onbuzz 4.7.1 → 4.8.0

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

@@ -419,6 +419,28 @@ describe('ToolsRegistry', () => {
     expect(tools[0].iconName.length).toBeGreaterThan(0);
   });
 
+  test('getAvailableToolsForUI prefers tool.name over description-parsed name', async () => {
+    // Regression: previously getAvailableToolsForUI ignored the explicit
+    // `this.name` set in every tool's constructor and tried to parse
+    // a name from "Foo Tool: …" prefixes in the description. When the
+    // description didn't follow that pattern OR had a colon elsewhere,
+    // the UI ended up rendering long sentences as the "name".
+    class NamedTool extends BaseTool {
+      constructor(...args) { super(...args); this.id = 'named'; this.name = 'Named Display'; }
+      getDescription() { return 'Some long description with a colon: that the old regex would eat'; }
+      parseParameters() { return {}; }
+      async execute() { return {}; }
+    }
+    await registry.registerTool(NamedTool);
+    const tools = registry.getAvailableToolsForUI();
+    const named = tools.find(t => t.id === 'named');
+    expect(named).toBeTruthy();
+    expect(named.name).toBe('Named Display');
+    // The description field still carries the readable first line —
+    // never the raw "name: " token alone.
+    expect(named.description.length).toBeGreaterThan(0);
+  });
+
   test('_getToolCategory maps every known tool (no "Other") incl. video-gen', () => {
     // Locks the "tools introduced to UI" alignment — a tool with no
     // explicit category falls into "Other" and gets buried in dropdowns.

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

@@ -334,6 +334,298 @@ describe('CodeMapTool', () => {
     expect(re).toContain('(.+/)?');
   });
 
+  // ─────────────────────────────────────────────────────────────────
+  // Browser-JS / pre-ES-module patterns. Before this set of regexes,
+  // CodeMap on a vanilla client-side .js file produced an empty map
+  // because the parser only matched ESM exports + class methods.
+  // These tests pin the new patterns. Each test exercises ONE pattern
+  // in isolation so a future regression on any one of them surfaces
+  // a precise failure.
+  // ─────────────────────────────────────────────────────────────────
+  describe('_parseJS — browser-JS patterns', () => {
+    const opts = { publicOnly: false, withComments: false, includeImports: false };
+    const signatures = (entries) =>
+      entries.filter(e => e.kind === 'signature').map(e => e.text.trim());
+
+    test('top-level IIFE is captured', () => {
+      const entries = tool._parseJS([
+        '(function () {',
+        '  var x = 1;',
+        '})();',
+      ], opts);
+      expect(signatures(entries)).toContain('(function () {');
+    });
+
+    test('IIFE with leading ! or + prefix (Webpack-UMD style)', () => {
+      const entries = tool._parseJS([
+        '!function () { return 1; }();',
+        '+function () { return 2; }();',
+      ], opts);
+      expect(signatures(entries)).toEqual(expect.arrayContaining([
+        '!function () { return 1; }();',
+        '+function () { return 2; }();',
+      ]));
+    });
+
+    test('window.X = function — global assignment', () => {
+      const entries = tool._parseJS([
+        'window.MyApp = function () {',
+        '  return 1;',
+        '};',
+      ], opts);
+      expect(signatures(entries).join('\n')).toMatch(/window\.MyApp\s*=\s*function/);
+    });
+
+    test('globalThis.foo = () => — global arrow assignment', () => {
+      const entries = tool._parseJS([
+        'globalThis.greet = (name) => `hi ${name}`;',
+      ], opts);
+      expect(signatures(entries).join('\n')).toMatch(/globalThis\.greet/);
+    });
+
+    test('Namespace.utils.foo = function — namespaced global assignment', () => {
+      const entries = tool._parseJS([
+        'MyApp.utils.formatDate = function (d) {',
+        '  return d.toISOString();',
+        '};',
+      ], opts);
+      expect(signatures(entries).join('\n')).toMatch(/MyApp\.utils\.formatDate/);
+    });
+
+    test('Foo.prototype.bar = function — prototype method', () => {
+      const entries = tool._parseJS([
+        'Foo.prototype.bar = function () {',
+        '  return this.x;',
+        '};',
+      ], opts);
+      expect(signatures(entries).join('\n')).toMatch(/Foo\.prototype\.bar/);
+    });
+
+    test('Foo.prototype.bar = () => — prototype arrow assignment', () => {
+      // (Real-world prototype-as-arrow is unusual but the regex
+      // covers it for completeness.)
+      const entries = tool._parseJS([
+        'Foo.prototype.bar = () => 42;',
+      ], opts);
+      expect(signatures(entries).join('\n')).toMatch(/Foo\.prototype\.bar/);
+    });
+
+    test('jQuery $.fn.plugin = function — jQuery plugin pattern', () => {
+      const entries = tool._parseJS([
+        '$.fn.myPlugin = function (opts) {',
+        '  return this.each(function () {});',
+        '};',
+      ], opts);
+      expect(signatures(entries).join('\n')).toMatch(/\$\.fn\.myPlugin/);
+    });
+
+    test('jQuery.fn.plugin = function — full jQuery prefix', () => {
+      const entries = tool._parseJS([
+        'jQuery.fn.banner = function () { return this; };',
+      ], opts);
+      expect(signatures(entries).join('\n')).toMatch(/jQuery\.fn\.banner/);
+    });
+
+    test('document.addEventListener("DOMContentLoaded", …) — page lifecycle', () => {
+      const entries = tool._parseJS([
+        'document.addEventListener("DOMContentLoaded", () => {',
+        '  init();',
+        '});',
+      ], opts);
+      expect(signatures(entries).join('\n')).toMatch(/document\.addEventListener/);
+    });
+
+    test('window.addEventListener("load", …) — page lifecycle (alt)', () => {
+      const entries = tool._parseJS([
+        'window.addEventListener("load", function () { boot(); });',
+      ], opts);
+      expect(signatures(entries).join('\n')).toMatch(/window\.addEventListener/);
+    });
+
+    test('REGRESSION: a vanilla browser file (IIFE wrapping jQuery plugins) now produces a non-empty map', () => {
+      // This is the original failure case: pure client-side .js with
+      // none of the new patterns produced zero entries. Pre-fix this
+      // file's signatures.length would have been 0; post-fix it's > 0.
+      const entries = tool._parseJS([
+        '(function ($) {',
+        '  $.fn.tooltip = function (options) {',
+        '    return this.each(function () {});',
+        '  };',
+        '  $.fn.popover = function (options) {',
+        '    return this.each(function () {});',
+        '  };',
+        '})(jQuery);',
+      ], opts);
+      expect(signatures(entries).length).toBeGreaterThanOrEqual(3);
+    });
+
+    test('REGRESSION: file unaffected by changes — modern ESM still matches', () => {
+      // Make sure adding the new regexes didn't regress the original
+      // matcher set.
+      const entries = tool._parseJS([
+        'export function hello() {}',
+        'export class Greeter {}',
+        'export const sum = (a, b) => a + b;',
+      ], opts);
+      expect(signatures(entries).length).toBe(3);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────
+  // C / C++ — _parseC. Same approach as the JS path; we lock the
+  // patterns the regex needs to handle on real-world C/CPP files so
+  // a future refactor (e.g. swapping for tree-sitter) has explicit
+  // behavior to preserve.
+  // ─────────────────────────────────────────────────────────────────
+  describe('_parseC — C/C++ skeleton extraction', () => {
+    const opts = { publicOnly: false, withComments: false, includeImports: true };
+    const sig = (lines) => tool._parseC(lines, opts).filter(e => e.kind === 'signature').map(e => e.text.trim());
+    const imp = (lines) => tool._parseC(lines, opts).filter(e => e.kind === 'import').map(e => e.text.trim());
+
+    test('#include with angle brackets and quotes', () => {
+      const lines = [
+        '#include <stdio.h>',
+        '#include "myheader.h"',
+      ];
+      expect(imp(lines)).toEqual([
+        '#include <stdio.h>',
+        '#include "myheader.h"',
+      ]);
+    });
+
+    test('#define captured as signature', () => {
+      expect(sig(['#define MAX_BUF 1024', '#define PI 3.14'])).toEqual([
+        '#define MAX_BUF 1024',
+        '#define PI 3.14',
+      ]);
+    });
+
+    test('class / struct / union / enum / namespace headers', () => {
+      const lines = [
+        'class Foo {',
+        '};',
+        'struct Bar {',
+        '};',
+        'union Baz { int a; };',
+        'enum class Color { RED, GREEN };',
+        'namespace loxia {',
+        '}',
+      ];
+      const found = sig(lines).join('\n');
+      expect(found).toMatch(/class Foo/);
+      expect(found).toMatch(/struct Bar/);
+      expect(found).toMatch(/union Baz/);
+      expect(found).toMatch(/enum class Color/);
+      expect(found).toMatch(/namespace loxia/);
+    });
+
+    test('typedef and using alias', () => {
+      const lines = [
+        'typedef unsigned long u64;',
+        'using IntList = std::vector<int>;',
+      ];
+      const found = sig(lines).join('\n');
+      expect(found).toMatch(/typedef unsigned long u64/);
+      expect(found).toMatch(/using IntList/);
+    });
+
+    test('free function definition with simple return type', () => {
+      const lines = [
+        'int add(int a, int b) {',
+        '  return a + b;',
+        '}',
+      ];
+      expect(sig(lines).join('\n')).toMatch(/int add\(int a, int b\)/);
+    });
+
+    test('static + inline + const-qualified function definitions', () => {
+      const lines = [
+        'static inline int square(int x) { return x * x; }',
+        'const char* greet(const char* name) {',
+        '  return name;',
+        '}',
+      ];
+      const found = sig(lines).join('\n');
+      expect(found).toMatch(/static inline int square/);
+      expect(found).toMatch(/const char\* greet/);
+    });
+
+    test('method, constructor, and destructor', () => {
+      const lines = [
+        'Foo::Foo(int x) : x_(x) {',
+        '}',
+        'Foo::~Foo() {',
+        '}',
+        'int Foo::compute(int n) const {',
+        '  return n * x_;',
+        '}',
+      ];
+      const found = sig(lines).join('\n');
+      expect(found).toMatch(/Foo::Foo\(int x\)/);
+      expect(found).toMatch(/Foo::~Foo\(\)/);
+      expect(found).toMatch(/int Foo::compute/);
+    });
+
+    test('REGRESSION: function CALLS are NOT misidentified as definitions', () => {
+      // Without the call-rejection heuristic, the regex would happily
+      // grab `printf("hi");` as a signature. Lock that it doesn't.
+      const lines = [
+        'int main(void) {',
+        '  printf("hi");',
+        '  foo();',
+        '  return 0;',
+        '}',
+      ];
+      // Only main(void) should be a signature; printf/foo are calls.
+      const found = sig(lines);
+      expect(found).toEqual(['int main(void) {']);
+    });
+
+    test('REGRESSION: a tiny realistic C file produces a useful skeleton', () => {
+      const lines = [
+        '#include <stdio.h>',
+        '',
+        '#define BUF_SIZE 256',
+        '',
+        'typedef struct {',
+        '  int x;',
+        '  int y;',
+        '} Point;',
+        '',
+        'static int distance_sq(Point p) {',
+        '  return p.x * p.x + p.y * p.y;',
+        '}',
+        '',
+        'int main(int argc, char** argv) {',
+        '  Point p = { 3, 4 };',
+        '  printf("d² = %d\\n", distance_sq(p));',
+        '  return 0;',
+        '}',
+      ];
+      const all = tool._parseC(lines, opts);
+      // Includes count as imports; the rest are signatures.
+      const imports = all.filter(e => e.kind === 'import').map(e => e.text.trim());
+      const signatures = all.filter(e => e.kind === 'signature').map(e => e.text.trim());
+      expect(imports).toEqual(['#include <stdio.h>']);
+      expect(signatures).toEqual(expect.arrayContaining([
+        '#define BUF_SIZE 256',
+        'static int distance_sq(Point p) {',
+        'int main(int argc, char** argv) {',
+      ]));
+    });
+  });
+
+  test('_langOf detects C/C++ files', () => {
+    expect(tool._langOf('foo.c')).toBe('c');
+    expect(tool._langOf('foo.h')).toBe('c');
+    expect(tool._langOf('foo.cpp')).toBe('c');
+    expect(tool._langOf('foo.cxx')).toBe('c');
+    expect(tool._langOf('foo.hpp')).toBe('c');
+    expect(tool._langOf('foo.cc')).toBe('c');
+    expect(tool._langOf('app.js')).toBe('js'); // sanity
+    expect(tool._langOf('script.py')).toBe('python'); // sanity
+  });
+
   test('execute skeleton on unsupported file type throws', async () => {
     mockFsPromises.stat.mockResolvedValue({
       isFile: () => true,
@@ -345,4 +637,100 @@ describe('CodeMapTool', () => {
       context
     )).rejects.toThrow('Unsupported file type');
   });
+
+  // ─────────────────────────────────────────────────────────────────
+  // Regex-free parser regressions — these cases are exactly the
+  // kind of pattern that brittle regex would silently mis-classify.
+  // They lock down the new string-utility implementation against
+  // the most common false-positive risks.
+  // ─────────────────────────────────────────────────────────────────
+  describe('REGRESSION: no-regex parsers — false-positive guards', () => {
+    const opts = { publicOnly: false, withComments: false, includeImports: true };
+
+    // JS
+    test('JS: `class` keyword does NOT match `classroom = …`', () => {
+      const entries = tool._parseJS(['classroom = 1;'], opts);
+      // No signature should be emitted — `classroom` is a plain var, not a class.
+      expect(entries.filter(e => e.kind === 'signature').length).toBe(0);
+    });
+    test('JS: string literal containing `class` does NOT push a class frame', () => {
+      // Pre-fix the original regex `(stripped.match(/\{/g) || []).length` could
+      // be tripped by content inside strings if not pre-masked. The no-regex
+      // implementation masks strings before counting braces.
+      const entries = tool._parseJS([
+        'const x = "class Foo {";',
+      ], opts);
+      // Only the `const` line should produce something; no class signature.
+      const sigs = entries.filter(e => e.kind === 'signature').map(e => e.text);
+      expect(sigs.some(s => s.startsWith('class '))).toBe(false);
+    });
+    test('JS: `// foo` and `/* foo */` line/block comments still suppress signatures', () => {
+      const entries = tool._parseJS([
+        '// export function fake() {}',
+        '/* export function alsoFake() {} */',
+        'export function real() {}',
+      ], opts);
+      const sigs = entries.filter(e => e.kind === 'signature').map(e => e.text.trim());
+      expect(sigs).toEqual(['export function real() {}']);
+    });
+    test('JS: `require` as a substring inside another identifier is NOT an import', () => {
+      // E.g. `prerequires = []` or `xrequireY()` — neither should be classified
+      // as an import line by the require-call detector.
+      const entries = tool._parseJS([
+        'const xrequireY = makeIt();',
+      ], opts);
+      expect(entries.filter(e => e.kind === 'import').length).toBe(0);
+    });
+    test('JS: `==` after a global LHS does NOT trigger an assignment match', () => {
+      const entries = tool._parseJS([
+        'window.foo == bar;',
+      ], opts);
+      expect(entries.filter(e => e.kind === 'signature').length).toBe(0);
+    });
+
+    // C
+    test('C: `class` inside a string literal does NOT push a class signature', () => {
+      const entries = tool._parseC([
+        'const char* msg = "class is a keyword in C++";',
+      ], opts);
+      // The C parser is line-based and doesn't deeply track string state;
+      // this asserts the realistic case where the assignment isn't a class.
+      // The line shouldn't surface as a "class …" signature.
+      const sigs = entries.filter(e => e.kind === 'signature').map(e => e.text);
+      expect(sigs.some(s => s.trim().startsWith('class '))).toBe(false);
+    });
+    test('C: bare function CALL `foo(x, y);` is NOT a definition', () => {
+      const entries = tool._parseC(['  foo(1, 2);'], opts);
+      expect(entries.filter(e => e.kind === 'signature').length).toBe(0);
+    });
+
+    // Python
+    test('Python: `class` keyword does NOT match `classroom = 1`', () => {
+      const entries = tool._parsePython(['classroom = 1'], opts);
+      // It's a top-level data assignment, NOT a class signature.
+      const sigs = entries.filter(e => e.kind === 'signature').map(e => e.text);
+      expect(sigs.length).toBe(0);
+      const datas = entries.filter(e => e.kind === 'data');
+      expect(datas.length).toBe(1);
+    });
+    test('Python: `def` keyword on a line where it is NOT the leading token (e.g. `nodef(x):`) is not a function', () => {
+      // The word-boundary check in startsWithKeyword catches this case.
+      const entries = tool._parsePython(['nodef(x):'], opts);
+      expect(entries.filter(e => e.kind === 'signature').length).toBe(0);
+    });
+    test('Python: relative import `from . import foo` is captured', () => {
+      const entries = tool._parsePython(['from . import foo'], opts);
+      expect(entries.filter(e => e.kind === 'import').length).toBe(1);
+    });
+    test('Python: docstring closes correctly on a one-liner', () => {
+      const entries = tool._parsePython([
+        'def hello():',
+        '    """One-liner docstring."""',
+        '    return 1',
+      ], { ...opts, withComments: true });
+      const kinds = entries.map(e => e.kind);
+      expect(kinds).toContain('signature');
+      expect(kinds).toContain('comment');
+    });
+  });
 });

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

@@ -0,0 +1,252 @@
+/**
+ * Tests for FoundryWebSearchTool.
+ *
+ * The tool wraps a single aiService call. We stub aiService and verify:
+ *   1. parseParameters accepts both JSON and XML invocation forms
+ *   2. execute requires aiService injection + a non-empty query
+ *   3. successful search formats answer + citations + usage into a
+ *      readable `output` string for the agent
+ *   4. 503 (not provisioned) returns a friendly fallback message
+ *      with `notProvisioned: true` so callers can branch
+ *   5. webSearches=0 produces a warning so the agent knows to retry
+ *      with stronger wording
+ *   6. idempotency key is stable for same (agent, turn, query) and
+ *      different across agents / turns / queries
+ *   7. Errors don't leak the raw stack to the agent
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger, createMockConfig } from '../../__test-utils__/mockFactories.js';
+
+jest.unstable_mockModule('../../utilities/tagParser.js', () => ({
+  default: {
+    extractContent: jest.fn((content, tag) => {
+      const regex = new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, 'g');
+      const matches = [];
+      let match;
+      while ((match = regex.exec(content)) !== null) matches.push(match[1]);
+      return matches;
+    }),
+  },
+}));
+
+const { default: FoundryWebSearchTool } = await import('../foundryWebSearchTool.js');
+
+function makeTool({ aiService } = {}) {
+  const tool = new FoundryWebSearchTool(createMockConfig(), createMockLogger());
+  if (aiService !== undefined) tool.setAIService(aiService);
+  return tool;
+}
+
+const SAMPLE_OK_RESPONSE = {
+  answer: 'Node.js 22 is the current LTS as of May 2026.',
+  citations: [
+    { url: 'https://nodejs.org/releases', title: 'Releases', start: 0, end: 31 },
+    { url: 'https://github.com/nodejs/release', title: 'release schedule', start: 5, end: 12 },
+  ],
+  model: 'gpt-4o',
+  usage: { inputTokens: 22, outputTokens: 87, webSearches: 1 },
+};
+
+describe('FoundryWebSearchTool — constructor + metadata', () => {
+  test('id, name, version, async flag', () => {
+    const t = makeTool();
+    expect(t.id).toBe('foundry_web_search');
+    expect(t.name).toBe('Foundry Web Search (Grounded)');
+    expect(t.version).toBe('1.0.0');
+    expect(t.isAsync).toBe(true);
+    expect(t.requiresProject).toBe(false);
+  });
+
+  test('aiService starts null until setAIService is called', () => {
+    const t = makeTool();
+    expect(t.aiService).toBeNull();
+    const ai = { foundryWebSearch: jest.fn() };
+    t.setAIService(ai);
+    expect(t.aiService).toBe(ai);
+  });
+
+  test('getDescription mentions citations + cost + the alternative tool', () => {
+    const d = makeTool().getDescription();
+    expect(d).toMatch(/citation/i);
+    expect(d).toMatch(/cost/i);
+    expect(d).toMatch(/\bweb\b/);          // mentions the puppeteer `web` tool as alternative
+    expect(d).toMatch(/webSearches/);       // documents the usage field
+  });
+});
+
+describe('FoundryWebSearchTool — parseParameters', () => {
+  test('JSON form: { query, instructions, model }', () => {
+    const t = makeTool();
+    const out = t.parseParameters(JSON.stringify({
+      query: 'latest node version', model: 'gpt-4o', instructions: 'force search',
+    }));
+    expect(out).toEqual({ query: 'latest node version', model: 'gpt-4o', instructions: 'force search' });
+  });
+
+  test('JSON form nested in `parameters` key (standard agent shape)', () => {
+    const t = makeTool();
+    const out = t.parseParameters(JSON.stringify({
+      parameters: { query: 'hello world' },
+    }));
+    expect(out.query).toBe('hello world');
+  });
+
+  test('XML form: <query>…</query>', () => {
+    const t = makeTool();
+    const out = t.parseParameters('<query>find python</query>');
+    expect(out.query).toBe('find python');
+  });
+
+  test('XML form: includes optional model + instructions', () => {
+    const t = makeTool();
+    const out = t.parseParameters(
+      '<query>x</query><model>gpt-4o-mini</model><instructions>be brief</instructions>'
+    );
+    expect(out).toMatchObject({ query: 'x', model: 'gpt-4o-mini', instructions: 'be brief' });
+  });
+
+  test('missing query → null (execute will reject with a clear error)', () => {
+    const t = makeTool();
+    expect(t.parseParameters('<other>foo</other>').query).toBeNull();
+    expect(t.parseParameters('{}').query).toBeNull();
+  });
+
+  test('whitespace-only query is normalised to a trimmed empty (then null at exec time)', () => {
+    const t = makeTool();
+    expect(t.parseParameters('<query>   </query>').query).toBe('');
+  });
+});
+
+describe('FoundryWebSearchTool — execute success path', () => {
+  test('formats answer + citations + usage into output', async () => {
+    const aiService = { foundryWebSearch: jest.fn().mockResolvedValue(SAMPLE_OK_RESPONSE) };
+    const t = makeTool({ aiService });
+    const r = await t.execute({ query: 'node lts' }, { agentId: 'a1', sessionId: 's1' });
+    expect(r.success).toBe(true);
+    expect(r.output).toContain('Node.js 22 is the current LTS');
+    expect(r.output).toContain('Sources:');
+    expect(r.output).toContain('https://nodejs.org/releases');
+    expect(r.output).toContain('searches=1');
+    expect(r.answer).toBe(SAMPLE_OK_RESPONSE.answer);
+    expect(r.citations).toEqual(SAMPLE_OK_RESPONSE.citations);
+    expect(r.usage).toEqual(SAMPLE_OK_RESPONSE.usage);
+    expect(r.warning).toBeUndefined();
+  });
+
+  test('forwards instructions + model + sessionId + idempotencyKey to aiService', async () => {
+    const aiService = { foundryWebSearch: jest.fn().mockResolvedValue(SAMPLE_OK_RESPONSE) };
+    const t = makeTool({ aiService });
+    await t.execute(
+      { query: 'q', instructions: 'always search', model: 'gpt-4o-mini' },
+      { agentId: 'a1', sessionId: 'sess-x' },
+    );
+    const callArgs = aiService.foundryWebSearch.mock.calls[0];
+    expect(callArgs[0]).toBe('q');
+    expect(callArgs[1]).toMatchObject({
+      instructions: 'always search',
+      model: 'gpt-4o-mini',
+      sessionId: 'sess-x',
+    });
+    expect(typeof callArgs[1].idempotencyKey).toBe('string');
+    expect(callArgs[1].idempotencyKey.length).toBeGreaterThan(0);
+  });
+
+  test('webSearches=0 adds a `warning` field so the agent knows to retry', async () => {
+    const aiService = {
+      foundryWebSearch: jest.fn().mockResolvedValue({
+        ...SAMPLE_OK_RESPONSE,
+        usage: { ...SAMPLE_OK_RESPONSE.usage, webSearches: 0 },
+      }),
+    };
+    const t = makeTool({ aiService });
+    const r = await t.execute({ query: 'easy q' }, { agentId: 'a1' });
+    expect(r.success).toBe(true);
+    expect(r.warning).toMatch(/did not invoke|stronger wording|search the web/i);
+  });
+
+  test('empty citations renders "(No sources cited.)" in output', async () => {
+    const aiService = {
+      foundryWebSearch: jest.fn().mockResolvedValue({ ...SAMPLE_OK_RESPONSE, citations: [] }),
+    };
+    const r = await makeTool({ aiService }).execute({ query: 'q' }, { agentId: 'a1' });
+    expect(r.output).toMatch(/No sources cited/);
+  });
+});
+
+describe('FoundryWebSearchTool — execute error paths', () => {
+  test('no aiService injected → returns initialisation error (does not throw)', async () => {
+    const t = new FoundryWebSearchTool(createMockConfig(), createMockLogger());
+    const r = await t.execute({ query: 'x' }, {});
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/aiService reference missing/i);
+  });
+
+  test('missing query → returns 400-style error', async () => {
+    const aiService = { foundryWebSearch: jest.fn() };
+    const r = await makeTool({ aiService }).execute({}, { agentId: 'a1' });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/query is required/);
+    expect(aiService.foundryWebSearch).not.toHaveBeenCalled();
+  });
+
+  test('503 from backend → friendly fallback message + notProvisioned: true', async () => {
+    const err = Object.assign(
+      new Error('Web search isn\'t enabled on this Loxia deployment.'),
+      { status: 503 }
+    );
+    const aiService = { foundryWebSearch: jest.fn().mockRejectedValue(err) };
+    const r = await makeTool({ aiService }).execute({ query: 'q' }, { agentId: 'a1' });
+    expect(r.success).toBe(false);
+    expect(r.notProvisioned).toBe(true);
+    expect(r.output).toMatch(/web` tool/);  // suggests the puppeteer fallback
+  });
+
+  test('generic backend error → user-friendly output, no stack trace leak', async () => {
+    const aiService = {
+      foundryWebSearch: jest.fn().mockRejectedValue(new Error('upstream went sideways')),
+    };
+    const r = await makeTool({ aiService }).execute({ query: 'q' }, { agentId: 'a1' });
+    expect(r.success).toBe(false);
+    expect(r.output).toMatch(/Web search failed:/);
+    expect(r.output).not.toMatch(/at Object\.|\bnode:internal\b/);
+  });
+});
+
+describe('FoundryWebSearchTool — idempotency key derivation', () => {
+  test('same (agentId, turnId, query) produces identical key', () => {
+    const t = makeTool();
+    const ctx = { agentId: 'a1', turnId: 'turn-99' };
+    const k1 = t._buildIdempotencyKey(ctx, 'hello world');
+    const k2 = t._buildIdempotencyKey(ctx, 'hello world');
+    expect(k1).toBe(k2);
+    expect(k1).toMatch(/^fws-a1-/);
+  });
+
+  test('different agents → different keys', () => {
+    const t = makeTool();
+    const k1 = t._buildIdempotencyKey({ agentId: 'a1', turnId: 't' }, 'q');
+    const k2 = t._buildIdempotencyKey({ agentId: 'a2', turnId: 't' }, 'q');
+    expect(k1).not.toBe(k2);
+  });
+
+  test('different turns → different keys (refresh between turns)', () => {
+    const t = makeTool();
+    const k1 = t._buildIdempotencyKey({ agentId: 'a1', turnId: 't1' }, 'q');
+    const k2 = t._buildIdempotencyKey({ agentId: 'a1', turnId: 't2' }, 'q');
+    expect(k1).not.toBe(k2);
+  });
+
+  test('different queries → different keys', () => {
+    const t = makeTool();
+    const k1 = t._buildIdempotencyKey({ agentId: 'a', turnId: 't' }, 'q1');
+    const k2 = t._buildIdempotencyKey({ agentId: 'a', turnId: 't' }, 'q2');
+    expect(k1).not.toBe(k2);
+  });
+
+  test('falls back to "unknown" agent + timestamp turn when missing', () => {
+    const t = makeTool();
+    const k = t._buildIdempotencyKey({}, 'q');
+    expect(k).toMatch(/^fws-unknown-/);
+  });
+});