@ziggs-ai/api-client 0.9.0 → 0.9.2

package/dist/http/AgreementClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { type Creds, type Agreement, type EngagementKind, type BroadcastAudience } from '../types.js';
 /**
  * Shared proposal terms. When `engagementKind` is omitted the server defaults to `service`.
@@ -46,6 +45,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>;
@@ -152,6 +178,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;
@@ -181,6 +208,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)
@@ -193,6 +222,7 @@ export declare function fulfillAgreement(agreementId: string, creds: Creds): Pro
 export declare function claimAgreement(agreementId: string, creds: Creds): Promise<{
     ok: boolean;
     agreement: Agreement;
+    kind?: ClaimedKind;
 }>;
 /**
  * Link types a caller may ASK for — the server's `CALLER_LINK_TYPES`, not its
@@ -251,6 +281,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

@@ -1,11 +1,10 @@
-import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.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.
+// Lazy: read at call time so a `configureApiClient` call that lands after this
+// module is imported still takes effect. Baking it at module-load time would
+// freeze the URL before the host has configured one.
 function getAgreementBaseUrl() {
     return `${getBackendUrl()}/agreements`;
 }
@@ -25,6 +24,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');
@@ -48,7 +95,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) {
@@ -96,7 +143,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).
@@ -110,7 +157,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`);
     }
@@ -213,7 +263,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)
@@ -232,7 +282,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)
@@ -261,8 +311,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)
@@ -284,10 +333,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');
@@ -316,20 +367,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}`, {
@@ -346,11 +406,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');
@@ -369,7 +434,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)
@@ -389,7 +455,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. */
@@ -409,7 +476,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):
@@ -433,7 +501,12 @@ 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

