@browserbridge/bbx 1.5.0 → 1.5.2

package/README.md

@@ -107,11 +107,13 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 
 1. Install [Browser Bridge from the Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie) in Chrome or another Chromium-based browser
 2. `npm install -g @browserbridge/bbx` - installs the CLI and native host
-3. Run `bbx install`, or target a specific browser with `bbx install --browser edge`, `bbx install --browser brave`, `bbx install --browser chromium`, or `bbx install --browser arc`
+3. Run `bbx install` (Chromium on Linux, Chrome elsewhere), or target a specific browser with `bbx install --browser chrome`, `bbx install --browser edge`, `bbx install --browser brave`, `bbx install --browser chromium`, or `bbx install --browser arc`
 4. In the extension side panel, install MCP or CLI (skill) for your agent of choice
 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.0",
+  "version": "1.5.2",
   "private": false,
   "keywords": [
     "agent-tools",

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

@@ -237,7 +237,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Setup',
     lines: [
-      'bbx install [extension-id] [--browser chrome|edge|brave|chromium|arc] [--all]  Install native messaging manifest',
+      'bbx install [extension-id] [--browser chrome|edge|brave|chromium|arc] [--all]  Install native messaging manifest (Linux defaults to Chromium)',
       'bbx uninstall                                                      Remove native host manifests, Browser Bridge runtime files, and managed MCP/skill installs',
       'bbx install-skill [targets|all] [--global] [--project <path>]      Install/update the managed Browser Bridge CLI skill',
       'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf|agents',

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>}
@@ -113,7 +116,7 @@ export async function withBridgeClient(callback) {
 }
 
 /**
- * @param {SupportedBrowser} [browser='chrome']
+ * @param {SupportedBrowser} [browser]
  * @returns {string}
  */
 export function getManifestPath(browser) {
@@ -121,7 +124,7 @@ export function getManifestPath(browser) {
 }
 
 /**
- * @param {SupportedBrowser} [browser='chrome']
+ * @param {SupportedBrowser} [browser]
  * @returns {Promise<{allowed_origins?: string[]} | null>}
  */
 export async function loadInstalledManifest(browser) {
@@ -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/bin/install-manifest.js

@@ -9,7 +9,7 @@ import {
   parseExtensionId,
   uninstallNativeManifest,
 } from '../src/install-manifest.js';
-import { SUPPORTED_BROWSERS } from '../src/config.js';
+import { getDefaultBrowser, SUPPORTED_BROWSERS } from '../src/config.js';
 
 /** @typedef {import('../src/config.js').SupportedBrowser} SupportedBrowser */
 
@@ -61,7 +61,7 @@ const targets = installAll
   ? [...SUPPORTED_BROWSERS]
   : browsers.length > 0
     ? browsers
-    : [/** @type {SupportedBrowser} */ ('chrome')];
+    : [getDefaultBrowser()];
 
 for (const [index, target] of targets.entries()) {
   if (uninstall) {

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

@@ -1,5 +1,6 @@
 // @ts-check
 
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -189,14 +190,37 @@ export function getLauncherFilename() {
  */
 export const SUPPORTED_BROWSERS = ['chrome', 'edge', 'brave', 'chromium', 'arc'];
 
+/**
+ * @returns {SupportedBrowser}
+ */
+export function getDefaultBrowser() {
+  return os.platform() === 'linux' ? 'chromium' : 'chrome';
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} home
+ * @returns {string}
+ */
+function getLinuxConfigHome(env, home) {
+  if (env.CHROME_CONFIG_HOME) {
+    return env.CHROME_CONFIG_HOME;
+  }
+  if (env.XDG_CONFIG_HOME) {
+    return env.XDG_CONFIG_HOME;
+  }
+  return path.join(home, '.config');
+}
+
 /**
  * Return the native messaging host manifest install directory for the given
  * browser on the current platform.
  *
- * @param {SupportedBrowser} [browser='chrome']
+ * @param {SupportedBrowser} [browser=getDefaultBrowser()]
+ * @param {NodeJS.ProcessEnv} [env=process.env]
  * @returns {string}
  */
-export function getManifestInstallDir(browser = 'chrome') {
+export function getManifestInstallDir(browser = getDefaultBrowser(), env = process.env) {
   const platform = os.platform();
   const home = os.homedir();
 
@@ -213,7 +237,7 @@ export function getManifestInstallDir(browser = 'chrome') {
   }
 
   if (platform === 'win32') {
-    const winBase = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    const winBase = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
     const winPaths = {
       chrome: path.join(winBase, 'Google', 'Chrome', 'User Data', 'NativeMessagingHosts'),
       edge: path.join(winBase, 'Microsoft', 'Edge', 'User Data', 'NativeMessagingHosts'),
@@ -231,12 +255,18 @@ export function getManifestInstallDir(browser = 'chrome') {
   }
 
   // Linux / others
+  const linuxConfigHome = getLinuxConfigHome(env, home);
+  const chromiumSnapProfile = path.join(home, 'snap', 'chromium', 'common', 'chromium');
+  const useChromiumSnapProfile =
+    !env.CHROME_CONFIG_HOME && !env.XDG_CONFIG_HOME && fs.existsSync(chromiumSnapProfile);
   const linuxPaths = {
-    chrome: path.join(home, '.config', 'google-chrome', 'NativeMessagingHosts'),
-    edge: path.join(home, '.config', 'microsoft-edge', 'NativeMessagingHosts'),
-    brave: path.join(home, '.config', 'BraveSoftware', 'Brave-Browser', 'NativeMessagingHosts'),
-    chromium: path.join(home, '.config', 'chromium', 'NativeMessagingHosts'),
-    arc: path.join(home, '.config', 'Arc', 'User Data', 'NativeMessagingHosts'),
+    chrome: path.join(linuxConfigHome, 'google-chrome', 'NativeMessagingHosts'),
+    edge: path.join(linuxConfigHome, 'microsoft-edge', 'NativeMessagingHosts'),
+    brave: path.join(linuxConfigHome, 'BraveSoftware', 'Brave-Browser', 'NativeMessagingHosts'),
+    chromium: useChromiumSnapProfile
+      ? path.join(chromiumSnapProfile, 'NativeMessagingHosts')
+      : path.join(linuxConfigHome, 'chromium', 'NativeMessagingHosts'),
+    arc: path.join(linuxConfigHome, 'Arc', 'User Data', 'NativeMessagingHosts'),
   };
   return linuxPaths[browser] ?? linuxPaths.chrome;
 }

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 */
@@ -259,13 +263,13 @@ export async function installNativeManifest(options) {
     extensionIdArg,
     browser,
     nodePath = process.execPath,
-    installDir = getManifestInstallDir(browser),
-    bridgeDir = getBridgeDir(),
+    env = process.env,
+    installDir = getManifestInstallDir(browser, env),
+    bridgeDir = getBridgeDir(env),
     stdout = process.stdout,
     stderr = process.stderr,
     preserveCustomExtensionId = false,
     writeRegistryValue: writeRegistryValueFn = writeRegistryValue,
-    env = process.env,
   } = options;
 
   const parsedExtensionId = parseExtensionId(extensionIdArg);
@@ -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/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.