@browserbridge/bbx 1.7.4 → 1.7.5

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

@@ -1,7 +1,12 @@
 // @ts-check
 
 import { BRIDGE_METHOD_REGISTRY, BRIDGE_METHODS } from '../../protocol/src/index.js';
-import { parseCommaList, parseIntArg, parsePropertyAssignments } from './cli-helpers.js';
+import {
+  parseCommaList,
+  parseIntArg,
+  parseNumberArg,
+  parsePropertyAssignments,
+} from './cli-helpers.js';
 
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
 /** @typedef {import('./types.js').ShortcutCommand} ShortcutCommand */
@@ -200,8 +205,8 @@ export const SHORTCUT_COMMANDS = {
   scroll: createShortcutCommand('viewport.scroll', 'bbx scroll <top> [left]', (r) => {
     if (!r[0] && !r[1]) throw new Error('Usage: scroll <top> [left]');
     return {
-      top: r[0] ? parseIntArg(r[0], 'top') : undefined,
-      left: r[1] ? parseIntArg(r[1], 'left') : undefined,
+      top: r[0] ? parseNumberArg(r[0], 'top') : undefined,
+      left: r[1] ? parseNumberArg(r[1], 'left') : undefined,
     };
   }),
   resize: createShortcutCommand('viewport.resize', 'bbx resize <width> <height>', (r) => {
@@ -256,11 +261,12 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf|agents',
       'bbx status                                                         Check bridge connection',
       'bbx doctor                                                         Diagnose install, daemon, extension, and access readiness',
-      'bbx restart                                                        Restart the local Browser Bridge daemon',
-      'bbx proxy enable [--port 9223] [--bind-host 0.0.0.0] [--rotate-token]  Enable opt-in TCP proxy mode (idempotent: re-running keeps settings and token)',
+      'bbx restart                                                        Restart the local daemon and running MCP servers',
+      'bbx proxy enable [--port 9223] [--bind-host 127.0.0.1] [--rotate-token]  Enable loopback TCP proxy mode for SSH tunneling',
+      '  Non-loopback binds require --unsafe-plaintext because raw TCP is unencrypted.',
       'bbx proxy disable                                                  Disable proxy mode and restart the daemon',
       'bbx proxy status                                                   Show proxy config and daemon reachability',
-      'bbx remote add <name> <host:port> --token <token>                  Add a remote Browser Bridge destination (example: remote-bbx 192.168.56.20:9223)',
+      'bbx remote add <name> <host:port> (--token <token>|--token-file <path>)  Add a remote Browser Bridge destination',
       'bbx remote list                                                    List remote destinations',
       'bbx remote test <name>                                             Ping a remote destination',
       'bbx remote remove <name>                                           Remove a remote destination',

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

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 import { installMcpConfig } from './mcp-config.js';
@@ -452,10 +453,44 @@ async function installManagedSkill(skillName, target, targetDir) {
     throw new Error(`Refusing to overwrite unmanaged skill directory: ${targetDir}`);
   }
 
-  await fs.promises.rm(targetDir, { recursive: true, force: true });
-  await copyDir(sourceDir, targetDir);
-  await applyManagedSkillPatches(skillName, target, targetDir);
-  await fs.promises.writeFile(sentinelPath, formatManagedSkillSentinel(skillName), 'utf8');
+  await fs.promises.mkdir(path.dirname(targetDir), { recursive: true });
+  const suffix = `${process.pid}-${randomUUID()}`;
+  const temporaryDir = `${targetDir}.tmp-${suffix}`;
+  const backupDir = `${targetDir}.backup-${suffix}`;
+  let backupCreated = false;
+
+  try {
+    await copyDir(sourceDir, temporaryDir);
+    await applyManagedSkillPatches(skillName, target, temporaryDir);
+    await fs.promises.writeFile(
+      path.join(temporaryDir, managedSentinelFilename),
+      formatManagedSkillSentinel(skillName),
+      'utf8'
+    );
+
+    if (targetExists) {
+      await fs.promises.rename(targetDir, backupDir);
+      backupCreated = true;
+    }
+    try {
+      await fs.promises.rename(temporaryDir, targetDir);
+    } catch (error) {
+      if (backupCreated) {
+        await fs.promises.rename(backupDir, targetDir);
+        backupCreated = false;
+      }
+      throw error;
+    }
+    if (backupCreated) {
+      await fs.promises.rm(backupDir, { recursive: true, force: true }).catch(() => {});
+      backupCreated = false;
+    }
+  } finally {
+    await fs.promises.rm(temporaryDir, { recursive: true, force: true }).catch(() => {});
+    if (backupCreated && !(await pathExists(targetDir))) {
+      await fs.promises.rename(backupDir, targetDir).catch(() => {});
+    }
+  }
 }
 
 /**

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

@@ -4,6 +4,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+import { atomicWriteFile } from './atomic-write.js';
+
 /** @typedef {import('./types.js').McpClientName} McpClientName */
 
 /** @type {McpClientName[]} */
@@ -491,6 +493,8 @@ async function installJsonMcpConfig(clientName, configPath, stdout) {
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
       existing = parsed;
+    } else {
+      throw new Error('MCP config root must be a JSON object.');
     }
   } catch (error) {
     if (!isMissingFileError(error)) {
@@ -519,8 +523,9 @@ async function installJsonMcpConfig(clientName, configPath, stdout) {
     },
   };
 
-  await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.promises.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+  await atomicWriteFile(configPath, `${JSON.stringify(merged, null, 2)}\n`, {
+    encoding: 'utf8',
+  });
   stdout.write(`Wrote ${configPath}\n`);
 }
 
@@ -533,13 +538,14 @@ async function installCodexMcpConfig(configPath, stdout) {
   let raw = '';
   try {
     raw = await fs.promises.readFile(configPath, 'utf8');
-  } catch {
-    raw = '';
+  } catch (error) {
+    if (!isMissingFileError(error)) {
+      throw error;
+    }
   }
 
   const updated = upsertCodexServerBlock(raw);
-  await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.promises.writeFile(configPath, updated, 'utf8');
+  await atomicWriteFile(configPath, updated, { encoding: 'utf8' });
   stdout.write(`Wrote ${configPath}\n`);
 }
 
@@ -558,10 +564,15 @@ async function removeJsonMcpConfig(clientName, configPath, stdout) {
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
       existing = parsed;
     } else {
+      throw new Error('MCP config root must be a JSON object.');
+    }
+  } catch (error) {
+    if (isMissingFileError(error)) {
       return false;
     }
-  } catch {
-    return false;
+    throw new Error(
+      `Cannot remove Browser Bridge from ${configPath}: existing MCP config is not readable valid JSON.`
+    );
   }
 
   const shape = getMcpConfigShapeForPath(clientName, configPath);
