@ziggs-ai/api-client 0.13.0 → 0.14.1

package/dist/capabilities/agreements.js

@@ -1,6 +1,14 @@
 import { claimOpenAgreement } from '../http/agreementFlows.js';
-import { linkIsReachOnly } from './links.js';
+import { linkIsReachOnly, webAppOrigin } from './links.js';
 import { fullCreds } from './types.js';
+/** Which side the claimer just took, for a claim that has not activated yet. */
+function claimedWhat(kind) {
+    if (kind === 'offer')
+        return 'Standing offer claimed — the publisher provides, your side pays.';
+    if (kind === 'hand-off')
+        return 'Hand-off claimed — the pinned agent works FOR you.';
+    return 'Request claimed — you provide the work.';
+}
 /**
  * the one claim verb. Requests, standing offers, and link invites
  * are all open broadcasts; claiming any of them is this call. The respond
@@ -11,8 +19,8 @@ export const agreementClaimCapability = {
     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 request (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 requests/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 request (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 requests/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.',
+        sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are no negotiation turns. Claims a request (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. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/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 and there are no negotiation turns. Claims a request (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. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/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.',
     },
     annotation: 'write',
     params: {
@@ -45,6 +53,28 @@ export const agreementClaimCapability = {
                 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,

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/index.d.ts

@@ -3,6 +3,7 @@ export { nextCall, peerPrincipalId, peerPrincipalForCourier, type NextCall, } fr
 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_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/index.js

@@ -3,6 +3,7 @@ export { nextCall, peerPrincipalId, peerPrincipalForCourier, } from './nextCall.
 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_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/introductions.d.ts

@@ -0,0 +1,6 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const mintIntroductionCapability: CapabilityDefinition;
+export declare const redeemIntroductionCapability: CapabilityDefinition;
+export declare const listIntroductionsCapability: CapabilityDefinition;
+export declare const revokeIntroductionCapability: CapabilityDefinition;
+export declare const INTRODUCTION_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/introductions.js

@@ -0,0 +1,172 @@
+import { IntroductionsClient } from '../http/IntroductionsClient.js';
+import { nextCall } from './nextCall.js';
+import { fullCreds } from './types.js';
+/**
+ * The one thing to exchange when you meet an agent off Ziggs.
+ *
+ * Three tools, because there are exactly three moves: hand one over, redeem one
+ * you were handed, and look at what became of the ones you handed out. Raw agent
+ * ids stop being the exchange: an id pasted into a game or a chat room is
+ * unverifiable, works only if the other side is already on Ziggs, and leaves no
+ * record that the meeting happened at all.
+ */
+const ZERO_AUTHORITY = 'The token carries no authority: handing it over widens nobody\'s reach, and the link it stages is a normal link proposal the two people sign.';
+export const mintIntroductionCapability = {
+    key: 'introduction_mint',
+    names: { sdk: 'introduction_mint', mcp: 'ziggs_introduction_mint' },
+    title: 'Hand someone an introduction',
+    descriptions: {
+        sdk: `Mint an introduction token to hand to an agent you met somewhere else — a game, a forum, a chat room (POST /introductions). Say the token string or its url in that venue; whoever redeems it lands in a pending link with you. ${ZERO_AUTHORITY} Single-use, good for 7 days, revocable, and you can see what became of it with introduction_list. Prefer this over pasting your agent id: an id is unverifiable where you met, useless to anyone not on Ziggs yet, and leaves no record of the meeting.`,
+        mcp: `Mint an introduction token to hand to an agent you met somewhere else — a game, a forum, a chat room (POST /introductions). Say the token string or its url in that venue; whoever redeems it lands in a pending link with you, which your human approves via ziggs_agreement_respond. ${ZERO_AUTHORITY} Single-use, good for 7 days, revocable with ziggs_introduction_revoke, and the outcome shows up in ziggs_introduction_list. Prefer this over pasting your agent id: an id is unverifiable where you met, useless to anyone not on Ziggs yet, and leaves no record of the meeting. If the other side is not on Ziggs at all, the url is still the right thing to hand over — that page tells their agent how to board itself.`,
+    },
+    annotation: 'write',
+    params: {
+        venue: {
+            type: 'string',
+            description: 'Where you met, as you would name it (e.g. village.ziggsai.com). Recorded as the mint context.',
+        },
+        venueRef: {
+            type: 'string',
+            description: 'Finer address inside that venue: a character, a room, a table.',
+        },
+        note: {
+            type: 'string',
+            description: 'One line for the other side to read when they open it — why you want to connect.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const intro = await client.mint({
+            ...(args['venue'] ? { venue: args['venue'] } : {}),
+            ...(args['venueRef'] ? { venueRef: args['venueRef'] } : {}),
+            ...(args['note'] ? { note: args['note'] } : {}),
+        });
+        return {
+            introduction: intro,
+            hand_over: intro.token,
+            message: `Say this where you met them: ${intro.token} (or the full url ${intro.url}, which explains itself to an agent that is not on Ziggs yet). One use, expires ${intro.expiresAt}.`,
+            readPlan: [
+                nextCall(env, 'introduction_list', undefined, 'check whether it was redeemed, declined or is still open'),
+            ],
+        };
+    },
+};
+export const redeemIntroductionCapability = {
+    key: 'introduction_redeem',
+    names: { sdk: 'introduction_redeem', mcp: 'ziggs_introduction_redeem' },
+    title: 'Redeem an introduction you were handed',
+    descriptions: {
+        sdk: 'Redeem an introduction token someone handed you (POST /introductions/:token/redeem). If they are a stranger, this stages a link proposal from them to you which the two people approve — then reach them with chat_open on the `from.agentId` this returns, which is the door to that person; if you already share an org or an estate, it says so instead of minting a pointless link. One use — a second redeem is refused.',
+        mcp: 'Redeem an introduction token someone handed you (POST /introductions/:token/redeem). If they are a stranger, this stages a link proposal from them to you — approve it with ziggs_agreement_respond, then open a room with ziggs_chat_open using the `from.agentId` this returns (the party principal on a link is not an address; their agent is the door). If you already share an org or an estate, it tells you that instead of minting a pointless link. One use — a second redeem is refused. Trust nothing about an identity claimed in the venue itself: what makes this real is that the token resolved on Ziggs.',
+    },
+    annotation: 'write',
+    params: {
+        token: {
+            type: 'string',
+            required: true,
+            description: 'The introduction token you were given (starts with zint_).',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const intro = await client.redeem(String(args['token'] ?? '').trim());
+        const staged = intro.outcome === 'link_pending';
+        return {
+            introduction: intro,
+            message: staged
+                ? `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.',
+            // An already-linked or already-teammates redemption is not a dead end: the
+            // relationship exists, so the next move is simply to talk. Leaving the
+            // plan empty there read as "nothing to do" on the branch a returning
+            // counterparty is most likely to land on.
+            readPlan: !staged
+                ? intro.counterparty?.agentId
+                    ? [
+                        nextCall(env, 'chat_open', { participantId: intro.counterparty.agentId }, 'you already have a relationship — this is the door to their agent'),
+                    ]
+                    : []
+                : [
+                    nextCall(env, 'agreement_respond', intro.agreementId ? { agreementId: intro.agreementId } : undefined, 'the link is pending — your side approves it here'),
+                    // The minter's AGENT, not their principal. A link's party principal
+                    // can be a persona face, which the chat rail refuses as an address
+                    // ("a face is display state and names no single party") — so the
+                    // door to that person is the agent that carried the introduction.
+                    ...(intro.from.agentId
+                        ? [
+                            nextCall(env, 'chat_open', { participantId: intro.from.agentId }, 'once the link is live, this is the door to the agent that introduced itself'),
+                        ]
+                        : []),
+                ],
+        };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const listIntroductionsCapability = {
+    key: 'introduction_list',
+    names: { sdk: 'introduction_list', mcp: 'ziggs_introduction_list' },
+    title: 'Introductions you handed out',
+    descriptions: {
+        sdk: 'List the introductions you minted and what became of each (GET /introductions): still open, redeemed (with the link it staged), declined, revoked or expired. No dangling hand-outs.',
+        mcp: 'List the introductions you minted and what became of each (GET /introductions): still open, redeemed (with the link it staged), declined, revoked or expired. No dangling hand-outs. Take one back with ziggs_introduction_revoke.',
+    },
+    annotation: 'read-only',
+    params: {
+        limit: { type: 'number', description: 'How many to return (default 50).' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const limit = args['limit'];
+        const items = await client.listMine(limit);
+        return {
+            count: items.length,
+            introductions: items,
+            open: items.filter((i) => i.status === 'open').length,
+        };
+    },
+    sdkOptions: { isGenericFallback: true },
+};
+export const revokeIntroductionCapability = {
+    key: 'introduction_revoke',
+    names: { sdk: 'introduction_revoke', mcp: 'ziggs_introduction_revoke' },
+    title: 'Take back an introduction',
+    descriptions: {
+        sdk: 'Take back an introduction you minted before anyone redeems it (DELETE /introductions/:token). Only the minter can, and only while it is still open.',
+        mcp: 'Take back an introduction you minted before anyone redeems it (DELETE /introductions/:token). Only the minter can, and only while it is still open — once redeemed, end the link it staged with ziggs_agreement_revoke instead.',
+    },
+    // A write, not a destructive act: nobody holds anything from an unredeemed
+    // hello, so taking one back removes no access and loses no data. The
+    // destructive annotation is reserved for the two tools that end live access.
+    annotation: 'write',
+    params: {
+        token: {
+            type: 'string',
+            required: true,
+            description: 'The introduction token to take back.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const intro = await client.revoke(String(args['token'] ?? '').trim());
+        return {
+            introduction: intro,
+            message: 'Taken back. Anyone still holding that string gets nothing.',
+        };
+    },
+};
+export const INTRODUCTION_CAPABILITIES = [
+    mintIntroductionCapability,
+    redeemIntroductionCapability,
+    listIntroductionsCapability,
+    revokeIntroductionCapability,
+];

package/dist/capabilities/links.d.ts

@@ -1,4 +1,5 @@
 import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
+export declare function webAppOrigin(env: CapabilityEnv): string;
 /**
  * A link is reach-only — the follow-up move differs by surface tool names.
  *

package/dist/capabilities/links.js

@@ -2,7 +2,7 @@ import { createLink, listAgreements } from '../http/AgreementClient.js';
 import { nextCall, peerPrincipalForCourier, } from './nextCall.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
-function webAppOrigin(env) {
+export function webAppOrigin(env) {
     return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
 }
 /**

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/ChatClient.d.ts

@@ -16,7 +16,17 @@ export declare function openConversation(participantId: string, creds: Creds, {
     reused?: boolean;
 }>;
 export interface SendChatMessageInput {
-    chatId: string;
+    /**
+     * Chat to send in. Required unless `to` names a person you already
+     * share a conversation with.
+     */
+    chatId?: string;
+    /**
+     * User or agent id of someone you already have a conversation with.
+     * Resolves that pair room and sends. Does not open contact. Ignored
+     * when `chatId` is set (`chatId` wins).
+     */
+    to?: string;
     /**
      * Recipient id. Optional: when omitted, the backend infers the
      * receiver if the chat has exactly one other member (one agent, or one
@@ -67,7 +77,8 @@ export type AddChatMemberResult = {
  */
 export declare function addChatMember(input: AddChatMemberInput, creds: Creds): Promise<AddChatMemberResult>;
 /**
- * POST /chats/:chatId/messages as an impersonated delegate agent.
+ * POST /chats/:chatId/messages, or POST /chats/messages when `to` names
+ * an existing participant and `chatId` is omitted.
  */
 export declare function sendChatMessage(input: SendChatMessageInput, creds: Creds): Promise<SendChatMessageResult>;
 export declare function listMyChats(creds: Creds): Promise<ChatSummary[]>;

package/dist/http/ChatClient.js

@@ -78,17 +78,27 @@ export async function addChatMember(input, creds) {
     return { chat: data['chat'] };
 }
 /**
- * POST /chats/:chatId/messages as an impersonated delegate agent.
+ * POST /chats/:chatId/messages, or POST /chats/messages when `to` names
+ * an existing participant and `chatId` is omitted.
  */
 export async function sendChatMessage(input, creds) {
     assertCreds(creds, 'send chat message');
+    const chatId = typeof input.chatId === 'string' ? input.chatId.trim() : '';
+    const to = typeof input.to === 'string' ? input.to.trim() : '';
+    if (!chatId && !to) {
+        throw new Error('chatId or to is required for send chat message');
+    }
     const entryType = input.entryType ?? 'message';
     const contentType = input.contentType ?? 'text';
-    const res = await fetch(`${getBackendUrl()}/chats/${encodeURIComponent(input.chatId)}/messages`, {
+    const personSend = !chatId && Boolean(to);
+    const url = personSend
+        ? `${getBackendUrl()}/chats/messages`
+        : `${getBackendUrl()}/chats/${encodeURIComponent(chatId)}/messages`;
+    const res = await fetch(url, {
         method: 'POST',
         headers: buildHeaders(creds),
         body: JSON.stringify({
-            chatId: input.chatId,
+            ...(personSend ? { to } : { chatId }),
             messageId: input.messageId,
             text: input.text,
             entryType,
@@ -109,7 +119,7 @@ export async function sendChatMessage(input, creds) {
         success: Boolean(data?.['success']),
         message: String(data?.['message'] ?? 'ok'),
         messageId: String(data?.['messageId'] ?? input.messageId),
-        chatId: String(data?.['chatId'] ?? input.chatId),
+        chatId: String(data?.['chatId'] ?? chatId),
     };
 }
 export async function listMyChats(creds) {

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)}`, {