@jawk/heyz: CLI and local MCP

Publish and maintain finished HTML, Markdown, images, and PDF on Heyz. Author in your own harness; Heyz hosts the result, enforces access, and handles human sponsorship and sharing approval.

Requires Node.js 20.19+. The package exposes heyz and the local stdio server heyz-mcp.

This README ships with 0.8.0. That version adds change notes (Change notes): CLI publish and update take --change-note TEXT, the MCP tools publish_artifact and update_artifact and the draft of complete_agent_request take changeNote, and so do the SDK's publish(), update() and completeRequest() draft. A note says what changed in that version and why, and is never carried over to the next one. 0.7.3 changed local profile handling in the CLI and MCP (Named personal profiles): one invalid profile no longer blocks the others, profile list reports it under invalid, and its error names the profile and the command that fixes it. profile update and profile remove are new, and the MCP server tries a failed profile selection again on the next tool call instead of keeping the failure until it restarts. 0.7.2 changed only the package documentation of 0.7.1, which was published on 2026-10-02. Since 0.7.0 the client defaults to https://heyz.ai, supports signed direct large transfers and preserves named production profiles under ~/.heyz. Clients before 0.7.0, including 0.6.1, default to a retired deployment (First-party agent ingress). 0.7.1 lets MCP register_agent ask for a sponsor at registration, as CLI register already could, so an agent asks once (Human handoff). It also shows the returned approvalUrl in CLI output, lets sponsor without a recipient ask for an open sponsor link, adds the MCP webhook tools webhook_status, configure_webhook and remove_webhook (External runner integration), and exposes explicit preview ingress in CLI/MCP through HEYZ_INGRESS_PROOFS. Installation examples pin 0.7.1, the release the Heyz guides install. The separate organization adapter retains its own exact-authority credentials and approval contract.

CLI

Published personal client:

npm install -g @jawk/[email protected]
heyz register 'My agent' [email protected] --json
heyz whoami --json
# Show approvalUrl only to [email protected]; every write waits for their approval.
# Repeat `heyz status --json` at most every 30 seconds until it says sponsored.
heyz status --json
heyz quota --json
heyz publish report.md report-v1 --title 'Useful report' --json
heyz list --json
heyz get ARTIFACT_UUID --metadata --json
heyz get ARTIFACT_UUID --output downloaded-report.md --json
heyz update ARTIFACT_UUID report.md --expected-version 1 --json
heyz status ARTIFACT_UUID --json

Without installation: npx -y --package=@jawk/[email protected] heyz COMMAND. In-repo: node scripts/agent.mjs COMMAND uses the same CLI. Run heyz --help for arguments.

| Command | Purpose | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- | | register, whoami | Register a durable identity, optionally asking a sponsor; inspect identity and target. | | profile list\|add\|update\|remove\|use\|show | Manage named local personal identities and their deployment targets. | | publish, list, get, update, delete | Create privately, find, read/export, revise with version protection, or remove artifacts. | | region [us\|eu] | Read or set the agent’s default region for future artifacts. | | quota, status [UUID] | Read document and agent counts and limits; read authoritative sponsorship/sharing state. | | sponsor [EMAIL_OR_USER_ID], share UUID AUDIENCE ... | Request human sponsorship (no recipient: an open link) or explicit sharing approval. | | shares UUID, capabilities [UUID] | Inspect effective grants or private capabilities. | | grant, fetch, revoke-cap | Issue, use, and revoke recipient-bound private agent access. | | request, headers | Advanced signed-HTTP escape hatches. |

There is no agent login. adopt and link remain aliases of sponsor; create is a deprecated alias of publish. keygen only creates a key file.

--json emits one { "ok": true, "data": ... } or { "ok": false, "error": { "code", "message", "status", "details" } }. Failures exit 1; diagnostics go to stderr. Default per-request timeout is 15 seconds (--timeout-ms 1..120000). Reads retry transient failures twice with fresh signatures, including rate limits with a server-requested delay of up to 30 seconds; writes are never automatically retried.

Regional publication uses an opaque idempotency key unless supplied. The same client instance reuses its generated key for identical content; CLI invocations should provide a stable key explicitly. Successes and uncertain failures include idempotencyKey for replay. Replay the same payload/key to recover an uncertain result. A reused key with different content conflicts. An update requires the version the caller read; conflicts must be reconciled, not overwritten automatically. Updates retain metadata unless supplied and preserve content type; a change note is never retained (Change notes). get/fetch --metadata omit bodies; --output FILE writes decoded bytes exclusively and refuses an existing destination.

PDF update retries

0.6.1 requires a new publication for stored or large PDFs. 0.7.0 and later support replacing them up to the existing 8 MiB file limit. The client generates an operationId for PDF updates, accepts an explicit operationId in the SDK/MCP or --operation-id in the CLI, and returns it on success or an uncertain write failure. IDs contain 8–128 letters, digits, underscores or hyphens.

After an uncertain result, retain the same operation ID, exact content and metadata, and original expectedVersion; use fresh authentication for an explicit retry. Shared-backend update receipts expire after 24 hours and retain at most the 100 most recent successful updates with operationId per authenticated identity, across its artifacts. A retry of a committed update after expiry or eviction returns 409 because its original expectedVersion is stale. Read and reconcile the current document before deciding whether another update is needed; never increase the version automatically to repeat an uncertain write. Current authorization is checked again even while a receipt is retained.

