@ziggs-ai/api-client 0.1.29 → 0.2.0

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