@browserbridge/bbx 1.10.0 → 1.11.1

package/README.md

@@ -116,7 +116,7 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 
 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 and startup instructions, so a separate CLI skill is not required for MCP guidance.
+MCP mode is self-contained: the dual-era stdio server supports legacy MCP clients and modern stateless MCP revision `2026-07-28`, and exposes tools and matching startup instructions without requiring a separate CLI skill.
 
 ## How it works
 

package/SECURITY.md

@@ -52,8 +52,15 @@ Out of scope:
 
 - By default the daemon listens on a user-owned Unix socket (mode `0700` directory) or,
   on Windows, a named pipe / localhost TCP.
-- Any TCP listener requires a random 256-bit auth token stored with mode `0600`;
-  registration without it is rejected and the comparison is constant-time.
+- Any TCP listener requires random 256-bit credentials stored with mode `0600`.
+  Agents and the Chrome native host use distinct credentials, so a remote agent
+  token cannot register an extension-role socket. Registration without the
+  role-appropriate credential is rejected and comparison is constant-time.
+- Setup mutation is accepted only from the local socket or authenticated native
+  host. A TCP agent remains non-local even when its peer address is loopback,
+  preventing SSH port forwarding from turning remote access into local control.
+- Daemon connections, registration time, malformed input, pending requests, and
+  per-client pending requests are bounded to limit resource exhaustion.
 - Proxy mode (LAN exposure) is opt-in via `bbx proxy enable` and always provisions a
   token; an invalid `bindHost` in the config rejects the config rather than widening
   the bind address.
@@ -62,3 +69,8 @@ Out of scope:
 - Ordinary Web Storage reads return key/presence metadata only. The separate
   `sensitive.read` method requires one exact key, is excluded from batches and
   automatic retries, and returns a value whole or fails atomically.
+- Fetch/XHR and console capture run in the inspected page's main JavaScript
+  world. Results are therefore marked `integrity: "untrusted"`, copied through
+  strict bounded schemas, and never treated as daemon or extension authority.
+- Request interception rules are bounded per tab; patterns, bodies, and headers
+  have protocol-level size limits and URL matchers are compiled once per rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -73,26 +73,24 @@
     "install-manifest": "node packages/native-host/bin/install-manifest.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/server": "^2.0.0",
     "@mozilla/readability": "^0.6.0",
     "linkedom": "^0.18.13",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/chrome": "^0.2.2",
-    "@types/node": "^26.1.1",
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@types/chrome": "^0.2.6",
+    "@types/node": "^26.2.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "c8": "^12.0.0",
     "har-schema": "^2.0.0",
-    "oxfmt": "^0.60.0",
-    "oxlint": "^1.75.0",
-    "tsx": "^4.23.1",
+    "oxfmt": "^0.63.0",
+    "oxlint": "^1.78.0",
+    "tsx": "^4.23.12",
     "typescript": "^7.0.2"
   },
-  "overrides": {
-    "@hono/node-server": "2.0.11"
-  },
   "engines": {
     "node": ">=20"
   }

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

@@ -11,7 +11,7 @@ import {
   readProxyConfig,
 } from '../../native-host/src/config.js';
 import { pingExistingDaemon } from '../../native-host/src/daemon.js';
