@browserbridge/bbx 1.8.0 → 1.10.0

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

@@ -28,9 +28,14 @@ import {
   getBridgeOperationTimeoutMs,
   getProtocolVersion,
   MAX_CLIENT_REQUEST_TIMEOUT_MS,
+  normalizeRecoveryTelemetrySummary,
+  RECOVERY_EVENT_KINDS,
+  sanitizeIncidentalPath,
+  sanitizeIncidentalText,
 } from '../../protocol/src/index.js';
-import { methodNeedsTab } from './cli-helpers.js';
+import { isElementRef, methodNeedsTab } from './cli-helpers.js';
 import { BridgeClient } from './client.js';
+import { applyConfiguredAutoUpdate } from './config.js';
 import { readRemoteConfig } from './remotes.js';
 import { collectSetupStatus } from './setup-status.js';
 
@@ -101,7 +106,7 @@ export async function ensureClientConnected(client) {
  * @param {BridgeClient} client
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} [params={}]
- * @param {{ tabId?: number | null, source?: BridgeRequestSource, tokenBudget?: number | null }} [options]
+ * @param {{ tabId?: number | null, source?: BridgeRequestSource, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} [options]
  * @returns {Promise<BridgeResponse>}
  */
 export async function requestBridge(client, method, params = {}, options = {}) {
@@ -122,7 +127,7 @@ export async function requestBridge(client, method, params = {}, options = {}) {
     method,
     params,
     tabId: methodNeedsTab(method) ? (options.tabId ?? null) : null,
-    meta: withRequestMeta(options.source, options.tokenBudget),
+    meta: withRequestMeta(options.source, options.tokenBudget, options.automaticRetry),
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
   });
 }
