@browserbridge/bbx 1.7.3 → 1.7.5

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,15 +181,23 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Tabs',
       description:
-        'List, create, or close 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'])
-          .describe('"list" (preferred), "create" (only when needed), or "close"'),
+          .enum(['list', 'create', 'close', 'activate'])
+          .describe('"list" (preferred), "create" (only when needed), "close", or "activate"'),
         url: z.string().optional().describe('URL for create action'),
         active: z.boolean().optional().describe('Focus the new tab (default: true)'),
-        tabId: z.number().int().positive().optional().describe('Tab ID (required for close)'),
-        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+        tabId: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('Tab ID (required for close/activate)'),
+        destinationId: z
+          .string()
+          .optional()
+          .describe('Target one destination; list without it aggregates configured destinations.'),
       },
     },
     handleTabsTool
@@ -194,7 +208,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser DOM',
       description:
-        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed — use query/find first.',
+        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed - use query/find first.',
       inputSchema: {
         action: z
           .enum([
@@ -270,7 +284,9 @@ export function createBridgeMcpServer() {
         state: z
           .enum(['attached', 'detached', 'visible', 'hidden'])
           .optional()
-          .describe('Expected element state (for wait action)'),
+          .describe(
+            'Expected element state (for wait action); hidden also matches complete absence'
+          ),
         timeoutMs: z
           .number()
           .int()
@@ -334,7 +350,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Page State',
       description:
-        'Read page-level data: state (URL/title), evaluate (JS), console, storage, text, network, or performance. For element-level reads, use browser_dom. evaluate and performance are debugger-backed — prefer lighter reads first.',
+        'Read page-level data: state (URL/title), evaluate (JS), console, storage, text, network, or performance. For element-level reads, use browser_dom. evaluate and performance are debugger-backed - prefer lighter reads first.',
       inputSchema: {
         action: z
           .enum([
@@ -364,15 +380,19 @@ 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
-          .string()
+          .enum(['all', 'debug', 'log', 'info', 'warn', 'error', 'exception', 'rejection'])
           .optional()
-          .describe('Minimum console level: log, warn, error (default: all)'),
+          .describe(
+            'Minimum console severity (default: all); exception/rejection select that exact stream'
+          ),
         clear: z.boolean().optional().describe('Clear buffer after reading (default: false)'),
         limit: z
           .number()
@@ -405,7 +425,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Navigation',
       description:
-        'Navigate to a URL, reload, go back/forward, scroll, or resize the viewport. resize is debugger-backed — use only for exact viewport overrides.',
+        'Navigate to a URL, reload, go back/forward, scroll, or resize the viewport. resize is debugger-backed - use only for exact viewport overrides.',
       inputSchema: {
         action: z
           .enum(['navigate', 'reload', 'go_back', 'go_forward', 'scroll', 'resize'])
@@ -423,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)'),
@@ -456,6 +476,7 @@ export function createBridgeMcpServer() {
             'click',
             'focus',
             'type',
+            'fill',
             'press_key',
             'cdp_press_key',
             'set_checked',
@@ -488,6 +509,11 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Click count (1=single, 2=double)'),
         text: z.string().max(100000).optional().describe('Text to type (for type action)'),
+        value: z.string().max(100000).optional().describe('Value to set (for fill action)'),
+        mode: z
+          .enum(['auto', 'setter', 'keystrokes'])
+          .optional()
+          .describe('Fill strategy (default: auto)'),
         clear: z.boolean().optional().describe('Clear field before typing (default: false)'),
         submit: z.boolean().optional().describe('Press Enter after typing (default: false)'),
         key: z
@@ -517,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()
@@ -565,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()
@@ -594,7 +613,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Capture',
       description:
-        'Capture screenshots or CDP snapshots. Debugger-backed and token-expensive — use only when structured reads (browser_dom, browser_styles_layout) are insufficient. Prefer element, then tight region; full_page only for document-level context.',
+        'Capture screenshots or CDP snapshots. Debugger-backed and token-expensive - use only when structured reads (browser_dom, browser_styles_layout) are insufficient. Prefer element, then tight region; full_page only for document-level context.',
       inputSchema: {
         action: z
           .enum([
@@ -645,7 +664,13 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Bridge Batch',
       description:
-        'Execute multiple bridge calls in parallel to reduce round-trips. Combine independent reads (e.g., styles + text + console) in one call. Preserves call order in the response.',
+        'Execute independent read-only bridge calls in parallel to reduce round-trips. Mutations and destructive reads are rejected; run them sequentially with specialized tools or browser_call. Preserves call order in the response.',
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
       inputSchema: {
         calls: z
           .array(
@@ -685,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/daemon.js

@@ -602,7 +602,9 @@ export class BridgeDaemon {
 
     if (message?.type === 'agent.request') {
       const isExtensionSetupRequest =
-        socket.__role === 'extension' && message.request?.method === 'setup.install';
+        socket.__role === 'extension' &&
+        (message.request?.method === 'setup.get_status' ||
+          message.request?.method === 'setup.install');
       if (socket.__role !== 'agent' && !isExtensionSetupRequest) {
         return this.rejectMessageForRole(socket, message);
       }

package/packages/protocol/src/capabilities.js

@@ -64,7 +64,7 @@ export const METHOD_CAPABILITIES = Object.freeze({
   'page.get_storage': CAPABILITIES.PAGE_READ,
   'page.get_text': CAPABILITIES.PAGE_READ,
   'page.get_network': CAPABILITIES.NETWORK_READ,
-  // Interception mutates traffic (block/forge responses) — distinct from
+  // Interception mutates traffic (block/forge responses) - distinct from
   // passive network reads so hosts can gate it independently.
   'network.intercept.add': CAPABILITIES.NETWORK_INTERCEPT,
   'network.intercept.remove': CAPABILITIES.NETWORK_INTERCEPT,

package/packages/protocol/src/defaults.js

@@ -20,6 +20,8 @@ export const DEFAULT_CONSOLE_LIMIT = 50;
 export const DEFAULT_VIEWPORT_WIDTH = 1280;
 export const DEFAULT_VIEWPORT_HEIGHT = 720;
 export const DEFAULT_DEVICE_SCALE_FACTOR = 0;
+/** @type {'continue'} */
+export const DEFAULT_NETWORK_INTERCEPT_ACTION = 'continue';
 
 /** Maximum size of a Chrome native messaging message in bytes. */
 export const MAX_NATIVE_MESSAGE_BYTES = 1_048_576;