@browserbridge/bbx 1.3.0 → 1.4.0

package/README.md

@@ -110,7 +110,9 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 3. Run `bbx install`, or target a specific browser with `bbx install --browser edge`, `bbx install --browser brave`, `bbx install --browser chromium`, or `bbx install --browser arc`
 4. In the extension side panel, install MCP or CLI (skill) for your agent of choice
 5. Enable Browser Bridge for the browser window you want to inspect/control with the AI agent
-6. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the `browser-bridge` / `$bbx` skill in CLI mode
+6. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the installed Browser Bridge skill in CLI mode (`/browser-bridge`, `browser-bridge`, or the client-specific skill trigger)
+
+MCP mode is self-contained: the server exposes tools, startup instructions, and prompt templates, so a separate CLI skill is not required for MCP guidance.
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -61,7 +61,7 @@
     "postinstall": "node packages/native-host/bin/postinstall.js",
     "package:extension": "node scripts/package-extension.mjs",
     "check:extension-zip": "node scripts/check-extension-zip.mjs",
-    "release:check": "npm run lint && npm run typecheck && npm test && npm run coverage:check && npm run package:extension && npm pack --dry-run",
+    "release:check": "npm run lint && npm run typecheck && npm test && npm run coverage:check && npm run package:extension && npm run check:extension-zip && npm pack --dry-run",
     "prepublishOnly": "npm run lint && npm run typecheck && npm test && npm run coverage:check",
     "status": "node packages/agent-client/src/cli.js status",
     "daemon": "node packages/native-host/bin/bridge-daemon.js",

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