package/dist/http/ArtifactsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 export type ArtifactVisibility = 'chat' | 'agent-private';
 export interface ListArtifactsOptions {
     after?: string;

package/dist/http/ArtifactsClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { throwApiError } from '../shared/apiError.js';
 import { getBackendUrl } from '../utils/urlUtils.js';

package/dist/http/ChatClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { type Creds } from '../types.js';
 /** Shape of GET /chats/mine items — the backend's ChatReadDto (ZIG-665). */
 export interface ChatSummary {
@@ -10,7 +9,9 @@ export interface ChatSummary {
     orgId: string | null;
     isOrgChat: boolean;
 }
-export declare function openConversation(participantId: string, creds: Creds): Promise<{
+export declare function openConversation(participantId: string, creds: Creds, { newChat }?: {
+    newChat?: boolean;
+}): Promise<{
     chatId: string;
 }>;
 export interface SendChatMessageInput {
@@ -75,7 +76,9 @@ export declare class ChatClient {
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
      */
     constructor(operatorKey: string, agentId?: string);
-    open(participantId: string): Promise<{
+    open(participantId: string, opts?: {
+        newChat?: boolean;
+    }): Promise<{
         chatId: string;
     }>;
     addMember(input: AddChatMemberInput): Promise<AddChatMemberResult>;

package/dist/http/ChatClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
@@ -18,14 +17,16 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
-export async function openConversation(participantId, creds) {
+export async function openConversation(participantId, creds, { newChat = false } = {}) {
     if (!participantId)
         throw new Error('participantId is required for openConversation');
     assertCreds(creds, 'open conversation');
     const res = await fetch(`${getBackendUrl()}/chats`, {
         method: 'POST',
         headers: buildHeaders(creds),
-        body: JSON.stringify({ participantId }),
+        // Only sent when asked for: an older backend ignores the field, so a
+        // caller that never wants a separate room behaves identically either way.
+        body: JSON.stringify({ participantId, ...(newChat ? { newChat: true } : {}) }),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
@@ -104,7 +105,7 @@ export async function listMyChats(creds) {
     assertCreds(creds, 'list my chats');
     // ZIG-699 — empty array only for a genuine empty 200; any failure (non-2xx /
     // network) throws so ziggs_chat_list reports a real error instead of "you
-    // have no chats". Status stays whitespace-delimited for toolError classification.
+    // have no chats". ZIG-1124 — HTTP failures are ApiError (status/body/code).
     let res;
     try {
         res = await fetch(`${getBackendUrl()}/chats/mine`, {
@@ -119,7 +120,7 @@ export async function listMyChats(creds) {
     if (!res.ok) {
         const body = await res.text().catch(() => '');
         runtimeLog.warn('ChatClient', `⚠️ listMyChats failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-        throw new Error(`GET /chats/mine ${res.status} ${body?.slice(0, 200)}`);
+        throwApiError(res, body, `GET /chats/mine failed: ${res.status}`);
     }
     const data = await res.json().catch(() => null);
     return Array.isArray(data?.['chats']) ? data['chats'] : [];
@@ -137,7 +138,7 @@ export class ChatClient {
         // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
-    open(participantId) { return openConversation(participantId, this.creds); }
+    open(participantId, opts) { return openConversation(participantId, this.creds, opts); }
     addMember(input) { return addChatMember(input, this.creds); }
     sendMessage(input) { return sendChatMessage(input, this.creds); }
     listMine() { return listMyChats(this.creds); }

package/dist/http/ConnectionsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import type { GrantView } from './grants.js';
 export declare function assertNoLeakedConnectionSecret(serialized: string): void;
 /** Thrown by ConnectionsClient with the HTTP status and raw body attached. */

package/dist/http/ConnectionsClient.js

@@ -1,5 +1,5 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { throwApiError } from '../shared/apiError.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { GrantsClient } from './GrantsClient.js';
 // ZIG-569 — defense-in-depth mirror of the backend leak-guard
@@ -169,10 +169,9 @@ export class ConnectionsClient {
         const response = await fetch(`${this.baseUrl}${path}`, init);
         const text = await response.text().catch(() => '');
         if (!response.ok) {
-            const err = new Error(`${method} ${path} ${response.status} ${text.slice(0, 200)}`);
-            err.status = response.status;
-            err.body = text;
-            throw err;
+            // ZIG-1124 — ApiError (status/body/code); ConnectionsError remains the
+            // documented duck type for callers that branch on `.status`.
+            throwApiError(response, text, `${method} ${path} failed: ${response.status}`);
         }
         return text;
     }

package/dist/http/ContextDiscoveryClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 /**
  * Labels-only pointer to context the agent could request access to (P4).
  * ZIG-927: covers chats, agreements, and connections; connection labels are the

package/dist/http/ContextDiscoveryClient.js

@@ -1,5 +1,5 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { throwApiError } from '../shared/apiError.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
  * P4 discovery — labels-only pointers to context the agent could REQUEST but
@@ -34,7 +34,7 @@ export class ContextDiscoveryClient {
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`ContextDiscoveryClient.discoverGrantable ${res.status} ${body.slice(0, 200)}`);
+            throwApiError(res, body, `ContextDiscoveryClient.discoverGrantable failed: ${res.status}`);
         }
         const parsed = JSON.parse(body);
         return (parsed.items ?? []).map((i) => ({

package/dist/http/ContextGrantsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import type { GrantView } from './grants.js';
 /**
  * ZIG-1037 added `artifact` — the narrowest context scope: one specific artifact,

package/dist/http/ContextGrantsClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { throwApiError } from '../shared/apiError.js';

package/dist/http/ContextReadClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 export declare const CONTEXT_READ_TYPES: readonly ["messages", "artifacts", "agreements", "tasks"];
 export type ContextReadType = (typeof CONTEXT_READ_TYPES)[number];
 /**

package/dist/http/ContextReadClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
 export const CONTEXT_READ_TYPES = [
@@ -105,18 +104,11 @@ export class ContextReadClient {
         const res = await fetch(url.toString(), { headers });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            // Carry the status like `snapshot()` does, so callers can branch on it.
             // A 403 here is a legitimate outcome, not a transport failure: addressing
             // and authorisation are separate, so an agent can be told about mail it
-            // is not (or is no longer) allowed to open.
-            // ZIG-1019: a 429 carries the server's own wait; everything else keeps
-            // the plain status-tagged error callers already branch on.
-            if (res.status === 429) {
-                throw pollSurfaceError(`ContextReadClient.read ${type}`, res, body);
-            }
-            const err = new Error(`ContextReadClient.read ${type} ${res.status} ${body.slice(0, 200)}`);
-            err.status = res.status;
-            throw err;
+            // is not (or is no longer) allowed to open. ZIG-1124 — one ApiError shape
+            // (429 → RateLimitedError with Retry-After).
+            throw pollSurfaceError(`ContextReadClient.read ${type}`, res, body);
         }
         return JSON.parse(body);
     }
@@ -151,12 +143,8 @@ export class ContextReadClient {
         const res = await fetch(url.toString(), { headers });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            if (res.status === 429) {
-                throw pollSurfaceError('ContextReadClient.snapshot', res, body);
-            }
-            const err = new Error(`ContextReadClient.snapshot ${res.status} ${body.slice(0, 200)}`);
-            err.status = res.status;
-            throw err;
+            // ZIG-1124 — ApiError for every non-OK (429 → RateLimitedError).
+            throw pollSurfaceError('ContextReadClient.snapshot', res, body);
         }
         return JSON.parse(body);
     }

package/dist/http/GrantsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import type { GrantView, GrantScopeKind, GrantHealth } from './grants.js';
 export interface ListGrantsQuery {
     /**

package/dist/http/GrantsClient.js

@@ -1,5 +1,5 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { throwApiError } from '../shared/apiError.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
  * ZIG-648 — unified grant listing across every rail. `GET /grants` returns the
@@ -41,7 +41,7 @@ export class GrantsClient {
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`GrantsClient.listGrants ${res.status} ${body.slice(0, 200)}`);
+            throwApiError(res, body, `GrantsClient.listGrants failed: ${res.status}`);
         }
         const parsed = JSON.parse(body);
         return {