@ziggs-ai/api-client 0.1.29 → 0.2.0

package/dist/http/InboxClient.js

@@ -29,8 +29,15 @@ export class InboxClient {
             headers['X-Agent-Id'] = this.agentId;
         return headers;
     }
-    async getInbox() {
-        const res = await fetch(`${this.baseUrl}/inbox`, {
+    inboxUrl(path, opts) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (opts.waitSeconds != null && opts.waitSeconds > 0) {
+            url.searchParams.set('wait', String(opts.waitSeconds));
+        }
+        return url.toString();
+    }
+    async getInbox(opts = {}) {
+        const res = await fetch(this.inboxUrl('/inbox', opts), {
             headers: this.headers(),
         });
         const body = await res.text().catch(() => '');
@@ -39,6 +46,22 @@ export class InboxClient {
         }
         return JSON.parse(body);
     }
+    /**
+     * 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.
+     */
+    async getOperatorInbox(opts = {}) {
+        const res = await fetch(this.inboxUrl('/inbox/operator', opts), {
+            headers: this.headers(),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw new Error(`InboxClient.getOperatorInbox ${res.status} ${body.slice(0, 200)}`);
+        }
+        return JSON.parse(body);
+    }
     async ack(scopes) {
         if (!scopes.length)
             throw new Error('InboxClient.ack: scopes are required');

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/TaskClient.d.ts

@@ -16,6 +16,14 @@ export declare function getTask(taskId: string, creds: Creds): Promise<Task>;
 export interface UpdateTaskStateData {
     result?: unknown;
     errorMessage?: string;
+    /**
+     * Optional idempotency key. A redelivered transition carrying the same key
+     * no-ops server-side (returns the current task) instead of erroring on an
+     * already-terminal task. Sent in the body — the backend reads
+     * `UpdateTaskStateDto.idempotencyKey`. Derive it deterministically so a
+     * stateless crash-replay reproduces it.
+     */
+    idempotencyKey?: string;
 }
 export declare function updateTaskState(taskId: string, state: TaskState, data: UpdateTaskStateData | undefined, creds: Creds): Promise<Task>;
 export declare function getActiveTasksForAgent(agentId: string, creds: Creds): Promise<Task[]>;

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/index.d.ts

@@ -13,9 +13,15 @@ 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

@@ -9,6 +9,9 @@ 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/index.d.ts

@@ -1,7 +1,5 @@
 export * from './http/index.js';
 export * from './relay/provisionRelayWorkers.js';
-export { WebSocketClient } from './websocket/index.js';
-export { createControlSocket } from './websocket/ControlSocket.js';
 export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';

package/dist/index.js

@@ -1,7 +1,5 @@
 export * from './http/index.js';
 export * from './relay/provisionRelayWorkers.js';
-export { WebSocketClient } from './websocket/index.js';
-export { createControlSocket } from './websocket/ControlSocket.js';
 export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';

package/package.json

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

package/dist/websocket/ControlSocket.d.ts

@@ -1,13 +0,0 @@
-import { type Socket } from 'socket.io-client';
-export interface ControlSocketOptions {
-    wsUrl: string;
-    operatorKey: string;
-    agentIds: () => string[];
-    onWake: (agentId: string) => void;
-}
-export interface ControlSocketHandle {
-    socket: Socket;
-    close: () => void;
-    resync: () => void;
-}
-export declare function createControlSocket({ wsUrl, operatorKey, agentIds, onWake }: ControlSocketOptions): ControlSocketHandle;

package/dist/websocket/ControlSocket.js

@@ -1,37 +0,0 @@
-import { io } from 'socket.io-client';
-import { runtimeLog } from '../shared/runtimeLog.js';
-export function createControlSocket({ wsUrl, operatorKey, agentIds, onWake }) {
-    if (!wsUrl || !operatorKey)
-        throw new Error('[createControlSocket] wsUrl and operatorKey are required');
-    if (typeof agentIds !== 'function')
-        throw new Error('[createControlSocket] agentIds must be a function returning string[]');
-    if (typeof onWake !== 'function')
-        throw new Error('[createControlSocket] onWake must be a function');
-    const socket = io(wsUrl, {
-        auth: { token: `Bearer ${operatorKey}` },
-        query: { token: operatorKey, role: 'launcher' },
-        extraHeaders: { Authorization: `Bearer ${operatorKey}` },
-        transports: ['websocket'],
-        reconnection: true,
-        reconnectionDelay: 1000,
-        reconnectionDelayMax: 30000,
-        randomizationFactor: 0.5,
-    });
-    socket.on('connect', () => {
-        const ids = agentIds();
-        runtimeLog.info('ControlSocket', `connected (${socket.id}); registering ${ids.length} agent(s)`);
-        socket.emit('launcher:register', { agentIds: ids });
-    });
-    socket.on('launcher:wake', ({ agentId }) => {
-        if (agentId)
-            onWake(agentId);
-    });
-    socket.on('disconnect', (reason) => runtimeLog.debug('ControlSocket', `disconnected: ${reason}`));
-    socket.on('connect_error', (err) => runtimeLog.warn('ControlSocket', `connect error: ${err.message}`));
-    return {
-        socket,
-        close: () => socket.disconnect(),
-        resync: () => { if (socket.connected)
-            socket.emit('launcher:register', { agentIds: agentIds() }); },
-    };
-}

package/dist/websocket/WebSocketClient.d.ts

@@ -1,86 +0,0 @@
-import 'dotenv/config';
-import { type MessageHandler } from '../types.js';
-export interface WebSocketClientOptions {
-    wsUrl?: string;
-    operatorKey?: string;
-    agentId?: string;
-    /**
-     * Optional user JWT (from `POST /users/login`). When set, the socket
-     * authenticates as that user — the gateway populates `socket.userId` and
-     * routes messages to them as a human user. Mutually exclusive with
-     * `operatorKey` + `agentId`. Used by the eval harness to seed chats as a
-     * real user instead of impersonating an agent.
-     */
-    userToken?: string;
-    label?: string;
-}
-/**
- * Mirrors the backend `ResourceEvent` shape. Emitted on the wire as
- * `resource_changed` when a resource the agent has access to mutates.
- */
-export interface ResourceEvent {
-    kind: 'message' | 'artifact' | 'task-state' | 'agreement';
-    ts: string;
-    resourceId: string;
-    chatId?: string;
-    agreementId?: string;
-    taskId?: string;
-    change?: 'created' | 'updated' | 'state-changed';
-    reason?: string;
-    /**
-     * Principal whose action produced the event, when the backend knows it.
-     * Hosts drop events the receiving agent itself caused — its own writes
-     * aren't news to it.
-     */
-    actorId?: string;
-}
-export type ResourceEventHandler = (event: ResourceEvent) => void | Promise<void>;
-export interface SendOptions {
-    entryType?: string;
-    content_type?: string;
-    contentType?: string;
-    taskId?: string;
-    /**
-     * When true, emits a 'chat:chunk' event instead of 'chat'.
-     * Use for streaming partial responses; send a final message
-     * (partial: false or omitted) to signal end of stream.
-     * Requires backend streaming support.
-     */
-    partial?: boolean;
-    /** Pre-allocated messageId for streaming continuity — links chunks to the final message. */
-    messageId?: string;
-}
-export declare class WebSocketClient {
-    private wsUrl;
-    private operatorKey;
-    private agentId;
-    private userToken;
-    private label;
-    private socket;
-    private messageHandler;
-    private resourceEventHandler;
-    constructor(options?: WebSocketClientOptions);
-    setMessageHandler(handler: MessageHandler): void;
-    /**
-     * Subscribe to `resource_changed` notifications — the unified push channel
-     * for non-message resource changes (artifact, task-state, agreement). The
-     * agent decides whether to pull the corresponding primitive based on
-     * `event.kind` + ids. Replaces cursor-based polling for delta detection.
-     */
-    setResourceEventHandler(handler: ResourceEventHandler): void;
-    private connectHandlers;
-    /**
-     * Called on every socket connect, including socket.io reconnects.
-     * Used for inbox catch-up (ZIG-454) so missed pushes are recovered from MongoDB.
-     */
-    onConnect(handler: () => void | Promise<void>): void;
-    private _emitConnect;
-    private _connect;
-    connectAsync(timeout?: number): Promise<this>;
-    disconnect(): void;
-    send(chatId: string, receiverId: string, content: string, options?: SendOptions): void;
-    isConnected(): boolean;
-    handleIncomingMessage(payload: unknown): Promise<void>;
-    private buildSocketOptions;
-    private generateMessageId;
-}