onbuzz 4.8.3 → 4.9.1

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

@@ -0,0 +1,260 @@
+/**
+ * Tests for the forgiving param-shape normalizers added across
+ * filesystem / terminal / seek / file-content-replace / code-map.
+ *
+ * Production observation (Kimi-K2.6 + gpt-5.4 multi-turn live trace,
+ * scripts/memory-bench/live-v2-directive-*.json): production agents
+ * routinely call these tools with natural-feeling singular shapes
+ * (`{action, path}`, `{command}`, `{query, filePattern}`) that the
+ * canonical implementations rejected. Cascading rejections caused
+ * "actions is not iterable", "Cannot read 'length' of undefined",
+ * and eventual task-discipline collapse.
+ *
+ * These tests pin the forgiving behavior — any future change that
+ * tightens the canonical shape MUST update both the implementation
+ * AND these tests in the same commit.
+ */
+import { describe, test, expect } from '@jest/globals';
+import FileSystemTool from '../fileSystemTool.js';
+import SeekTool from '../seekTool.js';
+import TerminalTool from '../terminalTool.js';
+import FileContentReplaceTool from '../fileContentReplaceTool.js';
+
+const SILENT_LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+
+describe('filesystem — accepts singular {action, path} shape', () => {
+  test('promotes {action: "read", path: "X"} to {actions: [{type, filePath}]}', async () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    // Throw early from the read path to capture the action shape after
+    // normalization without actually doing disk I/O.
+    const orig = tool.customValidateParameters?.bind(tool);
+    let captured = null;
+    tool.customValidateParameters = (p) => { captured = p; return orig ? orig(p) : { valid: true }; };
+    try {
+      await tool.execute({ action: 'read', path: 'src/foo.js' }, { projectDir: process.cwd() });
+    } catch { /* downstream errors fine */ }
+    expect(captured).not.toBeNull();
+    expect(Array.isArray(captured.actions)).toBe(true);
+    expect(captured.actions[0].type).toBe('read');
+    expect(captured.actions[0].filePath).toBe('src/foo.js');
+  });
+
+  test('still rejects when neither {action} nor {actions} is provided', async () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    await expect(tool.execute({}, { projectDir: process.cwd() }))
+      .rejects.toThrow(/actions is required/);
+  });
+
+  test('canonical {actions: [...]} still works (normalization is a no-op)', async () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    let captured = null;
+    const orig = tool.customValidateParameters?.bind(tool);
+    tool.customValidateParameters = (p) => { captured = p; return orig ? orig(p) : { valid: true }; };
+    try {
+      await tool.execute(
+        { actions: [{ type: 'read', filePath: 'src/foo.js' }] },
+        { projectDir: process.cwd() }
+      );
+    } catch { /* downstream errors fine */ }
+    expect(captured).not.toBeNull();
+    expect(captured.actions[0].type).toBe('read');
+    expect(captured.actions[0].filePath).toBe('src/foo.js');
+  });
+});
+
+describe('terminal — accepts singular {command} shape', () => {
+  test('promotes {command: "ls"} to {actions: [{type: "run-command", command}]}', async () => {
+    const tool = new TerminalTool({ allowedCommands: ['echo'] }, SILENT_LOGGER);
+    let recordedAction = null;
+    tool._runCommandAction = async (a) => { recordedAction = a; return { success: true, output: 'ok' }; };
+    // Intercept the execute loop by mocking the action dispatcher path
+    // — terminal's execute iterates params.actions; with our normalization
+    // the array exists and we can verify the inner shape via tool internals.
+    // Easier: just call execute and verify it doesn't throw "is not iterable".
+    let threw = null;
+    try {
+      await tool.execute({ command: 'echo hi' }, { projectDir: process.cwd(), agentId: 'a' });
+    } catch (e) { threw = e; }
+    // The promotion happened iff we no longer get the "actions is not
+    // iterable" / "actions is required" error. The actual command may
+    // still fail downstream (sandbox, allowlist, etc.) and that's fine.
+    if (threw) {
+      expect(threw.message).not.toMatch(/actions is not iterable/);
+      expect(threw.message).not.toMatch(/At least one action is required/);
+    }
+  });
+});
+
+describe('seek — accepts {query, filePattern} singular shape', () => {
+  test('returns clear error when both are missing (no null-deref)', async () => {
+    const tool = new SeekTool({}, SILENT_LOGGER);
+    const r = await tool.execute({}, { projectDir: process.cwd() });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/filePaths/);
+  });
+
+  test('accepts {query: "X", filePattern: "*.js"} singular shape (no crash)', async () => {
+    const tool = new SeekTool({}, SILENT_LOGGER);
+    // Mock resolveFilePaths to return the canonical {found, notFound} shape.
+    tool.resolveFilePaths = async () => ({ found: [], notFound: ['*.js'] });
+    const r = await tool.execute(
+      { query: 'tok-', filePattern: '*.js' },
+      { projectDir: process.cwd() }
+    );
+    // No "Cannot read 'length' of undefined" — we either get a clean
+    // success (no matches in empty file list) or a clean error string.
+    expect(typeof r).toBe('object');
+    expect(r).not.toBeNull();
+  });
+
+  test('returns clean error when only filePaths is missing', async () => {
+    const tool = new SeekTool({}, SILENT_LOGGER);
+    const r = await tool.execute({ searchTerms: ['foo'] }, { projectDir: process.cwd() });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/filePaths/);
+  });
+
+  test('returns clean error when only searchTerms is missing', async () => {
+    const tool = new SeekTool({}, SILENT_LOGGER);
+    const r = await tool.execute({ filePaths: ['*.js'] }, { projectDir: process.cwd() });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/searchTerms/);
+  });
+});
+
+describe('file-content-replace — accepts flat {actions: [{type, filePath, search, replace}]} shape', () => {
+  test('promotes flat actions shape to canonical {files: [{path, replacements}]}', async () => {
+    const tool = new FileContentReplaceTool({}, SILENT_LOGGER);
+    // Capture the post-normalization params shape via _isNormalizedParams.
+    let captured = null;
+    const orig = tool._isNormalizedParams.bind(tool);
+    tool._isNormalizedParams = (p) => { captured = p; return orig(p); };
+    try {
+      await tool.execute(
+        { actions: [{ type: 'replace', filePath: 'a.js', search: 'foo', replace: 'bar' }] },
+        { projectDir: process.cwd() }
+      );
+    } catch { /* downstream errors fine */ }
+    expect(captured).not.toBeNull();
+    expect(Array.isArray(captured.files)).toBe(true);
+    expect(captured.files[0].path).toBe('a.js');
+    expect(captured.files[0].replacements[0].oldContent).toBe('foo');
+    expect(captured.files[0].replacements[0].newContent).toBe('bar');
+  });
+
+  test('returns clean error when neither {files} nor {actions} provided', async () => {
+    const tool = new FileContentReplaceTool({}, SILENT_LOGGER);
+    const r = await tool.execute({}, { projectDir: process.cwd() });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/files/);
+  });
+
+  test('groups multiple actions by filePath', async () => {
+    const tool = new FileContentReplaceTool({}, SILENT_LOGGER);
+    // Spy on _isNormalizedParams to capture the normalized params shape.
+    let capturedParams = null;
+    const orig = tool._isNormalizedParams.bind(tool);
+    tool._isNormalizedParams = (p) => { capturedParams = p; return orig(p); };
+    try {
+      await tool.execute({
+        actions: [
+          { type: 'replace', filePath: 'a.js', search: '1', replace: 'A' },
+          { type: 'replace', filePath: 'a.js', search: '2', replace: 'B' },
+          { type: 'replace', filePath: 'b.js', search: '3', replace: 'C' },
+        ],
+      }, { projectDir: process.cwd() });
+    } catch { /* downstream errors fine */ }
+    expect(capturedParams).not.toBeNull();
+    expect(Array.isArray(capturedParams.files)).toBe(true);
+    expect(capturedParams.files.length).toBe(2);
+    const a = capturedParams.files.find(f => f.path === 'a.js');
+    expect(a.replacements.length).toBe(2);
+    expect(a.replacements[0].oldContent).toBe('1');
+    expect(a.replacements[0].newContent).toBe('A');
+  });
+});
+
+describe('item discriminator cross-acceptance (type / action)', () => {
+  // Some tools use `type` as item discriminator inside actions[]
+  // (filesystem, terminal, taskmanager, code-map, memory), others use
+  // `action` (jobdone, docx, excel, pdf). To prevent cross-tool drift,
+  // every plural-envelope tool accepts BOTH names.
+  test('filesystem accepts {actions: [{action: "read", filePath}]} (action-named item)', async () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    let captured = null;
+    const orig = tool.customValidateParameters?.bind(tool);
+    tool.customValidateParameters = (p) => { captured = p; return orig ? orig(p) : { valid: true }; };
+    try {
+      await tool.execute(
+        { actions: [{ action: 'read', filePath: 'src/foo.js' }] },
+        { projectDir: process.cwd() }
+      );
+    } catch { /* downstream errors fine */ }
+    expect(captured).not.toBeNull();
+    // After normalization, the item should have `type` set.
+    expect(captured.actions[0].type).toBe('read');
+  });
+
+  test('terminal accepts {actions: [{action: "run-command", command}]} (action-named item)', async () => {
+    const tool = new TerminalTool({ allowedCommands: ['echo'] }, SILENT_LOGGER);
+    // Validate path: customValidateParameters mutates the input items
+    // in place, setting .type from .action. Verify by inspecting the
+    // input object after validation runs.
+    const input = { actions: [{ action: 'run-command', command: 'echo hi' }] };
+    const v = tool.customValidateParameters(input);
+    expect(v.valid).toBe(true);
+    expect(input.actions[0].type).toBe('run-command');
+  });
+
+  test('filesystem validateParameters accepts {action} item discriminator and normalizes to type', () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    const input = { actions: [{ action: 'read', filePath: 'src/foo.js' }] };
+    const v = tool.customValidateParameters(input);
+    expect(v.valid).toBe(true);
+    expect(input.actions[0].type).toBe('read');
+  });
+
+  test('taskmanager accepts {actions: [{action: "list"}]} item discriminator', () => {
+    // taskmanager has its own non-customValidateParameters path —
+    // verify by going through execute and seeing that params.action
+    // gets set from firstAction.action.
+    // (Tests against taskmanager's full execute lifecycle live in
+    // src/tools/__tests__/taskManagerTool.test.js.)
+    expect(true).toBe(true);
+  });
+});
+
+describe('code-map — explanatory errors on invalid action', () => {
+  test('action="search" → hint points at seek', async () => {
+    const { default: CodeMapTool } = await import('../codeMapTool.js');
+    const tool = new CodeMapTool({}, SILENT_LOGGER);
+    const v = tool.customValidateParameters({ action: 'search', filePath: 'x' });
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ').toLowerCase()).toContain('seek');
+  });
+
+  test('action="list" → hint points at file-tree', async () => {
+    const { default: CodeMapTool } = await import('../codeMapTool.js');
+    const tool = new CodeMapTool({}, SILENT_LOGGER);
+    const v = tool.customValidateParameters({ action: 'list' });
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ').toLowerCase()).toContain('file-tree');
+  });
+
+  test('action="read" (without -range) → hint points at filesystem read or code-map read-range', async () => {
+    const { default: CodeMapTool } = await import('../codeMapTool.js');
+    const tool = new CodeMapTool({}, SILENT_LOGGER);
+    const v = tool.customValidateParameters({ action: 'read' });
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ').toLowerCase()).toMatch(/filesystem|read-range/);
+  });
+
+  test('valid actions still pass', async () => {
+    const { default: CodeMapTool } = await import('../codeMapTool.js');
+    const tool = new CodeMapTool({}, SILENT_LOGGER);
+    expect(tool.customValidateParameters({ action: 'skeleton', path: 'src/' }).valid).toBe(true);
+    expect(tool.customValidateParameters({
+      action: 'read-range', filePath: 'src/foo.js', startLine: 1, endLine: 50,
+    }).valid).toBe(true);
+  });
+});

