onbuzz 5.0.1 → 5.1.0

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,11 +42,9 @@ const REGISTERED_TOOL_IDS = new Set([
   'composio',
   'dependency-resolver',
   'desktop',
-  'doc',
   'file-content-replace',
   'file-tree',
   'filesystem',
-  'foundry_web_search',
   'help',
   'image-gen',
   'import-analyzer',
@@ -57,7 +55,6 @@ const REGISTERED_TOOL_IDS = new Set([
   'platformcontrol',
   'seek',
   'skills',
-  'spreadsheet',
   'staticanalysis',
   'taskmanager',
   'terminal',
@@ -240,29 +237,4 @@ describe('Batch 3 convention locks', () => {
     expect(required).toContain('directory');
   });
 
-  test('foundry_web_search: flat params, query is the only required field', () => {
-    const fws = OPENAI_FUNCTION_SCHEMAS.find(s => s.name === 'foundry_web_search');
-    expect(fws).toBeDefined();
-    expect(fws.parameters.properties.actions).toBeUndefined();
-    expect(fws.parameters.required).toEqual(['query']);
-    // Optional fields are advertised so the model knows they exist.
-    expect(fws.parameters.properties.instructions).toBeDefined();
-    expect(fws.parameters.properties.model).toBeDefined();
-  });
-
-  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
+  });
+});

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

