@browserbridge/bbx 1.6.4 → 1.7.1

package/package.json

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

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

@@ -9,21 +9,23 @@ import { fileURLToPath } from 'node:url';
 
 import {
   applyWindowsTcpTransportDefaults,
+  createTcpBridgeTransport,
   getProxyConfigPath,
   readProxyConfig,
   SUPPORTED_BROWSERS,
 } from '../../native-host/src/config.js';
 import { writeBridgeAuthToken } from '../../native-host/src/auth-token.js';
+import { pingExistingDaemon } from '../../native-host/src/daemon.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 import { uninstallNativeManifest } from '../../native-host/src/install-manifest.js';
 import {
   createRuntimeContext,
+  getProtocolVersion,
   METHODS,
   summarizeBatchErrorItem,
   summarizeBatchResponseItem,
 } from '../../protocol/src/index.js';
 import { startBridgeMcpServer } from '../../mcp-server/src/server.js';
-import { BridgeClient } from './client.js';
 import { CLI_HELP_SECTIONS, SHORTCUT_COMMANDS } from './command-registry.js';
 import {
   interactiveCheckbox,
@@ -59,6 +61,7 @@ import {
   parseRemoteEndpoint,
   readRemoteConfig,
   removeRemoteDestination,
+  resolveProxyEnableSettings,
 } from './remotes.js';
 import { collectSetupStatus } from './setup-status.js';
 import { annotateBridgeSummary, summarizeBridgeResponse } from './subagent.js';
@@ -69,6 +72,32 @@ import { annotateBridgeSummary, summarizeBridgeResponse } from './subagent.js';
 const REQUEST_SOURCE = 'cli';
 const TEST_TIMEOUT_ENV = 'BBX_CLIENT_REQUEST_TIMEOUT_MS';
 const TEST_DETECTED_MCP_CLIENTS_ENV = 'BBX_TEST_DETECTED_MCP_CLIENTS';
+const REMOTE_ENV = 'BBX_REMOTE';
+
+/**
+ * Commands that only make sense against the local machine (setup, daemon
+ * lifecycle, and config management). The explicit --remote flag is rejected
+ * for these; the ambient BBX_REMOTE env var is ignored.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const LOCAL_ONLY_COMMANDS = new Set([
+  'help',
+  '--help',
+  '-h',
+  '--version',
+  '-v',
+  'skill',
+  'install',
+  'uninstall',
+  'install-skill',
+  'install-mcp',
+  'mcp',
+  'proxy',
+  'remote',
+  'doctor',
+  'restart',
+]);
 
 /**
  * Read all of stdin as UTF-8 text. Resolves once stdin closes.
@@ -89,7 +118,18 @@ function readStdin() {
   });
 }
 
-const [, , command, ...rest] = process.argv;
+const remoteFlag = extractRemoteFlag(process.argv.slice(2));
+const [command, ...rest] = remoteFlag.rest;
+
+if (remoteFlag.explicit && command && LOCAL_ONLY_COMMANDS.has(command)) {
+  process.stderr.write(`The --remote flag is not supported with "${command}".\n`);
+  process.exit(1);
+}
+
+const remoteDestinationId =
+  command && LOCAL_ONLY_COMMANDS.has(command)
+    ? null
+    : (remoteFlag.remoteId ?? process.env[REMOTE_ENV] ?? null);
 
 if (!command || ['help', '--help', '-h'].includes(command)) {
   printUsage();
@@ -396,23 +436,60 @@ if (command === 'mcp') {
 }
 
 if (command === 'proxy') {
-  await handleProxyCommand(rest);
-  process.exit(0);
+  await runLocalCommand(() => handleProxyCommand(rest));
+  process.exit();
 }
 
 if (command === 'remote') {
-  await handleRemoteCommand(rest);
-  process.exit(0);
+  await runLocalCommand(() => handleRemoteCommand(rest));
+  process.exit();
 }
 
 const clientTimeoutMs = getClientTimeoutOverride();
 applyWindowsTcpTransportDefaults();
-const client = new BridgeClient(
-  clientTimeoutMs ? { defaultTimeoutMs: clientTimeoutMs } : undefined
-);
+const client = await createCliClient();
 
 await main();
 
+/**
+ * Run a local (pre-main) command, converting thrown errors into a friendly
+ * one-line message instead of an unhandled stack trace.
+ *
+ * @param {() => Promise<void>} run
+ * @returns {Promise<void>}
+ */
+async function runLocalCommand(run) {
+  try {
+    await run();
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Create the bridge client for this invocation, honoring the --remote flag
+ * and BBX_REMOTE env var. Exits with a friendly error when the destination
+ * is not configured.
+ *
+ * @returns {Promise<import('./client.js').BridgeClient>}
+ */
+async function createCliClient() {
+  try {
+    return await createBridgeClientForDestination(
+      remoteDestinationId,
+      clientTimeoutMs ? { defaultTimeoutMs: clientTimeoutMs } : {}
+    );
+  } catch (error) {
+    printJson({
+      ok: false,
+      summary: `ERROR: ${error instanceof Error ? error.message : String(error)}`,
+      evidence: null,
+    });
+    process.exit(1);
+  }
+}
+
 async function main() {
   try {
     if (command === 'status') {
@@ -552,7 +629,7 @@ async function main() {
               evidence: null,
               durationMs: 0,
               approxTokens: 0,
-              meta: { protocol_version: '1.0' },
+              meta: { protocol_version: getProtocolVersion() },
               error: {
                 code: 'INVALID_REQUEST',
                 message: 'Each batch call needs a method.',
@@ -569,7 +646,7 @@ async function main() {
               evidence: null,
               durationMs: 0,
               approxTokens: 0,
-              meta: { protocol_version: '1.0' },
+              meta: { protocol_version: getProtocolVersion() },
               error: {
                 code: 'INVALID_REQUEST',
                 message: `Unknown bridge method "${call.method}".`,
@@ -859,7 +936,12 @@ async function handleProxyCommand(args) {
   const [subcommand, ...restArgs] = args;
   if (subcommand === 'enable') {
     const options = parseProxyEnableArgs(restArgs);
-    const token = options.token ?? randomUUID();
+    const existing = readProxyConfig();
+    const { port, bindHost, token, tokenSource } = resolveProxyEnableSettings(
+      existing,
+      options,
+      randomUUID
+    );
     await writeBridgeAuthToken(token);
     const configPath = getProxyConfigPath();
     await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
@@ -868,8 +950,8 @@ async function handleProxyCommand(args) {
       `${JSON.stringify(
         {
           enabled: true,
-          port: options.port,
-          bindHost: options.bindHost,
+          port,
+          bindHost,
           token,
         },
         null,
@@ -878,14 +960,22 @@ async function handleProxyCommand(args) {
       { encoding: 'utf8', mode: 0o600 }
     );
     const result = await restartBridgeDaemon();
-    const exampleHost = getProxyExampleHost(options.bindHost);
-    process.stdout.write(
-      [
-        `Browser Bridge proxy enabled on ${options.bindHost}:${options.port}.`,
-        '',
-        `Token: ${token}`,
-        `Config: ${configPath}`,
-        `Daemon: ${result.previouslyRunning ? 'restarted' : 'started'} (pid ${result.pid})`,
+    const exampleHost = getProxyExampleHost(bindHost);
+    const tokenNote =
+      tokenSource === 'existing'
+        ? ' (unchanged — already-configured clients keep working; pass --rotate-token to generate a new secret)'
+        : tokenSource === 'generated' && existing
+          ? ' (rotated — update every configured client with `bbx remote add`)'
+          : '';
+    const lines = [
+      `Browser Bridge proxy enabled on ${bindHost}:${port}.`,
+      '',
+      `Token: ${token}${tokenNote}`,
+      `Config: ${configPath}`,
+      `Daemon: ${result.previouslyRunning ? 'restarted' : 'started'} (pid ${result.pid})`,
+    ];
+    if (tokenSource !== 'existing') {
+      lines.push(
         '',
         'On your dev machine, add this remote:',
         '',
@@ -893,10 +983,11 @@ async function handleProxyCommand(args) {
         '',
         'Example:',
         '',
-        `bbx remote add remote-bbx ${exampleHost}:${options.port} --token ${token}`,
-        '',
-      ].join('\n')
-    );
+        `bbx remote add remote-bbx ${exampleHost}:${port} --token ${token}`
+      );
+    }
+    lines.push('');
+    process.stdout.write(lines.join('\n'));
     return;
   }
 
@@ -916,10 +1007,12 @@ async function handleProxyCommand(args) {
       process.stdout.write('Browser Bridge proxy is disabled.\n');
       return;
     }
+    const reachable = await pingExistingDaemon(createTcpBridgeTransport(config.port, '127.0.0.1'));
     process.stdout.write(
       [
         `Browser Bridge proxy is enabled on ${config.bindHost}:${config.port}.`,
         `Config: ${getProxyConfigPath()}`,
+        `Daemon: ${reachable ? 'reachable' : 'not reachable'} on 127.0.0.1:${config.port}`,
         '',
       ].join('\n')
     );
@@ -930,12 +1023,15 @@ async function handleProxyCommand(args) {
 }
 
 /**
+ * Parse `bbx proxy enable` flags. Values stay undefined when not passed so an
+ * existing proxy config can be reused instead of silently reset to defaults.
+ *
  * @param {string[]} args
- * @returns {{ port: number, bindHost: string, token?: string }}
+ * @returns {import('./remotes.js').ProxyEnableOptions}
  */
 function parseProxyEnableArgs(args) {
-  /** @type {{ port: number, bindHost: string, token?: string }} */
-  const options = { port: 9223, bindHost: '0.0.0.0' };
+  /** @type {import('./remotes.js').ProxyEnableOptions} */
+  const options = {};
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === '--port') {
@@ -956,9 +1052,16 @@ function parseProxyEnableArgs(args) {
       }
       continue;
     }
+    if (arg === '--rotate-token') {
+      options.rotateToken = true;
+      continue;
+    }
     throw new Error(`Unknown proxy enable option "${arg}".`);
   }
-  if (options.port < 1 || options.port > 65535) {
+  if (options.token && options.rotateToken) {
+    throw new Error('Use either --token or --rotate-token, not both.');
+  }
+  if (options.port !== undefined && (options.port < 1 || options.port > 65535)) {
     throw new Error('port must be an integer between 1 and 65535.');
   }
   return options;
@@ -1049,10 +1152,23 @@ async function handleRemoteCommand(args) {
     try {
       await remoteClient.connect();
       const response = await remoteClient.request({ method: 'health.ping' });
+      if (response.ok) {
+        const health = /** @type {{ extensionConnected?: boolean }} */ (response.result);
+        process.stdout.write(
+          `Remote destination "${name}" is reachable (extension ${
+            health.extensionConnected === true ? 'connected' : 'not connected'
+          }).\n`
+        );
+      } else {
+        process.exitCode = 1;
+        process.stdout.write(`Remote destination "${name}" failed: ${response.error.message}\n`);
+      }
+    } catch (error) {
+      process.exitCode = 1;
       process.stdout.write(
-        response.ok
-          ? `Remote destination "${name}" is reachable.\n`
-          : `Remote destination "${name}" failed: ${response.error.message}\n`
+        `Remote destination "${name}" is not reachable: ${
+          error instanceof Error ? error.message : String(error)
+        }\n`
       );
     } finally {
       await remoteClient.close();
@@ -1214,7 +1330,7 @@ function printCallResponse(response) {
 }
 
 function printUsage() {
-  const blocks = ['Usage: bbx <command> [args]'];
+  const blocks = ['Usage: bbx [--remote <name>] <command> [args]'];
   for (const section of CLI_HELP_SECTIONS) {
     blocks.push('', `${section.title}:`);
     blocks.push(...section.lines.map((line) => `  ${line}`));
@@ -1297,6 +1413,28 @@ async function parseCallCommand(args) {
   throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
 }
 
+/**
+ * Extract the global --remote flag from anywhere in the argument list.
+ * Exits with a usage error when the flag is present without a value.
+ *
+ * @param {string[]} args
+ * @returns {{ remoteId: string | null, explicit: boolean, rest: string[] }}
+ */
+function extractRemoteFlag(args) {
+  const rest = [...args];
+  const index = rest.indexOf('--remote');
+  if (index === -1) {
+    return { remoteId: null, explicit: false, rest };
+  }
+  const remoteId = rest[index + 1];
+  if (!remoteId || remoteId.startsWith('--')) {
+    process.stderr.write('--remote requires a destination name (see `bbx remote list`).\n');
+    process.exit(1);
+  }
+  rest.splice(index, 2);
+  return { remoteId, explicit: true, rest };
+}
+
 /**
  * @param {string[]} args
  * @returns {{ tabId: number | null, rest: string[] }}

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

@@ -1,14 +1,16 @@
 // @ts-check
 
 import { EventEmitter, once } from 'node:events';
+import fs from 'node:fs';
 import net from 'node:net';
 import { randomUUID } from 'node:crypto';
 
 import {
   createRequest,
   DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
-  PROTOCOL_VERSION,
+  getProtocolVersion,
   parseJsonLines,
+  setProtocolPackageVersion,
 } from '../../protocol/src/index.js';
 import {
   createSocketBridgeTransport,
@@ -26,6 +28,21 @@ import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 /** @typedef {import('./types.js').PendingRequest} PendingRequest */
 /** @typedef {import('./types.js').ProtocolHealthResult} ProtocolHealthResult */
 
+setProtocolPackageVersion(loadPackageVersion());
+
+/**
+ * @returns {string | null}
+ */
+function loadPackageVersion() {
+  try {
+    const raw = fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed.version === 'string' ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * @param {string} left
  * @param {string} right
@@ -57,6 +74,18 @@ function createTimeoutError(method, timeoutMs) {
   return error;
 }
 
+/**
+ * npm exec often runs a checkout-local CLI against an already-connected global
+ * daemon. In that mode, protocol drift should warn instead of replacing the
+ * user's working daemon and temporarily disconnecting the extension.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {boolean}
+ */
+function shouldAutoRestartDaemonOnVersionMismatch(env = process.env) {
+  return env.npm_command !== 'exec';
+}
+
 /**
  * @param {net.Socket} socket
  * @param {string} line
@@ -83,7 +112,7 @@ export class BridgeClient extends EventEmitter {
     clientId = `agent_${randomUUID()}`,
     defaultTimeoutMs = DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
     autoReconnect = false,
-    restartDaemonOnVersionMismatch = true,
+    restartDaemonOnVersionMismatch = shouldAutoRestartDaemonOnVersionMismatch(),
     restartDaemonFn = restartBridgeDaemon,
     authToken = undefined,
   } = {}) {
@@ -390,9 +419,16 @@ export class BridgeClient extends EventEmitter {
           ? healthResult.supported_versions
           : [];
     const latestRemote = remoteVersions[0];
+    if (
+      healthResult?.extensionConnected === true &&
+      Array.isArray(healthResult.supported_versions) &&
+      !healthResult.supported_versions.includes(getProtocolVersion())
+    ) {
+      return false;
+    }
     return (
       typeof latestRemote === 'string' &&
-      compareProtocolVersions(latestRemote, PROTOCOL_VERSION) < 0
+      compareProtocolVersions(latestRemote, getProtocolVersion()) < 0
     );
   }
 
@@ -436,20 +472,21 @@ export class BridgeClient extends EventEmitter {
     if (remoteVersions.length === 0) {
       return {
         compatible: true,
-        localVersion: PROTOCOL_VERSION,
+        localVersion: getProtocolVersion(),
         remoteVersions,
       };
     }
-    const compatible = remoteVersions.includes(PROTOCOL_VERSION);
+    const localVersion = getProtocolVersion();
+    const compatible = remoteVersions.includes(localVersion);
     return {
       compatible,
-      localVersion: PROTOCOL_VERSION,
+      localVersion,
       remoteVersions,
       ...(!compatible && {
         warning:
           typeof healthResult?.migration_hint === 'string' && healthResult.migration_hint
             ? healthResult.migration_hint
-            : `Protocol mismatch: client speaks ${PROTOCOL_VERSION} but remote supports [${remoteVersions.join(', ')}]. Update the ${remoteVersions[0] > PROTOCOL_VERSION ? 'client (npm)' : 'extension'} to match.`,
+            : `Protocol mismatch: client speaks ${localVersion} but remote supports [${remoteVersions.join(', ')}]. Update the ${remoteVersions[0] > localVersion ? 'client (npm)' : 'extension'} to match.`,
       }),
     };
   }

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

@@ -257,10 +257,13 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       '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]              Enable opt-in TCP proxy mode and print a token',
+      '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 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 list                                                    List remote destinations',
+      'bbx remote test <name>                                             Ping a remote destination',
+      'bbx remote remove <name>                                           Remove a remote destination',
       'bbx access-request                                                 Request Browser Bridge access for the focused window',
       'bbx logs                                                           Recent bridge logs',
       'bbx tabs                                                           List available tabs',
@@ -277,6 +280,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx call [--tab <tabId>] <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?},...]'                           Parallel method calls",
+      '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/remotes.js

@@ -179,6 +179,34 @@ export async function listBridgeDestinations() {
   ];
 }
 
+/**
+ * @typedef {{ port?: number, bindHost?: string, token?: string, rotateToken?: boolean }} ProxyEnableOptions
+ */
+
+/**
+ * Merge `bbx proxy enable` options with an existing proxy config so re-running
+ * the command is idempotent: the port, bind host, and shared secret are
+ * preserved unless explicitly overridden. The token only changes when passed
+ * via --token or regenerated via --rotate-token, so already-configured remote
+ * clients keep working across repeated enables.
+ *
+ * @param {{ port: number, bindHost: string, token?: string } | null} existing
+ * @param {ProxyEnableOptions} options
+ * @param {() => string} generateToken
+ * @returns {{ port: number, bindHost: string, token: string, tokenSource: 'explicit' | 'existing' | 'generated' }}
+ */
+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';
+  if (options.token) {
+    return { port, bindHost, token: options.token, tokenSource: 'explicit' };
+  }
+  if (!options.rotateToken && existing?.token) {
+    return { port, bindHost, token: existing.token, tokenSource: 'existing' };
+  }
+  return { port, bindHost, token: generateToken(), tokenSource: 'generated' };
+}
+
 /**
  * @param {string | null | undefined} destinationId
  * @param {{ defaultTimeoutMs?: number }} [options={}]