@browserbridge/bbx 1.7.2 → 1.7.4

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

@@ -1,18 +1,18 @@
 // @ts-check
 
 import {
-  dispatchToolAction,
+  createToolResult,
   getToolTokenBudget,
   REQUEST_SOURCE,
   requestBridgeWithRetry,
   resolveToolRef,
-  resolveRef,
   summarizeToolError,
   summarizeToolResponse,
   withToolClient,
 } from './handlers-utils.js';
 
 /** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('../../protocol/src/types.js').BridgeResponse} BridgeResponse */
 /** @typedef {import('./handlers-utils.js').ToolAction} ToolAction */
 /** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
 
@@ -97,7 +97,170 @@ export async function handleCaptureTool(args) {
     return summarizeToolError('nodeId must be a finite number.');
   }
 
-  return dispatchToolAction(CAPTURE_ACTIONS, args, 'capture');
+  const entry = CAPTURE_ACTIONS[args.action];
+  if (!entry) {
+    return summarizeToolError(`Unsupported capture action "${args.action}".`);
+  }
+
+  return withToolClient(
+    async (client) => {
+      const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
+      const ref = entry.ref ? await resolveToolRef(client, args, requestedTabId) : undefined;
+      const response = await requestBridgeWithRetry(client, entry.method, entry.params(args, ref), {
+        tabId: requestedTabId,
+        source: REQUEST_SOURCE,
+        tokenBudget: getToolTokenBudget(args),
+      });
+      if (!response.ok) {
+        return summarizeToolResponse(response, entry.method);
+      }
+      return entry.method.startsWith('screenshot.')
+        ? createScreenshotResult(response, entry.method)
+        : createCdpCaptureResult(response, entry.method);
+    },
+    { destinationId: args.destinationId ?? null }
+  );
+}
+
+/**
+ * @param {BridgeResponse & { ok: true }} response
+ * @param {BridgeMethod} method
+ * @returns {ToolResult}
+ */
+function createScreenshotResult(response, method) {
+  const result = toRecord(response.result);
+  if (typeof result.image !== 'string') {
+    return summarizeToolError(`${method} returned no image data.`);
+  }
+
+  const image = normalizeBase64Image(result.image);
+  if (!image) {
+    return summarizeToolError(`${method} returned invalid base64 image data.`);
+  }
+
+  const rect = boundedRect(result.rect);
+  return createToolResult(
+    `Captured ${image.mimeType} screenshot (${image.byteLength} bytes).`,
+    {
+      ok: true,
+      method,
+      mimeType: image.mimeType,
+      byteLength: image.byteLength,
+      ...(rect ? { rect } : {}),
+    },
+    false,
+    [{ type: 'image', data: image.data, mimeType: image.mimeType }]
+  );
+}
+
+/**
+ * @param {BridgeResponse & { ok: true }} response
+ * @param {BridgeMethod} method
+ * @returns {ToolResult}
+ */
+function createCdpCaptureResult(response, method) {
+  const bounded = boundStructuredValue(response.result);
+  return createToolResult(`Captured bounded structured data from ${method}.`, {
+    ok: true,
+    method,
+    data: bounded.value,
+    truncated: bounded.truncated,
+  });
+}
+
+/**
+ * @param {string} value
+ * @returns {{ data: string, mimeType: string, byteLength: number } | null}
+ */
+function normalizeBase64Image(value) {
+  const dataUrl = /^data:([^;,]+);base64,(.*)$/su.exec(value);
+  const mimeType = dataUrl?.[1] ?? 'image/png';
+  if (!mimeType.startsWith('image/')) return null;
+  const data = (dataUrl?.[2] ?? value).replace(/\s+/gu, '');
+  if (!data || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(data)) {
+    return null;
+  }
+  const bytes = Buffer.from(data, 'base64');
+  if (bytes.toString('base64') !== data) return null;
+  return { data, mimeType, byteLength: bytes.length };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, number> | null}
+ */
+function boundedRect(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const source = /** @type {Record<string, unknown>} */ (value);
+  /** @type {Record<string, number>} */
+  const rect = {};
+  for (const key of ['x', 'y', 'width', 'height', 'scale']) {
+    if (isFiniteNumber(source[key])) rect[key] = source[key];
+  }
+  return Object.keys(rect).length > 0 ? rect : null;
+}
+
+/**
+ * Bound debugger payloads by depth, entries, and string length while retaining
+ * their actual values rather than reducing them to field names.
+ *
+ * @param {unknown} input
+ * @returns {{ value: unknown, truncated: boolean }}
+ */
+function boundStructuredValue(input) {
+  const state = { entries: 0, characters: 0, truncated: false };
+  const maxEntries = 500;
+  const maxCharacters = 50_000;
+  /** @type {(value: unknown, depth: number) => unknown} */
+  const visit = (value, depth) => {
+    if (state.entries >= maxEntries || state.characters >= maxCharacters || depth > 8) {
+      state.truncated = true;
+      return '[truncated]';
+    }
+    state.entries += 1;
+    if (typeof value === 'string') {
+      const remaining = maxCharacters - state.characters;
+      const limit = Math.min(value.length, remaining, 4000);
+      state.characters += limit;
+      if (limit === value.length) return value;
+      state.truncated = true;
+      return `${value.slice(0, limit)}[truncated]`;
+    }
+    if (Array.isArray(value)) {
+      const remaining = maxEntries - state.entries;
+      const limit = Math.min(value.length, remaining, 100);
+      if (limit < value.length) state.truncated = true;
+      return value.slice(0, limit).map((entry) => visit(entry, depth + 1));
+    }
+    if (value && typeof value === 'object') {
+      /** @type {Record<string, unknown>} */
+      const output = {};
+      const entries = Object.entries(/** @type {Record<string, unknown>} */ (value));
+      const limit = Math.min(entries.length, 100);
+      if (limit < entries.length) state.truncated = true;
+      for (const [key, entry] of entries.slice(0, limit)) {
+        if (state.entries >= maxEntries || state.characters >= maxCharacters) {
+          state.truncated = true;
+          break;
+        }
+        state.characters += key.length;
+        output[key] = visit(entry, depth + 1);
+      }
+      return output;
+    }
+    return value;
+  };
+  return { value: visit(input, 0), truncated: state.truncated };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+function toRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? /** @type {Record<string, unknown>} */ (value)
+    : {};
 }
 
 /** @type {Record<string, BridgeMethod>} */
