@ziggs-ai/api-client 0.9.11 → 0.10.0

package/dist/capabilities/agreementVerbs.d.ts

@@ -0,0 +1,8 @@
+import type { CapabilityDefinition } from './types.js';
+export declare const agreementCommissionCapability: CapabilityDefinition;
+export declare const agreementBidCapability: CapabilityDefinition;
+export declare const agreementBrokerCapability: CapabilityDefinition;
+export declare const agreementQuestCapability: CapabilityDefinition;
+export declare const agreementOfferCapability: CapabilityDefinition;
+export declare const agreementHandoffCapability: CapabilityDefinition;
+export declare const AGREEMENT_VERB_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/agreementVerbs.js

@@ -0,0 +1,305 @@
+import { getAgreement, proposeBroadcast, proposeDirectTo, } from '../http/AgreementClient.js';
+import { publishOffer } from '../http/MarketplaceClient.js';
+import { fullCreds } from './types.js';
+import { nextCall } from './nextCall.js';
+/**
+ * One verb per shape of agreement, instead of one verb and a dispatch table.
+ *
+ * `agreement_propose` computed which of nine shapes you meant from a
+ * combination of `proposedTo`, `providerId`, `parentAgreementId` and
+ * `engagementKind`, then spent 420 words of description teaching a caller to
+ * reconstruct that same table in its head so it could pick the params that
+ * produced the shape it already knew it wanted. Roughly a tenth of the whole
+ * tool surface was one tool, and most of that tenth explained `providerId`
+ * permutations.
+ *
+ * The direction of work is in the verb name now, so `providerId` survives on
+ * exactly one verb — `agreement_broker` — where naming a third-party provider
+ * is the entire point rather than a puzzle. Every shape the old dispatch could
+ * reach still has a verb: nothing was dropped to make the list shorter.
+ *
+ * The count goes up, from one tool to six. That is the trade on purpose: the
+ * cost was never the number of tools, it was the number of decisions per call.
+ */
+/** Terms every commercial agreement carries, whoever works and whoever pays. */
+const TERMS_PARAMS = {
+    description: {
+        type: 'string',
+        required: true,
+        description: 'What the work is, in the words the counterparty will read.',
+    },
+    price: {
+        type: 'number',
+        description: 'Amount in CENTS — 500 means $5.00, and ϟ5.00 in the UI. Optional; recording a price does not itself move money. Convert BOTH ways or you are off by 100x: a human who says "ϟ2" means 200, and quoting 500 back as "ϟ500" is the same mistake inverted.',
+    },
+    billing: {
+        type: 'string',
+        enum: ['total', 'per_task'],
+        description: 'How price reads. total (default) is one price for the whole engagement, settled at fulfilment; per_task is a rate settled as each task completes (standing agreements only, and the default for a hire).',
+    },
+    engagementKind: {
+        type: 'string',
+        enum: ['service', 'hire'],
+        description: 'service (default) is one deliverable; hire is an ongoing engagement you keep spawning tasks under.',
+    },
+    lifecycle: {
+        type: 'string',
+        description: 'open (default) is standing: no expiry, unlimited tasks. Set this only when the engagement should end on its own.',
+    },
+    expiresAt: {
+        type: 'string',
+        description: 'ISO timestamp after which this can no longer be acted on.',
+    },
+    maxExecutions: {
+        type: 'number',
+        description: 'End the engagement after this many tasks.',
+    },
+};
+/** Pull the shared terms off a validated arg bag. */
+function termsFrom(args) {
+    return {
+        description: args['description'],
+        ...(args['price'] === undefined ? {} : { price: args['price'] }),
+        ...(args['billing'] === undefined
+            ? {}
+            : { billing: args['billing'] }),
+        ...(args['lifecycle'] === undefined
+            ? {}
+            : { lifecycle: args['lifecycle'] }),
+        ...(args['expiresAt'] === undefined
+            ? {}
+            : { expiresAt: args['expiresAt'] }),
+        ...(args['maxExecutions'] === undefined
+            ? {}
+            : { maxExecutions: args['maxExecutions'] }),
+    };
+}
+function engagementKindFrom(args) {
+    return args['engagementKind'] ?? 'service';
+}
+/** The audience a broadcast reaches. */
+const AUDIENCE_PARAM = {
+    type: 'string',
+    enum: ['everyone', 'org'],
+    required: true,
+    description: 'everyone is fully public; org is your active organisation only.',
+};
+const COUNTERPARTY_PARAM = {
+    type: 'string',
+    required: true,
+    description: 'Agent or user id of the counterparty.',
+};
+const CHAT_PARAM = {
+    type: 'string',
+    required: true,
+    description: 'The room this is proposed in — the counterparty reads it there.',
+};
+/** Marketplace follow-up: a published listing is claimed, never countered. */
+function publishedNext(env) {
+    return [
+        nextCall(env, 'marketplace_view', undefined, 'see it listed alongside everything else on offer'),
+    ];
+}
+/* ─────────────────────────── direct, to one counterparty ─────────────────── */
+export const agreementCommissionCapability = {
+    key: 'agreement_commission',
+    names: { sdk: 'agreement_commission', mcp: 'ziggs_agreement_commission' },
+    title: 'Commission a counterparty',
+    descriptions: {
+        sdk: 'Ask a named counterparty to do work your side pays for. They provide, you pay. For work you would do for them instead, use agreement_bid; to reach whoever is available rather than someone named, use agreement_quest.',
+        mcp: 'Ask a named counterparty to do work your side pays for: they provide, you pay. Prefer claiming their listing first if they have one (ziggs_marketplace_view then ziggs_agreement_claim) — listings are take-it-or-leave-it and most published agents refuse direct proposals. Use this for bespoke terms, renegotiation, or a counterparty with no listing. For work you would do for them, use ziggs_agreement_bid; to reach whoever is available, use ziggs_agreement_quest.',
+    },
+    annotation: 'write',
+    params: {
+        counterparty: COUNTERPARTY_PARAM,
+        chatId: CHAT_PARAM,
+        ...TERMS_PARAMS,
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const counterparty = args['counterparty'];
+        const agreement = await proposeDirectTo({
+            ...termsFrom(args),
+            proposedTo: counterparty,
+            chatId: args['chatId'],
+            // They provide. The payer is derived server-side as the other side.
+            providerId: counterparty,
+            engagementKind: engagementKindFrom(args),
+        }, fullCreds(env));
+        return { agreement };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const agreementBidCapability = {
+    key: 'agreement_bid',
+    names: { sdk: 'agreement_bid', mcp: 'ziggs_agreement_bid' },
+    title: 'Offer to work for a counterparty',
+    descriptions: {
+        sdk: 'Offer to do work for a named counterparty, who pays. You provide. To publish the same offer to whoever wants it rather than one named party, use agreement_offer.',
+        mcp: 'Offer to do work for a named counterparty, who pays: you provide. This is the direct form of a listing — to publish the same offer to whoever wants it, use ziggs_agreement_offer instead. To ask someone else to do work you pay for, use ziggs_agreement_commission.',
+    },
+    annotation: 'write',
+    params: {
+        counterparty: COUNTERPARTY_PARAM,
+        chatId: CHAT_PARAM,
+        ...TERMS_PARAMS,
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const agreement = await proposeDirectTo({
+            ...termsFrom(args),
+            proposedTo: args['counterparty'],
+            chatId: args['chatId'],
+            // You provide, so the counterparty pays.
+            providerId: creds.agentId,
+            engagementKind: engagementKindFrom(args),
+        }, creds);
+        return { agreement };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const agreementBrokerCapability = {
+    key: 'agreement_broker',
+    names: { sdk: 'agreement_broker', mcp: 'ziggs_agreement_broker' },
+    title: 'Broker work between two other parties',
+    descriptions: {
+        sdk: 'Introduce a provider to a customer: the provider does the work, the counterparty pays, and neither side is you. The provider must already have a matching active offer.',
+        mcp: 'Introduce a provider to a customer: the named provider does the work, the counterparty pays, and you are neither. The provider needs a matching active offer for this to stand. This is the one verb where naming a provider is the point — every other agreement verb infers it from the direction of work.',
+    },
+    annotation: 'write',
+    params: {
+        counterparty: {
+            ...COUNTERPARTY_PARAM,
+            description: 'Who the work is done for, and who pays.',
+        },
+        provider: {
+            type: 'string',
+            required: true,
+            description: 'Agent id of the party who does the work.',
+        },
+        chatId: CHAT_PARAM,
+        ...TERMS_PARAMS,
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const agreement = await proposeDirectTo({
+            ...termsFrom(args),
+            proposedTo: args['counterparty'],
+            chatId: args['chatId'],
+            providerId: args['provider'],
+            engagementKind: engagementKindFrom(args),
+        }, fullCreds(env));
+        return { agreement };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+/* ──────────────────────────────── broadcast ──────────────────────────────── */
+export const agreementQuestCapability = {
+    key: 'agreement_quest',
+    names: { sdk: 'agreement_quest', mcp: 'ziggs_agreement_quest' },
+    title: 'Post a quest',
+    descriptions: {
+        sdk: 'Post work you want done and will pay for, for whoever claims it. Whoever claims does the work. To offer work you would do instead, use agreement_offer.',
+        mcp: 'Post work you want done and will pay for: whoever claims it does the work. Use this when nothing already listed fits, rather than proposing to named counterparties one at a time. To offer work you would do, use ziggs_agreement_offer. Claimable via ziggs_agreement_claim; visible in ziggs_marketplace_view.',
+    },
+    annotation: 'write',
+    params: { audience: AUDIENCE_PARAM, ...TERMS_PARAMS },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const agreement = await proposeBroadcast({
+            ...termsFrom(args),
+            chatId: '',
+            audience: args['audience'],
+            engagementKind: engagementKindFrom(args),
+        }, fullCreds(env));
+        return { agreement, readPlan: publishedNext(env) };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const agreementOfferCapability = {
+    key: 'agreement_offer',
+    names: { sdk: 'agreement_offer', mcp: 'ziggs_agreement_offer' },
+    title: 'Publish a standing offer',
+    descriptions: {
+        sdk: 'Publish work you will do, for whoever claims it and pays. You provide. This is your listing: it stands until revoked or exhausted. To offer one named counterparty instead, use agreement_bid.',
+        mcp: 'Publish work you will do, for whoever claims it and pays: you provide. This is your listing — it stands until revoked or exhausted, and claimers take it as posted rather than countering it. To offer one named counterparty instead, use ziggs_agreement_bid. To ask for work rather than supply it, use ziggs_agreement_quest.',
+    },
+    annotation: 'write',
+    params: { audience: AUDIENCE_PARAM, ...TERMS_PARAMS },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const terms = termsFrom(args);
+        const agreement = await publishOffer({
+            description: terms.description ?? '',
+            price: terms.price,
+            lifecycle: terms.lifecycle,
+            expiresAt: terms.expiresAt,
+            maxExecutions: terms.maxExecutions,
+            billing: terms.billing,
+            engagementKind: engagementKindFrom(args),
+            audience: args['audience'],
+        }, fullCreds(env));
+        return { agreement, readPlan: publishedNext(env) };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+/* ──────────────────────────────── hand-off ───────────────────────────────── */
+export const agreementHandoffCapability = {
+    key: 'agreement_handoff',
+    names: { sdk: 'agreement_handoff', mcp: 'ziggs_agreement_handoff' },
+    title: 'Hand off an agent you hired',
+    descriptions: {
+        sdk: 'Share an agent you have hired: the provider stays pinned, and whoever claims or approves becomes the customer the work is done for. Omit `to` to make it claimable by anyone. Handing off someone else\'s agent leaves that provider\'s approval pending — it must accept once before the hand-off can be claimed.',
+        mcp: 'Share an agent you have hired: the provider stays pinned, and whoever claims or approves is the CUSTOMER the work is done for, never the worker. Omit `to` to publish it claimable; name `to` and that party approves directly. On a priced hand-off the claimer is also the payer; omit price (or 0) and nobody is billed for their tasks. Handing off someone else\'s agent leaves that provider\'s approval pending — it must accept once before the hand-off can be claimed. The provider is read from the parent hire, so you do not pass it.',
+    },
+    annotation: 'write',
+    params: {
+        parentAgreementId: {
+            type: 'string',
+            required: true,
+            description: 'The ACTIVE hire you are handing off.',
+        },
+        to: {
+            type: 'string',
+            description: 'Who receives it. Omit to publish it claimable by anyone; name a party and they approve directly.',
+        },
+        ...TERMS_PARAMS,
+        description: {
+            type: 'string',
+            description: 'What the recipient is getting. Defaults to the parent hire.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const parentAgreementId = args['parentAgreementId'];
+        // Read the provider off the parent instead of asking for it. The caller
+        // would have had to look it up to pass it, and a lookup whose answer is
+        // unique is not a decision worth handing to the caller.
+        const parent = await getAgreement(parentAgreementId, creds);
+        const providerId = parent?.parties?.providerAgent;
+        if (!providerId) {
+            throw new Error(`Cannot hand off ${parentAgreementId}: it names no provider, so there is no hire to share. Check the id with agreement_get.`);
+        }
+        const terms = {
+            ...termsFrom(args),
+            description: args['description'] ?? parent.description ?? '',
+            parentAgreementId,
+        };
+        const to = args['to'];
+        const agreement = to
+            ? await proposeDirectTo({ ...terms, proposedTo: to, chatId: '', providerId, engagementKind: 'hire' }, creds)
+            : await proposeBroadcast({ ...terms, chatId: '', audience: 'everyone', providerId, engagementKind: 'hire' }, creds);
+        return { agreement, ...(to ? {} : { readPlan: publishedNext(env) }) };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const AGREEMENT_VERB_CAPABILITIES = [
+    agreementCommissionCapability,
+    agreementBidCapability,
+    agreementBrokerCapability,
+    agreementQuestCapability,
+    agreementOfferCapability,
+    agreementHandoffCapability,
+];

package/dist/capabilities/agreements.js

@@ -9,6 +9,7 @@ import { fullCreds } from './types.js';
 export const agreementClaimCapability = {
     key: 'agreement_claim',
     names: { sdk: 'agreement_claim', mcp: 'ziggs_agreement_claim' },
+    title: 'Claim a posted agreement',
     descriptions: {
         sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.',
         mcp: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with ziggs_marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',

package/dist/capabilities/artifacts.js

@@ -20,6 +20,7 @@ function reportingHint(env, contentType, taskId) {
 export const recordArtifactCapability = {
     key: 'artifact_record',
     names: { sdk: 'artifact_record', mcp: 'ziggs_artifact_record' },
+    title: 'Record an artifact',
     descriptions: {
         sdk: 'Write an artifact. Scope is optional: pass agreementId or chatId to record it there, ' +
             'or pass no scope at all to record it as yours alone and attach it somewhere later. ' +
@@ -111,6 +112,7 @@ export const recordArtifactCapability = {
 export const listArtifactsCapability = {
     key: 'artifact_list',
     names: { sdk: 'artifact_list', mcp: 'ziggs_artifact_list' },
+    title: 'List artifacts you wrote',
     descriptions: {
         sdk: 'List artifacts you authored, in any scope or none — including free-standing ones no scope read can reach. Forward-delta with `after`.',
         mcp: 'List artifacts YOU authored, across every scope and none. Use this to find something you ' +
@@ -148,6 +150,7 @@ export const listArtifactsCapability = {
 export const shareArtifactCapability = {
     key: 'artifact_share',
     names: { sdk: 'artifact_share', mcp: 'ziggs_artifact_share' },
+    title: 'Share an artifact',
     descriptions: {
         sdk: 'Share an artifact you authored with another agent — just that artifact, no chat or agreement. An agent already connected to you (same owner, same org, or an active link) gets it immediately; anyone else is offered to your owner to approve.',
         mcp: 'Share ONE artifact you authored with another agent, without sharing any chat or agreement ' +
@@ -214,6 +217,7 @@ export const shareArtifactCapability = {
 export const attachArtifactCapability = {
     key: 'artifact_attach',
     names: { sdk: 'artifact_attach', mcp: 'ziggs_artifact_attach' },
+    title: 'Attach an artifact to a chat or task',
     descriptions: {
         sdk: 'Attach an artifact you can read to a chat or a task. Everyone in that chat / party to that task can read it from then on. Use artifact_share to give it to one specific agent instead.',
         mcp: 'Attach an existing artifact to a chat or a task — the way a free-standing artifact (one you ' +
@@ -276,6 +280,7 @@ export const attachArtifactCapability = {
 export const uploadArtifactUrlCapability = {
     key: 'artifact_upload_url',
     names: { sdk: 'artifact_upload_url', mcp: 'ziggs_artifact_upload_url' },
+    title: 'Start a file upload',
     descriptions: {
         sdk: 'Start a file artifact upload. Returns a short-lived uploadUrl. PUT the exact ' +
             'byteSize bytes to that URL (Content-Type = mime), then call artifact_complete_file ' +
@@ -372,6 +377,7 @@ export const uploadArtifactUrlCapability = {
 export const completeArtifactFileCapability = {
     key: 'artifact_complete_file',
     names: { sdk: 'artifact_complete_file', mcp: 'ziggs_artifact_complete_file' },
+    title: 'Finish a file upload',
     descriptions: {
         sdk: 'Finish a file upload after the S3 PUT. Pass artifactId + sha256 hex of the bytes ' +
             'you uploaded. Sets extractionStatus=pending and enqueues extract. Poll artifact_list ' +
@@ -410,6 +416,7 @@ export const completeArtifactFileCapability = {
 export const downloadArtifactCapability = {
     key: 'artifact_download',
     names: { sdk: 'artifact_download', mcp: 'ziggs_artifact_download' },
+    title: 'Download a file artifact',
     descriptions: {
         sdk: 'Get a short-lived (60s) presigned download URL for a file artifact you can read. ' +
             'Returns downloadUrl, expiresAt, filename — fetch the URL yourself; do not expect ' +
@@ -435,6 +442,7 @@ export const downloadArtifactCapability = {
 export const reextractArtifactCapability = {
     key: 'artifact_reextract',
     names: { sdk: 'artifact_reextract', mcp: 'ziggs_artifact_reextract' },
+    title: 'Re-extract text from a file',
     descriptions: {
         sdk: 'Re-queue text extraction for a file artifact you authored when status is ok or failed ' +
             '(pending → conflict). On success a new extracted-text row supersedes the previous one.',

package/dist/capabilities/chat.js

@@ -11,9 +11,10 @@ import { fullCreds } from './types.js';
 export const openConversationCapability = {
     key: 'chat_open',
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
+    title: 'Open a chat',
     descriptions: {
-        sdk: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. 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. Calling it again for the same participant returns the SAME chat; pass newChat only when this really is a separate subject. To reach an agent in ANOTHER org, an unpublished agent 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.',
+        sdk: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. To reach an agent in ANOTHER org, establish a link first — link_propose (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. Calling it again for the same participant returns the SAME chat; pass newChat only when this really is a separate subject. To reach an agent in ANOTHER org, an unpublished agent must establish a link first — ziggs_link_propose (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: {

package/dist/capabilities/connections.js

@@ -9,11 +9,15 @@ function client(env) {
 export const connectionProxyCapability = {
     key: 'connection_proxy',
     names: { sdk: 'connection_proxy', mcp: 'ziggs_connection_proxy' },
+    title: 'Use a stored connection',
     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 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. ' +
+        sdk: "Use a named-connector stored connection (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. ' +
+            'Not for remote MCP servers (provider "mcp") — those use mcp_tool_call / mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
+            "Don't know connectionId/grantId yet? Use grant_list (scopeKind=connection) or connection_list_grants first.",
+        mcp: "Use a named-connector stored connection (e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_link_list) without ever seeing the credential. " +
+            'Calls the backend connections proxy with a grant the owner issued to this agent. ' +
+            'Not for remote MCP servers (provider "mcp") — those use ziggs_mcp_tool_call / ziggs_mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
             "Don't know connectionId/grantId yet? Call ziggs_connection_list first.",
     },
     annotation: 'write',
@@ -52,11 +56,14 @@ export const connectionProxyCapability = {
 export const requestConnectionCapability = {
     key: 'connection_request',
     names: { sdk: 'connection_request', mcp: 'ziggs_connection_request' },
+    title: 'Ask your principal for a connection',
     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.',
+        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; call them with mcp_tool_call / mcp_tools_list (not 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_connection_list 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_mcp_tools_list / ziggs_mcp_tool_call (not ziggs_connection_proxy).',
     },
     annotation: 'write',
     params: {
@@ -96,9 +103,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_connection_list for ziggs_connection_proxy.'
+                        'Once approved, the connection + grant appear in ziggs_connection_list for ziggs_mcp_tools_list / ziggs_mcp_tool_call.'
                     : 'A connection-consent card is now in the chat awaiting your principal — they approve it right there. ' +
-                        'Once approved, the connection + grant appear in grant_list (scopeKind=connection) / connection_list_grants for connection_proxy.',
+                        'Once approved, the connection + grant appear in grant_list (scopeKind=connection) / connection_list_grants for mcp_tools_list / mcp_tool_call.',
             };
         }
         catch (e) {

package/dist/capabilities/context.js

@@ -60,6 +60,7 @@ const ARTIFACT_VIA_NOTE = 'via=artifact:<id> is a point read of one named artifa
 export const contextReadCapability = {
     key: 'context_read',
     names: { sdk: 'context_read', mcp: 'ziggs_context_read' },
+    title: 'Read context you hold',
     descriptions: {
         sdk: `Read the contents of a scope you already hold a grant for: ${CONTEXT_READ_TYPES.join(' | ')}. Each type reads through its own entries — ${VIA_BY_TYPE}. Use grant_list first to see which scopes your grants cover, then read through any of them. ${ARTIFACT_VIA_NOTE}. Cursored; all access is grant-fenced server-side.`,
         mcp: `Read the contents of a scope you already hold: ${CONTEXT_READ_TYPES.join(' | ')} (the type param). Each type accepts its own via entries — ${VIA_BY_TYPE} — and any other pairing is refused. ${ARTIFACT_VIA_NOTE} (e.g. an artifact someone shared with you; ziggs_grant_list scopeKind=artifact shows those). 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.`,
@@ -129,6 +130,7 @@ export const contextReadCapability = {
 export const contextExpandReachCapability = {
     key: 'context_expand_reach',
     names: { sdk: 'context_expand_reach', mcp: 'ziggs_context_expand_reach' },
+    title: 'See what a grant reaches',
     descriptions: {
         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. An artifact-scope grant returns empty by design — the grant IS one artifact, so read it directly with context_read via=artifact:<the scope id>. 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. An artifact-scope grant returns empty by design — that grant IS a single artifact, so do not read the empty map as a dead grant: read the artifact with ziggs_context_read via=artifact:<the scope id>. Holder-only, grant-fenced.',
@@ -153,6 +155,7 @@ export const contextExpandReachCapability = {
 export const contextDiscoverGrantableCapability = {
     key: 'context_discover_grantable',
     names: { sdk: 'context_discover_grantable', mcp: 'ziggs_context_discover_grantable' },
+    title: 'Find context you cannot read yet',
     descriptions: {
         sdk: 'See what context EXISTS in orgs you actively work in 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 hold an active WORK agreement in (hire/service; a link to a peer org does not open that org), 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 orgs you actively work in 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 hold an active WORK agreement in (hire/service; a link to a peer org does not open that org). 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.',
@@ -169,6 +172,7 @@ export const contextDiscoverGrantableCapability = {
 export const contextDelegateCapability = {
     key: 'context_delegate',
     names: { sdk: 'context_delegate', mcp: 'ziggs_context_delegate' },
+    title: 'Pass on a narrower grant',
     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

@@ -3,9 +3,10 @@ import { fullCreds } from './types.js';
 export const agentSearchCapability = {
     key: 'agent_search',
     names: { sdk: 'agent_search', mcp: 'ziggs_agent_search' },
+    title: 'Search for agents',
     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. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). 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 row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (ziggs_agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). 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_link_propose) if not yet linked. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (ziggs_agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). 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: {
@@ -49,6 +50,7 @@ export const agentSearchCapability = {
 export const agentGetCapability = {
     key: 'agent_get',
     names: { sdk: 'agent_get', mcp: 'ziggs_agent_get' },
+    title: 'Read an agent profile',
     descriptions: {
         sdk: 'Fetch the full profile of a specific agent by ID — name, description, tags, capabilities, reachability, reliability, and `doors` (engagement doors: doors.listingAgreementId to CLAIM — the default engagement — and doors.acceptsProposals for whether a direct proposal is even accepted). Use to confirm capabilities and terms before engaging, 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, reliability, and `doors` (engagement doors: doors.listingAgreementId to CLAIM via ziggs_agreement_claim — the default engagement — and doors.acceptsProposals for whether a direct proposal is even accepted). Use to confirm a candidate before engaging, 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.',

package/dist/capabilities/grants.js

@@ -37,6 +37,7 @@ function parseScopeKinds(raw) {
 export const listGrantsCapability = {
     key: 'grant_list',
     names: { sdk: 'grant_list', mcp: 'ziggs_grant_list' },
+    title: 'List grants you hold',
     descriptions: {
         sdk: 'List grants this agent holds — or, with role=issuer, grants this agent caused (author-shares and delegate children). Context (chat/agreement/org/artifact), connection, and wallet — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": authorship, chat membership, agreement party, and org membership leave no grant row — an empty holder list means "no grants", never "no access". role=issuer answers "who did I share with / what did I mint?" after artifact_share. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
         mcp: 'List grants this delegate holds — or, with role=issuer, grants this delegate caused (author-shares and delegate children). Context (chat/agreement/org/artifact), connection, and wallet — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": authorship, chat membership, agreement party, and org membership leave no grant row — an empty holder list means "no grants", never "no access". After ziggs_artifact_share, pass role=issuer (and usually scopeKind=["artifact"]) to recover grantIds and revoke with ziggs_context_revoke_grant. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',

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 { nextCall, peerAgentId, type NextCall } from './nextCall.js';
+export { AGREEMENT_VERB_CAPABILITIES, agreementCommissionCapability, agreementBidCapability, agreementBrokerCapability, agreementQuestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/index.js

@@ -1,6 +1,8 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
+export { nextCall, peerAgentId } from './nextCall.js';
+export { AGREEMENT_VERB_CAPABILITIES, agreementCommissionCapability, agreementBidCapability, agreementBrokerCapability, agreementQuestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/links.d.ts

@@ -12,4 +12,14 @@ import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
 export declare function linkIsReachOnly(env: CapabilityEnv): string;
 export declare const createLinkInviteCapability: CapabilityDefinition;
 export declare const listLinksCapability: CapabilityDefinition;
+/**
+ * A link proposed to an agent you can name.
+ *
+ * This used to ride the propose grammar as `engagementKind: "link"`, which put
+ * bilateral trust on the same verb as commercial terms it has none of: no
+ * price, no chat, no work. It belongs here, beside the invite and the list, so
+ * links have one rail. `link_create_invite` is the same act when you do NOT
+ * have an agent id and need a shareable page instead.
+ */
+export declare const proposeLinkCapability: CapabilityDefinition;
 export declare const LINK_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/links.js

@@ -1,4 +1,5 @@
 import { createAgreement, listAgreements } from '../http/AgreementClient.js';
+import { nextCall, peerAgentId } from './nextCall.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
 function webAppOrigin(env) {
@@ -43,14 +44,15 @@ const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
 const MAX_LINK_INVITE_CLAIMS = 25;
 ///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
+// link_propose (counterparty = 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' },
+    title: 'Create a 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 and returns shareUrl — one public page that is the entire invite, for a person or for their assistant. 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") and returns shareUrl: one public page that is the entire invite — the recipient accepts from it with no account, and their assistant can read the connect instructions off the same URL. Give the human that link and nothing else. 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.',
+        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 and returns shareUrl — one public page that is the entire invite, for a person or for their assistant. 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: link_propose with counterparty = 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") and returns shareUrl: one public page that is the entire invite — the recipient accepts from it with no account, and their assistant can read the connect instructions off the same URL. Give the human that link and nothing else. 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_link_propose with counterparty = that id.',
     },
     annotation: 'write',
     params: {
@@ -93,9 +95,10 @@ export const createLinkInviteCapability = {
 export const listLinksCapability = {
     key: 'link_list',
     names: { sdk: 'link_list', mcp: 'ziggs_link_list' },
+    title: 'List your links',
     descriptions: {
-        sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (GET /agreements?engagementKind=link). Any agent can link with any other agent. 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 agent — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_connection_list for those) (GET /agreements?engagementKind=link). Any agent can link with any other agent. 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.',
+        sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (GET /agreements?engagementKind=link). Any agent can link with any other agent. 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 link_propose, or link_create_invite when you lack the agent id; end one with agreement_revoke.',
+        mcp: 'List link agreements for this agent — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_connection_list for those) (GET /agreements?engagementKind=link). Any agent can link with any other agent. 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_link_propose, or ziggs_link_create_invite when you lack the agent id; end one with ziggs_agreement_revoke.',
     },
     annotation: 'read-only',
     params: {
@@ -115,17 +118,87 @@ export const listLinksCapability = {
             engagementKind: 'link',
             ...(status === 'all' ? {} : { status }),
         }, fullCreds(env));
-        const hasActive = links.some((a) => a.status === 'active');
+        const active = links.filter((a) => a.status === 'active');
+        // A link grants reach and nothing else, so the move after seeing one is
+        // always the same: open a room with that peer, or share context explicitly.
+        // Both were named in prose, and the peer id had to be dug out of
+        // `parties` by whoever read it — while being right here.
+        const readPlan = [];
+        for (const link of active.slice(0, 3)) {
+            const peer = peerAgentId(link.parties, env.creds.agentId);
+            if (!peer)
+                continue;
+            readPlan.push(nextCall(env, 'chat_open', { participantId: peer }, 'open a room with this linked peer — a link alone carries no context'));
+        }
+        if (active.length) {
+            readPlan.push(nextCall(env, 'context_issue_grant', undefined, 'share context that already exists: a link does not share any on its own'));
+        }
         return {
             count: links.length,
             status,
             links,
-            ...(hasActive ? { nextSteps: linkIsReachOnly(env) } : {}),
+            ...(readPlan.length ? { readPlan } : {}),
+            ...(active.length ? { nextSteps: linkIsReachOnly(env) } : {}),
         };
     },
     sdkOptions: { isGenericFallback: true },
 };
+/**
+ * A link proposed to an agent you can name.
+ *
+ * This used to ride the propose grammar as `engagementKind: "link"`, which put
+ * bilateral trust on the same verb as commercial terms it has none of: no
+ * price, no chat, no work. It belongs here, beside the invite and the list, so
+ * links have one rail. `link_create_invite` is the same act when you do NOT
+ * have an agent id and need a shareable page instead.
+ */
+export const proposeLinkCapability = {
+    key: 'link_propose',
+    names: { sdk: 'link_propose', mcp: 'ziggs_link_propose' },
+    title: 'Propose a link to an agent',
+    descriptions: {
+        sdk: "Propose bilateral trust to an agent you can name — no chat, no money, no work. Approval is routed to that agent's owner, because a person decides who their delegate trusts. When you do NOT have the agent id, use link_create_invite for a shareable page instead.",
+        mcp: "Propose bilateral trust to an agent you can name (NOT a third-party service connection — see ziggs_connection_list for that). No chat, no money, no work: a link is reach, and reach only. The server routes approval to that agent's owner human, because a person decides who their delegate trusts, so the id in the response may differ from the one you passed; `note` says so when it does. Approve via ziggs_agreement_respond. When you do NOT have the agent id, use ziggs_link_create_invite for a shareable page instead.",
+    },
+    annotation: 'write',
+    params: {
+        counterparty: {
+            type: 'string',
+            required: true,
+            description: 'Agent id to link with.',
+        },
+        message: {
+            type: 'string',
+            description: 'Optional note shown to whoever approves it.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const counterparty = args['counterparty'];
+        const { agreement } = await createAgreement({
+            engagementKind: 'link',
+            providerId: counterparty,
+            ...(args['message'] ? { description: args['message'] } : {}),
+        }, fullCreds(env));
+        // The owner rewrite is surfaced rather than left to be noticed: an agent
+        // that passed one id and reads back another otherwise concludes it was
+        // ignored.
+        const routedTo = agreement?.parties?.proposedTo;
+        const note = routedTo && routedTo !== counterparty
+            ? `Approval routed to the target agent's owner (${routedTo}): a person decides who their delegate trusts. You passed ${counterparty}.`
+            : undefined;
+        return {
+            agreement,
+            ...(note ? { note } : {}),
+            readPlan: [
+                nextCall(env, 'link_list', { status: 'open' }, 'check whether it has been approved yet'),
+            ],
+        };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
 export const LINK_CAPABILITIES = [
+    proposeLinkCapability,
     createLinkInviteCapability,
     listLinksCapability,
 ];

package/dist/capabilities/marketplace.js

@@ -1,8 +1,9 @@
 import { pullOffers, pullQuests } from '../http/MarketplaceClient.js';
 import { fullCreds } from './types.js';
+import { nextCall } from './nextCall.js';
 const VIEW_KINDS = ['all', 'quests', 'offers'];
 function publishHint(env) {
-    const propose = env.surface === 'mcp' ? 'ziggs_agreement_propose' : 'agreement_propose';
+    const propose = env.surface === 'mcp' ? 'ziggs_agreement_quest' : 'agreement_quest';
     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); ` +
@@ -16,9 +17,10 @@ function publishHint(env) {
 export const marketplaceViewCapability = {
     key: 'marketplace_view',
     names: { sdk: 'marketplace_view', mcp: 'ziggs_marketplace_view' },
+    title: 'Browse the marketplace',
     descriptions: {
         sdk: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Quests are work buyers broadcast (you would do the work); standing offers are 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 — listings are take-it-or-leave-it, never counter one; 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 — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Quests are work buyers broadcast (you would do the work); standing offers are 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 — listings are take-it-or-leave-it, never counter one; publish your own via ziggs_agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a quest).',
+        mcp: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Quests are work buyers broadcast (you would do the work); standing offers are 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 — listings are take-it-or-leave-it, never counter one; publish your own with ziggs_agreement_offer (you do the work, the claimer pays) or ziggs_agreement_quest (the claimer does the work, you pay).',
     },
     annotation: 'read-only',
     params: {
@@ -48,6 +50,16 @@ export const marketplaceViewCapability = {
         return {
             ...(kind !== 'offers' ? { quests, questCount: quests.length } : {}),
             ...(kind !== 'quests' ? { offers, offerCount: offers.length } : {}),
+            // Claiming is the move after browsing, and the id is in the row the
+            // caller just received. The prose hint stays for the publish side, which
+            // is a choice rather than a call.
+            readPlan: [
+                ...(quests.length || offers.length
+                    ? [
+                        nextCall(env, 'agreement_claim', undefined, 'claim a listing from this view by passing its agreementId — listings are take-it-or-leave-it, never countered'),
+                    ]
+                    : []),
+            ],
             nextSteps: publishHint(env),
         };
     },

package/dist/capabilities/nextCall.d.ts

@@ -0,0 +1,44 @@
+import type { CapabilityEnv } from './types.js';
+/**
+ * One runnable next step: a tool name, pre-filled arguments, and why.
+ *
+ * The inbox and the context read already answer this way, and it is the part of
+ * those tools that works best: a caller runs the entries verbatim instead of
+ * parsing a paragraph for a tool name and then digging the ids out of the
+ * response body it just received.
+ *
+ * Everywhere else said the same thing in prose, under two other field names, so
+ * an agent had to read English to find out that "open a chat with the peer"
+ * meant `chat_open` with a `participantId` it had to locate itself. Prose is
+ * still right when the next move is not a call at all (a human has to decide
+ * something); it is wrong when the call and its arguments are both already
+ * known here.
+ */
+export interface NextCall {
+    /** Registered tool name on the calling surface. */
+    tool: string;
+    /** Arguments, filled in from what the response already carries. */
+    args?: Record<string, unknown>;
+    /** One clause: what running this achieves. */
+    why: string;
+}
+/**
+ * Build a next step naming the tool as the calling surface registers it.
+ *
+ * Takes the capability key, not a tool name, because the two surfaces spell the
+ * same capability differently (`chat_open` and `ziggs_chat_open`). Every one of
+ * the 31 capability definitions follows that one rule, so the key is enough and
+ * a caller cannot accidentally emit a name the surface does not have.
+ */
+export declare function nextCall(env: CapabilityEnv, capabilityKey: string, args: Record<string, unknown> | undefined, why: string): NextCall;
+/**
+ * The other party in a two-party agreement, from the perspective of `selfId`.
+ *
+ * Returns null rather than guessing when the row does not identify one, because
+ * a pre-filled call naming the wrong counterparty is worse than no pre-filled
+ * call: the caller would run it, and it would do something they did not ask for.
+ */
+export declare function peerAgentId(parties: {
+    creatorAgent?: string | null;
+    providerAgent?: string | null;
+} | undefined, selfId: string | undefined): string | null;

package/dist/capabilities/nextCall.js

@@ -0,0 +1,32 @@
+/**
+ * Build a next step naming the tool as the calling surface registers it.
+ *
+ * Takes the capability key, not a tool name, because the two surfaces spell the
+ * same capability differently (`chat_open` and `ziggs_chat_open`). Every one of
+ * the 31 capability definitions follows that one rule, so the key is enough and
+ * a caller cannot accidentally emit a name the surface does not have.
+ */
+export function nextCall(env, capabilityKey, args, why) {
+    return {
+        tool: env.surface === 'mcp' ? `ziggs_${capabilityKey}` : capabilityKey,
+        ...(args && Object.keys(args).length ? { args } : {}),
+        why,
+    };
+}
+/**
+ * The other party in a two-party agreement, from the perspective of `selfId`.
+ *
+ * Returns null rather than guessing when the row does not identify one, because
+ * a pre-filled call naming the wrong counterparty is worse than no pre-filled
+ * call: the caller would run it, and it would do something they did not ask for.
+ */
+export function peerAgentId(parties, selfId) {
+    if (!parties || !selfId)
+        return null;
+    const { creatorAgent, providerAgent } = parties;
+    if (creatorAgent && creatorAgent !== selfId)
+        return creatorAgent;
+    if (providerAgent && providerAgent !== selfId)
+        return providerAgent;
+    return null;
+}

package/dist/capabilities/payments.js

@@ -32,6 +32,7 @@ const grantCaveatParams = {
 export const paymentBalanceCapability = {
     key: 'payment_balance',
     names: { sdk: 'payment_balance', mcp: 'ziggs_payment_balance' },
+    title: 'Check your balance',
     descriptions: {
         sdk: "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds.",
         mcp: "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds.",
@@ -50,6 +51,7 @@ export const paymentBalanceCapability = {
 export const paymentResolveWalletCapability = {
     key: 'payment_resolve_wallet',
     names: { sdk: 'payment_resolve_wallet', mcp: 'ziggs_payment_resolve_wallet' },
+    title: 'Look up a wallet',
     descriptions: {
         sdk: 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.',
         mcp: 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.',
@@ -82,6 +84,7 @@ export const paymentResolveWalletCapability = {
 export const paymentTransferCapability = {
     key: 'payment_transfer',
     names: { sdk: 'payment_transfer', mcp: 'ziggs_payment_transfer' },
+    title: 'Transfer funds',
     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_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.',
@@ -169,6 +172,7 @@ export const paymentTransferCapability = {
 export const paymentWaitForApprovalCapability = {
     key: 'payment_wait_for_approval',
     names: { sdk: 'payment_wait_for_approval', mcp: 'ziggs_payment_wait_for_approval' },
+    title: 'Wait on a payment approval',
     descriptions: {
         sdk: 'Poll a paused transfer (status "approval_required") until the human decides or the timeout passes. Returns executed | rejected | expired | timeout | gone.',
         mcp: 'Poll a paused transfer (status "approval_required") until the human decides or the timeout passes. Returns executed | rejected | expired | timeout | gone. Use for quick decisions (≤2 min); for longer waits, stop and check again next session.',
@@ -207,6 +211,7 @@ export const paymentWaitForApprovalCapability = {
 export const paymentHoldCapability = {
     key: 'payment_hold',
     names: { sdk: 'payment_hold', mcp: 'ziggs_payment_hold' },
+    title: 'Hold funds in escrow',
     descriptions: {
         sdk: 'Pre-authorize (escrow) funds without moving them. Use to reserve payment at agreement formation; release with payment_release once work is complete or to refund if work is cancelled.',
         mcp: "Pre-authorize (escrow) funds without moving them. Use to reserve payment at agreement formation; release with ziggs_payment_release once work is complete, or refund if it's cancelled.",
@@ -246,6 +251,7 @@ export const paymentHoldCapability = {
 export const paymentReleaseCapability = {
     key: 'payment_release',
     names: { sdk: 'payment_release', mcp: 'ziggs_payment_release' },
+    title: 'Settle or refund a hold',
     descriptions: {
         sdk: "Settle or refund an escrow hold. Use action='complete' to transfer held funds to toWalletId (work done), or action='refund' to return funds to the sender (work cancelled).",
         mcp: "Settle or refund an escrow hold. action='complete' transfers held funds to toWalletId (work done); action='refund' returns funds to the sender (work cancelled).",
@@ -296,6 +302,7 @@ export const paymentReleaseCapability = {
 export const paymentIssueGrantCapability = {
     key: 'payment_issue_grant',
     names: { sdk: 'payment_issue_grant', mcp: 'ziggs_payment_issue_grant' },
+    title: 'Issue a spend grant',
     descriptions: {
         sdk: "Issue a payment grant delegating bounded spend from the operator's wallet to an agent holder. Caveats bound what the holder can do (max_amount, daily_budget, allowed_recipients, expiry). The holder spends by passing the grantId as paymentGrantId on transfers.",
         mcp: "Issue a payment grant delegating bounded spend from the operator's wallet to an agent holder. Caveats bound what the holder can do (max_amount, daily_budget, allowed_recipients, expiry). The holder spends by passing the grantId as paymentGrantId on transfers.",
@@ -329,6 +336,7 @@ export const paymentIssueGrantCapability = {
 export const paymentAttenuateGrantCapability = {
     key: 'payment_attenuate_grant',
     names: { sdk: 'payment_attenuate_grant', mcp: 'ziggs_payment_attenuate_grant' },
+    title: 'Pass on a tighter spend grant',
     descriptions: {
         sdk: 'Re-delegate a payment grant you hold to another agent with TIGHTER caveats (narrowing only — the child can never exceed the parent). Use to pass a bounded spend slice to a sub-agent.',
         mcp: 'Re-delegate a payment grant you hold to another agent with TIGHTER caveats (narrowing only — the child can never exceed the parent). Use to pass a bounded spend slice to a sub-agent.',
@@ -372,6 +380,7 @@ export const paymentAttenuateGrantCapability = {
 export const paymentRevokeGrantCapability = {
     key: 'payment_revoke_grant',
     names: { sdk: 'payment_revoke_grant', mcp: 'ziggs_payment_revoke_grant' },
+    title: 'Revoke a spend grant',
     descriptions: {
         sdk: 'Revoke a payment grant (and its attenuated children). The holder can no longer spend under it.',
         mcp: 'Revoke a payment grant (and its attenuated children). The holder can no longer spend under it.',

package/dist/capabilities/types.d.ts

@@ -59,6 +59,15 @@ export interface CapabilityDefinition {
         sdk: string;
         mcp: string;
     };
+    /**
+     * Human-readable label a host shows instead of the raw `rail_verb` name.
+     * Required: a tool with no title displays as its wire name, and the
+     * connector directory rejects the surface for it. One title for both
+     * surfaces — the wire name differs per surface, the action it performs
+     * does not. Phrase it as that action, and keep it product copy: this is
+     * what a person reads in the tool picker.
+     */
+    title: string;
     /**
      * Tool description per surface. Kept side by side deliberately: wording may
      * reference surface-local tool names and MCP delegate-protocol guidance, but

package/package.json

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