@browserbridge/bbx 1.7.8 → 1.9.0

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

@@ -4,10 +4,21 @@ import type {
   BridgeMethod,
   BridgeRequestSource,
   BridgeResponse,
+  RecoveryEventKind,
+  RecoveryTelemetrySummary,
+  ScreenshotResult,
+  SetupStatus,
 } from '../../protocol/src/types.js';
 import type { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 
-export type { BridgeMeta, BridgeMethod, BridgeRequestSource, BridgeResponse, BridgeTransport };
+export type {
+  BridgeMeta,
+  BridgeMethod,
+  BridgeRequestSource,
+  BridgeResponse,
+  BridgeTransport,
+  ScreenshotResult,
+};
 
 export type McpClientName =
   | 'codex'
@@ -21,6 +32,26 @@ export type McpClientName =
 
 export type SupportedTarget = McpClientName;
 
+export type AutoUpdatePolicy = 'off' | 'compatible';
+
+export interface BrowserBridgeConfig {
+  autoUpdate: AutoUpdatePolicy;
+  [key: string]: unknown;
+}
+
+export interface NpmUpdateResult {
+  updated: boolean;
+  reason:
+    | 'updated'
+    | 'invalid_extension_version'
+    | 'invalid_installed_version'
+    | 'extension_not_newer'
+    | 'not_global_install'
+    | 'no_compatible_update';
+  previousVersion?: string;
+  version?: string;
+}
+
 export type Detector = () => boolean | Promise<boolean>;
 
 export interface InstallAgentOptions {
@@ -42,7 +73,10 @@ export interface SetupStatusOptions {
 
 export interface ProtocolHealthResult {
   extensionConnected?: boolean;
+  extensionVersion?: string;
+  daemonVersion?: string;
   supported_versions?: string[];
+  extension_supported_versions?: string[];
   daemon_supported_versions?: string[];
   deprecated_since?: string;
   migration_hint?: string;
@@ -78,8 +112,15 @@ export interface BridgeClientOptions {
   clientId?: string;
   defaultTimeoutMs?: number;
   autoReconnect?: boolean;
+  checkProtocolOnConnect?: boolean;
   restartDaemonOnVersionMismatch?: boolean;
   restartDaemonFn?: typeof restartBridgeDaemon;
+  updateNpmOnCompatibleVersion?: boolean;
+  exitProcessOnNpmUpdate?: boolean;
+  updateCompatibleNpmPackageFn?: (options: {
+    extensionVersion: string;
+    supportedVersions: readonly string[];
+  }) => Promise<NpmUpdateResult>;
   authToken?: string | null;
 }
 
@@ -110,6 +151,113 @@ export interface NativeHostManifestIssue {
   message: string;
 }
 
+export interface DoctorTransportDiagnostics {
+  kind: 'socket' | 'tcp' | 'unknown';
+  local: true;
+  status: 'reachable' | 'offline' | 'authentication_failed';
+  proxyConfigured: boolean;
+  proxyExposed: boolean | null;
+  credentials: 'not_required' | 'accepted' | 'rejected' | 'unknown';
+}
+
+export interface DoctorConnectionDiagnostics {
+  extensionCount: number;
+  profileCount: number;
+}
+
+export interface DoctorProtocolDiagnostics {
+  clientVersion: string;
+  daemonVersion: string | null;
+  daemonSupportedVersions: string[];
+  extensionSupportedVersions: string[];
+  daemonCompatible: boolean | null;
+  extensionCompatible: boolean | null;
+  compatible: boolean | null;
+  migration: 'none' | 'update_client' | 'restart_daemon' | 'update_extension' | 'unknown';
+}
+
+export interface DoctorDebuggerDiagnostics {
+  state: 'idle' | 'active' | 'conflict' | 'detached' | 'unknown';
+  attachedTabCount: number | null;
+  heldTabCount: number | null;
+  pendingTabCount: number | null;
+  recentReason:
+    | 'debugger_conflict'
+    | 'debugger_detached'
+    | 'debugger_replaced'
+    | 'debugger_canceled'
+    | 'target_closed'
+    | null;
+  captureState:
+    | 'idle'
+    | 'stopped'
+    | 'armed'
+    | 'active'
+    | 'capturing'
+    | 'stop_failed'
+    | 'unavailable'
+    | 'unknown';
+  captureActiveTabCount: number | null;
+  captureOwnershipCount: number | null;
+  captureInflightCount: number | null;
+  interceptionActiveTabCount: number | null;
+  interceptionRuleCount: number | null;
+}
+
+export interface DoctorDaemonMetrics {
+  uptimeMs: number;
+  activeAgents: number;
+  activeExtensions: number;
+  pendingRequests: number;
+  requestsProcessed: number;
+  requestsFailed: number;
+  avgResponseTimeMs: number;
+  recovery: RecoveryTelemetrySummary | null;
+}
+
+export interface DoctorRecoveryDiagnostics {
+  daemon: RecoveryTelemetrySummary | null;
+  routedExtension: RecoveryTelemetrySummary | null;
+  activeLoops: RecoveryEventKind[];
+}
+
+export interface DoctorRecentEvent {
+  at?: string;
+  method?: BridgeMethod;
+  ok?: boolean;
+  source?: BridgeRequestSource;
+  cause?:
+    | 'debugger_conflict'
+    | 'debugger_detached'
+    | 'debugger_replaced'
+    | 'debugger_canceled'
+    | 'target_closed'
+    | 'dialog_conflict'
+    | 'extension_disconnected'
+    | 'wrong_window';
+}
+
+export interface DoctorSetupSummary {
+  source: 'daemon' | 'direct';
+  scope: 'global' | 'local';
+  mcp: {
+    detected: number;
+    configured: number;
+  };
+  skills: {
+    detected: number;
+    installed: number;
+    managed: number;
+    updatesAvailable: number;
+  };
+}
+
+export interface DoctorRemoteDiagnostics {
+  configuredCount: number;
+  status: 'not_configured' | 'not_probed_local_only' | 'config_unavailable';
+  credentials: 'not_configured' | 'unverified';
+}
+
 export interface DoctorReport {
   manifestInstalled: boolean;
   manifestPath: string;
@@ -117,6 +265,7 @@ export interface DoctorReport {
   defaultExtensionId: string | null;
   defaultExtensionIdSource: string;
   daemonReachable: boolean;
+  healthAvailable: boolean;
   extensionConnected: boolean;
   accessEnabled: boolean;
   enabledWindowId: number | null;
@@ -130,6 +279,17 @@ export interface DoctorReport {
   issues: string[];
   nextSteps: string[];
   browserManifests: BrowserManifestStatus[];
+  transport: DoctorTransportDiagnostics;
+  connections: DoctorConnectionDiagnostics;
+  protocol: DoctorProtocolDiagnostics;
+  debugger: DoctorDebuggerDiagnostics;
+  recovery: DoctorRecoveryDiagnostics;
+  metrics: DoctorDaemonMetrics | null;
+  recentEvents: DoctorRecentEvent[];
+  recentCauses: DoctorRecentEvent['cause'][];
+  setup: DoctorSetupSummary | null;
+  remoteDestinations: DoctorRemoteDiagnostics;
+  diagnosticFailures: string[];
 }
 
 export interface DoctorReportOptions {
@@ -145,6 +305,14 @@ export interface DoctorReportOptions {
   checkNativeHostManifestHealth?: (
     browserManifests: BrowserManifestStatus[]
   ) => Promise<NativeHostManifestIssue[]>;
+  readInstalledExtensionIds?: (browserManifests: BrowserManifestStatus[]) => Promise<string[]>;
+  collectSetupStatus?: () => Promise<SetupStatus>;
+  readRemoteConfig?: () => Promise<{
+    remotes: Array<{ id: string; host: string; port: number; token: string }>;
+  }>;
+  getLocalTransport?: () => BridgeTransport;
+  readProxyConfig?: () => { enabled: boolean } | null;
+  includeSetupStatus?: boolean;
 }
 
 export type BridgeClientRequest = (options: {
@@ -154,8 +322,3 @@ export type BridgeClientRequest = (options: {
   meta?: BridgeMeta;
   timeoutMs?: number;
 }) => Promise<BridgeResponse>;
-
-export interface ScreenshotResult {
-  image: string;
-  rect: Record<string, unknown>;
-}

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

@@ -5,7 +5,7 @@ export const MCP_SERVER_INSTRUCTIONS = [
   '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.',
   'Prefer Browser Bridge MCP tools over shelling out to bbx. Use bbx only for explicit CLI setup, doctor, logs, or raw debugging requests.',
   'Start with browser_call method health.ping. If window access is disabled, call browser_call method access.request once, ask the user to click Enable in the Browser Bridge popup or side panel, then retry once.',
-  'Use structured reads first through browser_call: page.get_state, dom.query, page.get_text, styles.get_computed, or layout.get_box_model. Use browser_batch only for parallel reads; run mutations sequentially and keep limits tight before widening.',
+  'Use structured reads first through browser_call: page.get_state, dom.query, page.get_text, page.extract_content, styles.get_computed, or layout.get_box_model. Prefer semantic extraction for articles and documentation. Use browser_batch only for parallel reads; run mutations sequentially and keep limits tight before widening.',
   'Reuse elementRef values returned by DOM tools. Use attribute allowlists for focused DOM reads.',
   '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.',

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

@@ -22,23 +22,40 @@ export const CAPTURE_ACTIONS = {
   element: {
     ref: true,
     method: 'screenshot.capture_element',
-    params: (_, r) => ({ elementRef: r }),
+    params: (a, r) => ({
+      elementRef: r,
+      ...(a.format ? { format: a.format } : {}),
+      ...(typeof a.quality === 'number' ? { quality: a.quality } : {}),
+      delivery: a.delivery ?? 'auto',
+      ...(typeof a.scale === 'number' ? { scale: a.scale } : {}),
+    }),
   },
   region: {
     ref: false,
     method: 'screenshot.capture_region',
-    params: (a) => /** @type {Record<string, unknown>} */ (a.rect || {}),
+    params: (a) => ({
+      .../** @type {Record<string, unknown>} */ (a.rect || {}),
+      ...(a.format ? { format: a.format } : {}),
+      ...(typeof a.quality === 'number' ? { quality: a.quality } : {}),
+      delivery: a.delivery ?? 'auto',
+      ...(typeof a.scale === 'number' ? { scale: a.scale } : {}),
+    }),
   },
   full_page: {
     ref: false,
     method: 'screenshot.capture_full_page',
-    params: () => ({}),
+    params: (a) => ({
+      ...(a.format ? { format: a.format } : {}),
+      ...(typeof a.quality === 'number' ? { quality: a.quality } : {}),
+      delivery: a.delivery ?? 'auto',
+      ...(typeof a.scale === 'number' ? { scale: a.scale } : {}),
+    }),
   },
   cdp_document: { ref: false, method: 'cdp.get_document', params: () => ({}) },
   cdp_dom_snapshot: {
     ref: false,
     method: 'cdp.get_dom_snapshot',
-    params: () => ({}),
+    params: (a) => ({ computedStyles: a.computedStyles }),
   },
   cdp_box_model: {
     ref: false,
@@ -82,7 +99,7 @@ function isValidCaptureRegion(rect) {
 }
 
 /**
- * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, nodeId?: number, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, format?: 'png' | 'jpeg' | 'webp', quality?: number, delivery?: 'auto' | 'inline' | 'artifact', scale?: number, nodeId?: number, computedStyles?: string[], tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleCaptureTool(args) {
@@ -130,6 +147,27 @@ export async function handleCaptureTool(args) {
  */
 export function createScreenshotResult(response, method) {
   const result = toRecord(response.result);
+  if (result.delivery === 'artifact') {
+    const artifact = toRecord(result.artifact);
+    if (typeof artifact.artifactId !== 'string' || typeof artifact.byteLength !== 'number') {
+      return summarizeToolError(new Error(`${method} returned invalid artifact metadata.`));
+    }
+    return createToolResult(
+      `Captured screenshot artifact (${artifact.byteLength} bytes, expires ${artifact.expiresAt ?? 'soon'}).`,
+      {
+        ok: true,
+        method,
+        delivery: 'artifact',
+        artifact,
+        mimeType: result.mimeType,
+        byteLength: result.byteLength,
+        dimensions: result.dimensions,
+        rect: boundedRect(result.rect),
+        complete: result.complete === true,
+        clipped: result.clipped === true,
+      }
+    );
+  }
   if (typeof result.image !== 'string') {
     return summarizeToolError(new Error(`${method} returned no image data.`));
   }
@@ -148,6 +186,9 @@ export function createScreenshotResult(response, method) {
       mimeType: image.mimeType,
       byteLength: image.byteLength,
       ...(rect ? { rect } : {}),
+      format: result.format ?? image.mimeType.replace('image/', ''),
+      complete: result.complete === true,
+      clipped: result.clipped === true,
     },
     false,
     [{ type: 'image', data: image.data, mimeType: image.mimeType }]
@@ -294,7 +335,20 @@ function createInputTarget(elementRef, selector) {
 }
 
 /**
- * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, text?: string, value?: string, mode?: 'auto' | 'setter' | 'keystrokes', 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, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * Avoid changing legacy handler payloads when new options are omitted.
+ *
+ * @param {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean }} args
+ * @returns {{ executionMode?: 'dom' | 'cdp', recoverStale?: boolean }}
+ */
+function createInputOptions(args) {
+  return {
+    ...(args.executionMode ? { executionMode: args.executionMode } : {}),
+    ...(typeof args.recoverStale === 'boolean' ? { recoverStale: args.recoverStale } : {}),
+  };
+}
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, text?: string, value?: string, mode?: 'auto' | 'setter' | 'keystrokes', executionMode?: 'dom' | 'cdp', recoverStale?: boolean, 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, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleInputTool(args) {
@@ -337,6 +391,7 @@ export async function handleInputTool(args) {
               button: args.button,
               clickCount: args.clickCount,
               modifiers: args.modifiers,
+              ...createInputOptions(args),
             },
             {
               tabId: requestedTabId,
@@ -352,6 +407,7 @@ export async function handleInputTool(args) {
             'input.focus',
             {
               target: elementTarget(),
+              ...createInputOptions(args),
             },
             {
               tabId: requestedTabId,
@@ -371,6 +427,7 @@ export async function handleInputTool(args) {
               clear: args.clear,
               submit: args.submit,
               modifiers: args.modifiers,
+              ...createInputOptions(args),
             },
             {
               tabId: requestedTabId,
@@ -388,6 +445,7 @@ export async function handleInputTool(args) {
               target: elementTarget(),
               value: args.value,
               mode: args.mode,
+              ...createInputOptions(args),
             },
             {
               tabId: requestedTabId,
@@ -406,6 +464,7 @@ export async function handleInputTool(args) {
               target,
               key: args.key,
               modifiers: args.modifiers,
+              ...createInputOptions(args),
             },
             {
               tabId: requestedTabId,
@@ -439,6 +498,7 @@ export async function handleInputTool(args) {
             {
               target: elementTarget(),
               checked: args.checked,
+              ...createInputOptions(args),
             },
             {
               tabId: requestedTabId,
@@ -457,6 +517,7 @@ export async function handleInputTool(args) {
               values: args.values,
               labels: args.labels,
               indexes: args.indexes,
+              ...createInputOptions(args),
             },
             {
               tabId: requestedTabId,
@@ -474,6 +535,7 @@ export async function handleInputTool(args) {
               target: elementTarget(),
               duration: args.duration,
               modifiers: args.modifiers,
+              ...createInputOptions(args),
             },
             {
               tabId: requestedTabId,
@@ -502,6 +564,7 @@ export async function handleInputTool(args) {
               destination,
               offsetX: args.offsetX,
               offsetY: args.offsetY,
+              ...createInputOptions(args),
             },
             {
               tabId: requestedTabId,

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

@@ -15,6 +15,32 @@ import {
 
 /** @type {Record<string, ToolAction>} */
 export const DOM_ACTIONS = {
+  baseline_create: {
+    ref: false,
+    method: 'dom.baseline.create',
+    params: (a) => ({
+      selector: a.selector,
+      maxNodes: a.maxNodes,
+      maxDepth: a.maxDepth,
+      textBudget: a.textBudget,
+      attributeAllowlist: a.attributeAllowlist,
+    }),
+  },
+  baseline_compare: {
+    ref: false,
+    method: 'dom.baseline.compare',
+    params: (a) => ({ baselineId: a.baselineId, maxChanges: a.maxChanges }),
+  },
+  baseline_describe: {
+    ref: false,
+    method: 'dom.baseline.describe',
+    params: (a) => ({ baselineId: a.baselineId }),
+  },
+  baseline_release: {
+    ref: false,
+    method: 'dom.baseline.release',
+    params: (a) => ({ baselineId: a.baselineId }),
+  },
   query: {
     ref: false,
     method: 'dom.query',
@@ -85,12 +111,18 @@ export const DOM_ACTIONS = {
   accessibility_tree: {
     ref: false,
     method: 'dom.get_accessibility_tree',
-    params: (a) => ({ maxNodes: a.maxNodes, maxDepth: a.maxDepth }),
+    params: (a) => ({
+      selector: a.selector,
+      maxNodes: a.maxNodes,
+      maxDepth: a.maxDepth,
+      compact: a.compact,
+      interactiveOnly: a.interactiveOnly,
+    }),
   },
 };
 
 /**
- * @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
+ * @param {{ action: string, baselineId?: string, maxChanges?: number, selector?: string, elementRef?: string, withinRef?: string, maxNodes?: number, maxDepth?: number, compact?: boolean, interactiveOnly?: boolean, 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, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleDomTool(args) {
@@ -103,7 +135,17 @@ export async function handleDomTool(args) {
   if (args.action === 'find_role' && !hasText(args.role)) {
     return summarizeToolError('role is required for dom.find_by_role.');
   }
-  if (args.action === 'query' || args.action === 'accessibility_tree') {
+  if (
+    ['baseline_compare', 'baseline_describe', 'baseline_release'].includes(args.action) &&
+    !hasText(args.baselineId)
+  ) {
+    return summarizeToolError('baselineId is required for this DOM baseline action.');
+  }
+  if (
+    args.action === 'query' ||
+    args.action === 'accessibility_tree' ||
+    args.action === 'baseline_create'
+  ) {
     const inferred =
       args.action === 'accessibility_tree' ? 'normal' : inferBudgetFromSelector(args);
     const withBudget = inferred ? { ...args, budgetPreset: args.budgetPreset ?? inferred } : args;
@@ -112,6 +154,18 @@ export async function handleDomTool(args) {
   if (args.action === 'text') {
     return dispatchToolAction(DOM_ACTIONS, applyTextBudgetPreset(args), 'DOM');
   }
+  if (args.action === 'baseline_compare') {
+    const byPreset = { quick: 10, normal: 50, deep: 100 };
+    return dispatchToolAction(
+      DOM_ACTIONS,
+      {
+        ...args,
+        maxChanges:
+          args.maxChanges ?? (args.budgetPreset ? byPreset[args.budgetPreset] : undefined),
+      },
+      'DOM'
+    );
+  }
   if (args.action === 'html') {
     return dispatchToolAction(DOM_ACTIONS, applyHtmlBudgetPreset(args), 'DOM');
   }
@@ -183,11 +237,14 @@ export const PATCH_ACTIONS = {
         removeAttribute: 'remove_attribute',
         addClass: 'add_class',
         removeClass: 'remove_class',
+        toggleClass: 'toggle_class',
         setTextContent: 'set_text',
       };
       const normalizedOperation = opMap[operation] || operation;
       const value =
-        normalizedOperation === 'add_class' || normalizedOperation === 'remove_class'
+        normalizedOperation === 'add_class' ||
+        normalizedOperation === 'remove_class' ||
+        normalizedOperation === 'toggle_class'
           ? (a.value ?? a.name)
           : a.value;
       return {

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

@@ -32,7 +32,8 @@ export async function handleTabsTool(args) {
         let client = null;
         try {
           client = await createBridgeClientForDestination(
-            destination.local ? null : destination.id
+            destination.local ? null : destination.id,
+            { checkProtocolOnConnect: false }
           );
           await client.connect();
           const response = await requestBridgeWithRetry(