onbuzz 5.0.2 → 5.3.0

package/package.json

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

package/scripts/gen-brand-icons.mjs

@@ -0,0 +1,21 @@
+/**
+ * Generate per-brand Electron app icons from the brand logo.
+ * Run: node scripts/gen-brand-icons.mjs
+ * Produces electron/icon-onbuzz.png (512x512, used by electron:build:onbuzz:*).
+ * The default electron/icon.png remains the Autopilot icon.
+ */
+import sharp from 'sharp';
+
+const SIZE = 512;
+const jobs = [
+  { src: 'web-ui/public/brands/onbuzz/logo.webp', out: 'electron/icon-onbuzz.png' },
+];
+
+for (const { src, out } of jobs) {
+  await sharp(src)
+    .resize(SIZE, SIZE, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+    .png()
+    .toFile(out);
+  const meta = await sharp(out).metadata();
+  console.log(`wrote ${out} (${meta.width}x${meta.height})`);
+}

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/scripts/web-automation-experiment.mjs

@@ -0,0 +1,112 @@
+/**
+ * Controlled experiment: does the tab-reuse fix make browser automation
+ * effective for a multi-turn chatbot conversation?
+ *
+ * It drives the REAL WebTool action dispatch (interactive → open-tab /
+ * switch-tab / top-level → _runActionsOnTab / executeTabAction) against a mock
+ * page that faithfully models browser semantics: page.goto() RELOADS and wipes
+ * in-page state (a chatbot's conversation lives in memory), while acting on the
+ * open page preserves it. Only the call PATTERN differs between arms.
+ *
+ * Run:  node scripts/web-automation-experiment.mjs
+ */
+import WebTool from '../src/tools/webTool.js';
+
+const TURNS = 6;
+const logger = { info() {}, warn() {}, error() {}, debug() {} };
+
+function makeChatPage() {
+  const state = { messages: [] };
+  let gotoCount = 0;
+  return {
+    state,
+    gotoCalls: () => gotoCount,
+    url: () => 'http://fixture.local/chat',
+    goto: async () => { gotoCount += 1; state.messages = []; return { status: () => 200 }; }, // reload wipes chat
+    content: async () => '<html><body>chat</body></html>',
+    close: async () => {},
+    $: async () => ({}),
+    evaluate: async (_cb, script) => {
+      if (typeof script === 'string' && script.includes('send')) {
+        state.messages.push('turn-' + (state.messages.length + 1));
+        return state.messages.length;
+      }
+      return null;
+    },
+    accessibility: { snapshot: async () => ({ role: 'WebArea', name: '', children: [
+      { role: 'textbox', name: 'Message' }, { role: 'button', name: 'Send' },
+    ] }) },
+  };
+}
+
+function newTool(agentId) {
+  const wt = new WebTool({}, logger);
+  wt.ensureBrowser = async () => {};
+  wt.browser = { isConnected: () => true, _stealthConfig: { stealthLevel: 'standard' } };
+  const page = makeChatPage();
+  wt.agentTabs.set(agentId, new Map([['chat', {
+    page, url: page.url(), name: 'chat', humanMode: false,
+    pageErrors: [], networkFailures: [], httpErrors: [], consoleMessages: [], lastActivity: 0,
+  }]]));
+  return { wt, page };
+}
+
+const run = (wt, actions, agentId) => wt.interactive(actions, { agentId, stealthLevel: 'standard', humanMode: false });
+const countErr = (r, re) => (r.results || []).filter(a => re.test(a.error || '') ||
+  (a.results || []).some(n => re.test(n.error || ''))).length;
+const CTX_ERR = /must be executed within a tab context/;
+
+async function arm(label, agentId, driveTurn) {
+  const { wt, page } = newTool(agentId);
+  let toolCalls = 0, ctxErrors = 0;
+  for (let i = 0; i < TURNS; i++) {
+    const r = await driveTurn(wt, agentId, i);
+    toolCalls += 1;
+    ctxErrors += countErr(r, CTX_ERR);
+  }
+  return { label, toolCalls, reloads: page.gotoCalls(), conversation: page.state.messages.length, ctxErrors };
+}
+
+const OLD = (wt, agentId) => run(wt, [{
+  type: 'open-tab', name: 'chat', url: 'http://fixture.local/chat',
+  nestedActions: [{ type: 'evaluate', script: 'send' }],
+}], agentId);
+
+const NEW = (wt, agentId, i) => (i === 0
+  ? run(wt, [{ type: 'open-tab', name: 'chat', url: 'http://fixture.local/chat', nestedActions: [{ type: 'evaluate', script: 'send' }] }], agentId)
+  // Subsequent turns: reuse the open tab (no url) — and use a TOP-LEVEL action
+  // (no wrapper) which previously errored with "must be executed within a tab context".
+  : run(wt, [{ type: 'evaluate', script: 'send' }], agentId));
+
+console.log(`\nControlled experiment — ${TURNS}-turn chatbot conversation\n${'='.repeat(58)}`);
+
+const oldArm = await arm('OLD (open-tab + url each turn)', 'old', OLD);
+const newArm = await arm('NEW (open once, then reuse tab)', 'new', NEW);
+
+const fmt = (a) => `${a.label.padEnd(34)} reloads=${String(a.reloads).padStart(2)}  conversation=${String(a.conversation).padStart(2)}/${TURNS}  ctxErrors=${a.ctxErrors}`;
+console.log(fmt(oldArm));
+console.log(fmt(newArm));
+
+const failures = [];
+if (!(oldArm.reloads === TURNS)) failures.push('expected OLD to reload every turn');
+if (!(oldArm.conversation === 1)) failures.push('expected OLD to lose conversation state (len 1)');
+if (!(newArm.reloads === 1)) failures.push('expected NEW to load exactly once');
+if (!(newArm.conversation === TURNS)) failures.push(`expected NEW to preserve all ${TURNS} turns`);
+if (!(newArm.ctxErrors === 0)) failures.push('expected NEW to have zero tab-context errors');
+
+console.log('\nVerdict:');
+console.log(`  • Page reloads: ${oldArm.reloads} → ${newArm.reloads}  (${Math.round((1 - newArm.reloads / oldArm.reloads) * 100)}% fewer)`);
+console.log(`  • Conversation preserved: ${oldArm.conversation}/${TURNS} → ${newArm.conversation}/${TURNS}`);
+console.log(`  • "must be executed within a tab context" errors eliminated (top-level actions now run on the active tab)`);
+
+console.log('\nUnder MAXIMUM stealth (headful browser + human-like delays) the win compounds:');
+console.log(`  • Each reload also incurs a human NAVIGATION delay (the most expensive step):`);
+console.log(`      navigation delays ≈ reloads: OLD ${oldArm.reloads} → NEW ${newArm.reloads}`);
+console.log(`  • Human pacing now applies ONLY to genuine input actions (click/type/…);`);
+console.log(`    observation actions (snapshot/evaluate/extract/get-*) incur ZERO delay.`);
+
+if (failures.length) {
+  console.error(`\n❌ EXPERIMENT FAILED:\n  - ${failures.join('\n  - ')}`);
+  process.exit(1);
+}
+console.log('\n✅ EXPERIMENT PASSED — tab reuse makes multi-turn automation effective.');

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__/stateManager.test.js

@@ -721,4 +721,29 @@ describe('StateManager', () => {
       expect(['repaired', 'partial']).toContain(restored._restoreRecoveries[0].kind);
     });
   });
