onbuzz 5.0.2 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",

package/scripts/recall-value-check.mjs

@@ -0,0 +1,92 @@
+/**
+ * Recall VALUE check — does the shipped 0.5 threshold actually deliver recall
+ * with the REAL nomic model? (Embedding quality, not plumbing.)
+ *
+ * Run in PLAIN NODE (not jest — jest's VM sandbox breaks onnxruntime):
+ *   node scripts/recall-value-check.mjs
+ * Point at an existing weights cache to skip a download (recommended):
+ *   LOXIA_NOMIC_STATE_DIR=<...>/loxia-autopilot/state node scripts/recall-value-check.mjs
+ *
+ * Exits 1 if the system fails to deliver value (so it works as a check):
+ *   - relevant question→fact pairs must clear the 0.5 gate
+ *   - the canonical name pair must sit BELOW the old 0.78 gate (proving the
+ *     threshold change was necessary — value quantified)
+ *   - unrelated pairs must stay below 0.5 (no new noise)
+ */
+import os from 'os';
+import path from 'path';
+import { EmbeddingService } from '../src/services/embeddings/embeddingService.js';
+
+const NEW_GATE = 0.5;
+const OLD_GATE = 0.78;
+
+const stateDir = process.env.LOXIA_NOMIC_STATE_DIR
+  || path.join(os.tmpdir(), 'loxia-nomic-value-cache');
+
+const svc = new EmbeddingService({
+  config: { provider: 'local', local: { modelId: 'nomic-ai/nomic-embed-text-v1' } },
+  apiKeyManager: { getEmbeddingApiKey: () => null },
+  baseUrl: 'http://unused',
+  stateDir,
+});
+
+function cosine(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+async function sim(q, d) {
+  const qv = await svc.embedQuery(q);
+  const dv = (await svc.embedDocuments([d], 'document'))[0];
+  return cosine(qv, dv);
+}
+
+// [question, document, expectation] — 'hit' must clear NEW_GATE, 'miss' must not.
+const RELEVANT = [
+  ["what's my name?", 'My name is Daniel.'],
+  ['where do I live?', 'I live in Tel Aviv.'],
+  ['what do I do for work?', 'I work as a software engineer.'],
+];
+const UNRELATED = [
+  ["what's my name?", 'The sky is blue today.'],
+  ['where do I live?', 'My favorite color is green.'],
+];
+
+console.log('Loading nomic model…', process.env.LOXIA_NOMIC_STATE_DIR ? `(cache: ${stateDir})` : '(downloading to temp cache)');
+await svc.warmup();
+
+const failures = [];
+
+console.log(`\nGate: recall if cosine >= ${NEW_GATE}  (old gate was ${OLD_GATE})\n`);
+console.log('RELEVANT (must be RECALLED):');
+const namePair = [];
+for (const [q, d] of RELEVANT) {
+  const s = await sim(q, d);
+  const ok = s >= NEW_GATE;
+  console.log(`  ${s.toFixed(4)}  ${ok ? 'RECALLED ✓' : 'MISSED   ✗'}  "${q}" ← "${d}"`);
+  if (!ok) failures.push(`relevant pair missed (${s.toFixed(3)}): "${q}" / "${d}"`);
+  if (d === 'My name is Daniel.') namePair.push(s);
+}
+
+console.log('\nUNRELATED (must be REJECTED):');
+for (const [q, d] of UNRELATED) {
+  const s = await sim(q, d);
+  const ok = s < NEW_GATE;
+  console.log(`  ${s.toFixed(4)}  ${ok ? 'rejected ✓' : 'LEAKED   ✗'}  "${q}" ← "${d}"`);
+  if (!ok) failures.push(`unrelated pair leaked (${s.toFixed(3)}): "${q}" / "${d}"`);
+}
+
+// Value of the threshold change: the canonical name pair must sit in (0.5, 0.78)
+// — recalled now, dropped before.
+const name = namePair[0];
+if (!(name >= NEW_GATE && name < OLD_GATE)) {
+  failures.push(`name pair ${name?.toFixed(3)} not in the (${NEW_GATE}, ${OLD_GATE}) band that proves the fix`);
+}
+console.log(`\nThreshold-change value: name pair = ${name?.toFixed(4)} → recalled at ${NEW_GATE}, would have been DROPPED at ${OLD_GATE}.`);
+
+if (failures.length) {
+  console.error(`\n❌ VALUE CHECK FAILED (${failures.length}):`);
+  for (const f of failures) console.error('  - ' + f);
+  process.exit(1);
+}
+console.log('\n✅ VALUE CHECK PASSED — recall delivers value at the shipped threshold.');

package/src/core/__tests__/agentPool.deprecatedCapabilities.test.js

@@ -0,0 +1,105 @@
+/**
+ * Deprecated-capability sanitization. `foundry_web_search` was removed from
+ * the tool registry but lingers in old persisted agent state, where it leaked
+ * into "Capabilities: …" prompt text and prompted the model to call a tool
+ * that no longer exists (58× "Tool not found" in one customer log). These
+ * tests prove it is stripped at every point capabilities enter an agent:
+ * create, update, and rehydrate-on-load (self-heal).
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger, createMockConfig, createMockStateManager } from '../../__test-utils__/mockFactories.js';
+
+const mockValidateAccessConfiguration = jest.fn().mockReturnValue({ valid: true });
+const mockCreateProjectDefaults = jest.fn().mockReturnValue({
+  workingDirectory: '/tmp/project', readOnlyDirectories: [], writeEnabledDirectories: ['/tmp/project'],
+});
+jest.unstable_mockModule('../../utilities/directoryAccessManager.js', () => {
+  const MockDAM = jest.fn().mockImplementation(() => ({ validateAccessConfiguration: mockValidateAccessConfiguration }));
+  MockDAM.createProjectDefaults = mockCreateProjectDefaults;
+  return { default: MockDAM };
+});
+jest.unstable_mockModule('../../services/visualEditorBridge.js', () => ({
+  getVisualEditorBridge: jest.fn().mockReturnValue({
+    hasInstance: jest.fn().mockReturnValue(false),
+    stopInstance: jest.fn().mockResolvedValue(undefined),
+  }),
+}));
+
+const { default: AgentPool, sanitizeCapabilities, DEPRECATED_CAPABILITIES, CAPABILITY_ALIASES } = await import('../agentPool.js');
+
+function makePool() {
+  const pool = new AgentPool(createMockConfig(), createMockLogger(), createMockStateManager(), { getContext: jest.fn() }, null);
+  return pool;
+}
+
+beforeEach(() => jest.clearAllMocks());
+
+describe('sanitizeCapabilities', () => {
+  test('strips deprecated names (case-insensitive) and keeps the rest', () => {
+    expect(sanitizeCapabilities(['web', 'foundry_web_search', 'terminal'])).toEqual(['web', 'terminal']);
+    expect(sanitizeCapabilities(['FOUNDRY_WEB_SEARCH'])).toEqual([]);
+  });
+
+  test('returns a new array and does not mutate the input', () => {
+    const input = ['web', 'foundry_web_search'];
+    const out = sanitizeCapabilities(input);
+    expect(out).not.toBe(input);
+    expect(input).toHaveLength(2);
+  });
+
+  test('passes non-array input through unchanged', () => {
+    expect(sanitizeCapabilities(undefined)).toBeUndefined();
+    expect(sanitizeCapabilities(null)).toBeNull();
+  });
+
+  test('foundry_web_search is in the deprecated set', () => {
+    expect(DEPRECATED_CAPABILITIES.has('foundry_web_search')).toBe(true);
+  });
+
+  test('migrates consolidated capabilities doc/spreadsheet → office (case-insensitive)', () => {
+    expect(sanitizeCapabilities(['doc', 'web'])).toEqual(['office', 'web']);
+    expect(sanitizeCapabilities(['SPREADSHEET'])).toEqual(['office']);
+    expect(CAPABILITY_ALIASES.get('doc')).toBe('office');
+    expect(CAPABILITY_ALIASES.get('spreadsheet')).toBe('office');
+  });
+
+  test('de-duplicates after migration (doc + spreadsheet + office → one office)', () => {
+    expect(sanitizeCapabilities(['doc', 'spreadsheet', 'office'])).toEqual(['office']);
+    expect(sanitizeCapabilities(['web', 'web'])).toEqual(['web']);
+  });
+
+  test('migration and deprecation compose (foundry dropped, doc mapped)', () => {
+    expect(sanitizeCapabilities(['foundry_web_search', 'doc', 'terminal']))
+      .toEqual(['office', 'terminal']);
+  });
+});
+
+describe('AgentPool strips deprecated capabilities', () => {
+  test('createAgent drops foundry_web_search', async () => {
+    const pool = makePool();
+    const agent = await pool.createAgent({
+      name: 'A', systemPrompt: 'x', preferredModel: 'm', projectDir: '/tmp/project',
+      capabilities: ['web', 'foundry_web_search', 'memory'],
+    });
+    expect(agent.capabilities).toEqual(['web', 'memory']);
+  });
+
+  test('updateAgent drops foundry_web_search from incoming updates', async () => {
+    const pool = makePool();
+    const agent = await pool.createAgent({
+      name: 'B', systemPrompt: 'x', preferredModel: 'm', projectDir: '/tmp/project', capabilities: ['web'],
+    });
+    const updated = await pool.updateAgent(agent.id, { capabilities: ['web', 'foundry_web_search'] });
+    expect(updated.capabilities).toEqual(['web']);
+  });
+
+  test('rehydrateFromState self-heals an old persisted agent', async () => {
+    const pool = makePool();
+    const restored = await pool.rehydrateFromState({
+      id: 'agent-old-1', name: 'Old', status: 'active',
+      capabilities: ['terminal', 'foundry_web_search'],
+      conversations: { full: { messages: [], lastUpdated: null } },
+    });
+    expect(restored.capabilities).toEqual(['terminal']);
+  });
+});

package/src/core/__tests__/agentScheduler.autoRecall.test.js

@@ -43,8 +43,6 @@ async function runAutoRecallStep({
 }) {
   const lastUserMsg = [...conversationHistory].reverse().find(m => m.role === 'user');
   if (
-    Array.isArray(agent.capabilities) &&
-    agent.capabilities.includes('memory') &&
     typeof aiService?.augmentSystemPrompt === 'function'
   ) {
     try {
@@ -114,19 +112,19 @@ describe('agentScheduler — auto-recall wiring (Phase 6d.2)', () => {
     );
   });
 
-  test('skipped when agent lacks memory capability', async () => {
+  test('fires even when agent lacks memory capability (recall is ungated)', async () => {
     const out = await runAutoRecallStep({
-      agent: { id: 'a1', capabilities: ['terminal'] },          // no memory
+      agent: { id: 'a1', capabilities: ['terminal'] },          // no memory capability
       conversationHistory: [{ role: 'user', content: 'hi' }],
       aiService, logger,
       enhancedSystemPrompt: 'BASE',
     });
-    expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
-    expect(out).toBe('BASE');                                    // unchanged
+    expect(aiService.augmentSystemPrompt).toHaveBeenCalledWith('BASE', 'a1', 'hi');
+    expect(out).toContain('## RELEVANT CONTEXT (auto-recalled)');
   });
 
-  test('skipped when capabilities is missing or non-array', async () => {
-    for (const caps of [undefined, null, 'memory', 42]) {
+  test('fires regardless of capabilities shape (capability no longer gates recall)', async () => {
+    for (const caps of [undefined, null, 'memory', 42, ['terminal']]) {
       aiService.augmentSystemPrompt.mockClear();
       const out = await runAutoRecallStep({
         agent: { id: 'a1', capabilities: caps },
@@ -134,8 +132,8 @@ describe('agentScheduler — auto-recall wiring (Phase 6d.2)', () => {
         aiService, logger,
         enhancedSystemPrompt: 'BASE',
       });
-      expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
-      expect(out).toBe('BASE');
+      expect(aiService.augmentSystemPrompt).toHaveBeenCalledTimes(1);
+      expect(out).toContain('## RELEVANT CONTEXT (auto-recalled)');
     }
   });
 

package/src/core/__tests__/agentScheduler.toolOutputOffload.test.js

@@ -0,0 +1,96 @@
+/**
+ * Scheduler wiring for generic large-tool-output offload. The pure offload
+ * logic is covered in toolResultOffload.test.js; here we prove the scheduler's
+ * lazy DocumentMemory accessor and the per-batch driver behave (delegation,
+ * caching, empty/non-array guards, and best-effort error swallowing).
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+const mockShouldAgentBeActive = jest.fn(() => ({ active: false, reason: 'idle' }));
+const mockGetActiveAgents = jest.fn(() => []);
+const mockShouldSkipIteration = jest.fn(() => false);
+jest.unstable_mockModule('../../services/agentActivityService.js', () => ({
+  shouldAgentBeActive: mockShouldAgentBeActive,
+  getActiveAgents: mockGetActiveAgents,
+  shouldSkipIteration: mockShouldSkipIteration,
+}));
+
+const { default: AgentScheduler } = await import('../agentScheduler.js');
+
+function makeScheduler(aiService = {}) {
+  const logger = createMockLogger();
+  const agentPool = { getAgent: jest.fn(), persistAgentState: jest.fn().mockResolvedValue(undefined) };
+  const scheduler = new AgentScheduler(agentPool, {}, aiService, logger);
+  return { scheduler, logger };
+}
+
+const big = () => 'x'.repeat(scheduleThreshold + 500);
+let scheduleThreshold;
+beforeEach(() => { jest.clearAllMocks(); });
+
+describe('_getToolOutputDocumentMemory', () => {
+  test('builds a DocumentMemory and caches it (idempotent)', () => {
+    const { scheduler } = makeScheduler({ getEmbeddingService: () => null });
+    const mem1 = scheduler._getToolOutputDocumentMemory();
+    const mem2 = scheduler._getToolOutputDocumentMemory();
+    expect(mem1).toBeTruthy();
+    expect(typeof mem1.remember).toBe('function');
+    expect(mem2).toBe(mem1); // cached
+  });
+
+  test('works even when aiService has no embedding service', () => {
+    const { scheduler } = makeScheduler({});
+    expect(scheduler._getToolOutputDocumentMemory()).toBeTruthy();
+  });
+});
+
+describe('_maybeOffloadToolResults', () => {
+  test('no-op for empty / non-array input', async () => {
+    const { scheduler } = makeScheduler();
+    const spy = jest.spyOn(scheduler, '_getToolOutputDocumentMemory');
+    await scheduler._maybeOffloadToolResults('a1', []);
+    await scheduler._maybeOffloadToolResults('a1', null);
+    await scheduler._maybeOffloadToolResults('a1', undefined);
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  test('externalizes oversized results in place via the document memory', async () => {
+    const { scheduler } = makeScheduler();
+    scheduleThreshold = scheduler.toolOutputOffloadThreshold;
+    const remember = jest.fn().mockResolvedValue({
+      docId: 'doc-9', lines: 10, bytes: 1, chunkCount: 1, indexed: true, embeddingsEnabled: true,
+    });
+    scheduler._toolOutputDocumentMemory = { remember }; // inject cached memory
+
+    const results = [
+      { id: 'r1', status: 'completed', toolId: 'terminal', result: big() },
+      { id: 'r2', status: 'completed', toolId: 'filesystem', result: 'small' },
+    ];
+    await scheduler._maybeOffloadToolResults('a1', results);
+
+    expect(remember).toHaveBeenCalledTimes(1);
+    expect(results[0].result.toolOutputExternalized).toBe(true);
+    expect(results[1].result).toBe('small'); // untouched
+  });
+
+  test('returns quietly when the document memory cannot be built', async () => {
+    const { scheduler } = makeScheduler();
+    jest.spyOn(scheduler, '_getToolOutputDocumentMemory').mockImplementation(() => {
+      throw new Error('no store');
+    });
+    const results = [{ id: 'r1', status: 'completed', toolId: 'terminal', result: 'x'.repeat(99999) }];
+    await expect(scheduler._maybeOffloadToolResults('a1', results)).resolves.toBeUndefined();
+    expect(results[0].result).toMatch(/^x+$/); // left inline
+  });
+
+  test('swallows per-result offload errors without throwing', async () => {
+    const { scheduler } = makeScheduler();
+    scheduler._toolOutputDocumentMemory = {
+      remember: jest.fn().mockRejectedValue(new Error('boom')),
+    };
+    const results = [{ id: 'r1', status: 'completed', toolId: 'terminal', result: 'x'.repeat(99999) }];
+    await expect(scheduler._maybeOffloadToolResults('a1', results)).resolves.toBeUndefined();
+    expect(typeof results[0].result).toBe('string'); // unchanged
+  });
+});

package/src/core/__tests__/toolResultOffload.test.js

@@ -0,0 +1,140 @@
+import { describe, test, expect, jest } from '@jest/globals';
+import {
+  serializeToolResultBody,
+  maybeOffloadToolResult,
+  DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD,
+  DEFAULT_TOOL_OUTPUT_PREVIEW_CHARS,
+} from '../toolResultOffload.js';
+
+const big = (n = DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD + 500) => 'x'.repeat(n);
+
+function fakeMemory(handle = {}) {
+  return {
+    remember: jest.fn().mockResolvedValue({
+      docId: 'doc-1',
+      lines: 42,
+      bytes: 9000,
+      chunkCount: 3,
+      indexed: true,
+      embeddingsEnabled: true,
+      ...handle,
+    }),
+  };
+}
+
+describe('serializeToolResultBody', () => {
+  test('null for non-completed / empty results', () => {
+    expect(serializeToolResultBody(null)).toBeNull();
+    expect(serializeToolResultBody({ status: 'failed', error: 'boom' })).toBeNull();
+    expect(serializeToolResultBody({ status: 'completed', result: null })).toBeNull();
+    expect(serializeToolResultBody({ status: 'completed', result: undefined })).toBeNull();
+  });
+
+  test('serializes a completed object result as pretty JSON', () => {
+    const body = serializeToolResultBody({ status: 'completed', result: { a: 1 } });
+    expect(body).toBe(JSON.stringify({ a: 1 }, null, 2));
+  });
+
+  test('stringifies a completed scalar result', () => {
+    expect(serializeToolResultBody({ status: 'completed', result: 'hello' })).toBe('hello');
+    expect(serializeToolResultBody({ status: 'completed', result: 12345 })).toBe('12345');
+  });
+
+  test('returns null when the result cannot be serialized (circular)', () => {
+    const circular = {};
+    circular.self = circular;
+    expect(serializeToolResultBody({ status: 'completed', result: circular })).toBeNull();
+  });
+});
+
+describe('maybeOffloadToolResult', () => {
+  test('no-op without document memory / agentId / toolResult', async () => {
+    expect(await maybeOffloadToolResult()).toEqual({ externalized: false, toolResult: undefined });
+    expect(await maybeOffloadToolResult({})).toEqual({ externalized: false, toolResult: undefined });
+    expect(await maybeOffloadToolResult({ documentMemory: fakeMemory(), agentId: 'a1' }))
+      .toEqual({ externalized: false, toolResult: undefined });
+    const tr = { status: 'completed', result: big() };
+    expect(await maybeOffloadToolResult({ documentMemory: fakeMemory(), toolResult: tr }))
+      .toEqual({ externalized: false, toolResult: tr });
+  });
+
+  test('skips results already externalized by their producing tool', async () => {
+    const mem = fakeMemory();
+    const webResult = { status: 'completed', toolId: 'web', result: { contentExternalized: true, x: big() } };
+    const r1 = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: webResult });
+    expect(r1.externalized).toBe(false);
+
+    const ours = { status: 'completed', toolId: 'terminal', result: { toolOutputExternalized: true, x: big() } };
+    const r2 = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: ours });
+    expect(r2.externalized).toBe(false);
+    expect(mem.remember).not.toHaveBeenCalled();
+  });
+
+  test('leaves small results inline', async () => {
+    const mem = fakeMemory();
+    const tr = { status: 'completed', toolId: 'terminal', result: 'short output' };
+    const r = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(r.externalized).toBe(false);
+    expect(tr.result).toBe('short output');
+    expect(mem.remember).not.toHaveBeenCalled();
+  });
+
+  test('externalizes a large result and replaces it with a compact handle (embeddings ON)', async () => {
+    const mem = fakeMemory();
+    const body = big();
+    const tr = { id: 'res-7', status: 'completed', toolId: 'terminal', result: body };
+
+    const r = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+
+    expect(r.externalized).toBe(true);
+    expect(mem.remember).toHaveBeenCalledWith('a1', {
+      source: 'tool://terminal/res-7',
+      title: 'terminal output',
+      content: body,
+    });
+    expect(tr.result.toolOutputExternalized).toBe(true);
+    expect(tr.result.tool).toBe('terminal');
+    expect(tr.result.preview).toBe(body.slice(0, DEFAULT_TOOL_OUTPUT_PREVIEW_CHARS));
+    expect(tr.result.omittedChars).toBe(body.length - DEFAULT_TOOL_OUTPUT_PREVIEW_CHARS);
+    expect(tr.result.document.docId).toBe('doc-1');
+    expect(tr.result.recallHint).toMatch(/Recall relevant passages semantically/);
+  });
+
+  test('recallHint reflects embeddings OFF', async () => {
+    const mem = fakeMemory({ embeddingsEnabled: false, indexed: false });
+    const tr = { status: 'completed', toolId: 'filesystem', result: big() };
+    const r = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(r.externalized).toBe(true);
+    expect(tr.result.recallHint).toMatch(/semantic recall is OFF/);
+  });
+
+  test('falls back to a generic source/tool label when toolId/id are absent', async () => {
+    const mem = fakeMemory();
+    const tr = { status: 'completed', result: big() };
+    await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(mem.remember).toHaveBeenCalledWith('a1', expect.objectContaining({
+      source: 'tool://tool/result',
+      title: 'tool output',
+    }));
+  });
+
+  test('keeps the result inline when persistence fails', async () => {
+    const mem = { remember: jest.fn().mockRejectedValue(new Error('disk full')) };
+    const body = big();
+    const tr = { status: 'completed', toolId: 'terminal', result: body };
+    const r = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(r.externalized).toBe(false);
+    expect(tr.result).toBe(body); // unchanged — agent still sees its output
+  });
+
+  test('respects a custom threshold/previewChars', async () => {
+    const mem = fakeMemory();
+    const tr = { status: 'completed', toolId: 'x', result: 'abcdefghij' };
+    const r = await maybeOffloadToolResult({
+      documentMemory: mem, agentId: 'a1', toolResult: tr, threshold: 5, previewChars: 3,
+    });
+    expect(r.externalized).toBe(true);
+    expect(tr.result.preview).toBe('abc');
+    expect(tr.result.omittedChars).toBe(7);
+  });
+});

package/src/core/agentPool.js

@@ -21,6 +21,56 @@ import {
 import DirectoryAccessManager from '../utilities/directoryAccessManager.js';
 import { getVisualEditorBridge } from '../services/visualEditorBridge.js';
 
+/**
+ * Capabilities that were once granted but whose backing tool has since been
+ * removed from the registry. They linger in old persisted agent state. Both
+ * tool-advertisement paths (openaiFunctionSchemas.getToolSchemasForAgent and
+ * baseTool.generateToolDescriptionsForPrompt) already filter to registered
+ * tools, so a stale name is never offered as a usable tool — BUT it can still
+ * leak verbatim into "Capabilities: …" prompt text and tempt the model to
+ * call a non-existent tool. One customer log shows `foundry_web_search` doing
+ * exactly that 58× ("Tool not found"). Strip these whenever capabilities enter
+ * an agent so old agents self-heal on load.
+ */
+export const DEPRECATED_CAPABILITIES = new Set(['foundry_web_search']);
+
+/**
+ * Capabilities whose backing tool was consolidated into another tool. Old
+ * persisted agents that reference the former toolId are migrated to the
+ * replacement so they keep working through the new surface. `doc` (DOCX) and
+ * `spreadsheet` (Excel) were merged into the single `office` tool.
+ */
+export const CAPABILITY_ALIASES = new Map([
+  ['doc', 'office'],
+  ['spreadsheet', 'office'],
+]);
+
+/**
+ * Normalize a capability list: migrate consolidated capabilities to their
+ * replacement (CAPABILITY_ALIASES), drop deprecated ones
+ * (DEPRECATED_CAPABILITIES), and de-duplicate (e.g. an agent that had both
+ * `doc` and `office` collapses to a single `office`). Returns a new array
+ * (never mutates the input); non-array input is returned unchanged so callers
+ * can pass `config.capabilities` straight through.
+ * @param {Array<string>} capabilities
+ * @returns {Array<string>}
+ */
+export function sanitizeCapabilities(capabilities) {
+  if (!Array.isArray(capabilities)) return capabilities;
+  const out = [];
+  const seen = new Set();
+  for (const cap of capabilities) {
+    const lc = String(cap).toLowerCase();
+    if (DEPRECATED_CAPABILITIES.has(lc)) continue;
+    const mapped = CAPABILITY_ALIASES.get(lc) || cap;
+    const mappedLc = String(mapped).toLowerCase();
+    if (seen.has(mappedLc)) continue;
+    seen.add(mappedLc);
+    out.push(mapped);
+  }
+  return out;
+}
+
 class AgentPool {
   // Stopwords for the _tokenize / _jaccard similarity check used by
   // auto-save-as-plan dedup. Tight list — only words that appear in
@@ -169,7 +219,7 @@ class AgentPool {
       originalSystemPrompt: config.systemPrompt, // Store original for reference
       preferredModel: config.preferredModel,
       status: AGENT_STATUS.ACTIVE,
-      capabilities: config.capabilities || [],
+      capabilities: sanitizeCapabilities(config.capabilities || []),
       directoryAccess: directoryAccess, // Directory access configuration
       // Per-tool configuration — keyed by tool id (e.g., 'terminal',
       // 'filesystem'). When a tool is instantiated for this agent, the
@@ -357,6 +407,12 @@ class AgentPool {
       });
     }
 
+    // Strip deprecated capabilities from any incoming update so they never
+    // get re-persisted (and so the regenerated prompt below is built clean).
+    if (updates.capabilities) {
+      updates.capabilities = sanitizeCapabilities(updates.capabilities);
+    }
+
     // If capabilities or system prompt are being updated, regenerate the enhanced system prompt
     if ((updates.capabilities || updates.originalSystemPrompt !== undefined) && this.toolsRegistry) {
       try {
@@ -691,6 +747,12 @@ class AgentPool {
       status: agentData.status === 'paused' && this._isPauseExpired(agentData) ? 'active' : agentData.status
     };
 
+    // Self-heal: drop deprecated capabilities (e.g. foundry_web_search) that
+    // were persisted before the backing tool was removed. Without this, old
+    // agents keep advertising a dead capability name into prompt text.
+    // sanitizeCapabilities passes a missing/non-array list through unchanged.
+    agent.capabilities = sanitizeCapabilities(agent.capabilities);
+
     // RECOVERY: If agent was paused awaiting user input (e.g., credentials),
     // the promise is now lost due to server/UI restart. Resume the agent.
     if (agent.awaitingUserInput) {