onbuzz 4.8.3 → 4.9.0

package/src/services/composioService.js

@@ -0,0 +1,378 @@
+/**
+ * composioService — shared client + operations for the Composio
+ * integration hub. Used by:
+ *
+ *   - composioTool (agent-facing) — invokes execute/connect/etc.
+ *   - REST endpoints (UI-facing)  — power the Connections page
+ *   - CLI subcommands (operator)  — `loxia composio <verb>`
+ *
+ * Single source of truth for:
+ *   - SDK loading (dynamic + optional)
+ *   - API-key resolution (COMPOSIO_API_KEY env var)
+ *   - userId convention (agentId for agent calls; "operator" for UI/CLI)
+ *
+ * Every method returns a structured `{ success, ...data }` object so
+ * callers can render rich errors instead of relying on thrown exceptions.
+ * The SDK and API key are checked once and cached; transient SDK errors
+ * are surfaced per-call.
+ *
+ * userId conventions:
+ *   - composioTool maps agentId → userId so each agent has isolated
+ *     OAuth tokens.
+ *   - UI/CLI use the literal string "operator" so the human user's
+ *     connections are shared across agents the operator manages.
+ *     (Override via `?userId=…` on the REST routes, or `--user=…`
+ *     on the CLI, if multi-tenant ever lands.)
+ */
+
+import { getApiKeyManager } from './apiKeyManager.js';
+
+let _client = null;
+let _unavailableReason = null;
+let _activeKeyFingerprint = null; // First 8 chars of the key the cached client was built with.
+
+/**
+ * Reset cached client + unavailability — for tests, and for live
+ * key-rotation (the API-key endpoint calls this so the next op picks
+ * up the new key without a process restart).
+ */
+export function _resetForTests() {
+  _client = null;
+  _unavailableReason = null;
+  _activeKeyFingerprint = null;
+}
+
+/**
+ * Cache-invalidation hook for live key rotation. Production callers
+ * (the POST /api/composio/apikey route) call this after persisting a
+ * new key so the next service op rebuilds the SDK client with it.
+ *
+ * Different name than `_resetForTests` so it's obvious in production
+ * code that this is intentional, not a test shortcut.
+ */
+export function invalidateClientCache() {
+  _client = null;
+  _unavailableReason = null;
+  _activeKeyFingerprint = null;
+}
+
+/**
+ * Resolve the Composio API key from the highest-priority source:
+ *   1. ApiKeyManager (user-stored via the UI — encrypted on disk)
+ *   2. process.env.COMPOSIO_API_KEY (legacy / operator override)
+ *
+ * Returns { key, source: 'vault' | 'env' | null }.
+ */
+function resolveApiKey() {
+  const mgr = getApiKeyManager();
+  const vaultKey = mgr?.keys?.vendorKeys?.composio;
+  if (vaultKey && typeof vaultKey === 'string' && vaultKey.trim()) {
+    return { key: vaultKey.trim(), source: 'vault' };
+  }
+  const envKey = process.env.COMPOSIO_API_KEY;
+  if (envKey && typeof envKey === 'string' && envKey.trim()) {
+    return { key: envKey.trim(), source: 'env' };
+  }
+  return { key: null, source: null };
+}
+
+/**
+ * Load the SDK on first use. Returns { client } on success or { error }
+ * (string) when either the SDK is missing or the API key is unset.
+ */
+async function getClient() {
+  const { key: apiKey, source } = resolveApiKey();
+  const fingerprint = apiKey ? apiKey.slice(0, 8) : null;
+
+  // If the active key has changed since we last built the client (e.g.
+  // user just saved a new one via the UI), force a rebuild.
+  if (_client && fingerprint !== _activeKeyFingerprint) {
+    _client = null;
+    _unavailableReason = null;
+  }
+
+  if (_client) return { client: _client };
+  if (_unavailableReason) return { error: _unavailableReason };
+
+  if (!apiKey) {
+    const reason = 'No Composio API key configured. Add one on the Integrations page or set COMPOSIO_API_KEY in the environment.';
+    _unavailableReason = reason;
+    return { error: reason };
+  }
+
+  let Composio;
+  try {
+    const mod = await import('@composio/core');
+    Composio = mod.Composio || mod.default?.Composio || mod.default;
+  } catch (e) {
+    const reason = `@composio/core SDK is not installed. Run \`npm install @composio/core\`. Detail: ${e.message}`;
+    _unavailableReason = reason;
+    return { error: reason };
+  }
+
+  try {
+    _client = new Composio({ apiKey });
+    _activeKeyFingerprint = fingerprint;
+    return { client: _client };
+  } catch (e) {
+    const reason = `Composio SDK initialization failed: ${e.message}`;
+    _unavailableReason = reason;
+    return { error: reason };
+  }
+}
+
+/**
+ * Optionally inject a stub client. ONLY for tests.
+ *
+ * Also pins the fingerprint to whatever the current resolved key
+ * happens to be, so the live-rotation check inside `getClient()`
+ * doesn't immediately discard the stub.
+ *
+ * @param {object} stub
+ */
+export function _injectClientForTests(stub) {
+  _client = stub;
+  _unavailableReason = null;
+  const { key } = resolveApiKey();
+  _activeKeyFingerprint = key ? key.slice(0, 8) : '__test__';
+}
+
+/* ------------------------------------------------------------------------ */
+/* Operations                                                                */
+/* ------------------------------------------------------------------------ */
+
+/**
+ * Lightweight readiness check. Avoids running a real SDK call.
+ *
+ * Returns `keySource` so the UI can tell whether the active key came
+ * from the encrypted vault (user set it via the form) or from the env
+ * var (operator-managed). That changes the affordances on the
+ * Integrations page (e.g. don't show "Forget" for env-var keys).
+ *
+ * @returns {Promise<{available: boolean, reason?: string, keySource?: 'vault'|'env'|null}>}
+ */
+export async function isAvailable() {
+  const { source } = resolveApiKey();
+  const { client, error } = await getClient();
+  if (error) return { available: false, reason: error, keySource: source };
+  return { available: !!client, keySource: source };
+}
+
+/**
+ * Persist a Composio API key via ApiKeyManager (encrypted at rest)
+ * and invalidate the SDK client cache so the next op uses it.
+ *
+ * Validation: an empty string clears the key. Otherwise we trim
+ * whitespace and require >= 8 chars (placeholder guard — the real
+ * key shape is `comp_…` and is much longer).
+ *
+ * Does NOT verify the key against Composio's API here — the UI calls
+ * isAvailable() right after to do a real probe and surface the result.
+ *
+ * @param {string|null} apiKey   The key to persist, or empty/null to clear.
+ * @returns {Promise<{success: true, cleared?: boolean} | {success: false, error: string}>}
+ */
+export async function setApiKey(apiKey) {
+  const mgr = getApiKeyManager();
+  if (!mgr) {
+    return { success: false, error: 'ApiKeyManager is not initialized; key cannot be persisted.' };
+  }
+  const trimmed = (apiKey || '').trim();
+
+  // Empty → clear the stored key.
+  if (!trimmed) {
+    const existing = { ...(mgr.keys?.vendorKeys || {}) };
+    delete existing.composio;
+    mgr.keys.vendorKeys = existing;
+    await mgr.persist();
+    invalidateClientCache();
+    return { success: true, cleared: true };
+  }
+
+  // Cheap shape guard. The full validation is "does it actually authenticate"
+  // which the caller probes with isAvailable() after.
+  if (trimmed.length < 8) {
+    return { success: false, error: 'API key looks too short. Paste the full key from dashboard.composio.dev.' };
+  }
+
+  await mgr.setSessionKeys(null, { vendorKeys: { composio: trimmed } });
+  invalidateClientCache();
+  return { success: true };
+}
+
+/**
+ * Convenience: clear the stored key. Equivalent to setApiKey('').
+ * Exposed separately so the DELETE route reads naturally.
+ */
+export async function forgetApiKey() {
+  return setApiKey('');
+}
+
+/**
+ * @returns {Promise<{success, toolkits?: Array, error?: string}>}
+ */
+export async function listToolkits() {
+  const { client, error } = await getClient();
+  if (error) return { success: false, error };
+  try {
+    const toolkits = (await client.toolkits?.list?.()) || [];
+    return { success: true, toolkits };
+  } catch (err) {
+    return { success: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * @param {string} userId
+ * @returns {Promise<{success, connections?: Array, error?: string}>}
+ */
+export async function listConnections(userId) {
+  const { client, error } = await getClient();
+  if (error) return { success: false, error };
+  try {
+    // SDK exposes connectedAccounts.list({ userId }) → array
+    const result = await client.connectedAccounts?.list?.({ userId });
+    const connections = Array.isArray(result) ? result : (result?.items || []);
+    return { success: true, connections };
+  } catch (err) {
+    return { success: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * @param {string} userId
+ * @param {string} toolkitSlug
+ * @returns {Promise<{success, connected: boolean, status: string, connectionId?: string, error?: string}>}
+ */
+export async function connectionStatus(userId, toolkitSlug) {
+  const { client, error } = await getClient();
+  if (error) return { success: false, connected: false, status: 'UNAVAILABLE', error };
+  try {
+    const conn = await client.connectedAccounts?.get?.({ userId, toolkit: toolkitSlug });
+    const connected = !!(conn && (conn.status === 'ACTIVE' || conn.connected === true));
+    return {
+      success: true,
+      connected,
+      status: conn?.status || 'NOT_CONNECTED',
+      connectionId: conn?.id || null,
+    };
+  } catch (err) {
+    return { success: false, connected: false, status: 'ERROR', error: err.message || String(err) };
+  }
+}
+
+/**
+ * @param {string} userId
+ * @param {string} toolkitSlug
+ * @param {object} [options]   { authConfigId?: string }
+ * @returns {Promise<{success, connectLink?: string, connectionId?: string, raw?: any, error?: string}>}
+ */
+export async function connect(userId, toolkitSlug, options = {}) {
+  const { client, error } = await getClient();
+  if (error) return { success: false, error };
+  try {
+    const result = await client.connectedAccounts?.initiate?.({
+      userId,
+      toolkit: toolkitSlug,
+      ...(options.authConfigId ? { authConfigId: options.authConfigId } : {}),
+    });
+    return {
+      success: true,
+      connectLink: result?.redirectUrl || result?.connectLink || null,
+      connectionId: result?.id || result?.connectionId || null,
+      raw: result,
+    };
+  } catch (err) {
+    return { success: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * Disconnect a connection. Accepts either a connectionId (preferred) or
+ * a {userId, toolkitSlug} pair (looks up the connection first).
+ *
+ * @param {{connectionId?: string, userId?: string, toolkitSlug?: string}} target
+ * @returns {Promise<{success, error?: string}>}
+ */
+export async function disconnect(target) {
+  const { client, error } = await getClient();
+  if (error) return { success: false, error };
+  if (!target || (!target.connectionId && !(target.userId && target.toolkitSlug))) {
+    return { success: false, error: 'disconnect requires connectionId OR {userId, toolkitSlug}' };
+  }
+  let connectionId = target.connectionId;
+  try {
+    if (!connectionId) {
+      const conn = await client.connectedAccounts?.get?.({ userId: target.userId, toolkit: target.toolkitSlug });
+      connectionId = conn?.id || null;
+      if (!connectionId) {
+        return { success: false, error: `No active connection found for toolkit "${target.toolkitSlug}"` };
+      }
+    }
+    // SDK exposes connectedAccounts.delete(id) or .disconnect(id).
+    if (typeof client.connectedAccounts?.delete === 'function') {
+      await client.connectedAccounts.delete(connectionId);
+    } else if (typeof client.connectedAccounts?.disconnect === 'function') {
+      await client.connectedAccounts.disconnect(connectionId);
+    } else {
+      return { success: false, error: 'SDK does not expose a disconnect method' };
+    }
+    return { success: true, connectionId };
+  } catch (err) {
+    return { success: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * @param {string} toolkitSlug
+ * @param {string} [userId]
+ * @returns {Promise<{success, tools?: Array, error?: string}>}
+ */
+export async function listTools(toolkitSlug, userId) {
+  const { client, error } = await getClient();
+  if (error) return { success: false, error };
+  try {
+    const tools = (await client.tools?.list?.({ toolkit: toolkitSlug, ...(userId ? { userId } : {}) })) || [];
+    return { success: true, tools };
+  } catch (err) {
+    return { success: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * @param {string} userId
+ * @param {string} toolkitSlug
+ * @param {string} actionSlug
+ * @param {object} args
+ */
+export async function execute(userId, toolkitSlug, actionSlug, args = {}) {
+  const { client, error } = await getClient();
+  if (error) return { success: false, error };
+  try {
+    const result = await client.tools?.execute?.(actionSlug, { userId, arguments: args });
+    return {
+      success: result?.successful !== false,
+      output: result?.data ?? result?.output ?? result,
+      error: result?.error || null,
+    };
+  } catch (err) {
+    return { success: false, error: err.message || String(err) };
+  }
+}
+
+/* ------------------------------------------------------------------------ */
+/* Default export — convenient grouping for callers                          */
+/* ------------------------------------------------------------------------ */
+
+export default {
+  isAvailable,
+  setApiKey,
+  forgetApiKey,
+  listToolkits,
+  listConnections,
+  connectionStatus,
+  connect,
+  disconnect,
+  listTools,
+  execute,
+};

package/src/services/memoryService.js

@@ -299,6 +299,104 @@ class MemoryService {
     return memory;
   }
 
+  /**
+   * Append a timestamped block of content to an existing memory.
+   *
+   * Designed for the "memory grows as the agent learns" use case
+   * (task-context memories accumulate findings as the agent works).
+   * Each call appends a block like:
+   *
+   *   \n\n## 2026-05-18T14:30:00Z — agent
+   *   <body>
+   *
+   * Soft-cap behavior: if the resulting content exceeds APPEND_SOFT_CAP,
+   * the OLDEST appended block (not the original creation content) is
+   * dropped to keep the memory bounded. Older blocks should be summarized
+   * by the agent if it cares about them long-term.
+   *
+   * @param {string} agentId
+   * @param {string} memoryId
+   * @param {string} body  the text to append
+   * @returns {Promise<Object|null>} updated memory or null if not found
+   */
+  /**
+   * Return a compact catalog of the agent's memories for system-prompt
+   * injection. Format is intentionally small — id + title + 1-line
+   * description, sorted by recency — because we inject this every turn
+   * and don't want to flood the prompt.
+   *
+   * Excludes archived memories so they don't dilute the visible list
+   * (archived memories remain readable via explicit `memory list` /
+   * `memory read`).
+   *
+   * @param {string} agentId
+   * @param {number} limit  max entries; older are omitted with a tail line
+   * @returns {Promise<{entries:Array<{id,title,description,updatedAt}>, total:number}>}
+   */
+  async getCatalog(agentId, limit = 20) {
+    const memories = await this.loadMemories(agentId);
+    const active = memories.filter(m => !m.archived);
+    // Sort newest-first by updatedAt (creation if never updated)
+    active.sort((a, b) => {
+      const ta = a.updatedAt || a.createdAt || '';
+      const tb = b.updatedAt || b.createdAt || '';
+      return tb.localeCompare(ta);
+    });
+    return {
+      entries: active.slice(0, limit).map(m => ({
+        id: m.id,
+        title: m.title || '(untitled)',
+        description: (m.description || '').slice(0, 120),
+        updatedAt: m.updatedAt || m.createdAt || null,
+      })),
+      total: active.length,
+    };
+  }
+
+  async appendToMemory(agentId, memoryId, body) {
+    if (typeof body !== 'string' || body.length === 0) return null;
+    const memories = await this.loadMemories(agentId);
+    const index = memories.findIndex(m => m.id === memoryId);
+    if (index === -1) {
+      this.logger?.warn('[MemoryService] Memory not found for append', { agentId, memoryId });
+      return null;
+    }
+
+    const memory = memories[index];
+    const timestamp = new Date().toISOString();
+    const block = `\n\n## ${timestamp} — agent\n${body.trim()}`;
+
+    let nextContent = (memory.content || '') + block;
+
+    // Soft cap — keep the memory bounded. When exceeded, drop the
+    // OLDEST append block (the second `## <iso> — agent` section)
+    // until we fit under the cap. Never touches the original creation
+    // content (everything before the first `## <iso> — agent` marker).
+    const APPEND_SOFT_CAP = 16_000;
+    if (nextContent.length > APPEND_SOFT_CAP) {
+      const blockRe = /\n\n## \d{4}-\d{2}-\d{2}T[\d:.]+Z — agent\n/g;
+      while (nextContent.length > APPEND_SOFT_CAP) {
+        const matches = Array.from(nextContent.matchAll(blockRe));
+        if (matches.length < 2) break; // can't drop more without touching original
+        // Drop the OLDEST append block (between first and second match).
+        const dropStart = matches[0].index;
+        const dropEnd   = matches[1].index;
+        nextContent = nextContent.slice(0, dropStart) + nextContent.slice(dropEnd);
+      }
+    }
+
+    memory.content   = nextContent;
+    memory.updatedAt = timestamp;
+    memories[index] = memory;
+    await this.saveMemories(agentId, memories);
+
+    this.logger?.info('[MemoryService] Memory appended', {
+      agentId, memoryId, title: memory.title, totalChars: memory.content.length,
+    });
+
+    return memory;
+  }
+
   /**
    * Delete a memory
    * @param {string} agentId

package/src/tools/__tests__/baseTool.test.js

@@ -452,6 +452,68 @@ describe('ToolsRegistry', () => {
     });
   });
 
+  // ── Codebase-knowledge discipline — capability-gated ──────────────────
+  //
+  // The OPERATING POSTURE block teaches code-exploration agents to
+  // consult the cache before re-issuing code-map. Non-coder agents
+  // (filesystem-only, web-only, etc.) must not see this rule — it's
+  // referencing a cache they can't populate.
+
+  describe('codebase-knowledge discipline — only for code-map agents', () => {
+    class FakeCodeMapTool extends BaseTool {
+      constructor() { super(); this.id = 'code-map'; }
+      getDescription() { return 'code-map stub'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeFilesystemTool extends BaseTool {
+      constructor() { super(); this.id = 'filesystem'; }
+      getDescription() { return 'filesystem stub'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeWebTool extends BaseTool {
+      constructor() { super(); this.id = 'web'; }
+      getDescription() { return 'web stub'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+
+    test('agent with code-map gets the CODEBASE KNOWLEDGE rule', async () => {
+      await registry.registerTool(FakeCodeMapTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['code-map']);
+      expect(desc).toContain('CODEBASE KNOWLEDGE');
+      // The rule must mention cache behavior (wording can evolve)
+      // and must call out STALE as the re-read trigger.
+      expect(desc).toMatch(/cache/i);
+      expect(desc).toMatch(/STALE/);
+      expect(desc).toMatch(/(serve.+cache|cache.+serve)/i);
+    });
+
+    test('agent with filesystem-only (no code-map) does NOT get the rule', async () => {
+      // The cache is only populated by code-map. A filesystem-only
+      // agent has nothing to populate it, so the rule would be
+      // misleading prompt bloat.
+      await registry.registerTool(FakeFilesystemTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['filesystem']);
+      expect(desc).not.toContain('CODEBASE KNOWLEDGE');
+    });
+
+    test('agent with only non-file tools (web) does NOT get the rule', async () => {
+      await registry.registerTool(FakeWebTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['web']);
+      expect(desc).not.toContain('CODEBASE KNOWLEDGE');
+    });
+
+    test('agent with both code-map AND filesystem gets the rule once', async () => {
+      await registry.registerTool(FakeCodeMapTool);
+      await registry.registerTool(FakeFilesystemTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['code-map', 'filesystem']);
+      const matches = (desc.match(/CODEBASE KNOWLEDGE/g) || []).length;
+      expect(matches).toBe(1);
+    });
+  });
+
   // ── Per-model prompt shape: skip text docs for tools with native schemas
   //    when the target uses the Responses API (codex / o-series / gpt-5-pro).
   describe('apiType="responses" — trims duplication with native function schemas', () => {

package/src/tools/__tests__/codeMapTool.pluralCanonical.test.js

@@ -0,0 +1,83 @@
+/**
+ * Plural-canonical envelope tests for the code-map tool.
+ * See companion: memoryTool.pluralCanonical.test.js.
+ */
+import { describe, test, expect } from '@jest/globals';
+import CodeMapTool from '../codeMapTool.js';
+
+const SILENT_LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+const makeTool = () => new CodeMapTool({}, SILENT_LOGGER);
+
+describe('_normalizeToActions — code-map', () => {
+  test('promotes singular {action: "skeleton", path}', () => {
+    const r = makeTool()._normalizeToActions({ action: 'skeleton', path: 'src/' });
+    expect(r).toEqual([{ type: 'skeleton', path: 'src/' }]);
+  });
+
+  test('flattens singular {action, parameters: {...}}', () => {
+    const r = makeTool()._normalizeToActions({
+      action: 'read-range',
+      parameters: { filePath: 'src/x.js', startLine: 1, endLine: 50 },
+    });
+    expect(r).toEqual([{ type: 'read-range', filePath: 'src/x.js', startLine: 1, endLine: 50 }]);
+  });
+
+  test('canonical plural unchanged', () => {
+    const r = makeTool()._normalizeToActions({
+      actions: [
+        { type: 'skeleton', path: 'src/' },
+        { type: 'read-range', filePath: 'src/x.js', startLine: 1, endLine: 50 },
+      ],
+    });
+    expect(r).toHaveLength(2);
+    expect(r[0].type).toBe('skeleton');
+  });
+
+  test('renames {actions: [{action: "X"}]} to type', () => {
+    const r = makeTool()._normalizeToActions({
+      actions: [{ action: 'skeleton', path: 'src/' }],
+    });
+    expect(r).toEqual([{ type: 'skeleton', path: 'src/' }]);
+  });
+});
+
+describe('customValidateParameters — code-map plural', () => {
+  test('singular {action: "skeleton", path} validates', () => {
+    const v = makeTool().customValidateParameters({ action: 'skeleton', path: 'src/' });
+    expect(v.valid).toBe(true);
+  });
+
+  test('plural with two valid actions validates', () => {
+    const v = makeTool().customValidateParameters({
+      actions: [
+        { type: 'skeleton', path: 'src/' },
+        { type: 'read-range', filePath: 'src/x.js', startLine: 1, endLine: 50 },
+      ],
+    });
+    expect(v.valid).toBe(true);
+  });
+
+  test('plural with bad action[1] reports by index', () => {
+    const v = makeTool().customValidateParameters({
+      actions: [
+        { type: 'skeleton', path: 'src/' },
+        { type: 'read-range' /* missing filePath/startLine/endLine */ },
+      ],
+    });
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ')).toMatch(/actions\[1\]/);
+  });
+
+  test('invalid type still gets the right-tool hint', () => {
+    const v = makeTool().customValidateParameters({
+      actions: [{ type: 'search', query: 'foo' }],
+    });
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ').toLowerCase()).toContain('seek');
+  });
+
+  test('empty params rejected', () => {
+    const v = makeTool().customValidateParameters({});
+    expect(v.valid).toBe(false);
+  });
+});