@ziggs-ai/api-client 0.1.28 → 0.1.30

package/dist/http/ArtifactsClient.d.ts

@@ -49,5 +49,16 @@ export declare class ArtifactsClient {
      */
     recordThought(chatId: string, text: string): Promise<void>;
     write(input: WriteArtifactInput): Promise<void>;
+    /**
+     * ZIG-899 — the deliberate-record variant: a deliverable the model chose to
+     * record must fail loudly and hand back the artifactId, unlike `write`'s
+     * soft-fail breadcrumb contract. This is the one wire call for both agent
+     * surfaces (the SDK record_artifact tool and ziggs-mcp's
+     * ziggs_record_artifact).
+     */
+    writeStrict(input: WriteArtifactInput): Promise<{
+        artifactId?: string;
+    }>;
+    private _assertScopeXor;
     private _headers;
 }

package/dist/http/ArtifactsClient.js

@@ -60,9 +60,28 @@ export class ArtifactsClient {
     async write(input) {
         if (!input.text || !input.text.trim())
             return;
-        if ((input.chatId && input.agreementId) || (!input.chatId && !input.agreementId)) {
-            throw new Error('ArtifactsClient.write: pass exactly one of chatId or agreementId');
+        this._assertScopeXor(input);
+        try {
+            await this.writeStrict(input);
+        }
+        catch (e) {
+            // Soft-fail on the wire only: breadcrumb writes are not load-bearing.
+            // Caller mistakes (scope xor, empty text) still throw above.
+            runtimeLog.warn('ArtifactsClient', `⚠️ ${e.message}`);
+        }
+    }
+    /**
+     * ZIG-899 — the deliberate-record variant: a deliverable the model chose to
+     * record must fail loudly and hand back the artifactId, unlike `write`'s
+     * soft-fail breadcrumb contract. This is the one wire call for both agent
+     * surfaces (the SDK record_artifact tool and ziggs-mcp's
+     * ziggs_record_artifact).
+     */
+    async writeStrict(input) {
+        if (!input.text || !input.text.trim()) {
+            throw new Error('ArtifactsClient.writeStrict: text is required');
         }
+        this._assertScopeXor(input);
         const url = `${getBackendUrl()}/artifacts`;
         const res = await fetch(url, {
             method: 'POST',
@@ -77,10 +96,21 @@ export class ArtifactsClient {
                 service: input.service,
             }),
         });
+        const body = await res.text().catch(() => '');
         if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            // Soft-fail: artifact writes are breadcrumbs, not load-bearing.
-            runtimeLog.warn('ArtifactsClient', `⚠️ write failed ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+            throw new Error(`POST /artifacts ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+        }
+        try {
+            const parsed = body ? JSON.parse(body) : {};
+            return { artifactId: parsed.artifactId };
+        }
+        catch {
+            return {};
+        }
+    }
+    _assertScopeXor(input) {
+        if ((input.chatId && input.agreementId) || (!input.chatId && !input.agreementId)) {
+            throw new Error('ArtifactsClient.write: pass exactly one of chatId or agreementId');
         }
     }
     _headers() {

package/dist/http/ConnectionsClient.d.ts

@@ -0,0 +1,89 @@
+import 'dotenv/config';
+export declare function assertNoLeakedConnectionSecret(serialized: string): void;
+/** Thrown by ConnectionsClient with the HTTP status and raw body attached. */
+export interface ConnectionsError extends Error {
+    status?: number;
+    body?: string;
+}
+export interface ConnectionProxyParams {
+    connectionId: string;
+    grantId: string;
+    action: string;
+    payload?: unknown;
+}
+export interface McpConnectionRequestParams {
+    serverUrl: string;
+    tools: string[];
+    reason?: string;
+    /**
+     * Working chat the consent card is opened into. Required by the backend for
+     * the agent-tool path; the per-user gateway trigger (ZIG-771) omits it.
+     */
+    chatId?: string;
+    /**
+     * Target the consent request at this end-user (X-On-Behalf-Of-User) instead
+     * of the operator — the per-user MCP gateway's connect prompt (ZIG-771).
+     */
+    onBehalfOfUserId?: string;
+}
+/**
+ * ZIG-894 — the one connections client for every surface. Consolidates the
+ * former agent-sdk private ZiggsConnectClient and ziggs-mcp's inline fetches
+ * (proxyConnection, createMcpConnectionRequest). Proxied provider calls never
+ * return the raw OAuth token; every proxy response is additionally scanned by
+ * the client-side leak guard before it reaches the caller. Grant *listing*
+ * across connections is the unified GET /grants; the per-connection grant
+ * mutations (issue / attenuate / revoke) live here.
+ */
+export declare class ConnectionsClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    /**
+     * Present a ConnectionGrant to the broker and perform a provider action.
+     * Returns the provider result — never the raw OAuth token. Requires an
+     * impersonated agent (the grant holder).
+     */
+    proxy({ connectionId, grantId, action, payload }: ConnectionProxyParams): Promise<unknown>;
+    /**
+     * List ConnectionGrants on a connection. When impersonating an agent the
+     * server already scopes rows to that holder; the client-side filter is kept
+     * as defense-in-depth (same behavior as the former ZiggsConnectClient).
+     */
+    listGrants({ connectionId }: {
+        connectionId: string;
+    }): Promise<unknown[]>;
+    /** Issue a connection grant to an agent holder (connection owner side). */
+    issueGrant({ connectionId, holderId, caveats, }: {
+        connectionId: string;
+        holderId: string;
+        caveats?: unknown;
+    }): Promise<unknown>;
+    /**
+     * Attenuate (re-delegate) a connection grant with tighter caveats. Narrowing
+     * a grant whose connection you own mints immediately; a grant whose owner is
+     * a different party returns `{ status: 'pending_approval', agreementId }`
+     * (ZIG-701 consent flow) and no grant is minted yet.
+     */
+    attenuateGrant({ connectionId, grantId, holderId, caveats, }: {
+        connectionId: string;
+        grantId: string;
+        holderId: string;
+        caveats?: unknown;
+    }): Promise<unknown>;
+    /** Revoke a single connection grant. */
+    revokeGrant({ connectionId, grantId, }: {
+        connectionId: string;
+        grantId: string;
+    }): Promise<unknown>;
+    /**
+     * ZIG-686 — agent-initiated MCP connection request: ask the principal to
+     * connect a remote MCP server and grant this agent the listed tools. Opens a
+     * connection-consent agreement in the working chat (ZIG-798); on approval the
+     * server is connected (if needed) and the agent is granted the tools.
+     */
+    requestMcpConnection({ serverUrl, tools, reason, chatId, onBehalfOfUserId, }: McpConnectionRequestParams): Promise<Record<string, unknown>>;
+    private _requestRaw;
+    private _request;
+}

package/dist/http/ConnectionsClient.js

@@ -0,0 +1,154 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+// ZIG-569 — defense-in-depth mirror of the backend leak-guard
+// (assertProxyResponseDoesNotLeakTokens). The backend strips the *specific*
+// vault token from the response; clients never see that token, so this layer
+// instead pattern-scans the proxied body for high-signal provider credential
+// shapes and refuses to hand a likely-leaked secret to the model.
+const LEAKED_SECRET_PATTERNS = [
+    /\bgh[posru]_[A-Za-z0-9]{16,}\b/, // GitHub PAT / OAuth / user / server / refresh
+    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/, // fine-grained GitHub PAT
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/, // Slack bot/user/app/refresh tokens
+    /\bxapp-[A-Za-z0-9-]{10,}\b/, // Slack app-level token
+    /"(?:access_token|refresh_token)"\s*:\s*"[^"]{8,}"/, // raw OAuth token JSON keys
+];
+export function assertNoLeakedConnectionSecret(serialized) {
+    for (const re of LEAKED_SECRET_PATTERNS) {
+        if (re.test(serialized)) {
+            throw new Error('connection proxy response withheld: it appears to contain a credential (token-leak guard)');
+        }
+    }
+}
+/**
+ * ZIG-894 — the one connections client for every surface. Consolidates the
+ * former agent-sdk private ZiggsConnectClient and ziggs-mcp's inline fetches
+ * (proxyConnection, createMcpConnectionRequest). Proxied provider calls never
+ * return the raw OAuth token; every proxy response is additionally scanned by
+ * the client-side leak guard before it reaches the caller. Grant *listing*
+ * across connections is the unified GET /grants; the per-connection grant
+ * mutations (issue / attenuate / revoke) live here.
+ */
+export class ConnectionsClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId, baseUrl) {
+        if (!operatorKey)
+            throw new Error('ConnectionsClient: operatorKey is required');
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl || getBackendUrl();
+    }
+    /**
+     * Present a ConnectionGrant to the broker and perform a provider action.
+     * Returns the provider result — never the raw OAuth token. Requires an
+     * impersonated agent (the grant holder).
+     */
+    async proxy({ connectionId, grantId, action, payload }) {
+        if (!connectionId)
+            throw new Error('proxy: connectionId is required');
+        if (!grantId)
+            throw new Error('proxy: grantId is required');
+        if (!action)
+            throw new Error('proxy: action is required');
+        if (!this.agentId) {
+            throw new Error('proxy: agentId is required — connection broker calls must impersonate the grant holder agent');
+        }
+        const text = await this._requestRaw('POST', `/connections/${encodeURIComponent(connectionId)}/proxy`, { grantId, action, payload: payload ?? {} });
+        assertNoLeakedConnectionSecret(text);
+        let parsed = text;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = text;
+        }
+        const result = parsed?.['result'];
+        return result ?? parsed;
+    }
+    /**
+     * List ConnectionGrants on a connection. When impersonating an agent the
+     * server already scopes rows to that holder; the client-side filter is kept
+     * as defense-in-depth (same behavior as the former ZiggsConnectClient).
+     */
+    async listGrants({ connectionId }) {
+        if (!connectionId)
+            throw new Error('listGrants: connectionId is required');
+        if (!this.agentId) {
+            throw new Error('listGrants: agentId is required — grants are scoped to the impersonated agent');
+        }
+        const res = (await this._request('GET', `/connections/${encodeURIComponent(connectionId)}/grants`, undefined));
+        const grants = res['grants'] || [];
+        return grants.filter((g) => g['holderId'] === this.agentId);
+    }
+    /** Issue a connection grant to an agent holder (connection owner side). */
+    async issueGrant({ connectionId, holderId, caveats, }) {
+        if (!connectionId)
+            throw new Error('issueGrant: connectionId is required');
+        if (!holderId)
+            throw new Error('issueGrant: holderId is required');
+        return this._request('POST', `/connections/${encodeURIComponent(connectionId)}/grants`, {
+            holderId,
+            caveats,
+        });
+    }
+    /**
+     * Attenuate (re-delegate) a connection grant with tighter caveats. Narrowing
+     * a grant whose connection you own mints immediately; a grant whose owner is
+     * a different party returns `{ status: 'pending_approval', agreementId }`
+     * (ZIG-701 consent flow) and no grant is minted yet.
+     */
+    async attenuateGrant({ connectionId, grantId, holderId, caveats, }) {
+        if (!connectionId)
+            throw new Error('attenuateGrant: connectionId is required');
+        if (!grantId)
+            throw new Error('attenuateGrant: grantId is required');
+        if (!holderId)
+            throw new Error('attenuateGrant: holderId is required');
+        return this._request('POST', `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}/attenuate`, { holderId, caveats });
+    }
+    /** Revoke a single connection grant. */
+    async revokeGrant({ connectionId, grantId, }) {
+        if (!connectionId)
+            throw new Error('revokeGrant: connectionId is required');
+        if (!grantId)
+            throw new Error('revokeGrant: grantId is required');
+        return this._request('DELETE', `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}`, undefined);
+    }
+    /**
+     * ZIG-686 — agent-initiated MCP connection request: ask the principal to
+     * connect a remote MCP server and grant this agent the listed tools. Opens a
+     * connection-consent agreement in the working chat (ZIG-798); on approval the
+     * server is connected (if needed) and the agent is granted the tools.
+     */
+    async requestMcpConnection({ serverUrl, tools, reason, chatId, onBehalfOfUserId, }) {
+        if (!serverUrl)
+            throw new Error('requestMcpConnection: serverUrl is required');
+        return (await this._request('POST', '/connections/mcp/requests', { serverUrl, tools, reason, chatId }, onBehalfOfUserId ? { 'X-On-Behalf-Of-User': onBehalfOfUserId } : undefined));
+    }
+    async _requestRaw(method, path, body, extraHeaders) {
+        const init = {
+            method,
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+                ...extraHeaders,
+            }),
+        };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        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;
+        }
+        return text;
+    }
+    async _request(method, path, body, extraHeaders) {
+        const text = await this._requestRaw(method, path, body, extraHeaders);
+        return text ? JSON.parse(text) : null;
+    }
+}

