onbuzz 5.0.2 → 5.3.0

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

@@ -366,3 +366,163 @@ describe('ImportAnalyzerTool — execute against real fixture projects', () => {
     }
   });
 });
+
+// ───────────────── "not a function" call detection (full mode) ──────────────
+
+describe('ImportAnalyzerTool — notCallable detection', () => {
+  test('flags a call to a non-exported symbol (high) and renders it', async () => {
+    const dir = await mkProject('notcallable');
+    try {
+      await writeFiles(dir, {
+        'm.js': 'export const bar = 1;\n',
+        'a.js': "import { foo } from './m.js';\nfoo();\n",
+      });
+      const r = await new ImportAnalyzerTool().execute(
+        { path: '.', mode: 'full', output: 'detailed', ignoreFile: '.gitignore' },
+        { projectDir: dir },
+      );
+      expect(r.success).toBe(true);
+      expect(Array.isArray(r.results.notCallable)).toBe(true);
+      const hit = r.results.notCallable.find(f => f.callee === 'foo');
+      expect(hit).toBeTruthy();
+      expect(hit.confidence).toBe('high');
+      expect(r.statistics.issuesFound).toBeGreaterThan(0);
+      expect(r.output).toMatch(/NOT-A-FUNCTION CALLS/);
+      expect(r.output).toMatch(/not exported/);
+    } finally {
+      try { await fs.rm(dir, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+
+  test('summary output surfaces a not-a-function count', async () => {
+    const dir = await mkProject('notcallable-sum');
+    try {
+      await writeFiles(dir, {
+        'm.js': 'export const CONFIG = {};\n',
+        'a.js': "import { CONFIG } from './m.js';\nCONFIG();\n",
+      });
+      const r = await new ImportAnalyzerTool().execute(
+        { path: '.', mode: 'full', output: 'summary', ignoreFile: '.gitignore' },
+        { projectDir: dir },
+      );
+      expect(r.output).toMatch(/Not-a-function calls:/);
+    } finally {
+      try { await fs.rm(dir, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+
+  test('quick mode does NOT run the callable check', async () => {
+    const dir = await mkProject('notcallable-quick');
+    try {
+      await writeFiles(dir, {
+        'm.js': 'export const bar = 1;\n',
+        'a.js': "import { foo } from './m.js';\nfoo();\n",
+      });
+      const r = await new ImportAnalyzerTool().execute(
+        { path: '.', mode: 'quick', output: 'detailed', ignoreFile: '.gitignore' },
+        { projectDir: dir },
+      );
+      expect(r.results.notCallable).toBeUndefined();
+    } finally {
+      try { await fs.rm(dir, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+
+  test('wildcard re-export yields a low-confidence finding (rendered)', async () => {
+    const dir = await mkProject('notcallable-low');
+    try {
+      await writeFiles(dir, {
+        'other.js': 'export const realThing = () => {};\n',
+        'm.js': "export * from './other.js';\nexport const known = () => {};\n",
+        'a.js': "import { mystery } from './m.js';\nmystery();\n",
+      });
+      const r = await new ImportAnalyzerTool().execute(
+        { path: '.', mode: 'full', output: 'detailed', ignoreFile: '.gitignore' },
+        { projectDir: dir },
+      );
+      const hit = r.results.notCallable.find(f => f.callee === 'mystery');
+      expect(hit?.confidence).toBe('low');
+      expect(r.output).toMatch(/\[low\]/);
+    } finally {
+      try { await fs.rm(dir, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+
+  test('local object member miss yields a medium-confidence finding (rendered)', async () => {
+    const dir = await mkProject('notcallable-med');
+    try {
+      await writeFiles(dir, { 'a.js': 'const o = { a() {} };\no.b();\n' });
+      const r = await new ImportAnalyzerTool().execute(
+        { path: '.', mode: 'full', output: 'detailed', ignoreFile: '.gitignore' },
+        { projectDir: dir },
+      );
+      const hit = r.results.notCallable.find(f => f.callee === 'o.b');
+      expect(hit?.confidence).toBe('medium');
+      expect(r.output).toMatch(/\[medium\]/);
+    } finally {
+      try { await fs.rm(dir, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+
+  test('multiple findings render sorted high → medium → low', async () => {
+    const dir = await mkProject('notcallable-multi');
+    try {
+      await writeFiles(dir, {
+        'enum.js': 'export const bar = 1;\n',                       // fully enumerable
+        'wild.js': "export * from './enum.js';\n",                  // wildcard → not enumerable
+        'a.js':
+          "import { foo } from './enum.js';\n" +                    // high: foo not exported
+          "import { mystery } from './wild.js';\n" +               // low: wildcard module
+          "foo();\n" +
+          "mystery();\n" +
+          'const o = { a() {} };\n' +
+          'o.b();\n',                                               // medium: local object miss
+      });
+      const r = await new ImportAnalyzerTool().execute(
+        { path: '.', mode: 'full', output: 'detailed', ignoreFile: '.gitignore' },
+        { projectDir: dir },
+      );
+      const confidences = r.results.notCallable.map(f => f.confidence).sort();
+      expect(confidences).toEqual(['high', 'low', 'medium']); // all three present
+      // Detailed output orders them high → medium → low.
+      const out = r.output;
+      expect(out.indexOf('[high]')).toBeLessThan(out.indexOf('[medium]'));
+      expect(out.indexOf('[medium]')).toBeLessThan(out.indexOf('[low]'));
+    } finally {
+      try { await fs.rm(dir, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+
+  test('call into an unresolved relative import is skipped (no finding)', async () => {
+    const dir = await mkProject('notcallable-unresolved');
+    try {
+      // './ghost.js' does not exist → callable check cannot resolve it → skip.
+      await writeFiles(dir, { 'a.js': "import { ghost } from './ghost.js';\nghost();\n" });
+      const r = await new ImportAnalyzerTool().execute(
+        { path: '.', mode: 'full', output: 'json', ignoreFile: '.gitignore' },
+        { projectDir: dir },
+      );
+      expect(JSON.parse(r.output).notCallable).toEqual([]);
+    } finally {
+      try { await fs.rm(dir, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+
+  test('clean project reports no not-a-function calls', async () => {
+    const dir = await mkProject('notcallable-clean');
+    try {
+      await writeFiles(dir, {
+        'm.js': 'export function go() {}\n',
+        'a.js': "import { go } from './m.js';\ngo();\n",
+      });
+      const r = await new ImportAnalyzerTool().execute(
+        { path: '.', mode: 'full', output: 'json', ignoreFile: '.gitignore' },
+        { projectDir: dir },
+      );
+      const parsed = JSON.parse(r.output);
+      expect(parsed.notCallable).toEqual([]);
+    } finally {
+      try { await fs.rm(dir, { recursive: true, force: true }); } catch { /* */ }
+    }
+  });
+});

package/src/tools/__tests__/memoryTool.forgetStale.test.js

@@ -33,6 +33,7 @@ const mockMemoryService = {
 jest.unstable_mockModule('../../services/memoryService.js', () => ({
   getMemoryService: jest.fn(() => mockMemoryService),
   PLAN_TITLE_PREFIX: 'plan/',
+  SHARED_MEMORY_SCOPE: 'shared-user-memory',
 }));
 
 // Stub the indexer modules — forget-stale doesn't use them directly
@@ -224,7 +225,113 @@ describe('memoryTool.forget-stale — actual deletion', () => {
     );
     expect(r.forgotten).toBe(0);
     expect(r.failed).toBe(0);
-    expect(r.message).toMatch(/No memories older/);
+    expect(r.message).toMatch(/No stale memories/);
+  });
+});
+
+describe('memoryTool.pin', () => {
+  test('pins a memory (updateMemory{pinned:true}) and reports it', async () => {
+    const tool = makeTool();
+    mockMemoryService.updateMemory.mockResolvedValue({ id: 'm-1', pinned: true });
+    const r = await tool.execute({ actions: [{ type: 'pin', id: 'm-1' }] }, { agentId: 'a1' });
+    expect(r.success).toBe(true);
+    expect(r.pinned).toBe(true);
+    expect(mockMemoryService.updateMemory).toHaveBeenCalledWith('a1', 'm-1', { pinned: true });
+  });
+
+  test('unpins when pinned:false', async () => {
+    const tool = makeTool();
+    mockMemoryService.updateMemory.mockResolvedValue({ id: 'm-1', pinned: false });
+    const r = await tool.execute({ actions: [{ type: 'pin', id: 'm-1', pinned: false }] }, { agentId: 'a1' });
+    expect(r.pinned).toBe(false);
+    expect(mockMemoryService.updateMemory).toHaveBeenCalledWith('a1', 'm-1', { pinned: false });
+  });
+
+  test('unknown memory → success:false', async () => {
+    const tool = makeTool();
+    mockMemoryService.updateMemory.mockResolvedValue(null);
+    const r = await tool.execute({ actions: [{ type: 'pin', id: 'gone' }] }, { agentId: 'a1' });
+    expect(r.success).toBe(false);
+  });
+
+  test('pin without id is rejected by validation', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ actions: [{ type: 'pin' }] }, { agentId: 'a1' });
+    expect(r.success).toBe(false);
+  });
+});
+
+describe('memoryTool.forget-stale — retention (not age) decides staleness', () => {
+  const oldUnused = { id: 'm-unused', title: 'old unused', createdAt: new Date(NOW - 200 * DAY_MS).toISOString() };
+  const oldButUsed = {
+    id: 'm-used', title: 'old but used', createdAt: new Date(NOW - 200 * DAY_MS).toISOString(),
+    accessCount: 5, lastAccessed: new Date(NOW - 1 * DAY_MS).toISOString(),
+  };
+  const oldPinned = {
+    id: 'm-pin', title: 'old pinned', createdAt: new Date(NOW - 200 * DAY_MS).toISOString(), pinned: true,
+  };
+
+  test('an old-but-recently-accessed memory is KEPT (retention > age)', async () => {
+    const tool = makeTool();
+    mockMemoryService.listMemories.mockResolvedValue(makeListing([oldUnused, oldButUsed]));
+    const r = await tool.execute({ actions: [{ type: 'forget-stale', dryRun: true }] }, { agentId: 'a1' });
+    const ids = r.candidates.map((c) => c.id);
+    expect(ids).toContain('m-unused');   // old + never accessed → low retention → stale
+    expect(ids).not.toContain('m-used'); // old but recently used → high retention → kept
+  });
+
+  test('pinned memories are never forgotten', async () => {
+    const tool = makeTool();
+    mockMemoryService.listMemories.mockResolvedValue(makeListing([oldUnused, oldPinned]));
+    const r = await tool.execute({ actions: [{ type: 'forget-stale', dryRun: true }] }, { agentId: 'a1' });
+    expect(r.candidates.map((c) => c.id)).toEqual(['m-unused']);
+  });
+
+  test('candidates carry a retention score and are sorted lowest-first', async () => {
+    const tool = makeTool();
+    mockMemoryService.listMemories.mockResolvedValue(makeListing([oldUnused, fixtures.ancient]));
+    const r = await tool.execute({ actions: [{ type: 'forget-stale', dryRun: true }] }, { agentId: 'a1' });
+    expect(r.retentionThreshold).toBe(0.5);
+    expect(r.candidates.every((c) => typeof c.retention === 'number')).toBe(true);
+    const scores = r.candidates.map((c) => c.retention);
+    expect([...scores]).toEqual([...scores].sort((a, b) => a - b));
+  });
+
+  test('a high retention threshold sweeps even the recently-used memory', async () => {
+    const tool = makeTool();
+    mockMemoryService.listMemories.mockResolvedValue(makeListing([oldButUsed]));
+    const r = await tool.execute(
+      { actions: [{ type: 'forget-stale', dryRun: true, threshold: 5 }] },
+      { agentId: 'a1' },
+    );
+    expect(r.candidates.map((c) => c.id)).toContain('m-used'); // retention < 5 → now stale
+  });
+
+  test('old memory with lastAccessed but no accessCount is handled', async () => {
+    const tool = makeTool();
+    const m = { id: 'm-x', title: 'x', createdAt: new Date(NOW - 200 * DAY_MS).toISOString(), lastAccessed: new Date(NOW - 1 * DAY_MS).toISOString() };
+    mockMemoryService.listMemories.mockResolvedValue(makeListing([m]));
+    const r = await tool.execute({ actions: [{ type: 'forget-stale', dryRun: true }] }, { agentId: 'a1' });
+    expect(r.success).toBe(true); // recent access → kept, but the access path executed cleanly
+    expect(r.candidates.map((c) => c.id)).not.toContain('m-x');
+  });
+
+  test('dryRun with no stale candidates returns the no-op message', async () => {
+    const tool = makeTool();
+    mockMemoryService.listMemories.mockResolvedValue(makeListing([fixtures.fresh])); // too young
+    const r = await tool.execute({ actions: [{ type: 'forget-stale', dryRun: true }] }, { agentId: 'a1' });
+    expect(r.count).toBe(0);
+    expect(r.message).toMatch(/No stale memories/);
+  });
+
+  test('tolerates a missing grouped map / null buckets (defensive)', async () => {
+    const tool = makeTool();
+    mockMemoryService.listMemories.mockResolvedValueOnce({ count: 0 }); // no `grouped`
+    const r1 = await tool.execute({ actions: [{ type: 'forget-stale', dryRun: true }] }, { agentId: 'a1' });
+    expect(r1.count).toBe(0);
+    mockMemoryService.listMemories.mockResolvedValueOnce({ count: 0, grouped: { '2026-01-01': null } });
+    const r2 = await tool.execute({ actions: [{ type: 'forget-stale', dryRun: true }] }, { agentId: 'a1' });
+    expect(r2.count).toBe(0);
   });
 });
 

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

@@ -36,6 +36,7 @@ const mockMemoryService = {
 jest.unstable_mockModule('../../services/memoryService.js', () => ({
   getMemoryService: jest.fn(() => mockMemoryService),
   PLAN_TITLE_PREFIX: 'plan/',
+  SHARED_MEMORY_SCOPE: 'shared-user-memory',
 }));
 
 const { default: MemoryTool } = await import('../memoryTool.js');

package/src/tools/__tests__/memoryTool.reminisce.test.js

@@ -17,6 +17,7 @@ jest.unstable_mockModule('../../services/memoryService.js', () => ({
     initialize: jest.fn().mockResolvedValue(undefined),
   })),
   PLAN_TITLE_PREFIX: 'plan/',
+  SHARED_MEMORY_SCOPE: 'shared-user-memory',
 }));
 
 const { default: MemoryTool } = await import('../memoryTool.js');

package/src/tools/__tests__/memoryTool.reminisceSemanticSearch.test.js

@@ -32,6 +32,7 @@ const mockMemoryService = {
 jest.unstable_mockModule('../../services/memoryService.js', () => ({
   getMemoryService: jest.fn(() => mockMemoryService),
   PLAN_TITLE_PREFIX: 'plan/',
+  SHARED_MEMORY_SCOPE: 'shared-user-memory',
 }));
 
 const mockMemoryIndexerInstance = {

package/src/tools/__tests__/memoryTool.semanticSearch.test.js

@@ -40,6 +40,7 @@ const mockMemoryService = {
 jest.unstable_mockModule('../../services/memoryService.js', () => ({
   getMemoryService: jest.fn(() => mockMemoryService),
   PLAN_TITLE_PREFIX: 'plan/',
+  SHARED_MEMORY_SCOPE: 'shared-user-memory',
 }));
 
 // Stub the MemoryIndexer module — we want to assert exactly which
@@ -111,6 +112,22 @@ describe('memoryTool — async indexer hooks', () => {
     expect(mockIndexerInstance.indexOne).toHaveBeenCalledWith('a1', memory);
   });
 
+  test('add { shared: true } writes + indexes to the SHARED scope, not the agent', async () => {
+    const tool = makeTool();
+    const memory = { id: 'm1', title: 'User name', content: 'Daniel', createdAt: '2026-05-26T00:00:00Z' };
+    mockMemoryService.addMemory.mockResolvedValue(memory);
+
+    const res = await tool.execute(
+      { actions: [{ type: 'add', title: 'User name', content: 'Daniel', shared: true }] },
+      context,
+    );
+    await Promise.resolve();
+
+    expect(mockMemoryService.addMemory).toHaveBeenCalledWith('shared-user-memory', expect.objectContaining({ content: 'Daniel' }));
+    expect(mockIndexerInstance.indexOne).toHaveBeenCalledWith('shared-user-memory', memory);
+    expect(res).toBeDefined();
+  });
+
   test('update fires indexOne with the updated memory', async () => {
     const tool = makeTool();
     const updated = { id: 'm1', title: 'A', content: 'B-new' };

package/src/tools/__tests__/memoryTool.teamPool.test.js

@@ -34,6 +34,7 @@ const mockMemoryService = {
 jest.unstable_mockModule('../../services/memoryService.js', () => ({
   getMemoryService: jest.fn(() => mockMemoryService),
   PLAN_TITLE_PREFIX: 'plan/',
+  SHARED_MEMORY_SCOPE: 'shared-user-memory',
 }));
 
 const mockIndexerInstance = {

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

@@ -24,6 +24,7 @@ const mockMemoryService = {
 jest.unstable_mockModule('../../services/memoryService.js', () => ({
   getMemoryService: jest.fn(() => mockMemoryService),
   PLAN_TITLE_PREFIX: 'plan/',
+  SHARED_MEMORY_SCOPE: 'shared-user-memory',
 }));
 
 const { default: MemoryTool } = await import('../memoryTool.js');

package/src/tools/__tests__/openaiFunctionSchemas.validity.test.js

@@ -42,7 +42,6 @@ const REGISTERED_TOOL_IDS = new Set([
   'composio',
   'dependency-resolver',
   'desktop',
-  'doc',
   'file-content-replace',
   'file-tree',
   'filesystem',
@@ -56,7 +55,6 @@ const REGISTERED_TOOL_IDS = new Set([
   'platformcontrol',
   'seek',
   'skills',
-  'spreadsheet',
   'staticanalysis',
   'taskmanager',
   'terminal',
@@ -239,19 +237,4 @@ describe('Batch 3 convention locks', () => {
     expect(required).toContain('directory');
   });
 
-  test('legacy doc/spreadsheet: use `action` (not `type`) discriminator', () => {
-    // These predate the type-discriminator convention; their tools parse
-    // {action,...} not {type,...}. Lock the schema to match.
-    const doc = OPENAI_FUNCTION_SCHEMAS.find(s => s.name === 'doc');
-    const sheet = OPENAI_FUNCTION_SCHEMAS.find(s => s.name === 'spreadsheet');
-    expect(doc).toBeDefined();
-    expect(sheet).toBeDefined();
-    expect(doc.parameters.properties.actions.items.properties.action).toBeDefined();
-    expect(doc.parameters.properties.actions.items.required).toContain('action');
-    expect(sheet.parameters.properties.actions.items.properties.action).toBeDefined();
-    expect(sheet.parameters.properties.actions.items.required).toContain('action');
-    // Description should call out the deprecation so the model prefers `office`.
-    expect(doc.description.toLowerCase()).toMatch(/legacy|prefer/);
-    expect(sheet.description.toLowerCase()).toMatch(/legacy|prefer/);
-  });
 });

package/src/tools/__tests__/webTool.offload.test.js

@@ -0,0 +1,233 @@
+/**
+ * Stage 3b: web-content offload wiring in WebTool.
+ *
+ * Two layers:
+ *  1. _maybeOffload / _getDocumentMemory unit branches (fake DocumentMemory).
+ *  2. An end-to-end pass through execute('fetch') with a MOCKED browser/page
+ *     (no puppeteer) but a REAL DocumentMemory (temp-dir store + real indexer
+ *     + deterministic embeddings): proves fetch → persist file → index →
+ *     recall relevant passages, with only a compact handle in the result.
+ */
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+import WebTool from '../webTool.js';
+import { DocumentMemory } from '../../services/documents/documentMemory.js';
+import { DocumentStore } from '../../services/documents/documentStore.js';
+import { DocumentIndexer } from '../../services/embeddings/indexers/documentIndexer.js';
+import { InMemoryJsonStore } from '../../services/embeddings/vectorStore/inMemoryJsonStore.js';
+
+const logger = { info() {}, warn() {}, error() {}, debug() {} };
+
+// ── _maybeOffload branches (fake DocumentMemory) ────────────────────────
+describe('_maybeOffload', () => {
+  function makeTool() {
+    return new WebTool({ contentOffloadThreshold: 50, contentPreviewChars: 20 }, logger);
+  }
+  function fakeMem(handle, { recallHits = [] } = {}) {
+    return {
+      remember: jest.fn(async () => handle),
+      recall: jest.fn(async () => ({ hits: recallHits })),
+    };
+  }
+  const big = 'alpha '.repeat(40); // 240 chars > threshold
+
+  test('small content is left inline (no externalization)', async () => {
+    const wt = makeTool();
+    const { externalized, result } = await wt._maybeOffload({ text: 'short' }, { agentId: 'a', url: 'https://x/a' });
+    expect(externalized).toBe(false);
+    expect(result.text).toBe('short');
+  });
+
+  test('missing agentId leaves content inline', async () => {
+    const wt = makeTool();
+    const { externalized } = await wt._maybeOffload({ text: big }, { url: 'https://x/a' });
+    expect(externalized).toBe(false);
+  });
+
+  test('no text/html → nothing to offload', async () => {
+    const wt = makeTool();
+    const { externalized } = await wt._maybeOffload({ title: 'x' }, { agentId: 'a', url: 'https://x/a' });
+    expect(externalized).toBe(false);
+  });
+
+  test('large text → handle + preview, body removed', async () => {
+    const wt = makeTool();
+    wt._documentMemory = fakeMem({ docId: 'doc-1', source: 'https://x/a', title: 'T', bytes: 240, lines: 1, chunkCount: 2, indexed: true, embeddingsEnabled: true });
+    const { externalized, result } = await wt._maybeOffload({ title: 'T', text: big }, { agentId: 'a', url: 'https://x/a' });
+    expect(externalized).toBe(true);
+    expect(result.text).toBeUndefined();
+    expect(result.textPreview).toHaveLength(20);
+    expect(result.contentExternalized).toBe(true);
+    expect(result.document.docId).toBe('doc-1');
+    expect(result.recallHint).toMatch(/recall/i);
+  });
+
+  test('large html (no text) → html removed, htmlOmitted set', async () => {
+    const wt = makeTool();
+    wt._documentMemory = fakeMem({ docId: 'doc-2', source: 'u', title: '', bytes: 1, lines: 1, chunkCount: 1, indexed: true, embeddingsEnabled: true });
+    const { result } = await wt._maybeOffload({ html: '<div>' + big + '</div>' }, { agentId: 'a', url: 'https://x/a' });
+    expect(result.html).toBeUndefined();
+    expect(result.htmlOmitted).toBe(true);
+    expect(result.document.docId).toBe('doc-2');
+  });
+
+  test('both text and html large → text becomes the document, html omitted', async () => {
+    const wt = makeTool();
+    wt._documentMemory = fakeMem({ docId: 'doc-3', source: 'u', title: '', bytes: 1, lines: 1, chunkCount: 1, indexed: true, embeddingsEnabled: true });
+    const { result } = await wt._maybeOffload({ text: big, html: '<b>' + big + '</b>' }, { agentId: 'a', url: 'https://x/a' });
+    expect(result.text).toBeUndefined();
+    expect(result.textPreview).toBeDefined();
+    expect(result.htmlOmitted).toBe(true);
+  });
+
+  test('embeddings OFF → recallHint says so, no relevantChunks even with goal', async () => {
+    const wt = makeTool();
+    wt._documentMemory = fakeMem({ docId: 'doc-4', source: 'u', title: '', bytes: 1, lines: 1, chunkCount: 0, indexed: false, embeddingsEnabled: false });
+    const { result } = await wt._maybeOffload({ text: big }, { agentId: 'a', url: 'https://x/a', goal: 'q' });
+    expect(result.recallHint).toMatch(/OFF/);
+    expect(result.relevantChunks).toBeUndefined();
+  });
+
+  test('goal + embeddings ON → relevantChunks surfaced immediately', async () => {
+    const wt = makeTool();
+    wt._documentMemory = fakeMem(
+      { docId: 'doc-5', source: 'u', title: '', bytes: 1, lines: 9, chunkCount: 2, indexed: true, embeddingsEnabled: true },
+      { recallHits: [{ lineStart: 3, lineEnd: 5, text: 'passage' }] },
+    );
+    const { result } = await wt._maybeOffload({ text: big }, { agentId: 'a', url: 'https://x/a', goal: 'find it' });
+    expect(result.relevantChunks).toEqual([{ lineStart: 3, lineEnd: 5, text: 'passage' }]);
+  });
+
+  test('recall failure is swallowed (best-effort), handle still returned', async () => {
+    const wt = makeTool();
+    wt._documentMemory = {
+      remember: async () => ({ docId: 'doc-6', source: 'u', title: '', bytes: 1, lines: 1, chunkCount: 1, indexed: true, embeddingsEnabled: true }),
+      recall: async () => { throw new Error('recall boom'); },
+    };
+    const { result } = await wt._maybeOffload({ text: big }, { agentId: 'a', url: 'https://x/a', goal: 'q' });
+    expect(result.document.docId).toBe('doc-6');
+    expect(result.relevantChunks).toBeUndefined();
+  });
+
+  test('remember failure → inline fallback (not externalized)', async () => {
+    const wt = makeTool();
+    wt._documentMemory = { remember: async () => { throw new Error('store boom'); } };
+    const { externalized, result } = await wt._maybeOffload({ text: big }, { agentId: 'a', url: 'https://x/a' });
+    expect(externalized).toBe(false);
+    expect(result.text).toBe(big); // left inline
+  });
+});
+
+// ── _getDocumentMemory ──────────────────────────────────────────────────
+describe('_getDocumentMemory', () => {
+  test('builds a DocumentMemory and caches it', () => {
+    const wt = new WebTool({}, logger);
+    const m = wt._getDocumentMemory();
+    expect(m).toBeInstanceOf(DocumentMemory);
+    expect(wt._getDocumentMemory()).toBe(m); // cached
+  });
+
+  test('embeddings disabled when no aiService/embeddingService', () => {
+    const wt = new WebTool({}, logger);
+    expect(wt._getDocumentMemory().embeddingsEnabled).toBe(false);
+  });
+
+  test('embeddings enabled when aiService exposes an enabled service', () => {
+    const wt = new WebTool({}, logger);
+    wt.aiService = { getEmbeddingService: () => ({ isEnabled: true }) };
+    expect(wt._getDocumentMemory().embeddingsEnabled).toBe(true);
+  });
+});
+
+// ── End-to-end: execute('fetch') with mocked browser + REAL memory ──────
+describe('execute(fetch) end-to-end offload (mocked browser, real document memory)', () => {
+  let tmp;
+  let vecStore;
+
+  function vecFor(text) {
+    return String(text).toLowerCase().includes('alpha') ? Float32Array.from([1, 0, 0]) : Float32Array.from([0, 1, 0]);
+  }
+
+  beforeEach(async () => {
+    tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'weboffload-'));
+    vecStore = new InMemoryJsonStore({ filePath: path.join(tmp, 'documents.vec.json'), dimensions: 3, modelFingerprint: 'test' });
+    await vecStore.load();
+  });
+  afterEach(async () => {
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  function realMemory() {
+    const svc = {
+      isEnabled: true,
+      embedDocuments: async (texts) => texts.map(vecFor),
+      embedQuery: async (q) => vecFor(q),
+      getStore: async () => vecStore,
+    };
+    return new DocumentMemory({
+      store: new DocumentStore({ baseDir: tmp }),
+      indexer: new DocumentIndexer({ embeddingService: svc }),
+    });
+  }
+
+  function mockPage(bodyText) {
+    return {
+      on() {},
+      goto: async () => ({ status: () => 200 }),
+      title: async () => 'Big Alpha Page',
+      evaluate: async () => bodyText, // body.innerText
+      content: async () => `<html>${bodyText}</html>`,
+      close: async () => {},
+    };
+  }
+
+  test('large fetch persists a doc, returns a handle (not the body), and recalls passages', async () => {
+    const body = 'alpha '.repeat(200); // ~1200 chars, well over threshold
+    const wt = new WebTool({ contentOffloadThreshold: 100, contentPreviewChars: 50 }, logger);
+    wt.ensureBrowser = async () => {};
+    wt.browser = { isConnected: () => true, _stealthConfig: { stealthLevel: 'standard' }, newPage: async () => mockPage(body) };
+    const mem = realMemory();
+    wt._documentMemory = mem;
+
+    const res = await wt.execute(
+      { operation: 'fetch', url: 'https://example.com/big', formats: ['title', 'text'], goal: 'find alpha' },
+      { agentId: 'agent-e2e', context: {} },
+    );
+
+    // The body never came back inline — only a compact handle + preview.
+    expect(res.success).toBe(true);
+    expect(res.text).toBeUndefined();
+    expect(res.contentExternalized).toBe(true);
+    expect(res.textPreview).toHaveLength(50);
+    expect(res.document.docId).toBeTruthy();
+    expect(res.document.lines).toBeGreaterThan(0);
+    expect(res.relevantChunks.length).toBeGreaterThan(0); // goal-aware passages
+
+    // The full content is durable on disk…
+    const onDisk = await mem.read('agent-e2e', res.document.docId);
+    expect(onDisk.content).toBe(body);
+    // …and recallable semantically.
+    const recall = await mem.recall('agent-e2e', 'alpha', { topK: 5 });
+    expect(recall.hits.length).toBeGreaterThan(0);
+    expect(recall.hits[0].docId).toBe(res.document.docId);
+  });
+
+  test('re-fetching the same URL does not duplicate the document', async () => {
+    const body = 'alpha '.repeat(200);
+    const wt = new WebTool({ contentOffloadThreshold: 100 }, logger);
+    wt.ensureBrowser = async () => {};
+    wt.browser = { isConnected: () => true, _stealthConfig: { stealthLevel: 'standard' }, newPage: async () => mockPage(body) };
+    const mem = realMemory();
+    wt._documentMemory = mem;
+    const ctx = { agentId: 'agent-e2e', context: {} };
+
+    const first = await wt.execute({ operation: 'fetch', url: 'https://example.com/big', formats: ['text'] }, ctx);
+    const second = await wt.execute({ operation: 'fetch', url: 'https://example.com/big#section', formats: ['text'] }, ctx);
+
+    expect(second.document.docId).toBe(first.document.docId); // canonicalized → same id
+    const list = await mem.list('agent-e2e');
+    expect(list).toHaveLength(1); // no duplicate
+  });
+});