@browserbridge/bbx 1.1.0 → 1.3.0

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

@@ -0,0 +1,365 @@
+// @ts-check
+
+import {
+  DEFAULT_CONSOLE_LIMIT,
+  DEFAULT_NETWORK_LIMIT,
+  METHOD_SET,
+} from '../../protocol/src/index.js';
+import {
+  annotateBridgeSummary,
+  applyLimitBudgetPreset,
+  applyPageTextBudgetPreset,
+  bridgeMethodNeedsTab,
+  callBridgeTool,
+  createToolResult,
+  getToolTokenBudget,
+  requestBridge,
+  requestBridgeWithRetry,
+  summarizeBatchErrorItem,
+  summarizeBatchResponseItem,
+  summarizeBridgeResponse,
+  summarizeToolError,
+  withToolClient,
+  REQUEST_SOURCE,
+} from './handlers-utils.js';
+
+/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
+
+/** @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 = applyPageTextBudgetPreset(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),
+  });
+}
+
+/**
+ * @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 (!METHOD_SET.has(/** @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 (!METHOD_SET.has(/** @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,
+    });
+  });
+}
+
+/**
+ * @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 }) },
+    ],
+  },
+};
+
+/**
+ * @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,
+        failedSteps,
+      },
+      !allOk
+    );
+  });
+}

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

@@ -0,0 +1,318 @@
+// @ts-check
+
+import {
+  bridgeMethodNeedsTab,
+  DEFAULT_MAX_HTML_LENGTH,
+  DEFAULT_PAGE_TEXT_BUDGET,
+  estimateJsonPayloadCost,
+  getBudgetPreset,
+  getErrorRecovery,
+  isBudgetPresetName,
+  summarizeBatchErrorItem,
+  summarizeBatchResponseItem,
+} from '../../protocol/src/index.js';
+import {
+  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 */
+
+export 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}
+ */
+export 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}
+ */
+export function summarizeToolResponse(response, method) {
+  const summary = annotateBridgeSummary(summarizeBridgeResponse(response, method), response);
+  return createToolResult(summary.summary, summary, !summary.ok);
+}
+
+/**
+ * @param {unknown} error
+ * @returns {ToolResult}
+ */
+export 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>}
+ */
+export 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>}
+ */
+export 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}
+ */
+export function getBudgetPresetName(value) {
+  return isBudgetPresetName(value) ? value : null;
+}
+
+/**
+ * @param {{ budgetPreset?: unknown, selector?: unknown, elementRef?: unknown }} args
+ * @returns {'quick' | 'normal' | 'deep' | null}
+ */
+export function inferBudgetFromSelector(args) {
+  if (getBudgetPresetName(args.budgetPreset)) return null;
+  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;
+  if (/^#[\w-]+$/.test(sel)) return 'quick';
+  if ((sel.match(/\s/g) || []).length >= 3) return 'deep';
+  return 'normal';
+}
+
+/**
+ * @param {{ budgetPreset?: unknown }} args
+ * @returns {number | null}
+ */
+export 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}
+ */
+export 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}
+ */
+export 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, textBudget?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyPageTextBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const textBudgetByPreset = {
+    quick: 2000,
+    normal: DEFAULT_PAGE_TEXT_BUDGET,
+    deep: DEFAULT_PAGE_TEXT_BUDGET * 2,
+  };
+  return /** @type {T} */ ({
+    ...args,
+    textBudget: args.textBudget ?? textBudgetByPreset[presetName],
+  });
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, limit?: unknown }} T
+ * @param {T} args
+ * @param {{ quick: number, normal: number, deep: number }} defaults
+ * @returns {T}
+ */
+export 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}
+ */
+export 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],
+  });
+}
+
+/**
+ * @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>}
+ */
+export 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>}
+ */
+export 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
+ */
+
+/**
+ * @param {Record<string, ToolAction>} actions
+ * @param {Record<string, unknown> & { action: string }} args
+ * @param {string} toolName
+ * @returns {Promise<ToolResult>}
+ */
+export 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);
+  });
+}
+
+export {
+  bridgeMethodNeedsTab,
+  getDoctorReport,
+  requestBridge,
+  resolveRef,
+  withBridgeClient,
+  annotateBridgeSummary,
+  summarizeBridgeResponse,
+  summarizeBatchErrorItem,
+  summarizeBatchResponseItem,
+};