@browserbridge/bbx 1.7.1 → 1.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -61,8 +61,9 @@
     "postinstall": "node packages/native-host/bin/postinstall.js",
     "package:extension": "node scripts/package-extension.mjs",
     "check:extension-zip": "node scripts/check-extension-zip.mjs",
-    "release:check": "npm run lint && npm run typecheck && npm test && npm run coverage:check && npm run package:extension && npm run check:extension-zip && npm pack --dry-run",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm test && npm run coverage:check",
+    "check:release-version": "node scripts/check-release-version.mjs",
+    "release:check": "npm run check:release-version && npm run lint && npm run typecheck && npm test && npm run coverage:check && npm run package:extension && npm run check:extension-zip && npm pack --dry-run",
+    "prepublishOnly": "npm run check:release-version && npm run lint && npm run typecheck && npm test && npm run coverage:check",
     "status": "node packages/agent-client/src/cli.js status",
     "daemon": "node packages/native-host/bin/bridge-daemon.js",
     "install-manifest": "node packages/native-host/bin/install-manifest.js"

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

@@ -512,6 +512,9 @@ async function main() {
 
     if (command === 'doctor') {
       const report = await getDoctorReport();
+      if (report.issues.length > 0) {
+        process.exitCode = 1;
+      }
       printJson({
         ok: report.issues.length === 0,
         summary:
@@ -1298,6 +1301,9 @@ async function ensureClientConnection() {
  * @returns {Promise<void>}
  */
 async function printSummary(response, method) {
+  if (!response.ok) {
+    process.exitCode = 1;
+  }
   printJson(annotateBridgeSummary(summarizeBridgeResponse(response, method), response));
 }
 

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

@@ -3,7 +3,6 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 /** @typedef {import('./types.js').McpClientName} McpClientName */
 
@@ -40,8 +39,8 @@ export function isMcpClientName(value) {
 }
 
 const BROWSER_BRIDGE_SERVER_NAME = 'browser-bridge';
-const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
-const mcpServerBinPath = path.join(packageRoot, 'packages', 'mcp-server', 'src', 'bin.js');
+const MCP_COMMAND = 'bbx';
+const MCP_ARGS = Object.freeze(['mcp', 'serve']);
 
 /**
  * @returns {string}
@@ -76,7 +75,7 @@ function getLegacyCopilotVsCodeConfigPath() {
 
 /**
  * @param {McpClientName} clientName
- * @returns {{ key: string, includeType: boolean, legacyKeys?: string[], keepEmptyBlock?: boolean }}
+ * @returns {{ key: string, includeType: boolean, keepEmptyBlock?: boolean }}
  */
 export function getMcpConfigShape(clientName) {
   return MCP_CONFIG_SHAPES[clientName] ?? { key: 'mcpServers', includeType: false };
@@ -95,21 +94,21 @@ export function getMcpConfigShape(clientName) {
  */
 function createBaseServerConfig(clientName) {
   const serverConfig = {
-    command: process.execPath,
-    args: [mcpServerBinPath],
+    command: MCP_COMMAND,
+    args: [...MCP_ARGS],
     env: {},
   };
 
   if (clientName === 'opencode') {
     return {
       type: 'local',
-      command: [process.execPath, mcpServerBinPath],
+      command: [MCP_COMMAND, ...MCP_ARGS],
     };
   }
   return serverConfig;
 }
 
-/** @type {Record<McpClientName, { key: string, includeType: boolean, legacyKeys?: string[], keepEmptyBlock?: boolean }>} */
+/** @type {Record<McpClientName, { key: string, includeType: boolean, keepEmptyBlock?: boolean }>} */
 const MCP_CONFIG_SHAPES = {
   antigravity: { key: 'mcpServers', includeType: false },
   agents: { key: 'mcpServers', includeType: true },
@@ -117,7 +116,6 @@ const MCP_CONFIG_SHAPES = {
   copilot: {
     key: 'mcpServers',
     includeType: true,
-    legacyKeys: ['servers'],
     keepEmptyBlock: true,
   },
   cursor: { key: 'mcpServers', includeType: false },
@@ -126,6 +124,24 @@ const MCP_CONFIG_SHAPES = {
   opencode: { key: 'mcp', includeType: false },
 };
 
+/**
+ * Copilot CLI and VS Code use different top-level keys. Select the schema from
+ * the destination file instead of migrating one valid schema into the other.
+ *
+ * @param {McpClientName} clientName
+ * @param {string} configPath
+ * @returns {{ key: string, includeType: boolean, keepEmptyBlock?: boolean }}
+ */
+export function getMcpConfigShapeForPath(clientName, configPath) {
+  if (
+    clientName === 'copilot' &&
+    path.resolve(configPath) !== path.resolve(getCopilotUserConfigPath())
+  ) {
+    return { key: 'servers', includeType: true, keepEmptyBlock: true };
+  }
+  return getMcpConfigShape(clientName);
+}
+
 /**
  * @param {McpClientName} clientName
  * @returns {Record<string, unknown>}
@@ -135,8 +151,8 @@ export function buildMcpConfig(clientName) {
     return {
       mcp_servers: {
         [BROWSER_BRIDGE_SERVER_NAME]: {
-          command: process.execPath,
-          args: [mcpServerBinPath],
+          command: MCP_COMMAND,
+          args: [...MCP_ARGS],
         },
       },
     };
@@ -267,8 +283,8 @@ export async function getMcpConfigPaths(clientName, options) {
 function formatCodexServerBlock() {
   return [
     `[mcp_servers."${BROWSER_BRIDGE_SERVER_NAME}"]`,
-    `command = ${JSON.stringify(process.execPath)}`,
-    `args = ${JSON.stringify([mcpServerBinPath])}`,
+    `command = ${JSON.stringify(MCP_COMMAND)}`,
+    `args = ${JSON.stringify(MCP_ARGS)}`,
     '',
   ].join('\n');
 }
@@ -377,37 +393,6 @@ function removeCodexServerBlock(raw) {
   return trimmed ? `${trimmed}\n` : '';
 }
 
-/**
- * @param {McpClientName} clientName
- * @returns {string[]}
- */
-function getJsonMcpBlockKeys(clientName) {
-  const shape = getMcpConfigShape(clientName);
-  return [...(shape.legacyKeys ?? []), shape.key];
-}
-
-/**
- * Merge MCP entries from the current config key plus any legacy aliases.
- *
- * @param {Record<string, unknown>} config
- * @param {McpClientName} clientName
- * @returns {Record<string, unknown>}
- */
-function getMergedJsonMcpBlock(config, clientName) {
-  /** @type {Record<string, unknown>} */
-  const merged = {};
-
-  for (const key of getJsonMcpBlockKeys(clientName)) {
-    const block = config[key];
-    if (!block || typeof block !== 'object' || Array.isArray(block)) {
-      continue;
-    }
-    Object.assign(merged, /** @type {Record<string, unknown>} */ (block));
-  }
-
-  return merged;
-}
-
 /**
  * Merge the browser-bridge entry into an existing client config file, or
  * create it if it does not exist. Existing unrelated entries are preserved.
@@ -446,7 +431,7 @@ export async function findConfiguredMcpClients(options) {
     for (const configPath of configPaths) {
       try {
         const raw = await fs.promises.readFile(configPath, 'utf8');
-        if (parseInstalledMcpConfig(clientName, raw).configured) {
+        if (parseInstalledMcpConfig(clientName, raw, configPath).configured) {
           configured = true;
           break;
         }
@@ -499,8 +484,6 @@ export async function removeMcpConfig(clientName, options) {
  * @returns {Promise<void>}
  */
 async function installJsonMcpConfig(clientName, configPath, stdout) {
-  const newEntry = buildMcpConfig(clientName);
-
   /** @type {Record<string, unknown>} */
   let existing = {};
   try {
@@ -518,21 +501,23 @@ async function installJsonMcpConfig(clientName, configPath, stdout) {
     // File missing - start fresh.
   }
 
-  const shape = getMcpConfigShape(clientName);
+  const shape = getMcpConfigShapeForPath(clientName, configPath);
   const topKey = shape.key;
-  const entryBlock = /** @type {Record<string, unknown>} */ (newEntry[topKey]);
-  const existingBlock = getMergedJsonMcpBlock(existing, clientName);
+  const serverConfig = createBaseServerConfig(clientName);
+  const entry = shape.includeType ? { type: 'stdio', ...serverConfig } : serverConfig;
+  const currentBlock = existing[topKey];
+  const existingBlock =
+    currentBlock && typeof currentBlock === 'object' && !Array.isArray(currentBlock)
+      ? /** @type {Record<string, unknown>} */ (currentBlock)
+      : {};
 
   const merged = {
     ...existing,
     [topKey]: {
       ...existingBlock,
-      ...entryBlock,
+      [BROWSER_BRIDGE_SERVER_NAME]: entry,
     },
   };
-  for (const key of shape.legacyKeys ?? []) {
-    delete merged[key];
-  }
 
   await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
   await fs.promises.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
@@ -579,9 +564,13 @@ async function removeJsonMcpConfig(clientName, configPath, stdout) {
     return false;
   }
 
-  const shape = getMcpConfigShape(clientName);
+  const shape = getMcpConfigShapeForPath(clientName, configPath);
   const topKey = shape.key;
-  const block = getMergedJsonMcpBlock(existing, clientName);
+  const currentBlock = existing[topKey];
+  const block =
+    currentBlock && typeof currentBlock === 'object' && !Array.isArray(currentBlock)
+      ? /** @type {Record<string, unknown>} */ (currentBlock)
+      : {};
   if (!Object.hasOwn(block, BROWSER_BRIDGE_SERVER_NAME)) {
     return false;
   }
@@ -590,9 +579,7 @@ async function removeJsonMcpConfig(clientName, configPath, stdout) {
   delete updatedBlock[BROWSER_BRIDGE_SERVER_NAME];
 
   const merged = { ...existing };
-  for (const key of getJsonMcpBlockKeys(clientName)) {
-    delete merged[key];
-  }
+  delete merged[topKey];
   if (Object.keys(updatedBlock).length > 0 || shape.keepEmptyBlock) {
     merged[topKey] = updatedBlock;
   }
@@ -630,23 +617,35 @@ async function removeCodexMcpConfig(configPath, stdout) {
 /**
  * @param {McpClientName} clientName
  * @param {string} raw
+ * @param {string} [configPath]
  * @returns {{ configured: boolean }}
  */
-export function parseInstalledMcpConfig(clientName, raw) {
+export function parseInstalledMcpConfig(clientName, raw, configPath) {
   if (clientName === 'codex') {
     return { configured: hasCodexServerBlock(raw) };
   }
 
   try {
     const parsed = JSON.parse(raw);
-    const block =
+    const config =
       parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-        ? getMergedJsonMcpBlock(/** @type {Record<string, unknown>} */ (parsed), clientName)
+        ? /** @type {Record<string, unknown>} */ (parsed)
         : {};
+    const keys = configPath
+      ? [getMcpConfigShapeForPath(clientName, configPath).key]
+      : clientName === 'copilot'
+        ? ['mcpServers', 'servers']
+        : [getMcpConfigShape(clientName).key];
     return {
-      configured: Boolean(
-        block && typeof block === 'object' && Object.hasOwn(block, BROWSER_BRIDGE_SERVER_NAME)
-      ),
+      configured: keys.some((key) => {
+        const block = config[key];
+        return Boolean(
+          block &&
+          typeof block === 'object' &&
+          !Array.isArray(block) &&
+          Object.hasOwn(block, BROWSER_BRIDGE_SERVER_NAME)
+        );
+      }),
     };
   } catch {
     return { configured: false };

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

@@ -18,6 +18,12 @@ import {
   summarizeDaemonRestarts,
 } from '../../native-host/src/daemon-process.js';
 import { resolveDefaultExtensionId } from '../../native-host/src/install-manifest.js';
+import {
+  CLIENT_REQUEST_TIMEOUT_MARGIN_MS,
+  DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
+  getBridgeOperationTimeoutMs,
+  MAX_CLIENT_REQUEST_TIMEOUT_MS,
+} from '../../protocol/src/index.js';
 import { methodNeedsTab } from './cli-helpers.js';
 import { BridgeClient } from './client.js';
 
@@ -53,11 +59,24 @@ export async function ensureClientConnected(client) {
  */
 export async function requestBridge(client, method, params = {}, options = {}) {
   await ensureClientConnected(client);
+  const operationTimeoutMs = getBridgeOperationTimeoutMs(method, params);
+  const clientDefaultTimeoutMs =
+    typeof client.defaultTimeoutMs === 'number'
+      ? client.defaultTimeoutMs
+      : DEFAULT_CLIENT_REQUEST_TIMEOUT_MS;
+  const timeoutMs =
+    operationTimeoutMs === null
+      ? undefined
+      : Math.min(
+          MAX_CLIENT_REQUEST_TIMEOUT_MS,
+          Math.max(clientDefaultTimeoutMs, operationTimeoutMs + CLIENT_REQUEST_TIMEOUT_MARGIN_MS)
+        );
   return client.request({
     method,
     params,
     tabId: methodNeedsTab(method) ? (options.tabId ?? null) : null,
     meta: withRequestMeta(options.source, options.tokenBudget),
+    ...(timeoutMs === undefined ? {} : { timeoutMs }),
   });
 }
 

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

@@ -10,9 +10,9 @@ export const MCP_SERVER_INSTRUCTIONS = [
   '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.',
   '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.',
+  'Use structured reads first through browser_call: page.get_state, dom.query, page.get_text, styles.get_computed, or layout.get_box_model. Use browser_batch for parallel reads and keep limits tight before widening.',
   'Reuse elementRef values returned by DOM tools. Use attribute allowlists for focused DOM reads.',
-  'Escalate to screenshot.capture_element, screenshot.capture_region, accessibility_tree, page.evaluate, viewport.resize, or CDP only when structured reads cannot answer the question.',
+  'Escalate to screenshot.capture_element, screenshot.capture_region, dom.get_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');
@@ -102,8 +102,8 @@ function createGuidePrompt() {
       '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.',
+      '4. Start with structured reads via `browser_call`: `page.get_state`, `dom.query`, `dom.find_by_text`, `dom.find_by_role`, and `styles.get_computed`. Use `browser_batch` for parallel reads.',
+      '5. `browser_call` accepts explicit method limits, not `budgetPreset`; keep limits tight and 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.',

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

@@ -1,7 +1,7 @@
 // @ts-check
 
 import {
-  dispatchToolAction,
+  createToolResult,
   getToolTokenBudget,
   REQUEST_SOURCE,
   requestBridgeWithRetry,
@@ -13,6 +13,7 @@ import {
 } from './handlers-utils.js';
 
 /** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('../../protocol/src/types.js').BridgeResponse} BridgeResponse */
 /** @typedef {import('./handlers-utils.js').ToolAction} ToolAction */
 /** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
 
@@ -97,7 +98,170 @@ export async function handleCaptureTool(args) {
     return summarizeToolError('nodeId must be a finite number.');
   }
 
-  return dispatchToolAction(CAPTURE_ACTIONS, args, 'capture');
+  const entry = CAPTURE_ACTIONS[args.action];
+  if (!entry) {
+    return summarizeToolError(`Unsupported capture action "${args.action}".`);
+  }
+
+  return withToolClient(
+    async (client) => {
+      const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
+      const ref = entry.ref ? await resolveToolRef(client, args, requestedTabId) : undefined;
+      const response = await requestBridgeWithRetry(client, entry.method, entry.params(args, ref), {
+        tabId: requestedTabId,
+        source: REQUEST_SOURCE,
+        tokenBudget: getToolTokenBudget(args),
+      });
+      if (!response.ok) {
+        return summarizeToolResponse(response, entry.method);
+      }
+      return entry.method.startsWith('screenshot.')
+        ? createScreenshotResult(response, entry.method)
+        : createCdpCaptureResult(response, entry.method);
+    },
+    { destinationId: args.destinationId ?? null }
+  );
+}
+
+/**
+ * @param {BridgeResponse & { ok: true }} response
+ * @param {BridgeMethod} method
+ * @returns {ToolResult}
+ */
+function createScreenshotResult(response, method) {
+  const result = toRecord(response.result);
+  if (typeof result.image !== 'string') {
+    return summarizeToolError(`${method} returned no image data.`);
+  }
+
+  const image = normalizeBase64Image(result.image);
+  if (!image) {
+    return summarizeToolError(`${method} returned invalid base64 image data.`);
+  }
+
+  const rect = boundedRect(result.rect);
+  return createToolResult(
+    `Captured ${image.mimeType} screenshot (${image.byteLength} bytes).`,
+    {
+      ok: true,
+      method,
+      mimeType: image.mimeType,
+      byteLength: image.byteLength,
+      ...(rect ? { rect } : {}),
+    },
+    false,
+    [{ type: 'image', data: image.data, mimeType: image.mimeType }]
+  );
+}
+
+/**
+ * @param {BridgeResponse & { ok: true }} response
+ * @param {BridgeMethod} method
+ * @returns {ToolResult}
+ */
+function createCdpCaptureResult(response, method) {
+  const bounded = boundStructuredValue(response.result);
+  return createToolResult(`Captured bounded structured data from ${method}.`, {
+    ok: true,
+    method,
+    data: bounded.value,
+    truncated: bounded.truncated,
+  });
+}
+
+/**
+ * @param {string} value
+ * @returns {{ data: string, mimeType: string, byteLength: number } | null}
+ */
+function normalizeBase64Image(value) {
+  const dataUrl = /^data:([^;,]+);base64,(.*)$/su.exec(value);
+  const mimeType = dataUrl?.[1] ?? 'image/png';
+  if (!mimeType.startsWith('image/')) return null;
+  const data = (dataUrl?.[2] ?? value).replace(/\s+/gu, '');
+  if (!data || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(data)) {
+    return null;
+  }
+  const bytes = Buffer.from(data, 'base64');
+  if (bytes.toString('base64') !== data) return null;
+  return { data, mimeType, byteLength: bytes.length };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, number> | null}
+ */
+function boundedRect(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const source = /** @type {Record<string, unknown>} */ (value);
+  /** @type {Record<string, number>} */
+  const rect = {};
+  for (const key of ['x', 'y', 'width', 'height', 'scale']) {
+    if (isFiniteNumber(source[key])) rect[key] = source[key];
+  }
+  return Object.keys(rect).length > 0 ? rect : null;
+}
+
+/**
+ * Bound debugger payloads by depth, entries, and string length while retaining
+ * their actual values rather than reducing them to field names.
+ *
+ * @param {unknown} input
+ * @returns {{ value: unknown, truncated: boolean }}
+ */
+function boundStructuredValue(input) {
+  const state = { entries: 0, characters: 0, truncated: false };
+  const maxEntries = 500;
+  const maxCharacters = 50_000;
+  /** @type {(value: unknown, depth: number) => unknown} */
+  const visit = (value, depth) => {
+    if (state.entries >= maxEntries || state.characters >= maxCharacters || depth > 8) {
+      state.truncated = true;
+      return '[truncated]';
+    }
+    state.entries += 1;
+    if (typeof value === 'string') {
+      const remaining = maxCharacters - state.characters;
+      const limit = Math.min(value.length, remaining, 4000);
+      state.characters += limit;
+      if (limit === value.length) return value;
+      state.truncated = true;
+      return `${value.slice(0, limit)}[truncated]`;
+    }
+    if (Array.isArray(value)) {
+      const remaining = maxEntries - state.entries;
+      const limit = Math.min(value.length, remaining, 100);
+      if (limit < value.length) state.truncated = true;
+      return value.slice(0, limit).map((entry) => visit(entry, depth + 1));
+    }
+    if (value && typeof value === 'object') {
+      /** @type {Record<string, unknown>} */
+      const output = {};
+      const entries = Object.entries(/** @type {Record<string, unknown>} */ (value));
+      const limit = Math.min(entries.length, 100);
+      if (limit < entries.length) state.truncated = true;
+      for (const [key, entry] of entries.slice(0, limit)) {
+        if (state.entries >= maxEntries || state.characters >= maxCharacters) {
+          state.truncated = true;
+          break;
+        }
+        state.characters += key.length;
+        output[key] = visit(entry, depth + 1);
+      }
+      return output;
+    }
+    return value;
+  };
+  return { value: visit(input, 0), truncated: state.truncated };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+function toRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? /** @type {Record<string, unknown>} */ (value)
+    : {};
 }
 
 /** @type {Record<string, BridgeMethod>} */