@@ -105,6 +268,7 @@ export const INPUT_ACTION_METHODS = {
   click: 'input.click',
   focus: 'input.focus',
   type: 'input.type',
+  fill: 'input.fill',
   press_key: 'input.press_key',
   cdp_press_key: 'cdp.dispatch_key_event',
   set_checked: 'input.set_checked',
@@ -115,13 +279,30 @@ export const INPUT_ACTION_METHODS = {
 };
 
 /**
- * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, text?: string, clear?: boolean, submit?: boolean, key?: string, code?: 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, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * Keep selector-based actions atomic instead of resolving a ref in a separate
+ * bridge request that can race with a page rerender.
+ *
+ * @param {unknown} elementRef
+ * @param {unknown} selector
+ * @returns {import('../../protocol/src/types.js').InputTarget | null}
+ */
+function createInputTarget(elementRef, selector) {
+  if (typeof elementRef === 'string' && elementRef) return { elementRef };
+  if (typeof selector === 'string' && selector) return { selector };
+  return null;
+}
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, text?: string, value?: string, mode?: 'auto' | 'setter' | 'keystrokes', clear?: boolean, submit?: boolean, key?: string, code?: 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, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @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 === 'fill' && typeof args.value !== 'string') {
+    return summarizeToolError('value is required for input.fill.');
+  }
   if ((args.action === 'press_key' || args.action === 'cdp_press_key') && !hasText(args.key)) {
     return summarizeToolError('key is required for key input actions.');
   }
