@browserbridge/bbx 1.7.8 → 1.8.0

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

@@ -169,6 +169,10 @@ export function createBridgeMcpServer() {
       description: 'Ping the bridge to verify daemon and extension connectivity.',
       inputSchema: {
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+        intent: z
+          .enum(['inspect', 'interact', 'capture', 'navigate', 'debugger', 'general'])
+          .optional()
+          .describe('Reported operation family shown in the access prompt (defaults to general).'),
       },
     },
     handleHealthTool
@@ -206,7 +210,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser DOM',
       description:
-        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed - use query/find first.',
+        'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed and depth-limited - use query/find first.',
       inputSchema: {
         action: z
           .enum([
@@ -230,7 +234,9 @@ export function createBridgeMcpServer() {
         selector: z
           .string()
           .optional()
-          .describe('CSS selector (used if no elementRef; resolves to first match)'),
+          .describe(
+            'CSS selector (used if no elementRef; accessibility_tree requires exactly one match)'
+          ),
         elementRef: z
           .string()
           .optional()
@@ -248,6 +254,16 @@ export function createBridgeMcpServer() {
           .positive()
           .optional()
           .describe(`Maximum tree depth (default: ${DEFAULT_MAX_DEPTH})`),
+        compact: z
+          .boolean()
+          .optional()
+          .describe('Remove ignored, empty, and decorative AX nodes while preserving descendants'),
+        interactiveOnly: z
+          .boolean()
+          .optional()
+          .describe(
+            'Return semantically interactive AX nodes; actionable state is reported separately'
+          ),
         textBudget: z
           .number()
           .int()
@@ -327,7 +343,9 @@ export function createBridgeMcpServer() {
         properties: z
           .array(z.string())
           .optional()
-          .describe('Style properties to fetch (omitting returns all - expensive)'),
+          .describe(
+            'Style properties to fetch (omitting returns display, position, width, height, and color)'
+          ),
         x: z
           .number()
           .nonnegative()
@@ -348,16 +366,18 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Page State',
       description:
-        'Read page-level data: state (URL/title), evaluate (JS), console, storage, text, network, or performance. For element-level reads, use browser_dom. evaluate and performance are debugger-backed - prefer lighter reads first.',
+        'Read page-level data, wait for load/URL conditions, or explicitly inspect/handle JavaScript dialogs. For element-level reads, use browser_dom. evaluate, performance, handle_dialog, and source=cdp network capture are debugger-backed.',
       inputSchema: {
         action: z
           .enum([
             'state',
             'evaluate',
             'console',
+            'handle_dialog',
             'wait_for_load',
             'storage',
             'text',
+            'extract_content',
             'network',
             'performance',
           ])
@@ -373,6 +393,23 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('JavaScript expression to evaluate (for evaluate action)'),
         awaitPromise: z.boolean().optional().describe('Await returned promises (default: false)'),
+        dialogAction: z
+          .enum(['inspect', 'accept', 'dismiss'])
+          .optional()
+          .describe('Dialog operation on the current dialog (default: inspect)'),
+        promptText: z
+          .string()
+          .max(10_000)
+          .optional()
+          .describe('Prompt response text; only valid when dialogAction is accept'),
+        expectedDialogId: z
+          .string()
+          .min(1)
+          .max(128)
+          .optional()
+          .describe(
+            'Optional stale-decision check immediately before CDP dispatch; Chrome cannot atomically bind the action to this identifier'
+          ),
         timeoutMs: z
           .number()
           .int()
@@ -412,7 +449,43 @@ export function createBridgeMcpServer() {
           .positive()
           .optional()
           .describe(`Max chars for page text (default: ${DEFAULT_PAGE_TEXT_BUDGET})`),
+        format: z
+          .enum(['text', 'markdown'])
+          .optional()
+          .describe('Semantic content format (default: text)'),
+        selector: z.string().optional().describe('Scope semantic extraction to one CSS selector'),
+        includeMetadata: z
+          .boolean()
+          .optional()
+          .describe('Include bounded article metadata (default: true)'),
+        consistency: z
+          .enum(['best_effort', 'settled'])
+          .optional()
+          .describe('Optionally wait for a short mutation-quiet interval'),
+        settleTimeoutMs: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('Maximum semantic extraction settlement wait (default: 2000)'),
         urlPattern: z.string().optional().describe('Filter network entries by URL pattern'),
+        source: z
+          .enum(['fetch-xhr', 'cdp'])
+          .optional()
+          .describe('Network source (default: fetch-xhr; cdp captures all resource types)'),
+        capture: z
+          .enum(['read', 'start', 'clear', 'stop'])
+          .optional()
+          .describe('Explicit CDP capture lifecycle action (default: read)'),
+        waitForLoad: z
+          .boolean()
+          .optional()
+          .describe('For wait_for_load, also require tab status complete (default: true)'),
+        url: z.string().optional().describe('URL condition for wait_for_load'),
+        urlMatch: z
+          .enum(['exact', 'contains', 'regex'])
+          .optional()
+          .describe('URL match mode for wait_for_load (default: exact)'),
       },
     },
     handlePageTool
@@ -467,7 +540,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Input',
       description:
-        'Simulate user input: click, focus, type, press keys, CDP key events, set checked, select options, hover, drag, or scroll into view. Reuse elementRef from prior queries.',
+        'Dispatch browser input. Targeted click, focus, type, fill, press_key, set_checked, select_option, hover, and drag actions perform actionability checks and report resolution/execution metadata. cdp_press_key and scroll_into_view use separate contracts. Reuse elementRef values and verify application state after mutations.',
       inputSchema: {
         action: z
           .enum([
@@ -512,6 +585,18 @@ export function createBridgeMcpServer() {
           .enum(['auto', 'setter', 'keystrokes'])
           .optional()
           .describe('Fill strategy (default: auto)'),
+        executionMode: z
+          .enum(['dom', 'cdp'])
+          .optional()
+          .describe(
+            'Input execution path (default: dom; CDP supports click, hover, drag, type, fill)'
+          ),
+        recoverStale: z
+          .boolean()
+          .optional()
+          .describe(
+            'Strict bounded same-document stale elementRef recovery for targeted input actions (default: false; not used by cdp_press_key or scroll_into_view)'
+          ),
         clear: z.boolean().optional().describe('Clear field before typing (default: false)'),
         submit: z.boolean().optional().describe('Press Enter after typing (default: false)'),
         key: z
@@ -567,7 +652,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Patch',
       description:
-        'Apply or rollback reversible style and DOM patches for live prototyping before editing source. Set verify=true to get computed results inline without a follow-up query.',
+        'Apply or rollback document-local style and DOM patches for live prototyping before editing source. commit_baseline keeps current changes but discards rollback history. Set verify=true to get computed results inline.',
       inputSchema: {
         action: z
           .enum(['apply_styles', 'apply_dom', 'list', 'rollback', 'commit_baseline'])
@@ -652,6 +737,17 @@ export function createBridgeMcpServer() {
           })
           .optional()
           .describe('Viewport region for region action (keep crop tight)'),
+        format: z
+          .enum(['png', 'jpeg', 'webp'])
+          .optional()
+          .describe('Screenshot encoding (default: png)'),
+        quality: z
+          .number()
+          .int()
+          .min(0)
+          .max(100)
+          .optional()
+          .describe('JPEG/WebP quality from 0 to 100; ignored for PNG'),
       },
     },
     handleCaptureTool

package/packages/native-host/src/daemon.js

@@ -53,7 +53,7 @@ setProtocolPackageVersion(DAEMON_VERSION);
 /** @typedef {import('./config.js').BridgeTransport} BridgeTransport */
 /** @typedef {import('./daemon-logger.js').DaemonLoggerLike} DaemonLoggerLike */
 /** @typedef {'agent' | 'extension'} SocketRole */
-/** @typedef {import('node:net').Socket & { readonly __role?: SocketRole, __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __accessEnabled?: boolean, __lastActiveAt?: number }} ClientSocket */
+/** @typedef {import('node:net').Socket & { readonly __role?: SocketRole, __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __browserExtensionId?: string, __accessEnabled?: boolean, __lastActiveAt?: number }} ClientSocket */
 /** @typedef {{ socket: ClientSocket, timeoutId: NodeJS.Timeout, source?: string, method?: string, protocolVersion?: string, targets: Set<ClientSocket>, lastErrorResponse?: import('../../protocol/src/types.js').BridgeResponse }} PendingEntry */
 /**
  * @typedef {{
@@ -85,6 +85,151 @@ function compareProtocolVersions(left, right) {
   return 0;
 }
 
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function normalizeBrowserExtensionId(value) {
+  return typeof value === 'string' && /^[a-p]{32}$/u.test(value) ? value : undefined;
+}
+
+const HEALTH_DIAGNOSTIC_COUNT_LIMIT = 10_000;
+const HEALTH_ACCESS_REASONS = new Set([
+  'enabled',
+  'access_disabled',
+  'enabled_window_missing',
+  'no_routable_active_tab',
+  'restricted_page',
+]);
+const HEALTH_DEBUGGER_STATUSES = new Set(['idle', 'active']);
+const HEALTH_DEBUGGER_REASONS = new Set([
+  'debugger_conflict',
+  'debugger_detached',
+  'debugger_replaced',
+  'debugger_canceled',
+  'target_closed',
+]);
+const HEALTH_CAPTURE_STATES = new Set(['stopped', 'armed', 'active', 'stop_failed']);
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown> | null}
+ */
+function asHealthRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? /** @type {Record<string, unknown>} */ (value)
+    : null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function normalizeHealthCount(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.min(HEALTH_DIAGNOSTIC_COUNT_LIMIT, Math.trunc(value))
+    : undefined;
+}
+
+/**
+ * Copy only extension-owned health fields into the daemon response. This keeps
+ * transport, connectivity, daemon identity, and daemon protocol negotiation
+ * authoritative even if an extension response is malformed or hostile.
+ *
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+function normalizeExtensionHealthResult(value) {
+  const result = asHealthRecord(value);
+  if (!result) return {};
+
+  /** @type {Record<string, unknown>} */
+  const normalized = {};
+  if (result.extension === 'ok') normalized.extension = 'ok';
+
+  const access = asHealthRecord(result.access);
+  if (access) {
+    /** @type {Record<string, unknown>} */
+    const normalizedAccess = {};
+    if (typeof access.enabled === 'boolean') normalizedAccess.enabled = access.enabled;
+    if (
+      access.windowId === null ||
+      (Number.isSafeInteger(access.windowId) && Number(access.windowId) > 0)
+    ) {
+      normalizedAccess.windowId = access.windowId;
+    }
+    if (
+      access.routeTabId === null ||
+      (Number.isSafeInteger(access.routeTabId) && Number(access.routeTabId) > 0)
+    ) {
+      normalizedAccess.routeTabId = access.routeTabId;
+    }
+    if (typeof access.routeReady === 'boolean') normalizedAccess.routeReady = access.routeReady;
+    if (typeof access.reason === 'string' && HEALTH_ACCESS_REASONS.has(access.reason)) {
+      normalizedAccess.reason = access.reason;
+    }
+    normalized.access = normalizedAccess;
+  }
+
+  const debuggerDiagnostics = asHealthRecord(result.debugger);
+  if (debuggerDiagnostics) {
+    /** @type {Record<string, unknown>} */
+    const normalizedDebugger = {};
+    if (
+      typeof debuggerDiagnostics.status === 'string' &&
+      HEALTH_DEBUGGER_STATUSES.has(debuggerDiagnostics.status)
+    ) {
+      normalizedDebugger.status = debuggerDiagnostics.status;
+    }
+    for (const key of ['attachedTabCount', 'heldTabCount', 'pendingTabCount']) {
+      const count = normalizeHealthCount(debuggerDiagnostics[key]);
+      if (count !== undefined) normalizedDebugger[key] = count;
+    }
+    if (
+      typeof debuggerDiagnostics.recentReason === 'string' &&
+      HEALTH_DEBUGGER_REASONS.has(debuggerDiagnostics.recentReason)
+    ) {
+      normalizedDebugger.recentReason = debuggerDiagnostics.recentReason;
+    } else if (debuggerDiagnostics.recentReason === null) {
+      normalizedDebugger.recentReason = null;
+    }
+    normalized.debugger = normalizedDebugger;
+  }
+
+  const capture = asHealthRecord(result.capture);
+  if (capture) {
+    /** @type {Record<string, unknown>} */
+    const normalizedCapture = {};
+    if (typeof capture.state === 'string' && HEALTH_CAPTURE_STATES.has(capture.state)) {
+      normalizedCapture.state = capture.state;
+    }
+    for (const key of [
+      'activeTabCount',
+      'ownershipCount',
+      'inflightCount',
+      'interceptionActiveTabCount',
+      'interceptionRuleCount',
+    ]) {
+      const count = normalizeHealthCount(capture[key]);
+      if (count !== undefined) normalizedCapture[key] = count;
+    }
+    normalized.capture = normalizedCapture;
+  }
+
+  const extensionSupportedVersions = Array.isArray(result.supported_versions)
+    ? result.supported_versions
+        .filter(
+          (version) =>
+            typeof version === 'string' &&
+            version.length <= 32 &&
+            /^\d+\.\d+(?:\.\d+)?(?:[-+][A-Za-z0-9.-]+)?$/u.test(version)
+        )
+        .slice(0, 10)
+    : [];
+  normalized.extension_supported_versions = extensionSupportedVersions;
+  return normalized;
+}
+
 /**
  * @param {string | undefined} requestedVersion
  * @returns {{ supported_versions: readonly string[], deprecated_since?: string, migration_hint?: string }}
@@ -140,6 +285,7 @@ export function isWindowsNamedPipePath(socketPath) {
  *   response?: import('../../protocol/src/types.js').BridgeResponse,
  *   browserName?: string,
  *   profileLabel?: string,
+ *   browserExtensionId?: string,
  *   accessEnabled?: boolean,
  *   authToken?: string,
  *   at?: number
@@ -192,7 +338,7 @@ export class BridgeDaemon {
     this.pendingTimeoutMs = DEFAULT_DAEMON_PENDING_TIMEOUT_MS;
     /** @type {Record<string, unknown>[]} */
     this.recentLog = [];
-    /** @type {Array<{ extensionId: string, browserName: string | null, profileLabel: string | null, accessEnabled: boolean }> | null} */
+    /** @type {Array<{ extensionId: string, browserExtensionId: string | null, browserName: string | null, profileLabel: string | null, accessEnabled: boolean }> | null} */
     this.connectedExtensionsCache = null;
     /** @type {Promise<void> | null} */
     this.stopPromise = null;
@@ -302,7 +448,7 @@ export class BridgeDaemon {
   }
 
   /**
-   * @returns {Array<{ extensionId: string, browserName: string | null, profileLabel: string | null, accessEnabled: boolean }>}
+   * @returns {Array<{ extensionId: string, browserExtensionId: string | null, browserName: string | null, profileLabel: string | null, accessEnabled: boolean }>}
    */
   getConnectedExtensionsSnapshot() {
     if (this.connectedExtensionsCache) {
@@ -312,6 +458,7 @@ export class BridgeDaemon {
     this.connectedExtensionsCache = Array.from(this.extensionSockets.entries()).map(
       ([extensionId, extSocket]) => ({
         extensionId,
+        browserExtensionId: extSocket.__browserExtensionId ?? null,
         browserName: extSocket.__browserName ?? null,
         profileLabel: extSocket.__profileLabel ?? null,
         accessEnabled: extSocket.__accessEnabled ?? false,
@@ -373,6 +520,7 @@ export class BridgeDaemon {
         typeof message.browserName === 'string' ? message.browserName : undefined;
       socket.__profileLabel =
         typeof message.profileLabel === 'string' ? message.profileLabel : undefined;
+      socket.__browserExtensionId = normalizeBrowserExtensionId(message.browserExtensionId);
       socket.__lastActiveAt = Date.now();
       this.extensionSockets.set(extensionId, socket);
       this.invalidateConnectedExtensionsCache();
@@ -975,6 +1123,11 @@ export class BridgeDaemon {
       changed = changed || socket.__profileLabel !== message.profileLabel;
       socket.__profileLabel = message.profileLabel;
     }
+    if (typeof message.browserExtensionId === 'string') {
+      const browserExtensionId = normalizeBrowserExtensionId(message.browserExtensionId);
+      changed = changed || socket.__browserExtensionId !== browserExtensionId;
+      socket.__browserExtensionId = browserExtensionId;
+    }
     if (changed) {
       this.invalidateConnectedExtensionsCache();
     }
@@ -1061,15 +1214,14 @@ export class BridgeDaemon {
                 socketPath: this.socketPath,
                 transport: formatBridgeTransport(this.transport),
                 connectedExtensions: this.getConnectedExtensionsSnapshot(),
+                ...normalizeExtensionHealthResult(responseMessage.result),
                 ...getVersionNegotiationPayload(pending.protocolVersion),
-                .../** @type {Record<string, unknown>} */ (responseMessage.result),
                 daemonVersion: DAEMON_VERSION,
                 daemon_supported_versions: getSupportedProtocolVersions(),
                 proxy: this.getProxyStatusPayload(),
               },
               {
-                ...responseMessage.meta,
-                method: responseMessage.meta?.method ?? pending.method,
+                method: pending.method,
               }
             )
           : responseMessage;

package/packages/native-host/src/native-host.js

@@ -28,7 +28,8 @@ import { createNativeMessageReader, createNativeMessageWriter, writeJsonLine } f
  * @typedef {{
  *   type?: string,
  *   browserName?: string,
- *   profileLabel?: string
+ *   profileLabel?: string,
+ *   browserExtensionId?: string
  * }} HostIdentityMessage
  */
 
@@ -238,6 +239,7 @@ export async function runNativeHost({
             type: 'extension.identity',
             browserName: message.browserName,
             profileLabel: message.profileLabel,
+            browserExtensionId: message.browserExtensionId,
           });
           return;
         }

package/packages/protocol/src/defaults.js

@@ -11,6 +11,9 @@ export const DEFAULT_MAX_NODES = 25;
 export const DEFAULT_MAX_DEPTH = 4;
 export const DEFAULT_TEXT_BUDGET = 600;
 export const DEFAULT_PAGE_TEXT_BUDGET = 8000;
+export const DEFAULT_EXTRACT_SETTLE_TIMEOUT_MS = 2000;
+export const MAX_EXTRACT_SETTLE_TIMEOUT_MS = 10_000;
+export const EXTRACT_SETTLE_QUIET_MS = 100;
 export const DEFAULT_WAIT_TIMEOUT_MS = 5000;
 export const DEFAULT_EVAL_TIMEOUT_MS = 5000;
 export const DEFAULT_NAV_TIMEOUT_MS = 15000;

package/packages/protocol/src/errors.js

@@ -6,6 +6,15 @@ export const ERROR_CODES = Object.freeze({
   ACCESS_DENIED: 'ACCESS_DENIED',
   TAB_MISMATCH: 'TAB_MISMATCH',
   ELEMENT_STALE: 'ELEMENT_STALE',
+  ELEMENT_AMBIGUOUS: 'ELEMENT_AMBIGUOUS',
+  ELEMENT_NOT_ACTIONABLE: 'ELEMENT_NOT_ACTIONABLE',
+  ELEMENT_OBSCURED: 'ELEMENT_OBSCURED',
+  ELEMENT_NOT_FOUND: 'ELEMENT_NOT_FOUND',
+  INPUT_UNSUPPORTED: 'INPUT_UNSUPPORTED',
+  INPUT_INVALID_TARGET: 'INPUT_INVALID_TARGET',
+  INPUT_FOCUS_CHANGED: 'INPUT_FOCUS_CHANGED',
+  DIALOG_NOT_OPEN: 'DIALOG_NOT_OPEN',
+  DIALOG_ACTION_CONFLICT: 'DIALOG_ACTION_CONFLICT',
   RESULT_TRUNCATED: 'RESULT_TRUNCATED',
   RATE_LIMITED: 'RATE_LIMITED',
   INTERNAL_ERROR: 'INTERNAL_ERROR',
@@ -32,7 +41,51 @@ export const ERROR_RECOVERY = Object.freeze({
   [ERROR_CODES.ELEMENT_STALE]: {
     retry: false,
     alternativeMethod: 'dom.query',
-    hint: 'Element was removed from the DOM. Re-query with the same selector to get a fresh elementRef.',
+    hint: 'Element was removed from the DOM. Re-query for a fresh elementRef, or retry an input once with recoverStale=true when the same page and a strong unique descriptor still apply.',
+  },
+  [ERROR_CODES.ELEMENT_AMBIGUOUS]: {
+    retry: false,
+    alternativeMethod: 'dom.query',
+    hint: 'Multiple candidates matched, candidates tied, or a bounded stale-recovery scan could not prove uniqueness. Re-query and use a more specific selector or fresh elementRef.',
+  },
+  [ERROR_CODES.ELEMENT_NOT_ACTIONABLE]: {
+    retry: false,
+    alternativeMethod: 'dom.describe',
+    hint: 'The target is hidden, disabled, inert, or has no rendered area. Inspect it and choose an actionable target.',
+  },
+  [ERROR_CODES.ELEMENT_OBSCURED]: {
+    retry: false,
+    alternativeMethod: 'layout.hit_test',
+    hint: 'Another element blocks the target point. Inspect the blocker or wait for the overlay to close.',
+  },
+  [ERROR_CODES.ELEMENT_NOT_FOUND]: {
+    retry: false,
+    alternativeMethod: 'dom.query',
+    hint: 'No element matched the target selector. Check or narrow the selector with dom.query.',
+  },
+  [ERROR_CODES.INPUT_UNSUPPORTED]: {
+    retry: false,
+    hint: 'The requested execution mode does not support this input operation. Use executionMode=dom or choose a CDP-supported input method.',
+  },
+  [ERROR_CODES.INPUT_INVALID_TARGET]: {
+    retry: false,
+    alternativeMethod: 'dom.describe',
+    hint: 'The target is not compatible with this input operation or the requested option does not exist. Inspect the target and choose the appropriate control.',
+  },
+  [ERROR_CODES.INPUT_FOCUS_CHANGED]: {
+    retry: false,
+    alternativeMethod: 'dom.describe',
+    hint: 'Focus moved away from the resolved editable target before native text dispatch. Inspect focus handlers or target the control that retained focus.',
+  },
+  [ERROR_CODES.DIALOG_NOT_OPEN]: {
+    retry: false,
+    alternativeMethod: 'page.handle_dialog',
+    hint: 'No JavaScript dialog is currently observable. Inspect or trigger the dialog before trying another explicit action.',
+  },
+  [ERROR_CODES.DIALOG_ACTION_CONFLICT]: {
+    retry: false,
+    alternativeMethod: 'page.handle_dialog',
+    hint: 'The observed dialog changed before or during CDP dispatch. Do not repeat the action automatically; inspect the current dialog state first.',
   },
   [ERROR_CODES.TAB_MISMATCH]: {
     retry: false,