@ziggs-ai/api-client 0.14.0 → 0.14.1

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/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/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/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

@@ -175,6 +175,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.1",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",