@browserbridge/bbx 1.2.0 → 1.4.0

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

@@ -0,0 +1,139 @@
+import type { BridgeTransport } from '../../native-host/src/config.js';
+import type {
+  BridgeMeta,
+  BridgeMethod,
+  BridgeRequestSource,
+  BridgeResponse,
+} from '../../protocol/src/types.js';
+import type { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
+
+export type { BridgeMeta, BridgeMethod, BridgeRequestSource, BridgeResponse, BridgeTransport };
+
+export type McpClientName =
+  | 'codex'
+  | 'claude'
+  | 'cursor'
+  | 'copilot'
+  | 'opencode'
+  | 'antigravity'
+  | 'windsurf'
+  | 'agents';
+
+export type SupportedTarget = McpClientName;
+
+export type Detector = () => boolean | Promise<boolean>;
+
+export interface InstallAgentOptions {
+  targets: SupportedTarget[];
+  projectPath: string;
+  global: boolean;
+  [key: string]: unknown;
+}
+
+export interface SetupStatusOptions {
+  global?: boolean;
+  cwd?: string;
+  projectPath?: string;
+  mcpDetectors?: Record<string, Detector>;
+  skillDetectors?: Record<string, Detector>;
+  access?: (targetPath: string) => Promise<void>;
+  readFile?: (targetPath: string, encoding: BufferEncoding) => Promise<string>;
+}
+
+export interface ProtocolHealthResult {
+  extensionConnected?: boolean;
+  supported_versions?: string[];
+  daemon_supported_versions?: string[];
+  deprecated_since?: string;
+  migration_hint?: string;
+}
+
+export type ClientMessage =
+  | {
+      type: 'registered';
+      role: 'agent' | 'extension';
+      clientId?: string;
+    }
+  | {
+      type: 'registration_failed';
+      error?: {
+        code?: string;
+        message?: string;
+      };
+    }
+  | {
+      type: 'agent.response';
+      response: BridgeResponse;
+    };
+
+export interface PendingRequest {
+  resolve: (value: any) => void;
+  reject: (error: Error) => void;
+  timeoutId: NodeJS.Timeout;
+}
+
+export interface BridgeClientOptions {
+  transport?: BridgeTransport;
+  socketPath?: string;
+  clientId?: string;
+  defaultTimeoutMs?: number;
+  autoReconnect?: boolean;
+  restartDaemonOnVersionMismatch?: boolean;
+  restartDaemonFn?: typeof restartBridgeDaemon;
+  authToken?: string | null;
+}
+
+export interface ShortcutCommand {
+  method: BridgeMethod;
+  resolve?: boolean;
+  printMethod?: string;
+  usage: string;
+  description: string;
+  build: (r: string[], ref?: string) => Record<string, unknown>;
+}
+
+export interface BrowserManifestStatus {
+  browser: string;
+  manifestPath: string;
+  installed: boolean;
+}
+
+export interface DoctorReport {
+  manifestInstalled: boolean;
+  manifestPath: string;
+  allowedOrigins: string[];
+  defaultExtensionId: string | null;
+  defaultExtensionIdSource: string;
+  daemonReachable: boolean;
+  extensionConnected: boolean;
+  accessEnabled: boolean;
+  enabledWindowId: number | null;
+  routeTabId: number | null;
+  routeReady: boolean;
+  routeReason: string;
+  issues: string[];
+  nextSteps: string[];
+  browserManifests: BrowserManifestStatus[];
+}
+
+export interface DoctorReportOptions {
+  loadManifest?: () => Promise<{ allowed_origins?: string[] } | null>;
+  manifestPath?: string;
+  defaultExtensionIdInfo?: { extensionId: string | null; source: string };
+  bridgeClientRunner?: <T>(
+    callback: (client: { request: BridgeClientRequest }) => Promise<T>
+  ) => Promise<T>;
+}
+
+export type BridgeClientRequest = (options: {
+  method: BridgeMethod;
+  tabId?: number | null;
+  params?: Record<string, unknown>;
+  meta?: BridgeMeta;
+  timeoutMs?: number;
+}) => Promise<BridgeResponse>;
+
+export interface ScreenshotResult {
+  image: string;
+  rect: Record<string, unknown>;
+}

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;
+}

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

@@ -4,7 +4,7 @@ import {
   dispatchToolAction,
   getToolTokenBudget,
   REQUEST_SOURCE,
-  requestBridge,
+  requestBridgeWithRetry,
   resolveToolRef,
   resolveRef,
   summarizeToolError,
@@ -40,22 +40,63 @@ export const CAPTURE_ACTIONS = {
     params: () => ({}),
   },
   cdp_box_model: {
-    ref: true,
+    ref: false,
     method: 'cdp.get_box_model',
-    params: (_, r) => ({ elementRef: r }),
+    params: (a) => ({ nodeId: a.nodeId }),
   },
   cdp_computed_styles: {
-    ref: true,
+    ref: false,
     method: 'cdp.get_computed_styles_for_node',
-    params: (_, r) => ({ elementRef: r }),
+    params: (a) => ({ nodeId: a.nodeId }),
   },
 };
 
