@ziggs-ai/api-client 0.1.4 → 0.1.5

package/dist/websocket/WebSocketClient.js

@@ -59,7 +59,13 @@ export class WebSocketClient {
             const description = reasonDescriptions[reason] || 'Unknown disconnect reason';
             runtimeLog.debug(this.label, `Disconnected: ${reason} — ${description}`);
         });
-        this.socket.on('messages', async (payload) => {
+        // 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);
             }
@@ -89,9 +95,11 @@ export class WebSocketClient {
             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); });
-            this.socket.once('connect_error', (err) => { clearTimeout(timer); reject(err); });
         });
     }
     disconnect() {
@@ -123,7 +131,11 @@ export class WebSocketClient {
             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';
+        // 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);
     }
@@ -157,7 +169,9 @@ export class WebSocketClient {
         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 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>'} task?=${task ? `taskId=${task['taskId']} state=${task['state']}` : 'no'} agreement?=${agreement ? `agreementId=${agreement['agreementId']} status=${agreement['status']}` : 'no'} operation?=${operation ?? 'no'}`);
         const metadata = {
             chatId,
             userId: senderId,
@@ -171,6 +185,8 @@ export class WebSocketClient {
             taskId: task?.['taskId'] ?? null,
             task,
             agreement,
+            operation,
+            agreementId,
         };
         await this.messageHandler(p['text'], metadata);
     }
@@ -188,7 +204,8 @@ export class WebSocketClient {
             reconnection: true,
             reconnectionAttempts: Infinity,
             reconnectionDelay: 1000,
-            reconnectionDelayMax: 5000,
+            reconnectionDelayMax: 30000,
+            randomizationFactor: 0.5,
             timeout: 20000,
             autoConnect: true,
             forceNew: true,
@@ -204,8 +221,7 @@ export class WebSocketClient {
             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.
+            // agentId goes in query for fleet keys; agent-scoped keys omit it (ZIG-279).
             if (this.agentId)
                 options.query = { agentId: this.agentId };
         }

package/package.json

@@ -1,21 +1,20 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "src/index.ts",
   "exports": {
-    ".": "./dist/index.js",
-    "./http": "./dist/http/index.js",
-    "./websocket": "./dist/websocket/index.js"
+    ".": "./src/index.ts",
+    "./http": "./src/http/index.ts",
+    "./websocket": "./src/websocket/index.ts"
   },
   "engines": {
     "node": ">=18"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepare": "npm run build",
+    "prepack": "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"
   },
@@ -25,9 +24,16 @@
   },
   "keywords": ["ziggs", "api", "client", "websocket"],
   "license": "MIT",
-  "files": ["dist", "README.md"],
+  "files": ["dist", "src", "README.md"],
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org/",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+      ".": "./dist/index.js",
+      "./http": "./dist/http/index.js",
+      "./websocket": "./dist/websocket/index.js"
+    }
   }
 }

package/src/ConnectionManager.ts

