@browserbridge/bbx 1.0.1 → 1.2.0

package/packages/mcp-server/src/handlers.js

@@ -1,304 +1,69 @@
 // @ts-check
 
+import os from 'node:os';
+import { DEFAULT_CONSOLE_LIMIT, createRuntimeContext } from '../../protocol/src/index.js';
+import { collectSetupStatus } from '../../agent-client/src/setup-status.js';
 import {
-  bridgeMethodNeedsTab,
-  DEFAULT_CONSOLE_LIMIT,
-  DEFAULT_MAX_HTML_LENGTH,
-  DEFAULT_NETWORK_LIMIT,
-  estimateJsonPayloadCost,
-  getBudgetPreset,
-  getErrorRecovery,
-  isBudgetPresetName,
-  METHODS,
-  summarizeBatchErrorItem,
-  summarizeBatchResponseItem,
-} from '../../protocol/src/index.js';
-import {
+  callBridgeTool,
+  createToolResult,
   getDoctorReport,
-  requestBridge,
-  resolveRef,
-  withBridgeClient,
-} from '../../agent-client/src/runtime.js';
-import { annotateBridgeSummary, summarizeBridgeResponse } from '../../agent-client/src/subagent.js';
-
-/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
-/** @typedef {import('../../protocol/src/types.js').BridgeResponse} BridgeResponse */
-
-const REQUEST_SOURCE = 'mcp';
-
-/**
- * @typedef {{
- *   content: Array<{ type: 'text', text: string }>,
- *   structuredContent: Record<string, unknown>,
- *   isError?: boolean
- * }} ToolResult
- */
-
-/**
- * @param {string} summary
- * @param {Record<string, unknown>} [structuredContent={}]
- * @param {boolean} [isError=false]
- * @returns {ToolResult}
- */
-function createToolResult(summary, structuredContent = {}, isError = false) {
-  const toolResult = {
-    content: [{ type: /** @type {'text'} */ ('text'), text: summary }],
-    structuredContent,
-    ...(isError ? { isError: true } : {}),
-  };
-  const delivered = estimateJsonPayloadCost(toolResult);
-  return {
-    ...toolResult,
-    structuredContent: {
-      ...structuredContent,
-      deliveredBytes: delivered.bytes,
-      deliveredTokens: delivered.approxTokens,
-      deliveredCostClass: delivered.costClass,
-    },
-  };
-}
-
-/**
- * @param {BridgeResponse} response
- * @param {string} [method]
- * @returns {ToolResult}
- */
-function summarizeToolResponse(response, method) {
-  const summary = annotateBridgeSummary(summarizeBridgeResponse(response, method), response);
-  return createToolResult(summary.summary, summary, !summary.ok);
-}
-
-/**
- * @param {unknown} error
- * @returns {ToolResult}
- */
-function summarizeToolError(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  return createToolResult(
-    `ERROR: ${message}`,
-    {
-      ok: false,
-      evidence: null,
-    },
-    true
-  );
-}
-
-/**
- * @param {(client: import('../../agent-client/src/client.js').BridgeClient) => Promise<ToolResult>} callback
- * @returns {Promise<ToolResult>}
- */
-async function withToolClient(callback) {
-  try {
-    return await withBridgeClient(callback);
-  } catch (error) {
-    return summarizeToolError(error);
-  }
-}
-
-/**
- * @param {import('../../agent-client/src/client.js').BridgeClient} client
- * @param {{ elementRef?: string | undefined, selector?: string | undefined }} input
- * @param {number | null | undefined} [tabId]
- * @returns {Promise<string>}
- */
-async function resolveToolRef(client, input, tabId = null) {
-  if (typeof input.elementRef === 'string' && input.elementRef) {
-    return input.elementRef;
-  }
-  if (typeof input.selector === 'string' && input.selector) {
-    return resolveRef(client, input.selector, tabId, REQUEST_SOURCE);
-  }
-  throw new Error('Provide either elementRef or selector.');
-}
-
-/**
- * @param {unknown} value
- * @returns {'quick' | 'normal' | 'deep' | null}
- */
-function getBudgetPresetName(value) {
-  return isBudgetPresetName(value) ? value : null;
-}
-
-/**
- * Infer a budget preset from selector specificity when the caller hasn't
- * provided an explicit budgetPreset.
- *
- * - ID selectors (#foo) or single element refs -> quick
- * - Class / tag / attribute selectors -> normal
- * - Universal (*), deeply nested, or missing selector -> deep
- *
- * @param {{ budgetPreset?: unknown, selector?: unknown, elementRef?: unknown }} args
- * @returns {'quick' | 'normal' | 'deep' | null}
- */
-function inferBudgetFromSelector(args) {
-  if (getBudgetPresetName(args.budgetPreset)) return null; // explicit preset wins
-  if (typeof args.elementRef === 'string' && args.elementRef) return 'quick';
-  const sel = typeof args.selector === 'string' ? args.selector.trim() : '';
-  if (!sel || sel === '*' || sel === 'body') return null; // keep default
-  if (/^#[\w-]+$/.test(sel)) return 'quick';
-  if ((sel.match(/\s/g) || []).length >= 3) return 'deep';
-  return 'normal';
-}
-
-/**
- * @param {{ budgetPreset?: unknown }} args
- * @returns {number | null}
- */
-function getToolTokenBudget(args) {
-  const presetName = getBudgetPresetName(args.budgetPreset);
-  return presetName ? getBudgetPreset(presetName).tokenBudget : null;
-}
-
-/**
- * @template {{ budgetPreset?: unknown, maxNodes?: unknown, maxDepth?: unknown, textBudget?: unknown }} T
- * @param {T} args
- * @returns {T}
- */
-function applyTreeBudgetPreset(args) {
-  const presetName = getBudgetPresetName(args.budgetPreset);
-  if (!presetName) {
-    return args;
-  }
-  const preset = getBudgetPreset(presetName);
-  return /** @type {T} */ ({
-    ...args,
-    maxNodes: args.maxNodes ?? preset.maxNodes,
-    maxDepth: args.maxDepth ?? preset.maxDepth,
-    textBudget: args.textBudget ?? preset.textBudget,
-  });
-}
-
-/**
- * @template {{ budgetPreset?: unknown, textBudget?: unknown }} T
- * @param {T} args
- * @returns {T}
- */
-function applyTextBudgetPreset(args) {
-  const presetName = getBudgetPresetName(args.budgetPreset);
-  if (!presetName) {
-    return args;
-  }
-  const preset = getBudgetPreset(presetName);
-  return /** @type {T} */ ({
-    ...args,
-    textBudget: args.textBudget ?? preset.textBudget,
-  });
-}
-
-/**
- * @template {{ budgetPreset?: unknown, limit?: unknown }} T
- * @param {T} args
- * @param {{ quick: number, normal: number, deep: number }} defaults
- * @returns {T}
- */
-function applyLimitBudgetPreset(args, defaults) {
-  const presetName = getBudgetPresetName(args.budgetPreset);
-  if (!presetName) {
-    return args;
-  }
-  return /** @type {T} */ ({
-    ...args,
-    limit: args.limit ?? defaults[presetName],
-  });
-}
-
-/**
- * @template {{ budgetPreset?: unknown, maxLength?: unknown }} T
- * @param {T} args
- * @returns {T}
- */
-function applyHtmlBudgetPreset(args) {
-  const presetName = getBudgetPresetName(args.budgetPreset);
-  if (!presetName) {
-    return args;
-  }
-  const maxLengthByPreset = {
-    quick: 600,
-    normal: DEFAULT_MAX_HTML_LENGTH,
-    deep: 6000,
-  };
-  return /** @type {T} */ ({
-    ...args,
-    maxLength: args.maxLength ?? maxLengthByPreset[presetName],
-  });
-}
-
-/**
- * Call requestBridge and, on a retriable error, wait and retry once.
- * Logs retries to stderr so they are visible in MCP server output.
- *
- * @param {import('../../agent-client/src/client.js').BridgeClient} client
- * @param {BridgeMethod} method
- * @param {Record<string, unknown>} params
- * @param {{ tabId?: number | null, source?: import('../../protocol/src/types.js').BridgeRequestSource, tokenBudget?: number | null }} options
- * @returns {Promise<BridgeResponse>}
- */
-async function requestBridgeWithRetry(client, method, params, options) {
-  const response = await requestBridge(client, method, params, options);
-  const recovery = !response.ok && response.error ? getErrorRecovery(response.error.code) : null;
-  if (!response.ok && recovery?.retry) {
-    const delay = recovery.retryAfterMs ?? 1000;
-    process.stderr.write(
-      `[bbx-mcp] Retrying ${method} after ${delay}ms (${response.error.code})\n`
-    );
-    await new Promise((r) => setTimeout(r, delay));
-    return requestBridge(client, method, params, options);
-  }
-  return response;
-}
-
-/**
- * @param {BridgeMethod} method
- * @param {Record<string, unknown>} [params={}]
- * @param {{ tabId?: number | null, summaryMethod?: string, tokenBudget?: number | null }} [options]
- * @returns {Promise<ToolResult>}
- */
-async function callBridgeTool(method, params = {}, options = {}) {
-  return withToolClient(async (client) => {
-    const response = await requestBridgeWithRetry(client, method, params, {
-      tabId: options.tabId ?? null,
-      source: REQUEST_SOURCE,
-      tokenBudget: options.tokenBudget ?? null,
-    });
-    return summarizeToolResponse(response, options.summaryMethod || method);
-  });
-}
-
-/**
- * @typedef {{ ref: boolean, method: BridgeMethod, params: (args: Record<string, unknown>, ref?: string) => Record<string, unknown> }} ToolAction
- */
-
-/**
- * Generic dispatcher for table-driven tool handlers. Each action entry
- * declares a bridge method, whether it needs an element ref, and a function
- * mapping args (and optional ref) to bridge params.
- *
- * @param {Record<string, ToolAction>} actions
- * @param {Record<string, unknown> & { action: string }} args
- * @param {string} toolName
- * @returns {Promise<ToolResult>}
- */
-async function dispatchToolAction(actions, args, toolName) {
-  const entry = actions[args.action];
-  if (!entry) return summarizeToolError(`Unsupported ${toolName} action "${args.action}".`);
-  return withToolClient(async (client) => {
-    const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
-    const ref = entry.ref
-      ? await resolveToolRef(
-          client,
-          /** @type {{ elementRef?: string, selector?: string }} */ (args),
-          requestedTabId
-        )
-      : undefined;
-    const response = await requestBridgeWithRetry(client, entry.method, entry.params(args, ref), {
-      tabId: requestedTabId,
-      source: REQUEST_SOURCE,
-      tokenBudget: getToolTokenBudget(/** @type {{ budgetPreset?: unknown }} */ (args)),
-    });
-    return summarizeToolResponse(response, entry.method);
-  });
-}
+  getToolTokenBudget,
+  applyLimitBudgetPreset,
+  summarizeToolError,
+  summarizeToolResponse,
+  withToolClient,
+  REQUEST_SOURCE,
+} from './handlers-utils.js';
+
+export {
+  createToolResult,
+  summarizeToolError,
+  summarizeToolResponse,
+  withToolClient,
+  resolveToolRef,
+  getBudgetPresetName,
+  inferBudgetFromSelector,
+  getToolTokenBudget,
+  applyTreeBudgetPreset,
+  applyTextBudgetPreset,
+  applyLimitBudgetPreset,
+  applyHtmlBudgetPreset,
+  requestBridgeWithRetry,
+  callBridgeTool,
+  dispatchToolAction,
+  REQUEST_SOURCE,
+} from './handlers-utils.js';
+
+export {
+  DOM_ACTIONS,
+  STYLES_LAYOUT_ACTIONS,
+  PATCH_ACTIONS,
+  handleDomTool,
+  handleStylesLayoutTool,
+  handlePatchTool,
+} from './handlers-dom.js';
+
+export { NAVIGATION_ACTIONS, handleTabsTool, handleNavigationTool } from './handlers-navigation.js';
+
+export {
+  CAPTURE_ACTIONS,
+  INPUT_ACTION_METHODS,
+  handleCaptureTool,
+  handleInputTool,
+} from './handlers-capture.js';
+
+export {
+  PAGE_ACTIONS,
+  handlePageTool,
+  handleBatchTool,
+  handleRawCallTool,
+  handleInvestigateTool,
+} from './handlers-page.js';
+
+/** @typedef {import('./handlers-utils.js').ToolAction} ToolAction */
+/** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
+
+const HOME_DIR = os.homedir();
 
 /**
  * @returns {Promise<ToolResult>}
@@ -320,583 +85,10 @@ export async function handleStatusTool() {
 }
 
 /**
- * @param {{ action: string, url?: string, active?: boolean, tabId?: number }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handleTabsTool(args) {
-  if (args.action === 'list') {
-    return callBridgeTool('tabs.list');
-  }
-  if (args.action === 'create') {
-    return callBridgeTool('tabs.create', {
-      url: args.url,
-      active: args.active,
-    });
-  }
-  if (args.action === 'close') {
-    if (typeof args.tabId !== 'number') {
-      return summarizeToolError('tabId is required for tabs.close.');
-    }
-    return callBridgeTool('tabs.close', { tabId: args.tabId });
-  }
-  return summarizeToolError(`Unsupported tabs action "${args.action}".`);
-}
-
-/**
-/** @type {Record<string, ToolAction>} */
-export const DOM_ACTIONS = {
-  query: {
-    ref: false,
-    method: 'dom.query',
-    params: (a) => ({
-      selector: a.selector || 'body',
-      withinRef: a.withinRef,
-      maxNodes: a.maxNodes,
-      maxDepth: a.maxDepth,
-      textBudget: a.textBudget,
-      includeBbox: a.includeBbox,
-      attributeAllowlist: a.attributeAllowlist,
-    }),
-  },
-  describe: {
-    ref: true,
-    method: 'dom.describe',
-    params: (_, r) => ({ elementRef: r }),
-  },
-  text: {
-    ref: true,
-    method: 'dom.get_text',
-    params: (a, r) => ({ elementRef: r, textBudget: a.textBudget }),
-  },
-  attributes: {
-    ref: true,
-    method: 'dom.get_attributes',
-    params: (a, r) => ({ elementRef: r, attributes: a.attributes || [] }),
-  },
-  wait: {
-    ref: false,
-    method: 'dom.wait_for',
-    params: (a) => ({
-      selector: a.selector,
-      text: a.text,
-      state: a.state,
-      timeoutMs: a.timeoutMs,
-    }),
-  },
-  find_text: {
-    ref: false,
-    method: 'dom.find_by_text',
-    params: (a) => ({
-      text: a.text,
-      exact: a.exact,
-      selector: a.selector,
-      maxResults: a.maxResults,
-    }),
-  },
-  find_role: {
-    ref: false,
-    method: 'dom.find_by_role',
-    params: (a) => ({
-      role: a.role,
-      name: a.name,
-      selector: a.selector,
-      maxResults: a.maxResults,
-    }),
-  },
-  html: {
-    ref: true,
-    method: 'dom.get_html',
-    params: (a, r) => ({
-      elementRef: r,
-      outer: a.outer,
-      maxLength: a.maxLength,
-    }),
-  },
-  accessibility_tree: {
-    ref: false,
-    method: 'dom.get_accessibility_tree',
-    params: (a) => ({ maxNodes: a.maxNodes, maxDepth: a.maxDepth }),
-  },
-};
-
-/**
- * @param {{ action: string, selector?: string, elementRef?: string, withinRef?: string, maxNodes?: number, maxDepth?: number, textBudget?: number, includeBbox?: boolean, attributeAllowlist?: string[], attributes?: string[], text?: string, exact?: boolean, maxResults?: number, role?: string, name?: string, state?: string, timeoutMs?: number, outer?: boolean, maxLength?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handleDomTool(args) {
-  if (args.action === 'query' || args.action === 'accessibility_tree') {
-    const inferred = inferBudgetFromSelector(args);
-    const withBudget = inferred ? { ...args, budgetPreset: args.budgetPreset ?? inferred } : args;
-    return dispatchToolAction(DOM_ACTIONS, applyTreeBudgetPreset(withBudget), 'DOM');
-  }
-  if (args.action === 'text') {
-    return dispatchToolAction(DOM_ACTIONS, applyTextBudgetPreset(args), 'DOM');
-  }
-  if (args.action === 'html') {
-    return dispatchToolAction(DOM_ACTIONS, applyHtmlBudgetPreset(args), 'DOM');
-  }
-  return dispatchToolAction(DOM_ACTIONS, args, 'DOM');
-}
-
-/** @type {Record<string, ToolAction>} */
-export const STYLES_LAYOUT_ACTIONS = {
-  computed: {
-    ref: true,
-    method: 'styles.get_computed',
-    params: (a, r) => ({ elementRef: r, properties: a.properties }),
-  },
-  matched_rules: {
-    ref: true,
-    method: 'styles.get_matched_rules',
-    params: (_, r) => ({ elementRef: r }),
-  },
-  box_model: {
-    ref: true,
-    method: 'layout.get_box_model',
-    params: (_, r) => ({ elementRef: r }),
-  },
-  hit_test: {
-    ref: false,
-    method: 'layout.hit_test',
-    params: (a) => ({ x: a.x, y: a.y }),
-  },
-};
-
-/**
- * @param {{ action: string, elementRef?: string, selector?: string, properties?: string[], x?: number, y?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handleStylesLayoutTool(args) {
-  return dispatchToolAction(STYLES_LAYOUT_ACTIONS, args, 'styles/layout');
-}
-
-/** @type {Record<string, { method: BridgeMethod, params: (a: Record<string, unknown>) => Record<string, unknown> }>} */
-export const PAGE_ACTIONS = {
-  state: { method: 'page.get_state', params: () => ({}) },
-  evaluate: {
-    method: 'page.evaluate',
-    params: (a) => ({
-      expression: a.expression,
-      awaitPromise: a.awaitPromise,
-      timeoutMs: a.timeoutMs,
-      returnByValue: a.returnByValue,
-    }),
-  },
-  console: {
-    method: 'page.get_console',
-    params: (a) => ({ level: a.level, clear: a.clear, limit: a.limit }),
-  },
-  wait_for_load: {
-    method: 'page.wait_for_load_state',
-    params: (a) => ({ timeoutMs: a.timeoutMs }),
-  },
-  storage: {
-    method: 'page.get_storage',
-    params: (a) => ({ type: a.type, keys: a.keys }),
-  },
-  text: {
-    method: 'page.get_text',
-    params: (a) => ({ textBudget: a.textBudget }),
-  },
-  network: {
-    method: 'page.get_network',
-    params: (a) => ({
-      clear: a.clear,
-      limit: a.limit,
-      urlPattern: a.urlPattern,
-    }),
-  },
-  performance: { method: 'performance.get_metrics', params: () => ({}) },
-};
-
-/**
- * @param {{ action: string, expression?: string, awaitPromise?: boolean, timeoutMs?: number, returnByValue?: boolean, level?: string, clear?: boolean, limit?: number, type?: string, keys?: string[], textBudget?: number, urlPattern?: string, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handlePageTool(args) {
-  let normalizedArgs = args;
-  if (args.action === 'text') {
-    normalizedArgs = applyTextBudgetPreset(args);
-  } else if (args.action === 'console') {
-    normalizedArgs = applyLimitBudgetPreset(args, {
-      quick: 10,
-      normal: DEFAULT_CONSOLE_LIMIT,
-      deep: 100,
-    });
-  } else if (args.action === 'network') {
-    normalizedArgs = applyLimitBudgetPreset(args, {
-      quick: 10,
-      normal: DEFAULT_NETWORK_LIMIT,
-      deep: 100,
-    });
-  }
-  const entry = PAGE_ACTIONS[normalizedArgs.action];
-  if (!entry) return summarizeToolError(`Unsupported page action "${args.action}".`);
-  return callBridgeTool(entry.method, entry.params(normalizedArgs), {
-    tabId: typeof normalizedArgs.tabId === 'number' ? normalizedArgs.tabId : null,
-    tokenBudget: getToolTokenBudget(normalizedArgs),
-  });
-}
-
-/** @type {Record<string, { method: BridgeMethod, params: (a: Record<string, unknown>) => Record<string, unknown> }>} */
-export const NAVIGATION_ACTIONS = {
-  navigate: {
-    method: 'navigation.navigate',
-    params: (a) => ({
-      url: a.url,
-      waitForLoad: a.waitForLoad,
-      timeoutMs: a.timeoutMs,
-    }),
-  },
-  reload: {
-    method: 'navigation.reload',
-    params: (a) => ({ waitForLoad: a.waitForLoad, timeoutMs: a.timeoutMs }),
-  },
-  go_back: {
-    method: 'navigation.go_back',
-    params: (a) => ({ waitForLoad: a.waitForLoad, timeoutMs: a.timeoutMs }),
-  },
-  go_forward: {
-    method: 'navigation.go_forward',
-    params: (a) => ({ waitForLoad: a.waitForLoad, timeoutMs: a.timeoutMs }),
-  },
-  scroll: {
-    method: 'viewport.scroll',
-    params: (a) => ({
-      top: a.top,
-      left: a.left,
-      behavior: a.behavior,
-      relative: a.relative,
-    }),
-  },
-  resize: {
-    method: 'viewport.resize',
-    params: (a) => ({ width: a.width, height: a.height, reset: a.reset }),
-  },
-};
-
-/**
- * @param {{ action: string, url?: string, waitForLoad?: boolean, timeoutMs?: number, top?: number, left?: number, behavior?: string, relative?: boolean, width?: number, height?: number, reset?: boolean, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handleNavigationTool(args) {
-  const entry = NAVIGATION_ACTIONS[args.action];
-  if (!entry) return summarizeToolError(`Unsupported navigation action "${args.action}".`);
-  return callBridgeTool(entry.method, entry.params(args), {
-    tabId: typeof args.tabId === 'number' ? args.tabId : null,
-    tokenBudget: getToolTokenBudget(args),
-  });
-}
-
-/** @type {Record<string, BridgeMethod>} */
-export const INPUT_ACTION_METHODS = {
-  click: 'input.click',
-  focus: 'input.focus',
-  type: 'input.type',
-  press_key: 'input.press_key',
-  set_checked: 'input.set_checked',
-  select_option: 'input.select_option',
-  hover: 'input.hover',
-  drag: 'input.drag',
-  scroll_into_view: 'input.scroll_into_view',
-};
-
-/**
- * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, text?: string, clear?: boolean, submit?: boolean, key?: string, modifiers?: string[], checked?: boolean, values?: string[], labels?: string[], indexes?: number[], duration?: number, sourceElementRef?: string, sourceSelector?: string, destinationElementRef?: string, destinationSelector?: string, offsetX?: number, offsetY?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handleInputTool(args) {
-  return withToolClient(async (client) => {
-    const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
-    const elementTarget = async () => ({
-      elementRef: await resolveToolRef(client, args, requestedTabId),
-    });
-
-    switch (args.action) {
-      case 'click': {
-        const response = await requestBridge(
-          client,
-          'input.click',
-          {
-            target: await elementTarget(),
-            button: args.button,
-            clickCount: args.clickCount,
-          },
-          {
-            tabId: requestedTabId,
-            source: REQUEST_SOURCE,
-            tokenBudget: getToolTokenBudget(args),
-          }
-        );
-        return summarizeToolResponse(response, 'input.click');
-      }
-      case 'focus': {
-        const response = await requestBridge(
-          client,
-          'input.focus',
-          {
-            target: await elementTarget(),
-          },
-          {
-            tabId: requestedTabId,
-            source: REQUEST_SOURCE,
-            tokenBudget: getToolTokenBudget(args),
-          }
-        );
-        return summarizeToolResponse(response, 'input.focus');
-      }
-      case 'type': {
-        const response = await requestBridge(
-          client,
-          'input.type',
-          {
-            target: await elementTarget(),
-            text: args.text,
-            clear: args.clear,
-            submit: args.submit,
-          },
-          {
-            tabId: requestedTabId,
-            source: REQUEST_SOURCE,
-            tokenBudget: getToolTokenBudget(args),
-          }
-        );
-        return summarizeToolResponse(response, 'input.type');
-      }
-      case 'press_key': {
-        const target = args.elementRef || args.selector ? await elementTarget() : undefined;
-        const response = await requestBridge(
-          client,
-          'input.press_key',
-          {
-            target,
-            key: args.key,
-            modifiers: args.modifiers,
-          },
-          {
-            tabId: requestedTabId,
-            source: REQUEST_SOURCE,
-            tokenBudget: getToolTokenBudget(args),
-          }
-        );
-        return summarizeToolResponse(response, 'input.press_key');
-      }
-      case 'set_checked': {
-        const response = await requestBridge(
-          client,
-          'input.set_checked',
-          {
-            target: await elementTarget(),
-            checked: args.checked,
-          },
-          {
-            tabId: requestedTabId,
-            source: REQUEST_SOURCE,
-            tokenBudget: getToolTokenBudget(args),
-          }
-        );
-        return summarizeToolResponse(response, 'input.set_checked');
-      }
-      case 'select_option': {
-        const response = await requestBridge(
-          client,
-          'input.select_option',
-          {
-            target: await elementTarget(),
-            values: args.values,
-            labels: args.labels,
-            indexes: args.indexes,
-          },
-          {
-            tabId: requestedTabId,
-            source: REQUEST_SOURCE,
-            tokenBudget: getToolTokenBudget(args),
-          }
-        );
-        return summarizeToolResponse(response, 'input.select_option');
-      }
-      case 'hover': {
-        const response = await requestBridge(
-          client,
-          'input.hover',
-          {
-            target: await elementTarget(),
-            duration: args.duration,
-          },
-          {
-            tabId: requestedTabId,
-            source: REQUEST_SOURCE,
-            tokenBudget: getToolTokenBudget(args),
-          }
-        );
-        return summarizeToolResponse(response, 'input.hover');
-      }
-      case 'drag': {
-        const source = {
-          elementRef:
-            args.sourceElementRef ||
-            (args.sourceSelector
-              ? await resolveRef(client, args.sourceSelector, requestedTabId, REQUEST_SOURCE)
-              : ''),
-        };
-        const destination = {
-          elementRef:
-            args.destinationElementRef ||
-            (args.destinationSelector
-              ? await resolveRef(client, args.destinationSelector, requestedTabId, REQUEST_SOURCE)
-              : ''),
-        };
-        if (!source.elementRef || !destination.elementRef) {
-          return summarizeToolError(
-            'sourceElementRef/sourceSelector and destinationElementRef/destinationSelector are required for drag.'
-          );
-        }
-        const response = await requestBridge(
-          client,
-          'input.drag',
-          {
-            source,
-            destination,
-            offsetX: args.offsetX,
-            offsetY: args.offsetY,
-          },
-          {
-            tabId: requestedTabId,
-            source: REQUEST_SOURCE,
-            tokenBudget: getToolTokenBudget(args),
-          }
-        );
-        return summarizeToolResponse(response, 'input.drag');
-      }
-      case 'scroll_into_view': {
-        const response = await requestBridge(
-          client,
-          'input.scroll_into_view',
-          {
-            target: await elementTarget(),
-          },
-          {
-            tabId: requestedTabId,
-            source: REQUEST_SOURCE,
-            tokenBudget: getToolTokenBudget(args),
-          }
-        );
-        return summarizeToolResponse(response, 'input.scroll_into_view');
-      }
-      default:
-        return summarizeToolError(`Unsupported input action "${args.action}".`);
-    }
-  });
-}
-
-/** @type {Record<string, ToolAction>} */
-export const PATCH_ACTIONS = {
-  apply_styles: {
-    ref: true,
-    method: 'patch.apply_styles',
-    params: (a, r) => ({
-      target: { elementRef: r },
-      declarations: a.declarations,
-      important: a.important,
-      verify: a.verify,
-    }),
-  },
-  apply_dom: {
-    ref: true,
-    method: 'patch.apply_dom',
-    params: (a, r) => {
-      const operation = typeof a.operation === 'string' ? a.operation : '';
-      /** @type {Record<string, string>} */
-      const opMap = {
-        setAttribute: 'set_attribute',
-        removeAttribute: 'remove_attribute',
-        addClass: 'toggle_class',
-        removeClass: 'toggle_class',
-        setTextContent: 'set_text',
-        setProperty: 'set_attribute',
-      };
-      return {
-        target: { elementRef: r },
-        operation: opMap[operation] || operation,
-        value: a.value,
-        name: a.name,
-        verify: a.verify,
-      };
-    },
-  },
-  list: { ref: false, method: 'patch.list', params: () => ({}) },
-  rollback: {
-    ref: false,
-    method: 'patch.rollback',
-    params: (a) => ({ patchId: a.patchId }),
-  },
-  commit_baseline: {
-    ref: false,
-    method: 'patch.commit_session_baseline',
-    params: () => ({}),
-  },
-};
-
-/**
- * @param {{ action: string, elementRef?: string, selector?: string, declarations?: Record<string, string>, important?: boolean, operation?: string, value?: unknown, name?: string, patchId?: string, verify?: boolean, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handlePatchTool(args) {
-  return dispatchToolAction(PATCH_ACTIONS, args, 'patch');
-}
-
-/** @type {Record<string, ToolAction>} */
-export const CAPTURE_ACTIONS = {
-  element: {
-    ref: true,
-    method: 'screenshot.capture_element',
-    params: (_, r) => ({ elementRef: r }),
-  },
-  region: {
-    ref: false,
-    method: 'screenshot.capture_region',
-    params: (a) => /** @type {Record<string, unknown>} */ (a.rect || {}),
-  },
-  full_page: {
-    ref: false,
-    method: 'screenshot.capture_full_page',
-    params: () => ({}),
-  },
-  cdp_document: { ref: false, method: 'cdp.get_document', params: () => ({}) },
-  cdp_dom_snapshot: {
-    ref: false,
-    method: 'cdp.get_dom_snapshot',
-    params: () => ({}),
-  },
-  cdp_box_model: {
-    ref: true,
-    method: 'cdp.get_box_model',
-    params: (_, r) => ({ elementRef: r }),
-  },
-  cdp_computed_styles: {
-    ref: true,
-    method: 'cdp.get_computed_styles_for_node',
-    params: (_, r) => ({ elementRef: r }),
-  },
-};
-
-/**
- * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handleCaptureTool(args) {
-  return dispatchToolAction(CAPTURE_ACTIONS, args, 'capture');
-}
-
-/**
- * Returns the live runtime context: budget presets, method groups, and active limits.
- * Equivalent to `bbx skill`. Use this first to discover safe defaults before inspecting.
- *
  * @returns {Promise<ToolResult>}
  */
 export async function handleSkillTool() {
   try {
-    const { createRuntimeContext } = await import('../../protocol/src/index.js');
     const ctx = createRuntimeContext();
     return createToolResult('Runtime context retrieved.', {
       ok: true,
@@ -908,14 +100,11 @@ export async function handleSkillTool() {
 }
 
 /**
- * Check MCP config and CLI skill installation status.
- *
  * @param {{ global?: boolean }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleSetupTool(args) {
-  const { collectSetupStatus } = await import('../../agent-client/src/setup-status.js');
-  const projectPath = args.global !== false ? (await import('node:os')).homedir() : process.cwd();
+  const projectPath = args.global !== false ? HOME_DIR : process.cwd();
   const status = await collectSetupStatus({
     global: args.global !== false,
     cwd: process.cwd(),
@@ -928,8 +117,6 @@ export async function handleSetupTool(args) {
 }
 
 /**
- * Tail recent bridge logs for debugging.
- *
  * @param {{ limit?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
@@ -951,8 +138,6 @@ export async function handleLogTool(args) {
 }
 
 /**
- * Ping the bridge to check connectivity.
- *
  * @returns {Promise<ToolResult>}
  */
 export async function handleHealthTool() {
@@ -966,289 +151,8 @@ export async function handleHealthTool() {
 }
 
 /**
- * @param {{ calls?: Array<{ method?: string, params?: Record<string, unknown>, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }> }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handleBatchTool(args) {
-  if (!Array.isArray(args.calls) || args.calls.length === 0) {
-    return summarizeToolError('calls must be a non-empty array.');
-  }
-
-  const calls = args.calls;
-  return withToolClient(async (client) => {
-    const results = await Promise.all(
-      calls.map(async (call) => {
-        if (!call || typeof call !== 'object' || typeof call.method !== 'string') {
-          return {
-            method: '',
-            tabId: null,
-            ok: false,
-            summary: 'INVALID_REQUEST: Each batch call needs a method.',
-            evidence: null,
-            error: {
-              code: 'INVALID_REQUEST',
-              message: 'Each batch call needs a method.',
-            },
-            response: null,
-          };
-        }
-
-        if (!METHODS.includes(/** @type {BridgeMethod} */ (call.method))) {
-          return {
-            method: call.method,
-            tabId: null,
-            ok: false,
-            summary: `INVALID_REQUEST: Unknown bridge method "${call.method}".`,
-            evidence: null,
-            error: {
-              code: 'INVALID_REQUEST',
-              message: `Unknown bridge method "${call.method}".`,
-            },
-            response: null,
-          };
-        }
-
-        const method = /** @type {BridgeMethod} */ (call.method);
-        const tabId = bridgeMethodNeedsTab(method)
-          ? typeof call.tabId === 'number'
-            ? call.tabId
-            : null
-          : null;
-        const tokenBudget = getToolTokenBudget(call);
-
-        const startTime = Date.now();
-        try {
-          const response = await client.request({
-            method,
-            params: call.params || {},
-            tabId,
-            meta: {
-              source: REQUEST_SOURCE,
-              ...(tokenBudget != null ? { token_budget: tokenBudget } : {}),
-            },
-          });
-          return summarizeBatchResponseItem({
-            method,
-            tabId,
-            response,
-            durationMs: Date.now() - startTime,
-          });
-        } catch (error) {
-          return summarizeBatchErrorItem({
-            method,
-            tabId,
-            error,
-            durationMs: Date.now() - startTime,
-          });
-        }
-      })
-    );
-
-    const failureCount = results.filter((result) => !result.ok).length;
-    const summary =
-      failureCount === 0
-        ? `Batch executed ${results.length} call(s).`
-        : `Batch executed ${results.length} call(s) with ${failureCount} error(s).`;
-    return createToolResult(
-      summary,
-      {
-        ok: failureCount === 0,
-        results,
-      },
-      failureCount > 0
-    );
-  });
-}
-
-/**
- * @param {{ method: string, params?: Record<string, unknown>, tabId?: number }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handleRawCallTool(args) {
-  if (!METHODS.includes(/** @type {BridgeMethod} */ (args.method))) {
-    return summarizeToolError(`Unknown bridge method "${args.method}".`);
-  }
-
-  return withToolClient(async (client) => {
-    const response = await requestBridge(
-      client,
-      /** @type {BridgeMethod} */ (args.method),
-      args.params || {},
-      {
-        tabId: typeof args.tabId === 'number' ? args.tabId : null,
-        source: REQUEST_SOURCE,
-      }
-    );
-
-    if (!response.ok) {
-      return createToolResult(
-        response.error.message,
-        {
-          ok: false,
-          error: response.error,
-          response,
-        },
-        true
-      );
-    }
-
-    return createToolResult(`Called ${args.method}.`, {
-      ok: true,
-      response: response.result,
-    });
-  });
-}
-
-/**
- * Explicitly request Browser Bridge access for the current browser window.
- * Surfaces an Enable cue in the extension popup or side panel.
- *
  * @returns {Promise<ToolResult>}
  */
 export async function handleAccessTool() {
   return callBridgeTool('access.request');
 }
