@ziggs-ai/api-client 0.4.0 → 0.6.0

package/dist/capabilities/links.js

@@ -1,9 +1,33 @@
-import { createAgreement, claimAgreement, listAgreements, revokeAgreement, } from '../http/AgreementClient.js';
+import { createAgreement, listAgreements } from '../http/AgreementClient.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
+/** Public Streamable-HTTP MCP endpoint; OAuth is discovered from it (RFC 9728). */
+const ZIGGS_MCP_URL = 'https://mcp.ziggsai.com/mcp';
 function webAppOrigin(env) {
     return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
 }
+/**
+ * The second form an invite travels in: text the recipient pastes into their
+ * own assistant, which then connects itself and claims the invite. The claim
+ * URL alone only helps someone who already has Ziggs and an assistant wired
+ * up, so hand the caller both and let it pick per recipient.
+ */
+function invitePasteText(agreementId, claimUrl) {
+    return [
+        'Connect me to Ziggs and accept this agent link invite.',
+        '',
+        `1. Add this MCP server: ${ZIGGS_MCP_URL}`,
+        '   It speaks Streamable HTTP and uses OAuth — pasting the URL is enough,',
+        '   but I may need to approve a consent screen in my browser.',
+        `2. Once connected, call the tool ziggs_agreement_claim with agreementId "${agreementId}".`,
+        '3. Then tell me who I am linked with, and what they can and cannot see.',
+        '',
+        'If you cannot add MCP servers yourself, tell me exactly where to paste that',
+        "URL in my assistant's settings, then continue from step 2.",
+        '',
+        `Invite link (if you need it in a browser instead): ${claimUrl}`,
+    ].join('\n');
+}
 /**
  * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
  * block, approvals array, and Mongo internals are noise on a trust
@@ -28,106 +52,73 @@ export function linkSummary(a) {
 /** A link is reach-only — the follow-up move differs by surface tool names. */
 export function linkIsReachOnly(env) {
     return env.surface === 'mcp'
-        ? 'A link is reach-only. Open a chat with the peer (ziggs_open_conversation, participantId = peer agent id) and grant it chat access with ziggs_issue_grant, or share a slice of a grant you hold with ziggs_delegate_grant, before reading context.'
+        ? 'A link is reach-only. Open a chat with the peer (ziggs_chat_open, participantId = peer agent id) and grant it chat access with ziggs_context_issue_grant, or share a slice of a grant you hold with ziggs_context_delegate, before reading context.'
         : 'A link is reach-only: it does not grant context. Share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one, before reading.';
 }
 const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