+/** @param {Record<string, unknown>} args */
+function isCdpNodeCapture(args) {
+  return args.action === 'cdp_box_model' || args.action === 'cdp_computed_styles';
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/** @param {unknown} rect */
+function isValidCaptureRegion(rect) {
+  if (!rect || typeof rect !== 'object' || Array.isArray(rect)) {
+    return false;
+  }
+  const candidate = /** @type {Record<string, unknown>} */ (rect);
+  return (
+    isFiniteNumber(candidate.x) &&
+    isFiniteNumber(candidate.y) &&
+    isFiniteNumber(candidate.width) &&
+    candidate.width > 0 &&
+    isFiniteNumber(candidate.height) &&
+    candidate.height > 0
+  );
+}
+
 /**
- * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, nodeId?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleCaptureTool(args) {
+  if (args.action === 'region' && !isValidCaptureRegion(args.rect)) {
+    return summarizeToolError(
+      'rect with finite x, y, width, and height is required for region capture.'
+    );
+  }
+  if (
+    isCdpNodeCapture(args) &&
+    (typeof args.nodeId !== 'number' || !Number.isFinite(args.nodeId))
+  ) {
+    return summarizeToolError('nodeId must be a finite number.');
+  }
+
   return dispatchToolAction(CAPTURE_ACTIONS, args, 'capture');
 }
 
@@ -78,6 +119,21 @@ export const INPUT_ACTION_METHODS = {
  * @returns {Promise<ToolResult>}
  */
 export async function handleInputTool(args) {
+  if (args.action === 'type' && !hasText(args.text)) {
+    return summarizeToolError('text is required for input.type.');
+  }
+  if ((args.action === 'press_key' || args.action === 'cdp_press_key') && !hasText(args.key)) {
+    return summarizeToolError('key is required for key input actions.');
+  }
+  if (
+    args.action === 'select_option' &&
+    !hasNonEmptyArray(args.values) &&
+    !hasNonEmptyArray(args.labels) &&
+    !hasNonEmptyArray(args.indexes)
+  ) {
+    return summarizeToolError('values, labels, or indexes are required for input.select_option.');
+  }
+
   return withToolClient(async (client) => {
     const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
     const elementTarget = async () => ({
@@ -86,13 +142,14 @@ export async function handleInputTool(args) {
 
     switch (args.action) {
       case 'click': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.click',
           {
             target: await elementTarget(),
             button: args.button,
             clickCount: args.clickCount,
+            modifiers: args.modifiers,
           },
           {
             tabId: requestedTabId,
@@ -103,7 +160,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.click');
       }
       case 'focus': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.focus',
           {
@@ -118,7 +175,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.focus');
       }
       case 'type': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.type',
           {
@@ -126,6 +183,7 @@ export async function handleInputTool(args) {
             text: args.text,
             clear: args.clear,
             submit: args.submit,
+            modifiers: args.modifiers,
           },
           {
             tabId: requestedTabId,
@@ -137,7 +195,7 @@ export async function handleInputTool(args) {
       }
       case 'press_key': {
         const target = args.elementRef || args.selector ? await elementTarget() : undefined;
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.press_key',
           {
@@ -154,7 +212,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.press_key');
       }
       case 'cdp_press_key': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'cdp.dispatch_key_event',
           {
@@ -171,7 +229,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'cdp.dispatch_key_event');
       }
       case 'set_checked': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.set_checked',
           {
@@ -187,7 +245,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.set_checked');
       }
       case 'select_option': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.select_option',
           {
@@ -205,12 +263,13 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.select_option');
       }
       case 'hover': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.hover',
           {
             target: await elementTarget(),
             duration: args.duration,
+            modifiers: args.modifiers,
           },
           {
             tabId: requestedTabId,
@@ -240,7 +299,7 @@ export async function handleInputTool(args) {
             'sourceElementRef/sourceSelector and destinationElementRef/destinationSelector are required for drag.'
           );
         }
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.drag',
           {
@@ -258,7 +317,7 @@ export async function handleInputTool(args) {
         return summarizeToolResponse(response, 'input.drag');
       }
       case 'scroll_into_view': {
-        const response = await requestBridge(
+        const response = await requestBridgeWithRetry(
           client,
           'input.scroll_into_view',
           {
@@ -277,3 +336,19 @@ export async function handleInputTool(args) {
     }
   });
 }
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function hasNonEmptyArray(value) {
+  return Array.isArray(value) && value.length > 0;
+}