+
+  // ─── getAllAvailableAgents: orphan recovery count ──────────────────────
+  describe('getAllAvailableAgents recovery count', () => {
+    test('logs a numeric (not NaN) count of agents recovered from disk', async () => {
+      // Empty index + two on-disk state files not in the index → 2 recovered.
+      mockReadFile.mockResolvedValue('{}');
+      mockReaddir.mockResolvedValueOnce(['agent-aaa-state.json', 'agent-bbb-state.json', 'not-an-agent.txt']);
+
+      await sm.getAllAvailableAgents('/proj', null);
+
+      const msg = logger.info.mock.calls.map((c) => c[0]).find((m) => /Updated agent index with .* recovered agents/.test(m));
+      expect(msg).toBe('Updated agent index with 2 recovered agents');
+      expect(msg).not.toMatch(/NaN/);
+    });
+
+    test('does not log a recovery line when there is nothing to recover', async () => {
+      mockReadFile.mockResolvedValue('{}');
+      mockReaddir.mockResolvedValueOnce([]); // no state files
+
+      await sm.getAllAvailableAgents('/proj', null);
+
+      const msg = logger.info.mock.calls.map((c) => c[0]).find((m) => /Updated agent index with/.test(m));
+      expect(msg).toBeUndefined();
+    });
+  });
 });

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

