onbuzz 4.9.0 → 4.9.5

package/src/services/embeddings/vectorStore/storeInterface.js

@@ -0,0 +1,91 @@
+/**
+ * VectorStore interface — contract every concrete store implements.
+ *
+ * Why a contract module instead of an abstract base class: the JS
+ * inheritance ceremony adds nothing here (these are pure data ops),
+ * but the test-helper pattern below is invaluable — every concrete
+ * store re-runs the same conformance tests, so we can swap
+ * `inMemoryJsonStore` for `sqliteVecStore` later without rewriting
+ * the test surface.
+ *
+ * Shape on disk (in-memory store):
+ *   {
+ *     "version": 1,
+ *     "dimensions": 768,
+ *     "modelFingerprint": "local:Xenova/nomic-embed-text-v1.5",
+ *     "rows": [
+ *       {
+ *         "id":       "msg_abc#0",
+ *         "vector":   [0.1, …],
+ *         "metadata": { ... }
+ *       }
+ *     ]
+ *   }
+ *
+ * Why the fingerprint lives in the file header: when a user switches
+ * providers (azure ↔ local) or models (nomic ↔ bge), the existing
+ * vectors are dimensionally + semantically incompatible. The store
+ * REFUSES to load a file whose fingerprint doesn't match what the
+ * provider currently advertises, and the orchestrator interprets that
+ * refusal as "re-embed this scope from scratch".
+ *
+ * @typedef {Object} VectorRow
+ * @property {string}       id           - Stable identifier (e.g. "msg_abc#chunk0")
+ * @property {Float32Array} vector       - L2-normalized
+ * @property {Object}       metadata     - Arbitrary indexing-time payload (text, timestamps, etc.)
+ *
+ * @typedef {Object} QueryResult
+ * @property {string} id
+ * @property {number} score              - Higher = more similar; cosine in [-1, 1]
+ * @property {Object} metadata
+ *
+ * @typedef {Object} VectorStoreStats
+ * @property {number}      count
+ * @property {number}      dimensions
+ * @property {string}      modelFingerprint
+ * @property {string|null} lastIndexedAt - ISO timestamp of newest row, or null
+ */
+
+/**
+ * Reciprocal Rank Fusion constant. The standard literature value (60)
+ * — higher = more weight on top hits, lower = more weight across all
+ * ranks. 60 is a sane middle that handles short lists well.
+ */
+export const RRF_K = 60;
+
+/**
+ * Combine two ranked lists into a single hybrid ranking via Reciprocal
+ * Rank Fusion. The math: score(id) = Σ over ranking lists of
+ *   1 / (k + rank(id, list))
+ * where rank is 1-based and missing IDs contribute 0. Ranking-only —
+ * raw scores from the input lists are NOT used, which makes the fusion
+ * robust to wildly different score scales (cosine in [-1,1] vs
+ * substring boolean).
+ *
+ * @param {Array<Array<{id: string}>>} rankedLists - Already-sorted lists.
+ *        Each list element only needs an `id`.
+ * @param {object} [opts]
+ * @param {number} [opts.k=RRF_K]
+ * @param {number} [opts.topK]  - If set, returns at most this many results.
+ * @returns {Array<{id: string, score: number}>} Sorted desc by score.
+ */
+export function reciprocalRankFusion(rankedLists, { k = RRF_K, topK } = {}) {
+  const scores = new Map(); // id -> accumulated score
+  for (const list of rankedLists) {
+    if (!Array.isArray(list)) continue;
+    for (let rank = 0; rank < list.length; rank++) {
+      const id = list[rank]?.id;
+      if (!id) continue;
+      const inc = 1 / (k + rank + 1);
+      scores.set(id, (scores.get(id) || 0) + inc);
+    }
+  }
+  const out = Array.from(scores, ([id, score]) => ({ id, score }))
+    .sort((a, b) => b.score - a.score);
+  return typeof topK === 'number' ? out.slice(0, topK) : out;
+}
+
+// `runStoreContractTests` (the shared contract test suite that every
+// VectorStore implementation re-uses) lives in `storeContractTests.js`
+// instead of here, so production imports of this module don't pull in
+// @jest/globals or other test-only deps.