@@ -137,9 +318,11 @@ 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),
-      });
+      const elementTarget = () => {
+        const target = createInputTarget(args.elementRef, args.selector);
+        if (!target) throw new Error('Provide either elementRef or selector.');
+        return target;
+      };
 
       switch (args.action) {
         case 'click': {
@@ -147,7 +330,7 @@ export async function handleInputTool(args) {
             client,
             'input.click',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
               button: args.button,
               clickCount: args.clickCount,
               modifiers: args.modifiers,
@@ -165,7 +348,7 @@ export async function handleInputTool(args) {
             client,
             'input.focus',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
             },
             {
               tabId: requestedTabId,
@@ -180,7 +363,7 @@ export async function handleInputTool(args) {
             client,
             'input.type',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
               text: args.text,
               clear: args.clear,
               submit: args.submit,
@@ -194,8 +377,25 @@ export async function handleInputTool(args) {
           );
           return summarizeToolResponse(response, 'input.type');
         }
+        case 'fill': {
+          const response = await requestBridgeWithRetry(
+            client,
+            'input.fill',
+            {
+              target: elementTarget(),
+              value: args.value,
+              mode: args.mode,
+            },
+            {
+              tabId: requestedTabId,
+              source: REQUEST_SOURCE,
+              tokenBudget: getToolTokenBudget(args),
+            }
+          );
+          return summarizeToolResponse(response, 'input.fill');
+        }
         case 'press_key': {
-          const target = args.elementRef || args.selector ? await elementTarget() : undefined;
+          const target = args.elementRef || args.selector ? elementTarget() : undefined;
           const response = await requestBridgeWithRetry(
             client,
             'input.press_key',
@@ -234,7 +434,7 @@ export async function handleInputTool(args) {
             client,
             'input.set_checked',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
               checked: args.checked,
             },
             {
@@ -250,7 +450,7 @@ export async function handleInputTool(args) {
             client,
             'input.select_option',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
               values: args.values,
               labels: args.labels,
               indexes: args.indexes,
@@ -268,7 +468,7 @@ export async function handleInputTool(args) {
             client,
             'input.hover',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
               duration: args.duration,
               modifiers: args.modifiers,
             },
@@ -281,21 +481,12 @@ export async function handleInputTool(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) {
+          const source = createInputTarget(args.sourceElementRef, args.sourceSelector);
+          const destination = createInputTarget(
+            args.destinationElementRef,
+            args.destinationSelector
+          );
+          if (!source || !destination) {
             return summarizeToolError(
               'sourceElementRef/sourceSelector and destinationElementRef/destinationSelector are required for drag.'
             );
@@ -322,7 +513,7 @@ export async function handleInputTool(args) {
             client,
             'input.scroll_into_view',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
             },
             {
               tabId: requestedTabId,

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

@@ -96,6 +96,16 @@ export async function handleTabsTool(args) {
       { destinationId: args.destinationId ?? null }
     );
   }
+  if (args.action === 'activate') {
+    if (typeof args.tabId !== 'number') {
+      return summarizeToolError('tabId is required for tabs.activate.');
+    }
+    return callBridgeTool(
+      'tabs.activate',
+      { tabId: args.tabId },
+      { destinationId: args.destinationId ?? null }
+    );
+  }
   return summarizeToolError(`Unsupported tabs action "${args.action}".`);
 }
 

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

@@ -24,8 +24,57 @@ import {
 } from './handlers-utils.js';
 
 /** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('../../agent-client/src/client.js').BridgeClient} BridgeClient */
 /** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
 
+export const MAX_BATCH_CALLS = 20;
+export const MAX_BATCH_CONCURRENCY = 5;
+
+/** @type {ReadonlySet<BridgeMethod>} */
+const BATCH_SAFE_METHODS = new Set([
+  'health.ping',
+  'daemon.metrics',
+  'tabs.list',
+  'skill.get_runtime_context',
+  'setup.get_status',
+  'log.tail',
+  'page.get_state',
+  'page.get_console',
+  'page.wait_for_load_state',
+  'page.get_storage',
+  'page.get_text',
+  'page.get_network',
+  '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',
+  'network.intercept.list',
+  'patch.list',
+  'performance.get_metrics',
+]);
+
+/**
+ * @param {BridgeMethod} method
+ * @param {Record<string, unknown>} params
+ * @returns {boolean}
+ */
+export function isBatchSafeBridgeCall(method, params) {
+  if (!BATCH_SAFE_METHODS.has(method)) return false;
+  if ((method === 'page.get_console' || method === 'page.get_network') && params.clear === true) {
+    return false;
+  }
+  return true;
+}
+
 /** @type {Record<string, { method: BridgeMethod, params: (a: Record<string, unknown>) => Record<string, unknown> }>} */
 export const PAGE_ACTIONS = {
   state: { method: 'page.get_state', params: () => ({}) },
@@ -109,86 +158,90 @@ export async function handleBatchTool(args) {
   if (!Array.isArray(args.calls) || args.calls.length === 0) {
     return summarizeToolError('calls must be a non-empty array.');
   }
+  if (args.calls.length > MAX_BATCH_CALLS) {
+    return summarizeToolError(`calls must contain at most ${MAX_BATCH_CALLS} entries.`);
+  }
 
   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,
-          };
-        }
+  for (const [index, call] of calls.entries()) {
+    if (!call || typeof call !== 'object' || typeof call.method !== 'string') {
+      return summarizeToolError(`calls[${index}] needs a method.`);
+    }
+    if (!METHOD_SET.has(/** @type {BridgeMethod} */ (call.method))) {
+      return summarizeToolError(`Unknown bridge method "${call.method}" at calls[${index}].`);
+    }
+    const method = /** @type {BridgeMethod} */ (call.method);
+    if (!isBatchSafeBridgeCall(method, call.params || {})) {
+      return summarizeToolError(
+        `${method} is not safe for parallel batch execution. Use its specialized tool or browser_call sequentially.`
+      );
+    }
+  }
 
-        const method = /** @type {BridgeMethod} */ (call.method);
-        const tabId = bridgeMethodNeedsTab(method)
-          ? typeof call.tabId === 'number'
-            ? call.tabId
-            : null
-          : null;
-        const tokenBudget = getToolTokenBudget(call);
-        const destinationId = typeof call.destinationId === 'string' ? call.destinationId : null;
+  /** @param {BridgeClient | null} client */
+  const executeBatch = async (client) => {
+    const results = await mapWithConcurrency(calls, MAX_BATCH_CONCURRENCY, async (call) => {
+      const method = /** @type {BridgeMethod} */ (call.method);
+      const tabId = bridgeMethodNeedsTab(method)
+        ? typeof call.tabId === 'number'
+          ? call.tabId
+          : null
+        : null;
+      const tokenBudget = getToolTokenBudget(call);
+      const destinationId = typeof call.destinationId === 'string' ? call.destinationId : null;
 
-        const startTime = Date.now();
-        const callClient = destinationId
-          ? await createBridgeClientForDestination(destinationId)
-          : client;
-        try {
-          if (destinationId) {
-            await callClient.connect();
-          }
-          const response = await requestBridgeWithRetry(callClient, method, call.params || {}, {
+      const startTime = Date.now();
+      const callClient = destinationId
+        ? await createBridgeClientForDestination(destinationId)
+        : client;
+      if (!callClient) {
+        return summarizeBatchErrorItem(
+          {
+            method,
             tabId,
-            source: REQUEST_SOURCE,
-            tokenBudget,
-          });
-          return {
-            destinationId,
-            ...summarizeBatchResponseItem({
+            error: new Error('A local bridge client is required for calls without destinationId.'),
+            durationMs: Date.now() - startTime,
+          },
+          { compact: true }
+        );
+      }
+      try {
+        if (destinationId) {
+          await callClient.connect();
+        }
+        const response = await requestBridgeWithRetry(callClient, method, call.params || {}, {
+          tabId,
+          source: REQUEST_SOURCE,
+          tokenBudget,
+        });
+        return {
+          destinationId,
+          ...summarizeBatchResponseItem(
+            {
               method,
               tabId,
               response,
               durationMs: Date.now() - startTime,
-            }),
-          };
-        } catch (error) {
-          return summarizeBatchErrorItem({
+            },
+            { compact: true }
+          ),
+        };
+      } catch (error) {
+        return summarizeBatchErrorItem(
+          {
             method,
             tabId,
             error,
             durationMs: Date.now() - startTime,
-          });
-        } finally {
-          if (destinationId) {
-            await callClient.close();
-          }
+          },
+          { compact: true }
+        );
+      } finally {
+        if (destinationId) {
+          await callClient.close();
         }
-      })
-    );
+      }
+    });
 
     const failureCount = results.filter((result) => !result.ok).length;
     const summary =
@@ -199,11 +252,42 @@ export async function handleBatchTool(args) {
       summary,
       {
         ok: failureCount === 0,
+        successCount: results.length - failureCount,
+        failureCount,
+        compactOutput: true,
         results,
       },
       failureCount > 0
     );
-  });
+  };
+
+  return calls.every((call) => typeof call?.destinationId === 'string')
+    ? executeBatch(null)
+    : withToolClient(executeBatch);
+}
+
+/**
+ * @template T, R
+ * @param {T[]} values
+ * @param {number} concurrency
+ * @param {(value: T, index: number) => Promise<R>} callback
+ * @returns {Promise<R[]>}
+ */
+async function mapWithConcurrency(values, concurrency, callback) {
+  /** @type {R[]} */
+  const results = new Array(values.length);
+  let nextIndex = 0;
+  const worker = async () => {
+    while (nextIndex < values.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await callback(values[index], index);
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, values.length) }, async () => worker())
+  );
+  return results;
 }
 
 /**
@@ -214,6 +298,9 @@ export async function handleRawCallTool(args) {
   if (!METHOD_SET.has(/** @type {BridgeMethod} */ (args.method))) {
     return summarizeToolError(`Unknown bridge method "${args.method}".`);
   }
+  if (args.method === 'setup.install') {
+    return summarizeToolError('Use browser_setup for setup changes.');
+  }
 
   return withToolClient(
     async (client) => {