@browserbridge/bbx 1.5.1 → 1.6.0

package/README.md

@@ -112,6 +112,8 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 5. Enable Browser Bridge for the browser window you want to inspect/control with the AI agent
 6. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the installed Browser Bridge skill in CLI mode (`/browser-bridge`, `browser-bridge`, or the client-specific skill trigger)
 
+On Ubuntu, Chromium is commonly installed as a strict snap, and Flatpak Chromium is similarly sandboxed. If native messaging stays disconnected there, use a non-sandboxed Chromium-based browser such as Google Chrome, Brave, or Edge.
+
 MCP mode is self-contained: the server exposes tools, startup instructions, and prompt templates, so a separate CLI skill is not required for MCP guidance.
 
 ## How it works
@@ -129,6 +131,7 @@ MCP mode is self-contained: the server exposes tools, startup instructions, and
 - [Quickstart](https://github.com/koltyakov/browser-bridge/blob/main/docs/quickstart.md)
 - [Usage scenarios](https://github.com/koltyakov/browser-bridge/blob/main/docs/usage-scenarios.md)
 - [Manual setup](https://github.com/koltyakov/browser-bridge/blob/main/docs/manual-setup.md)
+- [Agent permissions](https://github.com/koltyakov/browser-bridge/blob/main/docs/agent-permissions.md)
 - [CLI guide](https://github.com/koltyakov/browser-bridge/blob/main/docs/cli-guide.md)
 - [MCP vs CLI](https://github.com/koltyakov/browser-bridge/blob/main/docs/mcp-vs-cli.md)
 - [Troubleshooting](https://github.com/koltyakov/browser-bridge/blob/main/docs/troubleshooting.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -69,15 +69,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/chrome": "^0.1.40",
-    "@types/node": "^25.5.2",
+    "@types/chrome": "^0.1.43",
+    "@types/node": "^25.9.2",
     "c8": "^11.0.0",
     "linkedom": "^0.18.12",
-    "oxfmt": "^0.47.0",
-    "oxlint": "^1.62.0",
+    "oxfmt": "^0.54.0",
+    "oxlint": "^1.69.0",
     "typescript": "^6.0.3"
   },
   "engines": {

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

@@ -476,6 +476,23 @@ async function main() {
       return;
     }
 
+    if (command === 'tab-activate') {
+      const [tabId] = rest;
+      if (!tabId) {
+        throw new Error('Usage: tab-activate <tabId>');
+      }
+      const response = await requestBridge(
+        client,
+        'tabs.activate',
+        {
+          tabId: parseIntArg(tabId, 'tabId'),
+        },
+        { source: REQUEST_SOURCE }
+      );
+      await printSummary(response);
+      return;
+    }
+
     if (command === 'call') {
       const { tabId, method, params } = await parseCallCommand(rest);
       const response = await requestBridge(client, method, params, {
@@ -580,18 +597,47 @@ async function main() {
 
     const shortcutCmd = SHORTCUT_COMMANDS[command];
     if (shortcutCmd) {
-      let elementRef;
-      if (shortcutCmd.resolve) {
-        if (!rest[0]) throw new Error(`Usage: ${command} <ref|selector>`);
-        elementRef = await resolveRef(client, rest[0], null, REQUEST_SOURCE);
+      // Allow `bbx <shortcut> --tab <id> ...` to target a specific tab.
+      // Without this, --tab gets eaten as a positional argument and the
+      // request hits whatever tab the bridge route happens to be pointing
+      // at (typically the active tab). For element-resolving shortcuts
+      // the ref must be resolved against the SAME tab the action targets,
+      // so we pass tabId to both resolveRef and the subsequent request.
+      const { tabId, rest: shortcutArgs } = extractTabFlag(rest);
+      const selectorInput = shortcutCmd.resolve ? shortcutArgs[0] : null;
+      if (shortcutCmd.resolve && !selectorInput) {
+        throw new Error(`Usage: ${command} <ref|selector>`);
       }
-      const response = await requestBridge(
-        client,
-        shortcutCmd.method,
-        shortcutCmd.build(rest, elementRef),
-        { source: REQUEST_SOURCE }
-      );
-      await printSummary(response, shortcutCmd.printMethod);
+
+      // Retry-on-stale: if the action fails with ELEMENT_STALE and the
+      // original input was a selector (not an el_xxx ref), re-resolve the
+      // selector and retry once. This handles the common case where the
+      // agent resolved an element, then the page re-rendered (React
+      // reconciliation, SPA navigation) before the action was dispatched.
+      const canRetry = typeof selectorInput === 'string' && !selectorInput.startsWith('el_');
+      const maxAttempts = canRetry ? 2 : 1;
+      /** @type {import('./runtime.js').BridgeResponse | undefined} */
+      let response;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        let elementRef;
+        if (shortcutCmd.resolve && selectorInput) {
+          elementRef = await resolveRef(client, selectorInput, tabId, REQUEST_SOURCE);
+        }
+        response = await requestBridge(
+          client,
+          shortcutCmd.method,
+          shortcutCmd.build(shortcutArgs, elementRef),
+          { source: REQUEST_SOURCE, tabId }
+        );
+        const isStale = !response.ok && response.error?.code === 'ELEMENT_STALE';
+        if (isStale && attempt < maxAttempts) {
+          process.stderr.write(
+            `bbx: ELEMENT_STALE on "${selectorInput}", re-resolving and retrying...\n`
+          );
+        }
+        if (!isStale || attempt >= maxAttempts) break;
+      }
+      if (response) await printSummary(response, shortcutCmd.printMethod);
       return;
     }
 
@@ -664,19 +710,92 @@ async function main() {
       return;
     }
 
+    if (command === 'intercept') {
+      const { tabId, rest: iArgs } = extractTabFlag(rest);
+      const sub = iArgs[0];
+      if (sub === 'add') {
+        const pattern = iArgs[1];
+        if (!pattern)
+          throw new Error(
+            'Usage: intercept add <urlPattern> [--respond <body>] [--status <code>] [--block]'
+          );
+        const isBlock = iArgs.includes('--block');
+        const statusIdx = iArgs.indexOf('--status');
+        const statusCode = statusIdx !== -1 ? parseIntArg(iArgs[statusIdx + 1], 'status') : 200;
+        const respondIdx = iArgs.indexOf('--respond');
+        const body =
+          respondIdx !== -1
+            ? iArgs
+                .slice(respondIdx + 1)
+                .filter((a) => !a.startsWith('--'))
+                .join(' ')
+            : undefined;
+        const response = await requestBridge(
+          client,
+          'network.intercept.add',
+          {
+            urlPattern: pattern,
+            action: isBlock ? 'block' : body != null ? 'fulfill' : 'continue',
+            statusCode,
+            body,
+          },
+          { source: REQUEST_SOURCE, tabId }
+        );
+        await printSummary(response);
+      } else if (sub === 'remove') {
+        const ruleId = iArgs[1];
+        if (!ruleId) throw new Error('Usage: intercept remove <ruleId>');
+        const response = await requestBridge(
+          client,
+          'network.intercept.remove',
+          { ruleId },
+          { source: REQUEST_SOURCE, tabId }
+        );
+        await printSummary(response);
+      } else if (sub === 'list') {
+        const response = await requestBridge(
+          client,
+          'network.intercept.list',
+          {},
+          { source: REQUEST_SOURCE, tabId }
+        );
+        await printSummary(response);
+      } else if (sub === 'clear') {
+        const response = await requestBridge(
+          client,
+          'network.intercept.clear',
+          {},
+          { source: REQUEST_SOURCE, tabId }
+        );
+        await printSummary(response);
+      } else {
+        throw new Error('Usage: intercept <add|remove|list|clear> [args]');
+      }
+      return;
+    }
+
     if (command === 'eval') {
-      let expression = rest.join(' ');
+      const { tabId, rest: evalArgs } = extractTabFlag(rest);
+      // --await: wait for the result if the expression returns a Promise
+      const awaitIndex = evalArgs.indexOf('--await');
+      const awaitPromise = awaitIndex !== -1;
+      if (awaitIndex !== -1) evalArgs.splice(awaitIndex, 1);
+
+      let expression = evalArgs.join(' ');
       if (!expression || expression === '-') expression = await readStdin();
       if (!expression)
-        throw new Error('Usage: eval <expression>  (or pipe via stdin: echo "expr" | bbx eval -)');
+        throw new Error(
+          'Usage: eval [--tab <id>] [--await] <expression>  (or pipe via stdin: echo "expr" | bbx eval -)'
+        );
       const response = await requestBridge(
         client,
         'page.evaluate',
         {
           expression,
           returnByValue: true,
+          ...(awaitPromise ? { awaitPromise: true } : {}),
         },
-        { source: REQUEST_SOURCE }
+        { source: REQUEST_SOURCE, tabId }
       );
       await printSummary(response);
       return;

package/packages/agent-client/src/command-registry.js

@@ -76,6 +76,19 @@ export const SHORTCUT_COMMANDS = {
     (r, ref) => ({ target: { elementRef: ref }, text: r.slice(1).join(' ') }),
     { resolve: true }
   ),
+  fill: createShortcutCommand(
+    'input.fill',
+    'bbx fill <ref|selector> <value>',
+    (r, ref) => ({
+      target: { elementRef: ref },
+      value: r.slice(1).join(' '),
+      mode: 'auto',
+    }),
+    {
+      resolve: true,
+      description: 'Set input/textarea value (React/Vue/Angular-safe, auto fallback to keystrokes)',
+    }
+  ),
   hover: createShortcutCommand(
     'input.hover',
     'bbx hover <ref|selector>',
@@ -249,6 +262,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx tabs                                                           List available tabs',
       'bbx tab-create [url]                                               Create a new tab',
       'bbx tab-close <tabId>                                              Close a tab',
+      'bbx tab-activate <tabId>                                           Bring a tab to the foreground',
       'bbx skill                                                          Runtime budget presets and method groups',
       'bbx mcp serve                                                      Start Browser Bridge as an MCP stdio server',
     ],
@@ -261,6 +275,10 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       "bbx batch '[{method,params,tabId?},...]'                           Parallel method calls",
       'Advanced bridge params stay available through `bbx call`, even when shortcuts expose only the common case.',
       'For open-ended investigation, start with `bbx batch` on `page.get_state`, `dom.query`, and `page.get_text` before any screenshot or CDP call.',
+      '',
+      'Interaction methods need a target wrapper (not a bare ref):',
+      '  bbx call input.click \'{"target":{"elementRef":"el_xxx"}}\'',
+      '  bbx call input.type  \'{"target":{"elementRef":"el_xxx"},"text":"hello"}\'',
     ],
   },
   {
@@ -294,7 +312,11 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Page',
     lines: [
-      'bbx eval <expression>                                              Evaluate JS in page context (use - for stdin)',
+      'bbx intercept add <pattern> [--respond <body>] [--block]           Add a request interception rule',
+      'bbx intercept list                                                  List active interception rules',
+      'bbx intercept remove <ruleId>                                       Remove a rule',
+      'bbx intercept clear                                                 Remove all rules',
+      'bbx eval [--await] <expression>                                     Evaluate JS in page context (--await for async, - for stdin)',
       ...[
         'console',
         'network',
@@ -316,7 +338,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Interact',
     lines: [
-      ...['click', 'focus', 'type', 'hover'].map(
+      ...['click', 'focus', 'type', 'fill', 'hover'].map(
         (command) =>
           `${SHORTCUT_COMMANDS[command].usage.padEnd(64)} ${SHORTCUT_COMMANDS[command].description}`
       ),

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

@@ -21,6 +21,9 @@ import { BridgeClient } from './client.js';
 /** @typedef {import('./types.js').DoctorReport} DoctorReport */
 /** @typedef {import('./types.js').DoctorReportOptions} DoctorReportOptions */
 
+const CHROMIUM_SANDBOXED_MANIFEST_RE =
+  /(?:^|[/\\])(?:snap[/\\]chromium|\.var[/\\]app[/\\]org\.chromium\.Chromium)[/\\]/;
+
 /**
  * @param {BridgeClient} client
  * @returns {Promise<void>}
@@ -164,6 +167,12 @@ export async function getDoctorReport(options = {}) {
 
   const browserManifests = await (options.checkBrowserManifests || checkBrowserManifests)();
   const manifestInstalled = Boolean(manifest) || browserManifests.some((b) => b.installed);
+  const chromiumSandboxedManifestInstalled = browserManifests.some(
+    (entry) =>
+      entry.installed &&
+      entry.browser === 'chromium' &&
+      CHROMIUM_SANDBOXED_MANIFEST_RE.test(entry.manifestPath)
+  );
 
   /** @type {DoctorReport} */
   const report = {
@@ -228,6 +237,12 @@ export async function getDoctorReport(options = {}) {
   }
   if (report.daemonReachable && !report.extensionConnected) {
     report.issues.push('extension_disconnected');
+    if (chromiumSandboxedManifestInstalled) {
+      report.issues.push('chromium_sandboxed_native_host_limited');
+      report.nextSteps.push(
+        "Detected a sandboxed Chromium native host manifest for snap or Flatpak. Sandboxed Chromium may not be able to launch Browser Bridge's Node-based native host; use Google Chrome, Brave, or Edge from a non-sandboxed package and run `bbx install --browser <browser>`."
+      );
+    }
     report.nextSteps.push(
       'Open Chrome and make sure the Browser Bridge extension is installed and active.'
     );

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

@@ -7,12 +7,14 @@ import * as z from 'zod/v4';
 
 export const MCP_SERVER_INSTRUCTIONS = [
   "Browser Bridge MCP inspects and interacts with the user's real Chrome tab through typed MCP tools.",
+  '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.',
-  'Call browser_status first. If window access is disabled, call browser_access once, ask the user to click Enable in the Browser Bridge popup or side panel, then retry once.',
-  'Use structured reads first: browser_page, browser_dom, browser_styles_layout, and browser_batch. Keep budgetPreset quick or normal before widening.',
+  '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, layout.get_box_model, or batch. Keep budgets quick or normal before widening.',
   'Reuse elementRef values returned by DOM tools. Use attribute allowlists for focused DOM reads.',
-  'Escalate to browser_capture, accessibility_tree, page evaluate, viewport resize, or CDP only when structured reads cannot answer the question.',
-  'Use browser_patch for temporary style or DOM experiments, and rollback patches before finishing unless the user asks to keep them.',
+  'Escalate to screenshot.capture_element, screenshot.capture_region, 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.',
+  'Only use the specialized Browser Bridge MCP tools directly when the host has already allowed them or the user explicitly wants typed tool calls.',
 ].join('\n');
 
 export const MCP_GUIDANCE_PROMPT_NAMES = Object.freeze([
@@ -97,13 +99,15 @@ function createGuidePrompt() {
       'Use Browser Bridge MCP for this browser task.',
       '',
       'Rules:',
-      '1. Prefer MCP tools over `bbx`; do not shell out unless setup, doctor, logs, or raw CLI debugging is explicitly needed.',
-      '2. Call `browser_status` first. If access is disabled, call `browser_access` once, ask the user to click Enable, then retry once.',
-      '3. Start with structured reads: `browser_page` action `state`, `browser_dom` action `query`/`find_text`/`find_role`, `browser_styles_layout`, and `browser_batch`.',
-      '4. Keep budgets tight with `budgetPreset: "quick"` or `"normal"`; widen only when results are truncated.',
-      '5. Reuse `elementRef` values returned by DOM tools instead of rescanning.',
-      '6. Escalate to `browser_capture`, accessibility tree, `browser_page` evaluate, viewport resize, or CDP only when structured reads cannot answer.',
-      '7. Use `browser_patch` for temporary style/DOM experiments and rollback before finishing unless the user asks to keep patches.',
+      '1. Prefer MCP over `bbx`; do not shell out unless setup, doctor, logs, or raw CLI debugging is explicitly needed.',
+      '2. In permission-ask hosts, use `browser_call` as the default tool so the user can approve one BBX MCP tool instead of separate tools for status, page, DOM, input, and patches.',
+      '3. Start with `browser_call` method `health.ping`. If access is disabled, call `browser_call` method `access.request` once, ask the user to click Enable, then retry once.',
+      '4. Start with structured reads via `browser_call`: `page.get_state`, `dom.query`, `dom.find_by_text`, `dom.find_by_role`, `styles.get_computed`, and `batch`.',
+      '5. Keep budgets tight with `budgetPreset: "quick"` or `"normal"`; widen only when results are truncated.',
+      '6. Reuse `elementRef` values returned by DOM tools instead of rescanning.',
+      '7. Escalate to screenshots, accessibility tree, `page.evaluate`, viewport resize, or CDP only when structured reads cannot answer.',
+      '8. Use `patch.apply_styles` or `patch.apply_dom` for temporary experiments and rollback before finishing unless the user asks to keep patches.',
+      '9. Only use specialized Browser Bridge MCP tools directly when the host has already allowed them or the user explicitly wants typed tool calls.',
       '',
       'Return concise findings with evidence. Edit source code only after the live page behavior is understood.',
     ].join('\n')

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

@@ -656,7 +656,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Raw Browser Bridge Call',
       description:
-        'Call any bridge method directly by name. Escape hatch when grouped tools lack a needed parameter or method.',
+        'Primary Browser Bridge tool for permission-ask hosts: call any bridge method directly by name so the user can approve one BBX MCP tool instead of each specialized tool separately.',
       inputSchema: {
         method: z.string().describe('Bridge method name (e.g., "dom.query", "input.click")'),
         params: z

package/packages/native-host/src/install-manifest.js

@@ -19,6 +19,10 @@ export const DEFAULT_EXTENSION_ID_ENV = 'BROWSER_BRIDGE_EXTENSION_ID';
 export const BUILT_IN_EXTENSION_ID_SOURCE = 'built_in';
 export const INSTALL_NATIVE_MANIFEST_ERROR = 'INSTALL_NATIVE_MANIFEST_FAILED';
 
+const CHROMIUM_SNAP_NATIVE_MESSAGING_RE = /(?:^|[/\\])snap[/\\]chromium[/\\]/;
+const CHROMIUM_FLATPAK_NATIVE_MESSAGING_RE =
+  /(?:^|[/\\])\.var[/\\]app[/\\]org\.chromium\.Chromium[/\\]/;
+
 /** @typedef {import('./config.js').SupportedBrowser} SupportedBrowser */
 /** @typedef {'env' | 'built_in' | 'none' | 'invalid_env'} ExtensionIdSource */
 /** @typedef {NodeJS.ErrnoException & { cause?: unknown }} MaybeErrnoError */
@@ -360,6 +364,18 @@ exec '${escapeSingleQuotes(nodePath)}' '${escapeSingleQuotes(hostPath)}' "$@"
     );
   }
 
+  if (isChromiumSnapManifestInstall(browser, installDir)) {
+    stderr.write(
+      'Compatibility warning: detected a Linux Chromium snap native messaging path. Strict snap Chromium commonly blocks launching Browser Bridge\'s Node-based native host with AppArmor, which leaves `bbx status` at "Extension: disconnected". Use a non-snap Chromium-based browser such as Google Chrome, Brave, or Edge and run `bbx install --browser <browser>`.\n'
+    );
+  }
+
+  if (isChromiumFlatpakManifestInstall(browser, installDir)) {
+    stderr.write(
+      'Compatibility warning: detected a Linux Chromium Flatpak native messaging path. Sandboxed Flatpak Chromium commonly blocks launching Browser Bridge\'s Node-based native host, which leaves `bbx status` at "Extension: disconnected". Use a non-sandboxed Chromium-based browser such as Google Chrome, Brave, or Edge and run `bbx install --browser <browser>`.\n'
+    );
+  }
+
   const hasPlaceholder = allowedOrigins.some((origin) =>
     origin.includes('__REPLACE_WITH_EXTENSION_ID__')
   );
@@ -378,6 +394,24 @@ exec '${escapeSingleQuotes(nodePath)}' '${escapeSingleQuotes(hostPath)}' "$@"
   };
 }
 
+/**
+ * @param {SupportedBrowser | undefined} browser
+ * @param {string} installDir
+ * @returns {boolean}
+ */
+function isChromiumSnapManifestInstall(browser, installDir) {
+  return browser === 'chromium' && CHROMIUM_SNAP_NATIVE_MESSAGING_RE.test(installDir);
+}
+
+/**
+ * @param {SupportedBrowser | undefined} browser
+ * @param {string} installDir
+ * @returns {boolean}
+ */
+function isChromiumFlatpakManifestInstall(browser, installDir) {
+  return browser === 'chromium' && CHROMIUM_FLATPAK_NATIVE_MESSAGING_RE.test(installDir);
+}
+
 /**
  * @param {UninstallManifestOptions} [options={}]
  * @returns {Promise<{ manifestPath: string, bridgeDir: string, removedManifest: boolean, removedBridgeDir: boolean }>}

package/packages/protocol/src/capabilities.js

@@ -22,6 +22,7 @@ export const CAPABILITIES = Object.freeze({
   TABS_MANAGE: 'tabs.manage',
   PERFORMANCE_READ: 'performance.read',
   NETWORK_READ: 'network.read',
+  NETWORK_INTERCEPT: 'network.intercept',
 });
 
 export const DEFAULT_CAPABILITIES = Object.freeze([
@@ -43,6 +44,7 @@ export const DEFAULT_CAPABILITIES = Object.freeze([
   CAPABILITIES.TABS_MANAGE,
   CAPABILITIES.PERFORMANCE_READ,
   CAPABILITIES.NETWORK_READ,
+  CAPABILITIES.NETWORK_INTERCEPT,
 ]);
 
 /** @type {Readonly<Record<CapabilityMethod, Capability | null>>} */
@@ -51,6 +53,7 @@ export const METHOD_CAPABILITIES = Object.freeze({
   'tabs.list': null,
   'tabs.create': CAPABILITIES.TABS_MANAGE,
   'tabs.close': CAPABILITIES.TABS_MANAGE,
+  'tabs.activate': CAPABILITIES.TABS_MANAGE,
   'skill.get_runtime_context': null,
   'setup.get_status': null,
   'setup.install': null,
@@ -61,6 +64,12 @@ 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
+  // passive network reads so hosts can gate it independently.
+  'network.intercept.add': CAPABILITIES.NETWORK_INTERCEPT,
+  'network.intercept.remove': CAPABILITIES.NETWORK_INTERCEPT,
+  'network.intercept.list': CAPABILITIES.NETWORK_INTERCEPT,
+  'network.intercept.clear': CAPABILITIES.NETWORK_INTERCEPT,
   'navigation.navigate': CAPABILITIES.NAVIGATION_CONTROL,
   'navigation.reload': CAPABILITIES.NAVIGATION_CONTROL,
   'navigation.go_back': CAPABILITIES.NAVIGATION_CONTROL,
@@ -83,6 +92,7 @@ export const METHOD_CAPABILITIES = Object.freeze({
   'input.click': CAPABILITIES.AUTOMATION_INPUT,
   'input.focus': CAPABILITIES.AUTOMATION_INPUT,
   'input.type': CAPABILITIES.AUTOMATION_INPUT,
+  'input.fill': CAPABILITIES.AUTOMATION_INPUT,
   'input.press_key': CAPABILITIES.AUTOMATION_INPUT,
   'input.set_checked': CAPABILITIES.AUTOMATION_INPUT,
   'input.select_option': CAPABILITIES.AUTOMATION_INPUT,

package/packages/protocol/src/protocol.js

@@ -380,6 +380,10 @@ function normalizeTarget(target) {
  */
 export function normalizeInputAction(params = {}) {
   const button = params.button === 'middle' || params.button === 'right' ? params.button : 'left';
+  const mode =
+    params.mode === 'setter' || params.mode === 'keystrokes' || params.mode === 'auto'
+      ? params.mode
+      : 'auto';
 
   return {
     target: normalizeTarget(
@@ -390,6 +394,8 @@ export function normalizeInputAction(params = {}) {
     button,
     clickCount: clampInt(params.clickCount, 1, 2, 1),
     text: typeof params.text === 'string' ? params.text : '',
+    value: typeof params.value === 'string' ? params.value : '',
+    mode,
     clear: Boolean(params.clear),
     submit: Boolean(params.submit),
     key: typeof params.key === 'string' ? params.key : '',

package/packages/protocol/src/registry.js

@@ -28,6 +28,7 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'tabs.list': 'List tabs in the enabled window.',
   'tabs.create': 'Create a new tab in the enabled window.',
   'tabs.close': 'Close a tab in the enabled window.',
+  'tabs.activate': 'Bring a tab to the foreground in the enabled window.',
   'skill.get_runtime_context': 'Return runtime method groups, budgets, and limits.',
   'setup.get_status': 'Return MCP and skill setup status.',
   'setup.install': 'Install or uninstall MCP or skill integration targets.',
@@ -38,6 +39,10 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'page.get_storage': 'Read local or session storage values.',
   'page.get_text': 'Read bounded visible text from the page.',
   'page.get_network': 'Read buffered fetch and XHR network activity.',
+  'network.intercept.add': 'Add a request interception rule (CDP Fetch domain).',
+  'network.intercept.remove': 'Remove a request interception rule by ID.',
+  'network.intercept.list': 'List active interception rules.',
+  'network.intercept.clear': 'Remove all interception rules and disable interception.',
   'navigation.navigate': 'Navigate the current tab to a URL.',
   'navigation.reload': 'Reload the current tab.',
   'navigation.go_back': 'Navigate backward in tab history.',
@@ -60,6 +65,7 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'input.click': 'Click an element.',
   'input.focus': 'Focus an element.',
   'input.type': 'Type text into an element.',
+  'input.fill': 'Set value of an input/textarea element (React/Vue/Angular-safe).',
   'input.press_key': 'Send a key press to the page or an element.',
   'input.set_checked': 'Set checkbox or radio checked state.',
   'input.select_option': 'Select options in a select element.',
@@ -130,6 +136,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
   '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.get_state': createRegistryEntry('page.get_state', 'page', true, [], 'low'),
   'page.evaluate': {
@@ -170,6 +177,35 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['clear', 'limit', 'urlPattern'],
     'low'
   ),
+  // network intercept — moderate (holds debugger session)
+  'network.intercept.add': createRegistryEntry(
+    'network.intercept.add',
+    'page',
+    true,
+    ['urlPattern', 'action', 'statusCode', 'body', 'headers'],
+    'moderate'
+  ),
+  'network.intercept.remove': createRegistryEntry(
+    'network.intercept.remove',
+    'page',
+    true,
+    ['ruleId'],
+    'trivial'
+  ),
+  'network.intercept.list': createRegistryEntry(
+    'network.intercept.list',
+    'page',
+    true,
+    [],
+    'trivial'
+  ),
+  'network.intercept.clear': createRegistryEntry(
+    'network.intercept.clear',
+    'page',
+    true,
+    [],
+    'low'
+  ),
   // navigation — low
   'navigation.navigate': createRegistryEntry(
     'navigation.navigate',
@@ -322,6 +358,13 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     ['target', 'text', 'clear', 'submit', 'modifiers'],
     'low'
   ),
+  'input.fill': createRegistryEntry(
+    'input.fill',
+    'interact',
+    true,
+    ['target', 'value', 'mode'],
+    'low'
+  ),
   'input.press_key': createRegistryEntry(
     'input.press_key',
     'interact',

package/packages/protocol/src/types.ts

@@ -18,7 +18,8 @@ export type Capability =
   | 'automation.input'
   | 'tabs.manage'
   | 'performance.read'
-  | 'network.read';
+  | 'network.read'
+  | 'network.intercept';
 
 export type ErrorCode =
   | 'ACCESS_DENIED'
@@ -37,6 +38,7 @@ export type BridgeMethod =
   | 'tabs.list'
   | 'tabs.create'
   | 'tabs.close'
+  | 'tabs.activate'
   | 'skill.get_runtime_context'
   | 'setup.get_status'
   | 'setup.install'
@@ -47,6 +49,10 @@ export type BridgeMethod =
   | 'page.get_storage'
   | 'page.get_text'
   | 'page.get_network'
+  | 'network.intercept.add'
+  | 'network.intercept.remove'
+  | 'network.intercept.list'
+  | 'network.intercept.clear'
   | 'navigation.navigate'
   | 'navigation.reload'
   | 'navigation.go_back'
@@ -69,6 +75,7 @@ export type BridgeMethod =
   | 'input.click'
   | 'input.focus'
   | 'input.type'
+  | 'input.fill'
   | 'input.press_key'
   | 'input.set_checked'
   | 'input.select_option'
@@ -215,6 +222,8 @@ export interface InputActionParams {
   button?: 'left' | 'middle' | 'right';
   clickCount?: number;
   text?: string;
+  value?: string;
+  mode?: 'auto' | 'setter' | 'keystrokes';
   clear?: boolean;
   submit?: boolean;
   key?: string;
@@ -226,6 +235,8 @@ export interface NormalizedInputAction extends BridgeParams {
   button: 'left' | 'middle' | 'right';
   clickCount: number;
   text: string;
+  value: string;
+  mode: 'auto' | 'setter' | 'keystrokes';
   clear: boolean;
   submit: boolean;
   key: string;

package/skills/browser-bridge/SKILL.md

@@ -9,6 +9,8 @@ Token-efficient Chrome tab inspection, interaction, and CSS/DOM patching through
 
 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.
 
+Permission prompts are controlled by the host agent, not by Browser Bridge. In permission-ask MCP hosts, use the generic `browser_call` MCP tool by default so the user can approve one BBX tool instead of separate status, page, DOM, input, and patch tools. In Claude Code CLI mode, allow `bbx` with `Bash(bbx *)` when direct shell access is desired. Exact permission syntax varies by client.
+
 Skill name: `browser-bridge` (also known as `bbx`). In GitHub Copilot, invoke as `/browser-bridge`. `bbx` is the CLI command used throughout this skill.
 When the runtime supports subagents, delegate bridge inspection to a smaller, lower-cost worker and return only concise findings to the parent.
 For open-ended investigation, start with structured reads (`page.get_state`, `dom.query`, `page.get_text`, `styles.get_computed`, `bbx batch`) and escalate to screenshots or debugger-backed methods only when structured evidence is insufficient.
@@ -28,6 +30,7 @@ bbx tabs                    # list available tabs (prefer this)
 bbx logs                    # recent bridge request log
 bbx tab-create [url]        # open a new tab (avoid unless necessary)
 bbx tab-close <tabId>       # close a tab
+bbx tab-activate <tabId>    # bring a tab to the foreground
 bbx skill                   # live runtime presets + limits
 ```
 
@@ -51,9 +54,11 @@ bbx a11y-tree [maxNodes] [maxDepth]  # accessibility tree
 ### Page & Evaluate
 
 ```bash
-bbx eval <expression>                # JS eval (- for stdin)
+bbx eval [--await] <expression>      # JS eval (--await for promises, - for stdin)
 bbx console [level]                  # console output
 bbx network [limit]                  # network requests
+bbx intercept add <pattern> [--respond <body>] [--status <code>] [--block]  # intercept matching requests
+bbx intercept list|remove <id>|clear # manage interception rules
 bbx page-text [budget]               # full page text
 bbx storage [local|session] [keys]   # browser storage
 bbx perf                             # performance metrics
@@ -71,6 +76,7 @@ bbx resize <width> <height>          # resize viewport
 bbx click <ref> [button]             # click element
 bbx focus <ref>                      # focus element
 bbx type <ref> <text...>             # type into element
+bbx fill <ref|selector> <value...>   # set input value (React/Vue/Angular-safe)
 bbx press-key <key> [ref]            # send key event
 bbx cdp-press-key --tab <id> Escape  # CDP key event without foreground focus
 bbx hover <ref>                      # hover over element
@@ -211,9 +217,9 @@ 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`                                                                                                                                  |
-| Interact    | `input.click`, `input.type`, `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`                                                                       |
+| 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`                                                                                           |
 | Navigate    | `navigation.navigate`, `viewport.scroll`, `viewport.resize`                                                                                         |
 | Performance | `performance.get_metrics` (debugger-backed)                                                                                                         |
@@ -281,7 +287,15 @@ Every CLI shortcut command produces consistent `{ok, summary, evidence}` JSON. U
 ## CLI Raw Params Gotchas
 
 - Use `selector`, not `scope`, to narrow `dom.find_by_text` and `dom.find_by_role`.
-- Wrap interaction targets as `target: { elementRef }` or `target: { selector }`; `viewport.scroll` also uses the `target` wrapper for element scrolling.
+- Wrap interaction targets as `target: { elementRef }` or `target: { selector }`; `viewport.scroll` also uses the `target` wrapper for element scrolling. **Do not pass `ref` or `elementRef` at the top level** -- interaction methods require the nested `target` wrapper:
+  ```bash
+  # CORRECT
+  bbx call input.click '{"target":{"elementRef":"el_xxx"}}'
+  bbx call input.type  '{"target":{"elementRef":"el_xxx"},"text":"hello"}'
+  # WRONG -- will fail with "Target not found"
+  bbx call input.click '{"ref":"el_xxx"}'
+  bbx call input.click '{"elementRef":"el_xxx"}'
+  ```
 - `input.drag` uses `source`, `destination`, and optional destination offsets `offsetX` / `offsetY`.
 - Raw `screenshot.capture_region` and `screenshot.capture_full_page` return base64 JSON; prefer `bbx screenshot <ref> [outPath]` when one element is enough.
 

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

@@ -7,6 +7,7 @@
 | `input.click`            | `click <ref> [button]`                | DOM-level click                                             |
 | `input.focus`            | `focus <ref>`                         | Focus an element                                            |
 | `input.type`             | `type <ref> <text>`                   | Type into input/textarea/contenteditable                    |
+| `input.fill`             | `fill <ref> <value>`                  | Set field value via native setter (React/Vue/Angular-safe)  |
 | `input.press_key`        | `press-key <key> [ref]`               | Send keyboard key (Enter, Backspace, etc.)                  |
 | `cdp.dispatch_key_event` | `cdp-press-key --tab <id> <key>`      | CDP keyDown/keyUp without focusing the target tab           |
 | `input.set_checked`      | `call input.set_checked '{...}'`      | Toggle checkbox/radio                                       |
@@ -64,6 +65,7 @@ bbx tabs                                 # list available tabs (start here)
 bbx tab-create https://example.com       # open new tab (avoid unless necessary)
 bbx tab-create                           # open blank tab (avoid unless necessary)
 bbx tab-close 12345                      # close tab by ID
+bbx tab-activate 12345                   # bring a tab to the foreground
 bbx call tabs.create '{"url":"https://example.com","active":false}'
 ```
 
@@ -156,6 +158,24 @@ Typical workflow - debug API calls:
 3. Cross-reference with `page.get_console` for errors
 4. Use `page.evaluate` to replay or inspect response data
 
+## Network Interception
+
+Block, stub, or modify matching requests via CDP (debugger-backed). Patterns are globs: `*` matches any characters, `?` matches one character.
+
+```bash
+bbx intercept add 'https://api.example.com/users*' --respond '{"users":[]}' --status 200
+bbx intercept add '*analytics*' --block      # fail matching requests
+bbx intercept list                           # active rules
+bbx intercept remove intercept_1
+bbx intercept clear                          # remove all rules, detach debugger
+```
+
+Caveats:
+
+- Rules are **in-memory and per-tab**. They drop silently if the debugger detaches (user dismisses the infobar, tab closes, extension service worker restarts). Verify with `bbx intercept list` before relying on them.
+- Sessions auto-expire after 10 minutes as a safety net.
+- Always `bbx intercept clear` when finished so the page returns to normal traffic.
+
 ## Form Controls
 
 **Checkbox/radio:**
@@ -172,6 +192,15 @@ 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`:**
+
+```bash
+bbx fill el_123 hello@example.com        # set value instantly (preferred for forms)
+bbx type el_123 hello                    # simulate per-character keystrokes
+```
+
+Prefer `fill` for setting form values: it uses the native prototype setter plus `input`/`change`/`blur` events, which React, Vue, and Angular pick up reliably. `mode` defaults to `auto` (setter first, keystroke fallback if the value did not stick); pass `"mode":"keystrokes"` via `bbx call input.fill` for components that only react to per-key events. Use `type` when page logic depends on individual key events (autocomplete, masked inputs).
+
 ## Hover
 
 Dispatch mouse events to trigger CSS `:hover` rules, tooltip display, dropdown menus, etc.
@@ -263,6 +292,24 @@ bbx call page.wait_for_load_state '{"timeoutMs":10000}'
 
 Use after clicking navigation links.
 
+## Raw `bbx call` for Interaction Methods
+
+All interaction methods (`input.click`, `input.type`, `input.focus`, `input.hover`, etc.) require the target wrapped in a `target` object -- do not pass `ref` or `elementRef` at the top level:
+
+```bash
+# CORRECT
+bbx call input.click '{"target":{"elementRef":"el_xxx"}}'
+bbx call input.click '{"target":{"elementRef":"el_xxx"},"button":"right"}'
+bbx call input.type  '{"target":{"elementRef":"el_xxx"},"text":"hello"}'
+bbx call input.focus '{"target":{"selector":"#search-input"}}'
+
+# WRONG -- "Target not found"
+bbx call input.click '{"ref":"el_xxx"}'
+bbx call input.click '{"elementRef":"el_xxx"}'
+```
+
+The CLI shortcuts (`bbx click el_xxx`) handle this wrapping automatically, but `bbx call` passes params as-is.
+
 ## Interaction Flow
 
 1. **Find target**: `dom.find_by_text`, `dom.find_by_role`, or `dom.query` → get `elementRef`

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

@@ -90,6 +90,12 @@ The table below includes the legacy capability bucket for each method so agents
 | 57  | `cdp.get_box_model`                | Yes  | CDP  | cdp         | `cdp.box_model`      | DevTools-backed element geometry                                        |
 | 58  | `cdp.get_computed_styles_for_node` | Yes  | CDP  | cdp         | `cdp.styles`         | DevTools-backed computed styles                                         |
 | 59  | `cdp.dispatch_key_event`           | Yes  | CDP  | cdp         | `cdp.input`          | DevTools keyDown/keyUp without foreground focus                         |
+| 60  | `tabs.activate`                    | No   | -    | tabs        | `tabs.manage`        | Bring a tab to the foreground in the enabled window                     |
+| 61  | `input.fill`                       | Yes  | -    | interact    | `automation.input`   | Set field value via native setter; `mode`: auto/setter/keystrokes       |
+| 62  | `network.intercept.add`            | Yes  | CDP  | page        | `network.intercept`  | Add interception rule; action fulfill/continue/block                    |
+| 63  | `network.intercept.remove`         | Yes  | CDP  | page        | `network.intercept`  | Remove rule by `ruleId`                                                 |
+| 64  | `network.intercept.list`           | Yes  | CDP  | page        | `network.intercept`  | List active rules (rules drop on debugger detach)                       |
+| 65  | `network.intercept.clear`          | Yes  | CDP  | page        | `network.intercept`  | Remove all rules, detach debugger                                       |
 
 ## CLI