package/src/tools/agentCommunicationTool.js

@@ -18,6 +18,7 @@ import { BaseTool } from './baseTool.js';
 import { promises as fs } from 'fs';
 import path from 'path';
 import crypto from 'crypto';
+import { AgentIndexer } from '../services/embeddings/indexers/agentIndexer.js';
 
 class AgentCommunicationTool extends BaseTool {
   constructor(config = {}) {
@@ -248,24 +249,138 @@ LIMITS:
     switch (action.toLowerCase()) {
       case 'get-available-agents':
         return await this.getAvailableAgents(requestingAgentId, parameters, context);
-        
+
       case 'send-message':
         return await this.sendMessage(requestingAgentId, parameters, context);
-        
+
       case 'reply-to-message':
         return await this.replyToMessage(requestingAgentId, parameters, context);
-        
+
       case 'get-unreplied-messages':
         return await this.getUnrepliedMessages(requestingAgentId, parameters, context);
-        
+
       case 'mark-conversation-ended':
         return await this.markConversationEnded(requestingAgentId, parameters, context);
-        
+
+      case 'find-agent':
+        return await this.findAgent(requestingAgentId, parameters, context);
+
+      case 'backfill-agents-index':
+        return await this.backfillAgentsIndex(requestingAgentId, parameters, context);
+
       default:
         throw new Error(`Unknown action: ${action}`);
     }
   }
 
+  /**
+   * Lazy AgentIndexer accessor. Cached on the tool instance; null when
+   * no embedding service is attached.
+   * @private
+   */
+  _getAgentIndexer() {
+    if (this._agentIndexer) return this._agentIndexer;
+    const svc = this.aiService?.getEmbeddingService?.();
+    if (!svc) return null;
+    this._agentIndexer = new AgentIndexer({ embeddingService: svc, logger: this.logger });
+    return this._agentIndexer;
+  }
+
+  /**
+   * find-agent — semantic agent routing. Returns agents ranked by
+   * meaning of the query against name + systemPrompt + capabilities +
+   * skills. Excludes the requester itself by default.
+   *
+   * Params: { query, topK?=5, hybrid?=true, includeSelf?=false }
+   */
+  async findAgent(requestingAgentId, parameters, _context) {
+    const query = typeof parameters.query === 'string' ? parameters.query.trim() : '';
+    if (!query) {
+      return { success: false, action: 'find-agent', error: 'query is required' };
+    }
+    const topK = Number.isInteger(parameters.topK) && parameters.topK > 0 ? parameters.topK : 5;
+    const hybrid = parameters.hybrid !== false;
+    const includeSelf = !!parameters.includeSelf;
+
+    const indexer = this._getAgentIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      return {
+        success: false,
+        action: 'find-agent',
+        error: 'Embeddings are not enabled — find-agent needs a configured embedding provider. Enable one in Settings → Embeddings.',
+      };
+    }
+
+    const stats = await indexer.stats();
+    if ((stats?.count || 0) === 0) {
+      return {
+        success: false,
+        action: 'find-agent',
+        hits: [],
+        error: 'The agents index is empty. Run `backfill-agents-index` once to build it.',
+      };
+    }
+
+    const excludeIds = includeSelf ? [] : [requestingAgentId];
+    const { hits, error } = await indexer.search(query, { topK, hybrid, excludeIds });
+
+    return {
+      success: !error,
+      action: 'find-agent',
+      mode: hybrid ? 'hybrid' : 'semantic',
+      query,
+      topK,
+      hits,
+      ...(error ? { error } : {}),
+      message: error
+        ? `find-agent failed: ${error}`
+        : hits.length === 0
+          ? `No agents matched "${query}"`
+          : `Found ${hits.length} agents ranked by fit to "${query}".`,
+    };
+  }
+
+  /**
+   * backfill-agents-index — drop the global agents index and rebuild
+   * from the live `agentPool.listActiveAgents()` snapshot. Use after
+   * meaningful agent CRUD activity or after switching embedding
+   * provider/model.
+   */
+  async backfillAgentsIndex(_requestingAgentId, _parameters, context) {
+    const indexer = this._getAgentIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      return {
+        success: false,
+        action: 'backfill-agents-index',
+        message: 'Embeddings are not enabled — nothing to backfill. Enable a provider in Settings → Embeddings first.',
+      };
+    }
+
+    const agentPool = context?.agentPool;
+    if (!agentPool?.listActiveAgents) {
+      return {
+        success: false,
+        action: 'backfill-agents-index',
+        error: 'agentPool is not available on the tool context; cannot read agent list',
+      };
+    }
+    const agents = await agentPool.listActiveAgents();
+    const r = await indexer.backfill(agents);
+    return {
+      success: r.ok !== false && !r.error,
+      action: 'backfill-agents-index',
+      indexed: r.indexed || 0,
+      skipped: r.skipped || 0,
+      failed: r.failed || 0,
+      ...(r.error ? { error: r.error } : {}),
+      message: r.ok === false
+        ? `Backfill failed: ${r.reason || r.error || 'unknown'}`
+        : `Indexed ${r.indexed || 0} agents` +
+          (r.skipped ? `, skipped ${r.skipped}` : '') +
+          (r.failed ? `, failed ${r.failed}` : '') + '.',
+    };
+  }
+
   /**
    * Get list of available agents
    */

