@browserbridge/bbx 1.7.4 → 1.7.6

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

@@ -1,7 +1,7 @@
 // @ts-check
 
 import os from 'node:os';
-import { DEFAULT_CONSOLE_LIMIT, createRuntimeContext } from '../../protocol/src/index.js';
+import { DEFAULT_LOG_TAIL_LIMIT, createRuntimeContext } from '../../protocol/src/index.js';
 import { collectSetupStatus } from '../../agent-client/src/setup-status.js';
 import {
   callBridgeTool,
@@ -82,15 +82,17 @@ export async function handleStatusTool(args = {}) {
       );
       const result = await callRemoteHealth(requestedDestinationId);
       return createToolResult(
-        result.reachable
-          ? `Browser Bridge destination "${requestedDestinationId}" is reachable.`
-          : `Browser Bridge destination "${requestedDestinationId}" is not reachable.`,
+        result.routeReady
+          ? `Browser Bridge destination "${requestedDestinationId}" is ready.`
+          : result.reachable
+            ? `Browser Bridge destination "${requestedDestinationId}" is reachable, but its browser route is not ready.`
+            : `Browser Bridge destination "${requestedDestinationId}" is not reachable.`,
         {
-          ok: result.reachable === true,
+          ok: result.routeReady === true,
           destination: destination ?? { id: requestedDestinationId, local: false },
           ...result,
         },
-        result.reachable !== true
+        result.routeReady !== true
       );
     }
 
