@ziggs-ai/api-client 0.1.3 → 0.1.4

package/dist/websocket/WebSocketClient.js

@@ -0,0 +1,217 @@
+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;
+    }
+    _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');
+        });
+        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}`);
+        });
+        this.socket.on('messages', 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)}`);
+        });
+    }
+    connectAsync(timeout = 10_000) {
+        if (this.socket?.connected)
+            return Promise.resolve(this);
+        return new Promise((resolve, reject) => {
+            this._connect();
+            const timer = setTimeout(() => reject(new Error(`[${this.label}] Connection timeout after ${timeout}ms`)), timeout);
+            this.socket.once('connect', () => { clearTimeout(timer); resolve(this); });
+            this.socket.once('connect_error', (err) => { clearTimeout(timer); reject(err); });
+        });
+    }
+    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 = 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;
+        const event = options.partial ? 'chat:chunk' : 'chat';
+        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;
+        runtimeLog.info(this.label, `[wire-debug] incoming chatId=${chatId} sender=${senderId} content_type=${p['content_type'] ?? p['contentType'] ?? '<none>'} entryType=${p['entryType'] ?? '<none>'} task?=${task ? `taskId=${task['taskId']} state=${task['state']}` : 'no'} agreement?=${agreement ? `agreementId=${agreement['agreementId']} status=${agreement['status']}` : 'no'}`);
+        const metadata = {
+            chatId,
+            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,
+        };
+        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: 5000,
+            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 so the gateway can route; token stays out of the URL
+            // to avoid leaking the long-lived operator key into proxy access logs.
+            if (this.agentId)
+                options.query = { agentId: this.agentId };
+        }
+        return options;
+    }
+    generateMessageId() {
+        return crypto.randomUUID();
+    }
+}

package/dist/websocket/index.js

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

package/package.json

@@ -1,24 +1,31 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
-  "main": "src/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./http": "./src/http/index.js",
-    "./websocket": "./src/websocket/index.js"
+    ".": "./dist/index.js",
+    "./http": "./dist/http/index.js",
+    "./websocket": "./dist/websocket/index.js"
   },
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "node --import tsx/esm --test --test-reporter=spec test/*.test.ts",
+    "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
+  },
   "dependencies": {
     "dotenv": "^17.2.3",
     "socket.io-client": "^4.7.0"
   },
   "keywords": ["ziggs", "api", "client", "websocket"],
   "license": "MIT",
-  "files": ["src", "README.md"],
+  "files": ["dist", "README.md"],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/ConnectionManager.js