@@ -0,0 +1,172 @@
+import { createControlSocket, type ControlSocketOptions, type ControlSocketHandle } from './websocket/ControlSocket.js';
+import { runtimeLog } from './shared/runtimeLog.js';
+
+type OpenFn = () => Promise<unknown>;
+type CloseFn = (handle: unknown) => Promise<void>;
+
+interface Entry {
+  openFn: OpenFn;
+  closeFn: CloseFn;
+}
+
+interface ActiveEntry {
+  handle: unknown;
+  timer: ReturnType<typeof setTimeout> | null;
+  lastActive: number;
+}
+
+export interface ConnectionManagerMeta {
+  domain?: string;
+  expertise?: string[];
+  tags?: string[];
+  [key: string]: unknown;
+}
+
+export interface ConnectionManagerOptions {
+  maxActive?: number;
+  idleTimeoutMs?: number;
+  control?: Pick<ControlSocketOptions, 'wsUrl' | 'operatorKey'>;
+}
+
+export interface QueryFilter {
+  domain?: string;
+  expertise?: string[];
+  tags?: string[];
+}
+
+export class ConnectionManager {
+  private maxActive: number;
+  private idleTimeoutMs: number;
+  private _controlOpts: Pick<ControlSocketOptions, 'wsUrl' | 'operatorKey'> | null;
+  private _controlHandle: ControlSocketHandle | null;
+  private _entries: Map<string, Entry>;
+  private _active: Map<string, ActiveEntry>;
+  private _meta: Map<string, ConnectionManagerMeta>;
+  private _waking: Map<string, Promise<unknown>>;
+
+  constructor({ maxActive = 50, idleTimeoutMs = 60_000, control }: ConnectionManagerOptions = {}) {
+    this.maxActive = maxActive;
+    this.idleTimeoutMs = idleTimeoutMs;
+    this._controlOpts = control ?? null;
+    this._controlHandle = null;
+    this._entries = new Map();
+    this._active = new Map();
+    this._meta = new Map();
+    this._waking = new Map();
+  }
+
+  register(id: string, openFn: OpenFn, closeFn: CloseFn, meta?: ConnectionManagerMeta): void {
+    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);
+  }
+
+  start(): void {
+    if (this._controlHandle || !this._controlOpts) return;
+    this._controlHandle = createControlSocket({
+      ...this._controlOpts,
+      agentIds: () => this.list(),
+      onWake: (id) =>
+        this.wake(id).catch(err =>
+          runtimeLog.warn('ConnectionManager', `wake("${id}") failed: ${(err as Error).message}`),
+        ),
+    });
+  }
+
+  async stop(): Promise<void> {
+    this._controlHandle?.close();
+    this._controlHandle = null;
+    await this.sleepAll();
+  }
+
+  async wake(id: string): Promise<unknown> {
+    const existing = this._active.get(id);
+    if (existing) {
+      this._resetTimer(id);
+      return existing.handle;
+    }
+
+    const pending = this._waking.get(id);
+    if (pending) return pending;
+
+    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 wakePromise = (async () => {
+      try {
+        const handle = await entry.openFn();
+        this._active.set(id, { handle, timer: null, lastActive: Date.now() });
+        this._scheduleIdle(id);
+        return handle;
+      } finally {
+        this._waking.delete(id);
+      }
+    })();
+
+    this._waking.set(id, wakePromise);
+    return wakePromise;
+  }
+
+  async sleep(id: string): Promise<void> {
+    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(): Promise<void> {
+    await Promise.all([...this._active.keys()].map(id => this.sleep(id)));
+  }
+
+  touch(id: string): void { this._resetTimer(id); }
+
+  list(): string[] { return [...this._entries.keys()]; }
+  listActive(): string[] { return [...this._active.keys()]; }
+  get size(): number { return this._entries.size; }
+
+  query({ domain, expertise, tags }: QueryFilter = {}): string[] {
+    const results: string[] = [];
+    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;
+  }
+
+  getMeta(id: string): ConnectionManagerMeta | undefined { return this._meta.get(id); }
+
+  private _scheduleIdle(id: string): void {
+    const entry = this._active.get(id);
+    if (!entry) return;
+    clearTimeout(entry.timer!);
+    entry.timer = setTimeout(() => {
+      this.sleep(id).catch(err =>
+        runtimeLog.warn('ConnectionManager', `idle sleep("${id}") failed: ${(err as Error).message}`),
+      );
+    }, this.idleTimeoutMs);
+  }
+
+  private _resetTimer(id: string): void {
+    const entry = this._active.get(id);
+    if (!entry) return;
+    entry.lastActive = Date.now();
+    this._scheduleIdle(id);
+  }
+
+  private async _evictLRU(): Promise<void> {
+    let oldest: string | null = null;
+    for (const [id, entry] of this._active) {
+      const oldestEntry = oldest ? this._active.get(oldest) : null;
+      if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive) oldest = id;
+    }
+    if (oldest) await this.sleep(oldest);
+  }
+}