@@ -128,15 +128,21 @@ if (command === 'install-skill') {
   const positional = rest.filter((a) => !a.startsWith('--'));
 
   if (positional.length === 0) {
-    // Parse scope flags without going through parseInstallAgentArgs.
-    let isGlobal = true;
-    if (rest.includes('--local')) isGlobal = false;
-    if (rest.includes('--global')) isGlobal = true;
+    let scopeOptions;
+    try {
+      scopeOptions = parseInstallAgentArgs(rest);
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exit(1);
+    }
+
+    const isGlobal = scopeOptions.global !== false;
+    const projectPath = isGlobal ? os.homedir() : scopeOptions.projectPath;
 
     const setupStatus = await collectSetupStatus({
       global: isGlobal,
       cwd: process.cwd(),
-      projectPath: isGlobal ? os.homedir() : process.cwd(),
+      projectPath,
       ...getSetupStatusTestOverrides(),
     });
     /** @type {import('./types.js').SupportedTarget[]} */
@@ -176,7 +182,6 @@ if (command === 'install-skill') {
       targets = /** @type {import('./types.js').SupportedTarget[]} */ (selected);
     }
 
-    const projectPath = isGlobal ? os.homedir() : process.cwd();
     if (selected !== null) {
       const deselectedTargets =
         /** @type {import('./types.js').SupportedTarget[]} */ (
@@ -226,20 +231,32 @@ if (command === 'install-skill') {
 }
 
 if (command === 'install-mcp') {
-  const argsLeft = [...rest];
   let isGlobal = true;
+  /** @type {string[]} */
+  const positionals = [];
 
-  const localIdx = argsLeft.indexOf('--local');
-  if (localIdx !== -1) {
-    isGlobal = false;
-    argsLeft.splice(localIdx, 1);
+  for (const arg of rest) {
+    if (arg === '--local') {
+      isGlobal = false;
+      continue;
+    }
+    if (arg === '--global') {
+      isGlobal = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      process.stderr.write(`Unknown install-mcp option "${arg}".\n`);
+      process.exit(1);
+    }
+    positionals.push(arg);
   }
-  const globalIdx = argsLeft.indexOf('--global');
-  if (globalIdx !== -1) {
-    argsLeft.splice(globalIdx, 1);
+
+  if (positionals.length > 1) {
+    process.stderr.write(`Unexpected extra argument "${positionals[1]}".\n`);
+    process.exit(1);
   }
 
-  const clientArg = argsLeft[0];
+  const clientArg = positionals[0];
 
   /** @type {import('./types.js').McpClientName[]} */
   let clients;

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

@@ -15,6 +15,7 @@ import {
   getBridgeTransport,
   getSocketPath,
 } from '../../native-host/src/config.js';
+import { normalizeBridgeAuthToken, readBridgeAuthToken } from '../../native-host/src/auth-token.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 
 /** @typedef {import('./types.js').BridgeMeta} BridgeMeta */
@@ -56,6 +57,22 @@ function createTimeoutError(method, timeoutMs) {
   return error;
 }
 
+/**
+ * @param {net.Socket} socket
+ * @param {string} line
+ * @returns {Promise<void>}
+ */
+async function writeSocketLine(socket, line) {
+  if (!socket.write(line)) {
+    await Promise.race([
+      once(socket, 'drain'),
+      once(socket, 'close').then(() => {
+        throw new Error('Bridge socket closed while writing.');
+      }),
+    ]);
+  }
+}
+
 export class BridgeClient extends EventEmitter {
   /**
    * @param {BridgeClientOptions} [options={}]
@@ -68,6 +85,7 @@ export class BridgeClient extends EventEmitter {
     autoReconnect = false,
     restartDaemonOnVersionMismatch = true,
     restartDaemonFn = restartBridgeDaemon,
+    authToken = undefined,
   } = {}) {
     super();
     this.transport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
@@ -78,6 +96,7 @@ export class BridgeClient extends EventEmitter {
     this.autoReconnect = autoReconnect;
     this.restartDaemonOnVersionMismatch = restartDaemonOnVersionMismatch;
     this.restartDaemonFn = restartDaemonFn;
+    this.authToken = authToken;
     this.socket = null;
     this.connected = false;
     this.protocolCompatibility = null;
@@ -111,6 +130,18 @@ export class BridgeClient extends EventEmitter {
       throw error;
     }
 
+    const registrationPromise = new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        this.waiting.delete('registered');
+        reject(createTimeoutError('register', this.defaultTimeoutMs));
+      }, this.defaultTimeoutMs);
+      this.waiting.set('registered', {
+        resolve,
+        reject,
+        timeoutId,
+      });
+    });
+
     parseJsonLines(socket, (raw) => {
       const message = /** @type {ClientMessage} */ (raw);
       if (message.type === 'registered') {
@@ -124,6 +155,16 @@ export class BridgeClient extends EventEmitter {
         return;
       }
 
+      if (message.type === 'registration_failed') {
+        const pending = this.waiting.get('registered');
+        if (pending) {
+          this.waiting.delete('registered');
+          clearTimeout(pending.timeoutId);
+          pending.reject(new Error(message.error?.message || 'Bridge daemon registration failed.'));
+        }
+        return;
+      }
+
       if (message.type === 'agent.response') {
         const pending = this.waiting.get(message.response.id);
         if (pending) {
@@ -148,20 +189,31 @@ export class BridgeClient extends EventEmitter {
       // 'close' fires after 'error'; reconnect is triggered there.
     });
 
-    this.socket.write(
-      `${JSON.stringify({ type: 'register', role: 'agent', clientId: this.clientId })}\n`
-    );
-    await new Promise((resolve, reject) => {
-      const timeoutId = setTimeout(() => {
+    const authToken =
+      this.authToken === undefined
+        ? this.transport.type === 'tcp'
+          ? await readBridgeAuthToken()
+          : null
+        : normalizeBridgeAuthToken(this.authToken);
+    try {
+      await writeSocketLine(
+        socket,
+        `${JSON.stringify({
+          type: 'register',
+          role: 'agent',
+          clientId: this.clientId,
+          ...(authToken ? { authToken } : {}),
+        })}\n`
+      );
+    } catch (error) {
+      const pending = this.waiting.get('registered');
+      if (pending) {
+        clearTimeout(pending.timeoutId);
         this.waiting.delete('registered');
-        reject(createTimeoutError('register', this.defaultTimeoutMs));
-      }, this.defaultTimeoutMs);
-      this.waiting.set('registered', {
-        resolve,
-        reject,
-        timeoutId,
-      });
-    });
+      }
+      throw error;
+    }
+    await registrationPromise;
 
     this.protocolCompatibility = null;
     this.protocolWarning = null;
@@ -244,13 +296,15 @@ export class BridgeClient extends EventEmitter {
       });
     });
 
-    if (!this.socket.write(`${JSON.stringify({ type: 'agent.request', request })}\n`)) {
-      await Promise.race([
-        once(this.socket, 'drain'),
-        once(this.socket, 'close').then(() => {
-          throw new Error('Bridge socket closed while writing.');
-        }),
-      ]);
+    try {
+      await writeSocketLine(this.socket, `${JSON.stringify({ type: 'agent.request', request })}\n`);
+    } catch (error) {
+      const pending = this.waiting.get(request.id);
+      if (pending) {
+        clearTimeout(pending.timeoutId);
+        this.waiting.delete(request.id);
+      }
+      throw error;
     }
     const response = /** @type {BridgeResponse} */ (await responsePromise);
     return this.attachProtocolWarning(response);

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

@@ -237,11 +237,10 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Setup',
     lines: [
-      'bbx install [--browser chrome|edge|brave|chromium|arc] [extension-id]  Install native messaging manifest',
+      'bbx install [extension-id] [--browser chrome|edge|brave|chromium|arc] [--all]  Install native messaging manifest',
       'bbx uninstall                                                      Remove native host manifests, Browser Bridge runtime files, and managed MCP/skill installs',
-      'bbx install [--all] [--browser <name>] [extension-id]              Install native host manifest (--all for all supported browsers)',
       'bbx install-skill [targets|all] [--global] [--project <path>]      Install/update the managed Browser Bridge CLI skill',
-      'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf',
+      'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf|agents',
       'bbx status                                                         Check bridge connection',
       'bbx doctor                                                         Diagnose install, daemon, extension, and access readiness',
       'bbx restart                                                        Restart the local Browser Bridge daemon',

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

@@ -523,8 +523,13 @@ async function installJsonMcpConfig(clientName, configPath, stdout) {
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
       existing = parsed;
     }
-  } catch {
-    // File missing or unparseable - start fresh.
+  } catch (error) {
+    if (!isMissingFileError(error)) {
+      throw new Error(
+        `Cannot update ${configPath}: existing MCP config is not valid JSON. Fix or remove it first.`
+      );
+    }
+    // File missing - start fresh.
   }
 
   const shape = getMcpConfigShape(clientName);
@@ -661,3 +666,15 @@ export function parseInstalledMcpConfig(clientName, raw) {
     return { configured: false };
   }
 }
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isMissingFileError(error) {
+  return Boolean(
+    error &&
+    typeof error === 'object' &&
+    /** @type {{ code?: unknown }} */ (error).code === 'ENOENT'
+  );
+}

package/packages/agent-client/src/types.ts

@@ -54,6 +54,13 @@ export type ClientMessage =
       role: 'agent' | 'extension';
       clientId?: string;
     }
+  | {
+      type: 'registration_failed';
+      error?: {
+        code?: string;
+        message?: string;
+      };
+    }
   | {
       type: 'agent.response';
       response: BridgeResponse;
@@ -73,6 +80,7 @@ export interface BridgeClientOptions {
   autoReconnect?: boolean;
   restartDaemonOnVersionMismatch?: boolean;
   restartDaemonFn?: typeof restartBridgeDaemon;
+  authToken?: string | null;
 }
 
 export interface ShortcutCommand {

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

@@ -0,0 +1,241 @@
+// @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.",
+  'Prefer Browser Bridge MCP tools over shelling out to bbx. Use bbx only for explicit CLI setup, doctor, logs, or raw debugging requests.',
+  'Call browser_status first. If window access is disabled, call browser_access once, ask the user to click Enable in the Browser Bridge popup or side panel, then retry once.',
+  'Use structured reads first: browser_page, browser_dom, browser_styles_layout, and browser_batch. Keep budgetPreset quick or normal before widening.',
+  'Reuse elementRef values returned by DOM tools. Use attribute allowlists for focused DOM reads.',
+  'Escalate to browser_capture, accessibility_tree, page evaluate, viewport resize, or CDP only when structured reads cannot answer the question.',
+  'Use browser_patch for temporary style or DOM experiments, and rollback patches before finishing unless the user asks to keep them.',
+].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 tools over `bbx`; do not shell out unless setup, doctor, logs, or raw CLI debugging is explicitly needed.',
+      '2. Call `browser_status` first. If access is disabled, call `browser_access` once, ask the user to click Enable, then retry once.',
+      '3. Start with structured reads: `browser_page` action `state`, `browser_dom` action `query`/`find_text`/`find_role`, `browser_styles_layout`, and `browser_batch`.',
+      '4. Keep budgets tight with `budgetPreset: "quick"` or `"normal"`; widen only when results are truncated.',
+      '5. Reuse `elementRef` values returned by DOM tools instead of rescanning.',
+      '6. Escalate to `browser_capture`, accessibility tree, `browser_page` evaluate, viewport resize, or CDP only when structured reads cannot answer.',
+      '7. Use `browser_patch` for temporary style/DOM experiments and rollback before finishing unless the user asks to keep patches.',
+      '',
+      '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;
+}