@ziggs-ai/api-client 0.1.30 → 0.3.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,4 @@
-import { type ControlSocketOptions } from './websocket/ControlSocket.js';
+import { type InboxOperatorAgentEntry } from './http/InboxClient.js';
 type OpenFn = () => Promise<unknown>;
 type CloseFn = (handle: unknown) => Promise<void>;
 export interface ConnectionManagerMeta {
@@ -10,7 +10,26 @@ 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 push notification — lazy process management driven by the poll. `wsUrl`
+     * is accepted for back-compat but unused (the poll is HTTP).
+     */
+    control?: {
+        wsUrl?: string;
+        operatorKey?: string;
+    };
+    /**
+     * Gate on the operator-poll lazy start (ZIG-910). Called for each agent
+     * slice with actionable content before its host is started; return false to
+     * leave the host down this pass. The slice stays in later envelopes (reading
+     * never acks), so the gate is consulted again on every poll. Explicit
+     * `startAgent()` calls are not gated. Default: everything actionable starts.
+     */
+    shouldLazyStart?: (entry: InboxOperatorAgentEntry) => boolean;
 }
 export interface QueryFilter {
     domain?: string;
@@ -20,17 +39,27 @@ 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);
+    private _starting;
+    private _shouldLazyStart;
+    constructor({ maxActive, idleTimeoutMs, control, shouldLazyStart }?: ConnectionManagerOptions);
     register(id: string, openFn: OpenFn, closeFn: CloseFn, meta?: ConnectionManagerMeta): void;
-    start(): void;
+    start(operatorKey?: string): void;
     stop(): Promise<void>;