-
-// ---------------------------------------------------------------------------
-// browser_investigate — heuristic fallback for subagent-delegatable inspection
-// ---------------------------------------------------------------------------
-
-/**
- * @typedef {{ method: BridgeMethod, params: (args: Record<string, unknown>) => Record<string, unknown> }} InvestigateStep
- */
-
-/** @type {Record<string, { label: string, steps: InvestigateStep[] }>} */
-const INVESTIGATE_SCOPES = {
-  quick: {
-    label: 'quick',
-    steps: [
-      { method: 'page.get_state', params: () => ({}) },
-      {
-        method: 'dom.query',
-        params: (a) => ({
-          selector: a.selector || 'body',
-          maxNodes: 10,
-          maxDepth: 2,
-          textBudget: 300,
-        }),
-      },
-    ],
-  },
-  normal: {
-    label: 'normal',
-    steps: [
-      { method: 'page.get_state', params: () => ({}) },
-      {
-        method: 'dom.query',
-        params: (a) => ({
-          selector: a.selector || 'body',
-          maxNodes: 25,
-          maxDepth: 4,
-          textBudget: 600,
-        }),
-      },
-      { method: 'page.get_text', params: () => ({ textBudget: 4000 }) },
-    ],
-  },
-  deep: {
-    label: 'deep',
-    steps: [
-      { method: 'page.get_state', params: () => ({}) },
-      {
-        method: 'dom.query',
-        params: (a) => ({
-          selector: a.selector || 'body',
-          maxNodes: 50,
-          maxDepth: 6,
-          textBudget: 1000,
-        }),
-      },
-      { method: 'page.get_text', params: () => ({ textBudget: 8000 }) },
-      {
-        method: 'page.get_console',
-        params: () => ({ level: 'warn', limit: 20 }),
-      },
-      { method: 'page.get_network', params: () => ({ limit: 20 }) },
-    ],
-  },
-};
-
-/**
- * Investigate a page to answer a question or verify a condition.
- * Runs a deterministic heuristic inspection sequence and returns a
- * structured summary. Designed so smart orchestrators can delegate
- * this to a cheaper subagent instead.
- *
- * @param {{ objective: string, scope?: 'quick' | 'normal' | 'deep', tabId?: number, selector?: string }} args
- * @returns {Promise<ToolResult>}
- */
-export async function handleInvestigateTool(args) {
-  const objective = typeof args.objective === 'string' ? args.objective.trim() : '';
-  if (!objective) {
-    return summarizeToolError('objective is required for browser_investigate.');
-  }
-
-  const scopeName = args.scope || 'normal';
-  const scope = INVESTIGATE_SCOPES[scopeName];
-  if (!scope) {
-    return summarizeToolError(`Unsupported investigation scope "${scopeName}".`);
-  }
-
-  return withToolClient(async (client) => {
-    const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
-
-    /** @type {Array<{ method: string, ok: boolean, summary: string, evidence: unknown, durationMs: number }>} */
-    const stepResults = [];
-
-    for (const step of scope.steps) {
-      const startTime = Date.now();
-      try {
-        const response = await requestBridgeWithRetry(client, step.method, step.params(args), {
-          tabId: requestedTabId,
-          source: REQUEST_SOURCE,
-          tokenBudget: null,
-        });
-        const bridgeSummary = annotateBridgeSummary(
-          summarizeBridgeResponse(response, step.method),
-          response
-        );
-        stepResults.push({
-          method: step.method,
-          ok: bridgeSummary.ok,
-          summary: bridgeSummary.summary,
-          evidence: bridgeSummary.evidence,
-          durationMs: Date.now() - startTime,
-        });
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        stepResults.push({
-          method: step.method,
-          ok: false,
-          summary: `ERROR: ${message}`,
-          evidence: null,
-          durationMs: Date.now() - startTime,
-        });
-      }
-    }
-
-    const failedSteps = stepResults.filter((s) => !s.ok);
-    const allOk = failedSteps.length === 0;
-    const totalDuration = stepResults.reduce((sum, s) => sum + s.durationMs, 0);
-
-    const summaryText = allOk
-      ? `Investigation complete (${scope.label}, ${stepResults.length} steps, ${totalDuration}ms). Objective: ${objective}`
-      : `Investigation partial (${scope.label}, ${stepResults.length} steps, ${failedSteps.length} failed, ${totalDuration}ms). Objective: ${objective}`;
-
-    return createToolResult(
-      summaryText,
-      {
-        ok: allOk,
-        objective,
-        scope: scopeName,
-        heuristicFallback: true,
-        steps: stepResults,
-      },
-      !allOk
-    );
-  });
-}