@@ -0,0 +1,167 @@
+/**
+ * Stage 4: web `recall` operation — semantic search over saved documents.
+ *
+ *  1. recall() method branches (fake DocumentMemory).
+ *  2. execute('recall') end-to-end with a REAL DocumentMemory (temp store +
+ *     real indexer + deterministic embeddings), asserting hits come back
+ *     top-level AND the browser is never launched (recall is browserless).
+ */
+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() {} };
+
+// ── recall() method branches ────────────────────────────────────────────
+describe('recall()', () => {
+  function tool() { return new WebTool({}, logger); }
+  function fakeMem({ enabled = true, hits = [] } = {}) {
+    return { embeddingsEnabled: enabled, recall: jest.fn(async () => ({ enabled, hits })) };
+  }
+
+  test('empty / whitespace query → error', async () => {
+    const wt = tool();
+    expect((await wt.recall('', { agentId: 'a' })).success).toBe(false);
+    expect((await wt.recall('   ', { agentId: 'a' })).success).toBe(false);
+  });
+
+  test('missing agentId → error', async () => {
+    expect((await tool().recall('q', {})).success).toBe(false);
+  });
+
+  test('embeddings OFF → success with note, no hits, recall not called', async () => {
+    const wt = tool();
+    const mem = fakeMem({ enabled: false });
+    wt._documentMemory = mem;
+    const r = await wt.recall('q', { agentId: 'a' });
+    expect(r.success).toBe(true);
+    expect(r.count).toBe(0);
+    expect(r.hits).toEqual([]);
+    expect(r.note).toMatch(/OFF/);
+    expect(mem.recall).not.toHaveBeenCalled();
+  });
+
+  test('embeddings ON → maps hits + count', async () => {
+    const wt = tool();
+    wt._documentMemory = fakeMem({
+      hits: [{ docId: 'd1', title: 'T', source: 'u', lineStart: 2, lineEnd: 4, score: 0.9, text: 'passage' }],
+    });
+    const r = await wt.recall('q', { agentId: 'a' });
+    expect(r.success).toBe(true);
+    expect(r.count).toBe(1);
+    expect(r.hits[0]).toEqual({ docId: 'd1', title: 'T', source: 'u', lineStart: 2, lineEnd: 4, score: 0.9, text: 'passage' });
+  });
+
+  test('docId restricts the search; default topK is 8', async () => {
+    const wt = tool();
+    const mem = fakeMem();
+    wt._documentMemory = mem;
+    await wt.recall('q', { agentId: 'a', docId: 'd1' });
+    expect(mem.recall).toHaveBeenCalledWith('a', 'q', { topK: 8, docId: 'd1' });
+  });
+
+  test('explicit topK is honoured; no docId omits the filter', async () => {
+    const wt = tool();
+    const mem = fakeMem();
+    wt._documentMemory = mem;
+    await wt.recall('q', { agentId: 'a', topK: 3 });
+    expect(mem.recall).toHaveBeenCalledWith('a', 'q', { topK: 3 });
+  });
+
+  test('invalid topK falls back to default 8', async () => {
+    const wt = tool();
+    const mem = fakeMem();
+    wt._documentMemory = mem;
+    await wt.recall('q', { agentId: 'a', topK: -5 });
+    expect(mem.recall).toHaveBeenCalledWith('a', 'q', { topK: 8 });
+  });
+});
+
+// ── execute('recall') end-to-end (real memory, no browser) ──────────────
+describe('execute(recall) end-to-end', () => {
+  let tmp;
+  let vecStore;
+  const vecFor = (t) => (String(t).toLowerCase().includes('alpha') ? Float32Array.from([1, 0, 0]) : Float32Array.from([0, 1, 0]));
+
+  beforeEach(async () => {
+    tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'webrecall-'));
+    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 }) });
+  }
+
+  test('recalls a previously-saved doc and never launches the browser', async () => {
+    const mem = realMemory();
+    await mem.remember('agent-r', { source: 'https://x/a', title: 'A', content: 'alpha '.repeat(80) });
+
+    const wt = new WebTool({}, logger);
+    wt._documentMemory = mem;
+    wt.ensureBrowser = jest.fn(async () => {}); // must NOT be called
+
+    const res = await wt.execute({ operation: 'recall', query: 'alpha', topK: 5 }, { agentId: 'agent-r', context: {} });
+
+    expect(res.success).toBe(true);
+    expect(res.count).toBeGreaterThan(0);
+    expect(res.hits[0].docId).toBeTruthy();
+    expect(res.hits[0]).toHaveProperty('lineStart');
+    expect(wt.ensureBrowser).not.toHaveBeenCalled(); // browserless op
+  });
+
+  test('recall with no matches returns success + empty hits (no browser)', async () => {
+    const mem = realMemory();
+    const wt = new WebTool({}, logger);
+    wt._documentMemory = mem;
+    wt.ensureBrowser = jest.fn(async () => {});
+    const res = await wt.execute({ operation: 'recall', query: 'nothing-here' }, { agentId: 'agent-empty', context: {} });
+    expect(res.success).toBe(true);
+    expect(res.count).toBe(0);
+    expect(wt.ensureBrowser).not.toHaveBeenCalled();
+  });
+
+  test('pin marks a saved doc and never launches the browser', async () => {
+    const mem = realMemory();
+    const h = await mem.remember('agent-r', { source: 'https://x/a', content: 'alpha '.repeat(80) });
+    const wt = new WebTool({}, logger);
+    wt._documentMemory = mem;
+    wt.ensureBrowser = jest.fn(async () => {});
+
+    const pinned = await wt.execute({ operation: 'pin', docId: h.docId }, { agentId: 'agent-r', context: {} });
+    expect(pinned.success).toBe(true);
+    expect(pinned.pinned).toBe(true);
+    expect(wt.ensureBrowser).not.toHaveBeenCalled();
+    expect((await mem.list('agent-r'))[0].pinned).toBe(true);
+
+    const unpinned = await wt.execute({ operation: 'pin', docId: h.docId, pinned: false }, { agentId: 'agent-r', context: {} });
+    expect(unpinned.pinned).toBe(false);
+  });
+});
+
+describe('pinDocument() guards', () => {
+  function tool() { return new WebTool({}, logger); }
+  test('missing docId / agentId → error', async () => {
+    expect((await tool().pinDocument('', { agentId: 'a' })).success).toBe(false);
+    expect((await tool().pinDocument('doc-1', {})).success).toBe(false);
+    expect((await tool().pinDocument('doc-1')).success).toBe(false); // no options (default arg)
+  });
+  test('unknown document → error', async () => {
+    const wt = tool();
+    wt._documentMemory = { pin: async () => null };
+    expect((await wt.pinDocument('doc-nope', { agentId: 'a' })).success).toBe(false);
+  });
+});