-    wake(id: string): Promise<unknown>;
+    /**
+     * 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;
+    startAgent(id: string): Promise<unknown>;
     sleep(id: string): Promise<void>;
     sleepAll(): Promise<void>;
     touch(id: string): void;

package/dist/ConnectionManager.js

@@ -1,23 +1,33 @@
-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;
-    _waking;
-    constructor({ maxActive = 50, idleTimeoutMs = 60_000, control } = {}) {
+    _starting;
+    _shouldLazyStart;
+    constructor({ maxActive = 50, idleTimeoutMs = 60_000, control, shouldLazyStart } = {}) {
         this.maxActive = maxActive;
         this.idleTimeoutMs = idleTimeoutMs;
-        this._controlOpts = control ?? null;
-        this._controlHandle = null;
+        this._shouldLazyStart = shouldLazyStart ?? null;
+        this._operatorKey = control?.operatorKey ?? null;
+        this._polling = false;
+        this._pollDone = null;
         this._entries = new Map();
         this._active = new Map();
         this._meta = new Map();
-        this._waking = new Map();
+        this._starting = new Map();
     }
     register(id, openFn, closeFn, meta) {
         if (!id)
@@ -30,27 +40,65 @@ 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();
     }
-    async wake(id) {
+    /**
+     * 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;
+                    if (this._shouldLazyStart && !this._shouldLazyStart(entry))
+                        continue;
+                    this.startAgent(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 startAgent(id) {
         const existing = this._active.get(id);
         if (existing) {
             this._resetTimer(id);
             return existing.handle;
         }
-        const pending = this._waking.get(id);
+        const pending = this._starting.get(id);
         if (pending)
             return pending;
         const entry = this._entries.get(id);
@@ -58,7 +106,7 @@ export class ConnectionManager {
             throw new Error(`[ConnectionManager] unknown id: "${id}"`);
         if (this._active.size >= this.maxActive)
             await this._evictLRU();
-        const wakePromise = (async () => {
+        const startPromise = (async () => {
             try {
                 const handle = await entry.openFn();
                 this._active.set(id, { handle, timer: null, lastActive: Date.now() });
@@ -66,11 +114,11 @@ export class ConnectionManager {
                 return handle;
             }
             finally {
-                this._waking.delete(id);
+                this._starting.delete(id);
             }
         })();
-        this._waking.set(id, wakePromise);
-        return wakePromise;
+        this._starting.set(id, startPromise);
+        return startPromise;
     }
     async sleep(id) {
         const entry = this._active.get(id);

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

package/dist/http/ArtifactsClient.js

@@ -49,12 +49,13 @@ 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) {
@@ -94,6 +95,7 @@ export class ArtifactsClient {
                 agreementId: input.agreementId,
                 taskId: input.taskId,
                 service: input.service,
+                ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
             }),
         });
         const body = await res.text().catch(() => '');

package/dist/http/ConnectionsClient.d.ts

@@ -29,7 +29,7 @@ export interface McpConnectionRequestParams {
 /**
  * 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
+ * (proxy, requestMcpConnection). 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

package/dist/http/ConnectionsClient.js

@@ -23,7 +23,7 @@ export function assertNoLeakedConnectionSecret(serialized) {
 /**
  * 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
+ * (proxy, requestMcpConnection). 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

package/dist/http/ContextDiscoveryClient.d.ts

@@ -1,10 +1,14 @@
 import 'dotenv/config';
-/** Labels-only pointer to context the agent could request access to (P4). */
+/**
+ * Labels-only pointer to context the agent could request access to (P4).
+ * ZIG-927: covers chats, agreements, and connections; connection labels are the
+ * provider name only (never tokens/account labels).
+ */
 export interface DiscoverableItem {
-    type: 'chat';
+    type: 'chat' | 'agreement' | 'connection';
     label: string;
     scopeRef: {
-        kind: 'chat' | 'agreement' | 'org';
+        kind: 'chat' | 'agreement' | 'org' | 'connection';
         id: string;
     };
     orgId: string;

package/dist/http/ContextReadClient.d.ts

@@ -53,7 +53,7 @@ export declare class ContextReadClient {
     /**
      * Aggregated chat snapshot — `GET /context/snapshot?via=chat:<id>`. The
      * server composes history + agreements + roster through the same grant-fenced
-     * readers as {@link read}, so hosted agents pull one fenced view per wake.
+     * readers as {@link read}, so hosted agents pull one fenced view per poll cycle.
      * Rejects with an `Error & { status }` on non-OK so callers can branch (404).
      */
     snapshot(chatId: string, opts?: {

package/dist/http/ContextReadClient.js

@@ -56,7 +56,7 @@ export class ContextReadClient {
     /**
      * Aggregated chat snapshot — `GET /context/snapshot?via=chat:<id>`. The
      * server composes history + agreements + roster through the same grant-fenced
-     * readers as {@link read}, so hosted agents pull one fenced view per wake.
+     * readers as {@link read}, so hosted agents pull one fenced view per poll cycle.
      * Rejects with an `Error & { status }` on non-OK so callers can branch (404).
      */
     async snapshot(chatId, opts = {}) {

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>;
 }

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

@@ -25,4 +25,4 @@ export type { ConnectionsError, ConnectionProxyParams, McpConnectionRequestParam
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
-export type { InboxScopeKind, InboxScopeEntry, InboxProposalRef, InboxConnectionRequestRef, InboxMcpServerRequestRef, InboxHumanAttention, InboxEnvelope, InboxAck, InboxAckResult, } from './InboxClient.js';
+export type { InboxScopeKind, InboxScopeEntry, InboxProposalRef, InboxConnectionRequestRef, InboxMcpServerRequestRef, InboxHumanAttention, InboxEnvelope, InboxAck, InboxAckResult, InboxOperatorAgentEntry, InboxOperatorEnvelope, } 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.30",
+  "version": "0.3.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;
-}

package/dist/websocket/WebSocketClient.js

@@ -1,268 +0,0 @@
-import { io } from 'socket.io-client';
-import 'dotenv/config';
-import { getWebSocketUrl } from '../utils/urlUtils.js';
-import { runtimeLog } from '../shared/runtimeLog.js';
-export class WebSocketClient {
-    wsUrl;
-    operatorKey;
-    agentId;
-    userToken;
-    label;
-    socket;
-    messageHandler;
-    resourceEventHandler;
-    constructor(options = {}) {
-        this.wsUrl = options.wsUrl || getWebSocketUrl();
-        this.userToken = options.userToken || null;
-        this.operatorKey = this.userToken ? null : (options.operatorKey || process.env.ZIGGS_OPERATOR_KEY || null);
-        this.agentId = this.userToken ? null : (options.agentId || null);
-        this.label = options.label || 'agent';
-        this.socket = null;
-        this.messageHandler = null;
-        this.resourceEventHandler = null;
-    }
-    setMessageHandler(handler) {
-        this.messageHandler = handler;
-    }
-    /**
-     * 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) {
-        this.resourceEventHandler = handler;
-    }
-    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) {
-        this.connectHandlers.push(handler);
-    }
-    async _emitConnect() {
-        for (const handler of this.connectHandlers) {
-            try {
-                await handler();
-            }
-            catch (error) {
-                const msg = error instanceof Error ? error.message : String(error);
-                runtimeLog.warn(this.label, `connect handler error: ${msg}`);
-            }
-        }
-    }
-    _connect() {
-        if (this.socket?.connected)
-            return;
-        runtimeLog.debug(this.label, `Connecting to ${this.wsUrl}`);
-        const socketOptions = this.buildSocketOptions();
-        this.socket = io(this.wsUrl, socketOptions);
-        this.socket.on('connect', () => {
-            runtimeLog.info(this.label, 'Connected');
-            void this._emitConnect();
-        });
-        this.socket.on('connect_error', (error) => {
-            runtimeLog.error(this.label, `Connection error: ${error.message}`);
-        });
-        this.socket.on('disconnect', (reason) => {
-            const reasonDescriptions = {
-                'io server disconnect': 'Server forcefully disconnected the client',
-                'io client disconnect': 'Client manually disconnected',
-                'ping timeout': 'Server did not respond to ping (connection timeout)',
-                'transport close': 'Connection closed by transport layer',
-                'transport error': 'Transport error occurred',
-                'parse error': 'Error parsing server message',
-                'forced close': 'Connection was forcibly closed',
-                'forced server close': 'Server forcibly closed the connection',
-            };
-            const description = reasonDescriptions[reason] || 'Unknown disconnect reason';
-            runtimeLog.debug(this.label, `Disconnected: ${reason} — ${description}`);
-        });
-        // ZIG-207: subscribe to the canonical event name. Backend dual-emits
-        // `messages` + `chat:message:new` with byte-identical payloads, so
-        // listening to ONE of the two is exactly correct — listening to both
-        // would double-invoke handleIncomingMessage(). We pick the canonical
-        // namespaced name so once the sunset PR drops the legacy `messages`
-        // emit, no client change is needed.
-        this.socket.on('chat:message:new', async (payload) => {
-            try {
-                await this.handleIncomingMessage(payload);
-            }
-            catch (error) {
-                const msg = error instanceof Error ? error.message : String(error);
-                runtimeLog.error(this.label, `Error handling incoming message: ${msg}`);
-                throw error;
-            }
-        });
-        this.socket.on('resource_changed', async (payload) => {
-            if (!this.resourceEventHandler)
-                return;
-            try {
-                await this.resourceEventHandler(payload);
-            }
-            catch (error) {
-                const msg = error instanceof Error ? error.message : String(error);
-                runtimeLog.error(this.label, `Error handling resource_changed: ${msg}`);
-            }
-        });
-        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)
-            return Promise.resolve(this);
-        return new Promise((resolve, reject) => {
-            this._connect();
-            // Only reject on timeout — not on the first connect_error. socket.io
-            // retries automatically (reconnectionAttempts: Infinity), so a single
-            // network hiccup or a briefly-down backend shouldn't crash the caller.
-            const timer = setTimeout(() => reject(new Error(`[${this.label}] Connection timeout after ${timeout}ms`)), timeout);
-            this.socket.once('connect', () => { clearTimeout(timer); resolve(this); });
-        });
-    }
-    disconnect() {
-        if (this.socket) {
-            this.socket.disconnect();
-            this.socket = null;
-        }
-    }
-    send(chatId, receiverId, content, options = {}) {
-        if (!chatId || typeof chatId !== 'string')
-            throw new Error('send: chatId is required');
-        if (!receiverId || typeof receiverId !== 'string')
-            throw new Error('send: receiverId is required');
-        if (typeof content !== 'string' || content.trim().length === 0)
-            throw new Error('send: content must be a non-empty string');
-        if (!this.socket)
-            throw new Error('send: socket is not initialized. Call connect() first.');
-        if (!this.socket.connected)
-            throw new Error('send: socket is not connected. Call connect() and wait for connection.');
-        const messageId = options.messageId ?? this.generateMessageId();
-        if (!messageId || typeof messageId !== 'string')
-            throw new Error('send: failed to generate valid messageId');
-        const message = {
-            receiverId,
-            chatId,
-            messageId,
-            text: content,
-            entryType: options.entryType || 'message',
-            content_type: options.content_type || options.contentType || 'text',
-        };
-        const messagePreview = content.length > 100 ? content.substring(0, 100) + '...' : content;
-        // ZIG-207: emit the canonical namespaced inbound event. Backend
-        // registers `chat:message:send` as a one-line alias on `handleChat`,
-        // so this is byte-identical to the legacy `chat` emit. Streaming
-        // chunks keep their existing `chat:chunk` name (already namespaced).
-        const event = options.partial ? 'chat:chunk' : 'chat:message:send';
-        runtimeLog.debug(this.label, `Sending message (${event}) - chatId: ${chatId}, receiverId: ${receiverId}\n   Message: ${messagePreview}`);
-        this.socket.emit(event, message);
-    }
-    isConnected() {
-        return this.socket?.connected || false;
-    }
-    async handleIncomingMessage(payload) {
-        if (!payload || typeof payload !== 'object') {
-            throw new Error('handleIncomingMessage: payload must be an object');
-        }
-        const p = payload;
-        if (!p['text'] || typeof p['text'] !== 'string' || p['text'].trim().length === 0) {
-            throw new Error('handleIncomingMessage: payload.text is required and must be a non-empty string');
-        }
-        if (!p['chatId'] || typeof p['chatId'] !== 'string') {
-            throw new Error('handleIncomingMessage: payload.chatId is required and must be a string');
-        }
-        const sender = p['sender'];
-        const senderId = sender?.['id'];
-        const senderType = sender?.['type'];
-        if (!senderId || typeof senderId !== 'string') {
-            throw new Error('handleIncomingMessage: payload.sender.id is required and must be a string');
-        }
-        runtimeLog.debug(this.label, `Received message - chatId: ${p['chatId']}, sender: ${senderId} (${senderType})`);
-        if (this.agentId && senderId === this.agentId)
-            return;
-        if (!this.messageHandler) {
-            throw new Error('handleIncomingMessage: messageHandler is not set. Call setMessageHandler() first.');
-        }
-        const chatId = p['chatId'];
-        const receiver = p['receiver'];
-        const task = p['task'] ?? null;
-        const agreement = p['agreement'] ?? null;
-        const operation = p['operation'] ?? null;
-        const agreementId = p['agreementId'] ?? null;
-        runtimeLog.info(this.label, `[wire-debug] incoming chatId=${chatId} sender=${senderId} content_type=${p['content_type'] ?? p['contentType'] ?? '<none>'} entryType=${p['entryType'] ?? '<none>'} ts=${typeof p['timestamp']}/${typeof p['sentTimestamp']} keys=${Object.keys(p).join(',')} task?=${task ? `taskId=${task['taskId']} state=${task['state']}` : 'no'} agreement?=${agreement ? `agreementId=${agreement['agreementId']} status=${agreement['status']}` : 'no'} operation?=${operation ?? 'no'}`);
-        const metadata = {
-            chatId,
-            messageId: typeof p['messageId'] === 'string' ? p['messageId'] : undefined,
-            userId: senderId,
-            sender: { id: senderId, type: senderType },
-            senderId,
-            senderType,
-            receiver: receiver || null,
-            receiverId: receiver?.['id'] || null,
-            entryType: p['entryType'],
-            content_type: (p['content_type'] ?? p['contentType']),
-            taskId: task?.['taskId'] ?? null,
-            task,
-            agreement,
-            operation,
-            agreementId,
-            // ZIG-860: carry the send time through — the live-path watermark ack
-            // (AgentHost, ZIG-832 P4) reads it, and dropping it here meant the ack
-            // never fired for any live message.
-            timestamp: typeof p['timestamp'] === 'string' ? p['timestamp'] : undefined,
-            sentTimestamp: typeof p['sentTimestamp'] === 'string' ? p['sentTimestamp'] : undefined,
-        };
-        await this.messageHandler(p['text'], metadata);
-    }
-    buildSocketOptions() {
-        // `forceNew: true` is required when multiple WebSocketClient instances
-        // hit the same URL with DIFFERENT auth. socket.io's default
-        // `multiplex: true` shares the engine.io Manager across `io()` calls
-        // to the same URL — and the Manager's auth is fixed by whoever opened
-        // it first. So a second client (e.g. an eval's user-mode connection
-        // alongside agent-host operator-key connections) would silently inherit
-        // the first client's auth and get rejected. Forcing a fresh Manager
-        // per client avoids that aliasing.
-        const options = {
-            transports: ['websocket'],
-            reconnection: true,
-            reconnectionAttempts: Infinity,
-            reconnectionDelay: 1000,
-            reconnectionDelayMax: 30000,
-            randomizationFactor: 0.5,
-            timeout: 20000,
-            autoConnect: true,
-            forceNew: true,
-            multiplex: false,
-        };
-        if (this.userToken) {
-            const bearer = `Bearer ${this.userToken}`;
-            options.auth = { token: bearer };
-            options.extraHeaders = { Authorization: bearer };
-            // No agentId — the gateway sees the `userId` claim and routes as a human user.
-        }
-        else if (this.operatorKey) {
-            const bearer = `Bearer ${this.operatorKey}`;
-            options.auth = { token: bearer };
-            options.extraHeaders = { Authorization: bearer };
-            // agentId goes in query for fleet keys; agent-scoped keys omit it (ZIG-279).
-            if (this.agentId)
-                options.query = { agentId: this.agentId };
-        }
-        return options;
-    }
-    generateMessageId() {
-        return crypto.randomUUID();
-    }
-}

package/dist/websocket/index.d.ts

@@ -1 +0,0 @@
-export { WebSocketClient } from './WebSocketClient.js';

package/dist/websocket/index.js

@@ -1 +0,0 @@
-export { WebSocketClient } from './WebSocketClient.js';