@ziggs-ai/api-client 0.1.29 → 0.2.0

package/README.md

@@ -10,25 +10,11 @@ npm install @ziggs-ai/api-client
 
 ## Usage
 
-### WebSocket Client
-
-Real-time bidirectional communication with the Ziggs backend:
-
-```javascript
-import { WebSocketClient } from '@ziggs-ai/api-client';
-
-const client = new WebSocketClient({
-  operatorKey: process.env.ZIGGS_OPERATOR_KEY,
-  agentId: 'my-agent-id',
-});
-
-client.setMessageHandler(async (text, metadata) => {
-  console.log('Received:', text);
-  console.log('From:', metadata.senderId);
-});
-
-client.connect();
-```
+Delivery is a stateless HTTP pull — there is no WebSocket client. An agent
+receives work by long-polling its inbox: `GET /inbox?wait=25` (held open until
+something passes the caller's cursor) → act → `POST /inbox/ack`. Because the
+cursor lives server-side, any HTTP client following this loop is both correct
+and live. See `docs/unified-inbox-wake-queue.md` for the reference loop.
 
 ### HTTP Clients
 

package/dist/ConnectionManager.d.ts

@@ -1,4 +1,3 @@
-import { type ControlSocketOptions } from './websocket/ControlSocket.js';
 type OpenFn = () => Promise<unknown>;
 type CloseFn = (handle: unknown) => Promise<void>;
 export interface ConnectionManagerMeta {
@@ -10,7 +9,18 @@ export interface ConnectionManagerMeta {
 export interface ConnectionManagerOptions {
     maxActive?: number;
     idleTimeoutMs?: number;
-    control?: Pick<ControlSocketOptions, 'wsUrl' | 'operatorKey'>;
+    /**
+     * Fleet control (delivery law, phase 4): the operator key whose owned agents
+     * this manager lazily starts. `start()` long-polls `GET /inbox/operator` with
+     * this key; when an agent's slice shows actionable content, it starts that
+     * agent's host (which then consumes via its own per-agent inbox loop). No
+     * socket, no wake push — lazy process management driven by the poll. `wsUrl`
+     * is accepted for back-compat but unused (the poll is HTTP).
+     */
+    control?: {
+        wsUrl?: string;
+        operatorKey?: string;
+    };
 }
 export interface QueryFilter {
     domain?: string;
@@ -20,16 +30,25 @@ export interface QueryFilter {
 export declare class ConnectionManager {
     private maxActive;
     private idleTimeoutMs;
-    private _controlOpts;
-    private _controlHandle;
+    private _operatorKey;
+    private _polling;
+    private _pollDone;
     private _entries;
     private _active;
     private _meta;
     private _waking;
     constructor({ maxActive, idleTimeoutMs, control }?: ConnectionManagerOptions);
     register(id: string, openFn: OpenFn, closeFn: CloseFn, meta?: ConnectionManagerMeta): void;
-    start(): void;
+    start(operatorKey?: string): void;
     stop(): Promise<void>;
+    /**
+     * Fleet lazy-start loop: long-poll the operator inbox and start a host for any
+     * owned agent whose slice is actionable and not already running. The started
+     * host consumes + acks via its own per-agent inbox loop, so this loop never
+     * acks — it only decides which hosts to run. Errors retry with backoff+jitter;
+     * the loop never exits until `stop()` (nothing to resynchronize).
+     */
+    private _runOperatorPoll;
     wake(id: string): Promise<unknown>;
     sleep(id: string): Promise<void>;
     sleepAll(): Promise<void>;

package/dist/ConnectionManager.js

@@ -1,10 +1,17 @@
-import { createControlSocket } from './websocket/ControlSocket.js';
+import { InboxClient } from './http/InboxClient.js';
 import { runtimeLog } from './shared/runtimeLog.js';
+const OPERATOR_POLL_WAIT_SECONDS = 25;
+const POLL_BACKOFF_BASE_MS = 1_000;
+const POLL_BACKOFF_MAX_MS = 30_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export class ConnectionManager {
     maxActive;
     idleTimeoutMs;
-    _controlOpts;
-    _controlHandle;
+    _operatorKey;
+    _polling;
+    _pollDone;
     _entries;
     _active;
     _meta;
@@ -12,8 +19,9 @@ export class ConnectionManager {
     constructor({ maxActive = 50, idleTimeoutMs = 60_000, control } = {}) {
         this.maxActive = maxActive;
         this.idleTimeoutMs = idleTimeoutMs;
-        this._controlOpts = control ?? null;
-        this._controlHandle = null;
+        this._operatorKey = control?.operatorKey ?? null;
+        this._polling = false;
+        this._pollDone = null;
         this._entries = new Map();
         this._active = new Map();
         this._meta = new Map();
@@ -30,20 +38,56 @@ export class ConnectionManager {
         if (meta)
             this._meta.set(id, meta);
     }
-    start() {
-        if (this._controlHandle || !this._controlOpts)
+    start(operatorKey) {
+        if (operatorKey)
+            this._operatorKey = operatorKey;
+        if (this._polling || !this._operatorKey)
             return;
-        this._controlHandle = createControlSocket({
-            ...this._controlOpts,
-            agentIds: () => this.list(),
-            onWake: (id) => this.wake(id).catch(err => runtimeLog.warn('ConnectionManager', `wake("${id}") failed: ${err.message}`)),
-        });
+        this._polling = true;
+        this._pollDone = this._runOperatorPoll(this._operatorKey);
     }
     async stop() {
-        this._controlHandle?.close();
-        this._controlHandle = null;
+        this._polling = false;
+        if (this._pollDone)
+            await this._pollDone.catch(() => { });
+        this._pollDone = null;
         await this.sleepAll();
     }
+    /**
+     * Fleet lazy-start loop: long-poll the operator inbox and start a host for any
+     * owned agent whose slice is actionable and not already running. The started
+     * host consumes + acks via its own per-agent inbox loop, so this loop never
+     * acks — it only decides which hosts to run. Errors retry with backoff+jitter;
+     * the loop never exits until `stop()` (nothing to resynchronize).
+     */
+    async _runOperatorPoll(operatorKey) {
+        // No agentId → operator-level multiplex read (transport auth only).
+        const inbox = new InboxClient(operatorKey);
+        let consecutiveErrors = 0;
+        while (this._polling) {
+            try {
+                const env = await inbox.getOperatorInbox({ waitSeconds: OPERATOR_POLL_WAIT_SECONDS });
+                consecutiveErrors = 0;
+                for (const entry of env.agents) {
+                    const id = entry.agentId;
+                    // Only slices with actionable content are listed; start the host if
+                    // it isn't already running and we know how to open it.
+                    if (!id || this._active.has(id) || !this._entries.has(id))
+                        continue;
+                    this.wake(id).catch((err) => runtimeLog.warn('ConnectionManager', `lazy-start("${id}") failed: ${err.message}`));
+                }
+            }
+            catch (err) {
+                if (!this._polling)
+                    break;
+                consecutiveErrors++;
+                const backoff = Math.min(POLL_BACKOFF_MAX_MS, POLL_BACKOFF_BASE_MS * 2 ** (consecutiveErrors - 1));
+                const jitter = backoff * (0.5 + (consecutiveErrors % 7) / 14);
+                runtimeLog.warn('ConnectionManager', `operator poll failed (#${consecutiveErrors}): ${err.message} — retrying in ~${Math.round(jitter)}ms`);
+                await sleep(jitter);
+            }
+        }
+    }
     async wake(id) {
         const existing = this._active.get(id);
         if (existing) {

package/dist/http/ArtifactsClient.d.ts

@@ -23,6 +23,13 @@ export interface WriteArtifactInput {
     /** Optional task binding — creates a TaskArtifactLink alongside the primary scope link. */
     taskId?: string;
     service?: Record<string, unknown>;
+    /**
+     * Optional idempotency key. A redelivered write with the same key (same
+     * sender) no-ops server-side and returns the original artifact. Derive it
+     * deterministically from durable inputs so a stateless crash-replay
+     * reproduces it.
+     */
+    idempotencyKey?: string;
 }
 /**
  * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
@@ -47,7 +54,20 @@ export declare class ArtifactsClient {
      * endpoint is updated to accept `visibility`, this falls back to logging
      * locally (operators can still wire their own sink).
      */
-    recordThought(chatId: string, text: string): Promise<void>;
+    recordThought(chatId: string, text: string, opts?: {
+        idempotencyKey?: 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

@@ -49,20 +49,40 @@ export class ArtifactsClient {
      * endpoint is updated to accept `visibility`, this falls back to logging
      * locally (operators can still wire their own sink).
      */
-    async recordThought(chatId, text) {
+    async recordThought(chatId, text, opts = {}) {
         return this.write({
             chatId,
             text,
             content_type: 'thought',
             visibility: 'agent-private',
+            idempotencyKey: opts.idempotencyKey,
         });
     }
     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',
@@ -75,12 +95,24 @@ export class ArtifactsClient {
                 agreementId: input.agreementId,
                 taskId: input.taskId,
                 service: input.service,
+                ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
             }),
         });
+        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/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/InboxClient.d.ts

@@ -84,6 +84,32 @@ export interface InboxAckResult {
         ackedUpTo: string;
     }>;
 }
+/**
+ * Long-poll option shared by the inbox reads. The server holds the request up
+ * to this many seconds (server-clamped, ~25s ceiling) and returns as soon as
+ * anything actionable exists. Omit for an immediate snapshot — the response
+ * shape is identical either way, so `wait` only changes how long an EMPTY
+ * answer is withheld.
+ */
+export interface InboxReadOptions {
+    waitSeconds?: number;
+}
+/** One agent's slice of the operator-level multiplexed read. */
+export interface InboxOperatorAgentEntry {
+    agentId: string;
+    /** That agent's own inbox — fenced to its grants, floored by its cursors. */
+    inbox: InboxEnvelope;
+}
+/** GET /inbox/operator: one poll across every agent the key's owner runs. */
+export interface InboxOperatorEnvelope {
+    asOf: string;
+    /** Agents with actionable content only. */
+    agents: InboxOperatorAgentEntry[];
+    /** Agents examined whose inboxes were empty. */
+    idleAgents: number;
+    /** Owned agents beyond the server's per-pass cap — not examined. */
+    truncatedAgents: number;
+}
 /**
  * The doorbell, not the door (ZIG-434): references and counts since the
  * agent's last ack — never content. Flow: inbox → read → act → ack (ZIG-446).
@@ -99,6 +125,14 @@ export declare class InboxClient {
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     private headers;
-    getInbox(): Promise<InboxEnvelope>;
+    private inboxUrl;
+    getInbox(opts?: InboxReadOptions): Promise<InboxEnvelope>;
+    /**
+     * Operator-level multiplexed read: one poll for every agent this key's
+     * owner runs, each slice fenced to its own agent (an agent-scoped key
+     * collapses to its one agent). Ack stays per agent — use a per-agent
+     * client's `ack()` after acting on that agent's slice.
+     */
+    getOperatorInbox(opts?: InboxReadOptions): Promise<InboxOperatorEnvelope>;
     ack(scopes: InboxAck[]): Promise<InboxAckResult>;
 }