@@ -584,8 +595,9 @@ async function removeJsonMcpConfig(clientName, configPath, stdout) {
     merged[topKey] = updatedBlock;
   }
 
-  await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.promises.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+  await atomicWriteFile(configPath, `${JSON.stringify(merged, null, 2)}\n`, {
+    encoding: 'utf8',
+  });
   stdout.write(`Removed ${configPath}\n`);
   return true;
 }
@@ -599,8 +611,11 @@ async function removeCodexMcpConfig(configPath, stdout) {
   let raw = '';
   try {
     raw = await fs.promises.readFile(configPath, 'utf8');
-  } catch {
-    return false;
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return false;
+    }
+    throw error;
   }
 
   if (!hasCodexServerBlock(raw)) {
@@ -608,8 +623,7 @@ async function removeCodexMcpConfig(configPath, stdout) {
   }
 
   const updated = removeCodexServerBlock(raw);
-  await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.promises.writeFile(configPath, updated, 'utf8');
+  await atomicWriteFile(configPath, updated, { encoding: 'utf8' });
   stdout.write(`Removed ${configPath}\n`);
   return true;
 }

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

@@ -5,6 +5,7 @@ import path from 'node:path';
 
 import { createTcpBridgeTransport, getBridgeDir } from '../../native-host/src/config.js';
 import { normalizeBridgeAuthToken } from '../../native-host/src/auth-token.js';
