@browserbridge/bbx 1.7.3 → 1.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.7.3",
+  "version": "1.7.4",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -73,13 +73,13 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/chrome": "^0.1.43",
-    "@types/node": "^25.9.2",
+    "@types/chrome": "^0.2.2",
+    "@types/node": "^26.1.1",
     "c8": "^11.0.0",
-    "linkedom": "^0.18.12",
-    "oxfmt": "^0.54.0",
-    "oxlint": "^1.69.0",
-    "typescript": "^6.0.3"
+    "linkedom": "^0.18.13",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0",
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=18"

package/packages/agent-client/src/cli.js

@@ -966,9 +966,9 @@ async function handleProxyCommand(args) {
     const exampleHost = getProxyExampleHost(bindHost);
     const tokenNote =
       tokenSource === 'existing'
-        ? ' (unchanged — already-configured clients keep working; pass --rotate-token to generate a new secret)'
+        ? ' (unchanged - already-configured clients keep working; pass --rotate-token to generate a new secret)'
         : tokenSource === 'generated' && existing
-          ? ' (rotated — update every configured client with `bbx remote add`)'
+          ? ' (rotated - update every configured client with `bbx remote add`)'
           : '';
     const lines = [
       `Browser Bridge proxy enabled on ${bindHost}:${port}.`,

package/packages/agent-client/src/runtime.js

@@ -350,7 +350,7 @@ export async function checkNativeHostManifestHealth(browserManifests) {
  */
 export async function checkUnwritableBridgePaths() {
   // The root-owned-files scenario comes from sudo installs, which do not exist
-  // on Windows — and fs.access(W_OK) there only reflects the read-only file
+  // on Windows - and fs.access(W_OK) there only reflects the read-only file
   // attribute, so it would produce false positives.
   if (os.platform() === 'win32') {
     return [];

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

@@ -10,7 +10,7 @@ export const MCP_SERVER_INSTRUCTIONS = [
   'In permission-ask hosts, use browser_call as the default Browser Bridge MCP tool so the user can approve one BBX tool instead of separate browser_status, browser_page, browser_dom, browser_input, and other tools.',
   'Prefer Browser Bridge MCP tools over shelling out to bbx. Use bbx only for explicit CLI setup, doctor, logs, or raw debugging requests.',
   'Start with browser_call method health.ping. If window access is disabled, call browser_call method access.request once, ask the user to click Enable in the Browser Bridge popup or side panel, then retry once.',
-  'Use structured reads first through browser_call: page.get_state, dom.query, page.get_text, styles.get_computed, or layout.get_box_model. Use browser_batch for parallel reads and keep limits tight before widening.',
+  'Use structured reads first through browser_call: page.get_state, dom.query, page.get_text, styles.get_computed, or layout.get_box_model. Use browser_batch only for parallel reads; run mutations sequentially and keep limits tight before widening.',
   'Reuse elementRef values returned by DOM tools. Use attribute allowlists for focused DOM reads.',
   'Escalate to screenshot.capture_element, screenshot.capture_region, dom.get_accessibility_tree, page.evaluate, viewport.resize, or CDP only when structured reads cannot answer the question.',
   'Use patch.apply_styles or patch.apply_dom for temporary experiments, and rollback patches before finishing unless the user asks to keep them.',

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

@@ -6,7 +6,6 @@ import {
   REQUEST_SOURCE,
   requestBridgeWithRetry,
   resolveToolRef,
-  resolveRef,
   summarizeToolError,
   summarizeToolResponse,
   withToolClient,
@@ -269,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',
@@ -279,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.');
   }
@@ -301,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': {
@@ -311,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,
@@ -329,7 +348,7 @@ export async function handleInputTool(args) {
             client,
             'input.focus',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
             },
             {
               tabId: requestedTabId,
@@ -344,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,
@@ -358,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',
@@ -398,7 +434,7 @@ export async function handleInputTool(args) {
             client,
             'input.set_checked',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
               checked: args.checked,
             },
             {
@@ -414,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,
@@ -432,7 +468,7 @@ export async function handleInputTool(args) {
             client,
             'input.hover',
             {
-              target: await elementTarget(),
+              target: elementTarget(),
               duration: args.duration,
               modifiers: args.modifiers,
             },
@@ -445,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.'
             );
@@ -486,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

@@ -30,6 +30,51 @@ import {
 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: () => ({}) },
@@ -118,54 +163,24 @@ export async function handleBatchTool(args) {
   }
 
   const calls = args.calls;
+  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.`
+      );
+    }
+  }
+
   /** @param {BridgeClient | null} client */
   const executeBatch = async (client) => {
     const results = await mapWithConcurrency(calls, MAX_BATCH_CONCURRENCY, 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,
-        };
-      }
-
-      if (call.method === 'setup.install') {
-        return {
-          method: call.method,
-          tabId: null,
-          ok: false,
-          summary: 'INVALID_REQUEST: Use browser_setup for setup changes.',
-          evidence: null,
-          error: {
-            code: 'INVALID_REQUEST',
-            message: 'Use browser_setup for setup changes.',
-          },
-          response: null,
-        };
-      }
-
       const method = /** @type {BridgeMethod} */ (call.method);
       const tabId = bridgeMethodNeedsTab(method)
         ? typeof call.tabId === 'number'
@@ -180,12 +195,15 @@ export async function handleBatchTool(args) {
         ? await createBridgeClientForDestination(destinationId)
         : client;
       if (!callClient) {
-        return summarizeBatchErrorItem({
-          method,
-          tabId,
-          error: new Error('A local bridge client is required for calls without destinationId.'),
-          durationMs: Date.now() - startTime,
-        });
+        return summarizeBatchErrorItem(
+          {
+            method,
+            tabId,
+            error: new Error('A local bridge client is required for calls without destinationId.'),
+            durationMs: Date.now() - startTime,
+          },
+          { compact: true }
+        );
       }
       try {
         if (destinationId) {
@@ -198,20 +216,26 @@ export async function handleBatchTool(args) {
         });
         return {
           destinationId,
-          ...summarizeBatchResponseItem({
+          ...summarizeBatchResponseItem(
+            {
+              method,
+              tabId,
+              response,
+              durationMs: Date.now() - startTime,
+            },
+            { compact: true }
+          ),
+        };
+      } catch (error) {
+        return summarizeBatchErrorItem(
+          {
             method,
             tabId,
-            response,
+            error,
             durationMs: Date.now() - startTime,
-          }),
-        };
-      } catch (error) {
-        return summarizeBatchErrorItem({
-          method,
-          tabId,
-          error,
-          durationMs: Date.now() - startTime,
-        });
+          },
+          { compact: true }
+        );
       } finally {
         if (destinationId) {
           await callClient.close();
@@ -228,6 +252,9 @@ export async function handleBatchTool(args) {
       summary,
       {
         ok: failureCount === 0,
+        successCount: results.length - failureCount,
+        failureCount,
+        compactOutput: true,
         results,
       },
       failureCount > 0

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

@@ -134,11 +134,17 @@ export function summarizeToolResponse(response, method) {
  */
 export function summarizeToolError(error) {
   const message = error instanceof Error ? error.message : String(error);
+  const record =
+    error && typeof error === 'object' ? /** @type {Record<string, unknown>} */ (error) : {};
+  const code = typeof record.code === 'string' ? record.code : 'INTERNAL_ERROR';
+  const recovery = getErrorRecovery(code);
   return createToolResult(
-    `ERROR: ${message}`,
+    `${code}: ${message}${recovery?.hint ? ` ${recovery.hint}` : ''}`,
     {
       ok: false,
       evidence: null,
+      error: { code, message },
+      recovery,
     },
     true
   );
@@ -317,7 +323,10 @@ 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;
+  const recovery =
+    !response.ok && response.error
+      ? (response.error.recovery ?? getErrorRecovery(response.error.code))
+      : null;
   if (!response.ok && recovery?.retry && isRetrySafeBridgeMethod(method, params)) {
     const delay = recovery.retryAfterMs ?? 1000;
     process.stderr.write(

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

@@ -175,14 +175,19 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Tabs',
       description:
-        'List, create, or close browser tabs. Prefer "list" to work in existing tabs; only use "create" when the user explicitly requests a new page.',
+        'List, create, close, or activate browser tabs. Prefer "list" to work in existing tabs; only use "create" when the user explicitly requests a new page.',
       inputSchema: {
         action: z
-          .enum(['list', 'create', 'close'])
-          .describe('"list" (preferred), "create" (only when needed), or "close"'),
+          .enum(['list', 'create', 'close', 'activate'])
+          .describe('"list" (preferred), "create" (only when needed), "close", or "activate"'),
         url: z.string().optional().describe('URL for create action'),
         active: z.boolean().optional().describe('Focus the new tab (default: true)'),
-        tabId: z.number().int().positive().optional().describe('Tab ID (required for close)'),
+        tabId: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('Tab ID (required for close/activate)'),
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
       },
     },
@@ -194,7 +199,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser DOM',
       description:
-        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed — use query/find first.',
+        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed - use query/find first.',
       inputSchema: {
         action: z
           .enum([
@@ -270,7 +275,9 @@ export function createBridgeMcpServer() {
         state: z
           .enum(['attached', 'detached', 'visible', 'hidden'])
           .optional()
-          .describe('Expected element state (for wait action)'),
+          .describe(
+            'Expected element state (for wait action); hidden also matches complete absence'
+          ),
         timeoutMs: z
           .number()
           .int()
@@ -334,7 +341,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Page State',
       description:
-        'Read page-level data: state (URL/title), evaluate (JS), console, storage, text, network, or performance. For element-level reads, use browser_dom. evaluate and performance are debugger-backed — prefer lighter reads first.',
+        'Read page-level data: state (URL/title), evaluate (JS), console, storage, text, network, or performance. For element-level reads, use browser_dom. evaluate and performance are debugger-backed - prefer lighter reads first.',
       inputSchema: {
         action: z
           .enum([
@@ -370,9 +377,11 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Return actual value vs JSON (default: true)'),
         level: z
-          .string()
+          .enum(['all', 'debug', 'log', 'info', 'warn', 'error', 'exception', 'rejection'])
           .optional()
-          .describe('Minimum console level: log, warn, error (default: all)'),
+          .describe(
+            'Minimum console severity (default: all); exception/rejection select that exact stream'
+          ),
         clear: z.boolean().optional().describe('Clear buffer after reading (default: false)'),
         limit: z
           .number()
@@ -405,7 +414,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Navigation',
       description:
-        'Navigate to a URL, reload, go back/forward, scroll, or resize the viewport. resize is debugger-backed — use only for exact viewport overrides.',
+        'Navigate to a URL, reload, go back/forward, scroll, or resize the viewport. resize is debugger-backed - use only for exact viewport overrides.',
       inputSchema: {
         action: z
           .enum(['navigate', 'reload', 'go_back', 'go_forward', 'scroll', 'resize'])
@@ -456,6 +465,7 @@ export function createBridgeMcpServer() {
             'click',
             'focus',
             'type',
+            'fill',
             'press_key',
             'cdp_press_key',
             'set_checked',
@@ -488,6 +498,11 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Click count (1=single, 2=double)'),
         text: z.string().max(100000).optional().describe('Text to type (for type action)'),
+        value: z.string().max(100000).optional().describe('Value to set (for fill action)'),
+        mode: z
+          .enum(['auto', 'setter', 'keystrokes'])
+          .optional()
+          .describe('Fill strategy (default: auto)'),
         clear: z.boolean().optional().describe('Clear field before typing (default: false)'),
         submit: z.boolean().optional().describe('Press Enter after typing (default: false)'),
         key: z
@@ -594,7 +609,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Capture',
       description:
-        'Capture screenshots or CDP snapshots. Debugger-backed and token-expensive — use only when structured reads (browser_dom, browser_styles_layout) are insufficient. Prefer element, then tight region; full_page only for document-level context.',
+        'Capture screenshots or CDP snapshots. Debugger-backed and token-expensive - use only when structured reads (browser_dom, browser_styles_layout) are insufficient. Prefer element, then tight region; full_page only for document-level context.',
       inputSchema: {
         action: z
           .enum([
@@ -645,7 +660,13 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Bridge Batch',
       description:
-        'Execute multiple bridge calls in parallel to reduce round-trips. Combine independent reads (e.g., styles + text + console) in one call. Preserves call order in the response.',
+        'Execute independent read-only bridge calls in parallel to reduce round-trips. Mutations and destructive reads are rejected; run them sequentially with specialized tools or browser_call. Preserves call order in the response.',
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
       inputSchema: {
         calls: z
           .array(

package/packages/native-host/src/daemon.js

@@ -602,7 +602,9 @@ export class BridgeDaemon {
 
     if (message?.type === 'agent.request') {
       const isExtensionSetupRequest =
-        socket.__role === 'extension' && message.request?.method === 'setup.install';
+        socket.__role === 'extension' &&
+        (message.request?.method === 'setup.get_status' ||
+          message.request?.method === 'setup.install');
       if (socket.__role !== 'agent' && !isExtensionSetupRequest) {
         return this.rejectMessageForRole(socket, message);
       }

package/packages/protocol/src/capabilities.js

@@ -64,7 +64,7 @@ export const METHOD_CAPABILITIES = Object.freeze({
   'page.get_storage': CAPABILITIES.PAGE_READ,
   'page.get_text': CAPABILITIES.PAGE_READ,
   'page.get_network': CAPABILITIES.NETWORK_READ,
-  // Interception mutates traffic (block/forge responses) — distinct from
+  // Interception mutates traffic (block/forge responses) - distinct from
   // passive network reads so hosts can gate it independently.
   'network.intercept.add': CAPABILITIES.NETWORK_INTERCEPT,
   'network.intercept.remove': CAPABILITIES.NETWORK_INTERCEPT,

package/packages/protocol/src/protocol.js

@@ -361,6 +361,7 @@ function normalizeRequestParams(method, params) {
     case 'input.click':
     case 'input.focus':
     case 'input.type':
+    case 'input.fill':
     case 'input.press_key':
       return normalizeInputAction(params);
     case 'cdp.dispatch_key_event':
@@ -412,7 +413,7 @@ export function getBridgeOperationTimeoutMs(method, params = {}) {
     case 'page.evaluate':
       return normalizeEvaluateParams(params).timeoutMs;
     case 'dom.wait_for':
-      return normalizeWaitForParams(params).timeoutMs;
+      return clampInt(params.timeoutMs, 100, 30_000, 5_000);
     default:
       return null;
   }
@@ -423,11 +424,13 @@ export function getBridgeOperationTimeoutMs(method, params = {}) {
  * @returns {NormalizedDomQuery}
  */
 export function normalizeDomQuery(params = {}) {
+  const nestedBudget =
+    params.budget && typeof params.budget === 'object' ? params.budget : undefined;
   return {
     selector:
       typeof params.selector === 'string' && params.selector.trim() ? params.selector : 'body',
     withinRef: typeof params.withinRef === 'string' ? params.withinRef : null,
-    budget: applyBudget(params),
+    budget: applyBudget({ ...nestedBudget, ...params }),
   };
 }
 
@@ -706,9 +709,18 @@ export function normalizeConsoleParams(params = {}) {
  */
 export function normalizeWaitForParams(params = {}) {
   const validStates = ['attached', 'detached', 'visible', 'hidden'];
+  const selector =
+    typeof params.selector === 'string' && params.selector.trim() ? params.selector : '';
+  const text = typeof params.text === 'string' && params.text.trim() ? params.text : null;
+  if (!selector && text === null) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'selector or text is required for dom.wait_for.'
+    );
+  }
   return {
-    selector: typeof params.selector === 'string' && params.selector.trim() ? params.selector : '',
-    text: params.text != null ? String(params.text) : null,
+    selector: selector || '*',
+    text,
     state: validStates.includes(String(params.state ?? ''))
       ? /** @type {'attached' | 'detached' | 'visible' | 'hidden'} */ (String(params.state))
       : 'attached',

package/packages/protocol/src/registry.js

@@ -112,7 +112,7 @@ function createRegistryEntry(method, group, tab, params, complexity = 'low') {
 
 /** @type {Readonly<Record<import('./types.js').BridgeMethod, BridgeMethodRegistryEntry>>} */
 export const BRIDGE_METHOD_REGISTRY = Object.freeze({
-  // system — trivial
+  // system - trivial
   'access.request': createRegistryEntry('access.request', 'system', false, [], 'trivial'),
   'skill.get_runtime_context': createRegistryEntry(
     'skill.get_runtime_context',
@@ -132,12 +132,12 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
   'log.tail': createRegistryEntry('log.tail', 'system', false, ['limit'], 'trivial'),
   'health.ping': createRegistryEntry('health.ping', 'system', false, [], 'trivial'),
   'daemon.metrics': createRegistryEntry('daemon.metrics', 'system', false, [], 'trivial'),
-  // tabs — trivial
+  // tabs - trivial
   'tabs.list': createRegistryEntry('tabs.list', 'tabs', false, [], 'trivial'),
   'tabs.create': createRegistryEntry('tabs.create', 'tabs', false, ['url', 'active'], 'trivial'),
   'tabs.close': createRegistryEntry('tabs.close', 'tabs', false, ['tabId'], 'trivial'),
   'tabs.activate': createRegistryEntry('tabs.activate', 'tabs', false, ['tabId'], 'trivial'),
-  // page — low (basic reads), moderate (evaluate, debugger-backed)
+  // page - low (basic reads), moderate (evaluate, debugger-backed)
   'page.get_state': createRegistryEntry('page.get_state', 'page', true, [], 'low'),
   'page.evaluate': {
     ...createRegistryEntry(
@@ -177,7 +177,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['clear', 'limit', 'urlPattern'],
     'low'
   ),
-  // network intercept — moderate (holds debugger session)
+  // network intercept - moderate (holds debugger session)
   'network.intercept.add': createRegistryEntry(
     'network.intercept.add',
     'page',
@@ -206,7 +206,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     [],
     'low'
   ),
-  // navigation — low
+  // navigation - low
   'navigation.navigate': createRegistryEntry(
     'navigation.navigate',
     'navigate',
@@ -235,7 +235,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['waitForLoad', 'timeoutMs'],
     'low'
   ),
-  // dom — low (reads), moderate (accessibility tree)
+  // dom - low (reads), moderate (accessibility tree)
   'dom.query': {
     ...createRegistryEntry(
       'dom.query',
@@ -303,7 +303,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['maxNodes', 'maxDepth'],
     'moderate'
   ),
-  // layout — low
+  // layout - low
   'layout.get_box_model': createRegistryEntry(
     'layout.get_box_model',
     'inspect',
@@ -312,7 +312,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'low'
   ),
   'layout.hit_test': createRegistryEntry('layout.hit_test', 'inspect', true, ['x', 'y'], 'low'),
-  // styles — low (computed), moderate (matched rules)
+  // styles - low (computed), moderate (matched rules)
   'styles.get_computed': createRegistryEntry(
     'styles.get_computed',
     'inspect',
@@ -327,7 +327,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['elementRef'],
     'moderate'
   ),
-  // viewport — low (scroll), moderate (resize, debugger-backed)
+  // viewport - low (scroll), moderate (resize, debugger-backed)
   'viewport.scroll': createRegistryEntry(
     'viewport.scroll',
     'navigate',
@@ -342,7 +342,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['width', 'height', 'deviceScaleFactor', 'reset'],
     'moderate'
   ),
-  // input — low (simple), moderate (drag)
+  // input - low (simple), moderate (drag)
   'input.click': createRegistryEntry(
     'input.click',
     'interact',
@@ -407,7 +407,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['target'],
     'low'
   ),
-  // capture — high (screenshots, CDP)
+  // capture - high (screenshots, CDP)
   'screenshot.capture_region': createRegistryEntry(
     'screenshot.capture_region',
     'capture',
@@ -429,7 +429,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     [],
     'high'
   ),
-  // patch — moderate (side effects)
+  // patch - moderate (side effects)
   'patch.apply_styles': createRegistryEntry(
     'patch.apply_styles',
     'patch',
@@ -453,7 +453,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     [],
     'low'
   ),
-  // cdp — high (raw protocol, large payloads)
+  // cdp - high (raw protocol, large payloads)
   'cdp.get_document': createRegistryEntry('cdp.get_document', 'cdp', true, [], 'high'),
   'cdp.get_dom_snapshot': createRegistryEntry('cdp.get_dom_snapshot', 'cdp', true, [], 'high'),
   'cdp.get_box_model': createRegistryEntry('cdp.get_box_model', 'cdp', true, ['nodeId'], 'high'),
@@ -471,7 +471,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['key', 'code', 'modifiers'],
     'moderate'
   ),
-  // performance — moderate (debugger-backed)
+  // performance - moderate (debugger-backed)
   'performance.get_metrics': createRegistryEntry(
     'performance.get_metrics',
     'performance',

package/packages/protocol/src/summary.js

@@ -2,6 +2,7 @@
 
 import {
   estimateSerializedPayloadCost,
+  getErrorRecovery,
   getCostClass,
   getProtocolVersion,
   serializeJsonPayload,
@@ -26,7 +27,8 @@ import {
  * @typedef {{
  *   ok: boolean,
  *   summary: string,
- *   evidence: unknown
+ *   evidence: unknown,
+ *   recovery?: import('./types.js').BridgeRecovery | null
  * }} BridgeSummary
  */
 
@@ -49,7 +51,7 @@ import {
  *   approxTokens: number,
  *   meta?: Record<string, unknown>,
  *   error: unknown,
- *   response: unknown
+ *   response?: unknown
  * }} BatchItemSummary
  */
 
@@ -164,14 +166,15 @@ function getMetaCostClass(meta, field) {
 export function summarizeBridgeResponse(response, method) {
   const protocolWarning = getProtocolWarning(response.meta);
   if (!response.ok) {
-    const hint = summarizeErrorHint(response.error.code);
+    const recovery = response.error.recovery ?? getErrorRecovery(response.error.code);
     return {
       ok: false,
       summary: appendProtocolWarning(
-        `${response.error.code}: ${response.error.message}${hint ? ` ${hint}` : ''}`,
+        `${response.error.code}: ${response.error.message}${recovery?.hint ? ` ${recovery.hint}` : ''}`,
         protocolWarning
       ),
       evidence: response.error.details ?? null,
+      recovery,
     };
   }
 
@@ -348,16 +351,38 @@ export function summarizeBridgeResponse(response, method) {
       }
       return entry;
     });
-    let label;
-    if (method === 'dom.find_by_text' || method === 'dom.find_by_role') {
-      label = 'Found';
-    } else {
-      label = 'DOM query returned';
+    const isFind = method === 'dom.find_by_text' || method === 'dom.find_by_role';
+    if (isFind) {
+      const count = typeof result.count === 'number' ? result.count : nodes.length;
+      const scanned = typeof result.scanned === 'number' ? result.scanned : null;
+      const truncated = result.truncated === true;
+      let summary;
+      if (count === 0) {
+        summary = truncated
+          ? `No matching elements returned; search stopped${scanned === null ? '' : ` after scanning ${scanned}`}.`
+          : 'No matching elements found.';
+      } else if (truncated) {
+        summary = `Found ${count} matching element(s); additional matches were omitted.`;
+      } else {
+        summary = `Found ${count} matching element(s)${scanned === null ? '' : ` after scanning ${scanned}`}.`;
+      }
+      return {
+        ok: true,
+        summary: appendProtocolWarning(summary, protocolWarning),
+        evidence: {
+          found: count > 0,
+          count,
+          scanned,
+          truncated,
+          truncationReason: result.truncationReason ?? null,
+          nodes: compact,
+        },
+      };
     }
     return {
       ok: true,
       summary: appendProtocolWarning(
-        `${label} ${nodes.length} element(s)${nodes.length > 15 ? '; showing first 15' : ''}.`,
+        `DOM query returned ${nodes.length} element(s)${nodes.length > 15 ? '; showing first 15' : ''}.`,
         protocolWarning
       ),
       evidence: compact,
@@ -666,9 +691,10 @@ export function summarizeBridgeResponse(response, method) {
 
 /**
  * @param {{ method: SummaryMethod, tabId: number | null, response: BridgeResponse, durationMs: number }} input
+ * @param {{ compact?: boolean }} [options]
  * @returns {BatchItemSummary}
  */
-export function summarizeBatchResponseItem({ method, tabId, response, durationMs }) {
+export function summarizeBatchResponseItem({ method, tabId, response, durationMs }, options = {}) {
   const summary = annotateBridgeSummary(summarizeBridgeResponse(response, method), response);
   return {
     method,
@@ -676,17 +702,18 @@ export function summarizeBatchResponseItem({ method, tabId, response, durationMs
     ...summary,
     durationMs,
     approxTokens: summary.transportTokens,
-    meta: response.meta,
+    meta: options.compact ? compactBatchMeta(response.meta) : response.meta,
     error: response.ok ? null : response.error,
-    response: response.ok ? response.result : null,
+    ...(options.compact ? {} : { response: response.ok ? response.result : null }),
   };
 }
 
 /**
  * @param {{ method: SummaryMethod, tabId: number | null, error: unknown, durationMs: number }} input
+ * @param {{ compact?: boolean }} [options]
  * @returns {BatchItemSummary}
  */
-export function summarizeBatchErrorItem({ method, tabId, error, durationMs }) {
+export function summarizeBatchErrorItem({ method, tabId, error, durationMs }, options = {}) {
   const message = error instanceof Error ? error.message : String(error);
   const response = /** @type {BridgeResponse} */ ({
     id: 'batch_error',
@@ -706,12 +733,30 @@ export function summarizeBatchErrorItem({ method, tabId, error, durationMs }) {
     ...summary,
     durationMs,
     approxTokens: 0,
-    meta: response.meta,
+    meta: options.compact ? compactBatchMeta(response.meta) : response.meta,
     error: response.error,
-    response: null,
+    ...(options.compact ? {} : { response: null }),
   };
 }
 
+/**
+ * @param {Record<string, unknown>} meta
+ * @returns {Record<string, unknown>}
+ */
+function compactBatchMeta(meta) {
+  /** @type {Record<string, unknown>} */
+  const compact = {};
+  for (const key of [
+    'protocol_version',
+    'protocol_warning',
+    'budget_truncated',
+    'continuation_hint',
+  ]) {
+    if (meta[key] !== undefined && meta[key] !== null) compact[key] = meta[key];
+  }
+  return compact;
+}
+
 /**
  * @param {unknown} value
  * @returns {Record<string, unknown>}
@@ -758,20 +803,6 @@ function truncateUrl(url) {
   }
 }
 
-/**
- * @param {string} code
- * @returns {string}
- */
-function summarizeErrorHint(code) {
-  if (code === 'ELEMENT_STALE') {
-    return 'Re-query the current page after navigation or DOM updates.';
-  }
-  if (code === 'RESULT_TRUNCATED') {
-    return 'Narrow the query or raise the relevant budget if more detail is required.';
-  }
-  return '';
-}
-
 /**
  * Check if an array looks like a list of patch entries.
  * Returns true for empty arrays when method context suggests patch.list.

package/packages/protocol/src/types.ts

@@ -140,6 +140,7 @@ export interface BridgeRecovery {
   hint: string;
   retry?: boolean;
   retryAfterMs?: number;
+  alternativeMethod?: string;
 }
 
 export interface BridgeFailure {
@@ -192,6 +193,7 @@ export interface TruncateResult {
 export interface DomQueryParams extends BudgetOptions {
   selector?: string;
   withinRef?: string | null;
+  budget?: BudgetOptions;
 }
 
 export interface NormalizedDomQuery extends BridgeParams {
@@ -200,6 +202,15 @@ export interface NormalizedDomQuery extends BridgeParams {
   budget: Budget;
 }
 
+export interface DomFindResult {
+  found: boolean;
+  nodes: Record<string, unknown>[];
+  count: number;
+  scanned: number;
+  truncated: boolean;
+  truncationReason: 'maxResults' | 'scanLimit' | null;
+}
+
 export interface StyleQueryParams {
   elementRef?: string;
   target?: InputTarget;

package/skills/browser-bridge/SKILL.md

@@ -5,7 +5,7 @@ description: 'Token-efficient Chrome tab inspection, interaction, and patching v
 
 # Browser Bridge
 
-Token-efficient Chrome tab inspection, interaction, and CSS/DOM patching through a local native-messaging bridge. Reads structured DOM, styles, layout, console, storage, network, and applies reversible patches — all from the real tab the user already has open.
+Token-efficient Chrome tab inspection, interaction, and CSS/DOM patching through a local native-messaging bridge. Reads structured DOM, styles, layout, console, storage, network, and applies reversible patches - all from the real tab the user already has open.
 
 This CLI skill is for agents that can run shell commands and where direct `bbx` control fits better than MCP tools: manual debugging, terminal reproduction, install/doctor flows, raw protocol access, or environments without MCP.
 
@@ -235,7 +235,7 @@ bbx page-text 2000                                  # extract page content
 | Inspect     | `dom.query`, `dom.describe`, `dom.get_html`, `styles.get_computed`, `layout.get_box_model`                                                          |
 | Find        | `dom.find_by_text`, `dom.find_by_role`, `dom.wait_for`, `dom.get_accessibility_tree`                                                                |
 | Page State  | `page.get_console`, `page.get_storage`, `page.get_text`, `page.wait_for_load_state`, `page.evaluate` (debugger-backed)                              |
-| Network     | `page.get_network`, `network.intercept.add/remove/list/clear` (debugger-backed; rules are in-memory and drop if the debugger detaches — verify with `list`) |
+| Network     | `page.get_network`, `network.intercept.add/remove/list/clear` (debugger-backed; rules are in-memory and drop if the debugger detaches - verify with `list`) |
 | Interact    | `input.click`, `input.type`, `input.fill`, `input.focus`, `input.press_key`, `cdp.dispatch_key_event`, `input.hover`, `input.drag`, `input.scroll_into_view` |
 | Tabs        | `tabs.list` (preferred), `tabs.create` (avoid unless necessary), `tabs.close`, `tabs.activate`                                                      |
 | Patch       | `patch.apply_styles`, `patch.apply_dom`, `patch.rollback`                                                                                           |
@@ -291,7 +291,7 @@ dom.find_by_role('button', 'Login') → input.click
 
 `bbx a11y-tree` and `dom.get_accessibility_tree` are sensitive to `maxDepth` and `maxNodes`. Shallow runs can undercount interactive nodes on real pages, so widen those limits before treating a low interactive count as a bug.
 
-> **MCP mode:** If Browser Bridge is connected via MCP (tools named `browser_dom`, `browser_capture`, etc.), use the MCP tools directly — do not shell out to `bbx`. The MCP tools map 1:1 to CLI capabilities. In prompts, `BB MCP` and `Browser Bridge MCP` both work. Do not treat `bbx-mcp` as a skill alias.
+> **MCP mode:** If Browser Bridge is connected via MCP (tools named `browser_dom`, `browser_capture`, etc.), use the MCP tools directly - do not shell out to `bbx`. The MCP tools map 1:1 to CLI capabilities. In prompts, `BB MCP` and `Browser Bridge MCP` both work. Do not treat `bbx-mcp` as a skill alias.
 >
 > For open-ended MCP inspection tasks, prefer `browser_investigate` first. It is read-only, designed for cheaper delegated investigation, and falls back to a deterministic sequence when the client cannot delegate. Escalate to `browser_capture` only when the structured investigation is not enough.
 

package/skills/browser-bridge/references/interaction.md

@@ -195,7 +195,7 @@ bbx call input.select_option '{"target":{"elementRef":"el_456"},"values":["us"]}
 
 Select by value, label, or index. Multiple values for multi-select.
 
-**Text fields — `fill` vs `type`:**
+**Text fields - `fill` vs `type`:**
 
 ```bash
 bbx fill el_123 hello@example.com        # set value instantly (preferred for forms)

package/skills/browser-bridge/references/protocol.md

@@ -121,7 +121,7 @@ bbx access-request
 bbx call access.request
 ```
 
-If a tab-bound call returns `ACCESS_DENIED`, it also surfaces the Enable prompt automatically — so explicit `access.request` is optional but useful for proactive setup.
+If a tab-bound call returns `ACCESS_DENIED`, it also surfaces the Enable prompt automatically - so explicit `access.request` is optional but useful for proactive setup.
 
 If access is already pending for a window, do not call `access.request` again. Ask the user to click `Enable` for the requested window and wait for confirmation before continuing.
 
@@ -139,7 +139,7 @@ bbx call page.evaluate '{"expression":"await fetch(\"/api/health\").then(r=>r.js
 
 ### page.get_console
 
-Read buffered console output. The console interceptor is auto-installed on first call. Captures `log`, `warn`, `error`, `info`, `debug` plus uncaught exceptions and unhandled rejections.
+Read buffered console output. The console interceptor is auto-installed on first call. Captures `log`, `warn`, `error`, `info`, `debug` plus uncaught exceptions and unhandled rejections. `level` is a minimum severity, so `warn` includes errors, exceptions, and rejections; `exception` and `rejection` select only that exact stream.
 
 To capture a reproduction reliably, call it once with `clear: true` before triggering the event. This installs the interceptor and removes older entries. Reproduce the issue, then read again without `clear`.
 
@@ -182,7 +182,7 @@ If `_registryPruned` is true, refresh previously cached refs before reusing them
 
 ### dom.wait_for
 
-Wait for a DOM condition using MutationObserver + 250 ms polling fallback. Returns `{found, elementRef, duration}`.
+Wait for a DOM condition using MutationObserver + 250 ms polling fallback. A text-only wait searches all elements. `hidden` succeeds when no matching visible element remains, including when it is absent. Returns `{found, elementRef, duration}`.
 
 - `state`: `attached` (default), `detached`, `visible`, `hidden`
 - `text`: optional text content filter