@browserbridge/bbx 1.3.0 → 1.4.0

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

@@ -4,7 +4,7 @@ import {
   dispatchToolAction,
   getToolTokenBudget,
   REQUEST_SOURCE,
-  requestBridge,
+  requestBridgeWithRetry,
   resolveToolRef,
   resolveRef,
   summarizeToolError,
@@ -56,11 +56,40 @@ function isCdpNodeCapture(args) {
   return args.action === 'cdp_box_model' || args.action === 'cdp_computed_styles';
 }
 
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/** @param {unknown} rect */
+function isValidCaptureRegion(rect) {
+  if (!rect || typeof rect !== 'object' || Array.isArray(rect)) {
+    return false;
+  }
+  const candidate = /** @type {Record<string, unknown>} */ (rect);
+  return (
+    isFiniteNumber(candidate.x) &&
+    isFiniteNumber(candidate.y) &&
+    isFiniteNumber(candidate.width) &&
+    candidate.width > 0 &&
+    isFiniteNumber(candidate.height) &&
+    candidate.height > 0
+  );
+}
+
 /**
  * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, nodeId?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleCaptureTool(args) {
+  if (args.action === 'region' && !isValidCaptureRegion(args.rect)) {
+    return summarizeToolError(
+      'rect with finite x, y, width, and height is required for region capture.'
+    );
+  }
   if (
     isCdpNodeCapture(args) &&
     (typeof args.nodeId !== 'number' || !Number.isFinite(args.nodeId))
@@ -90,6 +119,21 @@ export const INPUT_ACTION_METHODS = {
  * @returns {Promise<ToolResult>}
  */
 export async function handleInputTool(args) {
+  if (args.action === 'type' && !hasText(args.text)) {
+    return summarizeToolError('text is required for input.type.');
+  }
+  if ((args.action === 'press_key' || args.action === 'cdp_press_key') && !hasText(args.key)) {
+    return summarizeToolError('key is required for key input actions.');
+  }
+  if (
+    args.action === 'select_option' &&
+    !hasNonEmptyArray(args.values) &&
+    !hasNonEmptyArray(args.labels) &&
+    !hasNonEmptyArray(args.indexes)
+  ) {
+    return summarizeToolError('values, labels, or indexes are required for input.select_option.');
+  }
+
   return withToolClient(async (client) => {
     const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
     const elementTarget = async () => ({
@@ -98,13 +142,14 @@ export async function handleInputTool(args) {
 
     switch (args.action) {
       case 'click': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.click',
           {
             target: await elementTarget(),
             button: args.button,
             clickCount: args.clickCount,
+            modifiers: args.modifiers,
           },
           {
             tabId: requestedTabId,
@@ -115,7 +160,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.click');
       }
       case 'focus': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.focus',
           {
@@ -130,7 +175,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.focus');
       }
       case 'type': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.type',
           {
@@ -138,6 +183,7 @@ export async function handleInputTool(args) {
             text: args.text,
             clear: args.clear,
             submit: args.submit,
+            modifiers: args.modifiers,
           },
           {
             tabId: requestedTabId,
@@ -149,7 +195,7 @@ export async function handleInputTool(args) {
       }
       case 'press_key': {
         const target = args.elementRef || args.selector ? await elementTarget() : undefined;
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.press_key',
           {
@@ -166,7 +212,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.press_key');
       }
       case 'cdp_press_key': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'cdp.dispatch_key_event',
           {
@@ -183,7 +229,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'cdp.dispatch_key_event');
       }
       case 'set_checked': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.set_checked',
           {
@@ -199,7 +245,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.set_checked');
       }
       case 'select_option': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.select_option',
           {
@@ -217,12 +263,13 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.select_option');
       }
       case 'hover': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.hover',
           {
             target: await elementTarget(),
             duration: args.duration,
+            modifiers: args.modifiers,
           },
           {
             tabId: requestedTabId,
@@ -252,7 +299,7 @@ export async function handleInputTool(args) {
             'sourceElementRef/sourceSelector and destinationElementRef/destinationSelector are required for drag.'
           );
         }
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.drag',
           {
@@ -270,7 +317,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.drag');
       }
       case 'scroll_into_view': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.scroll_into_view',
           {
@@ -289,3 +336,19 @@ export async function handleInputTool(args) {
     }
   });
 }
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function hasNonEmptyArray(value) {
+  return Array.isArray(value) && value.length > 0;
+}

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

@@ -6,6 +6,7 @@ import {
   applyTreeBudgetPreset,
   dispatchToolAction,
   inferBudgetFromSelector,
+  summarizeToolError,
 } from './handlers-utils.js';
 
 /** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
@@ -93,6 +94,15 @@ export const DOM_ACTIONS = {
  * @returns {Promise<ToolResult>}
  */
 export async function handleDomTool(args) {
+  if (args.action === 'wait' && !hasText(args.selector) && !hasText(args.text)) {
+    return summarizeToolError('selector or text is required for dom.wait_for.');
+  }
+  if (args.action === 'find_text' && !hasText(args.text)) {
+    return summarizeToolError('text is required for dom.find_by_text.');
+  }
+  if (args.action === 'find_role' && !hasText(args.role)) {
+    return summarizeToolError('role is required for dom.find_by_role.');
+  }
   if (args.action === 'query' || args.action === 'accessibility_tree') {
     const inferred = inferBudgetFromSelector(args);
     const withBudget = inferred ? { ...args, budgetPreset: args.budgetPreset ?? inferred } : args;
@@ -136,6 +146,15 @@ export const STYLES_LAYOUT_ACTIONS = {
  * @returns {Promise<ToolResult>}
  */
 export async function handleStylesLayoutTool(args) {
+  if (
+    args.action === 'hit_test' &&
+    (typeof args.x !== 'number' ||
+      !Number.isFinite(args.x) ||
+      typeof args.y !== 'number' ||
+      !Number.isFinite(args.y))
+  ) {
+    return summarizeToolError('x and y are required for layout.hit_test.');
+  }
   return dispatchToolAction(STYLES_LAYOUT_ACTIONS, args, 'styles/layout');
 }
 
@@ -199,5 +218,34 @@ export const PATCH_ACTIONS = {
  * @returns {Promise<ToolResult>}
  */
 export async function handlePatchTool(args) {
+  if (args.action === 'apply_styles' && !hasStringRecord(args.declarations)) {
+    return summarizeToolError('declarations are required for patch.apply_styles.');
+  }
+  if (args.action === 'apply_dom' && !hasText(args.operation)) {
+    return summarizeToolError('operation is required for patch.apply_dom.');
+  }
+  if (args.action === 'rollback' && !hasText(args.patchId)) {
+    return summarizeToolError('patchId is required for patch.rollback.');
+  }
   return dispatchToolAction(PATCH_ACTIONS, args, 'patch');
 }
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, string>}
+ */
+function hasStringRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const entries = Object.entries(/** @type {Record<string, unknown>} */ (value));
+  return entries.length > 0 && entries.every(([key, val]) => key.trim() && typeof val === 'string');
+}

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

@@ -61,17 +61,37 @@ export const NAVIGATION_ACTIONS = {
   },
   resize: {
     method: 'viewport.resize',
-    params: (a) => ({ width: a.width, height: a.height, reset: a.reset }),
+    params: (a) => ({
+      width: a.width,
+      height: a.height,
+      deviceScaleFactor: a.deviceScaleFactor,
+      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
+ * @param {{ action: string, url?: string, waitForLoad?: boolean, timeoutMs?: number, top?: number, left?: number, behavior?: string, relative?: boolean, width?: number, height?: number, deviceScaleFactor?: 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}".`);
+  if (args.action === 'navigate' && (typeof args.url !== 'string' || !args.url.trim())) {
+    return summarizeToolError('url is required for navigation.navigate.');
+  }
+  if (
+    args.action === 'resize' &&
+    args.reset !== true &&
+    (typeof args.width !== 'number' ||
+      !Number.isFinite(args.width) ||
+      typeof args.height !== 'number' ||
+      !Number.isFinite(args.height))
+  ) {
+    return summarizeToolError(
+      'width and height are required for viewport.resize unless reset=true.'
+    );
+  }
   return callBridgeTool(entry.method, entry.params(args), {
     tabId: typeof args.tabId === 'number' ? args.tabId : null,
     tokenBudget: getToolTokenBudget(args),

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

@@ -13,7 +13,6 @@ import {
   callBridgeTool,
   createToolResult,
   getToolTokenBudget,
-  requestBridge,
   requestBridgeWithRetry,
   summarizeBatchErrorItem,
   summarizeBatchResponseItem,
@@ -147,14 +146,10 @@ export async function handleBatchTool(args) {
 
         const startTime = Date.now();
         try {
-          const response = await client.request({
-            method,
-            params: call.params || {},
+          const response = await requestBridgeWithRetry(client, method, call.params || {}, {
             tabId,
-            meta: {
-              source: REQUEST_SOURCE,
-              ...(tokenBudget != null ? { token_budget: tokenBudget } : {}),
-            },
+            source: REQUEST_SOURCE,
+            tokenBudget,
           });
           return summarizeBatchResponseItem({
             method,
@@ -199,7 +194,7 @@ export async function handleRawCallTool(args) {
   }
 
   return withToolClient(async (client) => {
-    const response = await requestBridge(
+    const response = await requestBridgeWithRetry(
       client,
       /** @type {BridgeMethod} */ (args.method),
       args.params || {},

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

@@ -24,6 +24,52 @@ import { annotateBridgeSummary, summarizeBridgeResponse } from '../../agent-clie
 
 export const REQUEST_SOURCE = 'mcp';
 
+/** @type {ReadonlySet<BridgeMethod>} */
+const RETRY_SAFE_METHODS = new Set([
+  'skill.get_runtime_context',
+  'setup.get_status',
+  'log.tail',
+  'health.ping',
+  'daemon.metrics',
+  'tabs.list',
+  'page.get_state',
+  'page.get_storage',
+  'page.get_text',
+  'dom.query',
+  'dom.describe',
+  'dom.get_text',
+  'dom.get_attributes',
+  'dom.wait_for',
+  'dom.find_by_text',
+  'dom.find_by_role',
+  'dom.get_html',
+  'dom.get_accessibility_tree',
+  'layout.get_box_model',
+  'layout.hit_test',
+  'styles.get_computed',
+  'styles.get_matched_rules',
+  'screenshot.capture_region',
+  'screenshot.capture_element',
+  'screenshot.capture_full_page',
+  'performance.get_metrics',
+  'cdp.get_document',
+  'cdp.get_dom_snapshot',
+  'cdp.get_box_model',
+  'cdp.get_computed_styles_for_node',
+]);
+
+/**
+ * @param {BridgeMethod} method
+ * @param {Record<string, unknown>} params
+ * @returns {boolean}
+ */
+export function isRetrySafeBridgeMethod(method, params) {
+  if (method === 'page.get_console' || method === 'page.get_network') {
+    return params.clear !== true;
+  }
+  return RETRY_SAFE_METHODS.has(method);
+}
+
 /**
  * @typedef {{
  *   content: Array<{ type: 'text', text: string }>,
@@ -246,7 +292,7 @@ export function applyHtmlBudgetPreset(args) {
 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) {
+  if (!response.ok && recovery?.retry && isRetrySafeBridgeMethod(method, params)) {
     const delay = recovery.retryAfterMs ?? 1000;
     process.stderr.write(
       `[bbx-mcp] Retrying ${method} after ${delay}ms (${response.error.code})\n`