@@ -0,0 +1,87 @@
+import { describe, test, expect } from '@jest/globals';
+import { structuralPreview, DEFAULT_PREVIEW_LIMITS } from '../structuralPreview.js';
+
+describe('structuralPreview — primitives & strings', () => {
+  test('passes through small primitives unchanged, untruncated', () => {
+    for (const v of [null, 0, 42, true, false, 'short']) {
+      expect(structuralPreview(v)).toEqual({ preview: v, truncated: false });
+    }
+  });
+  test('truncates a long string with a char-count marker', () => {
+    const s = 'a'.repeat(500);
+    const { preview, truncated } = structuralPreview(s, { maxStringChars: 100 });
+    expect(truncated).toBe(true);
+    expect(preview).toBe('a'.repeat(100) + '…[+400 chars]');
+  });
+  test('a string exactly at the limit is not truncated', () => {
+    const s = 'a'.repeat(DEFAULT_PREVIEW_LIMITS.maxStringChars);
+    expect(structuralPreview(s)).toEqual({ preview: s, truncated: false });
+  });
+  test('drops functions/undefined (non-JSON)', () => {
+    expect(structuralPreview(undefined).preview).toBeUndefined();
+    expect(structuralPreview(() => {}).preview).toBeUndefined();
+  });
+});
+
+describe('structuralPreview — arrays', () => {
+  test('keeps first N items + an omission marker', () => {
+    const { preview, truncated } = structuralPreview([1, 2, 3, 4, 5], { maxArrayItems: 2 });
+    expect(preview).toEqual([1, 2, '…[+3 more of 5 items]']);
+    expect(truncated).toBe(true);
+  });
+  test('an array within the cap is untouched', () => {
+    expect(structuralPreview([1, 2], { maxArrayItems: 3 })).toEqual({ preview: [1, 2], truncated: false });
+  });
+});
+
+describe('structuralPreview — objects', () => {
+  test('keeps first N keys + a marker key', () => {
+    const obj = { a: 1, b: 2, c: 3, d: 4 };
+    const { preview, truncated } = structuralPreview(obj, { maxObjectKeys: 2 });
+    expect(preview).toEqual({ a: 1, b: 2, '…': '[+2 more keys]' });
+    expect(truncated).toBe(true);
+  });
+  test('an object within the cap is untouched', () => {
+    expect(structuralPreview({ a: 1 }, { maxObjectKeys: 5 })).toEqual({ preview: { a: 1 }, truncated: false });
+  });
+});
+
+describe('structuralPreview — depth', () => {
+  test('depth-caps nested objects', () => {
+    const deep = { l1: { l2: { l3: 'too deep' } } };
+    const { preview, truncated } = structuralPreview(deep, { maxDepth: 2 });
+    expect(preview).toEqual({ l1: { l2: '[…nested object, depth capped]' } });
+    expect(truncated).toBe(true);
+  });
+  test('depth-caps nested arrays', () => {
+    const deep = [[['x']]];
+    const { preview, truncated } = structuralPreview(deep, { maxDepth: 2 });
+    expect(preview).toEqual([['[…1 items, depth capped]']]);
+    expect(truncated).toBe(true);
+  });
+});
+
+describe('structuralPreview — representative tool output (schema-agnostic)', () => {
+  test('an email-list shape collapses to a small, structure-preserving sample', () => {
+    const emails = Array.from({ length: 10 }, (_, i) => ({
+      id: `m${i}`, subject: `Subject ${i}`, from: { name: 'X', address: 'x@y.z' },
+      bodyPreview: 'short preview', body: { contentType: 'html', content: '<div>' + 'z'.repeat(50000) + '</div>' },
+    }));
+    const payload = { success: true, output: { '@odata.context': 'u'.repeat(300), value: emails } };
+
+    const { preview, truncated } = structuralPreview(payload);
+    expect(truncated).toBe(true);
+    // structure preserved
+    expect(preview.success).toBe(true);
+    expect(Array.isArray(preview.output.value)).toBe(true);
+    // only first N emails kept + marker
+    expect(preview.output.value.length).toBe(DEFAULT_PREVIEW_LIMITS.maxArrayItems + 1);
+    expect(preview.output.value[DEFAULT_PREVIEW_LIMITS.maxArrayItems]).toMatch(/more of 10 items/);
+    // huge body truncated, useful fields intact
+    expect(preview.output.value[0].subject).toBe('Subject 0');
+    expect(preview.output.value[0].bodyPreview).toBe('short preview');
+    expect(preview.output.value[0].body.content).toMatch(/\[\+\d+ chars\]$/);
+    // and the whole thing is now tiny
+    expect(JSON.stringify(preview).length).toBeLessThan(2000);
+  });
+});