@ziggs-ai/api-client 0.8.0 → 0.9.1

package/dist/capabilities/links.js

@@ -18,27 +18,6 @@ function webAppOrigin(env) {
 function inviteShareUrl(env, agreementId) {
     return `${webAppOrigin(env)}/connect/${agreementId}`;
 }
-/**
- * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
- * block, approvals array, and Mongo internals are noise on a trust
- * relationship. ZIG-956 moved this into the shared layer so the MCP mutations
- * return it too (they used to leak the raw agreement doc).
- */
-export function linkSummary(a) {
-    return {
-        agreementId: a.agreementId,
-        status: a.status,
-        proposalStatus: a.proposalStatus,
-        parties: {
-            creatorAgent: a.parties?.creatorAgent ?? null,
-            providerAgent: a.parties?.providerAgent ?? null,
-            creator: a.parties?.creator ?? null,
-            proposedTo: a.parties?.proposedTo ?? null,
-        },
-        ...(a.description ? { description: a.description } : {}),
-        createdAt: a.createdAt,
-    };
-}
 /**
  * A link is reach-only — the follow-up move differs by surface tool names.
  *
@@ -106,7 +85,7 @@ export const createLinkInviteCapability = {
             message: env.surface === 'mcp'
                 ? `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),
+            agreement,
         };
     },
     sdkOptions: { isAgreementCreation: true },
@@ -136,12 +115,11 @@ export const listLinksCapability = {
             engagementKind: 'link',
             ...(status === 'all' ? {} : { status }),
         }, fullCreds(env));
-        const summaries = links.map(linkSummary);
         const hasActive = links.some((a) => a.status === 'active');
         return {
-            count: summaries.length,
+            count: links.length,
             status,
-            links: summaries,
+            links,
             ...(hasActive ? { nextSteps: linkIsReachOnly(env) } : {}),
         };
     },

package/dist/capabilities/types.d.ts

@@ -43,6 +43,7 @@ export interface CapabilityEnv {
     creds: {
         operatorKey: string;
         agentId?: string;
+        laneId?: string;
     };
     /** SDK runner base-URL override (BACKEND_URL / ZIGGS_BACKEND_URL). */
     baseUrl?: string;

package/dist/capabilities/types.js

@@ -1,11 +1,13 @@
 /** Creds for impersonated calls; adapters guarantee agentId when needsAgentId. */
 export function fullCreds(env) {
-    const { operatorKey, agentId } = env.creds;
+    const { operatorKey, agentId, laneId } = env.creds;
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
     if (!agentId)
         throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
+    // ZIG-1092 — the lane rides along so every Creds-based client sends
+    // X-Ziggs-Lane without each capability having to remember to.
+    return { operatorKey, agentId, ...(laneId ? { laneId } : {}) };
 }
 /**
  * Re-throw a client error with a capability-level prefix, preserving the HTTP
@@ -19,6 +21,9 @@ export function rethrowWithContext(error, prefix) {
         wrapped.status = e.status;
     if (e.body !== undefined)
         wrapped.body = e.body;
+    // ZIG-1124 — keep the machine code so toolError can classify without prose.
+    if (typeof e.code === 'string' && e.code)
+        wrapped.code = e.code;
     wrapped['cause'] = error;
     throw wrapped;
 }

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;
@@ -51,6 +46,33 @@ export interface ProposeDirectInput extends ProposeTerms {
 export type ProposeBroadcastInput = Omit<ProposeDirectInput, 'proposedTo'> & {
     audience?: BroadcastAudience;
 };
+/**
+ * A trust link's agreement, as every caller sees it.
+ *
+ * A link is reach, not commerce: it carries no money, no escrow, no execution
+ * state and no approvals ledger. Handing the raw document over anyway put Mongo
+ * bookkeeping in front of an LLM, which is what ZIG-957 forbade.
+ *
+ * Lives here rather than in `capabilities/links.ts` because this is where the
+ * rule is applied (ZIG-1111); that module re-exports it so the public name is
+ * unchanged.
+ */
+export declare function linkSummary(a: Agreement): Record<string, unknown>;
+/**
+ * Every agreement document this client parses passes through here.
+ *
+ * The rule — a link is returned as its summary, anything else verbatim — used to
+ * be written out at six call sites across the SDK runner, the MCP tools and the
+ * capability layer, and three verbs never got it: `agreement_counter`,
+ * `agreement_fulfill` and `agreement_subcontract` returned the raw document
+ * (ZIG-1111). Applying it at the parse boundary means a new verb inherits the
+ * rule instead of remembering to opt in, and no surface can word its own verdict.
+ *
+ * Typed as `Agreement` on the way out: every key the summary keeps IS an
+ * Agreement field, so this narrows a document rather than returning a different
+ * shape.
+ */
+export declare function shapeAgreement(a: Agreement): Agreement;
 /** @deprecated Alias for {@link ProposeDirectInput}. */
 export type ProposeAgreementData = ProposeDirectInput;
 export declare function proposeAgreement(proposalData: ProposeDirectInput, creds: Creds): Promise<Agreement>;
@@ -67,16 +89,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 +109,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 +156,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>;
@@ -143,6 +179,7 @@ export interface GetMyAgreementsFilters {
     partyOnly?: boolean;
 }
 export declare function getMyAgreements(filters: GetMyAgreementsFilters | undefined, creds: Creds): Promise<Agreement[]>;
+/** One agreement, shaped: a link comes back as its summary. */
 export declare function getAgreement(agreementId: string, creds: Creds): Promise<Agreement | null>;
 export interface CreateAgreementBody {
     proposedToId?: string;
@@ -172,6 +209,8 @@ export declare function fulfillAgreement(agreementId: string, creds: Creds): Pro
     ok: boolean;
     agreement: Agreement;
 }>;
+/** What an open-broadcast claim turned out to be. ⚠️ SYNC: backend AgreementOpenService. */
+export type ClaimedKind = 'link' | 'offer' | 'quest' | 'hand-off';
 /**
  * Claim an open agreement (ZIG-524 phase 2 / ZIG-525):
  * - open link invite (`engagementKind: link`, proposedTo everyone)
@@ -184,8 +223,17 @@ export declare function fulfillAgreement(agreementId: string, creds: Creds): Pro
 export declare function claimAgreement(agreementId: string, creds: Creds): Promise<{
     ok: boolean;
     agreement: Agreement;
+    kind?: ClaimedKind;
 }>;
-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 +241,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 {
@@ -232,6 +282,7 @@ export declare class AgreementClient {
     claimAgreement(id: string): Promise<{
         ok: boolean;
         agreement: Agreement;
+        kind?: ClaimedKind;
     }>;
     linkToChat(id: string, chatId: string, linkType?: ChatLinkType): Promise<unknown>;
     listChats(id: string): Promise<unknown[]>;

package/dist/http/AgreementClient.js

@@ -14,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) {
@@ -22,6 +25,54 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
+/**
+ * A trust link's agreement, as every caller sees it.
+ *
+ * A link is reach, not commerce: it carries no money, no escrow, no execution
+ * state and no approvals ledger. Handing the raw document over anyway put Mongo
+ * bookkeeping in front of an LLM, which is what ZIG-957 forbade.
+ *
+ * Lives here rather than in `capabilities/links.ts` because this is where the
+ * rule is applied (ZIG-1111); that module re-exports it so the public name is
+ * unchanged.
+ */
+export function linkSummary(a) {
+    return {
+        agreementId: a.agreementId,
+        // Kept deliberately: callers branch on this, and a summary that hides what
+        // kind of thing it describes breaks the code it is meant to protect.
+        engagementKind: a.engagementKind,
+        status: a.status,
+        proposalStatus: a.proposalStatus,
+        parties: {
+            creatorAgent: a.parties?.creatorAgent ?? null,
+            providerAgent: a.parties?.providerAgent ?? null,
+            creator: a.parties?.creator ?? null,
+            proposedTo: a.parties?.proposedTo ?? null,
+        },
+        ...(a.description ? { description: a.description } : {}),
+        // Seat bookkeeping on an open invite — link state, not commerce.
+        ...(a.linkInvite ? { linkInvite: a.linkInvite } : {}),
+        createdAt: a.createdAt,
+    };
+}
+/**
+ * Every agreement document this client parses passes through here.
+ *
+ * The rule — a link is returned as its summary, anything else verbatim — used to
+ * be written out at six call sites across the SDK runner, the MCP tools and the
+ * capability layer, and three verbs never got it: `agreement_counter`,
+ * `agreement_fulfill` and `agreement_subcontract` returned the raw document
+ * (ZIG-1111). Applying it at the parse boundary means a new verb inherits the
+ * rule instead of remembering to opt in, and no surface can word its own verdict.
+ *
+ * Typed as `Agreement` on the way out: every key the summary keeps IS an
+ * Agreement field, so this narrows a document rather than returning a different
+ * shape.
+ */
+export function shapeAgreement(a) {
+    return a.engagementKind === 'link' ? linkSummary(a) : a;
+}
 export async function proposeAgreement(proposalData, creds) {
     if (!proposalData)
         throw new Error('Proposal data is required for proposal creation');
@@ -45,7 +96,7 @@ export async function proposeAgreement(proposalData, creds) {
     if (!data?.['agreement']) {
         throw new Error('Invalid response: expected { agreement } from POST /agreements/proposals');
     }
-    return data['agreement'];
+    return shapeAgreement(data['agreement']);
 }
 /** Propose a contract to one party (user or agent). Server defaults `engagementKind` to `service`. */
 export async function proposeDirectTo(input, creds) {
@@ -93,7 +144,7 @@ export async function delegateAgreement(proposalData, creds) {
     if (!data?.['agreement']) {
         throw new Error('Invalid response: expected { agreement } from POST /agreements/:parentAgreementId/delegations');
     }
-    return data['agreement'];
+    return shapeAgreement(data['agreement']);
 }
 /**
  * Approve or reject a pending agreement (ZIG-524 canonical client path).
@@ -107,7 +158,10 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
     if (!agreementId || !action)
         throw new Error('Agreement ID and action are required for proposal response');
     assertCreds(creds, 'proposal response');
-    const agreement = opts.agreement ?? (await getAgreement(agreementId, creds));
+    // Unshaped on purpose: the approvals ledger below is exactly what the link
+    // summary drops, and resolving the caller's slot from a summary would fail
+    // every link approval with "no pending approval entry".
+    const agreement = opts.agreement ?? (await getAgreementDocument(agreementId, creds));
     if (!agreement) {
         throw new Error(`Agreement ${agreementId} not found`);
     }
@@ -135,28 +189,54 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
     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`).
@@ -184,7 +264,7 @@ export async function approveAgreementAsParty(agreementId, partyId, status, cred
     if (!data?.['agreement']) {
         throw new Error('Invalid response: expected { agreement } from PUT /agreements/:id/approvals/:partyId');
     }
-    return data['agreement'];
+    return shapeAgreement(data['agreement']);
 }
 export async function counterAgreement(agreementId, counter, creds) {
     if (!agreementId)
@@ -203,7 +283,7 @@ export async function counterAgreement(agreementId, counter, creds) {
     if (!data?.['agreement']) {
         throw new Error('Invalid response: expected { agreement } from /agreements/:id/counter');
     }
-    return data['agreement'];
+    return shapeAgreement(data['agreement']);
 }
 export async function getAgreementStatus(agreementId, creds) {
     if (!agreementId)
@@ -232,8 +312,7 @@ export async function listAgreements(filters = {}, creds) {
     assertCreds(creds, 'list agreements');
     // ZIG-699 — return an empty array only for a genuine empty 200 result. Any
     // failure (non-2xx / network) throws so the MCP tool reports a real error
-    // instead of "you have no agreements". The status stays whitespace-delimited
-    // so the tool's toolError/classifyToolError maps it to a stable code.
+    // instead of "you have no agreements". ZIG-1124 — HTTP failures are ApiError.
     // Canonical query path: GET /agreements?scope=&status=&engagementKind=&...
     const url = new URL(getAgreementBaseUrl());
     if (filters.status)
@@ -255,10 +334,12 @@ export async function listAgreements(filters = {}, creds) {
     if (!res.ok) {
         const body = await res.text().catch(() => '');
         runtimeLog.warn('AgreementClient', `⚠️ List agreements failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-        throw new Error(`GET /agreements ${res.status} ${body?.slice(0, 200)}`);
+        throwApiError(res, body, `GET /agreements failed: ${res.status}`);
     }
     const data = await res.json().catch(() => null);
-    return Array.isArray(data?.['agreements']) ? data['agreements'] : [];
+    return Array.isArray(data?.['agreements'])
+        ? data['agreements'].map(shapeAgreement)
+        : [];
 }
 export async function getMyAgreements(filters = {}, creds) {
     assertCreds(creds, 'get my agreements');
@@ -287,20 +368,29 @@ export async function getMyAgreements(filters = {}, creds) {
     if (!res.ok) {
         const body = await res.text().catch(() => '');
         runtimeLog.warn('AgreementClient', `⚠️ Get my agreements failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-        throw new Error(`GET /agreements?scope=mine ${res.status} ${body?.slice(0, 200)}`);
+        throwApiError(res, body, `GET /agreements?scope=mine failed: ${res.status}`);
     }
     const data = await res.json().catch(() => null);
-    return Array.isArray(data?.['agreements']) ? data['agreements'] : [];
+    return Array.isArray(data?.['agreements'])
+        ? data['agreements'].map(shapeAgreement)
+        : [];
 }
-export async function getAgreement(agreementId, creds) {
+/**
+ * The full agreement document, unshaped — for this client's OWN reads.
+ *
+ * `respondToAgreement` resolves which approvals slot the caller may fill, and
+ * `claimOpenAgreement` routes on the broadcast's open side; both need fields the
+ * link summary deliberately drops. Callers outside this module get the shaped
+ * `getAgreement`.
+ */
+async function getAgreementDocument(agreementId, creds) {
     if (!agreementId)
         return null;
     assertCreds(creds, 'get agreement');
     // ZIG-698 — a genuine 404 (and 200-with-no-agreement) is a real "not found"
     // and returns null. Every other failure (403/5xx/network) must throw so the
     // caller can tell "does not exist" from "could not fetch" instead of a 403
-    // masquerading as not-found. The MCP tool classifies the thrown status via
-    // toolError; the message keeps the status whitespace-delimited for that.
+    // masquerading as not-found. ZIG-1124 — thrown as ApiError for toolError.
     let res;
     try {
         res = await fetch(`${getAgreementBaseUrl()}/${agreementId}`, {
@@ -317,11 +407,16 @@ export async function getAgreement(agreementId, creds) {
     if (!res.ok) {
         const body = await res.text().catch(() => '');
         runtimeLog.warn('AgreementClient', `⚠️ Get agreement failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-        throw new Error(`GET /agreements/${agreementId} ${res.status} ${body?.slice(0, 200)}`);
+        throwApiError(res, body, `GET /agreements/${agreementId} failed: ${res.status}`);
     }
     const data = await res.json().catch(() => null);
     return data?.['agreement'] ?? null;
 }
+/** One agreement, shaped: a link comes back as its summary. */
+export async function getAgreement(agreementId, creds) {
+    const agreement = await getAgreementDocument(agreementId, creds);
+    return agreement ? shapeAgreement(agreement) : null;
+}
 export async function createAgreement(body, creds) {
     if (!body)
         throw new Error('Body is required for agreement creation');
@@ -340,7 +435,8 @@ export async function createAgreement(body, creds) {
     if (!data?.['agreement']) {
         throw new Error('Invalid response: expected { ok, agreement } from POST /agreements');
     }
-    return data;
+    const envelope = data;
+    return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
 }
 export async function revokeAgreement(agreementId, creds) {
     if (!agreementId)
@@ -360,7 +456,8 @@ export async function revokeAgreement(agreementId, creds) {
     if (!data?.['agreement']) {
         throw new Error('Invalid response: expected { ok, agreement } from DELETE /agreements/:id');
     }
-    return data;
+    const envelope = data;
+    return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
 }
 /** ZIG-832: mark an agreement fulfilled (complete). A provider closing its own
  * delivered work — party-gated server-side. */
@@ -380,7 +477,8 @@ export async function fulfillAgreement(agreementId, creds) {
     if (!data?.['agreement']) {
         throw new Error('Invalid response: expected { ok, agreement } from POST /agreements/:id/fulfill');
     }
-    return data;
+    const envelope = data;
+    return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
 }
 /**
  * Claim an open agreement (ZIG-524 phase 2 / ZIG-525):
@@ -404,8 +502,29 @@ export async function claimAgreement(agreementId, creds) {
     if (!data?.['agreement']) {
         throw new Error('Invalid response: expected { ok, agreement } from POST /agreements/:id/claim');
     }
-    return data;
+    // ZIG-1155: the route reports which kind of broadcast this turned out to be.
+    // A caller cannot work it out from the row — post-claim no sentinel is left,
+    // and a quest (you do the work) reads the same shape as a standing offer (you
+    // pay for it) unless you know which slot you landed in.
+    const envelope = data;
+    return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
 }
+// ---------------------------------------------------------------------------
+// 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;
@@ -468,6 +587,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;
@@ -512,6 +635,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

@@ -62,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

package/dist/http/ArtifactsClient.js

@@ -28,15 +28,20 @@ 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 = {}) {
         const selectors = [q.chatId, q.agreementId, q.taskId, q.authoredBy].filter(Boolean);
@@ -178,12 +183,19 @@ export class ArtifactsClient {
      */
     _assertScopeXor(input) {
         if (input.chatId && input.agreementId) {
-            throw new Error('ArtifactsClient.write: pass at most one of chatId or 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);
     }
 }