package/dist/http/ContextDiscoveryClient.d.ts

@@ -1,16 +1,4 @@
 import 'dotenv/config';
-export interface ContextReachDescriptor {
-    grantId: string;
-    scope: {
-        kind: 'chat' | 'agreement' | 'org';
-        id: string;
-    };
-    temporal: 'from-now' | 'from-start';
-    watermarkAt: string;
-    expiresAt: string | null;
-    parentGrantId: string | null;
-    createdAt: string;
-}
 /** Labels-only pointer to context the agent could request access to (P4). */
 export interface DiscoverableItem {
     type: 'chat';
@@ -22,7 +10,9 @@ export interface DiscoverableItem {
     orgId: string;
 }
 /**
- * ZIG-412 discovery — scope descriptors only, no content.
+ * P4 discovery — labels-only pointers to context the agent could REQUEST but
+ * does not yet hold (`GET /context/discovery/available`). Grants the agent
+ * already holds are listed via the unified `GrantsClient` (GET /grants).
  */
 export declare class ContextDiscoveryClient {
     private readonly operatorKey;
@@ -33,7 +23,6 @@ export declare class ContextDiscoveryClient {
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string);
-    discover(): Promise<ContextReachDescriptor[]>;
     /**
      * P4: what context EXISTS in the agent's engaged orgs that it does NOT hold
      * a grant for — so it can request access rather than fail blind. Labels only.

package/dist/http/ContextDiscoveryClient.js

@@ -2,7 +2,9 @@ import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
- * ZIG-412 discovery — scope descriptors only, no content.
+ * P4 discovery — labels-only pointers to context the agent could REQUEST but
+ * does not yet hold (`GET /context/discovery/available`). Grants the agent
+ * already holds are listed via the unified `GrantsClient` (GET /grants).
  */
 export class ContextDiscoveryClient {
     operatorKey;
@@ -20,17 +22,6 @@ export class ContextDiscoveryClient {
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
     }
-    async discover() {
-        const res = await fetch(`${this.baseUrl}/context/discovery`, {
-            headers: buildOperatorHeaders(this.operatorKey, this.agentId),
-        });
-        const body = await res.text().catch(() => '');
-        if (!res.ok) {
-            throw new Error(`ContextDiscoveryClient.discover ${res.status} ${body.slice(0, 200)}`);
-        }
-        const parsed = JSON.parse(body);
-        return parsed.reach ?? [];
-    }
     /**
      * P4: what context EXISTS in the agent's engaged orgs that it does NOT hold
      * a grant for — so it can request access rather than fail blind. Labels only.

package/dist/http/ContextGrantsClient.d.ts

@@ -39,6 +39,26 @@ export type DelegateContextGrantResult = {
     agreementId: string;
     ownerId?: string;
 };
+/** A single readable entry inside a grant's scope — id + label only (ZIG-870). */
+export interface ReachEntry {
+    id: string;
+    label: string;
+}
+/**
+ * ZIG-870 reach expansion — the chat/agreement ids a grant you hold actually
+ * covers, so an org/agreement-scoped grant becomes a concrete list you can
+ * `context_read` through (via=chat:<id> / agreement:<id>). Ids + labels only,
+ * never content. Org scope is capped; `truncatedChats`/`truncatedAgreements`
+ * report how many were left off, never silently dropped.
+ */
+export interface GrantReachResult {
+    grantId: string;
+    scope: ContextGrantScope;
+    chats: ReachEntry[];
+    agreements: ReachEntry[];
+    truncatedChats: number;
+    truncatedAgreements: number;
+}
 /**
  * ZIG-411 context grant management — list / issue / delegate / revoke.
  */
@@ -53,6 +73,13 @@ export declare class ContextGrantsClient {
     constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     issueGrant(input: IssueContextGrantInput): Promise<GrantView>;
     delegateGrant(parentGrantId: string, input: DelegateContextGrantInput): Promise<DelegateContextGrantResult>;
+    /**
+     * ZIG-870 — expand a grant you hold into the chat/agreement ids inside its
+     * scope. A grant is a fence, not a listing: discovery says "you hold
+     * org:acme", this says which chats/agreements that covers. Holder-only,
+     * labels-only, grant-fenced server-side.
+     */
+    getReach(grantId: string): Promise<GrantReachResult>;
     revokeGrant(grantId: string): Promise<{
         status: string;
         revokedCount?: number;

package/dist/http/ContextGrantsClient.js

@@ -88,6 +88,31 @@ export class ContextGrantsClient {
         }
         return { status: 'granted', grant: parsed.grant };
     }
+    /**
+     * ZIG-870 — expand a grant you hold into the chat/agreement ids inside its
+     * scope. A grant is a fence, not a listing: discovery says "you hold
+     * org:acme", this says which chats/agreements that covers. Holder-only,
+     * labels-only, grant-fenced server-side.
+     */
+    async getReach(grantId) {
+        const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(grantId)}/reach`, { headers: buildOperatorHeaders(this.operatorKey, this.agentId) });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, body, `getReach failed: ${res.status} ${res.statusText}`);
+        }
+        const parsed = JSON.parse(body);
+        if (!parsed.scope) {
+            throw new Error('Invalid response: expected { scope, chats, agreements } from GET /context/grants/:id/reach');
+        }
+        return {
+            grantId: parsed.grantId ?? grantId,
+            scope: parsed.scope,
+            chats: parsed.chats ?? [],
+            agreements: parsed.agreements ?? [],
+            truncatedChats: parsed.truncatedChats ?? 0,
+            truncatedAgreements: parsed.truncatedAgreements ?? 0,
+        };
+    }
     async revokeGrant(grantId) {
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(grantId)}`, {
             method: 'DELETE',

package/dist/http/GrantsClient.d.ts

@@ -0,0 +1,45 @@
+import 'dotenv/config';
+import type { GrantView, GrantScopeKind, GrantHealth } from './grants.js';
+export interface ListGrantsQuery {
+    /**
+     * Filter to grants held by this agent. Admin-gated server-side when the caller
+     * is not impersonating that agent.
+     */
+    holderId?: string;
+    /**
+     * Rail/resource filter. One kind or several (the context rail spans three
+     * kinds: chat, agreement, org). Absent = every rail.
+     */
+    scopeKind?: GrantScopeKind | GrantScopeKind[];
+    /** Filter to grants of one health. */
+    health?: GrantHealth;
+    cursor?: string;
+    limit?: number;
+}
+export interface ListGrantsResult {
+    items: GrantView[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/**
+ * ZIG-648 — unified grant listing across every rail. `GET /grants` returns the
+ * canonical GrantView for each grant the caller holds (or, admin-gated, a named
+ * holder), filterable by scope kind and health, with cursor pagination. Replaces
+ * the old per-rail listers (context discovery, connection-grants,
+ * payment-grants).
+ */
+export declare class GrantsClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    listGrants(query?: ListGrantsQuery): Promise<ListGrantsResult>;
+    /**
+     * Every grant matching `query`, following the cursor to completion. Use when a
+     * caller needs the whole set (reach tagging, catch-up, an owner listing) rather
+     * than a single page — `listGrants` returns only one page (server default 30),
+     * so a holder with more grants than a page would otherwise be silently
+     * truncated. `maxPages` bounds the loop as a runaway guard.
+     */
+    listAllGrants(query?: Omit<ListGrantsQuery, 'cursor'>, maxPages?: number): Promise<GrantView[]>;
+}

package/dist/http/GrantsClient.js

@@ -0,0 +1,72 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+/**
+ * ZIG-648 — unified grant listing across every rail. `GET /grants` returns the
+ * canonical GrantView for each grant the caller holds (or, admin-gated, a named
+ * holder), filterable by scope kind and health, with cursor pagination. Replaces
+ * the old per-rail listers (context discovery, connection-grants,
+ * payment-grants).
+ */
+export class GrantsClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId, baseUrl) {
+        if (!operatorKey)
+            throw new Error('GrantsClient: operatorKey is required');
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl || getBackendUrl();
+    }
+    async listGrants(query = {}) {
+        const url = new URL(`${this.baseUrl}/grants`);
+        if (query.holderId)
+            url.searchParams.set('holderId', query.holderId);
+        if (query.scopeKind) {
+            const kinds = Array.isArray(query.scopeKind)
+                ? query.scopeKind
+                : [query.scopeKind];
+            for (const k of kinds)
+                url.searchParams.append('scopeKind', k);
+        }
+        if (query.health)
+            url.searchParams.set('health', query.health);
+        if (query.cursor)
+            url.searchParams.set('cursor', query.cursor);
+        if (query.limit != null)
+            url.searchParams.set('limit', String(query.limit));
+        const res = await fetch(url.toString(), {
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw new Error(`GrantsClient.listGrants ${res.status} ${body.slice(0, 200)}`);
+        }
+        const parsed = JSON.parse(body);
+        return {
+            items: parsed.items ?? [],
+            nextCursor: parsed.nextCursor ?? null,
+            hasMore: parsed.hasMore ?? false,
+        };
+    }
+    /**
+     * Every grant matching `query`, following the cursor to completion. Use when a
+     * caller needs the whole set (reach tagging, catch-up, an owner listing) rather
+     * than a single page — `listGrants` returns only one page (server default 30),
+     * so a holder with more grants than a page would otherwise be silently
+     * truncated. `maxPages` bounds the loop as a runaway guard.
+     */
+    async listAllGrants(query = {}, maxPages = 50) {
+        const all = [];
+        let cursor;
+        for (let page = 0; page < maxPages; page++) {
+            const res = await this.listGrants({ ...query, cursor });
+            all.push(...res.items);
+            if (!res.nextCursor)
+                return all;
+            cursor = res.nextCursor;
+        }
+        return all;
+    }
+}

package/dist/http/PaymentsClient.d.ts

@@ -0,0 +1,94 @@
+import 'dotenv/config';
+import type { GrantView } from './grants.js';
+/** Thrown by PaymentsClient with the HTTP status and raw body attached. */
+export interface PaymentsError extends Error {
+    status?: number;
+    body?: string;
+}
+export interface WalletBalance {
+    walletId: string | null;
+    currency: string;
+    balance: number;
+    availableBalance: number;
+}
+/**
+ * ZIG-894 — the one payments client for every surface (agent-sdk, ziggs-mcp,
+ * scripts). Consolidates the former agent-sdk private ZiggsPayClient. Wallet
+ * ops ride the operator key; agent-impersonated calls send X-Agent-Id and are
+ * policy-gated server-side (transfers above threshold return
+ * `approval_required`). Wallet-rail grant mutations (issue / attenuate /
+ * revoke) live here; grant *listing* is the unified GET /grants (ZIG-648).
+ */
+export declare class PaymentsClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    balance(): Promise<WalletBalance>;
+    resolve({ userId, agentId }?: {
+        userId?: string;
+        agentId?: string;
+    }): Promise<unknown>;
+    transfer({ to, amount, idempotencyKey, description, paymentGrantId, }: {
+        to: string;
+        amount: number;
+        idempotencyKey?: string;
+        description?: string;
+        paymentGrantId?: string;
+    }): Promise<unknown>;
+    hold({ amount, idempotencyKey, description, }: {
+        amount: number;
+        idempotencyKey?: string;
+        description?: string;
+    }): Promise<unknown>;
+    release({ holdId, action, toWalletId, idempotencyKey, }: {
+        holdId: string;
+        action?: string;
+        toWalletId?: string;
+        idempotencyKey?: string;
+    }): Promise<unknown>;
+    history(params?: {
+        limit?: number;
+        offset?: number;
+        type?: string;
+    }): Promise<unknown>;
+    issueGrant({ holderId, caveats }: {
+        holderId: string;
+        caveats?: unknown;
+    }): Promise<unknown>;
+    attenuateGrant({ grantId, holderId, caveats, }: {
+        grantId: string;
+        holderId: string;
+        caveats?: unknown;
+    }): Promise<unknown>;
+    revokeGrant(grantId: string): Promise<unknown>;
+    /**
+     * Live wallet grants the acting agent holds, via the unified GET /grants
+     * (ZIG-648 retired GET /payments/grants), following the cursor to completion.
+     */
+    listGrants(): Promise<GrantView[]>;
+    createTopUpIntent({ amount, description, currency, }?: {
+        amount?: number;
+        description?: string;
+        currency?: string;
+    }): Promise<unknown>;
+    confirmMockIntent(intentId: string): Promise<unknown>;
+    faucet({ amount, description, idempotencyKey, }?: {
+        amount?: number;
+        description?: string;
+        idempotencyKey?: string;
+    }): Promise<unknown>;
+    approvals({ status }?: {
+        status?: string;
+    }): Promise<unknown[]>;
+    getApproval(approvalId: string): Promise<unknown | null>;
+    decide(approvalId: string, decision: string, note?: string): Promise<unknown>;
+    waitForApproval(approvalId: string, opts?: {
+        pollMs?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    private _request;
+    private _get;
+    private _post;
+}

package/dist/http/PaymentsClient.js

@@ -0,0 +1,231 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+import { GrantsClient } from './GrantsClient.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
+ * ops ride the operator key; agent-impersonated calls send X-Agent-Id and are
+ * policy-gated server-side (transfers above threshold return
+ * `approval_required`). Wallet-rail grant mutations (issue / attenuate /
+ * revoke) live here; grant *listing* is the unified GET /grants (ZIG-648).
+ */
+export class PaymentsClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId, baseUrl) {
+        if (!operatorKey)
+            throw new Error('PaymentsClient: operatorKey is required');
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl || getBackendUrl();
+    }
+    async balance() {
+        const w = (await this._get('/payments/wallet'));
+        const wallet = w['wallet'];
+        return {
+            walletId: wallet?.['walletId'] || null,
+            currency: wallet?.['currency'] || 'pez',
+            balance: w['balance'] ?? 0,
+            availableBalance: w['availableBalance'] ?? 0,
+        };
+    }
+    async resolve({ userId, agentId } = {}) {
+        if (!userId && !agentId)
+            throw new Error('resolve: provide userId or agentId');
+        const params = new URLSearchParams();
+        if (userId)
+            params.set('userId', userId);
+        if (agentId)
+            params.set('agentId', agentId);
+        const res = (await this._get(`/payments/wallets/resolve?${params}`));
+        return res['wallet'] || null;
+    }
+    async transfer({ to, amount, idempotencyKey, description, paymentGrantId, }) {
+        if (!to)
+            throw new Error('transfer: `to` is required');
+        if (!(Number.isInteger(amount) && amount > 0))
+            throw new Error('transfer: `amount` must be a positive integer (cents)');
+        if (this.agentId && !paymentGrantId)
+            throw new Error('transfer: paymentGrantId is required for agent-impersonated transfers. The wallet owner must have issued a payment grant to this agentId.');
+        let toWalletId = to;
+        if (!to.startsWith('wal_')) {
+            const w = (await this.resolve(to.startsWith('agent_') ? { agentId: to } : { userId: to }));
+            if (!w?.['walletId'])
+                throw new Error(`transfer: could not resolve wallet for "${to}"`);
+            toWalletId = w['walletId'];
+        }
+        const result = (await this._post('/payments/transfer', {
+            toWalletId,
+            amount,
+            idempotencyKey: idempotencyKey || randomIdempotencyKey('xfer'),
+            description,
+            paymentGrantId,
+        }));
+        if (result?.['status'] === 'approval_required') {
+            const approval = result['approval'] || {};
+            return {
+                status: 'approval_required',
+                approvalId: approval['approvalId'] || null,
+                expiresAt: approval['expiresAt'] || null,
+                reason: approval['reason'] || 'Amount exceeds auto-approve threshold',
+                toWalletId,
+                amount,
+            };
+        }
+        const tx = result?.['transaction'];
+        return { status: 'transferred', transactionId: tx?.['transactionId'] || null, toWalletId, amount };
+    }
+    async hold({ amount, idempotencyKey, description, }) {
+        if (!(Number.isInteger(amount) && amount > 0))
+            throw new Error('hold: `amount` must be a positive integer (cents)');
+        return this._post('/payments/hold', {
+            amount,
+            idempotencyKey: idempotencyKey || randomIdempotencyKey('hold'),
+            description,
+        });
+    }
+    async release({ holdId, action = 'complete', toWalletId, idempotencyKey, }) {
+        return this._post(`/payments/release/${holdId}`, {
+            idempotencyKey: idempotencyKey || randomIdempotencyKey('rel'),
+            action,
+            toWalletId,
+        });
+    }
+    async history(params = {}) {
+        const q = new URLSearchParams();
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.offset != null)
+            q.set('offset', String(params.offset));
+        if (params.type)
+            q.set('type', params.type);
+        return this._get('/payments/history' + (q.toString() ? `?${q}` : ''));
+    }
+    async issueGrant({ holderId, caveats }) {
+        return this._post('/payments/grants', { holderId, caveats });
+    }
+    async attenuateGrant({ grantId, holderId, caveats, }) {
+        return this._post(`/payments/grants/${grantId}/attenuate`, { holderId, caveats });
+    }
+    async revokeGrant(grantId) {
+        return this._request('DELETE', `/payments/grants/${grantId}`, undefined);
+    }
+    /**
+     * Live wallet grants the acting agent holds, via the unified GET /grants
+     * (ZIG-648 retired GET /payments/grants), following the cursor to completion.
+     */
+    async listGrants() {
+        const grants = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl);
+        return grants.listAllGrants({ scopeKind: 'wallet', health: 'active' });
+    }
+    async createTopUpIntent({ amount, description, currency, } = {}) {
+        return this._post('/payments/onramp/intent', { amount, description, currency });
+    }
+    async confirmMockIntent(intentId) {
+        return this._post(`/payments/onramp/mock-confirm/${intentId}`, {});
+    }
+    async faucet({ amount, description = 'Faucet', idempotencyKey, } = {}) {
+        return this._post('/payments/wallet/fund', {
+            amount,
+            idempotencyKey: idempotencyKey || randomIdempotencyKey('faucet'),
+            description,
+        });
+    }
+    async approvals({ status = 'pending' } = {}) {
+        const res = (await this._get(`/payments/approvals?status=${encodeURIComponent(status)}`));
+        return res['approvals'] || [];
+    }
+    async getApproval(approvalId) {
+        if (!approvalId)
+            throw new Error('getApproval: approvalId is required');
+        try {
+            const res = (await this._get(`/payments/approvals/${approvalId}`));
+            return res?.['approval'] || null;
+        }
+        catch (err) {
+            if (err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    async decide(approvalId, decision, note = '') {
+        return this._post(`/payments/approvals/${approvalId}/decide`, { decision, note });
+    }
+    async waitForApproval(approvalId, opts = {}) {
+        const pollMs = Math.max(500, opts.pollMs ?? 3_000);
+        const timeoutMs = Math.max(pollMs, opts.timeoutMs ?? 120_000);
+        const signal = opts.signal;
+        const deadline = Date.now() + timeoutMs;
+        const sleep = (ms) => new Promise((resolve, reject) => {
+            const timer = setTimeout(resolve, ms);
+            if (signal) {
+                if (signal.aborted) {
+                    clearTimeout(timer);
+                    reject(new Error('aborted'));
+                    return;
+                }
+                signal.addEventListener('abort', () => {
+                    clearTimeout(timer);
+                    reject(new Error('aborted'));
+                }, { once: true });
+            }
+        });
+        while (true) {
+            if (signal?.aborted)
+                throw new Error('aborted');
+            const approval = (await this.getApproval(approvalId));
+            if (!approval)
+                return { status: 'gone' };
+            const s = approval['status'];
+            if (s === 'executed')
+                return { status: 'executed', approval, transactionId: approval['executedTransactionId'] || null };
+            if (s === 'rejected')
+                return { status: 'rejected', approval };
+            if (s === 'expired')
+                return { status: 'expired', approval };
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return { status: 'timeout', approval };
+            await sleep(Math.min(pollMs, remaining));
+        }
+    }
+    async _request(method, path, body) {
+        const init = {
+            method,
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, body !== undefined ? { 'content-type': 'application/json' } : {}),
+        };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        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}`));
+            err.status = response.status;
+            err.body = text;
+            throw err;
+        }
+        return text ? JSON.parse(text) : null;
+    }
+    _get(path) {
+        return this._request('GET', path, undefined);
+    }
+    _post(path, body) {
+        return this._request('POST', path, body ?? {});
+    }
+}

package/dist/http/grantRails.d.ts

@@ -0,0 +1,20 @@
+import type { GrantScopeKind } from './grants.js';
+/**
+ * Read the `scopes` claim of an operator JWT without verifying its signature —
+ * an identity hint only, exactly as the backend re-checks the key row on every
+ * request. Returns null when the token isn't a decodable JWT (so callers treat
+ * entitlement as unknown rather than empty).
+ */
+export declare function decodeOperatorScopes(operatorKey: string): string[] | null;
+export interface UnreadableRail {
+    rail: 'context' | 'connection' | 'wallet';
+    requiredScope: string;
+}
+/**
+ * Which grant rails the operator key can't read, among those requested (or all
+ * rails when no filter is given). Returns null when the key's scopes can't be
+ * decoded — the caller then omits the "what I can't see" note rather than
+ * guessing. `GET /grants` enforces the same boundary server-side; this only
+ * lets the tool surface report it.
+ */
+export declare function unreadableGrantRails(operatorKey: string, requested?: readonly GrantScopeKind[]): UnreadableRail[] | null;

package/dist/http/grantRails.js

@@ -0,0 +1,50 @@
+const RAIL_GROUPS = [
+    { rail: 'context', kinds: ['chat', 'agreement', 'org'], requiredScope: 'context:read' },
+    { rail: 'connection', kinds: ['connection'], requiredScope: 'connections:read' },
+    { rail: 'wallet', kinds: ['wallet'], requiredScope: 'payments:read' },
+];
+/**
+ * Read the `scopes` claim of an operator JWT without verifying its signature —
+ * an identity hint only, exactly as the backend re-checks the key row on every
+ * request. Returns null when the token isn't a decodable JWT (so callers treat
+ * entitlement as unknown rather than empty).
+ */
+export function decodeOperatorScopes(operatorKey) {
+    const parts = (operatorKey ?? '').trim().split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+        const payload = JSON.parse(json);
+        if (!Array.isArray(payload.scopes))
+            return null;
+        return payload.scopes.filter((s) => typeof s === 'string');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Which grant rails the operator key can't read, among those requested (or all
+ * rails when no filter is given). Returns null when the key's scopes can't be
+ * decoded — the caller then omits the "what I can't see" note rather than
+ * guessing. `GET /grants` enforces the same boundary server-side; this only
+ * lets the tool surface report it.
+ */
+export function unreadableGrantRails(operatorKey, requested) {
+    const scopes = decodeOperatorScopes(operatorKey);
+    if (scopes === null)
+        return null;
+    const held = new Set(scopes);
+    const wanted = requested && requested.length > 0 ? new Set(requested) : null;
+    const out = [];
+    for (const group of RAIL_GROUPS) {
+        const inScope = wanted ? group.kinds.some((k) => wanted.has(k)) : true;
+        if (!inScope)
+            continue;
+        if (!held.has(group.requiredScope)) {
+            out.push({ rail: group.rail, requiredScope: group.requiredScope });
+        }
+    }
+    return out;
+}

package/dist/http/grants.d.ts

@@ -15,6 +15,12 @@ export type GrantScopeKind = 'chat' | 'agreement' | 'org' | 'connection' | 'wall
 export interface GrantScopeView {
     kind: GrantScopeKind;
     id: string;
+    /**
+     * Human-readable name for the scoped resource, populated only by the unified
+     * list read (GET /grants / GrantsClient); the per-rail issue/delegate
+     * responses omit it. Optional so the one shape stays additive.
+     */
+    label?: string;
 }
 export interface GrantCaveatView {
     type: string;

package/dist/http/index.d.ts

@@ -9,11 +9,19 @@ export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, List
 export { ContextReadClient } from './ContextReadClient.js';
 export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
-export type { ContextReachDescriptor } from './ContextDiscoveryClient.js';
+export type { DiscoverableItem } from './ContextDiscoveryClient.js';
+export { GrantsClient } from './GrantsClient.js';
+export type { ListGrantsQuery, ListGrantsResult } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
-export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, } from './ContextGrantsClient.js';
+export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, DelegateContextGrantResult, ReachEntry, GrantReachResult, } from './ContextGrantsClient.js';
 export { grantCaveat } from './grants.js';
 export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, } from './grants.js';
+export { decodeOperatorScopes, unreadableGrantRails } from './grantRails.js';
+export type { UnreadableRail } from './grantRails.js';
+export { PaymentsClient } from './PaymentsClient.js';
+export type { PaymentsError, WalletBalance } from './PaymentsClient.js';
+export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
+export type { ConnectionsError, ConnectionProxyParams, McpConnectionRequestParams, } from './ConnectionsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';

package/dist/http/index.js

@@ -6,8 +6,12 @@ export { MessagesClient } from './MessagesClient.js';
 export { ArtifactsClient } from './ArtifactsClient.js';
 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 { decodeOperatorScopes, unreadableGrantRails } from './grantRails.js';
+export { PaymentsClient } from './PaymentsClient.js';
+export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';

package/dist/websocket/WebSocketClient.js

@@ -109,6 +109,15 @@ export class WebSocketClient {
         this.socket.on('error', (error) => {
             runtimeLog.error(this.label, `Socket.IO error: ${String(error)}`);
         });
+        // ZIG-860: the send path is fire-and-forget (no ack callback), so the
+        // backend's structured rejection is the ONLY failure signal. Not listening
+        // made every rejected send silent — an agent's message just vanished (the
+        // a2a schema bug hid behind exactly this). Log loudly; delivery recovery
+        // stays with the inbox/catch-up machinery.
+        this.socket.on('chat:error', (payload) => {
+            const p = (payload ?? {});
+            runtimeLog.error(this.label, `chat:error [${p['code'] ?? 'UNKNOWN'}] chatId=${p['chatId'] ?? '-'} messageId=${p['messageId'] ?? '-'}: ${p['message'] ?? ''}`);
+        });
     }
     connectAsync(timeout = 10_000) {
         if (this.socket?.connected)

package/package.json

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