@browserbridge/bbx 1.11.0 → 1.11.2

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

@@ -47,17 +47,119 @@ 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>} */
+/** @type {AsyncLocalStorage<{ era: import('../../protocol/src/types.js').McpProtocolEra, signal?: AbortSignal }>} */
 const MCP_REQUEST_ERA = new AsyncLocalStorage();
 
 /**
  * @template T
  * @param {import('../../protocol/src/types.js').McpProtocolEra} era
  * @param {() => T} callback
+ * @param {AbortSignal} [signal]
  * @returns {T}
  */
-export function runWithMcpRequestEra(era, callback) {
-  return MCP_REQUEST_ERA.run(era, callback);
+export function runWithMcpRequestEra(era, callback, signal) {
+  return MCP_REQUEST_ERA.run({ era, signal }, callback);
+}
+
+/** @returns {void} */
+export function throwIfMcpRequestCancelled() {
+  MCP_REQUEST_ERA.getStore()?.signal?.throwIfAborted();
+}
+
+/**
+ * Race request-owned work against cancellation and an optional absolute budget.
+ * Connection attempts can finish after close(), so dispose late completions too.
+ *
+ * @template T
+ * @param {() => Promise<T>} operation
+ * @param {{ timeoutMs?: number, onCancel?: () => void }} [options]
+ * @returns {Promise<T>}
+ */
+function awaitMcpOperation(operation, options = {}) {
+  const signal = MCP_REQUEST_ERA.getStore()?.signal;
+  const deadline = options.timeoutMs === undefined ? null : Date.now() + options.timeoutMs;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let cancelled = false;
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let timer;
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    };
+    /** @param {unknown} error */
+    const cancel = (error) => {
+      if (settled) return;
+      settled = true;
+      cancelled = true;
+      cleanup();
+      options.onCancel?.();
+      reject(error);
+    };
+    const onAbort = () => cancel(signal?.reason);
+    const onTimeout = () => cancel(new BridgeError('TIMEOUT', 'MCP connection deadline exceeded.'));
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (deadline !== null) {
+      timer = setTimeout(onTimeout, Math.max(0, deadline - Date.now()));
+    }
+    Promise.resolve()
+      .then(() => {
+        if (deadline !== null && Date.now() >= deadline) onTimeout();
+        if (settled) return undefined;
+        return operation();
+      })
+      .then(
+        (result) => {
+          if (cancelled) options.onCancel?.();
+          if (!settled && deadline !== null && Date.now() >= deadline) onTimeout();
+          if (settled) return;
+          settled = true;
+          cleanup();
+          resolve(/** @type {T} */ (result));
+        },
+        (error) => {
+          if (cancelled) options.onCancel?.();
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(error);
+        }
+      );
+  });
+}
+
+/**
+ * @param {number} delayMs
+ * @returns {Promise<void>}
+ */
+function waitForMcpRequest(delayMs) {
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  return awaitMcpOperation(
+    () =>
+      new Promise((resolve) => {
+        timer = setTimeout(resolve, delayMs);
+      }),
+    { onCancel: () => clearTimeout(timer) }
+  );
+}
+
+/**
+ * @param {import('../../agent-client/src/client.js').BridgeClient} client
+ * @param {number} timeoutMs
+ * @returns {Promise<void>}
+ */
+function connectMcpClient(client, timeoutMs) {
+  return awaitMcpOperation(() => client.connect(), {
+    timeoutMs,
+    onCancel: () => {
+      void client.close().catch(() => {});
+    },
+  });
 }
 
 /** @type {ReadonlySet<BridgeMethod>} */
