onbuzz 5.1.0 → 5.4.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__/openaiFunctionSchemas.mustHave.test.js

@@ -0,0 +1,37 @@
+import { describe, test, expect } from '@jest/globals';
+import { getToolSchemasForAgent, OPENAI_FUNCTION_SCHEMAS } from '../openaiFunctionSchemas.js';
+
+const names = (schemas) => schemas.map((s) => s.name);
+
+describe('getToolSchemasForAgent — must-have injection', () => {
+  test('empty / non-array capabilities → full catalog unchanged', () => {
+    expect(getToolSchemasForAgent([])).toBe(OPENAI_FUNCTION_SCHEMAS);
+    expect(getToolSchemasForAgent(undefined)).toBe(OPENAI_FUNCTION_SCHEMAS);
+  });
+
+  test('explicit list in AGENT mode gains taskmanager AND jobdone', () => {
+    const out = names(getToolSchemasForAgent(['web'], 'agent'));
+    expect(out).toContain('web');
+    expect(out).toContain('taskmanager');
+    expect(out).toContain('jobdone');
+  });
+
+  test('explicit list in CHAT mode gains taskmanager but NOT jobdone', () => {
+    const out = names(getToolSchemasForAgent(['web'], 'chat'));
+    expect(out).toContain('web');
+    expect(out).toContain('taskmanager');
+    expect(out).not.toContain('jobdone');
+  });
+
+  test('!taskmanager opt-out removes the forced schema', () => {
+    const out = names(getToolSchemasForAgent(['web', '!taskmanager'], 'agent'));
+    expect(out).not.toContain('taskmanager');
+    expect(out).toContain('jobdone');
+  });
+
+  test('does not invent schemas for capabilities that have none', () => {
+    const out = names(getToolSchemasForAgent(['definitely-not-a-tool'], 'chat'));
+    // only the real must-have (taskmanager) survives the schema filter
+    expect(out).toEqual(['taskmanager']);
+  });
+});

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

@@ -258,6 +258,96 @@ describe('UserPromptTool', () => {
     });
   });
 
