@browserbridge/bbx 1.1.0 → 1.3.0

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

@@ -0,0 +1,131 @@
+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: '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;
+}
+
+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/handlers-capture.js

@@ -0,0 +1,291 @@
+// @ts-check
+
+import {
+  dispatchToolAction,
+  getToolTokenBudget,
+  REQUEST_SOURCE,
+  requestBridge,
+  resolveToolRef,
+  resolveRef,
+  summarizeToolError,
+  summarizeToolResponse,
+  withToolClient,
+} from './handlers-utils.js';
+
+/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./handlers-utils.js').ToolAction} ToolAction */
+/** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
+
+/** @type {Record<string, ToolAction>} */
+export const CAPTURE_ACTIONS = {
+  element: {
+    ref: true,
+    method: 'screenshot.capture_element',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  region: {
+    ref: false,
+    method: 'screenshot.capture_region',
+    params: (a) => /** @type {Record<string, unknown>} */ (a.rect || {}),
+  },
+  full_page: {
+    ref: false,
+    method: 'screenshot.capture_full_page',
+    params: () => ({}),
+  },
+  cdp_document: { ref: false, method: 'cdp.get_document', params: () => ({}) },
+  cdp_dom_snapshot: {
+    ref: false,
+    method: 'cdp.get_dom_snapshot',
+    params: () => ({}),
+  },
+  cdp_box_model: {
+    ref: false,
+    method: 'cdp.get_box_model',
+    params: (a) => ({ nodeId: a.nodeId }),
+  },
+  cdp_computed_styles: {
+    ref: false,
+    method: 'cdp.get_computed_styles_for_node',
+    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 {{ 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 (
+    isCdpNodeCapture(args) &&
+    (typeof args.nodeId !== 'number' || !Number.isFinite(args.nodeId))
+  ) {
+    return summarizeToolError('nodeId must be a finite number.');
+  }
+
+  return dispatchToolAction(CAPTURE_ACTIONS, args, 'capture');
+}
+
+/** @type {Record<string, BridgeMethod>} */
+export const INPUT_ACTION_METHODS = {
+  click: 'input.click',
+  focus: 'input.focus',
+  type: 'input.type',
+  press_key: 'input.press_key',
+  cdp_press_key: 'cdp.dispatch_key_event',
+  set_checked: 'input.set_checked',
+  select_option: 'input.select_option',
+  hover: 'input.hover',
+  drag: 'input.drag',
+  scroll_into_view: 'input.scroll_into_view',
+};
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, text?: string, clear?: boolean, submit?: boolean, key?: string, code?: string, modifiers?: string[], checked?: boolean, values?: string[], labels?: string[], indexes?: number[], duration?: number, sourceElementRef?: string, sourceSelector?: string, destinationElementRef?: string, destinationSelector?: string, offsetX?: number, offsetY?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleInputTool(args) {
+  return withToolClient(async (client) => {
+    const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
+    const elementTarget = async () => ({
+      elementRef: await resolveToolRef(client, args, requestedTabId),
+    });
+
+    switch (args.action) {
+      case 'click': {
+        const response = await requestBridge(
+          client,
+          'input.click',
+          {
+            target: await elementTarget(),
+            button: args.button,
+            clickCount: args.clickCount,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.click');
+      }
+      case 'focus': {
+        const response = await requestBridge(
+          client,
+          'input.focus',
+          {
+            target: await elementTarget(),
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.focus');
+      }
+      case 'type': {
+        const response = await requestBridge(
+          client,
+          'input.type',
+          {
+            target: await elementTarget(),
+            text: args.text,
+            clear: args.clear,
+            submit: args.submit,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.type');
+      }
+      case 'press_key': {
+        const target = args.elementRef || args.selector ? await elementTarget() : undefined;
+        const response = await requestBridge(
+          client,
+          'input.press_key',
+          {
+            target,
+            key: args.key,
+            modifiers: args.modifiers,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.press_key');
+      }
+      case 'cdp_press_key': {
+        const response = await requestBridge(
+          client,
+          'cdp.dispatch_key_event',
+          {
+            key: args.key,
+            code: args.code,
+            modifiers: args.modifiers,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'cdp.dispatch_key_event');
+      }
+      case 'set_checked': {
+        const response = await requestBridge(
+          client,
+          'input.set_checked',
+          {
+            target: await elementTarget(),
+            checked: args.checked,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.set_checked');
+      }
+      case 'select_option': {
+        const response = await requestBridge(
+          client,
+          'input.select_option',
+          {
+            target: await elementTarget(),
+            values: args.values,
+            labels: args.labels,
+            indexes: args.indexes,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.select_option');
+      }
+      case 'hover': {
+        const response = await requestBridge(
+          client,
+          'input.hover',
+          {
+            target: await elementTarget(),
+            duration: args.duration,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.hover');
+      }
+      case 'drag': {
+        const source = {
+          elementRef:
+            args.sourceElementRef ||
+            (args.sourceSelector
+              ? await resolveRef(client, args.sourceSelector, requestedTabId, REQUEST_SOURCE)
+              : ''),
+        };
+        const destination = {
+          elementRef:
+            args.destinationElementRef ||
+            (args.destinationSelector
+              ? await resolveRef(client, args.destinationSelector, requestedTabId, REQUEST_SOURCE)
+              : ''),
+        };
+        if (!source.elementRef || !destination.elementRef) {
+          return summarizeToolError(
+            'sourceElementRef/sourceSelector and destinationElementRef/destinationSelector are required for drag.'
+          );
+        }
+        const response = await requestBridge(
+          client,
+          'input.drag',
+          {
+            source,
+            destination,
+            offsetX: args.offsetX,
+            offsetY: args.offsetY,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.drag');
+      }
+      case 'scroll_into_view': {
+        const response = await requestBridge(
+          client,
+          'input.scroll_into_view',
+          {
+            target: await elementTarget(),
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.scroll_into_view');
+      }
+      default:
+        return summarizeToolError(`Unsupported input action "${args.action}".`);
+    }
+  });
+}

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

@@ -0,0 +1,203 @@
+// @ts-check
+
+import {
+  applyHtmlBudgetPreset,
+  applyTextBudgetPreset,
+  applyTreeBudgetPreset,
+  dispatchToolAction,
+  inferBudgetFromSelector,
+} from './handlers-utils.js';
+
+/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./handlers-utils.js').ToolAction} ToolAction */
+/** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
+
+/** @type {Record<string, ToolAction>} */
+export const DOM_ACTIONS = {
+  query: {
+    ref: false,
+    method: 'dom.query',
+    params: (a) => ({
+      selector: a.selector || 'body',
+      withinRef: a.withinRef,
+      maxNodes: a.maxNodes,
+      maxDepth: a.maxDepth,
+      textBudget: a.textBudget,
+      includeBbox: a.includeBbox,
+      attributeAllowlist: a.attributeAllowlist,
+    }),
+  },
+  describe: {
+    ref: true,
+    method: 'dom.describe',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  text: {
+    ref: true,
+    method: 'dom.get_text',
+    params: (a, r) => ({ elementRef: r, textBudget: a.textBudget }),
+  },
+  attributes: {
+    ref: true,
+    method: 'dom.get_attributes',
+    params: (a, r) => ({ elementRef: r, attributes: a.attributes || [] }),
+  },
+  wait: {
+    ref: false,
+    method: 'dom.wait_for',
+    params: (a) => ({
+      selector: a.selector,
+      text: a.text,
+      state: a.state,
+      timeoutMs: a.timeoutMs,
+    }),
+  },
+  find_text: {
+    ref: false,
+    method: 'dom.find_by_text',
+    params: (a) => ({
+      text: a.text,
+      exact: a.exact,
+      selector: a.selector,
+      maxResults: a.maxResults,
+    }),
+  },
+  find_role: {
+    ref: false,
+    method: 'dom.find_by_role',
+    params: (a) => ({
+      role: a.role,
+      name: a.name,
+      selector: a.selector,
+      maxResults: a.maxResults,
+    }),
+  },
+  html: {
+    ref: true,
+    method: 'dom.get_html',
+    params: (a, r) => ({
+      elementRef: r,
+      outer: a.outer,
+      maxLength: a.maxLength,
+    }),
+  },
+  accessibility_tree: {
+    ref: false,
+    method: 'dom.get_accessibility_tree',
+    params: (a) => ({ maxNodes: a.maxNodes, maxDepth: a.maxDepth }),
+  },
+};
+
+/**
+ * @param {{ action: string, selector?: string, elementRef?: string, withinRef?: string, maxNodes?: number, maxDepth?: number, textBudget?: number, includeBbox?: boolean, attributeAllowlist?: string[], attributes?: string[], text?: string, exact?: boolean, maxResults?: number, role?: string, name?: string, state?: string, timeoutMs?: number, outer?: boolean, maxLength?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleDomTool(args) {
+  if (args.action === 'query' || args.action === 'accessibility_tree') {
+    const inferred = inferBudgetFromSelector(args);
+    const withBudget = inferred ? { ...args, budgetPreset: args.budgetPreset ?? inferred } : args;
+    return dispatchToolAction(DOM_ACTIONS, applyTreeBudgetPreset(withBudget), 'DOM');
+  }
+  if (args.action === 'text') {
+    return dispatchToolAction(DOM_ACTIONS, applyTextBudgetPreset(args), 'DOM');
+  }
+  if (args.action === 'html') {
+    return dispatchToolAction(DOM_ACTIONS, applyHtmlBudgetPreset(args), 'DOM');
+  }
+  return dispatchToolAction(DOM_ACTIONS, args, 'DOM');
+}
+
+/** @type {Record<string, ToolAction>} */
+export const STYLES_LAYOUT_ACTIONS = {
+  computed: {
+    ref: true,
+    method: 'styles.get_computed',
+    params: (a, r) => ({ elementRef: r, properties: a.properties }),
+  },
+  matched_rules: {
+    ref: true,
+    method: 'styles.get_matched_rules',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  box_model: {
+    ref: true,
+    method: 'layout.get_box_model',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  hit_test: {
+    ref: false,
+    method: 'layout.hit_test',
+    params: (a) => ({ x: a.x, y: a.y }),
+  },
+};
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, properties?: string[], x?: number, y?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleStylesLayoutTool(args) {
+  return dispatchToolAction(STYLES_LAYOUT_ACTIONS, args, 'styles/layout');
+}
+
+/** @type {Record<string, ToolAction>} */
+export const PATCH_ACTIONS = {
+  apply_styles: {
+    ref: true,
+    method: 'patch.apply_styles',
+    params: (a, r) => ({
+      target: { elementRef: r },
+      declarations: a.declarations,
+      important: a.important,
+      patchId: a.patchId,
+      verify: a.verify,
+    }),
+  },
+  apply_dom: {
+    ref: true,
+    method: 'patch.apply_dom',
+    params: (a, r) => {
+      const operation = typeof a.operation === 'string' ? a.operation : '';
+      /** @type {Record<string, string>} */
+      const opMap = {
+        setAttribute: 'set_attribute',
+        removeAttribute: 'remove_attribute',
+        addClass: 'add_class',
+        removeClass: 'remove_class',
+        setTextContent: 'set_text',
+        setProperty: 'set_attribute',
+      };
+      const normalizedOperation = opMap[operation] || operation;
+      const value =
+        normalizedOperation === 'add_class' || normalizedOperation === 'remove_class'
+          ? (a.value ?? a.name)
+          : a.value;
+      return {
+        target: { elementRef: r },
+        operation: normalizedOperation,
+        value,
+        name: a.name,
+        patchId: a.patchId,
+        verify: a.verify,
+      };
+    },
+  },
+  list: { ref: false, method: 'patch.list', params: () => ({}) },
+  rollback: {
+    ref: false,
+    method: 'patch.rollback',
+    params: (a) => ({ patchId: a.patchId }),
+  },
+  commit_baseline: {
+    ref: false,
+    method: 'patch.commit_session_baseline',
+    params: () => ({}),
+  },
+};
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, declarations?: Record<string, string>, important?: boolean, operation?: string, value?: unknown, name?: string, patchId?: string, verify?: boolean, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handlePatchTool(args) {
+  return dispatchToolAction(PATCH_ACTIONS, args, 'patch');
+}

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

@@ -0,0 +1,79 @@
+// @ts-check
+
+import { callBridgeTool, getToolTokenBudget, summarizeToolError } from './handlers-utils.js';
+
+/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
+
+/**
+ * @param {{ action: string, url?: string, active?: boolean, tabId?: number }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleTabsTool(args) {
+  if (args.action === 'list') {
+    return callBridgeTool('tabs.list');
+  }
+  if (args.action === 'create') {
+    return callBridgeTool('tabs.create', {
+      url: args.url,
+      active: args.active,
+    });
+  }
+  if (args.action === 'close') {
+    if (typeof args.tabId !== 'number') {
+      return summarizeToolError('tabId is required for tabs.close.');
+    }
+    return callBridgeTool('tabs.close', { tabId: args.tabId });
+  }
+  return summarizeToolError(`Unsupported tabs action "${args.action}".`);
+}
+
+/** @type {Record<string, { method: BridgeMethod, params: (a: Record<string, unknown>) => Record<string, unknown> }>} */
+export const NAVIGATION_ACTIONS = {
+  navigate: {
+    method: 'navigation.navigate',
+    params: (a) => ({
+      url: a.url,
+      waitForLoad: a.waitForLoad,
+      timeoutMs: a.timeoutMs,
+    }),
+  },
+  reload: {
+    method: 'navigation.reload',
+    params: (a) => ({ waitForLoad: a.waitForLoad, timeoutMs: a.timeoutMs }),
+  },
+  go_back: {
+    method: 'navigation.go_back',
+    params: (a) => ({ waitForLoad: a.waitForLoad, timeoutMs: a.timeoutMs }),
+  },
+  go_forward: {
+    method: 'navigation.go_forward',
+    params: (a) => ({ waitForLoad: a.waitForLoad, timeoutMs: a.timeoutMs }),
+  },
+  scroll: {
+    method: 'viewport.scroll',
+    params: (a) => ({
+      top: a.top,
+      left: a.left,
+      behavior: a.behavior,
+      relative: a.relative,
+    }),
+  },
+  resize: {
+    method: 'viewport.resize',
+    params: (a) => ({ width: a.width, height: a.height, reset: a.reset }),
+  },
+};
+
+/**
+ * @param {{ action: string, url?: string, waitForLoad?: boolean, timeoutMs?: number, top?: number, left?: number, behavior?: string, relative?: boolean, width?: number, height?: number, reset?: boolean, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleNavigationTool(args) {
+  const entry = NAVIGATION_ACTIONS[args.action];
+  if (!entry) return summarizeToolError(`Unsupported navigation action "${args.action}".`);
+  return callBridgeTool(entry.method, entry.params(args), {
+    tabId: typeof args.tabId === 'number' ? args.tabId : null,
+    tokenBudget: getToolTokenBudget(args),
+  });
+}