@browserbridge/bbx 1.7.8 → 1.9.0

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

@@ -6,12 +6,20 @@ import net from 'node:net';
 import { randomUUID } from 'node:crypto';
 
 import {
+  createFailure,
   createRequest,
+  createSuccess,
   DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
+  ERROR_CODES,
   getProtocolVersion,
+  isBatchSafeBridgeCall,
+  isBridgeMethod,
+  MAX_BATCH_CALLS,
+  MAX_BATCH_CONCURRENCY,
   parseJsonLines,
   setProtocolPackageVersion,
 } from '../../protocol/src/index.js';
+import { extractContentFromHtml } from './content-extract.js';
 import {
   createSocketBridgeTransport,
   getBridgeTransport,
@@ -19,6 +27,12 @@ import {
 } from '../../native-host/src/config.js';
 import { normalizeBridgeAuthToken, readBridgeAuthToken } from '../../native-host/src/auth-token.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
+import {
+  comparePackageVersions,
+  NpmPackageUpdatedError,
+  parseStableVersion,
+  updateCompatibleNpmPackage,
+} from './npm-self-update.js';
 
 /** @typedef {import('./types.js').BridgeMeta} BridgeMeta */
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
@@ -28,7 +42,8 @@ import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 /** @typedef {import('./types.js').PendingRequest} PendingRequest */
 /** @typedef {import('./types.js').ProtocolHealthResult} ProtocolHealthResult */
 
-setProtocolPackageVersion(loadPackageVersion());
+const CLIENT_PACKAGE_VERSION = loadPackageVersion();
+setProtocolPackageVersion(CLIENT_PACKAGE_VERSION);
 
 /**
  * @returns {string | null}
@@ -112,8 +127,12 @@ export class BridgeClient extends EventEmitter {
     clientId = `agent_${randomUUID()}`,
     defaultTimeoutMs = DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
     autoReconnect = false,
+    checkProtocolOnConnect = true,
     restartDaemonOnVersionMismatch = shouldAutoRestartDaemonOnVersionMismatch(),
     restartDaemonFn = restartBridgeDaemon,
+    updateNpmOnCompatibleVersion = false,
+    exitProcessOnNpmUpdate = false,
+    updateCompatibleNpmPackageFn = updateCompatibleNpmPackage,
     authToken = undefined,
   } = {}) {
     super();
@@ -123,8 +142,12 @@ export class BridgeClient extends EventEmitter {
     this.clientId = clientId;
     this.defaultTimeoutMs = defaultTimeoutMs;
     this.autoReconnect = autoReconnect;
+    this.checkProtocolOnConnect = checkProtocolOnConnect;
     this.restartDaemonOnVersionMismatch = restartDaemonOnVersionMismatch;
     this.restartDaemonFn = restartDaemonFn;
+    this.updateNpmOnCompatibleVersion = updateNpmOnCompatibleVersion;
+    this.exitProcessOnNpmUpdate = exitProcessOnNpmUpdate;
+    this.updateCompatibleNpmPackageFn = updateCompatibleNpmPackageFn;
     this.authToken = authToken;
     this.socket = null;
     this.connected = false;
@@ -134,6 +157,9 @@ export class BridgeClient extends EventEmitter {
     this.waiting = new Map();
     this._reconnecting = false;
     this._attemptedVersionMismatchRestart = false;
+    this._attemptedNpmUpdate = false;
+    /** @type {import('./types.js').NpmUpdateResult | null} */
+    this.npmUpdateResult = null;
   }
 
   /**
@@ -246,6 +272,9 @@ export class BridgeClient extends EventEmitter {
 
     this.protocolCompatibility = null;
     this.protocolWarning = null;
+    if (!this.checkProtocolOnConnect) {
+      return;
+    }
 
     /** @type {ProtocolHealthResult | null} */
     let healthResult = null;