package/src/services/telegramService.js

@@ -47,6 +47,43 @@ import { filterContentForExternalRelay, resolveBlockTargets } from './channelFil
 import { createTelegramSource } from './messageSource.js';
 import { parseTelegramBlock } from './telegramBlockParser.js';
 
+// Error-broadcast dedup window. The scheduler's "unknown error" branch
+// retries every 60s; with a 5-min window we collapse 5 identical fires
+// into one notification + one optional "still happening" summary.
+const ERROR_DEDUP_WINDOW_MS = 5 * 60 * 1000;
+// Memory cap on the dedup table — if a misbehaving system somehow
+// produces 50+ distinct (agent, type, message) combinations within a
+// window, we evict the oldest. In normal operation the table is tiny.
+const ERROR_DEDUP_MAX_KEYS = 50;
+
+/**
+ * Collapse runs of whitespace to a single space and trim leading/trailing
+ * whitespace — used to normalise error messages before hashing them for
+ * dedup. Implemented with plain character iteration to avoid the
+ * /\s+/g regex (the codebase convention is "string ops over regex").
+ *
+ * Treats ASCII control chars (0x00–0x20) and NBSP (0xA0) as whitespace.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function _collapseWhitespace(s) {
+  let out = '';
+  let prevWasWs = false;
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    const isWs = code <= 32 || code === 160;
+    if (isWs) {
+      prevWasWs = true;
+    } else {
+      if (prevWasWs && out.length > 0) out += ' ';
+      out += s[i];
+      prevWasWs = false;
+    }
+  }
+  return out;
+}
+
 const TELEGRAM_STATUS = {
   DISCONNECTED: 'disconnected',
   CONNECTING:   'connecting',
@@ -92,6 +129,28 @@ class TelegramService {
      */
     this.chats = new Map();
 
+    /**
+     * Dedup table for error broadcasts (agent_error / agent_timeout /
+     * criticalError / flow_run_failed).
+     *
+     * The scheduler can loop on the same uncategorised error every 60s
+     * forever; without dedup, every linked Telegram chat sees a fresh
+     * "⚠️ Agent Error" message on every retry. We coalesce identical
+     * errors within ERROR_DEDUP_WINDOW_MS and emit one "still happening"
+     * summary at the end of the window if the loop didn't clear.
+     *
+     * Keyed by `${agentId}:${type}:${hashedMessage}`. Each entry:
+     *   {
+     *     count:           how many times this exact error fired in the window
+     *     firstAt:         epoch ms of the first occurrence
+     *     agentName:       last-seen agent name (for the summary)
+     *     timer:           setTimeout handle that emits the summary on close
+     *   }
+     *
+     * Bounded by ERROR_DEDUP_MAX_KEYS so a runaway never blows memory.
+     */
+    this._errorBroadcastDedup = new Map();
+
     // Relay state (global — keyed by requestId)
     this.pendingRelays = new Map();         // requestId → { type, agentId, chatId, timeoutId, reminderId }
     this.replyContext = new Map();          // chatId → { type, requestId, agentId }
@@ -1205,7 +1264,22 @@ _Voice notes are transcribed automatically\\._`;
     }
 
     if (ALWAYS_RELAY.has(type)) {
-      this._fanoutNotification(text);
+      // Dedup: collapse identical (agent, type, message) bursts within
+      // ERROR_DEDUP_WINDOW_MS into a single first-message + an optional
+      // "still happening" summary when the window closes.
+      const agentId  = message.agentId  || message.data?.agentId  || '_unknown_';
+      const errorMsg = message.message  || message.data?.message  || message.error || '';
+      const decision = this._registerErrorBroadcast({
+        agentId,
+        type,
+        errorMsg,
+        agentName: message.agentName || message.data?.agentName,
+      });
+      if (decision.shouldEmit) {
+        this._fanoutNotification(text);
+      }
+      // else: suppressed; counter incremented; the summary timer will
+      // fire at the end of the window if count > 1.
     } else if (WATCH_GATED.has(type)) {
       for (const [chatId, state] of this.chats.entries()) {
         if (state.watchEnabled) this._queueNotification(chatId, text);
@@ -1213,6 +1287,71 @@ _Voice notes are transcribed automatically\\._`;
     }
   }
 
