@ziggs-ai/api-client 0.1.3 → 0.1.5

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

package/src/http/ContextWriter.js

@@ -1,98 +0,0 @@
-import 'dotenv/config';
-import { EntryTypes, ContentTypes } from '../types.js';
-import { getBackendUrl } from '../utils/urlUtils.js';
-
-export class ContextWriter {
-  constructor(operatorKey, agentId) {
-    if (!operatorKey) {
-      throw new Error('ContextWriter: operatorKey is required');
-    }
-    if (!agentId) {
-      throw new Error('ContextWriter: agentId is required (operator-token impersonation)');
-    }
-    this.operatorKey = operatorKey;
-    this.agentId = agentId;
-  }
-
-  _getBaseUrl() {
-    const route = process.env.HISTORY_SERVICE_ROUTE || 'context';
-    return `${getBackendUrl()}/${route}`;
-  }
-
-  async recordOperation(chatId, operation) {
-    if (!chatId) return;
-
-    const prefix = operation.state === 'completed'
-      ? 'operation_completed:'
-      : operation.state === 'failed'
-        ? 'operation_error:'
-        : 'operation_started:';
-
-    const text = prefix + JSON.stringify(operation);
-
-    try {
-      await fetch(`${this._getBaseUrl()}/ingest`, {
-        method: 'POST',
-        headers: this._buildHeaders(),
-        body: JSON.stringify({
-          chatId,
-          text,
-          entryType: EntryTypes.ARTIFACT,
-          content_type: ContentTypes.OPERATION
-        })
-      });
-    } catch (error) {
-      console.warn(`⚠️ Failed to record operation: ${error.message}`);
-    }
-  }
-
-  async recordMessage(chatId, message) {
-    if (!chatId) return;
-
-    try {
-      await fetch(`${this._getBaseUrl()}/ingest`, {
-        method: 'POST',
-        headers: this._buildHeaders(),
-        body: JSON.stringify({
-          chatId,
-          text: message.text,
-          entryType: EntryTypes.MESSAGE,
-          content_type: ContentTypes.TEXT
-        })
-      });
-    } catch (error) {
-      console.warn(`⚠️ Failed to record message: ${error.message}`);
-    }
-  }
-
-  /**
-   * Send agent thought (reasoning) as artifact so it appears in timeline and frontend.
-   * Backend stores with entryType=artifact, content_type=thought. Sender is taken from JWT.
-   */
-  async recordThought(chatId, thoughtText) {
-    if (!chatId || thoughtText == null || String(thoughtText).trim() === '') return;
-
-    try {
-      await fetch(`${this._getBaseUrl()}/ingest`, {
-        method: 'POST',
-        headers: this._buildHeaders(),
-        body: JSON.stringify({
-          chatId,
-          text: String(thoughtText).trim(),
-          entryType: EntryTypes.ARTIFACT,
-          content_type: ContentTypes.THOUGHT
-        })
-      });
-    } catch (error) {
-      console.warn(`⚠️ Failed to record thought artifact: ${error.message}`);
-    }
-  }
-
-  _buildHeaders() {
-    return {
-      'content-type': 'application/json',
-      'Authorization': `Bearer ${this.operatorKey}`,
-      'X-Agent-Id': this.agentId,
-    };
-  }
-}