@browserbridge/bbx 1.4.0 → 1.5.1

package/README.md

@@ -107,7 +107,7 @@ 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "private": false,
   "keywords": [
     "agent-tools",

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

@@ -687,7 +687,7 @@ async function main() {
     process.exitCode = 1;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    const raw = error instanceof Error && 'code' in error ? /** @type {any} */ (error).code : '';
+    const raw = getErrorCode(error);
     let code = 'ERROR';
     if (raw === 'ENOENT' || raw === 'ECONNREFUSED' || raw === 'EINVAL') {
       code = 'DAEMON_OFFLINE';
@@ -709,6 +709,18 @@ async function main() {
   }
 }
 
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function getErrorCode(error) {
+  if (!(error instanceof Error) || !('code' in error)) {
+    return '';
+  }
+  const code = /** @type {{ code?: unknown }} */ (error).code;
+  return typeof code === 'string' ? code : '';
+}
+
 /**
  * Allow tests to shrink request timeouts without changing the shared default.
  *

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/mcp-config.js

@@ -94,29 +94,19 @@ export function getMcpConfigShape(clientName) {
  * }}
  */
 function createBaseServerConfig(clientName) {
-  const windowsCommand =
-    process.platform === 'win32'
-      ? {
-          command: process.execPath,
-          args: [mcpServerBinPath],
-          env: {},
-        }
-      : {
-          command: 'bbx',
-          args: ['mcp', 'serve'],
-          env: {},
-        };
+  const serverConfig = {
+    command: process.execPath,
+    args: [mcpServerBinPath],
+    env: {},
+  };
 
   if (clientName === 'opencode') {
     return {
       type: 'local',
-      command:
-        process.platform === 'win32'
-          ? [process.execPath, mcpServerBinPath]
-          : ['bbx', 'mcp', 'serve'],
+      command: [process.execPath, mcpServerBinPath],
     };
   }
-  return windowsCommand;
+  return serverConfig;
 }
 
 /** @type {Record<McpClientName, { key: string, includeType: boolean, legacyKeys?: string[], keepEmptyBlock?: boolean }>} */
@@ -142,13 +132,11 @@ const MCP_CONFIG_SHAPES = {
  */
 export function buildMcpConfig(clientName) {
   if (clientName === 'codex') {
-    const command = process.platform === 'win32' ? process.execPath : 'bbx';
-    const args = process.platform === 'win32' ? [mcpServerBinPath] : ['mcp', 'serve'];
     return {
       mcp_servers: {
         [BROWSER_BRIDGE_SERVER_NAME]: {
-          command,
-          args,
+          command: process.execPath,
+          args: [mcpServerBinPath],
         },
       },
     };
@@ -277,12 +265,10 @@ export async function getMcpConfigPaths(clientName, options) {
  * @returns {string}
  */
 function formatCodexServerBlock() {
-  const command = process.platform === 'win32' ? process.execPath : 'bbx';
-  const args = process.platform === 'win32' ? [mcpServerBinPath] : ['mcp', 'serve'];
   return [
     `[mcp_servers."${BROWSER_BRIDGE_SERVER_NAME}"]`,
-    `command = ${JSON.stringify(command)}`,
-    `args = ${JSON.stringify(args)}`,
+    `command = ${JSON.stringify(process.execPath)}`,
+    `args = ${JSON.stringify([mcpServerBinPath])}`,
     '',
   ].join('\n');
 }

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

@@ -113,7 +113,7 @@ export async function withBridgeClient(callback) {
 }
 
 /**
- * @param {SupportedBrowser} [browser='chrome']
+ * @param {SupportedBrowser} [browser]
  * @returns {string}
  */
 export function getManifestPath(browser) {
@@ -121,7 +121,7 @@ export function getManifestPath(browser) {
 }
 
 /**
- * @param {SupportedBrowser} [browser='chrome']
+ * @param {SupportedBrowser} [browser]
  * @returns {Promise<{allowed_origins?: string[]} | null>}
  */
 export async function loadInstalledManifest(browser) {
@@ -160,10 +160,10 @@ export async function checkBrowserManifests() {
 export async function getDoctorReport(options = {}) {
   const manifest = await (options.loadManifest || loadInstalledManifest)();
   const allowedOrigins = Array.isArray(manifest?.allowed_origins) ? manifest.allowed_origins : [];
-  const manifestInstalled = Boolean(manifest);
   const defaultExtensionId = options.defaultExtensionIdInfo || resolveDefaultExtensionId();
 
-  const browserManifests = await checkBrowserManifests();
+  const browserManifests = await (options.checkBrowserManifests || checkBrowserManifests)();
+  const manifestInstalled = Boolean(manifest) || browserManifests.some((b) => b.installed);
 
   /** @type {DoctorReport} */
   const report = {
@@ -214,8 +214,6 @@ export async function getDoctorReport(options = {}) {
     report.extensionConnected = false;
   }
 
-  const browsersWithoutManifest = browserManifests.filter((b) => !b.installed);
-
   if (!report.manifestInstalled) {
     report.issues.push('native_host_manifest_missing');
     report.nextSteps.push(
@@ -223,12 +221,6 @@ export async function getDoctorReport(options = {}) {
         ? 'Run `bbx install` (or `bbx install --all` for all browsers) to install the native host manifest.'
         : 'Run `bbx install <extension-id>` (or `bbx install --all`) to install the native host manifest.'
     );
-  } else if (browsersWithoutManifest.length > 0) {
-    report.issues.push('native_host_manifest_partial');
-    const missing = browsersWithoutManifest.map((b) => b.browser).join(', ');
-    report.nextSteps.push(
-      `Manifests missing for: ${missing}. Run \`bbx install --all\` to install for all supported browsers.`
-    );
   }
   if (!report.daemonReachable) {
     report.issues.push('daemon_offline');

package/packages/agent-client/src/types.ts

@@ -67,7 +67,7 @@ export type ClientMessage =
     };
 
 export interface PendingRequest {
-  resolve: (value: any) => void;
+  resolve: (value: unknown) => void;
   reject: (error: Error) => void;
   timeoutId: NodeJS.Timeout;
 }
@@ -118,6 +118,7 @@ export interface DoctorReport {
 
 export interface DoctorReportOptions {
   loadManifest?: () => Promise<{ allowed_origins?: string[] } | null>;
+  checkBrowserManifests?: () => Promise<BrowserManifestStatus[]>;
   manifestPath?: string;
   defaultExtensionIdInfo?: { extensionId: string | null; source: string };
   bridgeClientRunner?: <T>(

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

@@ -87,6 +87,12 @@ export async function handlePageTool(args) {
   }
   const entry = PAGE_ACTIONS[normalizedArgs.action];
   if (!entry) return summarizeToolError(`Unsupported page action "${args.action}".`);
+  if (
+    normalizedArgs.action === 'evaluate' &&
+    (typeof normalizedArgs.expression !== 'string' || !normalizedArgs.expression.trim())
+  ) {
+    return summarizeToolError('expression is required for page evaluate.');
+  }
   return callBridgeTool(entry.method, entry.params(normalizedArgs), {
     tabId: typeof normalizedArgs.tabId === 'number' ? normalizedArgs.tabId : null,
     tokenBudget: getToolTokenBudget(normalizedArgs),

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/daemon-process.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 import { pingExistingDaemon } from './daemon.js';
 import {
+  applyWindowsTcpTransportDefaults,
   createSocketBridgeTransport,
   formatBridgeTransport,
   getBridgeTransport,
@@ -124,7 +125,7 @@ export async function clearDaemonPidFile(options = {}) {
  */
 export async function stopBridgeDaemon(options = {}) {
   const {
-    transport = getBridgeTransport(),
+    transport = undefined,
     socketPath = undefined,
     pidPath = getDaemonPidPath(),
     timeoutMs = DEFAULT_DAEMON_RESTART_TIMEOUT_MS,
@@ -136,7 +137,7 @@ export async function stopBridgeDaemon(options = {}) {
     rmFn = fs.promises.rm,
     sleepFn = sleep,
   } = options;
-  const resolvedTransport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
+  const resolvedTransport = resolveDaemonTransport({ transport, socketPath });
   const resolvedSocketPath =
     resolvedTransport.type === 'socket' ? resolvedTransport.socketPath : '';
 
@@ -238,7 +239,7 @@ export async function restartBridgeDaemonIfRunning(options = {}) {
  */
 async function restartBridgeDaemonAfterStop(stopResult, options = {}) {
   const {
-    transport = getBridgeTransport(),
+    transport = undefined,
     socketPath = undefined,
     pidPath = getDaemonPidPath(),
     timeoutMs = DEFAULT_DAEMON_RESTART_TIMEOUT_MS,
@@ -248,7 +249,7 @@ async function restartBridgeDaemonAfterStop(stopResult, options = {}) {
     sleepFn = sleep,
     spawnDaemonFn = spawnBridgeDaemonProcess,
   } = options;
-  const resolvedTransport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
+  const resolvedTransport = resolveDaemonTransport({ transport, socketPath });
 
   spawnDaemonFn();
 
@@ -271,6 +272,27 @@ async function restartBridgeDaemonAfterStop(stopResult, options = {}) {
   };
 }
 
+/**
+ * Mirror the daemon entrypoint transport defaults so restart polling targets the
+ * same endpoint the spawned process listens on.
+ *
+ * @param {{ transport?: BridgeTransport, socketPath?: string }} options
+ * @returns {BridgeTransport}
+ */
+function resolveDaemonTransport(options) {
+  const { transport, socketPath } = options;
+  if (socketPath) {
+    return createSocketBridgeTransport(socketPath);
+  }
+  if (transport) {
+    return transport;
+  }
+
+  const env = { ...process.env };
+  applyWindowsTcpTransportDefaults(env);
+  return getBridgeTransport(env);
+}
+
 /**
  * @param {BridgeTransport} transport
  * @returns {Promise<number | null>}

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

@@ -53,7 +53,7 @@ const DAEMON_VERSION = loadDaemonVersion();
 /** @typedef {import('./config.js').BridgeTransport} BridgeTransport */
 /** @typedef {import('./daemon-logger.js').DaemonLoggerLike} DaemonLoggerLike */
 /** @typedef {import('node:net').Socket & { __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __accessEnabled?: boolean, __lastActiveAt?: number, __authenticated?: boolean }} ClientSocket */
-/** @typedef {{ socket: ClientSocket, timeoutId: NodeJS.Timeout, source?: string, method?: string, targets: Set<ClientSocket>, lastErrorResponse?: import('../../protocol/src/types.js').BridgeResponse }} PendingEntry */
+/** @typedef {{ socket: ClientSocket, timeoutId: NodeJS.Timeout, source?: string, method?: string, protocolVersion?: string, targets: Set<ClientSocket>, lastErrorResponse?: import('../../protocol/src/types.js').BridgeResponse }} PendingEntry */
 /**
  * @typedef {{
  *   installAgentFiles: typeof import('../../agent-client/src/install.js').installAgentFiles,
@@ -762,6 +762,7 @@ export class BridgeDaemon {
     this.trackPendingRequest(request.id, {
       socket,
       method: request.method,
+      protocolVersion: request.meta?.protocol_version,
       source: typeof request.meta?.source === 'string' ? request.meta.source : '',
       targets: new Set(targets),
       timeoutId: setTimeout(() => {
@@ -925,6 +926,7 @@ export class BridgeDaemon {
                 socketPath: this.socketPath,
                 transport: formatBridgeTransport(this.transport),
                 connectedExtensions: this.getConnectedExtensionsSnapshot(),
+                ...getVersionNegotiationPayload(pending.protocolVersion),
                 .../** @type {Record<string, unknown>} */ (responseMessage.result),
                 daemonVersion: DAEMON_VERSION,
                 daemon_supported_versions: SUPPORTED_VERSIONS,

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

@@ -2,7 +2,7 @@
 
 import { once } from 'node:events';
 
-import { MAX_NATIVE_MESSAGE_BYTES } from '../../protocol/src/index.js';
+import { MAX_JSON_LINE_BYTES, MAX_NATIVE_MESSAGE_BYTES } from '../../protocol/src/index.js';
 
 /**
  * @param {NodeJS.WritableStream} stream
@@ -193,7 +193,12 @@ export function createNativeMessageReader(stream, onMessage, onProtocolError) {
  * @returns {Promise<void>}
  */
 export async function writeJsonLine(socket, message) {
-  if (!socket.write(`${JSON.stringify(message)}\n`)) {
+  const line = `${JSON.stringify(message)}\n`;
+  const byteLength = Buffer.byteLength(line.slice(0, -1), 'utf8');
+  if (byteLength > MAX_JSON_LINE_BYTES) {
+    throw new Error(`JSON line exceeds ${MAX_JSON_LINE_BYTES} bytes: ${byteLength}`);
+  }
+  if (!socket.write(line)) {
     await once(socket, 'drain');
   }
 }

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

@@ -259,13 +259,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);

package/packages/protocol/src/protocol.js

@@ -97,7 +97,9 @@ export const SUPPORTED_VERSIONS = Object.freeze(['1.0']);
  * @returns {number}
  */
 function clampInt(value, min, max, fallback) {
-  return Math.min(Math.max(Number(value) || fallback, min), max);
+  const numeric = Number(value);
+  const integer = Number.isFinite(numeric) && numeric !== 0 ? Math.trunc(numeric) : fallback;
+  return Math.min(Math.max(integer, min), max);
 }
 
 /** @type {ReadonlyArray<BridgeMethod>} */