@browserbridge/bbx 1.7.5 → 1.7.7

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

@@ -433,8 +433,7 @@ export async function getDoctorReport(options = {}) {
       if (!response.ok) {
         throw new Error(response.error.message);
       }
-      const result =
-        /** @type {{ daemon?: string, extensionConnected?: boolean, access?: {
+      const result = /** @type {{ daemon?: string, extensionConnected?: boolean, access?: {
         enabled?: boolean,
         windowId?: number | null,
         routeTabId?: number | null,

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

@@ -1,10 +1,5 @@
 // @ts-check
 
-import * as z from 'zod/v4';
-
-/** @typedef {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} McpServer */
-/** @typedef {import('@modelcontextprotocol/sdk/types.js').GetPromptResult} GetPromptResult */
-
 export const MCP_SERVER_INSTRUCTIONS = [
   "Browser Bridge MCP inspects and interacts with the user's real Chrome tab through typed MCP tools.",
   'In permission-ask hosts, use browser_call as the default Browser Bridge MCP tool so the user can approve one BBX tool instead of separate browser_status, browser_page, browser_dom, browser_input, and other tools.',
@@ -15,231 +10,8 @@ export const MCP_SERVER_INSTRUCTIONS = [
   'Escalate to screenshot.capture_element, screenshot.capture_region, dom.get_accessibility_tree, page.evaluate, viewport.resize, or CDP only when structured reads cannot answer the question.',
   'Use patch.apply_styles or patch.apply_dom for temporary experiments, and rollback patches before finishing unless the user asks to keep them.',
   'Only use the specialized Browser Bridge MCP tools directly when the host has already allowed them or the user explicitly wants typed tool calls.',
+  '',
+  'Page investigation: read page state, scoped DOM, and relevant page text first, batching independent reads. Find targets by text or role when selectors are unknown. Add styles, console, or network reads only when they directly answer the objective, and use screenshots or evaluation only when structured evidence is insufficient.',
+  'Layout debugging: locate the target, read only relevant computed properties and its box model, and inspect matched rules only when the cascade is unclear. Prototype the smallest fix with a reversible style patch, verify the result, check for new console errors, then rollback before editing source unless the user asks to keep the patch.',
+  'Flow verification: read initial page state, locate controls semantically, reuse elementRef values, interact through input tools, and wait for navigation or UI state changes. Verify the final DOM or page text plus console and network state when relevant. Do not create a new tab unless requested or required by the flow.',
 ].join('\n');
-
-export const MCP_GUIDANCE_PROMPT_NAMES = Object.freeze([
-  'browser_bridge_guide',
-  'browser_bridge_investigate',
-  'browser_bridge_debug_layout',
-  'browser_bridge_verify_flow',
-]);
-
-/**
- * Register Browser Bridge MCP prompt templates. These are the MCP-mode equivalent
- * of a lightweight skill: discoverable by clients without requiring filesystem
- * skill installation or shell access.
- *
- * @param {McpServer} server
- * @returns {void}
- */
-export function registerBridgeMcpGuidance(server) {
-  server.registerPrompt(
-    'browser_bridge_guide',
-    {
-      title: 'Use Browser Bridge MCP',
-      description:
-        'General Browser Bridge MCP workflow guidance. Prefer this over CLI skill setup.',
-    },
-    createGuidePrompt
-  );
-
-  server.registerPrompt(
-    'browser_bridge_investigate',
-    {
-      title: 'Investigate Current Page',
-      description:
-        'Inspect the current page with structured reads before screenshots or evaluation.',
-      argsSchema: {
-        objective: z.string().optional().describe('What to find, verify, or explain'),
-        selector: z
-          .string()
-          .optional()
-          .describe('Optional CSS selector to scope the first DOM read'),
-        scope: z.enum(['quick', 'normal', 'deep']).optional().describe('Investigation depth'),
-      },
-    },
-    createInvestigatePrompt
-  );
-
-  server.registerPrompt(
-    'browser_bridge_debug_layout',
-    {
-      title: 'Debug Layout Or Styling',
-      description: 'Diagnose a visual, spacing, sizing, visibility, or CSS issue in the live tab.',
-      argsSchema: {
-        target: z.string().optional().describe('Element, component, text, or selector to inspect'),
-        symptom: z.string().optional().describe('Observed layout or styling problem'),
-      },
-    },
-    createDebugLayoutPrompt
-  );
-
-  server.registerPrompt(
-    'browser_bridge_verify_flow',
-    {
-      title: 'Verify User Flow',
-      description:
-        'Drive a user flow through MCP input tools and verify page, console, and network state.',
-      argsSchema: {
-        flow: z.string().optional().describe('User flow to exercise'),
-        successCriteria: z.string().optional().describe('Expected successful outcome'),
-      },
-    },
-    createVerifyFlowPrompt
-  );
-}
-
-/**
- * @returns {GetPromptResult}
- */
-function createGuidePrompt() {
-  return createUserPrompt(
-    'Browser Bridge MCP workflow guide.',
-    [
-      'Use Browser Bridge MCP for this browser task.',
-      '',
-      'Rules:',
-      '1. Prefer MCP over `bbx`; do not shell out unless setup, doctor, logs, or raw CLI debugging is explicitly needed.',
-      '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 `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.',
-      '9. Only use specialized Browser Bridge MCP tools directly when the host has already allowed them or the user explicitly wants typed tool calls.',
-      '',
-      'Return concise findings with evidence. Edit source code only after the live page behavior is understood.',
-    ].join('\n')
-  );
-}
-
-/**
- * @param {{ objective?: string, selector?: string, scope?: 'quick' | 'normal' | 'deep' }} args
- * @returns {GetPromptResult}
- */
-function createInvestigatePrompt(args) {
-  const objective = normalizeTextArg(
-    args.objective,
-    'inspect the current page and report findings'
-  );
-  const selector = normalizeTextArg(
-    args.selector,
-    'none; start with main, body, or semantic search'
-  );
-  const scope = normalizeTextArg(args.scope, 'normal');
-
-  return createUserPrompt(
-    'Browser Bridge MCP page investigation workflow.',
-    [
-      'Investigate the current page with Browser Bridge MCP.',
-      '',
-      `Objective: ${objective}`,
-      `Scope: ${scope}`,
-      `Initial selector: ${selector}`,
-      '',
-      'Workflow:',
-      '1. Call `browser_status` to confirm daemon, extension, and access readiness.',
-      '2. If access is disabled, call `browser_access` once, ask the user to click Enable, then retry once.',
-      '3. Use `browser_batch` for independent structured reads, usually `page.get_state`, a scoped `dom.query`, and `page.get_text` when page copy matters.',
-      '4. Use `browser_dom` `find_text` or `find_role` when the target is known by label but not selector.',
-      '5. Add `browser_styles_layout`, `browser_page` console, or `browser_page` network only when they directly answer the objective.',
-      '6. Escalate to screenshots, accessibility tree, or evaluate only when structured reads are insufficient.',
-      '',
-      'Return concise findings, relevant evidence, and the next source-code action if a fix is needed.',
-    ].join('\n')
-  );
-}
-
-/**
- * @param {{ target?: string, symptom?: string }} args
- * @returns {GetPromptResult}
- */
-function createDebugLayoutPrompt(args) {
-  const target = normalizeTextArg(args.target, 'the affected element or component');
-  const symptom = normalizeTextArg(args.symptom, 'the observed layout or styling problem');
-
-  return createUserPrompt(
-    'Browser Bridge MCP layout debugging workflow.',
-    [
-      'Debug a layout or styling issue in the live tab with Browser Bridge MCP.',
-      '',
-      `Target: ${target}`,
-      `Symptom: ${symptom}`,
-      '',
-      'Workflow:',
-      '1. Call `browser_status` first and resolve access if needed.',
-      '2. Locate the target with `browser_dom` `query`, `find_text`, or `find_role` using a quick budget.',
-      '3. Read only relevant computed styles with `browser_styles_layout` action `computed` and specific `properties`.',
-      '4. Read dimensions with `browser_styles_layout` action `box_model`; use matched rules only when the cascade is unclear.',
-      '5. Prototype the smallest visual fix with `browser_patch` action `apply_styles` and `verify: true` when useful.',
-      '6. Check `browser_page` console for new errors after interaction or patching.',
-      '7. Roll back temporary patches unless the user explicitly wants them kept, then edit source with the confirmed fix.',
-      '',
-      'Avoid screenshots until DOM, computed styles, and box model evidence are insufficient.',
-    ].join('\n')
-  );
-}
-
-/**
- * @param {{ flow?: string, successCriteria?: string }} args
- * @returns {GetPromptResult}
- */
-function createVerifyFlowPrompt(args) {
-  const flow = normalizeTextArg(args.flow, 'the requested user flow');
-  const successCriteria = normalizeTextArg(
-    args.successCriteria,
-    'visible success state, no console errors, and expected network behavior'
-  );
-
-  return createUserPrompt(
-    'Browser Bridge MCP user-flow verification workflow.',
-    [
-      'Verify a user flow in the current real browser tab with Browser Bridge MCP.',
-      '',
-      `Flow: ${flow}`,
-      `Success criteria: ${successCriteria}`,
-      '',
-      'Workflow:',
-      '1. Call `browser_status` and resolve access if needed.',
-      '2. Read `browser_page` state so you know the current URL and title before interacting.',
-      '3. Locate controls semantically with `browser_dom` `find_role` or `find_text`; reuse returned `elementRef` values.',
-      '4. Interact with `browser_input` actions such as `click`, `type`, `set_checked`, `select_option`, and `press_key`.',
-      '5. After navigation or UI changes, wait with `browser_dom` action `wait` or `browser_page` action `wait_for_load`.',
-      '6. Verify final page text/DOM plus `browser_page` console and network if the flow depends on API calls.',
-      '7. Do not create new tabs unless the user requested a fresh page or the flow requires one.',
-      '',
-      'Report the verified result, evidence, and any blocking failures.',
-    ].join('\n')
-  );
-}
-
-/**
- * @param {string} description
- * @param {string} text
- * @returns {GetPromptResult}
- */
-function createUserPrompt(description, text) {
-  return {
-    description,
-    messages: [
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text,
-        },
-      },
-    ],
-  };
-}
-
-/**
- * @param {string | undefined} value
- * @param {string} fallback
- * @returns {string}
- */
-function normalizeTextArg(value, fallback) {
-  const text = typeof value === 'string' ? value.trim() : '';
-  return text || fallback;
-}

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