-import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
+import { restartBridgeDaemon, stopBridgeDaemon } from '../../native-host/src/daemon-process.js';
 import { atomicWriteFile } from './atomic-write.js';
 import { parseIntArg } from './cli-helpers.js';
 import {
@@ -44,6 +44,8 @@ export async function handleProxyCommand(args) {
       randomUUID
     );
     assertProxyBindSafety(existing, options, bindHost);
+    // Stop against the current config before changing its port or auth token.
+    const stopResult = await stopBridgeDaemon();
     await atomicWriteFile(getBridgeAuthTokenPath(), `${token}\n`, {
       encoding: 'utf8',
       mode: 0o600,
@@ -75,7 +77,7 @@ export async function handleProxyCommand(args) {
       '',
       `Token: ${token}${tokenNote}`,
       `Config: ${configPath}`,
-      `Daemon: ${result.previouslyRunning ? 'restarted' : 'started'} (pid ${result.pid})`,
+      `Daemon: ${stopResult.previouslyRunning ? 'restarted' : 'started'} (pid ${result.pid})`,
     ];
     if (tokenSource !== 'existing') {
       if (isLoopbackHost(bindHost)) {
@@ -106,10 +108,11 @@ export async function handleProxyCommand(args) {
 
   if (subcommand === 'disable') {
     const configPath = getProxyConfigPath();
+    const stopResult = await stopBridgeDaemon();
     await fs.promises.rm(configPath, { force: true });
-    const result = await restartBridgeDaemon();
+    await restartBridgeDaemon();
     process.stdout.write(
-      `Browser Bridge proxy disabled. Daemon ${result.previouslyRunning ? 'restarted' : 'started'}.\n`
+      `Browser Bridge proxy disabled. Daemon ${stopResult.previouslyRunning ? 'restarted' : 'started'}.\n`
     );
     return;
   }

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

@@ -267,7 +267,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       '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',
-      '  MCP starts with common tools; browser_toolset loads one specialized typed tool by name when needed.',
+      '  MCP uses a compact surface: legacy clients can load typed tools; modern stateless clients use browser_call.',
       'bbx status                                                         Check bridge connection',
       'bbx doctor                                                         Consolidated local runtime, setup, protocol, and readiness diagnostics',
       'bbx restart                                                        Restart the local daemon and running MCP servers',

package/packages/agent-client/src/npm-self-update.js

@@ -14,6 +14,8 @@ const DEFAULT_LOCK_TIMEOUT_MS = 120_000;
 const UPDATE_LOCK_PORT_START = 49_152;
 const UPDATE_LOCK_PORT_COUNT = 16_384;
 const UPDATE_LOCK_PORT_ATTEMPTS = 32;
+const UPDATE_LOCK_PORT_STEP = UPDATE_LOCK_PORT_COUNT / UPDATE_LOCK_PORT_ATTEMPTS;
+const UNAVAILABLE_LOCK_PORT_CODES = new Set(['EACCES', 'EADDRINUSE']);
 
 /** @typedef {import('./types.js').NpmUpdateResult} NpmUpdateResult */
 
@@ -113,6 +115,7 @@ export async function runNpmCommand(args, options = {}) {
     ? process.execPath
     : npmExecPath || (process.platform === 'win32' ? 'npm.cmd' : 'npm');
   const commandArgs = useNode && npmExecPath ? [npmExecPath, ...args] : args;
+  const useWindowsShell = process.platform === 'win32' && /\.(?:cmd|bat)$/iu.test(command);
 
   return new Promise((resolve, reject) => {
     execFile(
@@ -124,6 +127,7 @@ export async function runNpmCommand(args, options = {}) {
         timeout: options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
         maxBuffer: 4 * 1024 * 1024,
         windowsHide: true,
+        shell: useWindowsShell,
       },
       (error, stdout, stderr) => {
         if (!error) {
@@ -154,7 +158,8 @@ export function getNpmUpdateLockPort(lockKey, offset = 0) {
   const digest = createHash('sha256').update(lockKey).digest();
   return (
     UPDATE_LOCK_PORT_START +
-    ((digest.readUInt32BE(0) + Math.max(0, Math.trunc(offset))) % UPDATE_LOCK_PORT_COUNT)
+    ((digest.readUInt32BE(0) + Math.max(0, Math.trunc(offset)) * UPDATE_LOCK_PORT_STEP) %
+      UPDATE_LOCK_PORT_COUNT)
   );
 }
 
@@ -200,7 +205,9 @@ export async function acquireNpmUpdateLock(lockKey, timeoutMs = DEFAULT_LOCK_TIM
       const server = net.createServer((socket) => socket.end(`${identity}\n`));
       const acquired = await new Promise((resolve, reject) => {
         server.once('error', (error) => {
-          if (/** @type {NodeJS.ErrnoException} */ (error).code === 'EADDRINUSE') {
+          if (
+            UNAVAILABLE_LOCK_PORT_CODES.has(/** @type {NodeJS.ErrnoException} */ (error).code ?? '')
+          ) {
             resolve(false);
             return;
           }

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

@@ -106,7 +106,7 @@ export async function ensureClientConnected(client) {
  * @param {BridgeClient} client
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} [params={}]
- * @param {{ tabId?: number | null, source?: BridgeRequestSource, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} [options]
+ * @param {{ tabId?: number | null, source?: BridgeRequestSource, mcpEra?: import('./types.js').McpProtocolEra, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} [options]
  * @returns {Promise<BridgeResponse>}
  */
 export async function requestBridge(client, method, params = {}, options = {}) {
@@ -127,7 +127,12 @@ export async function requestBridge(client, method, params = {}, options = {}) {
     method,
     params,
     tabId: methodNeedsTab(method) ? (options.tabId ?? null) : null,
-    meta: withRequestMeta(options.source, options.tokenBudget, options.automaticRetry),
+    meta: withRequestMeta(
+      options.source,
+      options.mcpEra,
+      options.tokenBudget,
+      options.automaticRetry
+    ),
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
   });
 }
@@ -168,16 +173,20 @@ export async function resolveRef(client, refOrSelector, tabId = null, source) {
 
 /**
  * @param {BridgeRequestSource | undefined} source
+ * @param {import('./types.js').McpProtocolEra | undefined} mcpEra
  * @param {number | null | undefined} tokenBudget
  * @param {'mcp_second_attempt' | undefined} automaticRetry
  * @returns {BridgeMeta}
  */
-function withRequestMeta(source, tokenBudget, automaticRetry) {
+function withRequestMeta(source, mcpEra, tokenBudget, automaticRetry) {
   /** @type {BridgeMeta} */
   const meta = {};
   if (source) {
     meta.source = source;
   }
+  if (source === 'mcp' && mcpEra) {
+    meta.mcp_era = mcpEra;
+  }
   if (typeof tokenBudget === 'number' && Number.isFinite(tokenBudget)) {
     meta.token_budget = tokenBudget;
   }

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

@@ -4,6 +4,7 @@ import type {
   BridgeMethod,
   BridgeRequestSource,
   BridgeResponse,
+  McpProtocolEra,
   RecoveryEventKind,
   RecoveryTelemetrySummary,
   ScreenshotResult,
@@ -17,6 +18,7 @@ export type {
   BridgeRequestSource,
   BridgeResponse,
   BridgeTransport,
+  McpProtocolEra,
   ScreenshotResult,
 };
 

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

@@ -9,7 +9,7 @@ import { startBridgeMcpServer } from './server.js';
 
 /**
  * @typedef {{
- *   start?: () => Promise<void>,
+ *   start?: () => void | Promise<void>,
  *   startControl?: typeof tryStartMcpProcessControl,
  *   argv?: string[],
  *   stdout?: { write: (chunk: string) => unknown },

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

@@ -29,20 +29,26 @@ const WORKFLOW_INSTRUCTIONS = Object.freeze([
 const SERVER_HEADER =
   "Browser Bridge MCP inspects and interacts with the user's real Chrome tab through a compact tool set.";
 
-const TOOL_RULES = Object.freeze([
+const LEGACY_TOOL_RULES = Object.freeze([
   'The common tools are available immediately. When a specialized typed tool is useful, call browser_toolset with its exact tool name; browser_call always reaches every bridge method without loading another tool.',
   'Use browser_call method protocol.describe with method or group params to load unfamiliar signatures cheaply.',
 ]);
 
+const MODERN_TOOL_RULES = Object.freeze([
+  'The compact tool list is static for stateless MCP. browser_call reaches every bridge method, and browser_skill returns runtime groups and limits.',
+  'Use browser_call method protocol.describe with method or group params to load unfamiliar signatures cheaply.',
+]);
+
 /**
- * Build instructions for progressive tool discovery.
+ * Build instructions for the negotiated MCP era.
  *
+ * @param {'legacy' | 'modern'} [era='legacy']
  * @returns {string}
  */
-export function getMcpServerInstructions() {
-  return [SERVER_HEADER, ...TOOL_RULES, ...SHARED_INSTRUCTIONS, ...WORKFLOW_INSTRUCTIONS].join(
-    '\n'
-  );
+export function getMcpServerInstructions(era = 'legacy') {
+  const toolRules = era === 'modern' ? MODERN_TOOL_RULES : LEGACY_TOOL_RULES;
+  return [SERVER_HEADER, ...toolRules, ...SHARED_INSTRUCTIONS, ...WORKFLOW_INSTRUCTIONS].join('\n');
 }
 
 export const MCP_SERVER_INSTRUCTIONS = getMcpServerInstructions();
+export const MODERN_MCP_SERVER_INSTRUCTIONS = getMcpServerInstructions('modern');

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

@@ -1,5 +1,6 @@
 // @ts-check
 
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 
 import {
@@ -46,6 +47,18 @@ import { annotateBridgeSummary, summarizeBridgeResponse } from '../../agent-clie
 
 export const REQUEST_SOURCE = 'mcp';
 const MCP_CLIENT_ID = `mcp_${randomUUID()}`;
+/** @type {AsyncLocalStorage<import('../../protocol/src/types.js').McpProtocolEra>} */
+const MCP_REQUEST_ERA = new AsyncLocalStorage();
+
+/**
+ * @template T
+ * @param {import('../../protocol/src/types.js').McpProtocolEra} era
+ * @param {() => T} callback
+ * @returns {T}
+ */
+export function runWithMcpRequestEra(era, callback) {
+  return MCP_REQUEST_ERA.run(era, callback);
+}
 
 /** @type {ReadonlySet<BridgeMethod>} */
 const RETRY_SAFE_METHODS = new Set([
@@ -606,14 +619,18 @@ export async function waitForClientReconnect(client, timeoutMs = RECONNECT_WAIT_
  * @param {import('../../agent-client/src/client.js').BridgeClient} client
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} params
- * @param {{ tabId?: number | null, source?: import('../../protocol/src/types.js').BridgeRequestSource, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} options
+ * @param {{ tabId?: number | null, source?: import('../../protocol/src/types.js').BridgeRequestSource, mcpEra?: import('../../protocol/src/types.js').McpProtocolEra, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} options
  * @returns {Promise<BridgeResponse>}
  */
 export async function requestBridgeWithRetry(client, method, params, options) {
+  const requestOptions = {
+    ...options,
+    mcpEra: options.mcpEra ?? MCP_REQUEST_ERA.getStore(),
+  };
   /** @type {BridgeResponse} */
   let response;
   try {
-    response = await requestBridge(client, method, params, options);
+    response = await requestBridge(client, method, params, requestOptions);
   } catch (error) {
     if (!isConnectionLossError(error) || !isRetrySafeBridgeMethod(method, params)) {
       throw error;
@@ -625,7 +642,7 @@ export async function requestBridgeWithRetry(client, method, params, options) {
       throw error;
     }
     return requestBridge(client, method, params, {
-      ...options,
+      ...requestOptions,
       automaticRetry: 'mcp_second_attempt',
     });
   }
@@ -640,7 +657,7 @@ export async function requestBridgeWithRetry(client, method, params, options) {
     );
     await new Promise((r) => setTimeout(r, delay));
     return requestBridge(client, method, params, {
-      ...options,
+      ...requestOptions,
       automaticRetry: 'mcp_second_attempt',
     });
   }

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

@@ -11,6 +11,7 @@ import {
   getToolTokenBudget,
   getBridgeDestinations,
   applyLimitBudgetPreset,
+  requestBridgeWithRetry,
   summarizeToolError,
   summarizeToolResponse,
   withToolClient,
@@ -34,6 +35,7 @@ export {
   callBridgeTool,
   dispatchToolAction,
   REQUEST_SOURCE,
+  runWithMcpRequestEra,
 } from './handlers-utils.js';
 
 export {
@@ -233,10 +235,14 @@ export async function handleHealthTool(args = {}) {
   const destinationId = typeof args.destinationId === 'string' ? args.destinationId : null;
   return withToolClient(
     async (client) => {
-      const response = await client.request({
-        method: 'health.ping',
-        meta: { source: REQUEST_SOURCE },
-      });
+      const response = await requestBridgeWithRetry(
+        client,
+        'health.ping',
+        {},
+        {
+          source: REQUEST_SOURCE,
+        }
+      );
       return summarizeToolResponse(response, 'health.ping');
     },
     { destinationId }