@@ -1,179 +0,0 @@
-/**
- * ConnectionManager — generic, agent-agnostic pool.
- *
- * Holds an in-memory map of registered entities keyed by id. Each entity is
- * described by a pair of functions: `openFn()` returns a live "connection"
- * handle, `closeFn(handle)` tears it down. The manager enforces a `maxActive`
- * cap with LRU eviction and automatically releases idle entries after
- * `idleTimeoutMs`.
- *
- * Optionally opens a control socket (`createControlSocket`) so the backend
- * can push `wake` events for entries that aren't currently active — the
- * manager handles receipt and calls `wake(id)` on your behalf.
- *
- * This lives in api-client because it has no dependency on ZiggsAgent (or any
- * other SDK concept). Anyone writing their own agent runtime — or another
- * language binding — can use ConnectionManager directly, or just use
- * `createControlSocket` alone if they already manage their own lifecycle.
- *
- * Usage:
- *   const mgr = new ConnectionManager({
- *     maxActive: 50,
- *     idleTimeoutMs: 60_000,
- *     control: { wsUrl, operatorKey },   // optional
- *   });
- *   mgr.register(
- *     'agent-42',
- *     async () => openMySocketFor('agent-42'),
- *     async (handle) => handle.close(),
- *     { domain: 'science' }          // optional metadata for query()
- *   );
- *   mgr.start();                     // opens the control socket (if configured)
- *   const handle = await mgr.wake('agent-42');
- *   await mgr.stop();
- */
-
-import { createControlSocket } from './websocket/ControlSocket.js';
-
-export class ConnectionManager {
-  /**
-   * @param {object} opts
-   * @param {number} [opts.maxActive=50]        Max simultaneous open handles
-   * @param {number} [opts.idleTimeoutMs=60000] Ms before an idle handle is auto-closed
-   * @param {{ wsUrl: string, operatorKey: string }} [opts.control] Enables control socket wake-on-demand.
-   */
-  constructor({ maxActive = 50, idleTimeoutMs = 60_000, control } = {}) {
-    this.maxActive = maxActive;
-    this.idleTimeoutMs = idleTimeoutMs;
-    this._controlOpts = control ?? null;
-    this._controlHandle = null;
-
-    // id → { openFn, closeFn }
-    this._entries = new Map();
-    // id → { handle, timer, lastActive }
-    this._active = new Map();
-    // id → user-supplied metadata (for query())
-    this._meta = new Map();
-  }
-
-  // ---- registration ----
-
-  register(id, openFn, closeFn, meta) {
-    if (!id) throw new Error('[ConnectionManager] id is required');
-    if (typeof openFn !== 'function') throw new Error('[ConnectionManager] openFn must be a function');
-    if (typeof closeFn !== 'function') throw new Error('[ConnectionManager] closeFn must be a function');
-    this._entries.set(id, { openFn, closeFn });
-    if (meta) this._meta.set(id, meta);
-  }
-
-  // ---- lifecycle ----
-
-  /** Open the control socket (if configured). Safe to call multiple times. */
-  start() {
-    if (this._controlHandle || !this._controlOpts) return;
-    this._controlHandle = createControlSocket({
-      ...this._controlOpts,
-      agentIds: () => this.list(),
-      onWake:   (id) => this.wake(id).catch(err => console.warn(`[ConnectionManager] wake("${id}") failed: ${err.message}`)),
-    });
-  }
-
-  /** Close the control socket and all active handles. */
-  async stop() {
-    this._controlHandle?.close();
-    this._controlHandle = null;
-    await this.sleepAll();
-  }
-
-  // ---- connection lifecycle ----
-
-  /**
-   * Ensure an entry is active. Returns the live handle from `openFn()`.
-   * If `maxActive` is hit, evicts the LRU entry first.
-   */
-  async wake(id) {
-    const existing = this._active.get(id);
-    if (existing) {
-      this._resetTimer(id);
-      return existing.handle;
-    }
-    const entry = this._entries.get(id);
-    if (!entry) throw new Error(`[ConnectionManager] unknown id: "${id}"`);
-
-    if (this._active.size >= this.maxActive) await this._evictLRU();
-
-    const handle = await entry.openFn();
-    this._active.set(id, { handle, timer: null, lastActive: Date.now() });
-    this._scheduleIdle(id);
-    return handle;
-  }
-
-  /** Close a single active entry. */
-  async sleep(id) {
-    const entry = this._active.get(id);
-    if (!entry) return;
-    clearTimeout(entry.timer);
-    this._active.delete(id);
-    const reg = this._entries.get(id);
-    if (reg) await reg.closeFn(entry.handle);
-  }
-
-  async sleepAll() {
-    await Promise.all([...this._active.keys()].map(id => this.sleep(id)));
-  }
-
-  /** Call after `wake` if you performed work and want to extend the idle timer. */
-  touch(id) { this._resetTimer(id); }
-
-  // ---- introspection ----
-
-  /** All registered ids. */
-  list() { return [...this._entries.keys()]; }
-  /** Currently active ids. */
-  listActive() { return [...this._active.keys()]; }
-  get size() { return this._entries.size; }
-
-  /**
-   * Filter ids by metadata. `filter.domain` is exact match; `filter.expertise`
-   * and `filter.tags` are "at least one must match". No filter → all ids.
-   */
-  query({ domain, expertise, tags } = {}) {
-    const results = [];
-    for (const [id, meta] of this._meta) {
-      if (domain && meta.domain !== domain) continue;
-      if (expertise?.length && !expertise.some(e => meta.expertise?.includes(e))) continue;
-      if (tags?.length && !tags.some(t => meta.tags?.includes(t))) continue;
-      results.push(id);
-    }
-    return results;
-  }
-
-  /** Read metadata for a single id (undefined if not registered / no meta). */
-  getMeta(id) { return this._meta.get(id); }
-
-  // ---- internals ----
-
-  _scheduleIdle(id) {
-    const entry = this._active.get(id);
-    if (!entry) return;
-    clearTimeout(entry.timer);
-    entry.timer = setTimeout(() => {
-      this.sleep(id).catch(err => console.warn(`[ConnectionManager] idle sleep("${id}") failed: ${err.message}`));
-    }, this.idleTimeoutMs);
-  }
-
-  _resetTimer(id) {
-    const entry = this._active.get(id);
-    if (!entry) return;
-    entry.lastActive = Date.now();
-    this._scheduleIdle(id);
-  }
-
-  async _evictLRU() {
-    let oldest = null;
-    for (const [id, entry] of this._active) {
-      if (!oldest || entry.lastActive < this._active.get(oldest).lastActive) oldest = id;
-    }
-    if (oldest) await this.sleep(oldest);
-  }
-}

