@ziggs-ai/api-client 0.7.1 → 0.9.0

package/dist/http/AgreementClient.d.ts

@@ -1,6 +1,5 @@
 import 'dotenv/config';
 import { type Creds, type Agreement, type EngagementKind, type BroadcastAudience } from '../types.js';
-export type PlanReviewTiming = 'with_proposal' | 'before_execution';
 /**
  * Shared proposal terms. When `engagementKind` is omitted the server defaults to `service`.
  * For an open buyer-broadcast quest, set `proposedTo` to a broadcast sentinel —
@@ -22,7 +21,6 @@ export interface ProposeTerms {
     billing?: 'total' | 'per_task';
     agreementDescription?: string;
     parentAgreementId?: string;
-    parentTaskId?: string;
     /**
      * Who does the work. Required on direct proposals (your own id = you offer;
      * the proposedTo id = you commission the recipient); forbidden on
@@ -30,9 +28,6 @@ export interface ProposeTerms {
      * side — there is no payer input.
      */
     providerId?: string;
-    plan?: unknown;
-    planReviewTiming?: PlanReviewTiming;
-    requireMidWorkPlanAck?: boolean;
     /** Defaults to `service` on the server when omitted. Set `hire` for representation contracts. */
     engagementKind?: EngagementKind;
     idempotencyKey?: string;
@@ -67,16 +62,12 @@ export interface DelegateAgreementData {
     executorId: string;
     chatId: string;
     parentAgreementId: string;
-    parentTaskId?: string;
     price?: number;
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
     agreementDescription?: string;
     payerId?: string;
-    plan?: unknown;
-    planReviewTiming?: PlanReviewTiming;
-    requireMidWorkPlanAck?: boolean;
     idempotencyKey?: string;
 }
 export declare function delegateAgreement(proposalData: DelegateAgreementData, creds: Creds): Promise<Agreement>;
@@ -91,7 +82,29 @@ export declare function delegateAgreement(proposalData: DelegateAgreementData, c
 export declare function respondToAgreement(agreementId: string, action: 'approve' | 'reject', creds: Creds, opts?: {
     ownerUserId?: string | null;
     agreement?: Agreement | null;
+    /** Where to send the human when the decision is theirs (ZIG-1087). */
+    appUrl?: string;
 }): Promise<Agreement>;
+/**
+ * The approval facts a "who decides this?" question is answered from: the party
+ * ids still owing a decision, plus the named responder slot.
+ *
+ * Split out (ZIG-1087) so the inbox card and the respond call answer that
+ * question with ONE rule. The card had no rule at all — it offered the respond
+ * tool for every pending proposal, including the ones only the human can
+ * answer, and the agent found out by 403.
+ */
+export interface PendingApprovalFacts {
+    /** Party ids with a pending entry on the approvals ledger. */
+    pendingPartyIds: readonly string[];
+    /** The direct responder slot, when the proposal names one. */
+    proposedTo?: string | null;
+}
+/**
+ * Which of `candidateIds` holds the pending approval slot, first match wins —
+ * so pass them in preference order (agent id before owner principal).
+ */
+export declare function resolvePendingApprovalPartyId(facts: PendingApprovalFacts, candidateIds: ReadonlyArray<string | null | undefined>): string | null;
 /**
  * ZIG-524 — resolve which approvals.partyId the current operator may submit.
  * Checks pending ledger entries against impersonated agent id and owner principal.
@@ -116,10 +129,6 @@ export interface CounterAgreementData {
     lifecycle?: string;
     maxExecutions?: number;
     description?: string;
-    /** Override plan `{ steps: [...] }`; omit to copy from original proposal task */
-    plan?: unknown;
-    planReviewTiming?: PlanReviewTiming;
-    requireMidWorkPlanAck?: boolean;
 }
 export declare function counterAgreement(agreementId: string, counter: CounterAgreementData, creds: Creds): Promise<Agreement>;
 export declare function getAgreementStatus(agreementId: string, creds: Creds): Promise<unknown | null>;
@@ -185,7 +194,15 @@ export declare function claimAgreement(agreementId: string, creds: Creds): Promi
     ok: boolean;
     agreement: Agreement;
 }>;
-export type ChatLinkType = 'origin' | 'mention' | 'delegation' | 'join';
+/**
+ * Link types a caller may ASK for — the server's `CALLER_LINK_TYPES`, not its
+ * full `LINK_TYPES`. `space` is deliberately absent: an agreement space gets
+ * exactly one system-minted room, and letting a request name that type would
+ * burn the root's single slot on an unrelated chat. Shorter than the server
+ * union on purpose, which is why this list carries the reason with it.
+ */
+export declare const CHAT_LINK_TYPES: readonly ["origin", "mention", "delegation", "join"];
+export type ChatLinkType = (typeof CHAT_LINK_TYPES)[number];
 export declare function linkAgreementToChat(agreementId: string, chatId: string, linkType: ChatLinkType | undefined, creds: Creds): Promise<unknown | null>;
 export declare function getChatsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
 export declare function joinAgreement(agreementId: string, creds: Creds): Promise<{
@@ -193,10 +210,12 @@ export declare function joinAgreement(agreementId: string, creds: Creds): Promis
     agentId: string | null;
     isNew: boolean;
 }>;