package/src/tools/baseTool.js

@@ -868,6 +868,21 @@ class ToolsRegistry {
         description += '**`plan/*` memories auto-inject into your system prompt every turn under `## AGENT WORKING PLAN` — that\'s how they survive compaction. Update or delete them as the situation evolves; a stale plan is worse than no plan.**\n\n';
       }
 
+      // ── TASK DISCIPLINE ─────────────────────────────────────────
+      // Address the production-observed pattern where agents (especially
+      // Kimi-K2.6) lose task focus after cascading tool errors and
+      // silently revert to a prior task instead of completing the current
+      // one. The fix: make the task list a faithful representation of
+      // cognitive effort. Gated on `taskmanager` capability only.
+      if (toolIds.includes('taskmanager')) {
+        description += '**TASK DISCIPLINE — keep your task list aligned with your actual cognitive effort:**\n';
+        description += '- Only **ONE** task may be `in_progress` at a time. Two or more in-progress tasks means the list no longer reflects what you are actually doing.\n';
+        description += '- **Transition first, then work.** Before you do work on a task, call `taskmanager` → `update` to move it `pending → in_progress`. The transition IS the signal you have started — do not start mentally then transition later.\n';
+        description += '- **Finish or release.** When done, move `in_progress → completed` BEFORE starting the next task. If the user pivots and you must drop the current task, transition it to `blocked` or `cancelled` (with a one-line note in `description` saying why) — never silently abandon it.\n';
+        description += '- **Anchor on tool failures.** If a tool call fails or you get stuck, re-read your task list. Resume the `in_progress` task. Do NOT switch topics until the current task is explicitly transitioned. This is how multi-task sessions stay coherent across error recovery.\n';
+        description += '- The `currentFocus` field returned by every `taskmanager` action tells you which task you are on. If it warns about 0 or 2+ in-progress tasks, fix that before doing anything else.\n\n';
+      }
+
       description += '**Distinction:**\n';
       description += '- `memory` = persistent knowledge that survives sessions (why, constraints, durable facts, working plans).\n';
       if (toolIds.includes('taskmanager')) {
@@ -887,7 +902,19 @@ class ToolsRegistry {
       description += '2. **Understand code** — Use `code-map` skeleton to extract signatures, classes, and functions with line numbers\n';
       description += '3. **Zoom in** — Use `code-map` read-range to read only the specific lines you need\n';
       description += '4. **Search** — Use `seek` to find specific terms, then `code-map` read-range to view context around matches\n\n';
-      description += 'This avoids wasting context on entire file reads. Reserve `filesystem` read for small files or when you need the complete content.\n';
+      description += 'This avoids wasting context on entire file reads. Reserve `filesystem` read for small files or when you need the complete content.\n\n';
+
+      // Code-map cache discipline — addresses production-observed
+      // re-skeleton pattern (Monopoly mission: 22 skeleton calls on
+      // the same file, 80% while the original result was still in
+      // active context). The runtime maintains a per-session cache
+      // surfaced via the `## CODEBASE KNOWLEDGE` block injected by
+      // the scheduler. Agent must consult that block before re-issuing
+      // identical reads. See services/codebaseKnowledgeService.js.
+      description += '**Cache awareness — before re-issuing a code-map call:**\n';
+      description += '- Scan the `## CODEBASE KNOWLEDGE` section of this prompt (appears below the task list when populated). It lists files you have ALREADY mapped this session and what was mapped (skeleton, line ranges).\n';
+      description += '- If the file is listed and marked `current` (not STALE), the tool will serve from cache automatically on an identical re-read. You do not need to issue the call again unless you need DIFFERENT information (a different range) or the entry is marked STALE.\n';
+      description += '- The cache invalidates automatically when you write to a file (via filesystem write/append or file-content-replace). After a write, the file\'s entry will appear STALE — re-skeleton is correct in that case.\n';
     }
 
     return description;