@@ -44,7 +44,7 @@ import {
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
-import { MCP_SERVER_INSTRUCTIONS, registerBridgeMcpGuidance } from './guidance.js';
+import { MCP_SERVER_INSTRUCTIONS } from './guidance.js';
 
 export const BUDGET_PRESET_DESCRIPTION = `Budget preset: "quick", "normal", or "deep" (defaults: query ${BUDGET_PRESETS.normal.maxNodes} nodes / depth ${BUDGET_PRESETS.normal.maxDepth} / text ${BUDGET_PRESETS.normal.textBudget}). Numeric fields override the preset when both are provided.`;
 export const TAB_ID_DESCRIPTION =
@@ -109,8 +109,6 @@ export function createBridgeMcpServer() {
     }
   );
 
-  registerBridgeMcpGuidance(server);
-
   server.registerTool(
     'browser_status',
     {

package/packages/native-host/bin/bridge-daemon.js

@@ -44,7 +44,8 @@ try {
   await writeDaemonPidFile(process.pid);
 } catch (error) {
   // A stale root-owned pid file (e.g. after a sudo install) must not take down
-  // a daemon that is already listening; `bbx` falls back to lsof for the pid.
+  // a daemon that is already listening; `bbx` falls back to endpoint-owner
+  // discovery (lsof/ss on the socket, verified TCP listener lookup) for the pid.
   process.stderr.write(
     `Could not write daemon pid file: ${error instanceof Error ? error.message : String(error)}\n`
   );

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

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -34,6 +34,27 @@ export function normalizeBridgeAuthToken(value) {
   return TOKEN_PATTERN.test(token) || UUID_TOKEN_PATTERN.test(token) ? token : null;
 }
 
+/**
+ * Compare a candidate auth token against the expected token in constant time.
+ * Both sides are hashed before comparison so neither token length nor a
+ * matching prefix is observable through timing, which matters when the daemon
+ * listens on TCP (proxy mode exposes it beyond localhost).
+ *
+ * @param {unknown} candidate
+ * @param {string | null | undefined} expected
+ * @returns {boolean}
+ */
+export function bridgeAuthTokensEqual(candidate, expected) {
+  const normalizedCandidate = normalizeBridgeAuthToken(candidate);
+  if (!normalizedCandidate || typeof expected !== 'string' || !expected) {
+    return false;
+  }
+  return timingSafeEqual(
+    createHash('sha256').update(normalizedCandidate).digest(),
+    createHash('sha256').update(expected).digest()
+  );
+}
+
 /**
  * @param {{ env?: NodeJS.ProcessEnv, readFile?: typeof fs.promises.readFile }} [options={}]
  * @returns {Promise<string | null>}
@@ -60,7 +81,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');
 }
@@ -115,30 +120,65 @@ function normalizePort(value) {
 }
 
 /**
+ * @param {string} configPath
+ * @param {string} reason
+ * @returns {void}
+ */
+function warnProxyConfigIgnored(configPath, reason) {
+  console.error(`browser-bridge: ignoring proxy config at ${configPath}: ${reason}`);
+}
+
+/**
+ * Read the opt-in TCP proxy config. A missing file and `enabled: false` are
+ * the normal quiet cases; anything else that prevents using the config gets a
+ * stderr warning so a corrupt file does not silently fall back to the socket
+ * transport. An invalid `bindHost` rejects the whole config rather than
+ * defaulting to `0.0.0.0`, so a typo in a value meant to restrict binding
+ * cannot widen exposure to all interfaces.
+ *
  * @param {NodeJS.ProcessEnv} [env=process.env]
  * @returns {BridgeProxyConfig | null}
  */
 export function readProxyConfig(env = process.env) {
+  const configPath = getProxyConfigPath(env);
+  /** @type {unknown} */
+  let parsed;
   try {
-    const parsed = JSON.parse(fs.readFileSync(getProxyConfigPath(env), 'utf8'));
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      return null;
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (error) {
+    if (/** @type {{ code?: unknown }} */ (error)?.code !== 'ENOENT') {
+      warnProxyConfigIgnored(configPath, error instanceof Error ? error.message : String(error));
     }
-    const record = /** @type {Record<string, unknown>} */ (parsed);
-    const port = normalizePort(record.port);
-    const bindHost = normalizeHost(record.bindHost) ?? '0.0.0.0';
-    if (record.enabled !== true || port === null) {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    warnProxyConfigIgnored(configPath, 'expected a JSON object');
+    return null;
+  }
+  const record = /** @type {Record<string, unknown>} */ (parsed);
+  if (record.enabled !== true) {
+    return null;
+  }
+  const port = normalizePort(record.port);
+  if (port === null) {
+    warnProxyConfigIgnored(configPath, 'invalid "port" value');
+    return null;
+  }
+  let bindHost = '0.0.0.0';
+  if (record.bindHost != null) {
+    const normalized = normalizeHost(record.bindHost);
+    if (!normalized) {
+      warnProxyConfigIgnored(configPath, 'invalid "bindHost" value');
       return null;
     }
-    return {
-      enabled: true,
-      port,
-      bindHost,
-      ...(typeof record.token === 'string' ? { token: record.token } : {}),
-    };
-  } catch {
-    return null;
+    bindHost = normalized;
   }
+  return {
+    enabled: true,
+    port,
+    bindHost,
+    ...(typeof record.token === 'string' ? { token: record.token } : {}),
+  };
 }
 
 /**