-export type ArtifactLinkType = 'produced' | 'referenced';
+export declare const ARTIFACT_LINK_TYPES: readonly ["produced", "referenced"];
+export type ArtifactLinkType = (typeof ARTIFACT_LINK_TYPES)[number];
 export declare function linkArtifactToAgreement(agreementId: string, artifactId: string, linkType: ArtifactLinkType | undefined, creds: Creds): Promise<unknown | null>;
 export declare function getArtifactsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
-export type UserRole = 'payer' | 'provider' | 'participant' | 'observer';
+export declare const AGREEMENT_USER_ROLES: readonly ["payer", "provider", "participant", "observer"];
+export type UserRole = (typeof AGREEMENT_USER_ROLES)[number];
 export declare function linkUserToAgreement(agreementId: string, userId: string, role: UserRole, creds: Creds): Promise<unknown | null>;
 export declare function getUsersForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
 export declare class AgreementClient {

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.
@@ -13,6 +14,9 @@ function buildHeaders(creds) {
         'content-type': 'application/json',
         Authorization: `Bearer ${creds.operatorKey}`,
         'X-Agent-Id': creds.agentId,
+        // ZIG-1092 — the wake's lane, so the backend can fence this call to the
+        // engagement it belongs to rather than the agent's whole authority.
+        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
     };
 }
 function assertCreds(creds, op) {
@@ -21,20 +25,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,43 +114,78 @@ 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}`);
     }
+    // ZIG-1087 — the slot resolved to the principal, not to us. Every call from
+    // this client impersonates `creds.agentId` (X-Agent-Id on every request), and
+    // `PUT /approvals/:partyId` takes a decision only from the party itself, so
+    // sending this would 403 with "You can only submit your own approval" —
+    // a condition, from which the caller cannot tell that no retry will ever
+    // work. Withholding consent from delegates is deliberate; being silent about
+    // it is not.
+    if (partyId && partyId !== creds.agentId) {
+        throw new Error(`Agreement ${agreementId} is waiting on ${partyId} — your principal, not you. ` +
+            `Consent is the human's to give: a delegate can submit its own approval slot and never its principal's, ` +
+            `so there is nothing to retry here and no tool that changes it. ` +
+            `Ask your human to approve or reject it${opts.appUrl ? ` at ${opts.appUrl}` : ' in the Ziggs app, under Agreements'}, ` +
+            `then read the agreement again to see the outcome.`);
+    }
     return approveAgreementAsParty(agreementId, partyId, action === 'approve' ? 'approved' : 'rejected', creds);
 }
 /**
- * ZIG-524 — resolve which approvals.partyId the current operator may submit.
- * Checks pending ledger entries against impersonated agent id and owner principal.
+ * Which of `candidateIds` holds the pending approval slot, first match wins —
+ * so pass them in preference order (agent id before owner principal).
  */
-export function resolveMyPendingApprovalPartyId(agreement, opts) {
-    const actorIds = [opts.agentId, opts.ownerUserId].filter((id) => typeof id === 'string' && id.length > 0);
-    const pending = (agreement.approvals ?? []).filter((a) => a.status === 'pending' || a.status === 'PENDING');
+export function resolvePendingApprovalPartyId(facts, candidateIds) {
+    const actorIds = candidateIds.filter((id) => typeof id === 'string' && id.length > 0);
     for (const id of actorIds) {
-        const hit = pending.find((a) => a.partyId === id);
-        if (hit)
-            return hit.partyId;
+        if (facts.pendingPartyIds.includes(id))
+            return id;
     }
-    const proposedTo = agreement.parties?.proposedTo;
+    // A row with no pending ledger entries is a legacy one (approvals[] predates
+    // ZIG-244), and there the named responder slot IS the decision.
+    const proposedTo = facts.proposedTo ?? null;
     if (proposedTo &&
         actorIds.includes(proposedTo) &&
-        (pending.length === 0 || pending.some((a) => a.partyId === proposedTo))) {
+        facts.pendingPartyIds.length === 0) {
         return proposedTo;
     }
     return null;
 }
+/**
+ * ZIG-524 — resolve which approvals.partyId the current operator may submit.
+ * Checks pending ledger entries against impersonated agent id and owner principal.
+ */
+export function resolveMyPendingApprovalPartyId(agreement, opts) {
+    return resolvePendingApprovalPartyId({
+        pendingPartyIds: (agreement.approvals ?? [])
+            .filter((a) => a.status === 'pending' || a.status === 'PENDING')
+            .map((a) => a.partyId),
+        proposedTo: agreement.parties?.proposedTo ?? null,
+    }, [opts.agentId, opts.ownerUserId]);
+}
 /**
  * Record this party's approval decision on an agreement
  * (`PUT /agreements/:agreementId/approvals/:partyId`).
@@ -410,6 +435,22 @@ export async function claimAgreement(agreementId, creds) {
     }
     return data;
 }
+// ---------------------------------------------------------------------------
+// Chat links
+// ---------------------------------------------------------------------------
+/**
+ * Link types a caller may ASK for — the server's `CALLER_LINK_TYPES`, not its
+ * full `LINK_TYPES`. `space` is deliberately absent: an agreement space gets
+ * exactly one system-minted room, and letting a request name that type would
+ * burn the root's single slot on an unrelated chat. Shorter than the server
+ * union on purpose, which is why this list carries the reason with it.
+ */
+export const CHAT_LINK_TYPES = [
+    'origin',
+    'mention',
+    'delegation',
+    'join',
+];
 export async function linkAgreementToChat(agreementId, chatId, linkType = 'mention', creds) {
     if (!agreementId || !chatId)
         return null;
@@ -472,6 +513,10 @@ export async function joinAgreement(agreementId, creds) {
     }
     return data;
 }
+// ---------------------------------------------------------------------------
+// Artifact links
+// ---------------------------------------------------------------------------
+export const ARTIFACT_LINK_TYPES = ['produced', 'referenced'];
 export async function linkArtifactToAgreement(agreementId, artifactId, linkType = 'produced', creds) {
     if (!agreementId || !artifactId)
         return null;
@@ -516,6 +561,15 @@ export async function getArtifactsForAgreement(agreementId, creds) {
         return [];
     }
 }
+// ---------------------------------------------------------------------------
+// User links
+// ---------------------------------------------------------------------------
+export const AGREEMENT_USER_ROLES = [
+    'payer',
+    'provider',
+    'participant',
+    'observer',
+];
 export async function linkUserToAgreement(agreementId, userId, role, creds) {
     if (!agreementId || !userId || !role)
         return null;

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[];
@@ -55,11 +62,15 @@ export declare function artifactScopeForSession(sessionId: string): {
 export declare class ArtifactsClient {
     private readonly operatorKey;
     private readonly agentId?;
+    private readonly laneId?;
     /**
      * @param operatorKey Agent-scoped or fleet operator key.
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     * @param laneId ZIG-1092 — the wake's lane (chat id, or `agrn-<agreementId>`),
+     *   sent as X-Ziggs-Lane so `authoredBy=me` is fenced to this engagement
+     *   instead of returning every customer's deliverables in one call.
      */
-    constructor(operatorKey: string, agentId?: string);
+    constructor(operatorKey: string, agentId?: string, laneId?: string);
     list(q: ListArtifactsQuery, opts?: ListArtifactsOptions): Promise<ListArtifactsResult>;
     /**
      * Record an agent thought as an `agent-private` artifact. Replaces the
@@ -84,6 +95,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';
 /**
@@ -27,25 +28,35 @@ export function artifactScopeForSession(sessionId) {
 export class ArtifactsClient {
     operatorKey;
     agentId;
+    laneId;
     /**
      * @param operatorKey Agent-scoped or fleet operator key.
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     * @param laneId ZIG-1092 — the wake's lane (chat id, or `agrn-<agreementId>`),
+     *   sent as X-Ziggs-Lane so `authoredBy=me` is fenced to this engagement
+     *   instead of returning every customer's deliverables in one call.
      */
-    constructor(operatorKey, agentId) {
+    constructor(operatorKey, agentId, laneId) {
         if (!operatorKey)
             throw new Error('ArtifactsClient: operatorKey is required');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
+        this.laneId = laneId;
     }
     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 +64,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 +129,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,14 +139,63 @@ 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) {
+            // ZIG-1075: the refusal names the recovery, because this is the one gate
+            // for every caller — the exposed tool surfaces inherit it rather than each
+            // wording their own, and a caller that used to have chatId silently
+            // dropped here now learns what to do instead. Wording matters: a bare
+            // "pick one" at the last step of a finished task is what the drop was
+            // added to avoid (ZIG-924 dogfood).
+            throw new Error('pass at most one of chatId or agreementId — a deliverable under an ' +
+                'agreement wants agreementId alone (its parties see it); use chatId ' +
+                'only for a chat-scoped note. To put it in both places, record it ' +
+                'with agreementId, then attach it to the chat.');
         }
     }
     _headers() {
-        return buildOperatorHeaders(this.operatorKey, this.agentId, {
-            'content-type': 'application/json',
-        });
+        return buildOperatorHeaders(this.operatorKey, this.agentId, { 'content-type': 'application/json' }, this.laneId);
     }
 }

package/dist/http/ChatClient.js

@@ -1,12 +1,15 @@
 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',
         Authorization: `Bearer ${creds.operatorKey}`,
         'X-Agent-Id': creds.agentId,
+        // ZIG-1092 — the wake's lane, so the backend can fence this call to the
+        // engagement it belongs to rather than the agent's whole authority.
+        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
     };
 }
 function assertCreds(creds, op) {
@@ -15,19 +18,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',