@ziggs-ai/api-client 0.6.3 → 0.8.0

package/dist/capabilities/agreements.js

@@ -10,8 +10,8 @@ export const agreementClaimCapability = {
     key: 'agreement_claim',
     names: { sdk: 'agreement_claim', mcp: 'ziggs_agreement_claim' },
     descriptions: {
-        sdk: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. Find quests/offers with marketplace_view; direct proposals are approved with agreement_respond instead, not claimed.',
-        mcp: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. Find quests/offers with ziggs_marketplace_view; direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
+        sdk: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with marketplace_view; direct proposals are approved with agreement_respond instead, not claimed.',
+        mcp: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with ziggs_marketplace_view; direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
     },
     annotation: 'write',
     params: {
@@ -37,7 +37,9 @@ export const agreementClaimCapability = {
             kind,
             message: kind === 'offer'
                 ? 'Standing offer claimed — the publisher provides, your side pays. Spawn work under it with the task-create tool.'
-                : 'Quest claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
+                : 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.'
+                    : 'Quest claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
             agreement,
         };
     },

package/dist/capabilities/artifacts.d.ts

@@ -1,3 +1,31 @@
 import { type CapabilityDefinition } from './types.js';
 export declare const recordArtifactCapability: CapabilityDefinition;
+/**
+ * ZIG-1037 — the artifacts you wrote, across every scope and none.
+ *
+ * The scope listings (`context_read` via chat / agreement / task) read attach
+ * tables, so a free-standing artifact appears in none of them. This is how an
+ * agent finds what it recorded without naming a container.
+ */
+export declare const listArtifactsCapability: CapabilityDefinition;
+/**
+ * ZIG-1037 — hand one artifact you authored to one other agent.
+ *
+ * Deliberately not part of `context_delegate`: there is no parent grant to
+ * attenuate here. An agent holds no grant over its own output — authorship is
+ * the authority, and it belongs to the agent's owner, which is why a receiver
+ * outside that owner's trust boundary needs their approval. What counts as
+ * "inside" is the shared new-party policy, not a local rule: same owner, same
+ * org, or an active agent link.
+ */
+export declare const shareArtifactCapability: CapabilityDefinition;
+/**
+ * ZIG-1037 — attach an artifact you already have to a chat or a task.
+ *
+ * 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.
+ */
+export declare const attachArtifactCapability: CapabilityDefinition;
 export declare const ARTIFACT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/artifacts.js

@@ -1,4 +1,5 @@
 import { ArtifactsClient } from '../http/ArtifactsClient.js';
+import { ContextGrantsClient } from '../http/ContextGrantsClient.js';
 import { fullCreds } from './types.js';
 /**
  * ZIG-560 teaching: name the result slot on the success path so an agent finds
@@ -20,8 +21,14 @@ export const recordArtifactCapability = {
     key: 'artifact_record',
     names: { sdk: 'artifact_record', mcp: 'ziggs_artifact_record' },
     descriptions: {
-        sdk: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. For a finished deliverable, set content_type=result and pass taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
-        mcp: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. ' +
+        sdk: 'Write an artifact. Scope is optional: pass agreementId or chatId to record it there, ' +
+            'or pass no scope at all to record it as yours alone and attach it somewhere later. ' +
+            'Set visibility explicitly. For a finished deliverable, set content_type=result and pass ' +
+            'taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
+        mcp: 'Write an artifact. 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 content_type=result and pass taskId to bind it to the task. ' +
             'Finished work is the task result — set it with ziggs_task_set_result; never report finished work as a chat message (chat is conversation only).',
     },
@@ -32,16 +39,17 @@ export const recordArtifactCapability = {
             type: 'string',
             required: true,
             enum: ['chat', 'agent-private'],
-            description: 'chat = visible to scope parties; agent-private = your eyes only',
+            description: 'chat = the scope’s parties can read it; agent-private = not shared with them. ' +
+                'Neither is permanent: you can share any artifact later with a specific agent.',
         },
-        chatId: { type: 'string', description: 'Target chat scope' },
+        chatId: { type: 'string', description: 'Optional chat scope' },
         agreementId: {
             type: 'string',
-            description: 'Target agreement scope — for a hire deliverable, prefer this. When both chatId and agreementId are passed, agreementId wins.',
+            description: 'Optional agreement scope — for a hire deliverable, prefer this. When both chatId and agreementId are passed, agreementId wins.',
         },
         taskId: {
             type: 'string',
-            description: 'Optional task — creates a TaskArtifactLink alongside the primary scope link',
+            description: 'Optional task binding. Valid on its own — a task-bound deliverable needs no chat or agreement.',
         },
         content_type: {
             type: 'string',
@@ -58,12 +66,13 @@ export const recordArtifactCapability = {
         // Agreement wins when both scopes arrive. Models naturally pass the chat
         // they are standing in alongside the agreement they deliver under; a hard
         // xor here failed the deliverable at the last step of a finished task
-        // (ZIG-924 dogfood). The backend still enforces exactly-one — we resolve
-        // the ambiguity at the exposed surface instead of erroring.
+        // (ZIG-924 dogfood). The backend accepts at most one — we resolve the
+        // ambiguity at the exposed surface instead of erroring.
         const chatId = agreementId ? undefined : args['chatId'];
-        if (!chatId && !agreementId) {
-            throw new Error('Pass chatId or agreementId');
-        }
+        // ZIG-1037: no scope is legal. The throw that used to live here ("Pass
+        // chatId or agreementId") is the exact failure this ticket removed — it cost
+        // a live agent a turn mid-delivery for naming no container, when the record
+        // itself never needed one.
         const visibility = args['visibility'];
         if (visibility !== 'chat' && visibility !== 'agent-private') {
             throw new Error('visibility must be chat or agent-private');
@@ -91,4 +100,177 @@ export const recordArtifactCapability = {
         };
     },
 };
-export const ARTIFACT_CAPABILITIES = [recordArtifactCapability];
+/**
+ * ZIG-1037 — the artifacts you wrote, across every scope and none.
+ *
+ * The scope listings (`context_read` via chat / agreement / task) read attach
+ * tables, so a free-standing artifact appears in none of them. This is how an
+ * agent finds what it recorded without naming a container.
+ */
+export const listArtifactsCapability = {
+    key: 'artifact_list',
+    names: { sdk: 'artifact_list', mcp: 'ziggs_artifact_list' },
+    descriptions: {
+        sdk: 'List artifacts you authored, in any scope or none — including free-standing ones no scope read can reach. Forward-delta with `after`.',
+        mcp: 'List artifacts YOU authored, across every scope and none. Use this to find something you ' +
+            'recorded free-standing (no chat/agreement/task), which the scope reads cannot return. ' +
+            'To read an artifact someone shared WITH you, use ziggs_context_read with via=artifact:<id>; ' +
+            'to see what has been shared with you, use ziggs_grant_list with scopeKind=artifact.',
+    },
+    annotation: 'read-only',
+    params: {
+        after: {
+            type: 'string',
+            description: 'ISO timestamp — return only artifacts written strictly after this',
+        },
+        limit: { type: 'number', description: 'Page size (server default when omitted)' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        return new ArtifactsClient(creds.operatorKey, creds.agentId).list({ authoredBy: 'me' }, {
+            after: args['after'],
+            limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
+        });
+    },
+};
+/**
+ * ZIG-1037 — hand one artifact you authored to one other agent.
+ *
+ * Deliberately not part of `context_delegate`: there is no parent grant to
+ * attenuate here. An agent holds no grant over its own output — authorship is
+ * the authority, and it belongs to the agent's owner, which is why a receiver
+ * outside that owner's trust boundary needs their approval. What counts as
+ * "inside" is the shared new-party policy, not a local rule: same owner, same
+ * org, or an active agent link.
+ */
+export const shareArtifactCapability = {
+    key: 'artifact_share',
+    names: { sdk: 'artifact_share', mcp: 'ziggs_artifact_share' },
+    descriptions: {
+        sdk: 'Share an artifact you authored with another agent — just that artifact, no chat or agreement. An agent already connected to you (same owner, same org, or an active link) gets it immediately; anyone else is offered to your owner to approve.',
+        mcp: 'Share ONE artifact you authored with another agent, without sharing any chat or agreement ' +
+            'it sits in. Only the authoring agent can call this. A receiver already connected to you — ' +
+            'same owner, same org, or an active link — is granted immediately. Any other agent is ' +
+            'offered to your owner to approve, and the reply is { status: "pending_approval", ' +
+            'agreementId } — nothing is shared until they do. Pass chatId to have that approval appear ' +
+            'in the chat you are working in. The receiver then reads it with ziggs_context_read ' +
+            'via=artifact:<id>.',
+    },
+    annotation: 'write',
+    params: {
+        artifactId: {
+            type: 'string',
+            required: true,
+            description: 'The artifact to share — you must be its author',
+        },
+        holderId: { type: 'string', required: true, description: 'Agent id that receives it' },
+        expiresAt: {
+            type: 'string',
+            description: 'ISO-8601 expiry; omit for the default grant lifetime',
+        },
+        chatId: {
+            type: 'string',
+            description: 'Chat to surface the approval request in, when the receiver’s owner has to approve',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const artifactId = args['artifactId'];
+        if (!artifactId)
+            throw new Error('artifactId is required');
+        const holderId = args['holderId'];
+        if (!holderId)
+            throw new Error('holderId is required');
+        const result = await new ContextGrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).shareArtifact(artifactId, {
+            holderId,
+            expiresAt: args['expiresAt'],
+            chatId: args['chatId'],
+        });
+        if (result.status === 'pending_approval') {
+            return {
+                ok: true,
+                ...result,
+                note: `Not shared yet — ${result.ownerId ?? 'the owner'} must approve agreement ${result.agreementId}.`,
+            };
+        }
+        return {
+            ok: true,
+            ...result,
+            note: `${holderId} can now read artifact ${artifactId} with via=artifact:${artifactId}.`,
+        };
+    },
+};
+/**
+ * ZIG-1037 — attach an artifact you already have to a chat or a task.
+ *
+ * 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.
+ */
+export const attachArtifactCapability = {
+    key: 'artifact_attach',
+    names: { sdk: 'artifact_attach', mcp: 'ziggs_artifact_attach' },
+    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.',
+    },
+    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' },
+        role: {
+            type: 'string',
+            enum: ['input', 'output'],
+            description: 'Task attach only: output (a deliverable, default) or input (something the task consumes). ' +
+                'A link’s role is set once — re-attaching with a different role is refused, not changed.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const artifactId = args['artifactId'];
+        if (!artifactId)
+            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 role = args['role'] ?? 'output';
+        if (role !== 'input' && role !== 'output') {
+            throw new Error('role must be input or output');
+        }
+        const creds = fullCreds(env);
+        const client = new ArtifactsClient(creds.operatorKey, creds.agentId);
+        if (chatId) {
+            await client.attachToChat(artifactId, chatId);
+            return {
+                ok: true,
+                artifactId,
+                chatId,
+                note: `Everyone in chat ${chatId} can now read artifact ${artifactId}.`,
+            };
+        }
+        await client.attachToTask(artifactId, taskId, role);
+        return {
+            ok: true,
+            artifactId,
+            taskId,
+            role,
+            note: `Artifact ${artifactId} is attached to task ${taskId} as ${role}; the task's parties can read it.`,
+        };
+    },
+};
+export const ARTIFACT_CAPABILITIES = [
+    recordArtifactCapability,
+    listArtifactsCapability,
+    shareArtifactCapability,
+    attachArtifactCapability,
+];

package/dist/capabilities/context.js

@@ -1,7 +1,7 @@
 import { ContextReadClient } from '../http/ContextReadClient.js';
 import { ContextGrantsClient, } from '../http/ContextGrantsClient.js';
 import { ContextDiscoveryClient } from '../http/ContextDiscoveryClient.js';
-import { grantCaveat } from '../http/grants.js';
+import { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, } from '../http/grants.js';
 import { fetchMyOrgs, resolveOrgSelector } from '../http/OrgsClient.js';
 import { fullCreds } from './types.js';
 const CONTEXT_READ_TYPES = [
@@ -10,7 +10,10 @@ const CONTEXT_READ_TYPES = [
     'agreements',
     'tasks',
 ];
-const GRANT_SCOPE_KINDS = ['chat', 'agreement', 'org'];
+// ZIG-1037: `artifact` joined the context rail. Delegating an artifact grant
+// onward works (same kind, same id — an exact re-grant); narrowing a container
+// grant DOWN to an artifact inside it is deliberately not supported yet.
+const GRANT_SCOPE_KINDS = CONTEXT_GRANT_SCOPE_KINDS;
 const CONTEXT_TEMPORALS = ['from-now', 'from-start'];
 /**
  * Human/LLM-readable bounds for a context grant. ZIG-646 folded a context
@@ -50,8 +53,8 @@ export const contextReadCapability = {
     key: 'context_read',
     names: { sdk: 'context_read', mcp: 'ziggs_context_read' },
     descriptions: {
-        sdk: 'Read the contents of a scope you already hold a grant for: messages | artifacts | agreements | tasks. Use grant_list first to see which scopes your grants cover, then read through any of them. Cursored; all access is grant-fenced server-side.',
-        mcp: 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id>. Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a `readPlan` with the next page and/or forward-delta call pre-filled (after=this page\'s latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.',
+        sdk: 'Read the contents of a scope you already hold a grant for: messages | artifacts | agreements | tasks. Use grant_list first to see which scopes your grants cover, then read through any of them. For artifacts you can also name one directly with via=artifact:<id> — the only way to read an artifact attached to no chat, agreement or task. Cursored; all access is grant-fenced server-side.',
+        mcp: 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id> — plus via=artifact:<id> for artifacts, a point read of one named artifact and the ONLY way to read one that is attached to no container (e.g. an artifact someone shared with you; ziggs_grant_list scopeKind=artifact shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a `readPlan` with the next page and/or forward-delta call pre-filled (after=this page\'s latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.',
     },
     annotation: 'read-only',
     params: {
@@ -64,7 +67,7 @@ export const contextReadCapability = {
         via: {
             type: 'string',
             required: true,
-            description: 'Scope entry you hold, e.g. chat:<id>, agreement:<id>, task:<id>',
+            description: 'Scope entry you hold, e.g. chat:<id>, agreement:<id>, task:<id>. For type=artifacts also artifact:<id> to read that one artifact.',
         },
         cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
         after: { type: 'string', description: 'ISO timestamp for forward-delta (messages/artifacts)' },
@@ -109,8 +112,8 @@ export const contextExpandReachCapability = {
     key: 'context_expand_reach',
     names: { sdk: 'context_expand_reach', mcp: 'ziggs_context_expand_reach' },
     descriptions: {
-        sdk: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the actual { chats, agreements } (ids + labels only, no content) that scope covers — feed an id to context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
-        mcp: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
+        sdk: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the actual { chats, agreements } (ids + labels only, no content) that scope covers — feed an id to context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. An artifact-scope grant returns empty by design — the grant IS one artifact, so read it directly with context_read via=artifact:<the scope id>. Holder-only, grant-fenced.',
+        mcp: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. An artifact-scope grant returns empty by design — that grant IS a single artifact, so do not read the empty map as a dead grant: read the artifact with ziggs_context_read via=artifact:<the scope id>. Holder-only, grant-fenced.',
     },
     annotation: 'read-only',
     params: {
@@ -179,7 +182,7 @@ export const contextDelegateCapability = {
         }
         const scopeKind = args['scopeKind'];
         if (!GRANT_SCOPE_KINDS.includes(scopeKind)) {
-            throw new Error('scopeKind must be chat, agreement, or org');
+            throw new Error(`scopeKind must be one of ${GRANT_SCOPE_KINDS.join(', ')}`);
         }
         // ZIG-941 #6 — an org scope may be named rather than pasted as org_… id.
         let scopeId = args['scopeId'];

package/dist/capabilities/grants.d.ts

@@ -1,7 +1,7 @@
 import { type CapabilityDefinition } from './types.js';
 /**
  * ZIG-893 — the single "what authority do I hold?" tool. One name, every rail
- * (context chat/agreement/org, connection, wallet), holder-scoped,
+ * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend (ZIG-956) so a short
  * list is never presented as complete when the key can't read a rail.
  */

package/dist/capabilities/grants.js

@@ -1,12 +1,11 @@
 import { GrantsClient } from '../http/GrantsClient.js';
+import { GRANT_SCOPE_KINDS, } from '../http/grants.js';
 import { fullCreds } from './types.js';
-const SCOPE_KINDS = [
-    'chat',
-    'agreement',
-    'org',
-    'connection',
-    'wallet',
-];
+// BOTH the tool's param enum and its validator, so a missing kind makes the
+// filter the description advertises fail validation. Derived from the canonical
+// list next to the type rather than restated, because that is exactly how
+// `artifact` came to be advertised but not accepted.
+const SCOPE_KINDS = GRANT_SCOPE_KINDS;
 const HEALTHS = ['active', 'expired', 'revoked'];
 function parseScopeKinds(raw) {
     if (raw == null)
@@ -24,7 +23,7 @@ function parseScopeKinds(raw) {
 }
 /**
  * ZIG-893 — the single "what authority do I hold?" tool. One name, every rail
- * (context chat/agreement/org, connection, wallet), holder-scoped,
+ * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend (ZIG-956) so a short
  * list is never presented as complete when the key can't read a rail.
  */
@@ -32,15 +31,15 @@ export const listGrantsCapability = {
     key: 'grant_list',
     names: { sdk: 'grant_list', mcp: 'ziggs_grant_list' },
     descriptions: {
-        sdk: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor. Pair with context_read to read through a context grant, or context_expand_reach to enumerate a scope.',
-        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. Pass a grantId to ziggs_context_read to pin a specific grant, or ziggs_context_expand_reach to enumerate a scope.',
+        sdk: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor. Pair with context_read to read through a context grant, or context_expand_reach to enumerate a scope.',
+        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. Pass a grantId to ziggs_context_read to pin a specific grant, or ziggs_context_expand_reach to enumerate a scope.',
     },
     annotation: 'read-only',
     params: {
         scopeKind: {
             type: 'array',
             items: { type: 'string', enum: SCOPE_KINDS },
-            description: 'Rail filter (repeatable): chat | agreement | org (context) | connection | wallet. Omit for every rail you can read.',
+            description: 'Rail filter (repeatable): chat | agreement | org | artifact (context) | connection | wallet. Omit for every rail you can read.',
         },
         health: {
             type: 'string',

package/dist/capabilities/index.d.ts

@@ -7,5 +7,5 @@ export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/index.js

@@ -7,5 +7,5 @@ export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/links.js

@@ -1,53 +1,22 @@
 import { createAgreement, listAgreements } from '../http/AgreementClient.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
-/** Public Streamable-HTTP MCP endpoint; OAuth is discovered from it (RFC 9728). */
-const ZIGGS_MCP_URL = 'https://mcp.ziggsai.com/mcp';
 function webAppOrigin(env) {
     return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
 }
 /**
- * The second form an invite travels in: text the recipient pastes into their
- * own assistant, which then connects itself and claims the invite. The claim
- * URL alone only helps someone who already has Ziggs and an assistant wired
- * up, so hand the caller both and let it pick per recipient.
+ * The one thing an invite travels as: `/connect/<inviteId>`.
  *
- * The account question comes FIRST, and the answer is always the claim URL —
- * never 'Create account' on the MCP consent screen. Signup is invite-gated and
- * only the claim URL carries the invite that waives it; the consent screen's
- * signup button carries nothing, and nothing in an MCP OAuth handshake can
- * carry it for them (the client builds its authorize request from RFC 8414/9728
- * discovery, so a query param on the pasted server URL never reaches us). So a
- * recipient new to Ziggs who lets their assistant lead used to hit a hard 403
- * with no way back. Ordering is the whole fix: the URL both signs them up AND
- * claims, leaving the assistant less to do, not more.
- *
- * Keep in step with the web app's copy of this text (frontend
- * src/lib/links/inviteShare.ts) — same instructions, two surfaces.
+ * There used to be two forms — this URL plus a block of instructions to paste
+ * into the recipient's assistant — and the caller had to explain which was
+ * which and pick per recipient. That block now lives on the page itself, which
+ * is public and server-rendered: a person reads it, and an assistant handed the
+ * same URL fetches it and finds the MCP server address, the claim tool and the
+ * invite id in the markup. One link, both readers, nothing to keep in step
+ * across two repos.
  */
-function invitePasteText(agreementId, claimUrl) {
-    return [
-        'Connect me to Ziggs and accept this agent link invite.',
-        '',
-        'First ask me: do I already have a Ziggs account?',
-        '',
-        `  If no, or I am not sure — open this in a browser: ${claimUrl}`,
-        '  That creates my account and accepts the link in one step, and needs no',
-        "  invite code. Do NOT send me to 'Create account' on the Ziggs consent",
-        '  screen instead — signup there is gated and will reject me. Once I am',
-        '  back, continue from step 1 to connect yourself; step 2 is already done.',
-        '',
-        '  If yes — start at step 1.',
-        '',
-        `1. Add this MCP server: ${ZIGGS_MCP_URL}`,
-        '   It speaks Streamable HTTP and uses OAuth — pasting the URL is enough,',
-        '   but I may need to approve a consent screen in my browser.',
-        `2. Once connected, call the tool ziggs_agreement_claim with agreementId "${agreementId}".`,
-        '3. Then tell me who I am linked with, and what they can and cannot see.',
-        '',
-        'If you cannot add MCP servers yourself, tell me exactly where to paste that',
-        "URL in my assistant's settings, then continue from step 2.",
-    ].join('\n');
+function inviteShareUrl(env, agreementId) {
+    return `${webAppOrigin(env)}/connect/${agreementId}`;
 }
 /**
  * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
@@ -101,8 +70,8 @@ export const createLinkInviteCapability = {
     key: 'link_create_invite',
     names: { sdk: 'link_create_invite', mcp: 'ziggs_link_create_invite' },
     descriptions: {
-        sdk: "Create a shareable OPEN link invite (bilateral agent-to-agent trust) when you do NOT have the counterparty's agent id (e.g. connecting across orgs). Creates an open link agreement proposed to everyone; the recipient forms the link by claiming the returned inviteId with agreement_claim. Set maxClaims to let several people claim the same link — each gets their own separate connection. When you DO have the agent id, propose the link directly instead: agreement_propose with engagementKind \"link\" and proposedTo = that id.",
-        mcp: 'Create a shareable OPEN link invite (bilateral agent-to-agent trust, NOT a third-party service connection — see ziggs_connection_list for that) when you do NOT have the counterparty\'s agent id (e.g. connecting across orgs). Creates an open link agreement (POST /agreements {engagementKind:"link"}, proposedTo:"everyone"). Share the returned inviteId (agreementId) out-of-band; the recipient forms the link by calling ziggs_agreement_claim — neither side pastes an agent id. Set maxClaims to share ONE link with several people; each claimer gets their own separate connection, not a group. Revoke via ziggs_agreement_revoke to disable. When you DO have the agent id, propose the link directly instead: ziggs_agreement_propose with engagementKind "link" and proposedTo = that id.',
+        sdk: "Create a shareable OPEN link invite (bilateral agent-to-agent trust) when you do NOT have the counterparty's agent id (e.g. connecting across orgs). Creates an open link agreement proposed to everyone and returns shareUrl — one public page that is the entire invite, for a person or for their assistant. Set maxClaims to let several people claim the same link — each gets their own separate connection. When you DO have the agent id, propose the link directly instead: agreement_propose with engagementKind \"link\" and proposedTo = that id.",
+        mcp: 'Create a shareable OPEN link invite (bilateral agent-to-agent trust, NOT a third-party service connection — see ziggs_connection_list for that) when you do NOT have the counterparty\'s agent id (e.g. connecting across orgs). Creates an open link agreement (POST /agreements {engagementKind:"link"}, proposedTo:"everyone") and returns shareUrl: one public page that is the entire invite — the recipient accepts from it with no account, and their assistant can read the connect instructions off the same URL. Give the human that link and nothing else. Set maxClaims to share ONE link with several people; each claimer gets their own separate connection, not a group. Revoke via ziggs_agreement_revoke to disable. When you DO have the agent id, propose the link directly instead: ziggs_agreement_propose with engagementKind "link" and proposedTo = that id.',
     },
     annotation: 'write',
     params: {
@@ -123,7 +92,7 @@ export const createLinkInviteCapability = {
             description: args['message'],
             ...(maxClaims == null ? {} : { maxClaims }),
         }, fullCreds(env));
-        const claimUrl = `${webAppOrigin(env)}/app/link-invites/${agreement.agreementId}`;
+        const shareUrl = inviteShareUrl(env, agreement.agreementId);
         const seats = agreement.linkInvite?.maxClaims ?? 1;
         const seatNote = seats > 1
             ? `valid 7 days and claimable by up to ${seats} people (each gets their own separate connection — not a group)`
@@ -131,13 +100,12 @@ export const createLinkInviteCapability = {
         return {
             status: 'open',
             inviteId: agreement.agreementId,
-            claimUrl,
+            shareUrl,
             maxClaims: seats,
             seatsRemaining: seats - (agreement.linkInvite?.claimsUsed ?? 0),
-            pasteText: invitePasteText(agreement.agreementId, claimUrl),
             message: env.surface === 'mcp'
-                ? `Open link invite created, ${seatNote}. Give the human BOTH forms and say which is which: claimUrl is the one that always works — a recipient with no Ziggs account signs up straight from it, no beta code needed, and it accepts the link in the same step. pasteText is for a recipient who would rather their own assistant do the wiring; it starts by sending them to claimUrl if they have no account yet, since signup on the MCP consent screen is gated and would reject them. Either way the recipient needs their own assistant connected before the link carries anything. No agent id needed on either side.`
-                : `Open link invite created, ${seatNote}. claimUrl is the one that always works — a recipient with no Ziggs account signs up straight from it, no beta code needed, and it accepts the link in the same step. pasteText is for a recipient whose own assistant does the wiring; it sends them to claimUrl first if they have no account, since signup on the consent screen is gated. Either way they need an assistant connected before the link carries anything. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
+                ? `Open link invite created, ${seatNote}. Give the human shareUrl and nothing else — it is the whole invite. A recipient with no Ziggs account signs up straight from that page, no beta code needed, and accepting the link is part of the same step; a recipient who would rather their own assistant do the wiring can hand it the same URL, because the page carries the MCP server address and the claim instructions in its markup. Either way the recipient needs their own assistant connected before the link carries anything.`
+                : `Open link invite created, ${seatNote}. shareUrl is the whole invite: a recipient with no Ziggs account signs up straight from that page and accepts the link in the same step, and an assistant handed the same URL reads the connect instructions off it. They still need an assistant connected before the link carries anything. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
             agreement: linkSummary(agreement),
         };
     },

package/dist/http/AgreementClient.js

@@ -1,7 +1,8 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, ApiError } from '../types.js';
+import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget } from '../types.js';
+import { throwApiError } from '../shared/apiError.js';
 // Lazy: read at call time so dotenv loaded after this module is imported
 // still takes effect. Baking it at module-load time would freeze the URL
 // before the caller's dotenv.config() runs.
@@ -21,20 +22,6 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
-function parseErrorMessage(responseBody, defaultMessage) {
-    if (!responseBody)
-        return defaultMessage;
-    try {
-        const d = JSON.parse(responseBody);
-        return d['details'] || d['error'] || d['message'] || defaultMessage;
-    }
-    catch {
-        return responseBody || defaultMessage;
-    }
-}
-function throwApiError(response, responseBody, defaultMessage) {
-    throw new ApiError(parseErrorMessage(responseBody, defaultMessage), response.status, responseBody);
-}
 export async function proposeAgreement(proposalData, creds) {
     if (!proposalData)
         throw new Error('Proposal data is required for proposal creation');
@@ -124,19 +111,28 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
     if (!agreement) {
         throw new Error(`Agreement ${agreementId} not found`);
     }
+    const partyId = resolveMyPendingApprovalPartyId(agreement, {
+        ownerUserId: opts.ownerUserId,
+        agentId: creds.agentId,
+    });
     const proposedTo = agreement.parties?.proposedTo;
     if (isBroadcastTarget(proposedTo) || isBroadcastTarget(agreement.parties?.payer)) {
         // ZIG-1021: respond is approve/reject on DIRECT proposals only. An open
         // broadcast (quest, standing offer, link invite) has no per-recipient
-        // approval slot — one recipient can neither approve nor reject it
-        // (ZIG-719); the move is to claim it, which has its own verb now.
-        throw new Error(`Agreement ${agreementId} is an open broadcast and has no personal approval slot — respond cannot ${action} it. Claim it with the claim tool (agreement_claim / ziggs_agreement_claim), or ignore it to pass.`);
+        // approval slot — a BYSTANDER can neither approve nor reject it
+        // (ZIG-719); their move is to claim it, which has its own verb.
+        //
+        // ZIG-1077: with one exception — the caller who HOLDS a pending approval
+        // on the row. A hand-off pins its provider and that provider's consent
+        // is a real ledger slot even on an open broadcast (ZIG-1059); this guard
+        // used to reject before looking, so the provider could not consent
+        // through ANY surface and the hand-off sat unclaimable forever. The
+        // backend keeps a consented broadcast OPEN for claims.
+        if (!partyId) {
+            throw new Error(`Agreement ${agreementId} is an open broadcast and has no personal approval slot — respond cannot ${action} it. Claim it with the claim tool (agreement_claim / ziggs_agreement_claim), or ignore it to pass.`);
+        }
     }
-    const partyId = resolveMyPendingApprovalPartyId(agreement, {
-        ownerUserId: opts.ownerUserId,
-        agentId: creds.agentId,
-    });
-    if (!partyId) {
+    else if (!partyId) {
         throw new Error(`No pending approval entry for this operator on agreement ${agreementId}`);
     }
     return approveAgreementAsParty(agreementId, partyId, action === 'approve' ? 'approved' : 'rejected', creds);

package/dist/http/ArtifactsClient.d.ts

@@ -7,6 +7,13 @@ export interface ListArtifactsOptions {
 export interface ListArtifactsQuery {
     chatId?: string;
     agreementId?: string;
+    taskId?: string;
+    /**
+     * ZIG-1037 — `'me'` lists artifacts YOU authored, in any scope or none. The
+     * only listing that surfaces a free-standing artifact, since the others read
+     * attach tables. Mutually exclusive with the scope filters.
+     */
+    authoredBy?: 'me';
 }
 export interface ListArtifactsResult {
     artifacts: unknown[];
@@ -84,6 +91,32 @@ export declare class ArtifactsClient {
     writeStrict(input: WriteArtifactInput): Promise<{
         artifactId?: string;
     }>;
+    /**
+     * ZIG-1037 — attach an existing artifact to a chat or a task.
+     *
+     * 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.
+     */
+    attachToChat(artifactId: string, chatId: string): Promise<{
+        success: boolean;
+    }>;
+    attachToTask(artifactId: string, taskId: string, role?: 'input' | 'output'): Promise<{
+        success: boolean;
+    }>;
+    private _attach;
+    /**
+     * ZIG-1037 — at most one container, and none is fine.
+     *
+     * This used to demand exactly one, which is what made a deliverable fail at the
+     * last step when the model had not worked out which container it was standing
+     * in. A write with no scope is now a free-standing artifact; `taskId` alone
+     * binds it to a task. Both containers at once is still a mistake worth naming,
+     * since only one of them would take effect.
+     */
     private _assertScopeXor;
     private _headers;
 }

package/dist/http/ArtifactsClient.js

@@ -1,5 +1,6 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
+import { throwApiError } from '../shared/apiError.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
@@ -38,14 +39,19 @@ export class ArtifactsClient {
         this.agentId = agentId;
     }
     async list(q, opts = {}) {
-        if ((q.chatId && q.agreementId) || (!q.chatId && !q.agreementId)) {
-            throw new Error('ArtifactsClient.list: pass exactly one of chatId or agreementId');
+        const selectors = [q.chatId, q.agreementId, q.taskId, q.authoredBy].filter(Boolean);
+        if (selectors.length !== 1) {
+            throw new Error('ArtifactsClient.list: pass exactly one of chatId, agreementId, taskId, or authoredBy');
         }
         const url = new URL(`${getBackendUrl()}/artifacts`);
         if (q.chatId)
             url.searchParams.set('chatId', q.chatId);
         if (q.agreementId)
             url.searchParams.set('agreementId', q.agreementId);
+        if (q.taskId)
+            url.searchParams.set('taskId', q.taskId);
+        if (q.authoredBy)
+            url.searchParams.set('authoredBy', q.authoredBy);
         if (opts.after)
             url.searchParams.set('after', opts.after);
         if (opts.limit != null)
@@ -53,7 +59,7 @@ export class ArtifactsClient {
         const res = await fetch(url.toString(), { headers: this._headers() });
         if (!res.ok) {
             const body = await res.text().catch(() => '');
-            throw new Error(`ArtifactsClient.list ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+            throwApiError(res, body, `listArtifacts failed: ${res.status} ${res.statusText}`);
         }
         return (await res.json());
     }
@@ -118,7 +124,7 @@ export class ArtifactsClient {
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`POST /artifacts ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+            throwApiError(res, body, `recordArtifact failed: ${res.status} ${res.statusText}`);
         }
         try {
             const parsed = body ? JSON.parse(body) : {};
@@ -128,9 +134,51 @@ export class ArtifactsClient {
             return {};
         }
     }
+    /**
+     * ZIG-1037 — attach an existing artifact to a chat or a task.
+     *
+     * 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.
+     */
+    async attachToChat(artifactId, chatId) {
+        return this._attach(`/chats/${encodeURIComponent(chatId)}/artifacts`, {
+            artifactId,
+        });
+    }
+    async attachToTask(artifactId, taskId, role = 'output') {
+        return this._attach(`/tasks/${encodeURIComponent(taskId)}/artifacts`, {
+            artifactId,
+            role,
+        });
+    }
+    async _attach(path, body) {
+        const res = await fetch(`${getBackendUrl()}${path}`, {
+            method: 'POST',
+            headers: this._headers(),
+            body: JSON.stringify(body),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, text, `attachArtifact failed: ${res.status} ${res.statusText}`);
+        }
+        return { success: true };
+    }
+    /**
+     * ZIG-1037 — at most one container, and none is fine.
+     *
+     * This used to demand exactly one, which is what made a deliverable fail at the
+     * last step when the model had not worked out which container it was standing
+     * in. A write with no scope is now a free-standing artifact; `taskId` alone
+     * binds it to a task. Both containers at once is still a mistake worth naming,
+     * since only one of them would take effect.
+     */
     _assertScopeXor(input) {
-        if ((input.chatId && input.agreementId) || (!input.chatId && !input.agreementId)) {
-            throw new Error('ArtifactsClient.write: pass exactly one of chatId or agreementId');
+        if (input.chatId && input.agreementId) {
+            throw new Error('ArtifactsClient.write: pass at most one of chatId or agreementId');
         }
     }
     _headers() {

package/dist/http/ChatClient.js

@@ -1,7 +1,7 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { ApiError } from '../types.js';
+import { throwApiError } from '../shared/apiError.js';
 function buildHeaders(creds) {
     return {
         'content-type': 'application/json',
@@ -15,19 +15,6 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
-function throwApiError(response, responseBody, defaultMessage) {
-    let message = defaultMessage;
-    if (responseBody) {
-        try {
-            const d = JSON.parse(responseBody);
-            message = d['details'] || d['error'] || d['message'] || defaultMessage;
-        }
-        catch {
-            message = responseBody || defaultMessage;
-        }
-    }
-    throw new ApiError(message, response.status, responseBody);
-}
 export async function openConversation(participantId, creds) {
     if (!participantId)
         throw new Error('participantId is required for openConversation');

package/dist/http/ContextGrantsClient.d.ts

@@ -1,6 +1,11 @@
 import 'dotenv/config';
 import type { GrantView } from './grants.js';
-export type ContextGrantScopeKind = 'chat' | 'agreement' | 'org';
+/**
+ * ZIG-1037 added `artifact` — the narrowest context scope: one specific artifact,
+ * shared without sharing any chat or agreement it sits in. Still the context
+ * rail, not a new grant primitive.
+ */
+export type ContextGrantScopeKind = 'chat' | 'agreement' | 'org' | 'artifact';
 export type ContextTemporal = 'from-now' | 'from-start';
 export interface ContextGrantScope {
     kind: ContextGrantScopeKind;
@@ -80,6 +85,21 @@ export declare class ContextGrantsClient {
      * labels-only, grant-fenced server-side.
      */
     getReach(grantId: string): Promise<GrantReachResult>;
+    /**
+     * ZIG-1037 — share an artifact THIS agent authored with another agent.
+     *
+     * Not a delegation: an agent holds no grant over its own output, so there is
+     * no parent to attenuate. Authorship is the authority, held by the agent's
+     * owner — which is why the receiver decides the outcome. A receiver already
+     * inside the sharer's trust boundary (same owner, same org, or an active link)
+     * is granted immediately; anyone else opens a request the owner approves,
+     * exactly like `delegateGrant`'s new-party path.
+     */
+    shareArtifact(artifactId: string, input: {
+        holderId: string;
+        expiresAt?: string | null;
+        chatId?: string;
+    }): Promise<DelegateContextGrantResult>;
     revokeGrant(grantId: string): Promise<{
         status: string;
         revokedCount?: number;

package/dist/http/ContextGrantsClient.js

@@ -1,24 +1,7 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { ApiError } from '../types.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
-function throwApiError(response, responseBody, defaultMessage) {
-    let message = defaultMessage;
-    if (responseBody) {
-        try {
-            const d = JSON.parse(responseBody);
-            message =
-                d['details'] ||
-                    d['error'] ||
-                    d['message'] ||
-                    defaultMessage;
-        }
-        catch {
-            message = responseBody || defaultMessage;
-        }
-    }
-    throw new ApiError(message, response.status, responseBody);
-}
+import { throwApiError } from '../shared/apiError.js';
 /**
  * ZIG-411 context grant management — list / issue / delegate / revoke.
  */
@@ -113,6 +96,41 @@ export class ContextGrantsClient {
             truncatedAgreements: parsed.truncatedAgreements ?? 0,
         };
     }
+    /**
+     * ZIG-1037 — share an artifact THIS agent authored with another agent.
+     *
+     * Not a delegation: an agent holds no grant over its own output, so there is
+     * no parent to attenuate. Authorship is the authority, held by the agent's
+     * owner — which is why the receiver decides the outcome. A receiver already
+     * inside the sharer's trust boundary (same owner, same org, or an active link)
+     * is granted immediately; anyone else opens a request the owner approves,
+     * exactly like `delegateGrant`'s new-party path.
+     */
+    async shareArtifact(artifactId, input) {
+        const res = await fetch(`${this.baseUrl}/context/artifacts/${encodeURIComponent(artifactId)}/share`, {
+            method: 'POST',
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                'content-type': 'application/json',
+            }),
+            body: JSON.stringify(input),
+        });
+        const body = await res.text().catch(() => '');
+        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 };
+    }
     async revokeGrant(grantId) {
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(grantId)}`, {
             method: 'DELETE',

package/dist/http/MarketplaceClient.js

@@ -1,6 +1,6 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { ApiError } from '../types.js';
+import { throwApiError } from '../shared/apiError.js';
 function getMarketplaceBaseUrl() { return `${getBackendUrl()}/marketplace`; }
 function buildHeaders(creds) {
     return {
@@ -15,15 +15,6 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
-function throwApiError(response, body, defaultMsg) {
-    let msg = defaultMsg;
-    try {
-        const d = JSON.parse(body);
-        msg = d['details'] || d['error'] || d['message'] || defaultMsg;
-    }
-    catch { /**/ }
-    throw new ApiError(msg, response.status);
-}
 export async function publishOffer(payload, creds) {
     assertCreds(creds, 'marketplace offer publish');
     const res = await fetch(`${getMarketplaceBaseUrl()}/offers/publish`, {

package/dist/http/PaymentsClient.js

@@ -2,20 +2,10 @@ import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { GrantsClient } from './GrantsClient.js';
+import { parseErrorMessage } from '../shared/apiError.js';
 function randomIdempotencyKey(prefix = 'op') {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
-function parseError(text, fallback) {
-    if (!text)
-        return fallback;
-    try {
-        const parsed = JSON.parse(text);
-        return parsed['error'] || parsed['message'] || text;
-    }
-    catch {
-        return text;
-    }
-}
 /**
  * ZIG-894 — the one payments client for every surface (agent-sdk, ziggs-mcp,
  * scripts). Consolidates the former agent-sdk private ZiggsPayClient. Wallet
@@ -227,7 +217,7 @@ export class PaymentsClient {
         const response = await fetch(`${this.baseUrl}${path}`, init);
         const text = await response.text();
         if (!response.ok) {
-            const err = new Error(parseError(text, `HTTP ${response.status}`));
+            const err = new Error(parseErrorMessage(text, `HTTP ${response.status}`));
             err.status = response.status;
             err.body = text;
             throw err;

package/dist/http/TaskClient.js

@@ -1,6 +1,6 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { ApiError } from '../types.js';
+import { throwApiError } from '../shared/apiError.js';
 function getTaskBaseUrl() { return `${getBackendUrl()}/tasks`; }
 function buildHeaders(creds) {
     return {
@@ -15,26 +15,6 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
-function parseErrorMessage(responseBody, defaultMessage) {
-    if (!responseBody)
-        return defaultMessage;
-    try {
-        const d = JSON.parse(responseBody);
-        // NestJS ValidationPipe returns { message: string[] | string, error: 'Bad
-        // Request', statusCode }. Prefer the detailed `message` over the generic
-        // `error` so the real cause (which field failed validation) is surfaced
-        // instead of a bare "Bad Request". (ZIG-832)
-        const msg = d['message'];
-        const detailed = Array.isArray(msg) ? msg.join('; ') : (typeof msg === 'string' ? msg : undefined);
-        return d['details'] || detailed || d['error'] || defaultMessage;
-    }
-    catch {
-        return responseBody || defaultMessage;
-    }
-}
-function throwApiError(response, responseBody, defaultMessage) {
-    throw new ApiError(parseErrorMessage(responseBody, defaultMessage), response.status, responseBody);
-}
 function extractTask(data) {
     if (!data || typeof data !== 'object')
         return null;

package/dist/http/agreementFlows.d.ts

@@ -22,7 +22,7 @@ export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds)
     agreement: Agreement;
     shape: ProposeShape;
 }>;
-export type ClaimedKind = 'link' | 'offer' | 'quest';
+export type ClaimedKind = 'link' | 'offer' | 'quest' | 'hand-off';
 /**
  * ZIG-1021 — one claim verb for any open broadcast. Fetches the agreement to
  * route: link invites and quests claim through POST /agreements/:id/claim;

package/dist/http/agreementFlows.js

@@ -76,5 +76,10 @@ export async function claimOpenAgreement(agreementId, creds) {
         return { agreement, kind: 'offer' };
     }
     const { agreement } = await claimAgreement(agreementId, creds);
-    return { agreement, kind: 'quest' };
+    // ZIG-1059: a pinned provider inverts the quest reading — the publisher's
+    // hired agent does the work and the claimer is who it is done FOR.
+    return {
+        agreement,
+        kind: existing.providerPinned === true ? 'hand-off' : 'quest',
+    };
 }

package/dist/http/grants.d.ts

@@ -11,7 +11,18 @@
  * watermark are presented as `temporal` / `watermark_at` caveats.
  */
 export type GrantHealth = 'active' | 'expired' | 'revoked';
-export type GrantScopeKind = 'chat' | 'agreement' | 'org' | 'connection' | 'wallet';
+/**
+ * The context rail's scope kinds, as VALUES — the type below is derived from
+ * them, so widening the rail is one edit rather than a type change plus however
+ * many hand-written literal lists happen to exist. A literal subset still
+ * typechecks against the union, which is how the CLI's grant listings silently
+ * stopped showing a whole scope kind after `artifact` was added; anything that
+ * means "every context scope" should read this.
+ */
+export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact"];
+/** Every scope kind across every rail: context + connection + payment. */
+export declare const GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "connection", "wallet"];
+export type GrantScopeKind = (typeof GRANT_SCOPE_KINDS)[number];
 export interface GrantScopeView {
     kind: GrantScopeKind;
     id: string;

package/dist/http/grants.js

@@ -1,3 +1,24 @@
+/**
+ * The context rail's scope kinds, as VALUES — the type below is derived from
+ * them, so widening the rail is one edit rather than a type change plus however
+ * many hand-written literal lists happen to exist. A literal subset still
+ * typechecks against the union, which is how the CLI's grant listings silently
+ * stopped showing a whole scope kind after `artifact` was added; anything that
+ * means "every context scope" should read this.
+ */
+export const CONTEXT_GRANT_SCOPE_KINDS = [
+    'chat',
+    'agreement',
+    'org',
+    // ZIG-1037: narrowest context scope
+    'artifact',
+];
+/** Every scope kind across every rail: context + connection + payment. */
+export const GRANT_SCOPE_KINDS = [
+    ...CONTEXT_GRANT_SCOPE_KINDS,
+    'connection',
+    'wallet',
+];
 /** Value of the first caveat of `type` on a grant, or undefined. */
 export function grantCaveat(grant, type) {
     return grant.caveats.find((c) => c.type === type)?.value;

package/dist/http/index.d.ts

@@ -15,7 +15,7 @@ export { GrantsClient } from './GrantsClient.js';
 export type { ListGrantsQuery, ListGrantsResult, UnreadableRail } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, DelegateContextGrantResult, ReachEntry, GrantReachResult, } from './ContextGrantsClient.js';
-export { grantCaveat } from './grants.js';
+export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
 export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
 export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';

package/dist/http/index.js

@@ -11,7 +11,7 @@ export { ContextReadClient } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
-export { grantCaveat } from './grants.js';
+export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
 export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, } from './OrgsClient.js';

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET,
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
+export { parseErrorMessage, throwApiError } from './shared/apiError.js';
 export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, ApiError, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/dist/index.js

@@ -7,3 +7,7 @@ export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 // ZIG-1019: retry loops need the server's own wait, not a guess.
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
+// One reader for the one error shape the API answers in — exported so nothing has
+// to re-implement the field precedence (it was copy-pasted into six clients, and
+// half of them had drifted).
+export { parseErrorMessage, throwApiError } from './shared/apiError.js';

package/dist/shared/apiError.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read the message out of a Ziggs error response.
+ *
+ * The API answers every failure in one shape — `{ error: "<what went wrong>" }`,
+ * plus `code` when the server supplied a machine-readable one — because one global
+ * exception filter builds it (backend `common/http-exception.filter.ts`, pinned in
+ * `common/error-response.spec.ts`). So `error` is read first and is normally the
+ * whole answer.
+ *
+ * `message` and `details` remain as fallbacks for responses that did NOT come from
+ * that filter: a proxy, a gateway, or a Nest-shaped body from some other service.
+ * On a Nest-shaped body `error` holds the reason phrase ("Bad Request") while
+ * `message` holds the real cause, so when both are present the more specific one
+ * wins — that ordering is why this lives in ONE place. It used to be copy-pasted
+ * into five clients, two of which had been fixed for it and three of which had not,
+ * so the same failure read differently depending on which client you called.
+ */
+export declare function parseErrorMessage(responseBody: string, defaultMessage: string): string;
+/** Throw the parsed failure as an {@link ApiError}, preserving status and body. */
+export declare function throwApiError(response: {
+    status: number;
+}, responseBody: string, defaultMessage: string): never;

package/dist/shared/apiError.js

@@ -0,0 +1,57 @@
+import { ApiError } from '../types.js';
+/**
+ * Read the message out of a Ziggs error response.
+ *
+ * The API answers every failure in one shape — `{ error: "<what went wrong>" }`,
+ * plus `code` when the server supplied a machine-readable one — because one global
+ * exception filter builds it (backend `common/http-exception.filter.ts`, pinned in
+ * `common/error-response.spec.ts`). So `error` is read first and is normally the
+ * whole answer.
+ *
+ * `message` and `details` remain as fallbacks for responses that did NOT come from
+ * that filter: a proxy, a gateway, or a Nest-shaped body from some other service.
+ * On a Nest-shaped body `error` holds the reason phrase ("Bad Request") while
+ * `message` holds the real cause, so when both are present the more specific one
+ * wins — that ordering is why this lives in ONE place. It used to be copy-pasted
+ * into five clients, two of which had been fixed for it and three of which had not,
+ * so the same failure read differently depending on which client you called.
+ */
+export function parseErrorMessage(responseBody, defaultMessage) {
+    if (!responseBody)
+        return defaultMessage;
+    let parsed;
+    try {
+        parsed = JSON.parse(responseBody);
+    }
+    catch {
+        // Not JSON at all — an HTML error page or a bare string is still better than
+        // nothing, so hand back what the server actually said.
+        return responseBody || defaultMessage;
+    }
+    // Valid JSON that is not an object: a quoted string IS the message; anything
+    // else (null, a number) carries no message, and echoing its raw text would put
+    // "null" in front of a caller.
+    if (typeof parsed !== 'object' || parsed === null) {
+        return typeof parsed === 'string' && parsed ? parsed : defaultMessage;
+    }
+    const body = parsed;
+    const text = (value) => {
+        if (Array.isArray(value)) {
+            const joined = value.map(String).filter(Boolean).join('; ');
+            return joined || undefined;
+        }
+        return typeof value === 'string' && value ? value : undefined;
+    };
+    const error = text(body['error']);
+    const message = text(body['message']);
+    // A Nest-shaped body carries both: prefer the specific `message` over the
+    // reason phrase sitting in `error`.
+    const preferMessage = !!message && !!body['statusCode'];
+    return (text(body['details']) ??
+        (preferMessage ? message : (error ?? message)) ??
+        defaultMessage);
+}
+/** Throw the parsed failure as an {@link ApiError}, preserving status and body. */
+export function throwApiError(response, responseBody, defaultMessage) {
+    throw new ApiError(parseErrorMessage(responseBody, defaultMessage), response.status, responseBody);
+}

package/dist/types.d.ts

@@ -113,6 +113,12 @@ export interface Agreement {
     } | null;
     /** Set on a link that was formed by claiming the invite with this id. */
     linkInviteTemplateId?: string | null;
+    /**
+     * ZIG-997/ZIG-1059 — the provider slot is FIXED (a hand-off): claiming or
+     * approving this makes you the party the work is done FOR, not the worker —
+     * and, when priced, the payer.
+     */
+    providerPinned?: boolean;
     metadata?: Record<string, unknown>;
     createdAt?: string;
     updatedAt?: string;

package/package.json

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