@browserbridge/bbx 1.9.0 → 1.11.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "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.5",
+    "@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-args.js

@@ -1,9 +1,12 @@
 // @ts-check
 
-import { METHODS } from '../../protocol/src/index.js';
+import { applyMethodBudgetPreset, isBudgetPresetName, METHODS } from '../../protocol/src/index.js';
 import { methodNeedsTab, parseIntArg, parseJsonObject } from './cli-helpers.js';
 
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('../../protocol/src/defaults.js').BudgetPresetName} BudgetPresetName */
+
+const CALL_USAGE = 'Usage: call [--tab <tabId>] [--preset quick|normal|deep] <method> [paramsJson]';
 
 /**
  * Read all of stdin as UTF-8 text. Resolves once stdin closes.
@@ -119,18 +122,44 @@ export function extractHarFlags(args) {
   return { limit, urlPattern, delivery: rawDelivery, rest };
 }
 
+/**
+ * Extract the --preset flag from anywhere in the argument list. Preset names
+ * are validated against the shared budget presets; explicit per-call params
+ * always override preset defaults.
+ *
+ * @param {string[]} args
+ * @returns {{ preset: BudgetPresetName | null, rest: string[] }}
+ */
+export function extractPresetFlag(args) {
+  const rest = [...args];
+  const index = rest.indexOf('--preset');
+  if (index === -1) {
+    return { preset: null, rest };
+  }
+  const value = rest[index + 1];
+  if (!value || value.startsWith('--')) {
+    throw new Error('--preset requires a value: quick, normal, or deep.');
+  }
+  if (!isBudgetPresetName(value)) {
+    throw new Error(`Unknown preset "${value}". Valid presets: quick, normal, deep.`);
+  }
+  rest.splice(index, 2);
+  return { preset: value, rest };
+}
+
 /**
  * @param {string[]} args
  * @returns {Promise<{ tabId: number | null, method: BridgeMethod, params: Record<string, unknown> }>}
  */
 export async function parseCallCommand(args) {
-  const parsed = extractTabFlag(args);
+  const presetParsed = extractPresetFlag(args);
+  const parsed = extractTabFlag(presetParsed.rest);
   const [first, second, ...extra] = parsed.rest;
   if (!first) {
-    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+    throw new Error(CALL_USAGE);
   }
   if (extra.length > 0) {
-    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+    throw new Error(CALL_USAGE);
   }
 
   if (first.includes('.')) {
@@ -146,11 +175,11 @@ export async function parseCallCommand(args) {
     return {
       method,
       tabId: methodNeedsTab(method) ? parsed.tabId : null,
-      params: parseJsonObject(rawParams),
+      params: applyMethodBudgetPreset(method, parseJsonObject(rawParams), presetParsed.preset),
     };
   }
 
-  throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+  throw new Error(CALL_USAGE);
 }
 
 /**

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

@@ -1,6 +1,7 @@
 // @ts-check
 
 import {
+  applyMethodBudgetPreset,
   getProtocolVersion,
   isBatchSafeBridgeCall,
   MAX_BATCH_CALLS,
@@ -14,6 +15,7 @@ import { requestBridge } from './runtime.js';
 
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
 /** @typedef {import('./types.js').BridgeRequestSource} BridgeRequestSource */
+/** @typedef {import('../../protocol/src/defaults.js').BudgetPresetName} BudgetPresetName */
 
 /**
  * @typedef {{
@@ -72,9 +74,10 @@ function invalidBatchItem(method, message) {
  * @param {import('./client.js').BridgeClient} client
  * @param {string | undefined} input - Raw JSON array argument
  * @param {BridgeRequestSource} source - Request source tag (e.g. 'cli')
+ * @param {{ preset?: BudgetPresetName | null }} [options] - Optional budget preset applied to every call
  * @returns {Promise<BatchResultItem[]>}
  */
-export async function runBatchCalls(client, input, source) {
+export async function runBatchCalls(client, input, source, options = {}) {
   if (!input) {
     throw new Error('Usage: batch \'[{"method":"...","params":{...}}, ...]\'');
   }
@@ -90,7 +93,7 @@ export async function runBatchCalls(client, input, source) {
   if (calls.length === 0 || calls.length > MAX_BATCH_CALLS) {
     throw new Error(`Batch input must contain between 1 and ${MAX_BATCH_CALLS} calls.`);
   }
-  const prepared = calls.map((call) => prepareBatchCall(call));
+  const prepared = calls.map((call) => prepareBatchCall(call, options.preset ?? null));
   if (prepared.some((item) => 'error' in item)) {
     return prepared.map((item) =>
       'error' in item
@@ -130,9 +133,10 @@ export async function runBatchCalls(client, input, source) {
 
 /**
  * @param {unknown} call
+ * @param {BudgetPresetName | null} preset
  * @returns {{ value: PreparedBatchCall } | { error: InvalidBatchItem }}
  */
-function prepareBatchCall(call) {
+function prepareBatchCall(call, preset) {
   if (!call || typeof call !== 'object' || Array.isArray(call)) {
     return { error: invalidBatchItem('', 'Each batch call needs a method.') };
   }
@@ -162,7 +166,8 @@ function prepareBatchCall(call) {
   }
   const params =
     batchCall.params === undefined ? {} : /** @type {Record<string, unknown>} */ (batchCall.params);
-  if (!isBatchSafeBridgeCall(method, params)) {
+  const mergedParams = applyMethodBudgetPreset(method, params, preset);
+  if (!isBatchSafeBridgeCall(method, mergedParams)) {
     return {
       error: invalidBatchItem(
         method,
@@ -177,7 +182,7 @@ function prepareBatchCall(call) {
     batchCall.tabId > 0
       ? batchCall.tabId
       : null;
-  return { value: { method, params, tabId } };
+  return { value: { method, params: mergedParams, tabId } };
 }
 
 /**

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

@@ -3,6 +3,14 @@
 import readline from 'node:readline';
 import { bridgeMethodNeedsTab } from '../../protocol/src/index.js';
 
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isElementRef(value) {
+  return value.startsWith('el_');
+}
+
 /**
  * Strip ANSI escape sequences from a string to prevent terminal injection
  * from malicious page content (e.g. DOM text, console output, eval results).

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/cli-setup-commands.js

@@ -150,7 +150,8 @@ export async function runInstallMcpCommand(args) {
   /** @type {string[]} */
   const positionals = [];
 
-  for (const arg of args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
     if (arg === '--local') {
       isGlobal = false;
       continue;
@@ -276,6 +277,7 @@ export async function runInstallMcpCommand(args) {
     projectPath: process.cwd(),
     stdout: process.stdout,
   });
+
   process.exit(0);
 }
 

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

@@ -10,7 +10,13 @@ import { fileURLToPath } from 'node:url';
 
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
-import { createRuntimeContext, METHODS } from '../../protocol/src/index.js';
+import {
+  createRuntimeContext,
+  describeBridgeMethods,
+  isBridgeMethod,
+  isHarDocument,
+  METHODS,
+} from '../../protocol/src/index.js';
 import {
   restartRegisteredMcpProcesses,
   tryStartMcpProcessControl,
@@ -19,6 +25,7 @@ import { startBridgeMcpServer } from '../../mcp-server/src/server.js';
 import {
   extractRemoteFlag,
   extractHarFlags,
+  extractPresetFlag,
   extractScreenshotFlags,
   extractTabFlag,
   parseCallCommand,
@@ -26,7 +33,7 @@ import {
   readStdin,
 } from './cli-args.js';
 import { runBatchCalls } from './cli-batch.js';
-import { parseIntArg } from './cli-helpers.js';
+import { isElementRef, parseIntArg } from './cli-helpers.js';
 import { printCallResponse, printJson, printSummary, printUsage } from './cli-output.js';
 import { handleProxyCommand, handleRemoteCommand } from './cli-proxy-remote.js';
 import {
@@ -64,6 +71,7 @@ const LOCAL_ONLY_COMMANDS = new Set([
   '--version',
   '-v',
   'skill',
+  'protocol',
   'install',
   'uninstall',
   'install-skill',
@@ -111,6 +119,22 @@ if (command === 'skill') {
   process.exit(0);
 }
 
+if (command === 'protocol') {
+  const [subcommand, target, ...extra] = rest;
+  if (subcommand !== 'describe' || extra.length > 0) {
+    process.stderr.write('Usage: bbx protocol describe [method|group]\n');
+    process.exit(1);
+  }
+  await runLocalCommand(async () => {
+    printJson(
+      target
+        ? describeBridgeMethods(isBridgeMethod(target) ? { method: target } : { group: target })
+        : describeBridgeMethods()
+    );
+  });
+  process.exit();
+}
+
 if (command === 'install') {
   const { execFileSync } = await import('node:child_process');
   const installScript = path.resolve(
@@ -142,7 +166,7 @@ if (command === 'install-mcp') {
 }
 
 if (command === 'mcp') {
-  const [subcommand, clientName] = rest;
+  const [subcommand, clientName, ...extra] = rest;
   if (subcommand === 'serve') {
     const control = await tryStartMcpProcessControl();
     try {
@@ -154,7 +178,7 @@ if (command === 'mcp') {
     await new Promise(() => {});
   }
   if (subcommand === 'config') {
-    if (!clientName || !isMcpClientName(clientName)) {
+    if (!clientName || !isMcpClientName(clientName) || extra.length > 0) {
       process.stderr.write(`Usage: bbx mcp config <${MCP_CLIENT_NAMES.join('|')}>\n`);
       process.exit(1);
     }
@@ -260,8 +284,10 @@ async function main() {
     }
 
     if (command === 'access-request') {
+      if (rest.length > 1) throw new Error('Usage: bbx access-request [intent]');
+      const params = SHORTCUT_COMMANDS['access-request'].build(rest);
       await printSummary(
-        await requestBridge(client, 'access.request', {}, { source: REQUEST_SOURCE })
+        await requestBridge(client, 'access.request', params, { source: REQUEST_SOURCE })
       );
       return;
     }
@@ -377,7 +403,8 @@ async function main() {
     }
 
     if (command === 'batch') {
-      const results = await runBatchCalls(client, rest[0], REQUEST_SOURCE);
+      const { preset, rest: batchArgs } = extractPresetFlag(rest);
+      const results = await runBatchCalls(client, batchArgs[0], REQUEST_SOURCE, { preset });
       if (results.some((result) => !result.ok)) {
         process.exitCode = 1;
       }
@@ -412,7 +439,7 @@ async function main() {
       const [key, refOrSelector] = rest;
       if (!key) throw new Error('Usage: press-key <key> [ref|selector]');
       const target = refOrSelector
-        ? refOrSelector.startsWith('el_')
+        ? isElementRef(refOrSelector)
           ? { elementRef: refOrSelector }
           : { selector: refOrSelector }
         : undefined;
@@ -755,14 +782,7 @@ function assertValidHarDocument(document) {
   if (!document || typeof document !== 'object' || Array.isArray(document)) {
     throw new Error('HAR response does not contain an inline HAR object.');
   }
-  const log = Reflect.get(document, 'log');
-  if (
-    !log ||
-    typeof log !== 'object' ||
-    Array.isArray(log) ||
-    Reflect.get(log, 'version') !== '1.2' ||
-    !Array.isArray(Reflect.get(log, 'entries'))
-  ) {
+  if (!isHarDocument(document)) {
     throw new Error('HAR response does not contain a valid HAR 1.2 document.');
   }
 }

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

@@ -2,6 +2,7 @@
 
 import { BRIDGE_METHOD_REGISTRY, BRIDGE_METHODS } from '../../protocol/src/index.js';
 import {
+  isElementRef,
   parseCommaList,
   parseIntArg,
   parseNumberArg,
@@ -39,7 +40,7 @@ function createShortcutCommand(method, usage, build, options = {}) {
  */
 function createAtomicTarget(value) {
   if (!value) throw new Error('A ref or selector is required.');
-  return value.startsWith('el_') ? { elementRef: value } : { selector: value };
+  return isElementRef(value) ? { elementRef: value } : { selector: value };
 }
 
 /** @type {Record<string, ShortcutCommand>} */
@@ -266,6 +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 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',
@@ -285,15 +287,17 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       '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 protocol describe [method|group]                                Describe method params or list registry groups locally',
       'bbx mcp serve                                                      Start Browser Bridge as an MCP stdio server',
     ],
   },
   {
     title: 'Generic RPC',
     lines: [
-      'bbx call [--tab <tabId>] <method> [paramsJson|-]                   Call any bridge method (- reads JSON from stdin)',
+      'bbx call [--tab <tabId>] [--preset quick|normal|deep] <method> [paramsJson|-]  Call any bridge method (- reads JSON from stdin)',
       'bbx <method> [--tab <tabId>] [paramsJson|-]                        Direct alias for exact bridge methods such as page.get_state',
-      "bbx batch '[{method,params,tabId?},...]'                           Up to 20 parallel read-only calls",
+      "bbx batch [--preset quick|normal|deep] '[{method,params,tabId?},...]'  Up to 20 parallel read-only calls",
+      '--preset fills budget gaps (maxNodes, maxDepth, textBudget, limit) from the shared quick|normal|deep presets; explicit params always win.',
       'Every bridge command accepts --remote <name> (or BBX_REMOTE env) to target a remote destination from `bbx remote list`.',
       '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.',

package/packages/agent-client/src/mcp-config.js

@@ -91,23 +91,23 @@ export function getMcpConfigShape(clientName) {
  *   env: Record<string, string>
  * } | {
  *   type: 'local',
- *   command: string[]
+ *   command: string[],
+ *   environment?: Record<string, string>
  * }}
  */
 function createBaseServerConfig(clientName) {
-  const serverConfig = {
-    command: MCP_COMMAND,
-    args: [...MCP_ARGS],
-    env: {},
-  };
-
   if (clientName === 'opencode') {
     return {
       type: 'local',
       command: [MCP_COMMAND, ...MCP_ARGS],
     };
   }
-  return serverConfig;
+
+  return {
+    command: MCP_COMMAND,
+    args: [...MCP_ARGS],
+    env: {},
+  };
 }
 
 /** @type {Record<McpClientName, { key: string, includeType: boolean, keepEmptyBlock?: boolean }>} */

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

@@ -33,7 +33,7 @@ import {
   sanitizeIncidentalPath,
   sanitizeIncidentalText,
 } from '../../protocol/src/index.js';
-import { methodNeedsTab } from './cli-helpers.js';
+import { isElementRef, methodNeedsTab } from './cli-helpers.js';
 import { BridgeClient } from './client.js';
 import { applyConfiguredAutoUpdate } from './config.js';
 import { readRemoteConfig } from './remotes.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 }),
   });
 }
@@ -140,7 +145,7 @@ export async function requestBridge(client, method, params = {}, options = {}) {
  * @returns {Promise<string>}
  */
 export async function resolveRef(client, refOrSelector, tabId = null, source) {
-  if (refOrSelector.startsWith('el_')) {
+  if (isElementRef(refOrSelector)) {
     return refOrSelector;
   }
 
@@ -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 },