@@ -107,7 +209,7 @@ const RETRY_SAFE_METHODS = new Set([
 export function isRetrySafeBridgeMethod(method, params) {
   if (method === 'page.get_console' || method === 'page.get_network') {
     return (
-      params.clear !== true &&
+      (params.clear === undefined || params.clear === false) &&
       (method !== 'page.get_network' ||
         params.source !== 'cdp' ||
         params.capture === undefined ||
@@ -227,27 +329,49 @@ export function summarizeToolError(error) {
  */
 export async function withToolClient(callback, options = {}) {
   try {
-    if (!options.destinationId) {
-      return await withBridgeClient(callback, {
-        checkProtocolOnConnect: false,
-        clientId: MCP_CLIENT_ID,
-      });
-    }
-    const client = await createBridgeClientForDestination(options.destinationId, {
-      checkProtocolOnConnect: false,
-      clientId: MCP_CLIENT_ID,
-    });
-    await client.connect();
-    try {
-      return await callback(client);
-    } finally {
-      await client.close();
-    }
+    return await withMcpRequestClient(callback, options);
   } catch (error) {
     return summarizeToolError(error);
   }
 }
 
+/**
+ * @template T
+ * @param {(client: import('../../agent-client/src/client.js').BridgeClient) => Promise<T>} callback
+ * @param {{ destinationId?: string | null }} [options]
+ * @returns {Promise<T>}
+ */
+export async function withMcpRequestClient(callback, options = {}) {
+  throwIfMcpRequestCancelled();
+  const client = await createBridgeClientForDestination(options.destinationId, {
+    checkProtocolOnConnect: false,
+    clientId: MCP_CLIENT_ID,
+  });
+  let completed = false;
+  try {
+    const result = await awaitMcpOperation(
+      async () => {
+        await connectMcpClient(client, client.defaultTimeoutMs);
+        throwIfMcpRequestCancelled();
+        return callback(client);
+      },
+      {
+        onCancel: () => {
+          void client.close().catch(() => {});
+        },
+      }
+    );
+    completed = true;
+    return result;
+  } finally {
+    if (completed) {
+      await client.close();
+    } else {
+      await client.close().catch(() => {});
+    }
+  }
+}
+
 /**
  * @param {import('../../agent-client/src/client.js').BridgeClient} client
  * @param {{ elementRef?: string | undefined, selector?: string | undefined }} input
@@ -255,11 +379,33 @@ export async function withToolClient(callback, options = {}) {
  * @returns {Promise<string>}
  */
 export async function resolveToolRef(client, input, tabId = null) {
+  throwIfMcpRequestCancelled();
   if (typeof input.elementRef === 'string' && input.elementRef) {
     return input.elementRef;
   }
   if (typeof input.selector === 'string' && input.selector) {
-    return resolveRef(client, input.selector, tabId, REQUEST_SOURCE);
+    const response = await requestBridgeWithRetry(
+      client,
+      'dom.query',
+      {
+        selector: input.selector,
+      },
+      { tabId, source: REQUEST_SOURCE }
+    );
+    if (!response.ok) {
+      throw new BridgeError(response.error.code, response.error.message, response.error.details);
+    }
+    const result = /** @type {{ nodes?: Array<{ elementRef: string }> }} */ (response.result);
+    if (!result.nodes?.length) {
+      throw new BridgeError(
+        'INVALID_REQUEST',
+        `No element found for selector "${input.selector}".`,
+        {
+          selector: input.selector,
+        }
+      );
+    }
+    return result.nodes[0].elementRef;
   }
   throw new BridgeError('INVALID_REQUEST', 'Provide either elementRef or selector.');
 }
@@ -570,7 +716,7 @@ export function isConnectionLossError(error) {
  * Wait, bounded, for the client to regain its daemon connection.
  *
  * When the client's own auto-reconnect loop is active it owns reconnecting and
- * emits `reconnected`; otherwise one manual connect is attempted per poll
+ * reconnects independently; otherwise one manual connect is attempted per poll
  * interval. Application state is never touched here - this only restores the
  * transport.
  *
@@ -580,26 +726,17 @@ export function isConnectionLossError(error) {
  */
 export async function waitForClientReconnect(client, timeoutMs = RECONNECT_WAIT_TIMEOUT_MS) {
   const deadline = Date.now() + timeoutMs;
+  throwIfMcpRequestCancelled();
   while (!client.connected && Date.now() < deadline) {
     if (client.autoReconnect) {
-      await new Promise((resolve) => {
-        const remaining = Math.max(0, deadline - Date.now());
-        /** @type {ReturnType<typeof setTimeout>} */
-        let timer;
-        const cleanup = () => {
-          clearTimeout(timer);
-          client.off('reconnected', onReconnected);
-          resolve(undefined);
-        };
-        const onReconnected = () => cleanup();
-        timer = setTimeout(cleanup, Math.min(RECONNECT_POLL_INTERVAL_MS, remaining));
-        client.on('reconnected', onReconnected);
-      });
+      await waitForMcpRequest(Math.min(RECONNECT_POLL_INTERVAL_MS, deadline - Date.now()));
       continue;
     }
     try {
-      await client.connect();
+      await connectMcpClient(client, deadline - Date.now());
     } catch (error) {
+      throwIfMcpRequestCancelled();
+      if (error instanceof BridgeError && error.code === 'TIMEOUT') return false;
       if (error instanceof Error && /already connected/u.test(error.message)) {
         break;
       }
@@ -607,9 +744,7 @@ export async function waitForClientReconnect(client, timeoutMs = RECONNECT_WAIT_
     }
     if (!client.connected) {
       const remaining = Math.max(0, deadline - Date.now());
-      await new Promise((resolve) =>
-        setTimeout(resolve, Math.min(RECONNECT_POLL_INTERVAL_MS, remaining))
-      );
+      await waitForMcpRequest(Math.min(RECONNECT_POLL_INTERVAL_MS, remaining));
     }
   }
   return client.connected;
@@ -625,13 +760,22 @@ export async function waitForClientReconnect(client, timeoutMs = RECONNECT_WAIT_
 export async function requestBridgeWithRetry(client, method, params, options) {
   const requestOptions = {
     ...options,
-    mcpEra: options.mcpEra ?? MCP_REQUEST_ERA.getStore(),
+    mcpEra: options.mcpEra ?? MCP_REQUEST_ERA.getStore()?.era,
   };
+  /** @param {typeof requestOptions} attemptOptions */
+  const attempt = (attemptOptions) =>
+    awaitMcpOperation(async () => {
+      throwIfMcpRequestCancelled();
+      if (!client.connected) await connectMcpClient(client, client.defaultTimeoutMs);
+      throwIfMcpRequestCancelled();
+      return requestBridge(client, method, params, attemptOptions);
+    });
   /** @type {BridgeResponse} */
   let response;
   try {
-    response = await requestBridge(client, method, params, requestOptions);
+    response = await attempt(requestOptions);
   } catch (error) {
+    throwIfMcpRequestCancelled();
     if (!isConnectionLossError(error) || !isRetrySafeBridgeMethod(method, params)) {
       throw error;
     }
@@ -641,7 +785,7 @@ export async function requestBridgeWithRetry(client, method, params, options) {
     if (!(await waitForClientReconnect(client))) {
       throw error;
     }
-    return requestBridge(client, method, params, {
+    return attempt({
       ...requestOptions,
       automaticRetry: 'mcp_second_attempt',
     });
@@ -655,8 +799,8 @@ export async function requestBridgeWithRetry(client, method, params, options) {
     process.stderr.write(
       `[bbx-mcp] Retrying ${method} after ${delay}ms (${response.error.code})\n`
     );
-    await new Promise((r) => setTimeout(r, delay));
-    return requestBridge(client, method, params, {
+    await waitForMcpRequest(delay);
+    return attempt({
       ...requestOptions,
       automaticRetry: 'mcp_second_attempt',
     });

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

@@ -172,7 +172,8 @@ export function createBridgeMcpServer(options = {}) {
    */
   const registerTool = (name, config, handler) => {
     const wrappedHandler = /** @type {typeof handler} */ (
-      (args, context) => runWithMcpRequestEra(era, () => handler(args, context))
+      (args, context) =>
+        runWithMcpRequestEra(era, () => handler(args, context), context.mcpReq.signal)
     );
     const registration = server.registerTool(name, config, wrappedHandler);
     registrations.set(name, registration);

package/packages/native-host/bin/postinstall.js

@@ -17,15 +17,17 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, '../../..');
 
 /**
- * npm exec may run package lifecycle hooks while resolving the local bin. Keep
- * transient `npm exec -- bbx ...` invocations from rewriting host setup or
- * replacing a working daemon.
+ * Host setup is appropriate for a global CLI install, not when this package is
+ * an ordinary project dependency. npm exec is also always non-mutating. The
+ * explicit force switch is reserved for controlled packaging/tests.
  *
  * @param {NodeJS.ProcessEnv} [env=process.env]
  * @returns {boolean}
  */
-function shouldSkipPostinstall(env = process.env) {
-  return env.npm_command === 'exec';
+export function shouldSkipPostinstall(env = process.env) {
+  const globalInstall = env.npm_config_global === 'true' || env.npm_config_global === '1';
+  const explicitlyEnabled = env.BBX_POSTINSTALL_FORCE === '1';
+  return env.npm_command === 'exec' || (!globalInstall && !explicitlyEnabled);
 }
 
 /**

package/packages/native-host/src/auth-token.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -9,7 +9,14 @@ import { getBridgeDir } from './config.js';
 export const BRIDGE_AUTH_TOKEN_ENV = 'BBX_AUTH_TOKEN';
 export const BRIDGE_AUTH_TOKEN_FILE_ENV = 'BBX_AUTH_TOKEN_FILE';
 const TOKEN_FILENAME = 'daemon.auth';
+const EXTENSION_TOKEN_FILENAME = 'daemon.extension.auth';
 const TOKEN_BYTES = 32;
+/**
+ * @typedef {{ tokenPath?: string, readFile?: typeof fs.promises.readFile,
+ * writeFile?: typeof fs.promises.writeFile, mkdir?: typeof fs.promises.mkdir,
+ * chmod?: typeof fs.promises.chmod, link?: typeof fs.promises.link,
+ * unlink?: typeof fs.promises.unlink, randomBytesFn?: typeof randomBytes }} TokenInitOptions
+ */
 const TOKEN_PATTERN = /^[A-Za-z0-9_-]{32,256}$/u;
 const UUID_TOKEN_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
@@ -22,6 +29,17 @@ export function getBridgeAuthTokenPath(env = process.env) {
   return path.join(getBridgeDir(env), TOKEN_FILENAME);
 }
 
+/**
+ * Private credential used only by the Chrome native host when registering the
+ * extension role. Remote agent configurations never receive this token.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string}
+ */
+export function getBridgeExtensionAuthTokenPath(env = process.env) {
+  return path.join(getBridgeDir(env), EXTENSION_TOKEN_FILENAME);
+}
+
 /**
  * @param {unknown} value
  * @returns {string | null}
@@ -91,6 +109,25 @@ export async function readBridgeAuthToken(options = {}) {
   }
   const tokenPath = options.tokenPath ?? getBridgeAuthTokenPath();
   const readFile = options.readFile ?? fs.promises.readFile.bind(fs.promises);
+  return readStoredBridgeAuthToken(tokenPath, readFile);
+}
+
+/**
+ * @param {{ tokenPath?: string, readFile?: typeof fs.promises.readFile }} [options={}]
+ * @returns {Promise<string | null>}
+ */
+export async function readBridgeExtensionAuthToken(options = {}) {
+  const tokenPath = options.tokenPath ?? getBridgeExtensionAuthTokenPath();
+  const readFile = options.readFile ?? fs.promises.readFile.bind(fs.promises);
+  return readStoredBridgeAuthToken(tokenPath, readFile);
+}
+
+/**
+ * @param {string} tokenPath
+ * @param {typeof fs.promises.readFile} readFile
+ * @returns {Promise<string | null>}
+ */
+async function readStoredBridgeAuthToken(tokenPath, readFile) {
   try {
     return normalizeBridgeAuthToken(await readFile(tokenPath, 'utf8'));
   } catch (error) {
@@ -124,35 +161,122 @@ export async function writeBridgeAuthToken(token, options = {}) {
 }
 
 /**
- * @param {{
- *   tokenPath?: string,
- *   readFile?: typeof fs.promises.readFile,
- *   writeFile?: typeof fs.promises.writeFile,
- *   mkdir?: typeof fs.promises.mkdir,
- *   chmod?: typeof fs.promises.chmod,
- *   randomBytesFn?: typeof randomBytes
- * }} [options={}]
+ * @param {TokenInitOptions} [options={}]
  * @returns {Promise<string>}
  */
 export async function ensureBridgeAuthToken(options = {}) {
   const tokenPath = options.tokenPath ?? getBridgeAuthTokenPath();
+  return ensureStoredBridgeAuthToken(tokenPath, options);
+}
+
+/**
+ * @param {TokenInitOptions} [options={}]
+ * @returns {Promise<string>}
+ */
+export async function ensureBridgeExtensionAuthToken(options = {}) {
+  const tokenPath = options.tokenPath ?? getBridgeExtensionAuthTokenPath();
+  return ensureStoredBridgeAuthToken(tokenPath, options);
+}
+
+/**
+ * @param {string} tokenPath
+ * @param {TokenInitOptions} options
+ * @returns {Promise<string>}
+ */
+async function ensureStoredBridgeAuthToken(tokenPath, options) {
   const readFile = options.readFile ?? fs.promises.readFile.bind(fs.promises);
   const writeFile = options.writeFile ?? fs.promises.writeFile.bind(fs.promises);
   const mkdir = options.mkdir ?? fs.promises.mkdir.bind(fs.promises);
   const chmod = options.chmod ?? fs.promises.chmod.bind(fs.promises);
+  const link = options.link ?? fs.promises.link.bind(fs.promises);
+  const unlink = options.unlink ?? fs.promises.unlink.bind(fs.promises);
   const randomBytesFn = options.randomBytesFn ?? randomBytes;
-  const existing = await readBridgeAuthToken({ tokenPath, readFile });
+  const existing = await readStoredBridgeAuthToken(tokenPath, readFile);
   if (existing) {
     return existing;
   }
 
   const token = randomBytesFn(TOKEN_BYTES).toString('base64url');
   await mkdir(path.dirname(tokenPath), { recursive: true });
-  await writeFile(tokenPath, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
-  if (process.platform !== 'win32') {
-    await chmod(tokenPath, 0o600).catch(() => {});
+  const nonce = randomUUID();
+  const temporaryPath = `${tokenPath}.${nonce}.tmp`;
+  const ownerPath = `${temporaryPath}.owner`;
+  let lockPath = `${tokenPath}.init.lock`;
+  let locked = false;
+  /** @param {string} filePath */
+  const remove = async (filePath) => {
+    try {
+      await unlink(filePath);
+    } catch (error) {
+      if (!isMissingFileError(error)) throw error;
+    }
+  };
+  try {
+    // Neither the credential nor lock name is visible until its complete contents
+    // have been written and closed. Hard links publish without replacing a winner.
+    await writeFile(temporaryPath, `${token}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    await writeFile(ownerPath, `${process.pid}:${nonce}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    if (process.platform !== 'win32') await chmod(temporaryPath, 0o600).catch(() => {});
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      try {
+        await link(ownerPath, lockPath);
+        locked = true;
+        break;
+      } catch (error) {
+        if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST')
+          throw error;
+      }
+      let owner;
+      try {
+        owner = await readFile(lockPath, 'utf8');
+      } catch (error) {
+        if (isMissingFileError(error)) continue;
+        throw error;
+      }
+      const match = /^(\d+):([0-9a-f-]{36})\n$/u.exec(owner);
+      if (!match || !Number.isSafeInteger(Number(match[1])) || Number(match[1]) <= 0) {
+        throw new Error('Bridge auth initialization lock has invalid ownership metadata.');
+      }
+      try {
+        process.kill(Number(match[1]), 0);
+      } catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ESRCH') {
+          // Never unlink a dead owner's lock: two stale-lock cleaners could delete
+          // a new winner's lock. All contenders instead follow the same successor.
+          lockPath = `${tokenPath}.init-${match[2]}.lock`;
+          continue;
+        }
+        if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EPERM')
+          throw error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    if (!locked) throw new Error('Timed out waiting for bridge auth initialization.');
+    const winner = await readStoredBridgeAuthToken(tokenPath, readFile);
+    if (winner) return winner;
+    await remove(tokenPath);
+    try {
+      await link(temporaryPath, tokenPath);
+      return token;
+    } catch (error) {
+      if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST')
+        throw error;
+      const published = await readStoredBridgeAuthToken(tokenPath, readFile);
+      if (published) return published;
+      throw error;
+    }
+  } finally {
+    // Release the lock even if temporary-file cleanup fails.
+    try {
+      if (locked) await remove(lockPath);
+    } finally {
+      await Promise.all([remove(temporaryPath), remove(ownerPath)]);
+    }
   }
-  return token;
 }
 
 /**

package/packages/native-host/src/daemon-process.js

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 
-import { pingExistingDaemon } from './daemon.js';
+import { hasLiveListener, pingExistingDaemon } from './daemon.js';
 import {
   applyWindowsTcpTransportDefaults,
   createSocketBridgeTransport,
@@ -725,7 +725,6 @@ async function removeStaleSocket(transport, rmFn, pingDaemonFn) {
   if (await safePingDaemon(transport, pingDaemonFn)) {
     return false;
   }
-
   try {
     await fs.promises.access(transport.socketPath);
   } catch (error) {
@@ -735,6 +734,10 @@ async function removeStaleSocket(transport, rmFn, pingDaemonFn) {
     throw error;
   }
 
+  if (await hasLiveListener(transport)) {
+    return false;
+  }
+
   try {
     await rmFn(transport.socketPath, { force: true });
     return true;