@@ -271,6 +300,9 @@ export class BridgeClient extends EventEmitter {
     if (this.protocolCompatibility.compatible) {
       this._attemptedVersionMismatchRestart = false;
     }
+    if (await this.tryCompatibleNpmUpdate(healthResult)) {
+      return;
+    }
     if (this.shouldRestartDaemonForProtocolMismatch(healthResult)) {
       this._attemptedVersionMismatchRestart = true;
       await this.disconnectForDaemonRestart();
@@ -279,6 +311,95 @@ export class BridgeClient extends EventEmitter {
     }
   }
 
+  /**
+   * @param {ProtocolHealthResult} healthResult
+   * @returns {Promise<boolean>}
+   */
+  async tryCompatibleNpmUpdate(healthResult) {
+    const extensionVersion = healthResult.extensionVersion;
+    const processVersion = CLIENT_PACKAGE_VERSION;
+    const extensionVersions = Array.isArray(healthResult.extension_supported_versions)
+      ? healthResult.extension_supported_versions
+      : healthResult.extensionConnected === true && Array.isArray(healthResult.supported_versions)
+        ? healthResult.supported_versions
+        : [];
+    if (
+      !this.updateNpmOnCompatibleVersion ||
+      this._attemptedNpmUpdate ||
+      healthResult.extensionConnected !== true ||
+      typeof extensionVersion !== 'string' ||
+      !parseStableVersion(extensionVersion) ||
+      typeof processVersion !== 'string' ||
+      !parseStableVersion(processVersion) ||
+      comparePackageVersions(extensionVersion, processVersion) <= 0 ||
+      extensionVersions.length === 0
+    ) {
+      return false;
+    }
+
+    this._attemptedNpmUpdate = true;
+    const previousAutoReconnect = this.autoReconnect;
+    this.autoReconnect = false;
+    try {
+      this.npmUpdateResult = await this.updateCompatibleNpmPackageFn({
+        extensionVersion,
+        supportedVersions: extensionVersions,
+      });
+      if (!this.npmUpdateResult.updated) {
+        if (
+          typeof this.npmUpdateResult.previousVersion === 'string' &&
+          parseStableVersion(this.npmUpdateResult.previousVersion) &&
+          comparePackageVersions(this.npmUpdateResult.previousVersion, processVersion) > 0
+        ) {
+          this.requireFreshProcess(this.npmUpdateResult.previousVersion);
+        }
+        if (this.npmUpdateResult.reason === 'not_global_install') {
+          this.setProtocolWarning(
+            'Automatic npm update skipped because this Browser Bridge client is not running from the global npm installation.'
+          );
+        }
+        return false;
+      }
+
+      this.requireFreshProcess(this.npmUpdateResult.version || extensionVersion);
+    } catch (error) {
+      if (error instanceof NpmPackageUpdatedError || this.npmUpdateResult?.updated) {
+        throw error;
+      }
+      this.setProtocolWarning(
+        `Automatic Browser Bridge npm update failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return false;
+    } finally {
+      this.autoReconnect = previousAutoReconnect;
+    }
+  }
+
+  /**
+   * @param {string} version
+   * @returns {never}
+   */
+  requireFreshProcess(version) {
+    if (this.exitProcessOnNpmUpdate) {
+      setTimeout(() => process.exit(0), 250).unref();
+    }
+    throw new NpmPackageUpdatedError(version);
+  }
+
+  /**
+   * @param {string} warning
+   * @returns {void}
+   */
+  setProtocolWarning(warning) {
+    this.protocolWarning = this.protocolWarning ? `${this.protocolWarning} ${warning}` : warning;
+    if (this.protocolCompatibility) {
+      this.protocolCompatibility = {
+        ...this.protocolCompatibility,
+        warning: this.protocolWarning,
+      };
+    }
+  }
+
   /**
    * @param {{
    *   method: BridgeMethod,
@@ -312,6 +433,113 @@ export class BridgeClient extends EventEmitter {
       meta,
     });
 
+    if (method === 'page.extract_content') {
+      const params =
+        /** @type {import('../../protocol/src/types.js').NormalizedExtractContentParams} */ (
+          request.params
+        );
+      const titleResponse = params.includeMetadata
+        ? await this.request({ method: 'page.get_state', tabId, meta, timeoutMs })
+        : null;
+      if (titleResponse && !titleResponse.ok) {
+        return {
+          ...titleResponse,
+          id: request.id,
+          meta: { ...titleResponse.meta, method },
+        };
+      }
+      const titleResult =
+        titleResponse?.ok && titleResponse.result && typeof titleResponse.result === 'object'
+          ? /** @type {Record<string, unknown>} */ (titleResponse.result)
+          : {};
+      const readSnapshot = () =>
+        this.request({
+          method: 'dom.get_html',
+          tabId,
+          params: {
+            target: { selector: params.selector ?? 'body' },
+            outer: true,
+            maxLength: 50_000,
+          },
+          meta: { ...meta, token_budget: null },
+          timeoutMs,
+        });
+
+      let snapshotResponse = await readSnapshot();
+      if (!snapshotResponse.ok) {
+        return {
+          ...snapshotResponse,
+          id: request.id,
+          meta: { ...snapshotResponse.meta, method },
+        };
+      }
+      let snapshot = normalizeHtmlSnapshot(snapshotResponse.result);
+      if (snapshot.truncated) {
+        return createFailure(
+          request.id,
+          ERROR_CODES.RESULT_TRUNCATED,
+          'The bounded HTML snapshot was too large for semantic extraction.',
+          {
+            selector: params.selector,
+            omitted: snapshot.omitted,
+            maxLength: 50_000,
+          },
+          {
+            method,
+            continuation_hint: 'Retry with a narrower selector.',
+          }
+        );
+      }
+
+      let settlement;
+      if (params.consistency === 'settled') {
+        const deadline = Date.now() + params.settleTimeoutMs;
+        let timedOut = false;
+        while (true) {
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          const nextResponse = await readSnapshot();
+          if (!nextResponse.ok) {
+            return {
+              ...nextResponse,
+              id: request.id,
+              meta: { ...nextResponse.meta, method },
+            };
+          }
+          const nextSnapshot = normalizeHtmlSnapshot(nextResponse.result);
+          if (nextSnapshot.truncated) {
+            return createFailure(
+              request.id,
+              ERROR_CODES.RESULT_TRUNCATED,
+              'The bounded HTML snapshot was too large for semantic extraction.',
+              { selector: params.selector, omitted: nextSnapshot.omitted, maxLength: 50_000 },
+              { method, continuation_hint: 'Retry with a narrower selector.' }
+            );
+          }
+          if (nextSnapshot.html === snapshot.html) {
+            snapshot = nextSnapshot;
+            break;
+          }
+          snapshot = nextSnapshot;
+          if (Date.now() >= deadline) {
+            timedOut = true;
+            break;
+          }
+        }
+        settlement = { requested: true, quietMs: 100, timedOut };
+      }
+
+      const result = extractContentFromHtml(snapshot.html, params, {
+        title: typeof titleResult.title === 'string' ? titleResult.title : undefined,
+        settlement,
+      });
+      return this.attachProtocolWarning(
+        createSuccess(request.id, result, {
+          method,
+          node_processed: true,
+        })
+      );
+    }
+
     const responsePromise = new Promise((resolve, reject) => {
       const timeoutId = setTimeout(() => {
         this.waiting.delete(request.id);
@@ -340,7 +568,7 @@ export class BridgeClient extends EventEmitter {
   }
 
   /**
-   * Send multiple bridge requests without waiting for each response serially.
+   * Send up to 20 read-only bridge requests with bounded concurrency.
    *
    * @param {Array<{
    *   method: BridgeMethod,
@@ -355,8 +583,27 @@ export class BridgeClient extends EventEmitter {
     if (!Array.isArray(calls)) {
       throw new TypeError('BridgeClient.batch expects an array of request objects.');
     }
+    if (calls.length === 0 || calls.length > MAX_BATCH_CALLS) {
+      throw new RangeError(
+        `BridgeClient.batch expects between 1 and ${MAX_BATCH_CALLS} request objects.`
+      );
+    }
+    for (const [index, call] of calls.entries()) {
+      if (!call || typeof call !== 'object' || !isBridgeMethod(call.method)) {
+        throw new TypeError(`BridgeClient.batch calls[${index}] needs a known bridge method.`);
+      }
+      const params = call.params ?? {};
+      if (!params || typeof params !== 'object' || Array.isArray(params)) {
+        throw new TypeError(`BridgeClient.batch calls[${index}].params must be an object.`);
+      }
+      if (!isBatchSafeBridgeCall(call.method, params)) {
+        throw new TypeError(
+          `${call.method} is not safe for BridgeClient.batch. Call it sequentially.`
+        );
+      }
+    }
 
-    return Promise.all(calls.map((call) => this.request(call)));
+    return mapWithConcurrency(calls, MAX_BATCH_CONCURRENCY, (call) => this.request(call));
   }
 
   /**
@@ -419,10 +666,13 @@ export class BridgeClient extends EventEmitter {
           ? healthResult.supported_versions
           : [];
     const latestRemote = remoteVersions[0];
+    const extensionVersions = Array.isArray(healthResult?.extension_supported_versions)
+      ? healthResult.extension_supported_versions
+      : healthResult?.supported_versions;
     if (
       healthResult?.extensionConnected === true &&
-      Array.isArray(healthResult.supported_versions) &&
-      !healthResult.supported_versions.includes(getProtocolVersion())
+      Array.isArray(extensionVersions) &&
+      !extensionVersions.includes(getProtocolVersion())
     ) {
       return false;
     }
@@ -466,9 +716,11 @@ export class BridgeClient extends EventEmitter {
    * @returns {{ compatible: boolean, localVersion: string, remoteVersions: string[], warning?: string }}
    */
   static checkProtocolVersion(healthResult) {
-    const remoteVersions = Array.isArray(healthResult?.supported_versions)
-      ? healthResult.supported_versions
-      : [];
+    const remoteVersions = Array.isArray(healthResult?.extension_supported_versions)
+      ? healthResult.extension_supported_versions
+      : Array.isArray(healthResult?.supported_versions)
+        ? healthResult.supported_versions
+        : [];
     if (remoteVersions.length === 0) {
       return {
         compatible: true,
@@ -520,3 +772,39 @@ export class BridgeClient extends EventEmitter {
     };
   }
 }
+
+/**
+ * @template T, R
+ * @param {T[]} values
+ * @param {number} concurrency
+ * @param {(value: T) => Promise<R>} callback
+ * @returns {Promise<R[]>}
+ */
+async function mapWithConcurrency(values, concurrency, callback) {
+  /** @type {R[]} */
+  const results = new Array(values.length);
+  let nextIndex = 0;
+  const workers = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+    while (nextIndex < values.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await callback(values[index]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * @param {unknown} result
+ * @returns {{ html: string, truncated: boolean, omitted: number }}
+ */
+function normalizeHtmlSnapshot(result) {
+  const value =
+    result && typeof result === 'object' ? /** @type {Record<string, unknown>} */ (result) : {};
+  return {
+    html: typeof value.html === 'string' ? value.html : '',
+    truncated: value.truncated === true,
+    omitted: typeof value.omitted === 'number' ? value.omitted : 0,
+  };
+}

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

@@ -30,103 +30,106 @@ function createShortcutCommand(method, usage, build, options = {}) {
   };
 }
 
+/**
+ * Preserve explicit refs and pass selectors directly to methods that support
+ * atomic target resolution.
+ *
+ * @param {string | undefined} value
+ * @returns {{ elementRef: string } | { selector: string }}
+ */
+function createAtomicTarget(value) {
+  if (!value) throw new Error('A ref or selector is required.');
+  return value.startsWith('el_') ? { elementRef: value } : { selector: value };
+}
+
 /** @type {Record<string, ShortcutCommand>} */
 export const SHORTCUT_COMMANDS = {
-  'access-request': createShortcutCommand('access.request', 'bbx access-request', () => ({})),
+  'access-request': createShortcutCommand('access.request', 'bbx access-request [intent]', (r) =>
+    r[0] ? { intent: r[0] } : {}
+  ),
   'dom-query': createShortcutCommand('dom.query', 'bbx dom-query [selector]', (r) => ({
     selector: r[0] || 'body',
   })),
   describe: createShortcutCommand(
     'dom.describe',
     'bbx describe <ref|selector>',
-    (_r, ref) => ({ elementRef: ref }),
-    { resolve: true, printMethod: 'dom.describe' }
+    (r) => ({ target: createAtomicTarget(r[0]) }),
+    { printMethod: 'dom.describe' }
   ),
   text: createShortcutCommand(
     'dom.get_text',
     'bbx text <ref|selector> [budget]',
-    (r, ref) => ({
-      elementRef: ref,
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       textBudget: r[1] ? parseIntArg(r[1], 'budget') : undefined,
     }),
-    { resolve: true, printMethod: 'dom.get_text' }
+    { printMethod: 'dom.get_text' }
   ),
   styles: createShortcutCommand(
     'styles.get_computed',
     'bbx styles <ref|selector> [props]',
-    (r, ref) => ({ elementRef: ref, properties: parseCommaList(r[1]) }),
-    { resolve: true, printMethod: 'styles.get_computed' }
+    (r) => ({ target: createAtomicTarget(r[0]), properties: parseCommaList(r[1]) }),
+    { printMethod: 'styles.get_computed' }
   ),
   box: createShortcutCommand(
     'layout.get_box_model',
     'bbx box <ref|selector>',
-    (_r, ref) => ({ elementRef: ref }),
-    { resolve: true, printMethod: 'layout.get_box_model' }
-  ),
-  click: createShortcutCommand(
-    'input.click',
-    'bbx click <ref|selector> [button]',
-    (r, ref) => ({ target: { elementRef: ref }, button: r[1] }),
-    { resolve: true }
-  ),
-  focus: createShortcutCommand(
-    'input.focus',
-    'bbx focus <ref|selector>',
-    (_r, ref) => ({ target: { elementRef: ref } }),
-    { resolve: true }
-  ),
-  type: createShortcutCommand(
-    'input.type',
-    'bbx type <ref|selector> <text...>',
-    (r, ref) => ({ target: { elementRef: ref }, text: r.slice(1).join(' ') }),
-    { resolve: true }
+    (r) => ({ target: createAtomicTarget(r[0]) }),
+    { printMethod: 'layout.get_box_model' }
   ),
+  click: createShortcutCommand('input.click', 'bbx click <ref|selector> [button]', (r) => ({
+    target: createAtomicTarget(r[0]),
+    button: r[1],
+  })),
+  focus: createShortcutCommand('input.focus', 'bbx focus <ref|selector>', (r) => ({
+    target: createAtomicTarget(r[0]),
+  })),
+  type: createShortcutCommand('input.type', 'bbx type <ref|selector> <text...>', (r) => ({
+    target: createAtomicTarget(r[0]),
+    text: r.slice(1).join(' '),
+  })),
   fill: createShortcutCommand(
     'input.fill',
     'bbx fill <ref|selector> <value>',
-    (r, ref) => ({
-      target: { elementRef: ref },
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       value: r.slice(1).join(' '),
       mode: 'auto',
     }),
     {
-      resolve: true,
       description: 'Set input/textarea value (React/Vue/Angular-safe, auto fallback to keystrokes)',
     }
   ),
-  hover: createShortcutCommand(
-    'input.hover',
-    'bbx hover <ref|selector>',
-    (_r, ref) => ({ target: { elementRef: ref } }),
-    { resolve: true }
-  ),
+  hover: createShortcutCommand('input.hover', 'bbx hover <ref|selector>', (r) => ({
+    target: createAtomicTarget(r[0]),
+  })),
   html: createShortcutCommand(
     'dom.get_html',
     'bbx html <ref|selector> [maxLen]',
-    (r, ref) => ({
-      elementRef: ref,
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       maxLength: r[1] ? parseIntArg(r[1], 'maxLen') : undefined,
     }),
-    { resolve: true }
+    {}
   ),
   'patch-style': createShortcutCommand(
     'patch.apply_styles',
     'bbx patch-style <ref|sel> prop=val',
-    (r, ref) => ({
-      target: { elementRef: ref },
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       declarations: parsePropertyAssignments(r.slice(1)),
     }),
-    { resolve: true }
+    {}
   ),
   'patch-text': createShortcutCommand(
     'patch.apply_dom',
     'bbx patch-text <ref|sel> <text...>',
-    (r, ref) => ({
-      target: { elementRef: ref },
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       operation: 'set_text',
       value: r.slice(1).join(' '),
     }),
-    { resolve: true, description: 'Apply a reversible DOM text patch' }
+    { description: 'Apply a reversible DOM text patch' }
   ),
   patches: createShortcutCommand('patch.list', 'bbx patches', () => ({}), {
     printMethod: 'patch.list',
@@ -201,7 +204,10 @@ export const SHORTCUT_COMMANDS = {
       maxDepth: r[1] ? parseIntArg(r[1], 'maxDepth') : undefined,
     })
   ),
-  perf: createShortcutCommand('performance.get_metrics', 'bbx perf', () => ({})),
+  perf: createShortcutCommand('performance.get_metrics', 'bbx perf', () => ({}), {
+    description:
+      'Read a raw Chrome/CDP counter point sample (names and units vary; no BBX navigation window or LCP/CLS/INP measurement)',
+  }),
   scroll: createShortcutCommand('viewport.scroll', 'bbx scroll <top> [left]', (r) => {
     if (!r[0] && !r[1]) throw new Error('Usage: scroll <top> [left]');
     return {
@@ -222,14 +228,14 @@ export const SHORTCUT_COMMANDS = {
   attrs: createShortcutCommand(
     'dom.get_attributes',
     'bbx attrs <ref|selector> [attr1,...]',
-    (r, ref) => ({ elementRef: ref, attributes: parseCommaList(r[1]) }),
-    { resolve: true, printMethod: 'dom.get_attributes' }
+    (r) => ({ target: createAtomicTarget(r[0]), attributes: parseCommaList(r[1]) }),
+    { printMethod: 'dom.get_attributes' }
   ),
   'matched-rules': createShortcutCommand(
     'styles.get_matched_rules',
     'bbx matched-rules <ref|selector>',
-    (_r, ref) => ({ elementRef: ref }),
-    { resolve: true, printMethod: 'styles.get_matched_rules' }
+    (r) => ({ target: createAtomicTarget(r[0]) }),
+    { printMethod: 'styles.get_matched_rules' }
   ),
 };
 
@@ -247,6 +253,7 @@ export const CLI_METHOD_BINDINGS = Object.freeze({
   'press-key': 'input.press_key',
   'cdp-press-key': 'cdp.dispatch_key_event',
   screenshot: 'screenshot.capture_element',
+  har: 'network.export_har',
   eval: 'page.evaluate',
 });
 
@@ -260,8 +267,9 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx install-skill [targets|all] [--global] [--project <path>]      Install/update the managed Browser Bridge CLI skill',
       'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf|agents',
       'bbx status                                                         Check bridge connection',
-      'bbx doctor                                                         Diagnose install, daemon, extension, and access readiness',
+      'bbx doctor                                                         Consolidated local runtime, setup, protocol, and readiness diagnostics',
       'bbx restart                                                        Restart the local daemon and running MCP servers',
+      'bbx config set auto-update <off|compatible>                         Configure protocol-compatible npm updates',
       'bbx proxy enable [--port 9223] [--bind-host 127.0.0.1] [--rotate-token]  Enable loopback TCP proxy mode for SSH tunneling',
       '  Non-loopback binds require --unsafe-plaintext because raw TCP is unencrypted.',
       'bbx proxy disable                                                  Disable proxy mode and restart the daemon',
@@ -270,7 +278,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx remote list                                                    List remote destinations',
       'bbx remote test <name>                                             Ping a remote destination',
       'bbx remote remove <name>                                           Remove a remote destination',
-      'bbx access-request                                                 Request Browser Bridge access for the focused window',
+      'bbx access-request [intent]                                        Request access with inspect|interact|capture|navigate|debugger|general intent',
       'bbx logs                                                           Recent bridge logs',
       'bbx tabs                                                           List available tabs',
       'bbx tab-create [url]                                               Create a new tab',
@@ -285,7 +293,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
     lines: [
       'bbx call [--tab <tabId>] <method> [paramsJson|-]                   Call any bridge method (- reads JSON from stdin)',
       'bbx <method> [--tab <tabId>] [paramsJson|-]                        Direct alias for exact bridge methods such as page.get_state',
-      "bbx batch '[{method,params,tabId?},...]'                           Parallel method calls",
+      "bbx batch '[{method,params,tabId?},...]'                           Up to 20 parallel read-only calls",
       'Every bridge command accepts --remote <name> (or BBX_REMOTE env) to target a remote destination from `bbx remote list`.',
       'Advanced bridge params stay available through `bbx call`, even when shortcuts expose only the common case.',
       'For open-ended investigation, start with `bbx batch` on `page.get_state`, `dom.query`, and `page.get_text` before any screenshot or CDP call.',
@@ -372,7 +380,8 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Capture',
     lines: [
-      'bbx screenshot [--tab <tabId>] <ref|selector> [path]               Capture partial element screenshot',
+      'bbx screenshot [--tab <tabId>] [--format png|jpeg|webp] [--quality 0-100] <ref|selector> [path]',
+      'bbx har [--tab <tabId>] [--limit 1-200] [--url-pattern <pattern>] [--delivery inline|artifact|auto] [outPath]',
     ],
   },
 ]);