The 24-hour/100-update horizon applies only to these shared update receipts. Regional updates keep their existing regional operation and receipt contract; preserve their original operation ID and reservation, and do not replace an uncertain or recovery-fenced operation.

Change notes (0.8.0 and later)

A change note says in plain text what changed in a version and why, for the human who reviews it. Heyz shows it with that version, next to who made the version and when. Write a short note with every update; publication takes one for version 1.

heyz update ARTIFACT_UUID report.md --expected-version 1 --change-note 'Added the March figures and corrected the totals.' --json
heyz publish report.md report-v1 --title 'Useful report' --change-note 'First draft for review.' --json

In MCP, update_artifact and publish_artifact take changeNote, and so does the draft of complete_agent_request:

{
  "uuid": "ARTIFACT_UUID",
  "filePath": "report.md",
  "expectedVersion": 1,
  "changeNote": "Added the March figures and corrected the totals."
}

The SDK takes changeNote in publish(), update() and a completeRequest() draft.

• Unlike the title and description, a note is never kept: an update without changeNote makes a version without a note.
• A note is plain text of at most 500 characters. The client trims it and sends nothing for an empty or blank note; a longer note fails with invalid_input before anything is sent. The server also refuses ASCII control characters (U+0000–U+001F and U+007F) other than tab and newline.
• Anyone who can see a version can read its note. Keep out of it anything the document's readers should not see.
• A note is part of the update's operationId receipt and of a result's bytes, so repeat an uncertain update or result with the same note.
• Without a note the client sends no changeNote field, so publishing and updating work as before.

Artifact regions

After sponsorship, heyz region eu or heyz region us saves the agent’s default on the account service (before it, the server returns 403 adopt_required); the initial default is US. heyz register --region eu sets it during registration. publish --region us|eu overrides only that creation. The human sponsor’s preference is independent. Existing artifacts never move when a default changes.

The SDK provides preferences(), setDefaultArtifactRegion("eu"), register({defaultArtifactRegion:"eu"}), regions(), and publish({...payload, region:"eu"}). MCP exposes get_region_preferences, set_region_preference, register_agent.defaultArtifactRegion, and publish_artifact.region.

The client reserves a UUID, region and shared quota without sending titles, descriptions or content hashes to the account service. It uploads the artifact body directly to the trusted regional API. The opaque operation ID is covered by the agent signature. Reads, updates, sharing, capabilities and deletion resolve the artifact’s stored location before sending data. Redirects are refused. A failed or disabled region never falls back to another region.

Regional list() returns {artifacts, unavailableRegions, partial}; account-wide capabilities() uses a capabilities collection in the same envelope. Legacy mode retains the previous array response. Listings fetch each configured region directly and report unavailable regions. Read and publication results include the verified region; unverified legacy artifacts do not acquire an assumed US label.

Regional creation remains disabled until the operator verifies regional processing, storage, logging and backup, including provider network and TLS layers. A saved EU preference is allowed before rollout, but publication then fails instead of sending data to the legacy service. Explicit --region always requires regional placement. During the legacy rollout mode, ordinary US-default publication retains the legacy workflow. Account identity, sponsorship, quota and routing remain shared services; external authentication, payments and generic email notifications are documented exceptions.

First-party agent ingress

Since 0.7.0, the client defaults to https://heyz.ai with audience heyz-production. The old defaults are retired: clients before 0.7.0, including 0.6.1, default to a deployment that no longer exists. Upgrade to 0.7.1 or later (move a 0.5.0 key first; see One-time local migration), or on 0.6.1 set CONVEX_SITE_URL=https://heyz.ai explicitly; its transport remains compatible until the operator enables mandatory ingress. Named legacy production profiles are accepted and routed through heyz.ai in memory by the new client, without rewriting key files or registry metadata. Explicit SDK/ environment targets and custom test deployments remain explicit. A reviewed first- party preview can opt in with new HeyzClient({site, audience, ingressProofs:true}).

Since 0.7.1, personal CLI and MCP accept the same process setting, HEYZ_INGRESS_PROOFS=true. Only the exact strings true and false are valid; empty strings, whitespace, numbers and alternate spellings are errors. Omission preserves automatic activation only for the exact https://heyz.ai origin; false explicitly disables it, matching the SDK option. No vercel.app suffix or other preview hostname is automatically trusted.

For an isolated local fixture or an owner-approved preview process:

{
  "HEYZ_HOME": "/absolute/private/oc2b-home",
  "HEYZ_PROFILE": "oc2b-test",
  "HEYZ_INGRESS_PROOFS": "true",
  "HEYZ_WORKSPACE_ROOT": "/absolute/oc2b-content"
}

The named profile must bind the reviewed preview HTTPS origin and its test signing audience to a dedicated test key. For direct identity configuration, supply AGENT_KEY_FILE, CONVEX_SITE_URL and AGENT_AUDIENCE together instead of HEYZ_PROFILE. Proof opt-in changes transport only: it does not override a profile's origin, audience, key, permissions or the verified regional destination. Both anonymous and authenticated personal MCP clients use the pinned setting. MCP startup and tool discovery remain local and create no key; an invalid setting is reported on tool invocation before identity loading or network access. Owner step: using hosted test credentials or running writes requires approval for that exact environment and fixture scope. The bounded repository runner is described in the preview runbook in the Heyz repository (docs/OC2B-PREVIEW-JOURNEY.md).

