@ziggs-ai/api-client 0.7.1 → 0.8.0

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/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/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/package.json

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