package/src/http/AgentSearchClient.js

@@ -1,113 +0,0 @@
-import 'dotenv/config';
-import { getBackendUrl } from '../utils/urlUtils.js';
-
-/**
- * Client for searching and retrieving agent information from the Ziggs API
- */
-export class AgentSearchClient {
-  constructor(operatorKey, agentId) {
-    if (!operatorKey) {
-      throw new Error('AgentSearchClient: operatorKey is required');
-    }
-    if (!agentId) {
-      throw new Error('AgentSearchClient: agentId is required (operator-token impersonation)');
-    }
-    this.operatorKey = operatorKey;
-    this.agentId = agentId;
-    this.baseUrl = getBackendUrl();
-  }
-
-  /**
-   * Search for agents based on a text query
-   * @param {string} query - Search query text
-   * @param {Object} options - Additional options
-   * @param {boolean} options.fullResponse - Whether to return full response data
-   * @returns {Promise<Object>} Search results
-   */
-  async searchAgents(query, options = {}) {
-    const { fullResponse = true } = options;
-
-    try {
-      const response = await fetch(`${this.baseUrl}/agents/searchAgents`, {
-        method: 'POST',
-        headers: this._buildHeaders(),
-        body: JSON.stringify({
-          query,
-          fullResponse
-        })
-      });
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        return {
-          success: false,
-          error: `Search failed: ${response.status}`,
-          message: errorText
-        };
-      }
-
-      const data = await response.json();
-      return data;
-
-    } catch (error) {
-      return {
-        success: false,
-        error: error.message || 'Failed to search agents'
-      };
-    }
-  }
-
-  /**
-   * Get detailed information about a specific agent
-   * @param {string} agentId - The unique identifier of the agent
-   * @returns {Promise<Object>} Agent details
-   */
-  async getAgentById(agentId) {
-    if (!agentId) {
-      return {
-        success: false,
-        error: 'agentId is required'
-      };
-    }
-
-    try {
-      const response = await fetch(`${this.baseUrl}/agents/getAgentById`, {
-        method: 'POST',
-        headers: this._buildHeaders(),
-        body: JSON.stringify({ agentId })
-      });
-
-      if (!response.ok) {
-        return {
-          success: false,
-          error: `Failed to get agent details: ${response.status}`
-        };
-      }
-
-      const agent = await response.json();
-      
-      return {
-        success: true,
-        agentId: agent.agentId,
-        name: agent.name,
-        description: agent.storePage?.description || 'No description available',
-        storePage: agent.storePage,
-        type: agent.type || 'agent'
-      };
-
-    } catch (error) {
-      return {
-        success: false,
-        error: error.message || 'Failed to get agent details'
-      };
-    }
-  }
-
-  _buildHeaders() {
-    return {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${this.operatorKey}`,
-      'X-Agent-Id': this.agentId,
-    };
-  }
-}

package/src/http/ContextReader.js

@@ -1,99 +0,0 @@
-import 'dotenv/config';
-import { getBackendUrl } from '../utils/urlUtils.js';
-
-export class ContextReader {
-  constructor(operatorKey, agentId) {
-    if (!operatorKey) {
-      throw new Error('ContextReader: operatorKey is required');
-    }
-    if (!agentId) {
-      throw new Error('ContextReader: agentId is required (operator-token impersonation)');
-    }
-    this.operatorKey = operatorKey;
-    this.agentId = agentId;
-  }
-
-  _getBaseUrl() {
-    const route = process.env.HISTORY_SERVICE_ROUTE || 'context';
-    return `${getBackendUrl()}/${route}`;
-  }
-
-  /**
-   * @param {string} chatId - Chat ID
-   * @param {Object} [options] - Optional limits (passed as query params to Shared Context Service API)
-   * @param {number} [options.maxMessages] - Max number of history entries (default: server default)
-   * @param {number} [options.maxCharacters] - Max total character count of history text (default: server default)
-   * @param {number} [options.maxTaskHistory] - Max number of task_history entries (default: server default)
-   * @param {boolean} [options.summarize] - Default true. Set false to skip timelineSummary generation.
-   */
-  async read(chatId, options = {}) {
-    if (!chatId) {
-      return this._emptyContext();
-    }
-
-    try {
-      const url = new URL(`${this._getBaseUrl()}/read`);
-      url.searchParams.set('chatId', chatId);
-      if (options.maxMessages != null) url.searchParams.set('maxMessages', String(options.maxMessages));
-      if (options.maxCharacters != null) url.searchParams.set('maxCharacters', String(options.maxCharacters));
-      if (options.maxTaskHistory != null) url.searchParams.set('maxTaskHistory', String(options.maxTaskHistory));
-      // Default summarize on; callers can disable with summarize: false
-      if (options.summarize !== false) url.searchParams.set('summarize', 'true');
-
-      const res = await fetch(url.toString(), {
-        method: 'GET',
-        headers: this._buildHeaders()
-      });
-
-      if (!res.ok) {
-        console.warn(`⚠️ Context read failed: ${res.status}`);
-        return this._emptyContext();
-      }
-
-      const data = await res.json();
-      return this._extractContext(data);
-
-    } catch (error) {
-      console.warn(`⚠️ Context read error: ${error.message}`);
-      return this._emptyContext();
-    }
-  }
-
-  _extractContext(data) {
-    const history = Array.isArray(data?.history) ? data.history : [];
-    const users = Array.isArray(data?.users) ? data.users : [];
-    const activeTasks = Array.isArray(data?.openTasks) ? data.openTasks : [];
-    const agents = Array.isArray(data?.agents) ? data.agents : [];
-    const perspectiveId = data?.perspectiveId || null;
-    const timelineSummary = data?.timelineSummary ?? null;
-
-    return {
-      history,
-      users,
-      activeTasks,
-      agents,
-      perspectiveId,
-      ...(timelineSummary != null && { timelineSummary }),
-    };
-  }
-
-  _emptyContext() {
-    return {
-      history: [],
-      users: [],
-      activeTasks: [],
-      agents: [],
-      perspectiveId: null,
-      latestSequence: null,
-      timelineSummary: null
-    };
-  }
-
-  _buildHeaders() {
-    return {
-      'content-type': 'application/json',
-      'Authorization': `Bearer ${this.operatorKey}`,
-      'X-Agent-Id': this.agentId,
-    };
-  }
-}