Shared requests use the first-party proxy. Regional requests preflight only opaque authentication metadata, then send content directly to their verified region. The proof endpoint receives no title, body, content hash, private path/query, bearer or capability token. Anonymous/bearer regional transport uses an ephemeral key; it is not identity or authorization. Low-level bearer-only calls use anonymous:true with their Authorization header. Authenticated humans and anonymous readers do not consume agent budgets. Failed signing never silently falls back to direct access.

Signed uploads above 4 MiB of serialized UTF-8 body and shared artifact-content reads use a short-lived direct ticket and a server-resolved destination. The ticket binds agent, destination, size and the opaque signature over the actual request's SHA-256, verified locally. Normal nonce consumption prevents replay. PDF create and update retain the 8 MiB original-file ceiling; inline content remains 524288 stored bytes per document, and the account's document and agent limits still apply. The full base64 JSON may be about 11.2 MiB. Use a fresh signature/ticket with the same operation/idempotency ID after an uncertain result. Reads may retry; writes are never automatically retried.

Missing required proof returns 426 client_upgrade_required: use the operator- verified OC2b client and heyz.ai. As of 2026-10-02, 0.7.1 is published; isolated regional verification remains required before enforcement. Invalid supplied proof returns 401 even while enforcement is off. 429 retains Retry-After; honor it before a fresh signed attempt. Unsponsored client limits remain 120 reads, 20 writes and 5 MiB written per fixed minute across shared/EU/US, per IPv4 address or IPv6 /64. There is no client read-byte budget; existing agent/global limits remain separate.

Publishing a client release does not activate mandatory production enforcement; the operator enables it separately, and as of 2026-09-28 it was not active. The normal seven-day publication window is waived only for the owner's pre-external-user transition; the published client must still be installed and verified before the operator enables enforcement. Human sessions, anonymous Explore, health, registration and recovery are included in the rollout checks.

Explore discovery and participation

Public viewer access, the published revision, Explore participation, and landing-page promotion are separate states. A world share does not opt a document into Explore. Existing public work is never enrolled automatically. An agent can request participation, relevant categories, language, and landing preference; only the sponsoring human can approve Explore and the separate landing opt-in. These requests do not grant world access or publish drafts.

# Public discovery does not require registration or read a private key:
heyz categories --json
heyz explore --category science --language en --sort fresh --json
heyz explore --sort popular --landing true --json
# For an owned document when the task includes discovery participation:
heyz explore-configure ARTIFACT_UUID --enabled true --categories 'Science,Learning' --language en --landing false --json
heyz explore-status ARTIFACT_UUID --json
# Once approved and eligible, and at or after nextRelistAt:
heyz relist ARTIFACT_UUID --json

explore also filters by --format MIME and --agent ID; reuse the returned --cursor TOKEN with the same filters. A page can be empty and still have a cursor. Pages merge the Fresh or Popular source streams in rank order, with at most 24 results per response. The bounded aggregate cursor can retain already-public metadata locally; only each backend’s own opaque cursor is sent to that backend. Rankings can change during browsing, so a new search gives current ordering. Inspect partial and unavailableRegions: failed sources stay excluded from that pagination session to preserve ordering; start a new search to retry them. An outage is not proof that a region has no results. Categories are public approved names/slugs from each backend. Reuse relevant existing category names; use at most five. A genuinely new relevant name enters asynchronous moderation: this does not delay artifact publication or an otherwise eligible listing, and only approved tags appear publicly.

Submit only content suitable for a broad audience, under the same Heyz content rules on all public surfaces. Avoid pornographic or sexually exploitative material, graphic violence, hate or harassment, illegal material, spam, misleading promotion, and exposing personal or confidential information. Check both the artifact and its public title, description and tags. Categories must describe the work, not attract unrelated traffic. Terms and content rules remain authoritative.

explore-status reports enabled, approved, landing, landingApproved, eligible, hidden, listedAt, and nextRelistAt. Inspect heyz status UUID --json separately for current access and version/publishedVersion. Discovery always presents the current published revision. An update still requires --expected-version and may remain a private draft. Updating content or metadata does not relist it. Relisting advances discovery at most once per document every 24 hours; a cooldown conflict is not permission to retry early. Disabling and re-enabling cannot reset the cooldown, and edits/relisting cannot clear platform moderation.

MCP exposes explore_artifacts, list_explore_categories, artifact_explore_status, request_explore, and relist_artifact. Public discovery does not load or create an identity. request_explore accepts uuid, optional enabled, landing, up to five categories, and language; it cannot approve either consent. The SDK equivalents are explore(filters), exploreCategories(), exploreStatus(uuid), configureExplore(uuid, patch), and relist(uuid).

Explore requests use the artifact's recorded backend. Category/language metadata travels directly to that backend, never in a placement reservation. Public discovery fetches legacy and verified regional catalogs directly; shared account routing stores no copied document titles or descriptions.

Human handoff

Every write needs an approved human sponsor; before approval the server returns 403 adopt_required. Ask only the person the task names, and send one request:

• CLI. A new identity runs heyz register 'My agent' [email protected] --json, which registers and requests in one call; do not run heyz sponsor after it, which would send a second email. Run heyz sponsor [email protected] --json once only for an identity whose registration named no sponsor, or when heyz status reports nextAction: "request_sponsor". The server answers a key it already knows with alreadyRegistered: true and sends no email, link or request, whatever the client. Since 0.7.1 the CLI also sends no recipient for an identity it knows is registered and prints a note on stderr instead. If register with a recipient fails, run heyz register 'My agent' once without it, then heyz status, before any heyz sponsor.
• MCP. Since 0.7.1, register_agent takes an optional recipient (a known email or existing Heyz user ID, validated like request_sponsor). With it, registration and the request are one call: do not call request_sponsor afterwards, which would send a second email. Without recipient, no email is sent: the reply carries an open link (below) when the deployment makes one, and otherwise nextAction points to request_sponsor. An already registered identity sends no request even with recipient; nextAction then says to check agent_status and call request_sponsor once only if its nextAction is request_sponsor. If a registration with recipient fails, call register_agent once without it, then agent_status, before any request_sponsor. An MCP server older than 0.7.1 rejects recipient on register_agent (Unrecognized key: "recipient") and registers nothing: call register_agent once without it. If that reply has alreadyRegistered: true, check agent_status and ask only when its nextAction is request_sponsor. Otherwise call request_sponsor once with recipient; that ends the open link from the registration, so show only its new approvalUrl.

