@ziggs-ai/api-client 0.5.0 → 0.6.1

package/dist/ConnectionManager.js

@@ -1,5 +1,6 @@
 import { InboxClient } from './http/InboxClient.js';
 import { runtimeLog } from './shared/runtimeLog.js';
+import { isRateLimited } from './shared/rateLimit.js';
 const OPERATOR_POLL_WAIT_SECONDS = 25;
 const POLL_BACKOFF_BASE_MS = 1_000;
 const POLL_BACKOFF_MAX_MS = 30_000;
@@ -99,6 +100,16 @@ export class ConnectionManager {
                 if (!this._polling)
                     break;
                 consecutiveErrors++;
+                // ZIG-1019: same rule as the per-agent loop — when the server throttles
+                // us it also says for how long, and retrying sooner just spends more of
+                // the budget we were told we are out of.
+                const throttleMs = isRateLimited(err) ? (err.retryAfterMs ?? 30_000) : null;
+                if (throttleMs !== null) {
+                    consecutiveErrors = 0;
+                    runtimeLog.warn('ConnectionManager', `operator poll throttled: ${err.message} — waiting ${Math.round(throttleMs)}ms as instructed`);
+                    await sleep(throttleMs);
+                    continue;
+                }
                 const backoff = Math.min(POLL_BACKOFF_MAX_MS, POLL_BACKOFF_BASE_MS * 2 ** (consecutiveErrors - 1));
                 const jitter = backoff * (0.5 + (consecutiveErrors % 7) / 14);
                 runtimeLog.warn('ConnectionManager', `operator poll failed (#${consecutiveErrors}): ${err.message} — retrying in ~${Math.round(jitter)}ms`);

package/dist/capabilities/agreements.d.ts

@@ -0,0 +1,8 @@
+import { type CapabilityDefinition } from './types.js';
+/**
+ * ZIG-1021 — the one claim verb. Quests, standing offers, and link invites
+ * are all open broadcasts; claiming any of them is this call. The respond
+ * tool no longer claims — it approves/rejects direct proposals only.
+ */
+export declare const agreementClaimCapability: CapabilityDefinition;
+export declare const AGREEMENT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/agreements.js

@@ -0,0 +1,45 @@
+import { claimOpenAgreement } from '../http/agreementFlows.js';
+import { linkIsReachOnly, linkSummary } from './links.js';
+import { fullCreds } from './types.js';
+/**
+ * ZIG-1021 — the one claim verb. Quests, standing offers, and link invites
+ * are all open broadcasts; claiming any of them is this call. The respond
+ * tool no longer claims — it approves/rejects direct proposals only.
+ */
+export const agreementClaimCapability = {
+    key: 'agreement_claim',
+    names: { sdk: 'agreement_claim', mcp: 'ziggs_agreement_claim' },
+    descriptions: {
+        sdk: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. Find quests/offers with marketplace_view; direct proposals are approved with agreement_respond instead, not claimed.',
+        mcp: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. Find quests/offers with ziggs_marketplace_view; direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
+    },
+    annotation: 'write',
+    params: {
+        agreementId: {
+            type: 'string',
+            required: true,
+            description: 'The open agreement to claim (quest / offer / link invite id)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env));
+        if (kind === 'link') {
+            return {
+                status: 'linked',
+                kind,
+                message: `Link invite claimed — you are now linked. ${linkIsReachOnly(env)}`,
+                agreement: linkSummary(agreement),
+            };
+        }
+        return {
+            status: 'claimed',
+            kind,
+            message: kind === 'offer'
+                ? 'Standing offer claimed — the publisher provides, your side pays. Spawn work under it with the task-create tool.'
+                : 'Quest claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
+            agreement,
+        };
+    },
+};
+export const AGREEMENT_CAPABILITIES = [agreementClaimCapability];

package/dist/capabilities/artifacts.js

@@ -3,12 +3,12 @@ import { fullCreds } from './types.js';
 /**
  * ZIG-560 teaching: name the result slot on the success path so an agent finds
  * the right move unaided — worded in each surface's task grammar (SDK
- * task_update carries the terminal result; MCP has ziggs_set_task_result).
+ * task_set_result carries the terminal result; MCP has ziggs_task_set_result).
  */
 function reportingHint(env, contentType, taskId) {
     const close = env.surface === 'mcp'
-        ? 'ziggs_set_task_result ({ summary, status, links })'
-        : 'task_update';
+        ? 'ziggs_task_set_result ({ summary, status, links })'
+        : 'task_set_result';
     if (contentType === 'result') {
         return taskId
             ? `Recorded as a task-bound result artifact. Close the task by setting its terminal result with ${close}.`
@@ -17,13 +17,13 @@ function reportingHint(env, contentType, taskId) {
     return `Reporting finished work? Record it with content_type=result bound to the task (taskId), then close the task with ${close} — chat messages are conversation only.`;
 }
 export const recordArtifactCapability = {
-    key: 'record_artifact',
-    names: { sdk: 'record_artifact', mcp: 'ziggs_record_artifact' },
+    key: 'artifact_record',
+    names: { sdk: 'artifact_record', mcp: 'ziggs_artifact_record' },
     descriptions: {
         sdk: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. For a finished deliverable, set content_type=result and pass taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
         mcp: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. ' +
             'For a finished deliverable, set content_type=result and pass taskId to bind it to the task. ' +
-            'Finished work is the task result — set it with ziggs_set_task_result; never report finished work as a chat message (chat is conversation only).',
+            'Finished work is the task result — set it with ziggs_task_set_result; never report finished work as a chat message (chat is conversation only).',
     },
     annotation: 'write',
     params: {

package/dist/capabilities/chat.d.ts

@@ -1,11 +1,11 @@
 import { type CapabilityDefinition } from './types.js';
 /**
- * ZIG-900 — the decided chat surface for agents: open_conversation only.
+ * ZIG-900 — the decided chat surface for agents: chat_open only.
  * There is deliberately NO chat-listing tool on the SDK: agents read context
  * only via held grants (ZIG-425) and chat membership auto-mints a chat grant
- * (ZIG-428/426), so "what chats can I see" is already answered by list_grants
+ * (ZIG-428/426), so "what chats can I see" is already answered by grant_list
  * scopeKind=chat (ZIG-626 rule). MCP keeps its rich session-UX lister
- * (ziggs_list_chats) for humans in Cursor/Claude.
+ * (ziggs_chat_list) for humans in Cursor/Claude.
  */
 export declare const openConversationCapability: CapabilityDefinition;
 export declare const CHAT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/chat.js

@@ -1,19 +1,19 @@
 import { openConversation } from '../http/ChatClient.js';
 import { fullCreds } from './types.js';
 /**
- * ZIG-900 — the decided chat surface for agents: open_conversation only.
+ * ZIG-900 — the decided chat surface for agents: chat_open only.
  * There is deliberately NO chat-listing tool on the SDK: agents read context
  * only via held grants (ZIG-425) and chat membership auto-mints a chat grant
- * (ZIG-428/426), so "what chats can I see" is already answered by list_grants
+ * (ZIG-428/426), so "what chats can I see" is already answered by grant_list
  * scopeKind=chat (ZIG-626 rule). MCP keeps its rich session-UX lister
- * (ziggs_list_chats) for humans in Cursor/Claude.
+ * (ziggs_chat_list) for humans in Cursor/Claude.
  */
 export const openConversationCapability = {
-    key: 'open_conversation',
-    names: { sdk: 'open_conversation', mcp: 'ziggs_open_conversation' },
+    key: 'chat_open',
+    names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
     descriptions: {
-        sdk: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, establish a link first — request_link (if you have its agent id) or create_link_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use list_grants scopeKind=chat.',
-        mcp: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, an unpublished delegate must establish a link first — call ziggs_request_link (if you have its agent id) or ziggs_create_link_invite (if you do not) and have it approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.',
+        sdk: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, establish a link first — agreement_propose with engagementKind "link" (if you have its agent id) or link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use grant_list scopeKind=chat.',
+        mcp: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, an unpublished delegate must establish a link first — ziggs_agreement_propose with engagementKind "link" (if you have its agent id) or ziggs_link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.',
     },
     annotation: 'write',
     params: {
@@ -28,7 +28,7 @@ export const openConversationCapability = {
         if (!args['participantId'])
             throw new Error('participantId is required');
         const { chatId } = await openConversation(args['participantId'], fullCreds(env));
-        const lister = env.surface === 'mcp' ? 'ziggs_list_grants' : 'list_grants';
+        const lister = env.surface === 'mcp' ? 'ziggs_grant_list' : 'grant_list';
         return {
             chatId,
             note: `Conversation is open (or reused). Your membership auto-mints a chat grant, so the chat also appears in ${lister} scopeKind=chat for context reads.`,

package/dist/capabilities/connections.js

@@ -10,11 +10,11 @@ export const connectionProxyCapability = {
     key: 'connection_proxy',
     names: { sdk: 'connection_proxy', mcp: 'ziggs_connection_proxy' },
     descriptions: {
-        sdk: "Use a stored connection (a third-party credential, e.g. the owner's GitHub/Jira) without ever seeing the credential. Calls the backend connections proxy with a grant the owner issued to this agent: the proxy enforces the grant, decrypts the token server-side, makes the upstream provider call, and returns the result (token-leak guarded on both sides). Provide connectionId, grantId, the provider action (e.g. repo:read), and an optional action-specific payload. Don't know connectionId/grantId yet? Use list_grants (scopeKind=connection) or connection_list_grants first.",
-        mcp: "Use a stored connection (a third-party credential, e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_list_links for that) without ever seeing the credential. " +
+        sdk: "Use a stored connection (a third-party credential, e.g. the owner's GitHub/Jira) without ever seeing the credential. Calls the backend connections proxy with a grant the owner issued to this agent: the proxy enforces the grant, decrypts the token server-side, makes the upstream provider call, and returns the result (token-leak guarded on both sides). Provide connectionId, grantId, the provider action (e.g. repo:read), and an optional action-specific payload. Don't know connectionId/grantId yet? Use grant_list (scopeKind=connection) or connection_list_grants first.",
+        mcp: "Use a stored connection (a third-party credential, e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_link_list for that) without ever seeing the credential. " +
             'Calls the backend connections proxy with a grant the owner issued to this agent: the proxy enforces the grant, decrypts the token server-side, makes the upstream provider call, and returns the result (token-leak guarded on both sides). ' +
             'Provide connectionId, grantId, the provider action (e.g. repo:read), and an optional action-specific payload. ' +
-            "Don't know connectionId/grantId yet? Call ziggs_list_my_connections first.",
+            "Don't know connectionId/grantId yet? Call ziggs_connection_list first.",
     },
     annotation: 'write',
     params: {
@@ -50,13 +50,13 @@ export const connectionProxyCapability = {
     },
 };
 export const requestConnectionCapability = {
-    key: 'request_connection',
-    names: { sdk: 'request_connection', mcp: 'ziggs_request_connection' },
+    key: 'connection_request',
+    names: { sdk: 'connection_request', mcp: 'ziggs_connection_request' },
     descriptions: {
         sdk: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement. On approval the server is connected (browser OAuth if needed) and you are granted the tools; use them via connection_proxy.',
         mcp: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
             'Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement (there is no MCP tool to approve it, so tell them to approve it in the chat). ' +
-            'On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_list_my_connections for use with ziggs_connection_proxy.',
+            'On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_connection_list for use with ziggs_connection_proxy.',
     },
     annotation: 'write',
     params: {
@@ -96,9 +96,9 @@ export const requestConnectionCapability = {
                 ...result,
                 note: env.surface === 'mcp'
                     ? 'A connection-consent card is now in the chat awaiting your principal. Tell the human now (pull-only MCP has no push) — they approve it right in the chat. ' +
-                        'Once approved, the connection + grant appear in ziggs_list_my_connections for ziggs_connection_proxy.'
+                        'Once approved, the connection + grant appear in ziggs_connection_list for ziggs_connection_proxy.'
                     : 'A connection-consent card is now in the chat awaiting your principal — they approve it right there (ZIG-798 flow). ' +
-                        'Once approved, the connection + grant appear in list_grants (scopeKind=connection) / connection_list_grants for connection_proxy.',
+                        'Once approved, the connection + grant appear in grant_list (scopeKind=connection) / connection_list_grants for connection_proxy.',
             };
         }
         catch (e) {

package/dist/capabilities/context.js

@@ -43,15 +43,15 @@ export async function resolveOrgScopeId(env, scopeId) {
     }
     if (scopeId.startsWith('org_'))
         return scopeId;
-    const lister = env.surface === 'mcp' ? 'ziggs_list_my_orgs' : 'your org list';
+    const lister = env.surface === 'mcp' ? 'ziggs_org_list' : 'your org list';
     throw new Error(`No org named "${scopeId}" in your memberships — use ${lister} to see them, or pass the org id.`);
 }
 export const contextReadCapability = {
     key: 'context_read',
-    names: { sdk: 'context_read', mcp: 'ziggs_read_context' },
+    names: { sdk: 'context_read', mcp: 'ziggs_context_read' },
     descriptions: {
-        sdk: 'Read the contents of a scope you already hold a grant for: messages | artifacts | agreements | tasks. Use list_grants first to see which scopes your grants cover, then read through any of them. Cursored; all access is grant-fenced server-side.',
-        mcp: 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id>. Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a `readPlan` with the next page and/or forward-delta call pre-filled (after=this page\'s latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist (your chats / tasks / agreements / grants / links), use the ziggs_list_* tools.',
+        sdk: 'Read the contents of a scope you already hold a grant for: messages | artifacts | agreements | tasks. Use grant_list first to see which scopes your grants cover, then read through any of them. Cursored; all access is grant-fenced server-side.',
+        mcp: 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id>. Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a `readPlan` with the next page and/or forward-delta call pre-filled (after=this page\'s latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.',
     },
     annotation: 'read-only',
     params: {
@@ -107,10 +107,10 @@ export const contextReadCapability = {
 };
 export const contextExpandReachCapability = {
     key: 'context_expand_reach',
-    names: { sdk: 'context_expand_reach', mcp: 'ziggs_expand_context' },
+    names: { sdk: 'context_expand_reach', mcp: 'ziggs_context_expand_reach' },
     descriptions: {
-        sdk: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. list_grants tells you that you hold e.g. org:acme or agreement:x; this returns the actual { chats, agreements } (ids + labels only, no content) that scope covers — feed an id to context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
-        mcp: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_list_grants tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_read_context (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
+        sdk: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the actual { chats, agreements } (ids + labels only, no content) that scope covers — feed an id to context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
+        mcp: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
     },
     annotation: 'read-only',
     params: {
@@ -131,10 +131,10 @@ export const contextExpandReachCapability = {
 };
 export const contextDiscoverGrantableCapability = {
     key: 'context_discover_grantable',
-    names: { sdk: 'context_discover_grantable', mcp: 'ziggs_discover_grantable' },
+    names: { sdk: 'context_discover_grantable', mcp: 'ziggs_context_discover_grantable' },
     descriptions: {
-        sdk: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of list_grants. Covers chats, agreements, and connections (type is one of "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you have an active agreement in, and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with list_grants (what you hold) and context_expand_reach (what a held grant covers).',
-        mcp: 'See what context EXISTS in your orgs that you CANNOT read yet — so you can ask for it instead of failing blind. Covers chats, agreements, and connections (type is "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only: { type, label, scopeRef, orgId } per item, never content, member names, tokens, or money. Bounded to orgs you have an active agreement in. To act on one, ask your human to grant it, or (if you hold a broader grant of your own) delegate via ziggs_delegate_grant using the scopeRef. Use ziggs_list_grants for what you already hold; this is what you lack.',
+        sdk: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of grant_list. Covers chats, agreements, and connections (type is one of "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you have an active agreement in, and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with grant_list (what you hold) and context_expand_reach (what a held grant covers).',
+        mcp: 'See what context EXISTS in your orgs that you CANNOT read yet — so you can ask for it instead of failing blind. Covers chats, agreements, and connections (type is "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only: { type, label, scopeRef, orgId } per item, never content, member names, tokens, or money. Bounded to orgs you have an active agreement in. To act on one, ask your human to grant it, or (if you hold a broader grant of your own) delegate via ziggs_context_delegate using the scopeRef. Use ziggs_grant_list for what you already hold; this is what you lack.',
     },
     annotation: 'read-only',
     params: {},
@@ -147,7 +147,7 @@ export const contextDiscoverGrantableCapability = {
 };
 export const contextDelegateCapability = {
     key: 'context_delegate',
-    names: { sdk: 'context_delegate', mcp: 'ziggs_delegate_grant' },
+    names: { sdk: 'context_delegate', mcp: 'ziggs_context_delegate' },
     descriptions: {
         sdk: 'Delegate a narrower child context grant (tighter scope, shorter expiry, or from-now). Holder-only. Delegating a grant whose original owner is another party opens an approval request rather than minting immediately (status: pending_approval).',
         mcp: 'Delegate a narrower child grant from one you hold (POST /context/grants/:id/delegate). Delegation only narrows scope/expiry/temporal — never broadens. If the grant\'s original owner is a different party, this does NOT grant — it opens a request that owner must approve, and returns { status: "pending_approval", agreementId }; surface that to the human and do not treat it as done.',

package/dist/capabilities/discovery.js

@@ -2,10 +2,10 @@ import { AgentSearchClient } from '../http/AgentSearchClient.js';
 import { fullCreds } from './types.js';
 export const agentSearchCapability = {
     key: 'agent_search',
-    names: { sdk: 'agent_search', mcp: 'ziggs_search_agents' },
+    names: { sdk: 'agent_search', mcp: 'ziggs_agent_search' },
     descriptions: {
         sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with. Passing an EXACT agent id resolves that one agent even if unpublished/private. Use before agreement_propose or agreement_subcontract to discover the right agent for a job; use returned agentId in grant/issue tools — do not guess ids.',
-        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with — so you can find a teammate or another user\'s delegate by name and ziggs_open_conversation with it directly, even if it is unpublished/offline and has never been in a chat with you. Passing an EXACT agent id resolves that one agent even if unpublished/private — use this for a delegate someone shared an id for, then ziggs_request_link if not yet linked. Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `linked`, or `managed`; it is not a blanket "published" label. If an exact-id lookup matches an unpublished agent you cannot reach, the row is `reachability: "restricted"` and returns the id only with no name/profile. Use returned agentId in grant/issue tools — do not guess ids.',
+        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with — so you can find a teammate or another user\'s delegate by name and ziggs_chat_open with it directly, even if it is unpublished/offline and has never been in a chat with you. Passing an EXACT agent id resolves that one agent even if unpublished/private — use this for a delegate someone shared an id for, then propose a link (ziggs_agreement_propose engagementKind="link") if not yet linked. Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `linked`, or `managed`; it is not a blanket "published" label. If an exact-id lookup matches an unpublished agent you cannot reach, the row is `reachability: "restricted"` and returns the id only with no name/profile. Use returned agentId in grant/issue tools — do not guess ids.',
     },
     annotation: 'read-only',
     params: {
@@ -48,10 +48,10 @@ export const agentSearchCapability = {
 };
 export const agentGetCapability = {
     key: 'agent_get',
-    names: { sdk: 'agent_get', mcp: 'ziggs_get_agent' },
+    names: { sdk: 'agent_get', mcp: 'ziggs_agent_get' },
     descriptions: {
         sdk: 'Fetch the full profile of a specific agent by ID — name, description, tags, capabilities, reachability, and reliability. Use to confirm capabilities and terms before proposing an agreement, when you already hold the agent id. An id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use agent_search.',
-        mcp: 'Fetch the full profile of ONE agent by its exact id (GET /agents/:id) — name, description, tags, capabilities, reachability, and reliability. Use to confirm a candidate before ziggs_propose_agreement / ziggs_request_link, when you already hold the agent id (from ziggs_search_agents, a grant, or an agreement party). Grant-scoped: an id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use ziggs_search_agents.',
+        mcp: 'Fetch the full profile of ONE agent by its exact id (GET /agents/:id) — name, description, tags, capabilities, reachability, and reliability. Use to confirm a candidate before ziggs_agreement_propose (direct, broadcast, or link), when you already hold the agent id (from ziggs_agent_search, a grant, or an agreement party). Grant-scoped: an id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use ziggs_agent_search.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/grants.js

@@ -29,11 +29,11 @@ function parseScopeKinds(raw) {
  * list is never presented as complete when the key can't read a rail.
  */
 export const listGrantsCapability = {
-    key: 'list_grants',
-    names: { sdk: 'list_grants', mcp: 'ziggs_list_grants' },
+    key: 'grant_list',
+    names: { sdk: 'grant_list', mcp: 'ziggs_grant_list' },
     descriptions: {
         sdk: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor. Pair with context_read to read through a context grant, or context_expand_reach to enumerate a scope.',
-        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. Pass a grantId to ziggs_read_context to pin a specific grant, or ziggs_expand_context to enumerate a scope.',
+        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. Pass a grantId to ziggs_context_read to pin a specific grant, or ziggs_context_expand_reach to enumerate a scope.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/index.d.ts

@@ -1,6 +1,8 @@
 export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, requestLinkCapability, createLinkInviteCapability, claimLinkInviteCapability, listLinksCapability, revokeLinkCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
+export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';

package/dist/capabilities/index.js

@@ -1,6 +1,8 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, requestLinkCapability, createLinkInviteCapability, claimLinkInviteCapability, listLinksCapability, revokeLinkCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
+export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';

package/dist/capabilities/links.d.ts

@@ -9,9 +9,6 @@ import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
 export declare function linkSummary(a: Agreement): Record<string, unknown>;
 /** A link is reach-only — the follow-up move differs by surface tool names. */
 export declare function linkIsReachOnly(env: CapabilityEnv): string;
-export declare const requestLinkCapability: CapabilityDefinition;
 export declare const createLinkInviteCapability: CapabilityDefinition;
-export declare const claimLinkInviteCapability: CapabilityDefinition;
 export declare const listLinksCapability: CapabilityDefinition;
-export declare const revokeLinkCapability: CapabilityDefinition;
 export declare const LINK_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/links.js

@@ -1,4 +1,4 @@
-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). */
@@ -19,7 +19,7 @@ function invitePasteText(agreementId, claimUrl) {
         `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_claim_link_invite with agreementId "${agreementId}".`,
+        `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',
@@ -52,108 +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,
+            maxClaims: seats,
+            seatsRemaining: seats - (agreement.linkInvite?.claimsUsed ?? 0),
             pasteText: invitePasteText(agreement.agreementId, claimUrl),
             message: env.surface === 'mcp'
-                ? 'Open link invite created, single-use and valid 7 days. 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. No agent id needed on either side.'
-                : 'Open link invite created, single-use and valid 7 days. 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. 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: {
@@ -184,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

@@ -154,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

@@ -36,6 +36,22 @@ export interface WriteArtifactInput {
  * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
  * they persist, are searchable, but are not visible to other chat parties.
  */
+/**
+ * ZIG-1032 — turn a runtime lane id into a scope the backend can accept.
+ *
+ * A task with no origin chat runs on the lane `agrn-<agreementId>` (see
+ * AgentHost.laneSessionIdForTask). That is a routing key, not a chat: no such
+ * chat row exists, so passing it as `chatId` made every breadcrumb and recorded
+ * thought on an agreement lane come back 403 "not authorized for this scope" —
+ * a fictional scope reading like an auth failure. The work is agreement-scoped,
+ * so say so; same rule ZIG-924 settled for deliverables.
+ */
+export declare const AGREEMENT_LANE_PREFIX = "agrn-";
+export declare function artifactScopeForSession(sessionId: string): {
+    chatId: string;
+} | {
+    agreementId: string;
+};
 export declare class ArtifactsClient {
     private readonly operatorKey;
     private readonly agentId?;
@@ -54,7 +70,7 @@ export declare class ArtifactsClient {
      * endpoint is updated to accept `visibility`, this falls back to logging
      * locally (operators can still wire their own sink).
      */
-    recordThought(chatId: string, text: string, opts?: {
+    recordThought(sessionId: string, text: string, opts?: {
         idempotencyKey?: string;
     }): Promise<void>;
     write(input: WriteArtifactInput): Promise<void>;
@@ -62,8 +78,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

@@ -7,6 +7,23 @@ import { buildOperatorHeaders } from './operatorHeaders.js';
  * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
  * they persist, are searchable, but are not visible to other chat parties.
  */
+/**
+ * ZIG-1032 — turn a runtime lane id into a scope the backend can accept.
+ *
+ * A task with no origin chat runs on the lane `agrn-<agreementId>` (see
+ * AgentHost.laneSessionIdForTask). That is a routing key, not a chat: no such
+ * chat row exists, so passing it as `chatId` made every breadcrumb and recorded
+ * thought on an agreement lane come back 403 "not authorized for this scope" —
+ * a fictional scope reading like an auth failure. The work is agreement-scoped,
+ * so say so; same rule ZIG-924 settled for deliverables.
+ */
+export const AGREEMENT_LANE_PREFIX = 'agrn-';
+export function artifactScopeForSession(sessionId) {
+    if (sessionId.startsWith(AGREEMENT_LANE_PREFIX)) {
+        return { agreementId: sessionId.slice(AGREEMENT_LANE_PREFIX.length) };
+    }
+    return { chatId: sessionId };
+}
 export class ArtifactsClient {
     operatorKey;
     agentId;
@@ -49,9 +66,10 @@ export class ArtifactsClient {
      * endpoint is updated to accept `visibility`, this falls back to logging
      * locally (operators can still wire their own sink).
      */
-    async recordThought(chatId, text, opts = {}) {
+    async recordThought(sessionId, text, opts = {}) {
+        // ZIG-1032: `sessionId` may be an agreement lane, which is not a chat.
         return this.write({
-            chatId,
+            ...artifactScopeForSession(sessionId),
             text,
             content_type: 'thought',
             visibility: 'agent-private',
@@ -75,8 +93,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.
@@ -53,6 +54,11 @@ export class ContextReadClient {
             // 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;
@@ -88,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;

package/dist/http/InboxClient.js

@@ -1,5 +1,6 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { pollSurfaceError } from '../shared/rateLimit.js';
 /**
  * The doorbell, not the door (ZIG-434): references addressed to this agent
  * since its last ack — never content. Flow: inbox → read → act → ack
@@ -45,7 +46,7 @@ export class InboxClient {
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`InboxClient.getInbox ${res.status} ${body.slice(0, 200)}`);
+            throw pollSurfaceError('InboxClient.getInbox', res, body);
         }
         return JSON.parse(body);
     }
@@ -81,7 +82,7 @@ export class InboxClient {
         }
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`InboxClient.getOperatorInbox ${res.status} ${body.slice(0, 200)}`);
+            throw pollSurfaceError('InboxClient.getOperatorInbox', res, body);
         }
         return JSON.parse(body);
     }
@@ -100,7 +101,7 @@ export class InboxClient {
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`InboxClient.ack ${res.status} ${body.slice(0, 200)}`);
+            throw pollSurfaceError('InboxClient.ack', res, body);
         }
         return JSON.parse(body);
     }

package/dist/http/agreementFlows.d.ts

@@ -0,0 +1,34 @@
+import { type ProposeTerms } from './AgreementClient.js';
+import { type Agreement, type Creds, type EngagementKind } from '../types.js';
+/**
+ * ZIG-1022 — one propose grammar. Direct, broadcast (quest and standing
+ * offer), and link proposals all flow through here; the surfaces expose a
+ * single propose tool instead of dedicated publish/request tools.
+ *
+ * Routing:
+ * - engagementKind 'link'                    → POST /agreements (link proposal / open invite)
+ * - proposedTo 'everyone' | 'org', providerId = self  → seller-broadcast standing offer
+ * - proposedTo 'everyone' | 'org', no providerId      → buyer-broadcast quest
+ * - anything else                            → direct proposal
+ */
+export interface UnifiedProposeInput extends ProposeTerms {
+    proposedTo: string;
+    /** Required on direct proposals; optional on broadcasts/links. */
+    chatId?: string;
+    engagementKind?: EngagementKind;
+}
+export type ProposeShape = 'direct' | 'quest' | 'offer' | 'link';
+export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds): Promise<{
+    agreement: Agreement;
+    shape: ProposeShape;
+}>;
+export type ClaimedKind = 'link' | 'offer' | 'quest';
+/**
+ * ZIG-1021 — one claim verb for any open broadcast. Fetches the agreement to
+ * route: link invites and quests claim through POST /agreements/:id/claim;
+ * standing offers (open payer side) through POST /marketplace/offers/claim.
+ */
+export declare function claimOpenAgreement(agreementId: string, creds: Creds): Promise<{
+    agreement: Agreement;
+    kind: ClaimedKind;
+}>;

package/dist/http/agreementFlows.js

@@ -0,0 +1,80 @@
+import { createAgreement, claimAgreement, getAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
+import { claimOffer, publishOffer } from './MarketplaceClient.js';
+import { isBroadcastTarget, } from '../types.js';
+export async function proposeUnified(input, creds) {
+    const { proposedTo, chatId, engagementKind, providerId, ...terms } = input;
+    if (!proposedTo)
+        throw new Error('proposedTo is required (a user/agent id, or "everyone"/"org" to broadcast)');
+    if (engagementKind === 'link') {
+        // A link is an agreement, proposed to one agent (providerId) or opened as
+        // an invite (proposedTo 'everyone'); no chat, no money.
+        const target = isBroadcastTarget(proposedTo) ? undefined : proposedTo;
+        const { agreement } = await createAgreement({
+            engagementKind: 'link',
+            ...(target ? { providerId: target } : {}),
+            ...(terms.description ? { description: terms.description } : {}),
+        }, creds);
+        return { agreement, shape: 'link' };
+    }
+    if (isBroadcastTarget(proposedTo)) {
+        const audience = proposedTo;
+        if (providerId && creds.agentId && providerId === creds.agentId) {
+            // Seller-broadcast: you work, the claimer pays — a standing offer.
+            const agreement = await publishOffer({
+                description: terms.description ?? '',
+                price: terms.price,
+                lifecycle: terms.lifecycle,
+                expiresAt: terms.expiresAt,
+                maxExecutions: terms.maxExecutions,
+                engagementKind: engagementKind,
+                billing: terms.billing,
+                audience,
+            }, creds);
+            return { agreement, shape: 'offer' };
+        }
+        if (providerId) {
+            throw new Error('On a broadcast, providerId must be your own agent id (a standing offer: you work, the claimer pays) or omitted (a quest: the claimer works, you pay). A third-party providerId is not broadcastable.');
+        }
+        // Buyer-broadcast: the claimer works, your side pays — an open quest.
+        const agreement = await proposeBroadcast({
+            ...terms,
+            chatId: chatId ?? '',
+            engagementKind: engagementKind ?? 'service',
+            audience,
+        }, creds);
+        return { agreement, shape: 'quest' };
+    }
+    if (!chatId)
+        throw new Error('chatId is required on a direct proposal');
+    const agreement = await proposeDirectTo({
+        ...terms,
+        proposedTo,
+        chatId,
+        providerId: providerId?.trim() || proposedTo,
+        engagementKind: engagementKind ?? 'service',
+    }, creds);
+    return { agreement, shape: 'direct' };
+}
+/**
+ * ZIG-1021 — one claim verb for any open broadcast. Fetches the agreement to
+ * route: link invites and quests claim through POST /agreements/:id/claim;
+ * standing offers (open payer side) through POST /marketplace/offers/claim.
+ */
+export async function claimOpenAgreement(agreementId, creds) {
+    if (!agreementId)
+        throw new Error('agreementId is required');
+    const existing = await getAgreement(agreementId, creds);
+    if (!existing)
+        throw new Error(`Agreement not found: ${agreementId}`);
+    if (existing.engagementKind === 'link') {
+        const { agreement } = await claimAgreement(agreementId, creds);
+        return { agreement, kind: 'link' };
+    }
+    if (isBroadcastTarget(existing.parties?.payer)) {
+        // Seller-broadcast standing offer: the open side is the payer — you buy.
+        const agreement = await claimOffer(agreementId, creds);
+        return { agreement, kind: 'offer' };
+    }
+    const { agreement } = await claimAgreement(agreementId, creds);
+    return { agreement, kind: 'quest' };
+}

package/dist/http/index.d.ts

@@ -1,10 +1,11 @@
 export * from './TaskClient.js';
 export * from './AgreementClient.js';
 export * from './MarketplaceClient.js';
+export * from './agreementFlows.js';
 export * from './ChatClient.js';
 export { MessagesClient } from './MessagesClient.js';
 export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
-export { ArtifactsClient } from './ArtifactsClient.js';
+export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
 export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.js';
 export { ContextReadClient } from './ContextReadClient.js';
 export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, } from './ContextReadClient.js';

package/dist/http/index.js

@@ -1,9 +1,12 @@
 export * from './TaskClient.js';
 export * from './AgreementClient.js';
 export * from './MarketplaceClient.js';
+export * from './agreementFlows.js';
 export * from './ChatClient.js';
 export { MessagesClient } from './MessagesClient.js';
-export { ArtifactsClient } from './ArtifactsClient.js';
+export { ArtifactsClient, 
+// ZIG-1032: agreement lanes are not chats — callers scope artifact writes with this.
+artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
 export { ContextReadClient } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export type { StartAgentOptions } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, ApiError, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/dist/index.js

@@ -5,3 +5,5 @@ export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+// ZIG-1019: retry loops need the server's own wait, not a guess.
+export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';

package/dist/shared/rateLimit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ZIG-1019 — a 429 is not a generic failure, it is an instruction with a
+ * deadline attached.
+ *
+ * The poll surface (`/inbox`, `/context/read`) is capped per actor, and every
+ * refused call still counts against that cap. A caller that retries on the
+ * usual exponential ladder (1s, 2s, 4s…) therefore spends its way deeper into
+ * the hole: observed live as an agent that could not read the conversation it
+ * had just been woken for, because its own retries kept the bucket empty.
+ *
+ * The server already says exactly how long to wait — `Retry-After`, or
+ * `RateLimit-Reset` from the standard headers. These helpers carry that number
+ * to whoever is doing the backing off.
+ */
+/** Thrown for HTTP 429 so a retry loop can wait the server's number, not its own. */
+export declare class RateLimitedError extends Error {
+    readonly status = 429;
+    /** How long the server said to wait. Null when it said nothing. */
+    readonly retryAfterMs: number | null;
+    constructor(message: string, retryAfterMs: number | null);
+}
+/** True for the error above — survives structured clones and re-wraps. */
+export declare function isRateLimited(err: unknown): err is {
+    retryAfterMs: number | null;
+};
+/**
+ * Read the wait out of a 429 response. `Retry-After` wins (it is the explicit
+ * one) and is accepted in both forms — delta-seconds or an HTTP date;
+ * `RateLimit-Reset` is the standard-headers fallback, in seconds. Capped so a
+ * bad header cannot park a loop for an hour, floored at a second so a `0` does
+ * not reproduce the hot-retry it is meant to stop.
+ */
+export declare function parseRetryAfterMs(headers: {
+    get(name: string): string | null;
+}): number | null;
+/**
+ * Build the error for a failed poll-surface response: 429s carry the server's
+ * wait, everything else stays an ordinary Error so existing handling is
+ * unchanged.
+ */
+export declare function pollSurfaceError(label: string, res: {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}, body: string): Error;

package/dist/shared/rateLimit.js

@@ -0,0 +1,73 @@
+/**
+ * ZIG-1019 — a 429 is not a generic failure, it is an instruction with a
+ * deadline attached.
+ *
+ * The poll surface (`/inbox`, `/context/read`) is capped per actor, and every
+ * refused call still counts against that cap. A caller that retries on the
+ * usual exponential ladder (1s, 2s, 4s…) therefore spends its way deeper into
+ * the hole: observed live as an agent that could not read the conversation it
+ * had just been woken for, because its own retries kept the bucket empty.
+ *
+ * The server already says exactly how long to wait — `Retry-After`, or
+ * `RateLimit-Reset` from the standard headers. These helpers carry that number
+ * to whoever is doing the backing off.
+ */
+/** Thrown for HTTP 429 so a retry loop can wait the server's number, not its own. */
+export class RateLimitedError extends Error {
+    status = 429;
+    /** How long the server said to wait. Null when it said nothing. */
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.name = 'RateLimitedError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/** True for the error above — survives structured clones and re-wraps. */
+export function isRateLimited(err) {
+    return (!!err &&
+        typeof err === 'object' &&
+        err.status === 429);
+}
+const MAX_RETRY_AFTER_MS = 120_000;
+/**
+ * Read the wait out of a 429 response. `Retry-After` wins (it is the explicit
+ * one) and is accepted in both forms — delta-seconds or an HTTP date;
+ * `RateLimit-Reset` is the standard-headers fallback, in seconds. Capped so a
+ * bad header cannot park a loop for an hour, floored at a second so a `0` does
+ * not reproduce the hot-retry it is meant to stop.
+ */
+export function parseRetryAfterMs(headers) {
+    const explicit = headers.get('retry-after');
+    if (explicit) {
+        const seconds = Number(explicit);
+        if (Number.isFinite(seconds))
+            return clampRetryMs(seconds * 1000);
+        const at = Date.parse(explicit);
+        if (!Number.isNaN(at))
+            return clampRetryMs(at - Date.now());
+    }
+    const reset = headers.get('ratelimit-reset');
+    if (reset) {
+        const seconds = Number(reset);
+        if (Number.isFinite(seconds))
+            return clampRetryMs(seconds * 1000);
+    }
+    return null;
+}
+function clampRetryMs(ms) {
+    if (!Number.isFinite(ms))
+        return 1_000;
+    return Math.min(MAX_RETRY_AFTER_MS, Math.max(1_000, Math.round(ms)));
+}
+/**
+ * Build the error for a failed poll-surface response: 429s carry the server's
+ * wait, everything else stays an ordinary Error so existing handling is
+ * unchanged.
+ */
+export function pollSurfaceError(label, res, body) {
+    const message = `${label} ${res.status} ${body.slice(0, 200)}`;
+    if (res.status !== 429)
+        return new Error(message);
+    return new RateLimitedError(message, parseRetryAfterMs(res.headers));
+}

package/dist/types.d.ts

@@ -102,6 +102,17 @@ export interface Agreement {
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
+    /**
+     * Seat bookkeeping when this agreement is an open link invite. Each claim
+     * takes a seat and mints its own child link, so one shared link produces N
+     * separate connections rather than a group.
+     */
+    linkInvite?: {
+        maxClaims?: number;
+        claimsUsed?: number;
+    } | null;
+    /** Set on a link that was formed by claiming the invite with this id. */
+    linkInviteTemplateId?: string | null;
     metadata?: Record<string, unknown>;
     createdAt?: string;
     updatedAt?: string;
@@ -165,7 +176,7 @@ export interface MessageMetadata {
      * `task.notify.chat` / `agreement.notify.direct` traffic. The agent SDK's
      * `normalizeIncomingEvent` reads `metadata.task` to upgrade structured
      * task notifications into `task_result` events (so executors see
-     * `task-assigned` outcomes when the orchestrator calls `task_spawn`),
+     * `task-assigned` outcomes when the orchestrator calls `task_create`),
      * and maps explicit wire `operation` + `agreementId` lifecycle fields
      * into `agreement_lifecycle` events for proposal approve/reject.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",