package/src/http/AgentSearchClient.ts

@@ -0,0 +1,115 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+
+export interface AgentSearchOptions {
+  limit?: number;
+  minScore?: number;
+}
+
+export interface AgentSearchResult {
+  success: boolean;
+  agents?: AgentProfile[];
+  error?: string;
+  message?: string;
+}
+
+export interface AgentProfile {
+  agentId: string;
+  name: string;
+  description?: string;
+  tags?: string[];
+  matchScore?: number;
+  reliability?: {
+    sampleSize: number;
+    band: string;
+    medianResponseMs: number;
+    lastActivityDaysAgo: number;
+  };
+  category?: string;
+  version?: string;
+  recentTaskSamples?: unknown[];
+}
+
+export class AgentSearchClient {
+  private readonly operatorKey: string;
+  private readonly agentId: string;
+  private readonly baseUrl: string;
+
+  constructor(operatorKey: string, agentId: string) {
+    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();
+  }
+
+  async searchAgents(query: string, options: AgentSearchOptions = {}): Promise<AgentSearchResult> {
+    if (!query || typeof query !== 'string') {
+      return { success: false, error: 'query is required' };
+    }
+    const params = new URLSearchParams({ q: query });
+    if (typeof options.limit === 'number') params.set('limit', String(options.limit));
+    if (typeof options.minScore === 'number') params.set('minScore', String(options.minScore));
+
+    const url = `${this.baseUrl}/agent-api/v1/agents/search?${params}`;
+    try {
+      const response = await fetch(url, { method: 'GET', headers: this._buildHeaders() });
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => '');
+        runtimeLog.warn(
+          'AgentSearchClient',
+          `⚠️ searchAgents failed agent=${this.agentId} ${response.status} ${response.statusText} url=${url} body=${errorText.slice(0, 200)}`,
+        );
+        return { success: false, error: `Search failed: ${response.status}`, message: errorText };
+      }
+      const { results = [] } = await response.json() as { results: AgentProfile[] };
+      return { success: true, agents: results };
+    } catch (error) {
+      runtimeLog.warn(
+        'AgentSearchClient',
+        `⚠️ searchAgents error agent=${this.agentId} url=${url} message=${(error as Error).message}`,
+      );
+      return { success: false, error: (error as Error).message || 'Failed to search agents' };
+    }
+  }
+
+  async getAgentById(agentId: string): Promise<AgentSearchResult & Partial<AgentProfile>> {
+    if (!agentId) return { success: false, error: 'agentId is required' };
+    const url = `${this.baseUrl}/agent-api/v1/agents/${encodeURIComponent(agentId)}`;
+    try {
+      const response = await fetch(url, { method: 'GET', headers: this._buildHeaders() });
+      if (response.status === 404) {
+        runtimeLog.warn(
+          'AgentSearchClient',
+          `⚠️ getAgentById 404 agent=${this.agentId} target=${agentId} url=${url}`,
+        );
+        return { success: false, error: 'agent not found' };
+      }
+      if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        runtimeLog.warn(
+          'AgentSearchClient',
+          `⚠️ getAgentById failed agent=${this.agentId} target=${agentId} ${response.status} ${response.statusText} body=${body.slice(0, 200)}`,
+        );
+        return { success: false, error: `Failed to get agent details: ${response.status}` };
+      }
+      const agent = await response.json() as AgentProfile;
+      return { success: true, ...agent };
+    } catch (error) {
+      runtimeLog.warn(
+        'AgentSearchClient',
+        `⚠️ getAgentById error agent=${this.agentId} target=${agentId} url=${url} message=${(error as Error).message}`,
+      );
+      return { success: false, error: (error as Error).message || 'Failed to get agent details' };
+    }
+  }
+
+  private _buildHeaders(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${this.operatorKey}`,
+      'X-Agent-Id': this.agentId,
+    };
+  }
+}