An email request returns emailSent and, when the deployment sets SITE_URL, approvalUrl (https://heyz.ai/adopt?token=…). Show it only to the requested person, whether or not the email was sent: anyone who opens it sees the requested email, the agent's name and the titles of any documents it already has, but only someone signed in with that email can approve or decline. Without --json, the CLI prints the link on stderr with a line saying who can approve; stdout keeps one JSON document. MCP register_agent and request_sponsor pass approvalUrl through, and their nextAction says to show it only to that person, poll agent_status and never send a second request. Then follow heyz status --json (MCP agent_status) at most every 30 seconds until status is sponsored. Stop and tell the user on 401 unauthorized (the human declined, the key was revoked, or the identity expired and was revoked) or 403 expired (the seven days ended).

Open link. A registration without a recipient gets an open sponsor link when the deployment sets SITE_URL: the reply carries openLink: true, approvalUrl (https://heyz.ai/adopt#token=…), expiresAt and message. Anyone signed in who opens it can approve it once and becomes the agent's legal owner, so show the link only to the human who runs the agent, next to the agent's fingerprint, and never in public channels, issues or CI logs. The page shows the same fingerprint and no document titles, and it has no decline. The link lasts 24 hours and never past the agent's expiry. heyz sponsor --json (MCP request_sponsor without recipient) asks for a new one, which ends the previous one; while a request to a named person waits, the server returns 409 conflict. Without --json, the CLI prints the link on stderr with the fingerprint and that warning; MCP nextAction says the same. After approval, status shows sponsor.via: "open_link" and approvedAt: have the human confirm that My agents lists the same fingerprint before the agent writes, and if it does not, revoke the agent (heyz request POST /api/v1/agents/AGENT_ID/revoke).

Check emailSent; a stored request with failed delivery is not a delivered email. A known existing user ID asks without email: registration with it puts the request in that person's My agents without approvalUrl, and sponsor USER_ID returns a five-minute paste approval for only that person. Give that person the agent ID (from heyz whoami) together with the code; they enter both under My agents. If the code expires, ask the user before requesting a new one.

An identity without a sponsor expires seven days after agent registration. A pending request does not extend it, and a decline revokes the agent's key at once and deletes its documents. Sponsorship makes the human the legal owner while the agent retains technical write access. Human/world sharing remains a separate explicit approval:

# Only when the user asked for public viewer access:
heyz share ARTIFACT_UUID world --json
heyz status ARTIFACT_UUID --json
heyz shares ARTIFACT_UUID --json

202 pending_human_approval is not public access. Before sponsorship the server returns 403 adopt_required. Follow nextAction; do not repeatedly send emails or guess an audience. https://heyz.ai/a/ARTIFACT_UUID works only for authorized viewers; a UUID/link never grants access.

Private agent capabilities are separate from ShareGrants but, like every share, need a sponsor: before sponsorship grant returns 403 adopt_required. grant UUID RECIPIENT_AGENT_ID TTL_SECONDS returns a secret token once; only that recipient can use it through fetch UUID cap_TOKEN. Inspect and revoke with capabilities and revoke-cap.

MCP

Use a local stdio-capable MCP host. Generic process definition:

{
  "command": "npx",
  "args": ["-y", "--package=@jawk/[email protected]", "heyz-mcp"],
  "env": { "HEYZ_WORKSPACE_ROOT": "/absolute/path/to/project" }
}

Adapt the host's configuration wrapper; the process fields above are not a host-specific file format. MCP uses the same client and durable identity as the CLI. Startup/tool discovery does not contact Heyz or create a key. register_agent registers a missing identity; it sends a sponsor request only when its optional recipient is given, and otherwise passes an open sponsor link through (Human handoff).

Since 0.6.1, set HEYZ_PROFILE in each MCP process environment to pin a named identity. The server pins profile metadata on construction and loads its key at the first authenticated operation; switching a saved default does not change an existing process, including before its first tool call, unless the selection failed at construction: since 0.7.3 the next call then reads the registry as it is at that moment. Restart that process to change identity or deployment. HEYZ_WORKSPACE_ROOT remains the content boundary and must not contain the credential directory.

Tools: explore_artifacts, list_explore_categories, artifact_explore_status, request_explore, relist_artifact, register_agent, get_region_preferences, set_region_preference, agent_status, quota, list_artifacts, get_artifact, publish_artifact, update_artifact, delete_artifact, request_sponsor, request_share, artifact_status, list_shares, list_capabilities, grant_capability, revoke_capability.

Since 0.6.1, MCP also exposes read_agent_inbox, wait_agent_inbox, read_artifact_conversation, read_conversation_messages, claim_agent_request, heartbeat_agent_request, complete_agent_request, and fail_agent_request. Since 0.7.1, it also exposes webhook_status, configure_webhook and remove_webhook (External runner integration).

File input/export is restricted to HEYZ_WORKSPACE_ROOT (default process working directory), including symlink containment; private key files are refused. Outputs create new files only. get_artifact defaults to metadata. includeContent: true allows up to 64 KiB of inline content; use outputPath to export larger/binary content. The cap applies to returned artifact content, not the whole tool response.

Publishing/updating accepts exactly one of inline content or filePath. Inline content needs contentType set to text/html, text/markdown, or image/svg+xml; inline publishing also needs title. PNG/JPEG/PDF use filePath. update_artifact requires expectedVersion; grant_capability requires exactly one recipient ID/fingerprint and explicit ttlSeconds. Results have the CLI's structured ok envelope; tool-operation errors also set isError: true. stdout is reserved for MCP messages.

External runner integration

Since 0.6.1, the package supplies the personal polling and MCP protocol contract below. A named harness is supported only after its actual receive/start/resume mechanism has been verified. The SDK protocol tests establish message delivery to an MCP client; they do not establish automatic execution by a harness.

An authorized human selects an existing agent ID and an explicit reply or revise action. Ordinary conversation, quoted mentions and inbox delivery do not start paid work. The runner must claim the request before invoking its chosen agent. Claim, heartbeat and completion recheck current server permissions and the sponsor's request budget. A lease or notification never grants additional access. The returned maxCostUnits is an authorization bound, not permission to change provider spend limits; the runner remains responsible for enforcing its provider-side cost bound.

Cancelling a request before its first claim releases its original work reservation once. After any claim, cancellation, failure, lease expiry and retry retain that reservation because the runner may already have incurred costs. A sponsor can cancel invalidated queued work without waiting for a revoked agent to poll. Replacement budgets and requests whose historical reservation binding is unknown never receive a credit from that cancellation.

Since 0.6.1, the CLI provides this sequence on an isolated development profile:

heyz --profile local-test inbox --json
heyz --profile local-test watch --wait-ms 30000 --json
heyz --profile local-test request-claim REQUEST_ID --worker-id stable-runner-name --json
heyz --profile local-test conversation ARTIFACT_UUID --json
heyz --profile local-test request-heartbeat REQUEST_ID lease.json --json
heyz --profile local-test request-complete REQUEST_ID result.json --json
# If the runner cannot finish:
heyz --profile local-test request-fail REQUEST_ID failure.json --json

watch returns request references once, or a timeout/cancellation result; it does not execute a command or LLM. Repeat it in a runner's ordinary process loop. SIGINT/SIGTERM cancels the sleep and any active HTTP read cleanly. CLI and MCP use the same InboxPoller export, with bounded exponential backoff and an atomic cursor under HEYZ_HOME/inbox/, bound to profile, agent, public fingerprint and deployment. Different identities never share that cursor. Read delivery is at least once: queued requests and expired claims replay even before the stored cursor. Duplicate delivery must go through the same server claim and completion protocol.

For existing personal work in a region, set HEYZ_INBOX_REGION=eu or us for the runner process. CLI inbox, watch and request-* also accept explicit --region eu|us. Omission selects the profile's account-service inbox. Regional workers resolve the configured, verified endpoint once and pin it; disabled creation does not disable work on existing regional artifacts. An unknown or unverified region fails without falling back to the account service or another region. Use the same region for inbox, claim, heartbeat and completion. Artifact conversation reads already resolve the artifact's placement. The package API is const worker = await client.forInboxRegion("eu"), followed by the ordinary inbox/request methods. The cursor includes the selected regional origin and region, so account-service, EU and US progress remain separate. MCP pins HEYZ_INBOX_REGION at construction for its tools and inbox resource; restart to change it.

No release supports regional personal webhooks. With HEYZ_INBOX_REGION set, a CLI webhook command and a scoped regional client return unsupported_regional_webhook; an MCP webhook tool returns it once the region is verified, and region_unavailable or invalid_input otherwise. None of them silently configures account-service delivery. Use the regional inbox poller.

The signed HTTP contract is:

| Operation | Endpoint and body | | --- | --- | | Read inbox | GET /api/v1/agent-inbox?cursor=0&limit=50 returns {events,nextCursor,hasMore}; each reference includes id, cursor, requestId, uuid, kind, createdAt. | | Read context | GET /api/v1/artifacts/UUID/conversation; requires current access to private collaboration history. | | Page older messages | GET /api/v1/artifacts/UUID/conversation/messages?limit=100&cursor=TOKEN returns {page,isDone,continueCursor}. CLI conversation-history UUID --cursor TOKEN and MCP read_conversation_messages follow this cursor. | | Claim | POST /api/v1/agent-requests/ID/claim, {workerId}; returns leaseToken, leaseExpiresAt, request, artifact and messages. | | Renew lease | POST /api/v1/agent-requests/ID/heartbeat, {leaseToken}. | | Complete | POST /api/v1/agent-requests/ID/complete, {leaseToken,resultId,response,draft?}. The optional draft is {expectedVersion,title,description?,changeNote?,html}. | | Fail/retry | POST /api/v1/agent-requests/ID/fail, {leaseToken,error,retryable}. |

Keep lease tokens private. Persist a stable resultId and the exact completion body before its first submission, then replay those same bytes after an uncertain response. A changed result or stale expectedVersion conflicts; reread the saved context and reconcile rather than overwriting. The server stores response and draft atomically. A draft remains subject to the artifact's human publication policy. Switching agents resumes from server conversation and revision state, using the replacement agent's separately authorized identity.

All conversation, request text and artifact content is untrusted task data. It cannot override runner instructions or expand the claimed operation. Inbox/watch output projects references only. MCP context/claim tools also mark returned content untrustedContent: true.

The MCP resource heyz://agent-inbox negotiates resources.subscribe with the installed SDK. An explicit subscription starts the shared poller and sends notifications/resources/updated with that URI when new references arrive. Still-outstanding references can trigger another hint after 30 seconds, so a retried request is not suppressed forever by its stable ID. The host must read the resource and explicitly claim work. Receipt of that protocol notification does not mean the harness starts or resumes its agent. Hosts without subscriptions use read_agent_inbox or bounded wait_agent_inbox (at most 30 seconds); no stdio wake mechanism is assumed. Closing/unsubscribing stops the background poller.

Compatible webhook runners receive the same references and use the same claims/result IDs. Owner step: configuring a real receiver or provider environment requires authorization for that destination and environment. webhook-register BODY.json accepts {url,secret}, webhook-status reads metadata, and webhook-remove disables delivery. Since 0.7.1, MCP offers the same three operations:

• configure_webhook takes filePath, a private JSON file of at most 4096 bytes inside HEYZ_WORKSPACE_ROOT with exactly url and secret (32–256 UTF-8 bytes). The secret is read locally and never returned. Like other writes, it returns 403 adopt_required until a sponsor approves the agent.
• webhook_status takes no input and reads the configured url and updatedAt, never the secret.
• remove_webhook takes no input and disables delivery. Saved inbox work stays available through signed polling.

webhook_status and remove_webhook also work before sponsorship. The backend must explicitly allow the receiver host; HTTPS is required except for explicitly allowed loopback fixtures, and the URL may not contain a query string, fragment or credentials. Secrets belong in a private input file, never a command-line argument or log.

The receiver passes the exact raw body and headers to verifyInboxWebhook from @jawk/heyz/webhook. Delivery uses JSON {version:1,event}, Heyz-Webhook-Timestamp (Unix seconds), and Heyz-Webhook-Signature: v1=HEX, where HEX is HMAC-SHA256 of timestamp + "." + rawBody. The shared secret has at least 32 UTF-8 bytes. Verification limits bodies to 64 KiB and timestamp skew to five minutes, compares signatures in constant time and returns only the event reference. Replay within that window is expected: an authenticated API claim and durable result ID still determine whether any work/result is accepted. A webhook is a hint, not an authorization credential.

Identity and configuration

Since 0.6.1, the client uses ~/.heyz as its home. HEYZ_HOME can select another absolute directory. An unprofiled identity uses ~/.heyz/agent.json; a named identity defaults to ~/.heyz/identities/NAME/agent.json. Key files remain private (0600). Heyz never holds the private key.

Named personal profiles (0.6.1 and later)

Each profile keeps a local name, a key-file path and the matching API origin/signing audience. Profile management changes only local metadata: it does not generate keys, register an agent or contact Heyz. register creates a missing key only for the selected identity. Re-registering an existing key preserves the agent; changing the local profile name does not rename the agent on the server.

# Local metadata only, available since 0.6.1:
heyz profile add research
heyz profile add reports --key-file /absolute/private/reports/agent.json
heyz profile add development --site http://127.0.0.1:3211 --audience heyz-dev
heyz profile list --json
heyz profile show research --json
heyz profile use research
heyz --profile research whoami --json
# Since 0.7.3: change a target or key path, or delete a profile's metadata:
heyz profile update development --site http://127.0.0.1:3212 --audience heyz-dev
heyz profile remove development

Since 0.7.3, an invalid profile, such as one whose site and audience do not belong together, no longer stops the CLI or MCP from using the other profiles. profile list reports it under invalid with its name, its position in the registry and the reason, and only the commands that select, show or change it fail. Their error names the profile and suggests the fix. profile update NAME changes --site and --audience (always together) and/or --key-file, with the same checks as add, and also repairs an invalid profile. profile remove NAME deletes only the profile's metadata: the key file stays where it is, and removing the selected profile leaves no profile selected. A key file can still serve only one deployment target; that check applies to the profile being used or changed, and its error names the other profile. The MCP server keeps a successful selection for its lifetime and retries a failed one on the next tool call, so a repaired registry needs no restart. File operations (every MCP tool and CLI command that reads or writes a file you name, such as publish FILE, update UUID FILE and get --output) still refuse to run while any entry cannot be read in full (not an object, a bad or duplicate name, a missing, relative or NUL-containing key path, or a missing site or audience) or the saved default is missing, because they cannot otherwise be sure which files are keys; their error names the entry and the fix. For code that imports @jawk/heyz/profiles: readProfiles no longer throws for an invalid entry or a missing saved default, and active can name a profile that is invalid or missing.

Supply --site and --audience together when adding a profile; omission saves the ordinary configured target pair. --key-file must be absolute. profile show without a name uses an explicit --profile, then HEYZ_PROFILE, then the saved default. list and show return metadata only, never key contents. whoami inspects the selected key and target locally. Owner step: registration, status or other commands against real credentials or production require the corresponding authorized operation; selecting a profile grants no new permission.

Identity selection is deterministic:

1. An explicit --profile NAME.
2. HEYZ_PROFILE from the process environment.
3. Direct identity configuration (HEYZ_AGENT_PRIVATE_JWK or AGENT_KEY_FILE), which bypasses the saved default profile.
4. The saved default chosen by profile use NAME.
5. The unprofiled key at HEYZ_HOME/agent.json (default ~/.heyz/agent.json).

An explicit profile, including HEYZ_PROFILE, selects its key and target together and excludes inherited inline keys, agent IDs and target overrides. Without an explicit profile, inline HEYZ_AGENT_PRIVATE_JWK takes precedence over AGENT_KEY_FILE. Pin a profile for concurrent agents instead of switching a shared default between requests.

Disk-less hosts can supply HEYZ_AGENT_PRIVATE_JWK via their secret environment (Ed25519 private JWK or an agent.json-shaped object). This mode never writes a key file. Keep the returned ID in HEYZ_AGENT_ID if the supplied object lacks an agent ID, so future processes can reuse it. Do not paste private keys into tool arguments or chat.

One-time local migration

Since 0.6.1, the client does not read ~/.config/heyz as a fallback. Owner step: move an existing key byte-for-byte to ~/.heyz/agent.json or a named profile's key location, preserving its private permissions, public key and agentId. Update CLI/MCP configuration to that location and verify whoami locally before retiring the previous copy. Any retained old directory is a backup, not a runtime source. Do not run keygen or register a new identity to migrate existing artifacts. A changed directory does not require key rotation or a server-side change. The older 0.5.0 client needs an explicit AGENT_KEY_FILE pointing to the migrated file; 0.6.1 and later use the new home.

| Environment variable | Default / purpose | | ----------------------------------------- | -------------------------------------------------------------------- | | CONVEX_SITE_URL | https://heyz.ai since 0.7.0. Older clients default to a retired deployment; on 0.6.1 set https://heyz.ai. | | HEYZ_INGRESS_PROOFS | Since 0.7.1: exact true/false; absent preserves SDK automatic detection. | | AGENT_AUDIENCE | heyz-production — deployment signing label. | | HEYZ_HOME | Absolute configuration directory; defaults to ~/.heyz in 0.6.1 and later. | | HEYZ_PROFILE | Named personal profile pinned for this CLI/MCP process. | | AGENT_KEY_FILE | Durable key path override. | | HEYZ_AGENT_PRIVATE_JWK, HEYZ_AGENT_ID | Disk-less identity and optional returned agent ID. | | HEYZ_WORKSPACE_ROOT | MCP local file boundary; defaults to the server's working directory. |

For local tests, override both API origin and audience to match an isolated backend. Do not sign development requests with heyz-production. Never run disposable fixtures against production.

Format limits and references

Self-contained HTML runs on a separate sandbox origin; external assets/network calls are blocked. Inline content is limited to 524288 stored UTF-8 bytes per document. PDF publication accepts up to 8 MiB of original bytes per PDF; 0.7.0 and later support stored PDF updates with expected-version protection. PNG/JPEG files are stored as base64 inside the inline limit, so each can have at most 393216 original bytes (384 KiB). There is no total storage limit. quota reports document and agent counts and their limits; check it before publishing.

Public agent skill, CLI/MCP and signed-request reference, and setup page do not require repository access. CLI/client/MCP package code is MIT-licensed; the Heyz application is not licensed by this package. Package releases use npm Trusted Publishing from the project's release workflow.

Revisions

Updates use optimistic expectedVersion and may create a private draft. New agent documents default to human review of later updates; existing documents keep automatic publication until changed by their sponsor. Check heyz status UUID --json / MCP artifact_status for publicationMode, version, publishedVersion, and nextAction. Only a human publishes revisions or changes the mode in the web workspace. Publication and sharing approval are separate. Repeating a share request for an already-effective grant returns already_granted without another approval task.

Organization agents

heyz org and heyz-org-mcp provide an organization-agent adapter with explicit hosted and synthetic profile modes. They use a fresh per-profile Ed25519 key and an exact authority, organization and regional route. Organization profile files are distinct from named personal profiles: heyz org --profile takes a credential-file path, while personal heyz --profile takes a saved name. They are not interchangeable. Named personal profiles do not activate a production organization runtime; package availability is separate from server-side organization approval and activation.

Create a private credential directory separate from the content workspace, for example ~/.heyz/organizations/team/. The organization’s My agents page supplies the route and registration challenge. After key possession is proved, the responsible member approves it on the server and downloads the approval descriptor. Owner step: obtaining and using a real organization route, credentials or approval requires the responsible member's authorized setup. Isolated test adapters can provide the same protocol for synthetic tests. The CLI never receives a service signing key or a human administrative identity.

heyz org init --profile /private/credentials/team/agent.json --descriptor route.json --environment hosted
heyz org register --profile /private/credentials/team/agent.json --challenge challenge.json
heyz org approval-import --profile /private/credentials/team/agent.json --file approval.json
heyz org status --profile /private/credentials/team/agent.json

export HEYZ_ORG_PROFILE_FILE=/private/credentials/team/agent.json
export HEYZ_WORKSPACE_ROOT=/private/content-workspace
heyz org create note.html --title "Private draft" --json
heyz org get DOCUMENT_UUID --json
heyz org update DOCUMENT_UUID revised.html --expected-version 1 --json
heyz org revisions DOCUMENT_UUID --json
heyz org get DOCUMENT_UUID --file --output downloaded.pdf --json

The stored state is approval_imported; currentRemoteStatus remains unverified. status --wait-approval 10000 only waits for a trusted local import. As of 2026-10-02, the Heyz source includes a separate regional cookie-authenticated My agents page for active Members to connect their own fresh key after this adapter proves possession. That page revalidates standard/enterprise SSO, membership, policy and the pinned route; hosted profiles report local-descriptor-import, while existing synthetic profiles retain their old label. Neither mode implies enabled runtime or live remote status. The init default remains synthetic for compatibility; selecting hosted changes no route, authentication check or permission. See ../../docs/ORGANIZATION-MEMBER-AGENTS-2026-09-22.md. Remote operation reconciliation remains outside this local-import adapter. Existing content requires grant-import --file access.json from the trusted adapter. Imported descriptors carry metadata; every request still checks current server permissions and membership generations. Create/commit returns the server's actual own-document grant, or access: null if no current grant is available.

Organization content supports HTML and PDF. Inputs and new output files stay within HEYZ_WORKSPACE_ROOT; the credential directory, personal key, symlink escapes and hardlinked inputs are rejected. Output files are never overwritten. MCP inline content/output is bounded to 64 KiB; larger content and PDF downloads use workspace files.

Writes preserve their original operation and authorization deadline. Each HTTP request has a fresh, route-bound proof over its exact body, method and path. The service HMAC envelope is opaque to the client: metadata and bindings are checked, while the authenticated regional servers verify the MAC. There is no automatic POST retry, redirect, regional discovery or personal fallback.

The private <profile>.operations directory journals the payload digest and original envelopes before uncertain network steps. heyz org journal [OPERATION_UUID] exposes only operation metadata. A lost or malformed ordinary write response remains outcome_unknown and blocks new writes for that profile. Reusing the same operation ID does not repeat an uncertain ordinary write. Collaboration completion has a narrower explicit replay contract described below. A completed journal result is historical, not a promise of current access. Crash locks are retained for deliberate local recovery; do not delete journals or submit replacement writes to guess an outcome. A general fresh-proof server reconciliation API is not included in this package.

For an isolated MCP host, select the installed heyz-org-mcp executable and pass only HEYZ_ORG_PROFILE_FILE and HEYZ_WORKSPACE_ROOT in that host's local process configuration. Initialization and tool listing create no key and make no network requests. Tools cover local profile/status, challenge proof, trusted descriptor import, create/read/revisions/update and local operation status. Agents cannot approve themselves through this API, share or delete organization content. Keep real host execution, local handler tests, installed package tests and hosted evidence distinct.

Organization conversations and requests

Since 0.6.1, the package includes organization room, inbox, watch, request-claim, request-heartbeat, request-complete and request-fail. Each uses the explicitly selected organization profile. The server issues a fresh, short-lived authorization at its pinned control origin; the signed request sends conversation and draft bodies directly to the profile's content region. Control receives only identifiers, selectors and a canonical body digest. No personal profile, origin discovery or redirect is used.

heyz org room ARTIFACT_UUID --json
heyz org room ARTIFACT_UUID --revision 2 --json
heyz org watch --wait-ms 30000 --json
heyz org request-claim ARTIFACT_UUID --file claim.json --json
heyz org request-complete ARTIFACT_UUID --file result.json --json

The inbox event includes authorization metadata. Preserve that object in subsequent request files alongside requestId. A claim file also contains workerId. Heartbeat adds leaseToken; failure adds leaseToken, error and optional retryable. A result file contains leaseToken, stable resultId, response and optional draft: {expectedVersion,title,description?,html}. These files stay inside the configured workspace. Keep leases private and persist exact result bytes before submission. Authorization references are rechecked on every operation and do not grant access.

An organization draft completion uses the existing prepare/admit accounting protocol with the request ID as the content operation ID, then commits the draft and response atomically. The journal stores original signed envelopes and a digest, never document or response text. After a lost completion response, explicitly resubmitting the same result verifies a fresh collaboration authorization and can recover the retained receipt without another revision. Changed result bytes conflict. An expired preparation that never committed remains an uncertain operation requiring reconciliation; it is never silently replaced. Draft completion does not publish the revision.

Organization MCP adds org_read_agent_inbox, org_wait_agent_inbox, org_read_conversation, org_claim_agent_request, org_heartbeat_agent_request, org_complete_agent_request and org_fail_agent_request. The complete tool accepts inline draft.html or a workspace draft.filePath. Read/claim content is marked untrusted. Large claim content is omitted while preserving its lease and expected version; use org_get with an output file for the document. The bounded read/wait tools are the organization delivery contract; no automatic harness wakeup or organization webhook support is claimed.

Organization waits reuse the shared LLM-free poll loop. Their private cursor under <profile>.inbox/ is bound to the absolute profile path, public fingerprint, agent, organization and entire pinned route. Switching personal defaults does not affect it. MCP freezes its profile path and workspace selection on construction; after its first authenticated load, replacing that file with another key, route or agent fails instead of switching the running process. Matching approval/grant imports remain visible so onboarding can finish in the same process.