+  /**
+   * Register an error broadcast for dedup tracking.
+   *
+   * First occurrence in window → returns { shouldEmit: true }, schedules a
+   * close-of-window summary if more arrive.
+   * Subsequent occurrences → returns { shouldEmit: false }, increments
+   * the counter so the summary knows the magnitude.
+   *
+   * The dedup key normalises the error message (lower-case, whitespace-
+   * collapsed, length-capped) so trivial textual variations of the same
+   * underlying failure still coalesce.
+   *
+   * @param {{agentId: string, type: string, errorMsg: string, agentName?: string}} args
+   * @returns {{ shouldEmit: boolean }}
+   * @private
+   */
+  _registerErrorBroadcast({ agentId, type, errorMsg, agentName }) {
+    // Plain string ops, no regex — collapse whitespace then truncate.
+    const normalised = _collapseWhitespace(String(errorMsg || '').toLowerCase()).slice(0, 200);
+    const key = `${agentId}:${type}:${normalised}`;
+
+    const existing = this._errorBroadcastDedup.get(key);
+    if (existing) {
+      existing.count++;
+      existing.lastAt = Date.now();
+      if (agentName) existing.agentName = agentName;
+      return { shouldEmit: false };
+    }
+
+    // Capacity guard — evict the oldest entry if we're at the cap.
+    if (this._errorBroadcastDedup.size >= ERROR_DEDUP_MAX_KEYS) {
+      const oldestKey = this._errorBroadcastDedup.keys().next().value;
+      const oldest    = this._errorBroadcastDedup.get(oldestKey);
+      if (oldest?.timer) clearTimeout(oldest.timer);
+      this._errorBroadcastDedup.delete(oldestKey);
+    }
+
+    const now = Date.now();
+    const timer = setTimeout(() => {
+      const entry = this._errorBroadcastDedup.get(key);
+      this._errorBroadcastDedup.delete(key);
+      if (entry && entry.count > 1) {
+        // Emit a brief "still happening" summary. We don't replay the
+        // full error text — the user already has the first message;
+        // this just tells them it kept happening so they know it's not
+        // a one-off.
+        const extra = entry.count - 1;
+        const who = entry.agentName ? `\\\`${entry.agentName}\\\` ` : '';
+        const summary = `⚠️ *Agent Error · still happening*\nAgent: ${who}\n${extra} more similar error${extra === 1 ? '' : 's'} in the last ${Math.round(ERROR_DEDUP_WINDOW_MS / 60000)} min.`;
+        this._fanoutNotification(summary).catch(() => {});
+      }
+    }, ERROR_DEDUP_WINDOW_MS);
+    // Don't keep the event loop alive for a notification timer.
+    if (typeof timer.unref === 'function') timer.unref();
+
+    this._errorBroadcastDedup.set(key, {
+      count:     1,
+      firstAt:   now,
+      lastAt:    now,
+      agentName,
+      timer,
+    });
+    return { shouldEmit: true };
+  }
+
   /** Send `text` to every linked chat regardless of /watch state. */
   async _fanoutNotification(text) {
     for (const chatId of this.chats.keys()) {

package/src/tools/__tests__/agentCommunicationTool.findAgent.test.js

@@ -0,0 +1,226 @@
+/**
+ * agentCommunicationTool tests for find-agent + backfill-agents-index.
+ *
+ * Pins:
+ *   - find-agent with embeddings disabled → clean error
+ *   - find-agent with empty index → clean hint to backfill first
+ *   - find-agent excludes requester unless includeSelf=true
+ *   - topK + hybrid forwarded; indexer error surfaces in result
+ *   - backfill walks agentPool.listActiveAgents + calls indexer.backfill
+ *   - backfill reports skipped + failed counts honestly
+ *   - missing agentPool → clean error
+ *
+ * Mocks: stub AgentIndexer at the module boundary (the indexer's
+ * internals have their own dedicated suite); fake agentPool with the
+ * single method this tool uses.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+
+const mockIndexerInstance = {
+  isEnabled: true,
+  indexOne:  jest.fn().mockResolvedValue({ indexed: true }),
+  deleteOne: jest.fn().mockResolvedValue({ deleted: true }),
+  backfill:  jest.fn().mockResolvedValue({ ok: true, indexed: 3, skipped: 0, failed: 0 }),
+  search:    jest.fn().mockResolvedValue({ enabled: true, hits: [] }),
+  stats:     jest.fn().mockResolvedValue({ count: 3, enabled: true }),
+};
+const MockAgentIndexer = jest.fn(() => mockIndexerInstance);
+jest.unstable_mockModule('../../services/embeddings/indexers/agentIndexer.js', () => ({
+  AgentIndexer: MockAgentIndexer,
+  agentToText: () => '',
+}));
+
+const { default: AgentCommunicationTool } = await import('../agentCommunicationTool.js');
+
+function makeTool({ embeddingsEnabled = true, agents = [] } = {}) {
+  const tool = new AgentCommunicationTool();
+  mockIndexerInstance.isEnabled = embeddingsEnabled;
+  mockIndexerInstance.search.mockClear();
+  mockIndexerInstance.backfill.mockClear();
+  mockIndexerInstance.stats.mockClear();
+  MockAgentIndexer.mockClear();
+
+  tool.aiService = { getEmbeddingService: () => ({ isEnabled: embeddingsEnabled }) };
+  tool._agentIndexer = null;
+
+  const agentPool = {
+    listActiveAgents: jest.fn(async () => agents),
+  };
+  return { tool, agentPool };
+}
+
+const sampleAgents = [
+  { id: 'agent-dba', name: 'Database Specialist', systemPrompt: 'SQL migrations expert', capabilities: ['terminal'], skills: ['migrations'] },
+  { id: 'agent-fe',  name: 'Frontend Dev',        systemPrompt: 'React + CSS',            capabilities: ['filesystem'], skills: ['react'] },
+];
+
+describe('agentCommunicationTool — find-agent', () => {
+  test('disabled embeddings → clean error, no indexer search', async () => {
+    const { tool } = makeTool({ embeddingsEnabled: false });
+    const r = await tool.execute(
+      { action: 'find-agent', query: 'database expert' },
+      { agentId: 'agent-self' },
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/not enabled/i);
+    expect(mockIndexerInstance.search).not.toHaveBeenCalled();
+  });
+
+  test('empty index → clean hint to run backfill first', async () => {
+    const { tool } = makeTool();
+    mockIndexerInstance.stats.mockResolvedValue({ count: 0, enabled: true });
+    const r = await tool.execute(
+      { action: 'find-agent', query: 'database expert' },
+      { agentId: 'agent-self' },
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/backfill/);
+    expect(mockIndexerInstance.search).not.toHaveBeenCalled();
+  });
+
+  test('missing query → clean error', async () => {
+    const { tool } = makeTool();
+    const r = await tool.execute(
+      { action: 'find-agent' },
+      { agentId: 'agent-self' },
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/query/i);
+  });
+
+  test('happy path → returns hits with name/type/capabilities/skills', async () => {
+    const { tool } = makeTool();
+    mockIndexerInstance.stats.mockResolvedValue({ count: 3, enabled: true });
+    mockIndexerInstance.search.mockResolvedValue({
+      enabled: true,
+      hits: [
+        {
+          id: 'agent-dba', score: 0.9,
+          agentId: 'agent-dba', name: 'Database Specialist', type: 'data-engineer',
+          capabilities: ['terminal'], skills: ['migrations'],
+          promptSnippet: 'SQL migrations expert',
+          metadata: {},
+        },
+      ],
+    });
+    const r = await tool.execute(
+      { action: 'find-agent', query: 'database migration', topK: 3 },
+      { agentId: 'agent-self' },
+    );
+    expect(r.success).toBe(true);
+    expect(r.action).toBe('find-agent');
+    expect(r.mode).toBe('hybrid');
+    expect(r.hits[0]).toMatchObject({
+      agentId: 'agent-dba',
+      name: 'Database Specialist',
+    });
+    expect(mockIndexerInstance.search).toHaveBeenCalledWith(
+      'database migration',
+      { topK: 3, hybrid: true, excludeIds: ['agent-self'] },
+    );
+  });
+
+  test('includeSelf=true keeps requester in results', async () => {
+    const { tool } = makeTool();
+    mockIndexerInstance.stats.mockResolvedValue({ count: 1, enabled: true });
+    mockIndexerInstance.search.mockResolvedValue({ enabled: true, hits: [] });
+    await tool.execute(
+      { action: 'find-agent', query: 'q', includeSelf: true },
+      { agentId: 'agent-self' },
+    );
+    expect(mockIndexerInstance.search).toHaveBeenCalledWith(
+      'q',
+      expect.objectContaining({ excludeIds: [] }),
+    );
+  });
+
+  test('hybrid:false forwarded', async () => {
+    const { tool } = makeTool();
+    mockIndexerInstance.stats.mockResolvedValue({ count: 1, enabled: true });
+    mockIndexerInstance.search.mockResolvedValue({ enabled: true, hits: [] });
+    await tool.execute(
+      { action: 'find-agent', query: 'q', hybrid: false },
+      { agentId: 'agent-self' },
+    );
+    expect(mockIndexerInstance.search).toHaveBeenCalledWith(
+      'q',
+      expect.objectContaining({ hybrid: false }),
+    );
+  });
+
+  test('indexer error surfaces in result', async () => {
+    const { tool } = makeTool();
+    mockIndexerInstance.stats.mockResolvedValue({ count: 3, enabled: true });
+    mockIndexerInstance.search.mockResolvedValue({ enabled: true, hits: [], error: 'rate-limited' });
+    const r = await tool.execute(
+      { action: 'find-agent', query: 'q' },
+      { agentId: 'agent-self' },
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toBe('rate-limited');
+  });
+});
+
+describe('agentCommunicationTool — backfill-agents-index', () => {
+  test('disabled → clean error, no indexer call', async () => {
+    const { tool, agentPool } = makeTool({ embeddingsEnabled: false, agents: sampleAgents });
+    const r = await tool.execute(
+      { action: 'backfill-agents-index' },
+      { agentId: 'agent-self', agentPool },
+    );
+    expect(r.success).toBe(false);
+    expect(r.message).toMatch(/not enabled/i);
+    expect(mockIndexerInstance.backfill).not.toHaveBeenCalled();
+  });
+
+  test('walks listActiveAgents + calls indexer.backfill', async () => {
+    const { tool, agentPool } = makeTool({ agents: sampleAgents });
+    const r = await tool.execute(
+      { action: 'backfill-agents-index' },
+      { agentId: 'agent-self', agentPool },
+    );
+    expect(agentPool.listActiveAgents).toHaveBeenCalledTimes(1);
+    expect(mockIndexerInstance.backfill).toHaveBeenCalledWith(sampleAgents);
+    expect(r.success).toBe(true);
+    expect(r.indexed).toBe(3);
+  });
+
+  test('missing agentPool → clean error', async () => {
+    const { tool } = makeTool();
+    const r = await tool.execute(
+      { action: 'backfill-agents-index' },
+      { agentId: 'agent-self' },
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/agentPool/);
+  });
+
+  test('reports skipped + failed counts cleanly', async () => {
+    const { tool, agentPool } = makeTool({ agents: sampleAgents });
+    mockIndexerInstance.backfill.mockResolvedValue({
+      ok: true, indexed: 1, skipped: 1, failed: 0,
+    });
+    const r = await tool.execute(
+      { action: 'backfill-agents-index' },
+      { agentId: 'agent-self', agentPool },
+    );
+    expect(r.indexed).toBe(1);
+    expect(r.skipped).toBe(1);
+    expect(r.message).toMatch(/skipped 1/);
+  });
+
+  test('indexer failure surfaces cleanly', async () => {
+    const { tool, agentPool } = makeTool({ agents: sampleAgents });
+    mockIndexerInstance.backfill.mockResolvedValue({
+      ok: false, indexed: 0, skipped: 0, failed: 2, error: 'rate-limited',
+    });
+    const r = await tool.execute(
+      { action: 'backfill-agents-index' },
+      { agentId: 'agent-self', agentPool },
+    );
+    expect(r.success).toBe(false);
+    expect(r.failed).toBe(2);
+    expect(r.error).toBe('rate-limited');
+  });
+});

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

@@ -16,10 +16,25 @@ jest.unstable_mockModule('fs', () => ({
   promises: fsMock
 }));
 
+// crypto.randomBytes(4).toString('hex') is the tool's ID generator (for
+// messages, conversations, attachments — see _generate*Id helpers). The
+// previous mock returned a constant 'mockrandom' string, so uniqueness
+// relied on Date.now() alone. When the test runner is fast (e.g. with
+// --silent), multiple calls land in the same millisecond, producing
+// identical IDs that collide in this.messages — depth tracking then sees
+// the wrong root message and lets replies through that should hit the cap.
+//
+// The fix: make the mock unique per call, the way real randomBytes is.
+// We mock both randomBytes (for the ID generators that actually run) and
+// randomUUID (for any future callers) so flakes can't recur if the impl
+// switches generators.
+let __cryptoCounter = 0;
 jest.unstable_mockModule('crypto', () => ({
   default: {
-    randomUUID: jest.fn(() => 'mock-crypto-uuid'),
-    randomBytes: jest.fn(() => ({ toString: () => 'mockrandom' }))
+    randomUUID: jest.fn(() => `mock-uuid-${++__cryptoCounter}`),
+    randomBytes: jest.fn(() => ({
+      toString: () => `mb${(++__cryptoCounter).toString(16).padStart(7, '0')}`
+    }))
   }
 }));
 

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

@@ -531,11 +531,15 @@ describe('ToolsRegistry', () => {
       parseParameters() { return {}; }
       async execute() { return { ok: true }; }
     }
-    class FakeWebTool extends BaseTool {
-      // 'web' is NOT in OPENAI_FUNCTION_SCHEMAS — its text doc must always appear.
-      constructor() { super(); this.id = 'web'; }
-      getDescription() { return 'Web tool LONG description that would normally take many tokens'; }
-      getSummary() { return 'Browser automation'; }
+    // A synthetic tool whose id is NOT in OPENAI_FUNCTION_SCHEMAS. Every
+    // tool that actually ships with the CLI now has a native schema (the
+    // Responses-API efficiency push backfilled the whole catalog), so the
+    // fallback branch only fires for tools added in the future before
+    // their schemas land. This fake exercises that branch.
+    class FakeNoSchemaTool extends BaseTool {
+      constructor() { super(); this.id = 'legacy-no-schema-tool'; }
+      getDescription() { return 'No-schema tool LONG description that would normally take many tokens'; }
+      getSummary() { return 'A tool without a native schema'; }
       parseParameters() { return {}; }
       async execute() { return { ok: true }; }
     }
@@ -557,14 +561,14 @@ describe('ToolsRegistry', () => {
       expect(responsesDesc).not.toContain('LONG description that would normally take many tokens');
     });
 
-    test('keeps text description for tools that do NOT have native function schemas (e.g. web)', async () => {
-      await registry.registerTool(FakeWebTool);
+    test('keeps text description for tools that do NOT have native function schemas', async () => {
+      await registry.registerTool(FakeNoSchemaTool);
       const responsesDesc = registry.generateToolDescriptionsForPrompt(
-        ['web'],
+        ['legacy-no-schema-tool'],
         { apiType: 'responses' },
       );
-      // 'web' has no native schema → text doc MUST be present.
-      expect(responsesDesc).toContain('### WEB TOOL');
+      // No native schema → text doc MUST be present so the agent can call it.
+      expect(responsesDesc).toContain('### LEGACY-NO-SCHEMA-TOOL TOOL');
       expect(responsesDesc).toContain('LONG description that would normally take many tokens');
     });