@ziggs-ai/api-client 0.4.0 → 0.6.0

package/dist/ConnectionManager.d.ts

@@ -1,6 +1,16 @@
 import { type InboxOperatorAgentEntry } from './http/InboxClient.js';
 type OpenFn = () => Promise<unknown>;
 type CloseFn = (handle: unknown) => Promise<void>;
+export interface StartAgentOptions {
+    /**
+     * Keep this host running until it is stopped explicitly — exempt from the
+     * idle sweep, last choice for LRU eviction. For agents the operator named
+     * (launcher `preStart` / `WAKE_AGENTS`): they were started because someone
+     * decided they must be up, not because work arrived, so "no work for a
+     * while" is not a reason to retire them.
+     */
+    pinned?: boolean;
+}
 export interface ConnectionManagerMeta {
     domain?: string;
     expertise?: string[];
@@ -46,6 +56,7 @@ export declare class ConnectionManager {
     private _active;
     private _meta;
     private _starting;
+    private _pinned;
     private _shouldLazyStart;
     constructor({ maxActive, idleTimeoutMs, control, shouldLazyStart }?: ConnectionManagerOptions);
     register(id: string, openFn: OpenFn, closeFn: CloseFn, meta?: ConnectionManagerMeta): void;
@@ -59,12 +70,13 @@ export declare class ConnectionManager {
      * the loop never exits until `stop()` (nothing to resynchronize).
      */
     private _runOperatorPoll;
-    startAgent(id: string): Promise<unknown>;
+    startAgent(id: string, { pinned }?: StartAgentOptions): Promise<unknown>;
     sleep(id: string): Promise<void>;
     sleepAll(): Promise<void>;
     touch(id: string): void;
     list(): string[];
     listActive(): string[];
+    listPinned(): string[];
     get size(): number;
     query({ domain, expertise, tags }?: QueryFilter): string[];
     getMeta(id: string): ConnectionManagerMeta | undefined;

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;
@@ -16,6 +17,7 @@ export class ConnectionManager {
     _active;
     _meta;
     _starting;
+    _pinned;
     _shouldLazyStart;
     constructor({ maxActive = 50, idleTimeoutMs = 60_000, control, shouldLazyStart } = {}) {
         this.maxActive = maxActive;
@@ -28,6 +30,7 @@ export class ConnectionManager {
         this._active = new Map();
         this._meta = new Map();
         this._starting = new Map();
+        this._pinned = new Set();
     }
     register(id, openFn, closeFn, meta) {
         if (!id)
@@ -68,7 +71,19 @@ export class ConnectionManager {
         let consecutiveErrors = 0;
         while (this._polling) {
             try {
-                const env = await inbox.getOperatorInbox({ waitSeconds: OPERATOR_POLL_WAIT_SECONDS });
+                // Roster scoping (ZIG-965): only agents this manager can actually
+                // start are worth sweeping server-side. Without it a partial launcher
+                // (ONLY_AGENTS) paid for a sweep of the owner's whole seeded fleet.
+                //
+                // Already-running agents are excluded: this loop's only job is
+                // lazy-start, and a running host polls its own inbox. Sending them
+                // made the server answer for agents whose entry we then discarded
+                // below — pure duplicate work, growing with how healthy the fleet is.
+                const startable = [...this._entries.keys()].filter((id) => !this._active.has(id));
+                const env = await inbox.getOperatorInbox({
+                    waitSeconds: OPERATOR_POLL_WAIT_SECONDS,
+                    agents: startable,
+                });
                 consecutiveErrors = 0;
                 for (const entry of env.agents) {
                     const id = entry.agentId;
@@ -85,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`);
@@ -92,7 +117,11 @@ export class ConnectionManager {
             }
         }
     }
-    async startAgent(id) {
+    async startAgent(id, { pinned = false } = {}) {
+        // Recorded before any await so a pin is never lost to a concurrent
+        // unpinned start of the same id.
+        if (pinned)
+            this._pinned.add(id);
         const existing = this._active.get(id);
         if (existing) {
             this._resetTimer(id);
@@ -136,6 +165,7 @@ export class ConnectionManager {
     touch(id) { this._resetTimer(id); }
     list() { return [...this._entries.keys()]; }
     listActive() { return [...this._active.keys()]; }
+    listPinned() { return [...this._pinned]; }
     get size() { return this._entries.size; }
     query({ domain, expertise, tags } = {}) {
         const results = [];
@@ -156,6 +186,14 @@ export class ConnectionManager {
         if (!entry)
             return;
         clearTimeout(entry.timer);
+        // A pinned host has no idle timer at all. Empty polls don't count as
+        // activity (only delivered items call touch()), so a pinned agent nobody
+        // talks to would otherwise be swept — and with lazy start unable to keep
+        // up at fleet size, nothing brings it back until the process restarts.
+        if (this._pinned.has(id)) {
+            entry.timer = null;
+            return;
+        }
         entry.timer = setTimeout(() => {
             this.sleep(id).catch(err => runtimeLog.warn('ConnectionManager', `idle sleep("${id}") failed: ${err.message}`));
         }, this.idleTimeoutMs);
@@ -168,13 +206,29 @@ export class ConnectionManager {
         this._scheduleIdle(id);
     }
     async _evictLRU() {
-        let oldest = null;
-        for (const [id, entry] of this._active) {
-            const oldestEntry = oldest ? this._active.get(oldest) : null;
-            if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive)
-                oldest = id;
+        // Pinned hosts are the last to go: pick the LRU unpinned one, and only
+        // fall back to a pinned one when every active host is pinned. maxActive
+        // stays a hard cap — a pin outranks other agents, not the capacity limit —
+        // but say so, because it means more agents were pinned than can run.
+        const oldestOf = (ids) => {
+            let oldest = null;
+            for (const id of ids) {
+                const entry = this._active.get(id);
+                const oldestEntry = oldest ? this._active.get(oldest) : null;
+                if (!entry)
+                    continue;
+                if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive)
+                    oldest = id;
+            }
+            return oldest;
+        };
+        const active = [...this._active.keys()];
+        const victim = oldestOf(active.filter(id => !this._pinned.has(id))) ?? oldestOf(active);
+        if (!victim)
+            return;
+        if (this._pinned.has(victim)) {
+            runtimeLog.warn('ConnectionManager', `evicting pinned "${victim}": all ${active.length} active hosts are pinned and maxActive=${this.maxActive} is reached — pin fewer agents or raise maxActive`);
         }
-        if (oldest)
-            await this.sleep(oldest);
+        await this.sleep(victim);
     }
 }

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: {
@@ -34,8 +34,11 @@ export const recordArtifactCapability = {
             enum: ['chat', 'agent-private'],
             description: 'chat = visible to scope parties; agent-private = your eyes only',
         },
-        chatId: { type: 'string', description: 'Target chat (xor agreementId)' },
-        agreementId: { type: 'string', description: 'Target agreement (xor chatId)' },
+        chatId: { type: 'string', description: 'Target chat scope' },
+        agreementId: {
+            type: 'string',
+            description: 'Target agreement scope — for a hire deliverable, prefer this. When both chatId and agreementId are passed, agreementId wins.',
+        },
         taskId: {
             type: 'string',
             description: 'Optional task — creates a TaskArtifactLink alongside the primary scope link',
@@ -51,10 +54,15 @@ export const recordArtifactCapability = {
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        const chatId = args['chatId'];
         const agreementId = args['agreementId'];
-        if ((chatId && agreementId) || (!chatId && !agreementId)) {
-            throw new Error('Pass exactly one of chatId or agreementId');
+        // Agreement wins when both scopes arrive. Models naturally pass the chat
+        // they are standing in alongside the agreement they deliver under; a hard
+        // xor here failed the deliverable at the last step of a finished task
+        // (ZIG-924 dogfood). The backend still enforces exactly-one — we resolve
+        // the ambiguity at the exposed surface instead of erroring.
+        const chatId = agreementId ? undefined : args['chatId'];
+        if (!chatId && !agreementId) {
+            throw new Error('Pass chatId or agreementId');
         }
         const visibility = args['visibility'];
         if (visibility !== 'chat' && visibility !== 'agent-private') {

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[];