@@ -135,7 +140,7 @@ export async function requestBridge(client, method, params = {}, options = {}) {
  * @returns {Promise<string>}
  */
 export async function resolveRef(client, refOrSelector, tabId = null, source) {
-  if (refOrSelector.startsWith('el_')) {
+  if (isElementRef(refOrSelector)) {
     return refOrSelector;
   }
 
@@ -164,9 +169,10 @@ export async function resolveRef(client, refOrSelector, tabId = null, source) {
 /**
  * @param {BridgeRequestSource | undefined} source
  * @param {number | null | undefined} tokenBudget
+ * @param {'mcp_second_attempt' | undefined} automaticRetry
  * @returns {BridgeMeta}
  */
-function withRequestMeta(source, tokenBudget) {
+function withRequestMeta(source, tokenBudget, automaticRetry) {
   /** @type {BridgeMeta} */
   const meta = {};
   if (source) {
@@ -175,6 +181,9 @@ function withRequestMeta(source, tokenBudget) {
   if (typeof tokenBudget === 'number' && Number.isFinite(tokenBudget)) {
     meta.token_budget = tokenBudget;
   }
+  if (automaticRetry === 'mcp_second_attempt') {
+    meta.automatic_retry = { attempt: 2, reason: 'retryable_error' };
+  }
   return meta;
 }
 
@@ -185,7 +194,7 @@ function withRequestMeta(source, tokenBudget) {
  * @returns {Promise<T>}
  */
 export async function withBridgeClient(callback, options) {
-  const client = new BridgeClient(options);
+  const client = new BridgeClient(await applyConfiguredAutoUpdate(options));
   await ensureClientConnected(client);
   try {
     return await callback(client);
@@ -661,6 +670,30 @@ function summarizeMetrics(value) {
     requestsProcessed: boundedCount(metrics.requestsProcessed),
     requestsFailed: boundedCount(metrics.requestsFailed),
     avgResponseTimeMs: boundedCount(metrics.avgResponseTimeMs),
+    recovery: normalizeRecoveryTelemetrySummary(metrics.recovery, 'daemon'),
+  };
+}
+
+/**
+ * @param {Record<string, unknown> | null} health
+ * @param {import('./types.js').DoctorDaemonMetrics | null} metrics
+ * @returns {import('./types.js').DoctorRecoveryDiagnostics}
+ */
+function summarizeRecovery(health, metrics) {
+  const recovery = asRecord(health?.recovery);
+  const daemon = metrics?.recovery ?? normalizeRecoveryTelemetrySummary(recovery?.daemon, 'daemon');
+  const routedExtension = normalizeRecoveryTelemetrySummary(
+    recovery?.routedExtension,
+    'routedExtension'
+  );
+  return {
+    daemon,
+    routedExtension,
+    activeLoops: RECOVERY_EVENT_KINDS.filter(
+      (kind) =>
+        daemon?.events[kind].activeLoop === true ||
+        routedExtension?.events[kind].activeLoop === true
+    ),
   };
 }
 
@@ -947,6 +980,7 @@ export async function getDoctorReport(options = {}) {
     },
     protocol: summarizeProtocol(null, false),
     debugger: summarizeDebugger(null),
+    recovery: summarizeRecovery(null, null),
     metrics: null,
     recentEvents: [],
     recentCauses: [],
@@ -1105,6 +1139,10 @@ export async function getDoctorReport(options = {}) {
     ),
   ];
   report.debugger = summarizeDebugger(report.healthAvailable ? resolvedHealth : null);
+  report.recovery = summarizeRecovery(
+    report.healthAvailable ? resolvedHealth : null,
+    report.metrics
+  );
   if (report.debugger.recentReason && !report.recentCauses.includes(report.debugger.recentReason)) {
     report.recentCauses.push(report.debugger.recentReason);
   }
@@ -1243,5 +1281,59 @@ export async function getDoctorReport(options = {}) {
     );
   }
 
-  return report;
+  for (const loop of report.recovery.activeLoops) {
+    const issue = `${loop}_loop`;
+    if (!report.issues.includes(issue)) report.issues.push(issue);
+    if (loop === 'stale_ref_recovery') {
+      report.nextSteps.push(
+        'Stale-reference recovery is repeatedly failing. Re-query the target for a fresh elementRef and retry once without reusing old refs.'
+      );
+    } else if (
+      loop === 'debugger_reattach' &&
+      report.debugger.state !== 'conflict' &&
+      !report.recentCauses.includes('debugger_conflict')
+    ) {
+      report.nextSteps.push(
+        'Debugger reattachment is repeatedly failing. Keep the tab open, close competing debuggers, and retry one debugger-backed operation.'
+      );
+    } else if (loop === 'content_script_reinjection') {
+      report.nextSteps.push(
+        'Content-script reinjection is repeatedly failing. Reload the Browser Bridge extension and target page, then enable the window again.'
+      );
+    } else if (loop === 'native_host_reconnect' && !authenticationFailed) {
+      report.nextSteps.push(
+        'Native-host reconnects are repeatedly failing. Run `bbx restart`; for remote TCP proxy use, verify the endpoint and rotate stale credentials with `bbx proxy enable --rotate-token`.'
+      );
+    } else if (loop === 'automatic_mcp_retry') {
+      report.nextSteps.push(
+        'Automatic MCP retries are repeatedly failing. Stop the retry loop, resolve the reported bridge readiness issue, then retry the original read once.'
+      );
+    } else if (loop === 'request_outcome') {
+      report.nextSteps.push(
+        'Browser requests are repeatedly failing. Inspect the first typed bridge error, narrow the request or target as directed, and retry once after correcting that specific failure.'
+      );
+    }
+  }
+
+  return {
+    ...report,
+    manifestPath: sanitizeDoctorPath(report.manifestPath),
+    daemonLogPath: sanitizeDoctorPath(report.daemonLogPath),
+    unwritableBridgePaths: report.unwritableBridgePaths.map(sanitizeDoctorPath),
+    nativeHostManifestIssues: report.nativeHostManifestIssues.map((issue) => ({
+      ...issue,
+      manifestPath: sanitizeDoctorPath(issue.manifestPath),
+      message: sanitizeIncidentalText(issue.message),
+    })),
+    browserManifests: report.browserManifests.map((browser) => ({
+      ...browser,
+      manifestPath: sanitizeDoctorPath(browser.manifestPath),
+    })),
+    nextSteps: report.nextSteps.map((step) => sanitizeIncidentalText(step)),
+  };
+}
+
+/** @param {string} value */
+function sanitizeDoctorPath(value) {
+  return value ? sanitizeIncidentalPath(value) : '';
 }

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

@@ -4,6 +4,8 @@ import type {
   BridgeMethod,
   BridgeRequestSource,
   BridgeResponse,
+  RecoveryEventKind,
+  RecoveryTelemetrySummary,
   ScreenshotResult,
   SetupStatus,
 } from '../../protocol/src/types.js';
@@ -30,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 {
@@ -51,6 +73,8 @@ export interface SetupStatusOptions {
 
 export interface ProtocolHealthResult {
   extensionConnected?: boolean;
+  extensionVersion?: string;
+  daemonVersion?: string;
   supported_versions?: string[];
   extension_supported_versions?: string[];
   daemon_supported_versions?: string[];
@@ -91,6 +115,12 @@ export interface BridgeClientOptions {
   checkProtocolOnConnect?: boolean;
   restartDaemonOnVersionMismatch?: boolean;
   restartDaemonFn?: typeof restartBridgeDaemon;
+  updateNpmOnCompatibleVersion?: boolean;
+  exitProcessOnNpmUpdate?: boolean;
+  updateCompatibleNpmPackageFn?: (options: {
+    extensionVersion: string;
+    supportedVersions: readonly string[];
+  }) => Promise<NpmUpdateResult>;
   authToken?: string | null;
 }
 
@@ -182,6 +212,13 @@ export interface DoctorDaemonMetrics {
   requestsProcessed: number;
   requestsFailed: number;
   avgResponseTimeMs: number;
+  recovery: RecoveryTelemetrySummary | null;
+}
+
+export interface DoctorRecoveryDiagnostics {
+  daemon: RecoveryTelemetrySummary | null;
+  routedExtension: RecoveryTelemetrySummary | null;
+  activeLoops: RecoveryEventKind[];
 }
 
 export interface DoctorRecentEvent {
@@ -246,6 +283,7 @@ export interface DoctorReport {
   connections: DoctorConnectionDiagnostics;
   protocol: DoctorProtocolDiagnostics;
   debugger: DoctorDebuggerDiagnostics;
+  recovery: DoctorRecoveryDiagnostics;
   metrics: DoctorDaemonMetrics | null;
   recentEvents: DoctorRecentEvent[];
   recentCauses: DoctorRecentEvent['cause'][];

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

@@ -1,17 +1,48 @@
 // @ts-check
 
-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.',
+/**
+ * Guidance lines shared by the progressive tool surface.
+ *
+ * @type {readonly string[]}
+ */
+const SHARED_INSTRUCTIONS = Object.freeze([
   '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, 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.',
+  'Reuse elementRef values returned by DOM reads. 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.',
-  'Only use the specialized Browser Bridge MCP tools directly when the host has already allowed them or the user explicitly wants typed tool calls.',
+]);
+
+/**
+ * Workflow guidance appended after the tool-selection rules.
+ *
+ * @type {readonly string[]}
+ */
+const WORKFLOW_INSTRUCTIONS = Object.freeze([
   '',
   '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');
+]);
+
+const SERVER_HEADER =
+  "Browser Bridge MCP inspects and interacts with the user's real Chrome tab through a compact tool set.";
+
+const TOOL_RULES = Object.freeze([
+  'The common tools are available immediately. When a specialized typed tool is useful, call browser_toolset with its exact tool name; browser_call always reaches every bridge method without loading another tool.',
+  'Use browser_call method protocol.describe with method or group params to load unfamiliar signatures cheaply.',
+]);
+
+/**
+ * Build instructions for progressive tool discovery.
+ *
+ * @returns {string}
+ */
+export function getMcpServerInstructions() {
+  return [SERVER_HEADER, ...TOOL_RULES, ...SHARED_INSTRUCTIONS, ...WORKFLOW_INSTRUCTIONS].join(
+    '\n'
+  );
+}
+
+export const MCP_SERVER_INSTRUCTIONS = getMcpServerInstructions();

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

@@ -26,6 +26,8 @@ export const CAPTURE_ACTIONS = {
       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: {
@@ -35,6 +37,8 @@ export const CAPTURE_ACTIONS = {
       .../** @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: {
@@ -43,13 +47,15 @@ export const CAPTURE_ACTIONS = {
     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,
@@ -93,7 +99,7 @@ function isValidCaptureRegion(rect) {
 }
 
 /**
- * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, format?: 'png' | 'jpeg' | 'webp', quality?: number, 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) {
@@ -141,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'}). Read it in chunks with the browser_artifact tool (action "read", paging offset until nextOffset is null), then delete it with browser_artifact action "delete" when done.`,
+      {
+        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.`));
   }

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',
@@ -96,7 +122,7 @@ export const DOM_ACTIONS = {
 };
 
 /**
- * @param {{ action: string, 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, 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) {
@@ -109,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;
@@ -118,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');
   }
@@ -189,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 {