-export const requestLinkCapability = {
-    key: 'request_link',
-    names: { sdk: 'request_link', mcp: 'ziggs_request_link' },
+/**
+ * Seat ceiling for one invite. ⚠️ SYNC: backend
+ * src/agreements/agreements.service.ts MAX_LINK_INVITE_CLAIMS — the backend
+ * rejects anything past it; this is only so the tool description says the
+ * limit instead of letting an agent discover it by getting a 400.
+ */
+const MAX_LINK_INVITE_CLAIMS = 25;
+// ZIG-1021/1022 — the link rail shrank to two tools. Links are agreements, so
+// the agreement verbs carry the rest: request a direct link with
+// agreement_propose (engagementKind 'link', proposedTo = the agent id), claim
+// an invite with agreement_claim, end a link with agreement_revoke.
+export const createLinkInviteCapability = {
+    key: 'link_create_invite',
+    names: { sdk: 'link_create_invite', mcp: 'ziggs_link_create_invite' },
     descriptions: {
-        sdk: 'Request a bilateral trust link with another agent before cross-org reach (party-to-party, NOT a third-party service connection — that is the connection rail). A link is just an agreement (engagementKind "link"). The target OWNER must approve it before unpublished delegates can message each other.',
-        mcp: 'Request a bilateral trust link with another agent before cross-org reach (party-to-party, NOT a third-party service connection — see ziggs_list_my_connections for that). A link is just an agreement (POST /agreements {engagementKind:"link"}). The target OWNER must approve it (via ziggs_respond_to_agreement) before unpublished delegates can message each other.',
+        sdk: "Create a shareable OPEN link invite (bilateral agent-to-agent trust) when you do NOT have the counterparty's agent id (e.g. connecting across orgs). Creates an open link agreement proposed to everyone; the recipient forms the link by claiming the returned inviteId with agreement_claim. Set maxClaims to let several people claim the same link — each gets their own separate connection. When you DO have the agent id, propose the link directly instead: agreement_propose with engagementKind \"link\" and proposedTo = that id.",
+        mcp: 'Create a shareable OPEN link invite (bilateral agent-to-agent trust, NOT a third-party service connection — see ziggs_connection_list for that) when you do NOT have the counterparty\'s agent id (e.g. connecting across orgs). Creates an open link agreement (POST /agreements {engagementKind:"link"}, proposedTo:"everyone"). Share the returned inviteId (agreementId) out-of-band; the recipient forms the link by calling ziggs_agreement_claim — neither side pastes an agent id. Set maxClaims to share ONE link with several people; each claimer gets their own separate connection, not a group. Revoke via ziggs_agreement_revoke to disable. When you DO have the agent id, propose the link directly instead: ziggs_agreement_propose with engagementKind "link" and proposedTo = that id.',
     },
     annotation: 'write',
     params: {
-        providerId: {
-            type: 'string',
-            required: true,
-            description: 'Bare agent id to link with (the target delegate). Use agent search or a known delegate id — do not guess.',
-        },
         message: {
             type: 'string',
-            description: 'Optional note shown to the counterparty human on approval (agreement description)',
+            description: 'Optional note shown to whoever opens the invite (agreement description)',
+        },
+        maxClaims: {
+            type: 'number',
+            description: `How many people may claim this one link (default 1, max ${MAX_LINK_INVITE_CLAIMS}). Each claimer forms their own separate connection with you — this does not create a group.`,
         },
     },
     needsAgentId: true,
     handler: async (args, env) => {
+        const maxClaims = args['maxClaims'];
         const { agreement } = await createAgreement({
             engagementKind: 'link',
-            providerId: args['providerId'],
             description: args['message'],
+            ...(maxClaims == null ? {} : { maxClaims }),
         }, fullCreds(env));
-        return {
-            status: 'pending',
-            message: env.surface === 'mcp'
-                ? 'Link agreement created — the counterparty owner must approve (ziggs_respond_to_agreement) before cross-org reach. Surface pending state to the human.'
-                : 'Link agreement created — the counterparty owner must approve (agreement_respond on their side) before cross-org reach. Surface pending state to your principal.',
-            agreement: linkSummary(agreement),
-        };
-    },
-    sdkOptions: { isAgreementCreation: true },
-};
-export const createLinkInviteCapability = {
-    key: 'create_link_invite',
-    names: { sdk: 'create_link_invite', mcp: 'ziggs_create_link_invite' },
-    descriptions: {
-        sdk: "Create a shareable OPEN link invite (bilateral agent-to-agent trust) when you do NOT have the counterparty's agent id (e.g. connecting across orgs). Creates an open link agreement proposed to everyone; the recipient forms the link by claiming the returned inviteId.",
-        mcp: 'Create a shareable OPEN link invite (bilateral agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) when you do NOT have the counterparty\'s agent id (e.g. connecting across orgs). Creates an open link agreement (POST /agreements {engagementKind:"link"}, proposedTo:"everyone"). Share the returned inviteId (agreementId) out-of-band; the recipient forms the link by calling ziggs_claim_link_invite — neither side pastes an agent id. Revoke via ziggs_revoke_link to disable.',
-    },
-    annotation: 'write',
-    params: {
-        message: {
-            type: 'string',
-            description: 'Optional note shown to whoever opens the invite (agreement description)',
-        },
-    },
-    needsAgentId: true,
-    handler: async (args, env) => {
-        const { agreement } = await createAgreement({ engagementKind: 'link', description: args['message'] }, fullCreds(env));
+        const claimUrl = `${webAppOrigin(env)}/app/link-invites/${agreement.agreementId}`;
+        const seats = agreement.linkInvite?.maxClaims ?? 1;
+        const seatNote = seats > 1
+            ? `valid 7 days and claimable by up to ${seats} people (each gets their own separate connection — not a group)`
+            : 'single-use and valid 7 days';
         return {
             status: 'open',
             inviteId: agreement.agreementId,
-            claimUrl: `${webAppOrigin(env)}/app/link-invites/${agreement.agreementId}`,
+            claimUrl,
+            maxClaims: seats,
+            seatsRemaining: seats - (agreement.linkInvite?.claimsUsed ?? 0),
+            pasteText: invitePasteText(agreement.agreementId, claimUrl),
             message: env.surface === 'mcp'
-                ? 'Open link invite created. Share claimUrl with the counterparty — they open it in the Ziggs web app to claim and activate the link. No agent id needed on either side.'
-                : 'Open link invite created. Share claimUrl (or the inviteId) with the counterparty — they claim it in the Ziggs web app or via their claim_link_invite tool. No agent id needed on either side. Revoke with revoke_link to disable.',
+                ? `Open link invite created, ${seatNote}. Give the human BOTH forms and say which is which: claimUrl for a recipient who already uses Ziggs, pasteText for one who has an AI assistant but no Ziggs account — pasting it makes their assistant connect and claim the invite itself. A recipient with no Ziggs account can sign up straight from the link; no beta code needed. No agent id needed on either side.`
+                : `Open link invite created, ${seatNote}. Share claimUrl with a counterparty who already uses Ziggs, or pasteText with one who has an assistant but no Ziggs account yet — their assistant connects and claims it. A recipient with no Ziggs account can sign up straight from the link; no beta code needed. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
             agreement: linkSummary(agreement),
         };
     },
     sdkOptions: { isAgreementCreation: true },
 };
-export const claimLinkInviteCapability = {
-    key: 'claim_link_invite',
-    names: { sdk: 'claim_link_invite', mcp: 'ziggs_claim_link_invite' },
-    descriptions: {
-        sdk: 'Claim an open link invite by its id to form a bilateral link. You become the counterparty and the link activates immediately (cross-org reach). You cannot claim your own invite.',
-        mcp: 'Claim an open link invite by its id to form a bilateral link (agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) (POST /agreements/:id/claim). You become the counterparty and the link activates immediately (cross-org reach + bilateral context grants). You cannot claim your own invite.',
-    },
-    annotation: 'write',
-    params: {
-        agreementId: {
-            type: 'string',
-            required: true,
-            description: 'The invite id (agreementId) shared by the issuer',
-        },
-    },
-    needsAgentId: true,
-    handler: async (args, env) => {
-        const { agreement } = await claimAgreement(args['agreementId'], fullCreds(env));
-        return {
-            status: 'linked',
-            message: `Link invite claimed — you are now linked. ${linkIsReachOnly(env)}`,
-            agreement: linkSummary(agreement),
-        };
-    },
-};
 export const listLinksCapability = {
-    key: 'list_links',
-    names: { sdk: 'list_links', mcp: 'ziggs_list_links' },
+    key: 'link_list',
+    names: { sdk: 'link_list', mcp: 'ziggs_link_list' },
     descriptions: {
-        sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties.',
-        mcp: 'List link agreements for this delegate — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_list_my_connections for those) (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner). Approve pending links via ziggs_respond_to_agreement.',
+        sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties. Request a new link with agreement_propose (engagementKind "link"), or link_create_invite when you lack the agent id; end one with agreement_revoke.',
+        mcp: 'List link agreements for this delegate — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_connection_list for those) (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner). Approve pending links via ziggs_agreement_respond; request a new one with ziggs_agreement_propose (engagementKind "link"), or ziggs_link_create_invite when you lack the agent id; end one with ziggs_agreement_revoke.',
     },
     annotation: 'read-only',
     params: {
@@ -158,36 +149,7 @@ export const listLinksCapability = {
     },
     sdkOptions: { isGenericFallback: true },
 };
-export const revokeLinkCapability = {
-    key: 'revoke_link',
-    names: { sdk: 'revoke_link', mcp: 'ziggs_revoke_link' },
-    descriptions: {
-        sdk: 'Revoke a bilateral link agreement (DELETE /agreements/:agreementId). Either party may revoke; cross-org reach ends immediately. For non-link agreements (hire/service/quest), use agreement_revoke — same endpoint, different messaging.',
-        mcp: 'Revoke a bilateral link agreement — agent-to-agent trust, NOT a third-party service connection (DELETE /agreements/:agreementId). Either party may revoke; cross-org reach ends immediately. For non-link agreements (hire/service/quest), use ziggs_revoke_agreement — same endpoint, different messaging.',
-    },
-    annotation: 'destructive',
-    params: {
-        agreementId: {
-            type: 'string',
-            required: true,
-            description: 'agreementId of the link agreement (from the link lister)',
-        },
-    },
-    needsAgentId: true,
-    handler: async (args, env) => {
-        const result = await revokeAgreement(args['agreementId'], fullCreds(env));
-        return {
-            status: 'revoked',
-            message: 'Link revoked — unpublished cross-org reach to this peer is blocked again.',
-            agreementId: args['agreementId'],
-            agreement: result.agreement ? linkSummary(result.agreement) : null,
-        };
-    },
-};
 export const LINK_CAPABILITIES = [
-    requestLinkCapability,
     createLinkInviteCapability,
-    claimLinkInviteCapability,
     listLinksCapability,
-    revokeLinkCapability,
 ];

package/dist/capabilities/marketplace.d.ts

@@ -0,0 +1,8 @@
+import { type CapabilityDefinition } from './types.js';
+/**
+ * ZIG-1023 — the marketplace read on both surfaces. Publishing and claiming
+ * ride the agreement grammar (propose-with-audience / agreement_claim); this
+ * is the browse that hands you the agreementIds those verbs need.
+ */
+export declare const marketplaceViewCapability: CapabilityDefinition;
+export declare const MARKETPLACE_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/marketplace.js

@@ -0,0 +1,55 @@
+import { pullOffers, pullQuests } from '../http/MarketplaceClient.js';
+import { fullCreds } from './types.js';
+const VIEW_KINDS = ['all', 'quests', 'offers'];
+function publishHint(env) {
+    const propose = env.surface === 'mcp' ? 'ziggs_agreement_propose' : 'agreement_propose';
+    const claim = env.surface === 'mcp' ? 'ziggs_agreement_claim' : 'agreement_claim';
+    return (`Claim any row with ${claim} (agreementId). Publish your own with ${propose}: ` +
+        `proposedTo "everyone" or "org" with no providerId broadcasts a quest (claimer works, you pay); ` +
+        `the same with providerId = your own id publishes a standing offer (you work, claimer pays).`);
+}
+/**
+ * ZIG-1023 — the marketplace read on both surfaces. Publishing and claiming
+ * ride the agreement grammar (propose-with-audience / agreement_claim); this
+ * is the browse that hands you the agreementIds those verbs need.
+ */
+export const marketplaceViewCapability = {
+    key: 'marketplace_view',
+    names: { sdk: 'marketplace_view', mcp: 'ziggs_marketplace_view' },
+    descriptions: {
+        sdk: 'Browse the open marketplace: quests (work buyers broadcast — you would do the work) and standing offers (services sellers broadcast — you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with agreement_claim; publish your own via agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a quest).',
+        mcp: 'Browse the open marketplace: quests (work buyers broadcast — you would do the work) and standing offers (services sellers broadcast — you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with ziggs_agreement_claim; publish your own via ziggs_agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a quest).',
+    },
+    annotation: 'read-only',
+    params: {
+        kind: {
+            type: 'string',
+            enum: VIEW_KINDS,
+            description: 'all (default) | quests | offers',
+        },
+        limit: { type: 'number', description: 'Max rows per kind (default 20)' },
+        since: { type: 'string', description: 'ISO timestamp — only rows published after this' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const kind = args['kind'] ?? 'all';
+        if (!VIEW_KINDS.includes(kind)) {
+            throw new Error(`kind must be one of ${VIEW_KINDS.join(', ')}`);
+        }
+        const creds = fullCreds(env);
+        const options = {
+            limit: typeof args['limit'] === 'number' ? args['limit'] : 20,
+            ...(args['since'] ? { since: args['since'] } : {}),
+        };
+        const [quests, offers] = await Promise.all([
+            kind === 'offers' ? Promise.resolve([]) : pullQuests(options, creds),
+            kind === 'quests' ? Promise.resolve([]) : pullOffers(options, creds),
+        ]);
+        return {
+            ...(kind !== 'offers' ? { quests, questCount: quests.length } : {}),
+            ...(kind !== 'quests' ? { offers, offerCount: offers.length } : {}),
+            nextSteps: publishHint(env),
+        };
+    },
+};
+export const MARKETPLACE_CAPABILITIES = [marketplaceViewCapability];

package/dist/capabilities/payments.js

@@ -84,7 +84,7 @@ export const paymentTransferCapability = {
     names: { sdk: 'payment_transfer', mcp: 'ziggs_payment_transfer' },
     descriptions: {
         sdk: 'Transfer funds to another wallet. Amounts are integer cents. Transfers above the wallet owner\'s policy pause with status "approval_required" — wait inline with payment_wait_for_approval when you expect a quick decision.',
-        mcp: 'Transfer funds to another wallet. Amounts are integer cents. As a delegate you spend under a payment grant the wallet owner issued (paymentGrantId — find yours via ziggs_list_grants scopeKind=wallet). Transfers above the owner\'s policy pause with status "approval_required": the human approves on the wallet page (it also shows in ziggs_pending_decisions) — you can wait inline with ziggs_payment_wait_for_approval, and you must NEVER approve your own transfer.',
+        mcp: 'Transfer funds to another wallet. Amounts are integer cents. As a delegate you spend under a payment grant the wallet owner issued (paymentGrantId — find yours via ziggs_grant_list scopeKind=wallet). Transfers above the owner\'s policy pause with status "approval_required": the human approves on the wallet page (it also shows in ziggs_pending_decisions) — you can wait inline with ziggs_payment_wait_for_approval, and you must NEVER approve your own transfer.',
     },
     annotation: 'write',
     params: {
@@ -389,7 +389,7 @@ export const paymentRevokeGrantCapability = {
     },
 };
 // ZIG-893 — payment_list_grants stays retired; the wallet rail is part of the
-// unified list_grants capability (scopeKind: 'wallet'). Grant *mutations* stay
+// unified grant_list capability (scopeKind: 'wallet'). Grant *mutations* stay
 // on the payment rail above.
 export const PAYMENT_CAPABILITIES = [
     paymentBalanceCapability,

package/dist/http/AgreementClient.d.ts

@@ -14,6 +14,12 @@ export interface ProposeTerms {
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
+    /**
+     * How `price` reads. `total` (default) escrows one price for the whole
+     * engagement and pays at fulfillment; `per_task` is a RATE settled as each
+     * task completes (standing/open agreements only, and the default for a hire).
+     */
+    billing?: 'total' | 'per_task';
     agreementDescription?: string;
     parentAgreementId?: string;
     parentTaskId?: string;
@@ -148,6 +154,8 @@ export interface CreateAgreementBody {
     maxExecutions?: number;
     description?: string;
     engagementKind?: EngagementKind;
+    /** Link invites only: how many people may claim this one link. Default 1. */
+    maxClaims?: number;
     metadata?: Record<string, unknown>;
 }
 export declare function createAgreement(body: CreateAgreementBody, creds: Creds): Promise<{

package/dist/http/AgreementClient.js

@@ -125,18 +125,12 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
         throw new Error(`Agreement ${agreementId} not found`);
     }
     const proposedTo = agreement.parties?.proposedTo;
-    if (isBroadcastTarget(proposedTo)) {
-        if (action === 'reject') {
-            // ZIG-719: an open/broadcast proposal is offered to many via a sentinel
-            // `proposedTo` ('everyone' | 'org'), so there is no per-recipient party
-            // slot for one recipient to reject and nothing a single reject could
-            // change server-side. Returning the agreement here reported a fake
-            // success while the item stayed claimable. Fail honestly instead — the
-            // caller either claims it (action=approve → POST /claim) or ignores it.
-            throw new Error(`Agreement ${agreementId} is an open/broadcast proposal (proposedTo="${String(proposedTo)}") and cannot be rejected by a single recipient — it has no personal approval slot. Ignore it to pass on it, or use action=approve to claim it.`);
-        }
-        const { agreement: updated } = await claimAgreement(agreementId, creds);
-        return updated;
+    if (isBroadcastTarget(proposedTo) || isBroadcastTarget(agreement.parties?.payer)) {
+        // ZIG-1021: respond is approve/reject on DIRECT proposals only. An open
+        // broadcast (quest, standing offer, link invite) has no per-recipient
+        // approval slot — one recipient can neither approve nor reject it
+        // (ZIG-719); the move is to claim it, which has its own verb now.
+        throw new Error(`Agreement ${agreementId} is an open broadcast and has no personal approval slot — respond cannot ${action} it. Claim it with the claim tool (agreement_claim / ziggs_agreement_claim), or ignore it to pass.`);
     }
     const partyId = resolveMyPendingApprovalPartyId(agreement, {
         ownerUserId: opts.ownerUserId,

package/dist/http/ArtifactsClient.d.ts

@@ -62,8 +62,8 @@ export declare class ArtifactsClient {
      * ZIG-899 — the deliberate-record variant: a deliverable the model chose to
      * record must fail loudly and hand back the artifactId, unlike `write`'s
      * soft-fail breadcrumb contract. This is the one wire call for both agent
-     * surfaces (the SDK record_artifact tool and ziggs-mcp's
-     * ziggs_record_artifact).
+     * surfaces (the SDK artifact_record tool and ziggs-mcp's
+     * ziggs_artifact_record).
      */
     writeStrict(input: WriteArtifactInput): Promise<{
         artifactId?: string;

package/dist/http/ArtifactsClient.js

@@ -75,8 +75,8 @@ export class ArtifactsClient {
      * ZIG-899 — the deliberate-record variant: a deliverable the model chose to
      * record must fail loudly and hand back the artifactId, unlike `write`'s
      * soft-fail breadcrumb contract. This is the one wire call for both agent
-     * surfaces (the SDK record_artifact tool and ziggs-mcp's
-     * ziggs_record_artifact).
+     * surfaces (the SDK artifact_record tool and ziggs-mcp's
+     * ziggs_artifact_record).
      */
     async writeStrict(input) {
         if (!input.text || !input.text.trim()) {

package/dist/http/ChatClient.js

@@ -113,7 +113,7 @@ export async function sendChatMessage(input, creds) {
 export async function listMyChats(creds) {
     assertCreds(creds, 'list my chats');
     // ZIG-699 — empty array only for a genuine empty 200; any failure (non-2xx /
-    // network) throws so ziggs_list_chats reports a real error instead of "you
+    // network) throws so ziggs_chat_list reports a real error instead of "you
     // have no chats". Status stays whitespace-delimited for toolError classification.
     let res;
     try {

package/dist/http/ContextReadClient.js

@@ -1,5 +1,6 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { pollSurfaceError } from '../shared/rateLimit.js';
 /**
  * Protocol-first uniform context reads (ZIG-427).
  * Wraps `GET /context/read/:type` — one client, one envelope, four types.
@@ -49,7 +50,18 @@ export class ContextReadClient {
         const res = await fetch(url.toString(), { headers });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`ContextReadClient.read ${type} ${res.status} ${body.slice(0, 200)}`);
+            // Carry the status like `snapshot()` does, so callers can branch on it.
+            // A 403 here is a legitimate outcome, not a transport failure: addressing
+            // and authorisation are separate, so an agent can be told about mail it
+            // is not (or is no longer) allowed to open.
+            // ZIG-1019: a 429 carries the server's own wait; everything else keeps
+            // the plain status-tagged error callers already branch on.
+            if (res.status === 429) {
+                throw pollSurfaceError(`ContextReadClient.read ${type}`, res, body);
+            }
+            const err = new Error(`ContextReadClient.read ${type} ${res.status} ${body.slice(0, 200)}`);
+            err.status = res.status;
+            throw err;
         }
         return JSON.parse(body);
     }
@@ -82,6 +94,9 @@ export class ContextReadClient {
         const res = await fetch(url.toString(), { headers });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
+            if (res.status === 429) {
+                throw pollSurfaceError('ContextReadClient.snapshot', res, body);
+            }
             const err = new Error(`ContextReadClient.snapshot ${res.status} ${body.slice(0, 200)}`);
             err.status = res.status;
             throw err;