+import { atomicWriteFile } from './atomic-write.js';
 import { BridgeClient } from './client.js';
 
 const REMOTES_FILENAME = 'remotes.json';
@@ -121,15 +122,13 @@ export async function readRemoteConfig(options = {}) {
 
 /**
  * @param {RemoteConfig} config
- * @param {{ configPath?: string, writeFile?: typeof fs.promises.writeFile, mkdir?: typeof fs.promises.mkdir }} [options={}]
+ * @param {{ configPath?: string }} [options={}]
  * @returns {Promise<void>}
  */
 export async function writeRemoteConfig(config, options = {}) {
   const configPath = options.configPath ?? getRemoteConfigPath();
-  const writeFile = options.writeFile ?? fs.promises.writeFile.bind(fs.promises);
-  const mkdir = options.mkdir ?? fs.promises.mkdir.bind(fs.promises);
-  await mkdir(path.dirname(configPath), { recursive: true });
-  await writeFile(configPath, `${JSON.stringify({ remotes: config.remotes }, null, 2)}\n`, {
+  const remotes = config.remotes.map(validateRemoteDestination);
+  await atomicWriteFile(configPath, `${JSON.stringify({ remotes }, null, 2)}\n`, {
     encoding: 'utf8',
     mode: 0o600,
   });
@@ -140,15 +139,16 @@ export async function writeRemoteConfig(config, options = {}) {
  * @returns {Promise<RemoteDestination>}
  */
 export async function addRemoteDestination(remote) {
+  const validated = validateRemoteDestination(remote);
   const config = await readRemoteConfig();
-  const existing = config.remotes.findIndex((entry) => entry.id === remote.id);
+  const existing = config.remotes.findIndex((entry) => entry.id === validated.id);
   if (existing === -1) {
-    config.remotes.push(remote);
+    config.remotes.push(validated);
   } else {
-    config.remotes[existing] = remote;
+    config.remotes[existing] = validated;
   }
   await writeRemoteConfig(config);
-  return remote;
+  return validated;
 }
 
 /**
@@ -180,7 +180,7 @@ export async function listBridgeDestinations() {
 }
 
 /**
- * @typedef {{ port?: number, bindHost?: string, token?: string, rotateToken?: boolean }} ProxyEnableOptions
+ * @typedef {{ port?: number, bindHost?: string, token?: string, rotateToken?: boolean, unsafePlaintext?: boolean }} ProxyEnableOptions
  */
 
 /**
@@ -197,14 +197,92 @@ export async function listBridgeDestinations() {
  */
 export function resolveProxyEnableSettings(existing, options, generateToken) {
   const port = options.port ?? existing?.port ?? DEFAULT_REMOTE_PORT;
-  const bindHost = options.bindHost ?? existing?.bindHost ?? '0.0.0.0';
+  const bindHost = options.bindHost ?? existing?.bindHost ?? '127.0.0.1';
   if (options.token) {
-    return { port, bindHost, token: options.token, tokenSource: 'explicit' };
+    return {
+      port,
+      bindHost,
+      token: validateAuthToken(options.token),
+      tokenSource: 'explicit',
+    };
   }
-  if (!options.rotateToken && existing?.token) {
-    return { port, bindHost, token: existing.token, tokenSource: 'existing' };
+  const existingToken = normalizeBridgeAuthToken(existing?.token);
+  if (!options.rotateToken && existingToken) {
+    return { port, bindHost, token: existingToken, tokenSource: 'existing' };
   }
-  return { port, bindHost, token: generateToken(), tokenSource: 'generated' };
+  return {
+    port,
+    bindHost,
+    token: validateAuthToken(generateToken()),
+    tokenSource: 'generated',
+  };
+}
+
+/**
+ * Require an explicit acknowledgement before creating or changing a raw TCP
+ * listener that is reachable beyond the local machine. A stored non-loopback
+ * host may be reused without breaking an existing installation.
+ *
+ * @param {{ bindHost: string } | null} existing
+ * @param {ProxyEnableOptions} options
+ * @param {string} bindHost
+ * @returns {void}
+ */
+export function assertProxyBindSafety(existing, options, bindHost) {
+  if (
+    isLoopbackHost(bindHost) ||
+    options.unsafePlaintext === true ||
+    (options.bindHost === undefined && existing?.bindHost === bindHost)
+  ) {
+    return;
+  }
+  throw new Error(
+    'Refusing to bind Browser Bridge raw TCP to a non-loopback host without --unsafe-plaintext. This transport is unencrypted; keep the default 127.0.0.1 bind and use an SSH tunnel instead.'
+  );
+}
+
+/**
+ * @param {string} host
+ * @returns {boolean}
+ */
+export function isLoopbackHost(host) {
+  const normalized = host
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/gu, '');
+  const ipv4Parts = normalized.split('.').map(Number);
+  const isIpv4Loopback =
+    ipv4Parts.length === 4 &&
+    ipv4Parts[0] === 127 &&
+    ipv4Parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255);
+  return (
+    normalized === 'localhost' ||
+    normalized === '::1' ||
+    normalized === '0:0:0:0:0:0:0:1' ||
+    isIpv4Loopback
+  );
+}
+
+/**
+ * @param {RemoteDestination} remote
+ * @returns {RemoteDestination}
+ */
+function validateRemoteDestination(remote) {
+  const id = normalizeDestinationId(remote.id);
+  const { host, port } = parseRemoteEndpoint(`${remote.host}:${remote.port}`);
+  return { id, host, port, token: validateAuthToken(remote.token) };
+}
+
+/**
+ * @param {unknown} token
+ * @returns {string}
+ */
+function validateAuthToken(token) {
+  const normalized = normalizeBridgeAuthToken(token);
+  if (!normalized) {
+    throw new Error('Bridge auth token must be a UUID or 32-256 URL-safe characters.');
+  }
+  return normalized;
 }
 
 /**

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

@@ -19,6 +19,7 @@ import {
 } from '../../native-host/src/daemon-process.js';
 import { resolveDefaultExtensionId } from '../../native-host/src/install-manifest.js';
 import {
+  BridgeError,
   CLIENT_REQUEST_TIMEOUT_MARGIN_MS,
   DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
   getBridgeOperationTimeoutMs,
@@ -102,12 +103,14 @@ export async function resolveRef(client, refOrSelector, tabId = null, source) {
   );
 
   if (!response.ok) {
-    throw new Error(response.error.message);
+    throw new BridgeError(response.error.code, response.error.message, response.error.details);
   }
 
   const result = /** @type {{ nodes: Array<{ elementRef: string }> }} */ (response.result);
   if (!result.nodes || result.nodes.length === 0) {
-    throw new Error(`No element found for selector "${refOrSelector}".`);
+    throw new BridgeError('INVALID_REQUEST', `No element found for selector "${refOrSelector}".`, {
+      selector: refOrSelector,
+    });
   }
   return result.nodes[0].elementRef;
 }

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

@@ -4,11 +4,13 @@
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import { tryStartMcpProcessControl } from './lifecycle.js';
 import { startBridgeMcpServer } from './server.js';
 
 /**
  * @typedef {{
  *   start?: () => Promise<void>,
+ *   startControl?: typeof tryStartMcpProcessControl,
  *   argv?: string[],
  *   stdout?: { write: (chunk: string) => unknown },
  *   stderr?: { write: (chunk: string) => unknown },
@@ -33,6 +35,7 @@ const MCP_USAGE = [
 export async function runBridgeMcpCli(options = {}) {
   const {
     start = startBridgeMcpServer,
+    startControl = tryStartMcpProcessControl,
     argv = process.argv.slice(2),
     stdout = process.stdout,
     stderr = process.stderr,
@@ -45,7 +48,13 @@ export async function runBridgeMcpCli(options = {}) {
   }
 
   try {
-    await start();
+    const control = await startControl();
+    try {
+      await start();
+    } catch (error) {
+      await control?.dispose();
+      throw error;
+    }
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.stack || error.message : String(error);

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

@@ -103,7 +103,7 @@ function createGuidePrompt() {
       '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`, 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.',
+      '5. `browser_call` accepts `budgetPreset`; explicit method limits override preset values. 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,5 +1,6 @@
 // @ts-check
 
+import { BridgeError } from '../../protocol/src/index.js';
 import {
   createToolResult,
   getToolTokenBudget,
@@ -109,7 +110,7 @@ export async function handleCaptureTool(args) {
       const response = await requestBridgeWithRetry(client, entry.method, entry.params(args, ref), {
         tabId: requestedTabId,
         source: REQUEST_SOURCE,
-        tokenBudget: getToolTokenBudget(args),
+        tokenBudget: entry.method.startsWith('screenshot.') ? null : getToolTokenBudget(args),
       });
       if (!response.ok) {
         return summarizeToolResponse(response, entry.method);
@@ -127,15 +128,15 @@ export async function handleCaptureTool(args) {
  * @param {BridgeMethod} method
  * @returns {ToolResult}
  */
-function createScreenshotResult(response, method) {
+export function createScreenshotResult(response, method) {
   const result = toRecord(response.result);
   if (typeof result.image !== 'string') {
-    return summarizeToolError(`${method} returned no image data.`);
+    return summarizeToolError(new Error(`${method} returned no image data.`));
   }
 
   const image = normalizeBase64Image(result.image);
   if (!image) {
-    return summarizeToolError(`${method} returned invalid base64 image data.`);
+    return summarizeToolError(new Error(`${method} returned invalid base64 image data.`));
   }
 
   const rect = boundedRect(result.rect);
@@ -320,7 +321,9 @@ export async function handleInputTool(args) {
       const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
       const elementTarget = () => {
         const target = createInputTarget(args.elementRef, args.selector);
-        if (!target) throw new Error('Provide either elementRef or selector.');
+        if (!target) {
+          throw new BridgeError('INVALID_REQUEST', 'Provide either elementRef or selector.');
+        }
         return target;
       };
 

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

@@ -104,7 +104,8 @@ export async function handleDomTool(args) {
     return summarizeToolError('role is required for dom.find_by_role.');
   }
   if (args.action === 'query' || args.action === 'accessibility_tree') {
-    const inferred = inferBudgetFromSelector(args);
+    const inferred =
+      args.action === 'accessibility_tree' ? 'normal' : inferBudgetFromSelector(args);
     const withBudget = inferred ? { ...args, budgetPreset: args.budgetPreset ?? inferred } : args;
     return dispatchToolAction(DOM_ACTIONS, applyTreeBudgetPreset(withBudget), 'DOM');
   }
@@ -183,7 +184,6 @@ export const PATCH_ACTIONS = {
         addClass: 'add_class',
         removeClass: 'remove_class',
         setTextContent: 'set_text',
-        setProperty: 'set_attribute',
       };
       const normalizedOperation = opMap[operation] || operation;
       const value =

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

@@ -6,6 +6,7 @@ import {
   createToolResult,
   getBridgeDestinations,
   getToolTokenBudget,
+  requestBridgeWithRetry,
   summarizeToolError,
 } from './handlers-utils.js';
 
@@ -27,15 +28,23 @@ export async function handleTabsTool(args) {
     }
     const results = await Promise.all(
       destinations.map(async (destination) => {
-        const client = await createBridgeClientForDestination(
-          destination.local ? null : destination.id
-        );
+        /** @type {import('../../agent-client/src/client.js').BridgeClient | null} */
+        let client = null;
         try {
+          client = await createBridgeClientForDestination(
+            destination.local ? null : destination.id
+          );
           await client.connect();
-          const response = await client.request({
-            method: 'tabs.list',
-            meta: { source: 'mcp' },
-          });
+          const response = await requestBridgeWithRetry(
+            client,
+            'tabs.list',
+            {},
+            {
+              tabId: null,
+              source: 'mcp',
+              tokenBudget: null,
+            }
+          );
           if (!response.ok) {
             return {
               destinationId: destination.id,
@@ -58,7 +67,9 @@ export async function handleTabsTool(args) {
             tabs: [],
           };
         } finally {
-          await client.close();
+          if (client) {
+            await client.close().catch(() => {});
+          }
         }
       })
     );
@@ -73,7 +84,7 @@ export async function handleTabsTool(args) {
         tabs,
         destinations: results,
       },
-      false
+      failures.length === results.length
     );
   }
   if (args.action === 'create') {