@browserbridge/bbx 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": false,
   "keywords": [
     "agent-tools",

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

@@ -613,16 +613,18 @@ async function main() {
     }
 
     if (command === 'screenshot') {
-      const [refOrSelector, outputPath] = rest;
-      if (!refOrSelector) throw new Error('Usage: screenshot <ref|selector> [path]');
-      const elementRef = await resolveRef(client, refOrSelector, null, REQUEST_SOURCE);
+      const parsed = extractTabFlag(rest);
+      const [refOrSelector, outputPath] = parsed.rest;
+      if (!refOrSelector)
+        throw new Error('Usage: screenshot [--tab <tabId>] <ref|selector> [path]');
+      const elementRef = await resolveRef(client, refOrSelector, parsed.tabId, REQUEST_SOURCE);
       const response = await requestBridge(
         client,
         'screenshot.capture_element',
         {
           elementRef,
         },
-        { source: REQUEST_SOURCE }
+        { tabId: parsed.tabId, source: REQUEST_SOURCE }
       );
       if (!response.ok) {
         await printSummary(response);

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

@@ -15,6 +15,7 @@ import {
   getBridgeTransport,
   getSocketPath,
 } from '../../native-host/src/config.js';
+import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 
 /** @typedef {import('../../native-host/src/config.js').BridgeTransport} BridgeTransport */
 
@@ -23,7 +24,9 @@ import {
 /** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
 /**
  * @typedef {{
+ *   extensionConnected?: boolean,
  *   supported_versions?: string[],
+ *   daemon_supported_versions?: string[],
  *   deprecated_since?: string,
  *   migration_hint?: string
  * }} ProtocolHealthResult
@@ -55,9 +58,29 @@ import {
  *   clientId?: string,
  *   defaultTimeoutMs?: number,
  *   autoReconnect?: boolean,
+ *   restartDaemonOnVersionMismatch?: boolean,
+ *   restartDaemonFn?: typeof restartBridgeDaemon,
  * }} BridgeClientOptions
  */
 
+/**
+ * @param {string} left
+ * @param {string} right
+ * @returns {number}
+ */
+function compareProtocolVersions(left, right) {
+  const leftParts = left.split('.').map((part) => Number(part) || 0);
+  const rightParts = right.split('.').map((part) => Number(part) || 0);
+  const length = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < length; index += 1) {
+    const delta = (leftParts[index] || 0) - (rightParts[index] || 0);
+    if (delta !== 0) {
+      return delta > 0 ? 1 : -1;
+    }
+  }
+  return 0;
+}
+
 /**
  * @param {string} method
  * @param {number} timeoutMs
@@ -81,6 +104,8 @@ export class BridgeClient extends EventEmitter {
     clientId = `agent_${randomUUID()}`,
     defaultTimeoutMs = DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
     autoReconnect = false,
+    restartDaemonOnVersionMismatch = true,
+    restartDaemonFn = restartBridgeDaemon,
   } = {}) {
     super();
     this.transport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
@@ -89,6 +114,8 @@ export class BridgeClient extends EventEmitter {
     this.clientId = clientId;
     this.defaultTimeoutMs = defaultTimeoutMs;
     this.autoReconnect = autoReconnect;
+    this.restartDaemonOnVersionMismatch = restartDaemonOnVersionMismatch;
+    this.restartDaemonFn = restartDaemonFn;
     this.socket = null;
     this.connected = false;
     this.protocolCompatibility = null;
@@ -96,6 +123,7 @@ export class BridgeClient extends EventEmitter {
     /** @type {Map<string, PendingRequest>} */
     this.waiting = new Map();
     this._reconnecting = false;
+    this._attemptedVersionMismatchRestart = false;
   }
 
   /**
@@ -173,19 +201,38 @@ export class BridgeClient extends EventEmitter {
       });
     });
 
+    this.protocolCompatibility = null;
+    this.protocolWarning = null;
+
+    /** @type {ProtocolHealthResult | null} */
+    let healthResult = null;
     try {
       const healthResponse = await this.request({
         method: 'health.ping',
       });
       if (healthResponse.ok) {
-        this.protocolCompatibility = BridgeClient.checkProtocolVersion(
-          /** @type {ProtocolHealthResult} */ (healthResponse.result)
-        );
-        this.protocolWarning = this.protocolCompatibility.warning ?? null;
+        healthResult = /** @type {ProtocolHealthResult} */ (healthResponse.result);
       }
     } catch {
       this.protocolCompatibility = null;
       this.protocolWarning = null;
+      return;
+    }
+
+    if (!healthResult) {
+      return;
+    }
+
+    this.protocolCompatibility = BridgeClient.checkProtocolVersion(healthResult);
+    this.protocolWarning = this.protocolCompatibility.warning ?? null;
+    if (this.protocolCompatibility.compatible) {
+      this._attemptedVersionMismatchRestart = false;
+    }
+    if (this.shouldRestartDaemonForProtocolMismatch(healthResult)) {
+      this._attemptedVersionMismatchRestart = true;
+      await this.disconnectForDaemonRestart();
+      await this.restartDaemonFn({ transport: this.transport });
+      await this.connect();
     }
   }
 
@@ -305,6 +352,60 @@ export class BridgeClient extends EventEmitter {
     this._reconnecting = false;
   }
 
+  /**
+   * @param {ProtocolHealthResult} healthResult
+   * @returns {boolean}
+   */
+  shouldRestartDaemonForProtocolMismatch(healthResult) {
+    if (
+      !this.restartDaemonOnVersionMismatch ||
+      this._attemptedVersionMismatchRestart ||
+      !this.protocolCompatibility ||
+      this.protocolCompatibility.compatible
+    ) {
+      return false;
+    }
+
+    const remoteVersions = Array.isArray(healthResult?.daemon_supported_versions)
+      ? healthResult.daemon_supported_versions
+      : healthResult?.extensionConnected === true
+        ? []
+        : Array.isArray(healthResult?.supported_versions)
+          ? healthResult.supported_versions
+          : [];
+    const latestRemote = remoteVersions[0];
+    return (
+      typeof latestRemote === 'string' &&
+      compareProtocolVersions(latestRemote, PROTOCOL_VERSION) < 0
+    );
+  }
+
+  /**
+   * Drop the current socket before forcing a daemon restart so the next
+   * connect() call observes a fresh local process rather than the existing one.
+   *
+   * @returns {Promise<void>}
+   */
+  async disconnectForDaemonRestart() {
+    const socket = this.socket;
+    if (!socket) {
+      return;
+    }
+
+    const previousAutoReconnect = this.autoReconnect;
+    this.autoReconnect = false;
+    this.connected = false;
+    this.socket = null;
+
+    if (!socket.destroyed) {
+      const closed = once(socket, 'close').catch(() => {});
+      socket.destroy();
+      await closed;
+    }
+
+    this.autoReconnect = previousAutoReconnect;
+  }
+
   /**
    * Check whether the remote side supports our protocol version.
    * Call after a successful health.ping to get early warnings about version drift.

package/packages/agent-client/src/command-registry.js

@@ -347,7 +347,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Capture',
     lines: [
-      'bbx screenshot <ref|selector> [path]                               Capture partial element screenshot',
+      'bbx screenshot [--tab <tabId>] <ref|selector> [path]               Capture partial element screenshot',
     ],
   },
 ]);

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

@@ -0,0 +1,279 @@
+// @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: true,
+    method: 'cdp.get_box_model',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  cdp_computed_styles: {
+    ref: true,
+    method: 'cdp.get_computed_styles_for_node',
+    params: (_, r) => ({ elementRef: r }),
+  },
+};
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleCaptureTool(args) {
+  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,196 @@
+// @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,
+      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: 'toggle_class',
+        removeClass: 'toggle_class',
+        setTextContent: 'set_text',
+        setProperty: 'set_attribute',
+      };
+      return {
+        target: { elementRef: r },
+        operation: opMap[operation] || operation,
+        value: a.value,
+        name: a.name,
+        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');
+}