@ziggs-ai/api-client 0.14.0 → 0.14.2

package/dist/capabilities/agreements.d.ts

@@ -1,4 +1,17 @@
-import { type CapabilityDefinition } from './types.js';
+import type { ClaimedKind } from '../http/AgreementClient.js';
+import type { Agreement } from '../types.js';
+import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
+/**
+ * One claim result shape for both surfaces. The SDK protocol runner used to
+ * return `{agreement, kind}` while MCP returned `{status, kind, message,
+ * agreement}` — same HTTP call, two answers.
+ */
+export declare function presentClaimResult(agreement: Agreement, kind: ClaimedKind, env: CapabilityEnv): {
+    status: string;
+    kind: ClaimedKind;
+    message: string;
+    agreement: Agreement;
+};
 /**
  * the one claim verb. Requests, standing offers, and link invites
  * are all open broadcasts; claiming any of them is this call. The respond

package/dist/capabilities/agreements.js

@@ -9,6 +9,46 @@ function claimedWhat(kind) {
         return 'Hand-off claimed — the pinned agent works FOR you.';
     return 'Request claimed — you provide the work.';
 }
+/**
+ * One claim result shape for both surfaces. The SDK protocol runner used to
+ * return `{agreement, kind}` while MCP returned `{status, kind, message,
+ * agreement}` — same HTTP call, two answers.
+ */
+export function presentClaimResult(agreement, kind, env) {
+    if (kind === 'link') {
+        return {
+            status: 'linked',
+            kind,
+            message: `Link invite claimed — you are now linked. ${linkIsReachOnly(env)}`,
+            agreement,
+        };
+    }
+    if (agreement?.status !== 'active') {
+        const held = (agreement?.approvals ?? []).find((a) => a.status === 'pending');
+        const approveUrl = `${webAppOrigin(env)}/app/agreements/${agreement.agreementId}`;
+        const remedy = held?.heldReason === 'contact-basis'
+            ? 'This is a first engagement with that counterparty — your human approves once; a standing link covers it after that.'
+            : 'Claiming for a job your human already approved activates at once — name the job with mandateAgreementId.';
+        return {
+            status: 'claimed',
+            kind,
+            message: `${claimedWhat(kind)} It is not active yet: the formation is waiting on ` +
+                'human approval, so nothing can be created under it until that lands. ' +
+                `Your human can approve it here: ${approveUrl} — ${remedy}`,
+            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.'
+            : kind === 'hand-off'
+                ? 'Hand-off claimed — the pinned agent works FOR you: you are the customer (and the payer when priced), never the worker. Spawn work under it with the task-create tool.'
+                : 'Request claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
+        agreement,
+    };
+}
 /**
  * the one claim verb. Requests, standing offers, and link invites
  * are all open broadcasts; claiming any of them is this call. The respond
@@ -45,46 +85,7 @@ export const agreementClaimCapability = {
         const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env), typeof declaredMandate === 'string' && declaredMandate
             ? { mandateAgreementId: declaredMandate }
             : {});
-        if (kind === 'link') {
-            return {
-                status: 'linked',
-                kind,
-                message: `Link invite claimed — you are now linked. ${linkIsReachOnly(env)}`,
-                agreement,
-            };
-        }
-        // A claim only activates when the claimer could consent for its own side.
-        // When it did not, say what the row actually says — and hand over the link
-        // where the human answers: the assistant is the human's only
-        // screen and it is refused if it tries to answer for them, so the URL IS
-        // the remaining loop. The held reason picks the one sentence that helps:
-        // a formation gate has the mandate remedy; a contact gate is a one-time
-        // stranger ask that a standing link retires.
-        if (agreement?.status !== 'active') {
-            const held = (agreement?.approvals ?? []).find((a) => a.status === 'pending');
-            const approveUrl = `${webAppOrigin(env)}/app/agreements/${agreement.agreementId}`;
-            const remedy = held?.heldReason === 'contact-basis'
-                ? 'This is a first engagement with that counterparty — your human approves once; a standing link covers it after that.'
-                : 'Claiming for a job your human already approved activates at once — name the job with mandateAgreementId.';
-            return {
-                status: 'claimed',
-                kind,
-                message: `${claimedWhat(kind)} It is not active yet: the formation is waiting on ` +
-                    'human approval, so nothing can be created under it until that lands. ' +
-                    `Your human can approve it here: ${approveUrl} — ${remedy}`,
-                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.'
-                : kind === 'hand-off'
-                    ? 'Hand-off claimed — the pinned agent works FOR you: you are the customer (and the payer when priced), never the worker. Spawn work under it with the task-create tool.'
-                    : 'Request claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
-            agreement,
-        };
+        return presentClaimResult(agreement, kind, env);
     },
 };
 export const AGREEMENT_CAPABILITIES = [agreementClaimCapability];

package/dist/capabilities/artifacts.d.ts

@@ -20,12 +20,13 @@ export declare const listArtifactsCapability: CapabilityDefinition;
  */
 export declare const shareArtifactCapability: CapabilityDefinition;
 /**
- * attach an artifact you already have to a chat or a task.
+ * attach an artifact you already have to a chat, a task, or an agreement.
  *
  * The other half of "record now, decide where later". Attaching confers nothing
  * by itself: it puts the artifact inside the container, and that container's
- * audience can read it from then on. Use this to publish to a room or bind a
- * deliverable to a task; use artifact_share to hand it to ONE agent instead.
+ * audience can read it from then on. Use this to publish to a room, bind a
+ * deliverable to a task, or restore agreement scope after a free-standing
+ * record; use artifact_share to hand it to ONE agent instead.
  */
 export declare const attachArtifactCapability: CapabilityDefinition;
 /**

package/dist/capabilities/artifacts.js

@@ -133,15 +133,19 @@ export const recordArtifactCapability = {
             'Set visibility explicitly. For a finished deliverable, set contentType=result and pass ' +
             'taskId to bind it to the task. A heavy deliverable belongs in an artifact rather than pasted into a message. ' +
             ARTIFACT_RECORD_INLINE_CAP,
-        mcp: 'Write an artifact — text (text) or a file (filename + mime + contentBase64; presign, upload ' +
+        mcp: 
+        // Canonical for ziggs-mcp (tools.ts must not override). Last paragraph is
+        // PROTOCOL.reporting copied verbatim — api-client cannot import ziggs-mcp;
+        // record-artifact-teaching.test.ts gates the live tool against both.
+        'Write an artifact — text (text) or a file (filename + mime + contentBase64; presign, upload ' +
             'and completion all happen inside this one call, so there is no separate upload dance). ' +
             'Scope is optional — pass agreementId or chatId to record it into that ' +
             'scope, pass taskId alone to bind a deliverable to its task, or pass no scope at all for a ' +
             'free-standing artifact that is yours until you attach or share it. Never guess a scope: ' +
             'recording with none always succeeds. Set visibility explicitly. ' +
             'For a finished deliverable, set contentType=result and pass taskId to bind it to the task. ' +
-            'When the work rides a task, close it with ziggs_task_set_result too: that is what the next agent reads from its own inbox. ' +
-            ARTIFACT_RECORD_INLINE_CAP,
+            ARTIFACT_RECORD_INLINE_CAP +
+            ' Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.',
     },
     annotation: 'write',
     params: {
@@ -188,7 +192,8 @@ export const recordArtifactCapability = {
         },
         idempotencyKey: {
             type: 'string',
-            description: 'Optional dedup key: a redelivered record with the same key no-ops and returns the original artifact. Derive it deterministically (e.g. from the source event + step) — not a random value — so a crash-replay reproduces it.',
+            description: 'Optional dedup key: a redelivered record with the same key no-ops and returns the original artifact. Derive it deterministically (e.g. from the source event + step) — not a random value — so a crash-replay reproduces it. ' +
+                'A task-bound result artifact is one deliverable per task: recordReport keys it `task-result:<taskId>`, so a retry after a partial failure reuses that row. A later revision of the same task still returns the original artifact — change the key if you mean a new deliverable.',
         },
     },
     needsAgentId: true,
@@ -350,30 +355,37 @@ export const shareArtifactCapability = {
     },
 };
 /**
- * attach an artifact you already have to a chat or a task.
+ * attach an artifact you already have to a chat, a task, or an agreement.
  *
  * The other half of "record now, decide where later". Attaching confers nothing
  * by itself: it puts the artifact inside the container, and that container's
- * audience can read it from then on. Use this to publish to a room or bind a
- * deliverable to a task; use artifact_share to hand it to ONE agent instead.
+ * audience can read it from then on. Use this to publish to a room, bind a
+ * deliverable to a task, or restore agreement scope after a free-standing
+ * record; use artifact_share to hand it to ONE agent instead.
  */
 export const attachArtifactCapability = {
     key: 'artifact_attach',
     names: { sdk: 'artifact_attach', mcp: 'ziggs_artifact_attach' },
-    title: 'Attach an artifact to a chat or task',
+    title: 'Attach to a chat, task, or agreement',
     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 ' +
-            'recorded with no scope) reaches an audience. Pass exactly one of chatId or taskId. Everyone ' +
-            'in that chat, or party to that task, can read it from then on; attaching gives you nothing ' +
-            'new yourself. You must already be able to read the artifact AND belong to the container. ' +
-            'To hand it to ONE specific agent without opening a chat, use ziggs_artifact_share instead.',
+        sdk: 'Attach an artifact you can read to a chat, a task, or an agreement. Everyone in that chat / party to that task or agreement 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, a task, or an agreement — the way a free-standing ' +
+            'artifact (one you recorded with no scope) reaches an audience, including restoring ' +
+            'agreement scope after a drop. Pass exactly one of chatId, taskId, or agreementId. Everyone ' +
+            'in that chat, or party to that task or agreement, can read it from then on; attaching ' +
+            'gives you nothing new yourself. You must already be able to read the artifact AND belong ' +
+            'to the container. To hand it to ONE specific agent without opening a chat, use ' +
+            'ziggs_artifact_share instead.',
     },
     annotation: 'write',
     params: {
         artifactId: { type: 'string', required: true, description: 'Artifact to attach' },
         chatId: { type: 'string', description: 'Chat to attach it to' },
         taskId: { type: 'string', description: 'Task to attach it to' },
+        agreementId: {
+            type: 'string',
+            description: 'Agreement to attach it to (POST /agreements/:id/artifacts)',
+        },
         role: {
             type: 'string',
             enum: ['input', 'output'],
@@ -388,8 +400,10 @@ export const attachArtifactCapability = {
             throw new Error('artifactId is required');
         const chatId = args['chatId'];
         const taskId = args['taskId'];
-        if (!!chatId === !!taskId) {
-            throw new Error('Pass exactly one of chatId or taskId');
+        const agreementId = args['agreementId'];
+        const named = [chatId, taskId, agreementId].filter(Boolean).length;
+        if (named !== 1) {
+            throw new Error('Pass exactly one of chatId, taskId, or agreementId');
         }
         const role = args['role'] ?? 'output';
         if (role !== 'input' && role !== 'output') {
@@ -406,6 +420,15 @@ export const attachArtifactCapability = {
                 note: `Everyone in chat ${chatId} can now read artifact ${artifactId}.`,
             };
         }
+        if (agreementId) {
+            await client.attachToAgreement(artifactId, agreementId);
+            return {
+                ok: true,
+                artifactId,
+                agreementId,
+                note: `Artifact ${artifactId} is attached to agreement ${agreementId}; the agreement's parties can read it.`,
+            };
+        }
         await client.attachToTask(artifactId, taskId, role);
         return {
             ok: true,

package/dist/capabilities/discovery.js

@@ -5,15 +5,15 @@ export const agentSearchCapability = {
     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_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.',
+        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 your own org-mates. A link does NOT make the other person\'s agents findable — how they staff their side is theirs, and it changes without telling anyone; reach a linked person through the link itself (link_list gives their addressable peer id, then chat_open). Passing an EXACT agent id resolves that one agent even if unpublished/private, when you can reach it. 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 your own org-mates — so you can find a teammate\'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. A link does NOT make the other person\'s agents findable: a link makes the PERSON addressable, never their staffing list. To reach someone you are linked with, take their peer id from ziggs_link_list and ziggs_chat_open with that; their agents become known to you by turning up in rooms. Passing an EXACT agent id resolves that one agent even if unpublished/private, when you can reach it — an id you cannot reach comes back `reachability: "restricted"` with no name/profile, and a linked person\'s unpublished agent is one of those. 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`, `managed`, or `engaged`; it is not a blanket "published" label. Use returned agentId in grant/issue tools — do not guess ids.',
     },
     annotation: 'read-only',
     params: {
         query: {
             type: 'string',
             required: true,
-            description: 'Keyword/natural-language search (published store + your org-mates + your linked delegates) OR an exact agent id (resolves that agent even if unpublished, when you can reach it)',
+            description: 'Keyword/natural-language search (published store + your org-mates) OR an exact agent id (resolves that agent even if unpublished, when you can reach it)',
         },
         limit: { type: 'number', description: 'Max results (default server-side)' },
         minScore: { type: 'number', description: 'Minimum match score filter' },
@@ -37,10 +37,12 @@ export const agentSearchCapability = {
             return {
                 count: 0,
                 agents: [],
-                searched: ['published store', 'your org-mates', 'your linked delegates'],
+                searched: ['published store', 'your org-mates'],
                 hint: 'Zero hits means no agent profile matched these terms — discovery itself is up. ' +
                     'Matching is lexical against agent name/description/tags, so try shorter or different keywords. ' +
-                    'If you already know the agent, pass its exact agent id as the query to resolve it directly.',
+                    'If you already know the agent, pass its exact agent id as the query to resolve it directly. ' +
+                    'Searching for someone you are LINKED with will always miss: a link makes the person addressable, ' +
+                    'not their agents. Take their peer id from link_list and open a chat with the person instead.',
             };
         }
         return { count: result.agents.length, agents: result.agents };

package/dist/capabilities/index.d.ts

@@ -1,10 +1,11 @@
 export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
-export { nextCall, peerPrincipalId, peerPrincipalForCourier, type NextCall, } from './nextCall.js';
+export { nextCall, peerPrincipalId, type NextCall, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
-export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
+export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
+export { TASK_CAPABILITIES, listTasksCapability } from './tasks.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';

package/dist/capabilities/index.js

@@ -1,10 +1,11 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
-export { nextCall, peerPrincipalId, peerPrincipalForCourier, } from './nextCall.js';
+export { nextCall, peerPrincipalId, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
-export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
+export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
+export { TASK_CAPABILITIES, listTasksCapability } from './tasks.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';

package/dist/capabilities/introductions.js

@@ -78,7 +78,7 @@ export const redeemIntroductionCapability = {
         return {
             introduction: intro,
             message: staged
-                ? `Redeemed. ${intro.from.label} now has a pending link with you (${intro.agreementId}). It becomes real when both people approve it — a link is reach only, and shares no context by itself.`
+                ? `Redeemed. A pending link with org ${intro.from.orgId} (${intro.from.agentId ?? 'no agent id'}) is staged (${intro.agreementId}). The display name they claimed is self-chosen and unverified. The link becomes real when both people approve it — a link is reach only, and shares no context by itself.`
                 : intro.outcome === 'already_teammates'
                     ? 'Redeemed, and there was nothing to link: you already answer to the same org or the same person. Talk to them directly.'
                     : 'Redeemed. You two are already linked, so nothing new was proposed.',

package/dist/capabilities/links.js

@@ -1,5 +1,5 @@
 import { createLink, listAgreements } from '../http/AgreementClient.js';
-import { nextCall, peerPrincipalForCourier, } from './nextCall.js';
+import { nextCall } from './nextCall.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
 export function webAppOrigin(env) {
@@ -31,7 +31,7 @@ function inviteShareUrl(env, agreementId) {
  */
 export function linkIsReachOnly(env) {
     return env.surface === 'mcp'
-        ? 'A link is reach-only — it shares no context on its own. Open a chat with the PERSON on the other side (ziggs_chat_open, participantId = the peer principal): delivery lands in their mailbox and whoever runs that side picks it up, which is not yours to choose. Opening the room admits both sides to read and post from then on. To share context that already exists, issue a grant on it with ziggs_context_issue_grant or share a slice of one you hold with ziggs_context_delegate.'
+        ? 'A link is reach-only — it shares no context on its own. Open a chat with the PERSON on the other side (ziggs_chat_open, participantId = that link\'s `peer.id`): delivery lands in their mailbox and whoever runs that side picks it up, which is not yours to choose. Use `peer.id`, never a principal out of `parties` — those are display faces, and chat_open refuses a face because it names no single party. Opening the room admits both sides to read and post from then on. To share context that already exists, issue a grant on it with ziggs_context_issue_grant or share a slice of one you hold with ziggs_context_delegate.'
         : 'A link is reach-only — it shares no context on its own. Open a chat with the PERSON on the other side; delivery lands in their mailbox and whoever runs that side picks it up, which is not yours to choose. Opening the room admits both sides to it from then on. To share context that already exists, share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one.';
 }
 const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
@@ -53,8 +53,8 @@ export const listLinksCapability = {
     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. The two principals on a link are the two PEOPLE it connects; the actor slots record which agent carried the paperwork and are not addresses. Connect with someone new using link_propose; end a link 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, and parties — where parties.creator.principal and parties.provider.principal are the two PEOPLE the link connects. The actor slots record which agent carried the paperwork and are not addresses: message the person. Approve pending links via ziggs_agreement_respond; connect with someone new using ziggs_link_propose; 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. Each active link carries `peer` — the person on the other side, by an id you can address (`peer.id`) plus their name. Address them with that. The principals in `parties` are display faces masked per viewer, and the actor slots record which agent carried the paperwork; neither is an address. Connect with someone new using link_propose; end a link 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, and — on links where you are one of the two sides — `peer`, the person on the other side by an addressable id (`peer.id`) and name. To reach them, pass `peer.id` to ziggs_chat_open. Do NOT address anything out of `parties`: those principals are display faces masked per viewer, and the actor slots are courier info, so both are refused as addresses. Approve pending links via ziggs_agreement_respond; connect with someone new using ziggs_link_propose; end one with ziggs_agreement_revoke.',
     },
     annotation: 'read-only',
     params: {
@@ -77,27 +77,26 @@ export const listLinksCapability = {
         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.
         //
-        // The peer is a PERSON. This used to pre-fill the peer's `actor`, which is
-        // courier info and null on most links, so the suggestion either named an
-        // agent that is no longer a door or silently disappeared. It fills in only
-        // when this agent's own stamp identifies which side is ours; otherwise the
-        // peer is named in prose and read off the rows below, because a pre-filled
-        // call naming the wrong party would get run.
+        // The peer id comes from the server now. Two earlier attempts read it off
+        // `parties` here and both were wrong: the peer's `actor` is courier info,
+        // null on any link two people formed from the web; the peer's `principal`
+        // is display state, masked to a `psn_` face across an org boundary — which
+        // is every link — and chat_open refuses a face. Neither could be fixed on
+        // this side, because the addressable id is not in the payload to find. It
+        // is now, as `peer`, resolved relative to whoever asked.
         const readPlan = [];
         let unnamedPeers = 0;
         for (const link of active.slice(0, 3)) {
-            const peer = peerPrincipalForCourier(link.parties, env.creds.agentId);
+            const peer = link.peer?.id;
             if (!peer) {
                 unnamedPeers += 1;
                 continue;
             }
-            readPlan.push(nextCall(env, 'chat_open', { participantId: peer }, 'open a room with this linked peer — a link alone carries no context'));
+            readPlan.push(nextCall(env, 'chat_open', { participantId: peer }, `open a room with ${link.peer?.name ?? 'this linked peer'} — a link alone carries no context`));
         }
         if (unnamedPeers > 0) {
-            readPlan.push(nextCall(env, 'chat_open', undefined, 'open a room with a linked peer: participantId is the other principal on the link (parties.creator / parties.provider), which is a person'));
+            readPlan.push(nextCall(env, 'chat_open', undefined, 'open a room with a linked peer: participantId is that link\'s `peer.id`. Do NOT pass a principal out of `parties` — those are display faces and chat_open refuses them'));
         }
         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'));

package/dist/capabilities/nextCall.d.ts

@@ -54,22 +54,3 @@ export declare function nextCall(env: CapabilityEnv, capabilityKey: string, args
  * call: the caller would run it, and it would do something they did not ask for.
  */
 export declare function peerPrincipalId(parties: AgreementParties | undefined, selfId: string | undefined): string | null;
-/**
- * The peer's principal, located by finding MY side rather than by knowing my
- * own principal id.
- *
- * An agent knows its own agent id and not the id of the person it answers for,
- * so it cannot ask {@link peerPrincipalId} which of two people it is. What it
- * CAN recognise is its own courier stamp: if my agent id is in one side's
- * `actor`, that side is mine and the other side's principal is the peer.
- *
- * Note the difference from the bug this replaced. Reading the peer's `actor` as
- * the peer's address was wrong — those slots are courier info, null on most
- * links, and never a door. Reading MY OWN `actor` to work out which side I am on
- * is sound, because I am comparing against an id I hold.
- *
- * Returns null when neither side carries my stamp, which is the common case for
- * a link two people formed from the web. No pre-filled call is the right answer
- * there: naming the wrong counterparty would get run.
- */
-export declare function peerPrincipalForCourier(parties: AgreementParties | undefined, myAgentId: string | undefined): string | null;

package/dist/capabilities/nextCall.js

@@ -45,34 +45,3 @@ export function peerPrincipalId(parties, selfId) {
         return provider;
     return null;
 }
-/**
- * The peer's principal, located by finding MY side rather than by knowing my
- * own principal id.
- *
- * An agent knows its own agent id and not the id of the person it answers for,
- * so it cannot ask {@link peerPrincipalId} which of two people it is. What it
- * CAN recognise is its own courier stamp: if my agent id is in one side's
- * `actor`, that side is mine and the other side's principal is the peer.
- *
- * Note the difference from the bug this replaced. Reading the peer's `actor` as
- * the peer's address was wrong — those slots are courier info, null on most
- * links, and never a door. Reading MY OWN `actor` to work out which side I am on
- * is sound, because I am comparing against an id I hold.
- *
- * Returns null when neither side carries my stamp, which is the common case for
- * a link two people formed from the web. No pre-filled call is the right answer
- * there: naming the wrong counterparty would get run.
- */
-export function peerPrincipalForCourier(parties, myAgentId) {
-    if (!parties || !myAgentId)
-        return null;
-    const mineIsCreator = parties.creator?.actor === myAgentId;
-    const mineIsProvider = parties.provider?.actor === myAgentId;
-    // Both sides stamped with me is one estate on both ends, not a peer.
-    if (mineIsCreator === mineIsProvider)
-        return null;
-    const peer = mineIsCreator
-        ? parties.provider?.principal
-        : parties.creator?.principal;
-    return peer && peer !== myAgentId ? peer : null;
-}

package/dist/capabilities/tasks.d.ts

@@ -0,0 +1,9 @@
+import { type CapabilityDefinition } from './types.js';
+/**
+ * One list-tasks verb. MCP and the hosted SDK both used to re-declare the
+ * same GET /tasks filters; assignedToMe vs assignedTo precedence then
+ * drifted independently. The handler is the single place that resolves
+ * those shorthands onto the HTTP query.
+ */
+export declare const listTasksCapability: CapabilityDefinition;
+export declare const TASK_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/tasks.js

@@ -0,0 +1,60 @@
+import { listTasks } from '../http/TaskClient.js';
+import { fullCreds } from './types.js';
+/**
+ * One list-tasks verb. MCP and the hosted SDK both used to re-declare the
+ * same GET /tasks filters; assignedToMe vs assignedTo precedence then
+ * drifted independently. The handler is the single place that resolves
+ * those shorthands onto the HTTP query.
+ */
+export const listTasksCapability = {
+    key: 'task_list',
+    names: { sdk: 'task_list', mcp: 'ziggs_task_list' },
+    title: 'List tasks',
+    descriptions: {
+        sdk: 'List tasks reachable by this agent (GET /tasks). Scope follows the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else.',
+        mcp: 'List tasks reachable by the acting agent (GET /tasks). Scope is determined by the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else.',
+    },
+    annotation: 'read-only',
+    params: {
+        state: {
+            type: 'string',
+            description: 'Filter by state: active, completed, failed, cancelled',
+        },
+        cursor: {
+            type: 'string',
+            description: 'Opaque cursor from a prior nextCursor',
+        },
+        limit: {
+            type: 'number',
+            description: 'Max rows (server default when omitted)',
+        },
+        assignedTo: {
+            type: 'string',
+            description: 'Filter to tasks assigned to this agent/user id',
+        },
+        createdByMe: {
+            type: 'boolean',
+            description: 'Tasks YOU created — the work you handed out to others. This is the check before delegating: assignedToMe lists only what was handed TO you, so a job you already assigned does not appear there and you would assign it twice.',
+        },
+        assignedToMe: {
+            type: 'boolean',
+            description: "Shorthand for assignedTo=<this agent's id>. Takes precedence over assignedTo when both are set.",
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const assignedTo = args['assignedToMe']
+            ? creds.agentId
+            : args['assignedTo'];
+        const createdBy = args['createdByMe'] ? creds.agentId : undefined;
+        return listTasks({
+            state: args['state'],
+            cursor: args['cursor'],
+            limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
+            assignedTo,
+            ...(createdBy ? { createdBy } : {}),
+        }, creds);
+    },
+};
+export const TASK_CAPABILITIES = [listTasksCapability];

package/dist/http/AgreementClient.js

@@ -54,6 +54,12 @@ export function linkSummary(a) {
             provider: side(a.parties?.provider),
             proposedTo: side(a.parties?.proposedTo),
         },
+        // The one id on a link that can be acted on. `parties` is display state —
+        // masked per viewer, so the peer arrives as a face that every addressing
+        // verb refuses — which left a link summary carrying nobody you could open a
+        // chat with. Dropping it here is what that looked like: the server sent the
+        // peer and the allow-list ate it before any caller saw it.
+        ...(a.peer ? { peer: a.peer } : {}),
         ...(a.description ? { description: a.description } : {}),
         // Seat bookkeeping on an open invite — link state, not commerce.
         ...(a.linkInvite ? { linkInvite: a.linkInvite } : {}),

package/dist/http/ArtifactsClient.d.ts

@@ -140,14 +140,12 @@ export declare class ArtifactsClient {
         artifactId?: string;
     }>;
     /**
-     * attach an existing artifact to a chat or a task.
+     * attach an existing artifact to a chat, a task, or an agreement.
      *
      * Attaching confers nothing on its own: it places the artifact inside the
-     * container, and that container's audience (chat members / task parties) can
-     * read it from then on. This is how a free-standing artifact reaches anyone
-     * without granting it to one specific agent.
-     *
-     * The agreement equivalent already existed as POST /agreements/:id/artifacts.
+     * container, and that container's audience (chat members / task or agreement
+     * parties) can read it from then on. This is how a free-standing artifact
+     * reaches anyone without granting it to one specific agent.
      */
     attachToChat(artifactId: string, chatId: string): Promise<{
         success: boolean;
@@ -155,6 +153,9 @@ export declare class ArtifactsClient {
     attachToTask(artifactId: string, taskId: string, role?: 'input' | 'output'): Promise<{
         success: boolean;
     }>;
+    attachToAgreement(artifactId: string, agreementId: string): Promise<{
+        success: boolean;
+    }>;
     /**
      * File artifact rail — presign PUT, then client uploads bytes to `uploadUrl`,
      * then {@link completeFile}. Optional `content` / `contentBase64` performs the

package/dist/http/ArtifactsClient.js

@@ -167,14 +167,12 @@ export class ArtifactsClient {
         }
     }
     /**
-     * attach an existing artifact to a chat or a task.
+     * attach an existing artifact to a chat, a task, or an agreement.
      *
      * Attaching confers nothing on its own: it places the artifact inside the
-     * container, and that container's audience (chat members / task parties) can
-     * read it from then on. This is how a free-standing artifact reaches anyone
-     * without granting it to one specific agent.
-     *
-     * The agreement equivalent already existed as POST /agreements/:id/artifacts.
+     * container, and that container's audience (chat members / task or agreement
+     * parties) can read it from then on. This is how a free-standing artifact
+     * reaches anyone without granting it to one specific agent.
      */
     async attachToChat(artifactId, chatId) {
         return this._attach(`/chats/${encodeURIComponent(chatId)}/artifacts`, {
@@ -187,6 +185,9 @@ export class ArtifactsClient {
             role,
         });
     }
+    async attachToAgreement(artifactId, agreementId) {
+        return this._attach(`/agreements/${encodeURIComponent(agreementId)}/artifacts`, { artifactId });
+    }
     /**
      * File artifact rail — presign PUT, then client uploads bytes to `uploadUrl`,
      * then {@link completeFile}. Optional `content` / `contentBase64` performs the

package/dist/http/ContextGrantsClient.js

@@ -1,6 +1,24 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { throwApiError } from '../shared/apiError.js';
+/**
+ * Shared post-parse for delegate and author-share: both endpoints return either
+ * a minted grant or a pending_approval request the owner must approve.
+ */
+function parseGrantOrPending(body, expectedFrom) {
+    const parsed = JSON.parse(body);
+    if (parsed.status === 'pending_approval' && parsed.agreementId) {
+        return {
+            status: 'pending_approval',
+            agreementId: parsed.agreementId,
+            ownerId: parsed.ownerId,
+        };
+    }
+    if (!parsed.grant?.grantId) {
+        throw new Error(`Invalid response: expected { grant } or { status: "pending_approval" } from ${expectedFrom}`);
+    }
+    return { status: 'granted', grant: parsed.grant };
+}
 /**
  * context grant management — list / issue / delegate / revoke.
  */
@@ -57,20 +75,9 @@ export class ContextGrantsClient {
         if (!res.ok) {
             throwApiError(res, body, `delegateGrant failed: ${res.status} ${res.statusText}`);
         }
-        const parsed = JSON.parse(body);
         // Re-granting a grant whose original owner is a different party does not
         // mint — it opens a request that owner must approve.
-        if (parsed.status === 'pending_approval' && parsed.agreementId) {
-            return {
-                status: 'pending_approval',
-                agreementId: parsed.agreementId,
-                ownerId: parsed.ownerId,
-            };
-        }
-        if (!parsed.grant?.grantId) {
-            throw new Error('Invalid response: expected { grant } or { status: "pending_approval" } from POST /context/grants/:id/delegate');
-        }
-        return { status: 'granted', grant: parsed.grant };
+        return parseGrantOrPending(body, 'POST /context/grants/:id/delegate');
     }
     /**
      * expand a grant you hold into the chat/agreement ids inside its
@@ -119,18 +126,7 @@ export class ContextGrantsClient {
         if (!res.ok) {
             throwApiError(res, body, `shareArtifact failed: ${res.status} ${res.statusText}`);
         }
-        const parsed = JSON.parse(body);
-        if (parsed.status === 'pending_approval' && parsed.agreementId) {
-            return {
-                status: 'pending_approval',
-                agreementId: parsed.agreementId,
-                ownerId: parsed.ownerId,
-            };
-        }
-        if (!parsed.grant?.grantId) {
-            throw new Error('Invalid response: expected { grant } or { status: "pending_approval" } from POST /context/artifacts/:id/share');
-        }
-        return { status: 'granted', grant: parsed.grant };
+        return parseGrantOrPending(body, 'POST /context/artifacts/:id/share');
     }
     async revokeGrant(grantId) {
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(grantId)}`, {

package/dist/http/IntroductionsClient.d.ts

@@ -1,15 +1,26 @@
 /** What became of one hello. `expired` is derived by the server, not stored. */
 export type IntroductionStatus = 'open' | 'redeemed' | 'declined' | 'revoked' | 'expired';
 export type IntroductionOutcome = 'link_pending' | 'already_teammates' | 'already_linked';
+export interface IntroductionFrom {
+    orgId: string;
+    agentId: string | null;
+    agentCreatedAt?: string | null;
+    claimedLabel?: {
+        text: string;
+        selfChosen: boolean;
+        verified: boolean;
+    };
+    /**
+     * Same text as claimedLabel.text. Not identity — anyone can pick it.
+     */
+    label: string;
+}
 export interface IntroductionView {
     token: string;
     status: IntroductionStatus;
     outcome: IntroductionOutcome | null;
-    from: {
-        label: string;
-        agentId: string | null;
-        orgId: string;
-    };
+    notice?: string;
+    from: IntroductionFrom;
     venue: string | null;
     venueRef: string | null;
     note: string | null;

package/dist/http/OrgsClient.d.ts

@@ -27,13 +27,23 @@ export type OrgResolution = {
  * match. Ambiguous names return the candidates rather than guessing.
  */
 export declare function resolveOrgSelector(orgs: MyOrg[], selector: string): OrgResolution;
-/** MCP OAuth auto-provisioned delegate id prefix. */
-export declare const MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX = "claude-delegate--";
+/**
+ * MCP OAuth auto-provisioned delegate id prefix.
+ *
+ * The backend stopped classifying delegates by their id and now reads a stamp
+ * on the agent row, which is what freed the prefix to drop the vendor name. A
+ * client holds credentials, not rows, so this is still a shape test — but it is
+ * a shape test against a NAME, and the only thing it decides is which access
+ * endpoint to read. It said `delegate--` until the ids were renamed;
+ * left alone, every delegate session would have fallen through to the hosted
+ * reader and reported the wrong org and connection state.
+ */
+export declare const MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX = "delegate--";
 /** True when `agentId` is an inbound MCP OAuth auto-provisioned delegate. */
 export declare function isMcpOAuthDelegateAgentId(agentId: string): boolean;
 /**
  * runtime acting org from the server (self-hire / agent
- * row): GET /agents/claude-delegate/access. Moved here from ziggs-mcp's inline
+ * row): GET /agents/delegate/access. Moved here from ziggs-mcp's inline
  * fetch ( "one client for every surface").
  *
  * Only valid for MCP OAuth Claude-delegate sessions. Hosted / fleet
@@ -44,7 +54,7 @@ export declare function fetchDelegateAccess(creds: Creds, baseUrl?: string): Pro
  * session access for hosted / fleet impersonation (owner key +
  * X-Agent-Id, or an agent-scoped key that is not a Claude OAuth delegate).
  *
- * `GET /agents/claude-delegate/access` refuses those credentials (or reports
+ * `GET /agents/delegate/access` refuses those credentials (or reports
  * disconnected), even though every other tool works. The credential's tenant
  * is already on the actor (`GET /orgs/me` → `activeOrgId`).
  */

package/dist/http/OrgsClient.js

@@ -42,29 +42,39 @@ export function resolveOrgSelector(orgs, selector) {
         return { status: 'ambiguous', matches: byName };
     return { status: 'not-found' };
 }
-/** MCP OAuth auto-provisioned delegate id prefix. */
-export const MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX = 'claude-delegate--';
+/**
+ * MCP OAuth auto-provisioned delegate id prefix.
+ *
+ * The backend stopped classifying delegates by their id and now reads a stamp
+ * on the agent row, which is what freed the prefix to drop the vendor name. A
+ * client holds credentials, not rows, so this is still a shape test — but it is
+ * a shape test against a NAME, and the only thing it decides is which access
+ * endpoint to read. It said `delegate--` until the ids were renamed;
+ * left alone, every delegate session would have fallen through to the hosted
+ * reader and reported the wrong org and connection state.
+ */
+export const MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX = 'delegate--';
 /** True when `agentId` is an inbound MCP OAuth auto-provisioned delegate. */
 export function isMcpOAuthDelegateAgentId(agentId) {
     return !!agentId && agentId.startsWith(MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX);
 }
 /**
  * runtime acting org from the server (self-hire / agent
- * row): GET /agents/claude-delegate/access. Moved here from ziggs-mcp's inline
+ * row): GET /agents/delegate/access. Moved here from ziggs-mcp's inline
  * fetch ( "one client for every surface").
  *
  * Only valid for MCP OAuth Claude-delegate sessions. Hosted / fleet
  * impersonation must use {@link fetchHostedAgentAccess}.
  */
 export async function fetchDelegateAccess(creds, baseUrl) {
-    const url = `${baseUrl || getBackendUrl()}/agents/claude-delegate/access`;
+    const url = `${baseUrl || getBackendUrl()}/agents/delegate/access`;
     const res = await fetch(url, {
         method: 'GET',
         headers: buildOperatorHeaders(creds.operatorKey, creds.agentId),
     });
     const body = await res.text().catch(() => '');
     if (!res.ok) {
-        throwApiError(res, body, `GET /agents/claude-delegate/access failed: ${res.status}`);
+        throwApiError(res, body, `GET /agents/delegate/access failed: ${res.status}`);
     }
     return body ? JSON.parse(body) : {};
 }
@@ -72,7 +82,7 @@ export async function fetchDelegateAccess(creds, baseUrl) {
  * session access for hosted / fleet impersonation (owner key +
  * X-Agent-Id, or an agent-scoped key that is not a Claude OAuth delegate).
  *
- * `GET /agents/claude-delegate/access` refuses those credentials (or reports
+ * `GET /agents/delegate/access` refuses those credentials (or reports
  * disconnected), even though every other tool works. The credential's tenant
  * is already on the actor (`GET /orgs/me` → `activeOrgId`).
  */

package/dist/http/index.d.ts

@@ -12,7 +12,7 @@ export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSna
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { IntroductionsClient } from './IntroductionsClient.js';
-export type { IntroductionView, IntroductionStatus, IntroductionOutcome, MintIntroductionInput, } from './IntroductionsClient.js';
+export type { IntroductionView, IntroductionFrom, IntroductionStatus, IntroductionOutcome, MintIntroductionInput, } from './IntroductionsClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export type { ListGrantsQuery, ListGrantsResult, UnreadableRail } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';

package/dist/types.d.ts

@@ -168,6 +168,18 @@ export interface Agreement {
     engagementKind?: EngagementKind;
     proposalStatus?: ProposalStatus;
     parties?: AgreementParties;
+    /**
+     * On a LINK, the person on the other side by an id you can address.
+     *
+     * `parties` is display state: read across an org boundary a principal comes
+     * back as a `psn_` face, which names no single party and every addressing
+     * verb refuses. This is the same person, resolved server-side relative to
+     * you. Present only when you are one of the two sides.
+     */
+    peer?: {
+        id: string;
+        name: string;
+    };
     approvals?: AgreementApprovalEntry[];
     /** Legacy root-level price — always null in practice. Use money.price instead. */
     price?: number | null;
@@ -175,6 +187,17 @@ export interface Agreement {
     money?: {
         price?: number | null;
         paymentStatus?: string;
+        transactionId?: string | null;
+        /**
+         * Ledger hold for this agreement, or null if paymentStatus says held but
+         * no hold row exists. Amount is cents. Never includes a wallet id.
+         */
+        held?: {
+            amount: number;
+            currency: string;
+            state: 'held' | 'released' | 'refunded';
+            agreementId: string;
+        } | null;
     };
     lifecycle?: string;
     expiresAt?: string;

package/package.json

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