@@ -131,17 +133,36 @@ export async function handleStatusTool(args = {}) {
  */
 async function callRemoteHealth(destinationId) {
   const result = await callBridgeTool('health.ping', {}, { destinationId });
+  const evidence =
+    result.structuredContent.evidence && typeof result.structuredContent.evidence === 'object'
+      ? /** @type {Record<string, unknown>} */ (result.structuredContent.evidence)
+      : {};
+  const access =
+    evidence.access && typeof evidence.access === 'object'
+      ? /** @type {Record<string, unknown>} */ (evidence.access)
+      : {};
+  const reachable = result.structuredContent.ok === true && evidence.daemon === 'ok';
   return {
-    reachable: result.structuredContent.ok === true,
+    reachable,
+    daemonReachable: reachable,
+    extensionConnected: evidence.extensionConnected === true,
+    accessEnabled: access.enabled === true,
+    routeReady: reachable && access.routeReady === true,
+    routeTabId: typeof access.routeTabId === 'number' ? access.routeTabId : null,
+    routeReason: typeof access.reason === 'string' ? access.reason : null,
     health: result.structuredContent,
   };
 }
 
 /**
+ * @param {{ destinationId?: string }} [args]
  * @returns {Promise<ToolResult>}
  */
-export async function handleSkillTool() {
+export async function handleSkillTool(args = {}) {
   try {
+    if (typeof args.destinationId === 'string') {
+      return callBridgeTool('skill.get_runtime_context', {}, { destinationId: args.destinationId });
+    }
     const ctx = createRuntimeContext();
     return createToolResult('Runtime context retrieved.', {
       ok: true,
@@ -176,13 +197,13 @@ export async function handleSetupTool(args) {
 export async function handleLogTool(args) {
   const normalizedArgs = applyLimitBudgetPreset(args, {
     quick: 10,
-    normal: DEFAULT_CONSOLE_LIMIT,
+    normal: DEFAULT_LOG_TAIL_LIMIT,
     deep: 100,
   });
   return callBridgeTool(
     'log.tail',
     {
-      limit: normalizedArgs.limit ?? DEFAULT_CONSOLE_LIMIT,
+      limit: normalizedArgs.limit ?? DEFAULT_LOG_TAIL_LIMIT,
     },
     {
       tokenBudget: getToolTokenBudget(normalizedArgs),

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

@@ -0,0 +1,413 @@
+// @ts-check
+
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+
+import { getBridgeDir } from '../../native-host/src/config.js';
+
+const MCP_CONTROL_PROTOCOL_VERSION = 1;
+const MCP_CONTROL_TIMEOUT_MS = 1_000;
+const MCP_REGISTRY_DIRNAME = 'mcp-processes';
+
+/**
+ * @typedef {{
+ *   protocolVersion: number,
+ *   instanceId: string,
+ *   pid: number,
+ *   port: number,
+ *   token: string,
+ * }} McpProcessRegistration
+ */
+
+/**
+ * @typedef {{
+ *   registryDir?: string,
+ *   onRestart?: () => void,
+ * }} StartMcpProcessControlOptions
+ */
+
+/**
+ * @typedef {{
+ *   registryDir?: string,
+ *   timeoutMs?: number,
+ * }} RestartMcpProcessesOptions
+ */
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string}
+ */
+export function getMcpProcessRegistryDir(env = process.env) {
+  return path.join(getBridgeDir(env), MCP_REGISTRY_DIRNAME);
+}
+
+/**
+ * Register a private localhost control endpoint for this MCP process. The
+ * endpoint lets `bbx restart` retire the loaded MCP code without relying on a
+ * stale PID that may have been reused by an unrelated process.
+ *
+ * @param {StartMcpProcessControlOptions} [options={}]
+ * @returns {Promise<{ registrationPath: string, dispose: () => Promise<void> }>}
+ */
+export async function startMcpProcessControl(options = {}) {
+  const { registryDir = getMcpProcessRegistryDir(), onRestart = () => process.exit(0) } = options;
+  const instanceId = randomUUID();
+  const token = randomUUID();
+  const registrationPath = path.join(registryDir, `${instanceId}.json`);
+  let restartRequested = false;
+  let disposed = false;
+
+  const server = net.createServer((socket) => {
+    socket.setEncoding('utf8');
+    socket.setTimeout(MCP_CONTROL_TIMEOUT_MS, () => socket.destroy());
+    socket.on('error', () => socket.destroy());
+    let input = '';
+    let handled = false;
+
+    socket.on('data', (chunk) => {
+      if (handled) {
+        return;
+      }
+      input += chunk;
+      if (input.length > 4_096) {
+        socket.destroy();
+        return;
+      }
+
+      const newlineIndex = input.indexOf('\n');
+      if (newlineIndex === -1) {
+        return;
+      }
+      handled = true;
+
+      const request = parseControlRequest(input.slice(0, newlineIndex));
+      if (!request || request.token !== token || request.action !== 'restart') {
+        socket.end(`${JSON.stringify({ ok: false })}\n`);
+        return;
+      }
+      if (restartRequested) {
+        socket.end(`${JSON.stringify({ ok: true })}\n`);
+        return;
+      }
+
+      restartRequested = true;
+      removeRegistrationSync(registrationPath);
+      server.close();
+      socket.end(`${JSON.stringify({ ok: true })}\n`, onRestart);
+    });
+  });
+
+  try {
+    await listenOnLoopback(server);
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+      throw new Error('MCP process control endpoint did not expose a TCP port.');
+    }
+
+    const registration = {
+      protocolVersion: MCP_CONTROL_PROTOCOL_VERSION,
+      instanceId,
+      pid: process.pid,
+      port: address.port,
+      token,
+    };
+    await writeRegistration(registrationPath, registration);
+  } catch (error) {
+    server.close();
+    removeRegistrationSync(registrationPath);
+    throw error;
+  }
+
+  const cleanupOnExit = () => removeRegistrationSync(registrationPath);
+  const cleanupOnStdinEnd = () => {
+    void dispose();
+  };
+  process.once('exit', cleanupOnExit);
+  process.stdin.once('end', cleanupOnStdinEnd);
+
+  async function dispose() {
+    if (disposed) {
+      return;
+    }
+    disposed = true;
+    process.removeListener('exit', cleanupOnExit);
+    process.stdin.removeListener('end', cleanupOnStdinEnd);
+    removeRegistrationSync(registrationPath);
+    await closeServer(server);
+  }
+
+  return { registrationPath, dispose };
+}
+
+/**
+ * Lifecycle coordination must never prevent the stdio MCP server from serving.
+ * Sandboxed agents and read-only installations can legitimately reject the
+ * loopback listener or registry write.
+ *
+ * @param {StartMcpProcessControlOptions} [options={}]
+ * @returns {Promise<{ registrationPath: string, dispose: () => Promise<void> } | null>}
+ */
+export async function tryStartMcpProcessControl(options = {}) {
+  try {
+    return await startMcpProcessControl(options);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ask every registered MCP process to exit so its owning agent can launch the
+ * current installed version. Registrations are removed only when the process is
+ * gone; transient control failures remain visible for a later retry.
+ *
+ * @param {RestartMcpProcessesOptions} [options={}]
+ * @returns {Promise<{ registered: number, restartRequested: number, restartFailed: number, staleRegistrationsRemoved: number }>}
+ */
+export async function restartRegisteredMcpProcesses(options = {}) {
+  const { registryDir = getMcpProcessRegistryDir(), timeoutMs = MCP_CONTROL_TIMEOUT_MS } = options;
+  let entries;
+  try {
+    entries = (await fs.promises.readdir(registryDir, { withFileTypes: true })).filter(
+      (entry) => entry.isFile() && entry.name.endsWith('.json')
+    );
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return {
+        registered: 0,
+        restartRequested: 0,
+        restartFailed: 0,
+        staleRegistrationsRemoved: 0,
+      };
+    }
+    throw error;
+  }
+
+  let restartRequested = 0;
+  let restartFailed = 0;
+  let staleRegistrationsRemoved = 0;
+  await Promise.all(
+    entries.map(async (entry) => {
+      const registrationPath = path.join(registryDir, entry.name);
+      const registration = await readRegistration(registrationPath);
+      if (!registration) {
+        await fs.promises.rm(registrationPath, { force: true });
+        staleRegistrationsRemoved += 1;
+        return;
+      }
+
+      const accepted = await requestProcessRestart(registration, timeoutMs).catch(() => false);
+      if (!accepted) {
+        if (isProcessRunning(registration.pid)) {
+          restartFailed += 1;
+          return;
+        }
+        await fs.promises.rm(registrationPath, { force: true });
+        staleRegistrationsRemoved += 1;
+        return;
+      }
+
+      restartRequested += 1;
+      await fs.promises.rm(registrationPath, { force: true });
+    })
+  );
+
+  return {
+    registered: entries.length,
+    restartRequested,
+    restartFailed,
+    staleRegistrationsRemoved,
+  };
+}
+
+/**
+ * @param {net.Server} server
+ * @returns {Promise<void>}
+ */
+function listenOnLoopback(server) {
+  return new Promise((resolve, reject) => {
+    /** @param {Error} error */
+    const onError = (error) => {
+      server.removeListener('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.removeListener('error', onError);
+      resolve();
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(0, '127.0.0.1');
+  });
+}
+
+/**
+ * @param {net.Server} server
+ * @returns {Promise<void>}
+ */
+function closeServer(server) {
+  if (!server.listening) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+/**
+ * @param {string} registrationPath
+ * @param {McpProcessRegistration} registration
+ * @returns {Promise<void>}
+ */
+async function writeRegistration(registrationPath, registration) {
+  await fs.promises.mkdir(path.dirname(registrationPath), { recursive: true });
+  const temporaryPath = `${registrationPath}.${process.pid}.tmp`;
+  await fs.promises.writeFile(temporaryPath, `${JSON.stringify(registration)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600,
+  });
+  await fs.promises.rename(temporaryPath, registrationPath);
+}
+
+/**
+ * @param {string} registrationPath
+ * @returns {Promise<McpProcessRegistration | null>}
+ */
+async function readRegistration(registrationPath) {
+  try {
+    const parsed = JSON.parse(await fs.promises.readFile(registrationPath, 'utf8'));
+    if (
+      !parsed ||
+      typeof parsed !== 'object' ||
+      parsed.protocolVersion !== MCP_CONTROL_PROTOCOL_VERSION ||
+      typeof parsed.instanceId !== 'string' ||
+      !Number.isInteger(parsed.pid) ||
+      parsed.pid <= 0 ||
+      !Number.isInteger(parsed.port) ||
+      parsed.port <= 0 ||
+      parsed.port > 65_535 ||
+      typeof parsed.token !== 'string' ||
+      parsed.token.length === 0
+    ) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {McpProcessRegistration} registration
+ * @param {number} timeoutMs
+ * @returns {Promise<boolean>}
+ */
+function requestProcessRestart(registration, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host: '127.0.0.1', port: registration.port });
+    let response = '';
+    let settled = false;
+
+    /**
+     * @param {Error | null} error
+     * @param {boolean} [accepted]
+     */
+    const finish = (error, accepted = false) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.destroy();
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(accepted);
+    };
+
+    socket.setEncoding('utf8');
+    socket.setTimeout(timeoutMs, () => finish(new Error('MCP process control request timed out.')));
+    socket.once('error', (error) => finish(error));
+    socket.once('connect', () => {
+      socket.write(`${JSON.stringify({ action: 'restart', token: registration.token })}\n`);
+    });
+    socket.on('data', (chunk) => {
+      response += chunk;
+      const newlineIndex = response.indexOf('\n');
+      if (newlineIndex === -1) {
+        return;
+      }
+      try {
+        const result = JSON.parse(response.slice(0, newlineIndex));
+        finish(null, Boolean(result && typeof result === 'object' && result.ok === true));
+      } catch (error) {
+        finish(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+    socket.once('close', () => finish(new Error('MCP process control connection closed.')));
+  });
+}
+
+/**
+ * @param {string} input
+ * @returns {{ action: string, token: string } | null}
+ */
+function parseControlRequest(input) {
+  try {
+    const parsed = JSON.parse(input);
+    if (
+      !parsed ||
+      typeof parsed !== 'object' ||
+      typeof parsed.action !== 'string' ||
+      typeof parsed.token !== 'string'
+    ) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} registrationPath
+ */
+function removeRegistrationSync(registrationPath) {
+  try {
+    fs.rmSync(registrationPath, { force: true });
+  } catch {
+    // Cleanup is best-effort during process shutdown.
+  }
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isMissingFileError(error) {
+  return Boolean(
+    error && typeof error === 'object' && 'code' in error && String(error.code) === 'ENOENT'
+  );
+}
+
+/**
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return Boolean(
+      error && typeof error === 'object' && 'code' in error && String(error.code) === 'EPERM'
+    );
+  }
+}

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

@@ -32,11 +32,14 @@ import {
 import {
   BUDGET_PRESETS,
   DEFAULT_CONSOLE_LIMIT,
+  DEFAULT_EVAL_TIMEOUT_MS,
+  DEFAULT_LOG_TAIL_LIMIT,
   DEFAULT_MAX_DEPTH,
   DEFAULT_MAX_HTML_LENGTH,
   DEFAULT_MAX_NODES,
   DEFAULT_PAGE_TEXT_BUDGET,
   DEFAULT_TEXT_BUDGET,
+  DEFAULT_NAV_TIMEOUT_MS,
   DEFAULT_WAIT_TIMEOUT_MS,
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
@@ -113,9 +116,12 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Bridge Status',
       description:
-        'Check bridge readiness: daemon connectivity, extension state, and window access. Call first to confirm the bridge is usable. If access is not enabled, ask the user to click Enable in the extension popup or side panel, then retry.',
+        'Check bridge readiness: daemon connectivity, extension state, and window access. Omit destinationId to inspect local and configured remote destinations. If access is not enabled, ask the user to click Enable in the extension popup or side panel, then retry.',
       inputSchema: {
-        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+        destinationId: z
+          .string()
+          .optional()
+          .describe('Inspect one destination instead of aggregating all configured destinations.'),
       },
     },
     handleStatusTool
@@ -147,7 +153,7 @@ export function createBridgeMcpServer() {
           .int()
           .positive()
           .optional()
-          .describe(`Maximum log entries to return (default: ${DEFAULT_CONSOLE_LIMIT})`),
+          .describe(`Maximum log entries to return (default: ${DEFAULT_LOG_TAIL_LIMIT})`),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -175,7 +181,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Tabs',
       description:
-        'List, create, close, or activate browser tabs. Prefer "list" to work in existing tabs; only use "create" when the user explicitly requests a new page.',
+        'List, create, close, or activate browser tabs. List without destinationId aggregates configured destinations; other actions default to local. Only create a page when the user explicitly requests it.',
       inputSchema: {
         action: z
           .enum(['list', 'create', 'close', 'activate'])
@@ -188,7 +194,10 @@ export function createBridgeMcpServer() {
           .positive()
           .optional()
           .describe('Tab ID (required for close/activate)'),
-        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+        destinationId: z
+          .string()
+          .optional()
+          .describe('Target one destination; list without it aggregates configured destinations.'),
       },
     },
     handleTabsTool
@@ -371,11 +380,13 @@ export function createBridgeMcpServer() {
           .int()
           .positive()
           .optional()
-          .describe(`Timeout for evaluate/wait operations (default: ${DEFAULT_WAIT_TIMEOUT_MS})`),
+          .describe(
+            `Timeout (default: ${DEFAULT_EVAL_TIMEOUT_MS} for evaluate, ${DEFAULT_NAV_TIMEOUT_MS} for wait_for_load)`
+          ),
         returnByValue: z
-          .boolean()
+          .literal(true)
           .optional()
-          .describe('Return actual value vs JSON (default: true)'),
+          .describe('Return serializable values (only true is supported; default: true)'),
         level: z
           .enum(['all', 'debug', 'log', 'info', 'warn', 'error', 'exception', 'rejection'])
           .optional()
@@ -432,7 +443,7 @@ export function createBridgeMcpServer() {
           .int()
           .positive()
           .optional()
-          .describe('Timeout for navigation (default: 30000)'),
+          .describe(`Timeout for navigation (default: ${DEFAULT_NAV_TIMEOUT_MS})`),
         top: z.number().optional().describe('Scroll target Y position (pixels)'),
         left: z.number().optional().describe('Scroll target X position (pixels)'),
         behavior: z.enum(['auto', 'smooth']).optional().describe('Scroll behavior (default: auto)'),
@@ -532,7 +543,7 @@ export function createBridgeMcpServer() {
           .int()
           .nonnegative()
           .optional()
-          .describe('Hover duration in ms (default: 100)'),
+          .describe('Hover duration in ms (default: 0)'),
         sourceElementRef: z.string().optional().describe('Drag source element (for drag action)'),
         sourceSelector: z
           .string()
@@ -580,19 +591,12 @@ export function createBridgeMcpServer() {
           .describe('CSS property: value pairs (for apply_styles)'),
         important: z.boolean().optional().describe('Add !important flag (default: false)'),
         operation: z
-          .enum([
-            'setAttribute',
-            'removeAttribute',
-            'addClass',
-            'removeClass',
-            'setTextContent',
-            'setProperty',
-          ])
+          .enum(['setAttribute', 'removeAttribute', 'addClass', 'removeClass', 'setTextContent'])
           .optional()
           .describe('DOM mutation type'),
         value: z.unknown().optional().describe('Value for the DOM operation'),
         name: z.string().optional().describe('Attribute/class/property name (for apply_dom)'),
-        patchId: z.string().optional().describe('Patch ID to rollback (omit for most recent)'),
+        patchId: z.string().optional().describe('Patch ID (required for rollback)'),
         verify: z
           .boolean()
           .optional()
@@ -706,6 +710,10 @@ export function createBridgeMcpServer() {
           .describe('Method parameters as object'),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+        budgetPreset: z
+          .enum(['quick', 'normal', 'deep'])
+          .optional()
+          .describe(BUDGET_PRESET_DESCRIPTION),
       },
     },
     handleRawCallTool

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

@@ -60,7 +60,7 @@ export async function readBridgeAuthTokenOverride(options = {}) {
 }
 
 /**
- * @param {{ tokenPath?: string, readFile?: typeof fs.promises.readFile }} [options={}]
+ * @param {{ env?: NodeJS.ProcessEnv, tokenPath?: string, readFile?: typeof fs.promises.readFile }} [options={}]
  * @returns {Promise<string | null>}
  */
 export async function readBridgeAuthToken(options = {}) {

package/packages/native-host/src/config.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 
 export const APP_NAME = 'com.browserbridge.browser_bridge';
 export const BRIDGE_HOME_ENV = 'BROWSER_BRIDGE_HOME';
@@ -62,15 +63,19 @@ export function getBridgeDir(env = process.env) {
  * connect to. On Windows we use a Named Pipe by default because Node's AF_UNIX
  * support fails with EACCES on listen() under recent Node + Windows 11
  * combinations, while Named Pipes are the historical and reliable Windows IPC
- * mechanism. An explicit bridge-home override keeps the legacy socket path so
- * callers can opt into custom test or compatibility setups.
+ * mechanism. Custom bridge homes use a stable suffix so isolated daemon and
+ * test setups do not contend for the default pipe.
  *
  * @param {NodeJS.ProcessEnv} [env=process.env]
  * @returns {string}
  */
 export function getSocketPath(env = process.env) {
-  if (os.platform() === 'win32' && !env[BRIDGE_HOME_ENV]) {
-    return `\\\\.\\pipe\\${APP_NAME}`;
+  if (os.platform() === 'win32') {
+    const bridgeHome = env[BRIDGE_HOME_ENV];
+    const suffix = bridgeHome
+      ? `-${createHash('sha256').update(bridgeHome.toLowerCase()).digest('hex').slice(0, 16)}`
+      : '';
+    return `\\\\.\\pipe\\${APP_NAME}${suffix}`;
   }
   return path.join(getBridgeDir(env), 'bridge.sock');
 }

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

@@ -407,10 +407,17 @@ async function restartBridgeDaemonAfterStop(stopResult, options = {}) {
     throw new Error('Timed out waiting for Browser Bridge daemon to start.');
   }
 
+  let pid = await readPidFn(pidPath);
+  if (pid === null) {
+    // The daemon starts listening immediately before it persists its PID.
+    await sleepFn(pollIntervalMs);
+    pid = await readPidFn(pidPath);
+  }
+
   return {
     ...stopResult,
     pidPath,
-    pid: await readPidFn(pidPath),
+    pid,
   };
 }