+  describe('timeout estimation', () => {
+    test('closed (options-only) question is clamped up to the 2-min floor', () => {
+      expect(tool._estimateTimeoutMs([{ allowFreeText: false }])).toBe(2 * 60 * 1000);
+    });
+    test('open (free-text) question estimates 3 min', () => {
+      expect(tool._estimateTimeoutMs([{ message: 'Q?' }])).toBe(3 * 60 * 1000);
+      expect(tool._estimateTimeoutMs([{ allowFreeText: true }])).toBe(3 * 60 * 1000);
+    });
+    test('sums per question (2 open = 6 min)', () => {
+      expect(tool._estimateTimeoutMs([{}, {}])).toBe(6 * 60 * 1000);
+    });
+    test('mixed: one open (3) + one closed (1) = 4 min', () => {
+      expect(tool._estimateTimeoutMs([{ allowFreeText: true }, { allowFreeText: false }])).toBe(4 * 60 * 1000);
+    });
+    test('caps at 15 min for many questions', () => {
+      const many = Array.from({ length: 10 }, () => ({ allowFreeText: true }));
+      expect(tool._estimateTimeoutMs(many)).toBe(15 * 60 * 1000);
+    });
+    test('no questions → falls back to the default', () => {
+      expect(tool._estimateTimeoutMs([])).toBe(tool.timeout);
+      expect(tool._estimateTimeoutMs(undefined)).toBe(tool.timeout);
+    });
+  });
+
+  describe('timeout resolution precedence', () => {
+    const oneOpen = { questions: [{ message: 'Q?' }] };
+
+    test('explicit timeoutMs / timeout override wins', () => {
+      expect(tool._resolveTimeoutMs({ ...oneOpen, timeoutMs: 42000 })).toBe(42000);
+      expect(tool._resolveTimeoutMs({ ...oneOpen, timeout: 99000 })).toBe(99000);
+    });
+    test('config strategy "none" → null (no auto-timeout)', () => {
+      expect(tool._resolveTimeoutMs(oneOpen, { strategy: 'none' })).toBeNull();
+    });
+    test('config strategy "fixed" uses fixedMinutes', () => {
+      expect(tool._resolveTimeoutMs(oneOpen, { strategy: 'fixed', fixedMinutes: 10 })).toBe(10 * 60 * 1000);
+    });
+    test('config strategy "fixed" with a bad value → default', () => {
+      expect(tool._resolveTimeoutMs(oneOpen, { strategy: 'fixed', fixedMinutes: 'nope' })).toBe(tool.timeout);
+    });
+    test('default / "estimated" → estimate from questions', () => {
+      expect(tool._resolveTimeoutMs(oneOpen)).toBe(3 * 60 * 1000);
+      expect(tool._resolveTimeoutMs(oneOpen, { strategy: 'estimated' })).toBe(3 * 60 * 1000);
+    });
+  });
+
+  describe('execute wiring', () => {
+    function wire(agentMode = 'agent') {
+      const mockWs = { broadcastToSession: jest.fn() };
+      const mockPool = {
+        getAgent: jest.fn().mockResolvedValue({ id: 'agent-1', mode: agentMode }),
+        persistAgentState: jest.fn().mockResolvedValue(undefined),
+        addUserMessage: jest.fn().mockResolvedValue(undefined),
+      };
+      tool.setWebSocketManager(mockWs);
+      tool.setAgentPool(mockPool);
+      mockPromptService.createPromptRequest.mockReturnValue({
+        requestInfo: { requestId: 'req-1', message: null, questions: [{ message: 'Q?' }], timeoutAt: new Date().toISOString() },
+        promise: Promise.resolve({ response: { answers: [] } }),
+      });
+      return { mockPool };
+    }
+
+    test('passes the estimated timeout to createPromptRequest', async () => {
+      wire();
+      await tool.execute({ questions: [{ message: 'Q?' }] }, { agentId: 'agent-1', sessionId: 's' });
+      expect(mockPromptService.createPromptRequest).toHaveBeenCalledWith(
+        'agent-1', expect.anything(), { timeout: 3 * 60 * 1000 },
+      );
+    });
+
+    test('honors per-agent tool config (strategy none → null timeout)', async () => {
+      wire();
+      await tool.execute(
+        { questions: [{ message: 'Q?' }] },
+        { agentId: 'agent-1', sessionId: 's', toolConfig: { strategy: 'none' } },
+      );
+      expect(mockPromptService.createPromptRequest).toHaveBeenCalledWith(
+        'agent-1', expect.anything(), { timeout: null },
+      );
+    });
+
+    test('CHAT mode no longer queues a synthetic user message', async () => {
+      const { mockPool } = wire('chat');
+      const result = await tool.execute({ questions: [{ message: 'Q?' }] }, { agentId: 'agent-1', sessionId: 's' });
+      expect(result.success).toBe(true);
+      expect(mockPool.addUserMessage).not.toHaveBeenCalled();
+    });
+  });
+
   describe('setAgentPool', () => {
     test('should store agent pool', () => {
       const pool = { getAgent: jest.fn() };

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

@@ -0,0 +1,349 @@
+/**
+ * Tab-reuse / efficient-interaction fixes for the web tool.
+ *
+ * Background: a real customer session ("CTF explorer") re-opened a fresh tab
+ * (open-tab + url) on 62 of 72 interactive calls, reloading the chatbot every
+ * turn and wiping its conversation — because switch-tab couldn't carry actions
+ * and top-level actions errored ("must be executed within a tab context"). These
+ * tests lock in the fixes: switch-tab/top-level actions run on the open page
+ * WITHOUT reloading, plus the accessibility snapshot action and humanMode default.
+ *
+ * The browser is stubbed and pages are mocked (the convention in webTool.*.test).
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+
+// Make human-like delays instant + deterministic, and COUNT them so we can
+// prove pacing is applied only to genuine input actions (efficiency under
+// 'maximum' stealth).
+const humanWaitMock = jest.fn(async () => {});
+jest.unstable_mockModule('../../utilities/humanBehavior.js', () => ({
+  createHumanCursor: () => ({ click: async () => {}, moveTo: async () => {} }),
+  humanType: async () => {},
+  humanWait: humanWaitMock,
+  humanScroll: async () => {},
+  humanSubmit: async () => {},
+}));
+
+const { default: WebTool } = await import('../webTool.js');
+
+const logger = { info() {}, warn() {}, error() {}, debug() {} };
+
+/** Mock page that models a stateful chat: goto() reloads → wipes state. */
+function makeChatPage(snapshotTree) {
+  const state = { messages: [] };
+  let gotoCount = 0;
+  return {
+    state,
+    gotoCalls: () => gotoCount,
+    url: () => 'http://fixture.local/chat',
+    goto: async () => { gotoCount += 1; state.messages = []; return { status: () => 200 }; },
+    content: async () => '<html><body>chat</body></html>',
+    close: async () => {},
+    on: () => {},
+    setCookie: async () => {},
+    $: async () => ({}),
+    click: async () => {},
+    type: async () => {},
+    // evaluate('send …') appends a message (deterministic stand-in for typing+sending).
+    evaluate: async (_cb, script) => {
+      if (typeof script === 'string' && script.includes('send')) {
+        state.messages.push('m' + (state.messages.length + 1));
+        return state.messages.length;
+      }
+      if (typeof script === 'string' && script.includes('count')) return state.messages.length;
+      return null;
+    },
+    accessibility: {
+      snapshot: async () => snapshotTree ?? {
+        role: 'WebArea', name: '', children: [
+          { role: 'heading', name: 'Negotiator' },
+          { role: 'textbox', name: 'Message', value: 'draft text' },
+          { role: 'button', name: 'Send', disabled: false },
+          { role: 'button', name: 'Cancel', disabled: true },
+          { role: 'generic', name: '', children: [{ role: 'link', name: 'Help' }] },
+          { role: 'checkbox', name: 'Remember me', checked: false },
+        ],
+      },
+    },
+  };
+}
+
+function makeTabInfo(page, humanMode = false) {
+  return {
+    page, url: 'http://fixture.local/chat', name: 'chat', humanMode,
+    pageErrors: [], networkFailures: [], httpErrors: [], consoleMessages: [], lastActivity: 0,
+  };
+}
+
+/** A WebTool with the browser stubbed and one named tab seeded. */
+function seeded({ agentId = 'a1', name = 'chat', page = makeChatPage(), active = false, humanMode = false } = {}) {
+  const wt = new WebTool({}, logger);
+  wt.ensureBrowser = async () => {};
+  wt.browser = { isConnected: () => true, _stealthConfig: { stealthLevel: 'standard' } };
+  wt.agentTabs.set(agentId, new Map([[name, makeTabInfo(page, humanMode)]]));
+  if (active) wt.agentActiveTab.set(agentId, name);
+  return { wt, page, agentId, name };
+}
+
+const run = (wt, actions, agentId = 'a1') =>
+  wt.interactive(actions, { agentId, stealthLevel: 'standard', humanMode: false });
+
+beforeEach(() => jest.clearAllMocks());
+
+describe('switch-tab carries actions (no reload)', () => {
+  test('runs nestedActions on the open tab without navigating', async () => {
+    const { wt, page } = seeded();
+    const r = await run(wt, [{ type: 'switch-tab', name: 'chat', nestedActions: [{ type: 'evaluate', script: 'send' }] }]);
+    expect(r.success).toBe(true);
+    expect(page.gotoCalls()).toBe(0);              // NO reload
+    expect(page.state.messages).toEqual(['m1']);   // action ran on the live page
+    expect(r.results[0].action).toBe('switch-tab');
+    expect(r.results[0].results[0].action).toBe('evaluate');
+    expect(wt.agentActiveTab.get('a1')).toBe('chat');
+  });
+
+  test('accepts the `actions` alias and reports failed actions', async () => {
+    const { wt } = seeded();
+    const r = await run(wt, [{ type: 'switch-tab', name: 'chat', actions: [{ type: 'evaluate' /* no script → fails */ }] }]);
+    expect(r.results[0].success).toBe(false);
+    expect(r.results[0].warning).toMatch(/1 of 1 action/);
+  });
+
+  test('bare switch-tab (no actions) just switches + sets active tab', async () => {
+    const { wt } = seeded();
+    const r = await run(wt, [{ type: 'switch-tab', name: 'chat' }]);
+    expect(r.results[0].message).toMatch(/Switched to tab 'chat'/);
+    expect(wt.agentActiveTab.get('a1')).toBe('chat');
+  });
+
+  test('switch-tab to an unknown tab fails gracefully (no throw to caller)', async () => {
+    const { wt } = seeded();
+    const r = await run(wt, [{ type: 'switch-tab', name: 'ghost' }]);
+    expect(r.results[0].success).toBe(false);
+    expect(r.results[0].error).toMatch(/not found/);
+  });
+});
+
+describe('top-level actions run on the active tab', () => {
+  test('a bare action targets the active tab (no reload, no context error)', async () => {
+    const { wt, page } = seeded({ active: true });
+    const r = await run(wt, [{ type: 'evaluate', script: 'send' }]);
+    expect(r.results[0].action).toBe('evaluate');
+    expect(r.results[0].success).toBe(true);
+    expect(page.gotoCalls()).toBe(0);
+    expect(page.state.messages).toEqual(['m1']);
+  });
+
+  test('with no active tab, returns a helpful error (not the old cryptic one)', async () => {
+    const { wt } = seeded({ active: false });
+    const r = await run(wt, [{ type: 'evaluate', script: 'send' }], 'noTabAgent');
+    expect(r.results[0].success).toBe(false);
+    expect(r.results[0].error).toMatch(/no active tab/i);
+    expect(r.results[0].error).not.toMatch(/must be executed within a tab context/);
+  });
+});
+
+describe('open-tab / close-tab active-tab tracking', () => {
+  test('open-tab on an existing tab reloads (url) and sets it active', async () => {
+    const { wt, page } = seeded();
+    const r = await run(wt, [{ type: 'open-tab', name: 'chat', url: 'http://fixture.local/chat', nestedActions: [{ type: 'evaluate', script: 'send' }] }]);
+    expect(r.results[0].success).toBe(true);
+    expect(page.gotoCalls()).toBe(1);              // url present → reload (the OLD pattern)
+    expect(wt.agentActiveTab.get('a1')).toBe('chat');
+  });
+
+  test('close-tab clears the active tab', async () => {
+    const { wt } = seeded({ active: true });
+    await run(wt, [{ type: 'close-tab', name: 'chat' }]);
+    expect(wt.agentActiveTab.has('a1')).toBe(false);
+  });
+
+  test('close-tab on a non-active tab leaves the active tab intact', async () => {
+    const { wt } = seeded({ active: true }); // active = 'chat'
+    wt.agentTabs.get('a1').set('other', makeTabInfo(makeChatPage()));
+    await run(wt, [{ type: 'close-tab', name: 'other' }]);
+    expect(wt.agentActiveTab.get('a1')).toBe('chat'); // unchanged
+  });
+
+  test('list-tabs reports the open tabs', async () => {
+    const { wt } = seeded({ active: true });
+    const r = await run(wt, [{ type: 'list-tabs' }]);
+    expect(r.results[0].success).not.toBe(false);
+  });
+});
+
+describe('snapshot (accessibility) action', () => {
+  test('returns interactive elements as role+name (and headings)', async () => {
+    const { wt } = seeded({ active: true });
+    const r = await run(wt, [{ type: 'snapshot' }]);
+    const snap = r.results[0];
+    expect(snap.success).toBe(true);
+    const roles = snap.elements.map(e => e.role);
+    expect(roles).toEqual(expect.arrayContaining(['heading', 'textbox', 'button', 'link', 'checkbox']));
+    expect(snap.elements.find(e => e.role === 'button').name).toBe('Send');
+    expect(snap.elements.find(e => e.role === 'checkbox').checked).toBe(false);
+    expect(snap.elements.find(e => e.role === 'textbox').value).toBe('draft text'); // value branch
+    expect(snap.elements.find(e => e.name === 'Cancel').disabled).toBe(true);        // disabled branch
+    expect(snap.elementCount).toBe(roles.length);
+  });
+
+  test('accessibility-snapshot alias + limit truncation', async () => {
+    const big = { role: 'WebArea', name: '', children: Array.from({ length: 5 }, (_, i) => ({ role: 'button', name: 'b' + i })) };
+    const { wt } = seeded({ active: true, page: makeChatPage(big) });
+    const r = await run(wt, [{ type: 'accessibility-snapshot', limit: 2 }]);
+    expect(r.results[0].elements).toHaveLength(2);
+    expect(r.results[0].truncated).toBe(3);
+  });
+
+  test('snapshot failure is reported, not thrown', async () => {
+    const page = makeChatPage();
+    page.accessibility.snapshot = async () => { throw new Error('no a11y'); };
+    const { wt } = seeded({ active: true, page });
+    const r = await run(wt, [{ type: 'snapshot' }]);
+    expect(r.results[0].success).toBe(false);
+    expect(r.results[0].error).toMatch(/Snapshot failed: no a11y/);
+  });
+});
+
+describe('_runActionsOnTab error collection', () => {
+  test('attaches js/network/http/console errors per action', async () => {
+    const { wt } = seeded();
+    const tab = makeTabInfo(makeChatPage());
+    wt.executeTabAction = async (page, action, tabInfo) => {
+      tabInfo.pageErrors.push({ message: 'boom' });
+      tabInfo.networkFailures.push({ method: 'GET', url: 'x', errorText: 'fail' });
+      tabInfo.httpErrors.push({ method: 'GET', url: 'y', status: 500 });
+      tabInfo.consoleMessages.push({ type: 'error', text: 'cerr' });
+      return { success: true };
+    };
+    const { results, failed } = await wt._runActionsOnTab(tab, [{ type: 'evaluate' }], {});
+    expect(failed).toBe(0);
+    expect(results[0].jsErrors).toEqual(['boom']);
+    expect(results[0].networkFailures[0]).toMatch(/GET x → fail/);
+    expect(results[0].httpErrors[0]).toMatch(/→ 500/);
+    expect(results[0].consoleErrors).toEqual(['cerr']);
+  });
+
+  test('a thrown action is captured as a failed result (not propagated)', async () => {
+    const { wt } = seeded();
+    const tab = makeTabInfo(makeChatPage());
+    wt.executeTabAction = async () => { throw new Error('kaboom'); };
+    const { results, failed } = await wt._runActionsOnTab(tab, [{ type: 'x' }], {});
+    expect(failed).toBe(1);
+    expect(results[0]).toMatchObject({ action: 'x', success: false, error: 'kaboom' });
+  });
+
+  test('humanMode tab waits between actions (branch coverage)', async () => {
+    const { wt } = seeded();
+    const tab = { ...makeTabInfo(makeChatPage()), humanMode: true };
+    wt.executeTabAction = async () => ({ success: true });
+    const { results } = await wt._runActionsOnTab(tab, [{ type: 'a' }, { type: 'b' }], {});
+    expect(results).toHaveLength(2);
+  });
+});
+
+describe('getDescription documents the efficient-interaction pattern', () => {
+  test('mentions snapshot + tab reuse + avoiding reload', () => {
+    const d = new WebTool({}, logger).getDescription();
+    expect(d).toMatch(/snapshot/);
+    expect(d).toMatch(/switch-tab/);
+    expect(d).toMatch(/RELOADS the page|avoids reloading/i);
+  });
+});
+
+describe('humanMode default tied to stealth (execute → interactive)', () => {
+  async function captureHumanMode(params) {
+    const wt = new WebTool({}, logger);
+    wt.ensureBrowser = async () => {};
+    wt.browser = { isConnected: () => true, _stealthConfig: { stealthLevel: params.stealthLevel || 'standard' } };
+    let captured;
+    wt.interactive = async (_actions, opts) => { captured = opts; return { success: true, results: [] }; };
+    await wt.execute({ operation: 'interactive', actions: [], ...params }, { agentId: 'a1' });
+    return captured.humanMode;
+  }
+  test("'standard' stealth → humanMode off (fast)", async () => {
+    expect(await captureHumanMode({ stealthLevel: 'standard' })).toBe(false);
+  });
+  test("'maximum' stealth → humanMode on", async () => {
+    expect(await captureHumanMode({ stealthLevel: 'maximum' })).toBe(true);
+  });
+  test('explicit humanMode:false wins even at maximum', async () => {
+    expect(await captureHumanMode({ stealthLevel: 'maximum', humanMode: false })).toBe(false);
+  });
+});
+
+describe('efficient under maximum stealth (humanMode)', () => {
+  test('tab reuse still avoids reloads with humanMode on', async () => {
+    const { wt, page } = seeded({ humanMode: true });
+    await run(wt, [{ type: 'switch-tab', name: 'chat', nestedActions: [{ type: 'type', selector: '#input', text: 'hi' }, { type: 'click', selector: '#submit' }] }]);
+    expect(page.gotoCalls()).toBe(0); // reuse, not reload — even under stealth
+  });
+
+  test('human pacing applies to input actions but NOT to observation actions', async () => {
+    const { wt } = seeded();
+    const tab = { ...makeTabInfo(makeChatPage(), true) };
+    wt.executeTabAction = async () => ({ success: true });
+    await wt._runActionsOnTab(tab, [
+      { type: 'type' }, { type: 'click' },        // paced (2)
+      { type: 'snapshot' }, { type: 'evaluate' }, // NOT paced
+      { type: 'extract-text' }, { type: 'wait-for' },
+    ], {});
+    // Only the 2 genuine input actions incur a human delay → no dead time on reads.
+    expect(humanWaitMock).toHaveBeenCalledTimes(2);
+  });
+
+  test('openTab reuse loop paces only input actions too', async () => {
+    const { wt } = seeded({ humanMode: true });
+    humanWaitMock.mockClear();
+    // open-tab reuse with url runs the openTab nested loop under humanMode.
+    await wt.interactive([{
+      type: 'open-tab', name: 'chat', url: 'http://fixture.local/chat',
+      nestedActions: [{ type: 'click', selector: '#submit' }, { type: 'evaluate', script: 'send' }],
+    }], { agentId: 'a1', stealthLevel: 'maximum', humanMode: true });
+    const actionDelays = humanWaitMock.mock.calls.filter(c => c[0] === 'action').length;
+    expect(actionDelays).toBe(1); // click only — evaluate (read) not paced
+  });
+
+  test('opening a NEW tab paces only input actions in its nested loop', async () => {
+    const { wt } = seeded();                 // a1 already has 'chat'
+    wt.createPage = async () => ({ page: makeChatPage(), cursor: null });
+    humanWaitMock.mockClear();
+    await wt.interactive([{
+      type: 'open-tab', name: 'fresh',       // no url → exercises the new-tab nested loop
+      nestedActions: [{ type: 'click', selector: '#submit' }, { type: 'evaluate', script: 'send' }],
+    }], { agentId: 'a1', stealthLevel: 'maximum', humanMode: true });
+    const actionDelays = humanWaitMock.mock.calls.filter(c => c[0] === 'action').length;
+    expect(actionDelays).toBe(1); // click only
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CONTROLLED EXPERIMENT — proves the fix: a 5-turn chatbot conversation.
+// OLD pattern (open-tab + url each turn) reloads every turn and loses state.
+// NEW pattern (open once, then switch-tab + actions) preserves the whole chat.
+// Same real dispatch code; only the call pattern differs.
+// ─────────────────────────────────────────────────────────────────────────────
+describe('EXPERIMENT: multi-turn chatbot — old vs new call pattern', () => {
+  const TURNS = 5;
+
+  test('OLD pattern: reloads every turn, conversation never accumulates', async () => {
+    const { wt, page } = seeded({ agentId: 'old' });
+    for (let i = 0; i < TURNS; i++) {
+      await run(wt, [{ type: 'open-tab', name: 'chat', url: 'http://fixture.local/chat', nestedActions: [{ type: 'evaluate', script: 'send' }] }], 'old');
+    }
+    expect(page.gotoCalls()).toBe(TURNS);          // 5 reloads
+    expect(page.state.messages).toHaveLength(1);    // state wiped each turn → only the last survives
+  });
+
+  test('NEW pattern: opens once, conversation accumulates across all turns', async () => {
+    const { wt, page } = seeded({ agentId: 'new' });
+    // Turn 1: open once (load the page).
+    await run(wt, [{ type: 'open-tab', name: 'chat', url: 'http://fixture.local/chat', nestedActions: [{ type: 'evaluate', script: 'send' }] }], 'new');
+    // Turns 2..N: reuse the open tab, no url → no reload.
+    for (let i = 1; i < TURNS; i++) {
+      await run(wt, [{ type: 'switch-tab', name: 'chat', nestedActions: [{ type: 'evaluate', script: 'send' }] }], 'new');
+    }
+    expect(page.gotoCalls()).toBe(1);               // ONE load for the whole conversation
+    expect(page.state.messages).toHaveLength(TURNS); // full 5-turn conversation preserved
+  });
+});