@browserbridge/bbx 1.7.8 → 1.9.0

package/PRIVACY.md

@@ -1,6 +1,6 @@
 # Browser Bridge (BBX) Privacy Policy
 
-Last updated: 2026-03-27
+Last updated: 2026-07-23
 
 ## Overview
 
@@ -12,30 +12,61 @@ When you enable Browser Bridge for a Chrome window, Browser Bridge can access pa
 
 - Page metadata such as URL, title, viewport, and scroll position
 - DOM structure, element attributes, visible text, and layout information
-- Computed styles, matched rules, and accessibility-tree data
+- Computed styles, class/inline-style context, and semantic accessibility-tree data
 - Console messages and uncaught page errors
-- Network request metadata captured from page `fetch` and `XMLHttpRequest` activity, such as URL, method, status, timing, and size
-- `localStorage` and `sessionStorage` values when explicitly requested
+- Network request metadata captured from page `fetch` and `XMLHttpRequest` activity, such as URL, method, status, timing, type, timestamp, and size
+- Optional Chrome DevTools Protocol metadata for broader resource activity, including request ID, redacted URL, method, resource type, status, MIME type, protocol, cache indicators, redirects, failure reason, duration, and timestamp
+- Metadata-only HAR 1.2 documents exported from an explicitly armed CDP capture, including sanitized URLs and observed status, redirect, failure, cache, and service-worker metadata
+- Current JavaScript dialog information when observable and explicitly requested, including dialog type, bounded message text, and bounded default prompt text
+- `localStorage` and `sessionStorage` key metadata through ordinary inspection, and one exact value only through a deliberate `sensitive.read` request
 - Screenshots or cropped image captures when explicitly requested
-- User-triggered interaction data such as clicks, typing, key presses, selection changes, and navigation actions
+- User-triggered interaction data and results such as clicks, native pointer movement/drag, DOM or native text dispatch, key presses, selection changes, dialog decisions, and navigation actions
+- Bounded semantic descriptors for optional stale-element recovery, represented in memory with normalized hashes and structural context rather than page text values or attributes written into the application DOM
+
+All-resource network inspection excludes request and response bodies, cookies,
+authorization values, and complete headers. It removes URL credentials and
+fragments, replaces query parameter values with a redaction marker, and
+summarizes data/blob URLs before returning them. Browser Bridge does not expose
+these excluded values through that feature. HAR exports use the same URL
+sanitization: schemes, hosts, paths, and query parameter names remain visible,
+but credentials, fragments, and query values do not. HAR request/response
+headers and cookies are empty, bodies are absent, and unavailable byte sizes and
+timing phases are reported as `-1`.
+
+Recovery telemetry contains only fixed category names, bounded counts, rates,
+timestamps, and active-loop flags. It does not include page content, URLs,
+selectors, method/group identifiers, request payloads, or error text. The fixed
+categories are automatic MCP retry, stale-reference recovery, debugger
+reattachment, content-script reinjection, native-host reconnect, and request
+outcome.
 
 Browser Bridge is designed for local debugging and automation of the browser state you intentionally expose to it.
 
+Ordinary storage inspection does not return value prefixes. Exact Web Storage
+values require a separate key-specific sensitive read, are returned whole or
+rejected whole, are never batched or retried automatically, and produce a
+textual Sensitive access warning in Recent Activity. The warning stores the
+source/category and key length, not the key or value. Powerful explicit methods
+such as page evaluation and DOM inspection can still expose page data by design.
+Every page evaluation is therefore labeled as Sensitive access in Recent
+Activity, and its returned value and derived size are excluded from persisted
+activity diagnostics.
+
 ## How Browser Bridge uses data
 
 Browser Bridge uses this data only to provide its user-facing purpose: letting you inspect, test, and patch the currently enabled browser window from a connected developer tool or agent.
 
-The extension sends request and response data locally through:
+The normal local path sends request and response data through:
 
 1. The Browser Bridge Chrome extension
 2. The Browser Bridge native messaging host running on your machine
-3. The local agent client or IDE that you intentionally connect
+3. The agent client or IDE that you intentionally connect
 
-Browser Bridge does not operate a Browser Bridge cloud service and does not send extension data to developer-operated remote servers.
+The extension/native-host segment remains on the browser machine. If you explicitly configure an authenticated remote destination, the daemon can send bridge results over your own SSH tunnel or network route to that selected client. Browser Bridge does not operate a Browser Bridge cloud service and does not send extension data to developer-operated remote servers. Raw remote TCP is not presented as encrypted.
 
 ## Sharing and downstream processing
 
-Browser Bridge shares page data only with the local companion components and local client you choose to connect.
+Browser Bridge shares page data only with the companion components and client you choose to connect. The normal path is local. If you explicitly configure Browser Bridge's authenticated remote proxy and your own tunnel or network route, the selected remote client can receive bridge results through that user-configured path; Browser Bridge does not provide or operate that network service.
 
 Important:
 
@@ -52,8 +83,15 @@ Browser Bridge keeps data only as long as needed for the current local session a
 
 - Window enablement state is stored in session storage and cleared when disabled or when the browser session ends.
 - Action log entries are stored for the current browser session only.
-- Console and network buffers are bounded in memory and cleared when disabled or when the page state is reset.
-- Patch state and remembered element references are session-scoped and cleared on disable, page replacement, or navigation as needed.
+- Incidental action/log URLs remove credentials and fragments and redact query values; sensitive structured fields and local path prefixes are reduced before persistence.
+- Console and fetch/XHR network buffers are bounded in memory and cleared when disabled or when the page state is reset.
+- Optional CDP network capture is bounded in memory, explicitly started/stopped, expires after a safety interval, and is cleared on relevant debugger, tab, or access teardown.
+- HAR export does not start, stop, or clear capture. Inline size limits remove whole oldest entries; artifact delivery uses opaque owner-scoped handles with no browser-host path. Artifacts expire after five minutes, are removed on daemon/extension teardown, and use private daemon directory/file modes on POSIX systems.
+- Recovery telemetry is held in fixed five-second buckets over a five-minute process-local window. Extension-side summaries reset with the extension service worker, daemon summaries reset with the daemon, and neither is durable history.
+- Dialog message/default prompt text is returned to the requesting caller when inspected but is excluded from persisted action-log summaries and size diagnostics.
+- Exact sensitive values traverse the selected client in memory but are excluded from action summaries, diagnostic size counters, daemon logs, and automatic artifact storage.
+- Patch rollback records and remembered element references live in the current document. Browser Bridge attempts patch rollback when access is disabled or switched, while page replacement/navigation removes document-local state.
+- Hashed semantic descriptors used for optional stale recovery are bounded in memory with the element registry and do not survive the document/registry lifecycle.
 
 Browser Bridge does not provide Browser Bridge-hosted accounts, sync, or long-term server-side storage.
 
@@ -72,12 +110,19 @@ Browser Bridge does not load remotely hosted extension code.
 
 Browser Bridge can, when you explicitly invoke features such as page evaluation, execute user-requested expressions in the inspected page context through Chrome's documented Debugger API. That execution affects only the currently enabled browser window and is part of Browser Bridge's developer-tool functionality.
 
+The same existing Debugger API permission is used only when requested for
+native pointer/text dispatch, JavaScript dialog observation and explicit
+handling, accessibility reads, screenshots, performance/CDP reads, interception,
+and optional all-resource network capture. Browser Bridge does not silently
+accept/dismiss dialogs and does not claim that accepted browser input proves an
+application-level outcome.
+
 ## Security
 
 - Extension code is packaged with the extension; Browser Bridge does not fetch and execute remote extension scripts.
 - Communication with the companion host uses Chrome Native Messaging.
 - Access is limited to the explicitly enabled browser window.
-- The extension includes bounded buffers and session-scoped rollback for temporary page patches.
+- The extension includes bounded buffers and document-local rollback records for temporary page patches, with rollback attempted when enabled-window access ends or switches.
 
 ## Chrome Web Store Limited Use statement
 

package/README.md

@@ -4,7 +4,7 @@
 
 > **Chrome Web Store:** Install `Browser Bridge (BBX)` from the [Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie). For local or custom builds, use the unpacked install flow in [docs/unpacked-extension.md](https://github.com/koltyakov/browser-bridge/blob/main/docs/unpacked-extension.md).
 
-A local bridge between your coding agent and a real Chrome tab. Browser Bridge gives the agent structured access to DOM, styles, layout, console, network, and reversible patches - starting from the actual tab you already have open, with all its real state intact.
+A local bridge between your coding agent and a real Chrome tab. Browser Bridge gives the agent structured access to DOM, styles, layout, console, network, accessibility data, reliable browser input, explicit JavaScript dialog handling, and reversible patches - starting from the actual tab you already have open, with all its real state intact.
 
 See [Quickstart](https://github.com/koltyakov/browser-bridge/blob/main/docs/quickstart.md) to get started in another repo, or browse the rest of the guides in [docs/index.md](https://github.com/koltyakov/browser-bridge/blob/main/docs/index.md).
 
@@ -93,6 +93,7 @@ Managed installs support OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Open
 ## What it's for
 
 - Debugging a UI on `localhost`: read DOM, computed styles, layout, console logs, and network state without a screenshot
+- Exporting sanitized, metadata-only HAR 1.2 evidence after explicitly capturing a network reproduction
 - Verifying a code change actually rendered the expected result in Chrome
 - Patching the live page to prove a fix visually, then moving it into source and rolling the patch back
 - Running structured browser checks from any local agent or IDE, not just one AI product
@@ -101,16 +102,17 @@ Managed installs support OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Open
 
 Most adjacent tools optimize for different goals. [Playwright](https://playwright.dev/) and headless automation stacks are excellent for deterministic tests and CI - but they start from a clean browser context by design. [Claude in Chrome](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) is great for integrated Claude workflows, and the [Codex extension](https://chromewebstore.google.com/detail/codex/hehggadaopoacecdllhhajmbjkdcmajg) is a great option if you use Codex, but both are vendor-specific. Generic MCP browser servers offer broad control without the developer-focused depth.
 
-Browser Bridge is optimized for the opposite starting point: **inspect the state that already exists** in a real tab - logged-in sessions, feature flags, seeded storage, SPA state - use structured reads to understand it, test a patch in place, then fix the source. It's open-source, agent-agnostic, and scoped to explicit tab sessions rather than ambient browser control.
+Browser Bridge is optimized for the opposite starting point: **inspect the state that already exists** in a real tab - logged-in sessions, feature flags, seeded storage, SPA state - use structured reads to understand it, test a patch in place, then fix the source. It's open-source, agent-agnostic, and scoped to one explicitly enabled browser window rather than ambient browser control.
 
 ## Setup
 
 1. Install [Browser Bridge from the Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie) in Chrome or another Chromium-based browser
 2. `npm install -g @browserbridge/bbx` - installs the CLI and native host
 3. Run `bbx install` (Chromium on Linux, Chrome elsewhere), or target a specific browser with `bbx install --browser chrome`, `bbx install --browser edge`, `bbx install --browser brave`, `bbx install --browser chromium`, or `bbx install --browser arc`
-4. In the extension side panel, install MCP or CLI (skill) for your agent of choice
-5. Enable Browser Bridge for the browser window you want to inspect/control with the AI agent
-6. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the installed Browser Bridge skill in CLI mode (`/browser-bridge`, `browser-bridge`, or the client-specific skill trigger)
+4. Optionally run `bbx config set auto-update compatible` to keep the global CLI on the highest stable npm release supported by the connected extension
+5. In the extension side panel, install MCP or CLI (skill) for your agent of choice
+6. Enable Browser Bridge for the browser window you want to inspect/control with the AI agent
+7. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the installed Browser Bridge skill in CLI mode (`/browser-bridge`, `browser-bridge`, or the client-specific skill trigger)
 
 On Ubuntu, Chromium is commonly installed as a strict snap, and Flatpak Chromium is similarly sandboxed. If native messaging stays disconnected there, use a non-sandboxed Chromium-based browser such as Google Chrome, Brave, or Edge.
 
@@ -120,10 +122,19 @@ MCP mode is self-contained: the server exposes tools and startup instructions, s
 
 - The extension is scoped to one explicitly enabled Chrome window at a time - no ambient browser access
 - Requests default to the active tab in that window unless a tab is targeted explicitly
-- Sessions are tab and origin scoped, auto-refreshed when possible
-- All patch operations are reversible and session-scoped
+- Targeted input actions reject hidden, disabled, ambiguous, stale, or obscured targets instead of silently guessing; their responses report the resolution and DOM/CDP execution path (`cdp_press_key` and `scroll_into_view` use separate contracts)
+- Native pointer/text input, dialog handling, all-resource network capture, accessibility trees, screenshots, and raw CDP reads use the existing debugger permission only when requested
+- HAR export is a read of an already armed CDP capture: start capture, reproduce, export, then stop. Export never starts, stops, or clears capture, and omits headers, cookies, bodies, authorization values, and unsupported size/timing detail
+- HAR and screenshot artifacts are opaque, owner-scoped daemon handles with a five-minute lifetime and no browser-host path; CLI capture commands download, verify, delete, and write them on the CLI host
+- Element references are document-local and strict by default; stale input recovery is opt-in, same-document, requires one strong unique semantic match, and fails safely when its bounded scan cannot prove uniqueness
+- Semantic DOM baselines provide explicit create/compare/describe/release verification without modifying the page; compact snapshots stay memory-only, expire after five minutes, and are invalidated by navigation or access teardown
+- Patches keep per-document rollback history and Browser Bridge attempts best-effort rollback when window access is disabled or switched; committing the patch baseline keeps current changes but discards their rollback history
+- URL waits observe full navigation and same-document SPA changes, and report the final URL and observed navigation kind
 - Structured DOM/style/layout reads are the primary transport; screenshots are a fallback
+- Browser input dispatch does not prove the application accepted the intended change, so agents should verify with a wait or structured read
 - Open-ended investigation should start with structured reads on a smaller, lower-cost subagent when the client supports delegation
+- Recovery diagnostics use process-local five-minute counters for six fixed, content-free categories. `health.ping`, `daemon.metrics`, and `bbx doctor` expose no page data; three failures in the same category group within 60 seconds produce an active-loop warning and fixed recovery guidance
+- Performance reads are raw browser-maintained CDP counter point samples with browser-defined names and units, not Web Vitals or Browser Bridge navigation measurements
 - The native host daemon auto-starts on demand
 
 ## Documentation
@@ -139,7 +150,7 @@ MCP mode is self-contained: the server exposes tools and startup instructions, s
 
 ## Privacy
 
-Browser Bridge itself routes extension data locally through the Chrome extension, native host, and the local client you choose to connect. Browser Bridge does not operate a Browser Bridge cloud service.
+The extension and native host communicate on the browser machine, and local clients connect to that daemon by default. If you explicitly configure an authenticated remote destination, bridge results can travel over your user-provided SSH tunnel or network route to the selected client. Browser Bridge does not operate a Browser Bridge cloud service, and raw remote TCP is not presented as encrypted.
 
 Your connected agent or IDE may still forward tool calls or tool results to remote services under that product's own settings and privacy policy. See [PRIVACY.md](https://github.com/koltyakov/browser-bridge/blob/main/PRIVACY.md) for the Browser Bridge policy.
 

package/SECURITY.md

@@ -10,6 +10,13 @@ Only the latest version published to npm (`@browserbridge/bbx`) and the Chrome W
 receives security fixes. Older versions are not patched retroactively; upgrade to the
 latest release before reporting.
 
+The optional `compatible` npm auto-update policy follows the connected
+extension's advertised `major.minor` protocol line. It installs only stable
+versions of the fixed `@browserbridge/bbx` package, never downgrades, and runs
+only from a verified global npm installation. If an older extension line is
+still installed, this policy may intentionally select an older release than the
+latest security-supported version.
+
 ## Reporting a Vulnerability
 
 Please do **not** open a public GitHub issue for security vulnerabilities.
@@ -50,3 +57,8 @@ Out of scope:
 - Proxy mode (LAN exposure) is opt-in via `bbx proxy enable` and always provisions a
   token; an invalid `bindHost` in the config rejects the config rather than widening
   the bind address.
+- Incidental persisted activity and daemon logs recursively redact sensitive keys,
+  URL credentials/fragments/query values, and local path prefixes.
+- Ordinary Web Storage reads return key/presence metadata only. The separate
+  `sensitive.read` method requires one exact key, is excluded from batches and
+  automatic retries, and returns a value whole or fails atomically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.7.8",
+  "version": "1.9.0",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -55,8 +55,9 @@
     "lint": "oxlint . && oxfmt --check .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
-    "test:runtime": "node --test",
-    "test": "c8 node --test",
+    "fixture:browser": "node tests/fixtures/browser-reliability/server.mjs",
+    "test:runtime": "node --import tsx --test packages/*/test/*.test.ts packages/integration-tests/*.test.ts tests/fixtures/*/*.test.ts",
+    "test": "c8 node --import tsx --test packages/*/test/*.test.ts packages/integration-tests/*.test.ts tests/fixtures/*/*.test.ts",
     "coverage": "c8 report --reporter=text --reporter=text-summary",
     "coverage:review": "c8 report --reporter=json-summary && node scripts/review-coverage.mjs",
     "coverage:check": "c8 check-coverage --lines 92 --branches 83",
@@ -73,17 +74,25 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@mozilla/readability": "^0.6.0",
+    "linkedom": "^0.18.13",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/chrome": "^0.2.2",
     "@types/node": "^26.1.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "c8": "^12.0.0",
-    "linkedom": "^0.18.13",
-    "oxfmt": "^0.59.0",
-    "oxlint": "^1.74.0",
+    "har-schema": "^2.0.0",
+    "oxfmt": "^0.60.0",
+    "oxlint": "^1.75.0",
+    "tsx": "^4.23.1",
     "typescript": "^7.0.2"
   },
+  "overrides": {
+    "@hono/node-server": "2.0.11"
+  },
   "engines": {
     "node": ">=20"
   }

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

@@ -60,6 +60,65 @@ export function extractTabFlag(args) {
   return { tabId, rest };
 }
 
+/**
+ * @param {string[]} args
+ * @returns {{ format: 'png' | 'jpeg' | 'webp', quality: number | undefined, rest: string[] }}
+ */
+export function extractScreenshotFlags(args) {
+  const rest = [...args];
+  const formatIndex = rest.indexOf('--format');
+  const rawFormat = formatIndex === -1 ? 'png' : rest[formatIndex + 1];
+  if (rawFormat !== 'png' && rawFormat !== 'jpeg' && rawFormat !== 'webp') {
+    throw new Error('--format must be png, jpeg, or webp.');
+  }
+  if (formatIndex !== -1) rest.splice(formatIndex, 2);
+  const qualityIndex = rest.indexOf('--quality');
+  let quality;
+  if (qualityIndex !== -1) {
+    quality = Number(rest[qualityIndex + 1]);
+    if (!Number.isInteger(quality) || quality < 0 || quality > 100) {
+      throw new Error('--quality must be an integer from 0 to 100.');
+    }
+    rest.splice(qualityIndex, 2);
+  }
+  return { format: rawFormat, quality, rest };
+}
+
+/**
+ * @param {string[]} args
+ * @returns {{ limit: number | undefined, urlPattern: string | undefined, delivery: 'inline' | 'artifact' | 'auto', rest: string[] }}
+ */
+export function extractHarFlags(args) {
+  const rest = [...args];
+  const limitIndex = rest.indexOf('--limit');
+  let limit;
+  if (limitIndex !== -1) {
+    limit = Number(rest[limitIndex + 1]);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+      throw new Error('--limit must be an integer from 1 to 200.');
+    }
+    rest.splice(limitIndex, 2);
+  }
+
+  const urlPatternIndex = rest.indexOf('--url-pattern');
+  const urlPattern = urlPatternIndex === -1 ? undefined : rest[urlPatternIndex + 1];
+  if (urlPatternIndex !== -1) {
+    if (!urlPattern || urlPattern.startsWith('--')) {
+      throw new Error('--url-pattern requires a value.');
+    }
+    rest.splice(urlPatternIndex, 2);
+  }
+
+  const deliveryIndex = rest.indexOf('--delivery');
+  const rawDelivery = deliveryIndex === -1 ? 'auto' : rest[deliveryIndex + 1];
+  if (rawDelivery !== 'inline' && rawDelivery !== 'artifact' && rawDelivery !== 'auto') {
+    throw new Error('--delivery must be inline, artifact, or auto.');
+  }
+  if (deliveryIndex !== -1) rest.splice(deliveryIndex, 2);
+
+  return { limit, urlPattern, delivery: rawDelivery, rest };
+}
+
 /**
  * @param {string[]} args
  * @returns {Promise<{ tabId: number | null, method: BridgeMethod, params: Record<string, unknown> }>}

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

@@ -2,6 +2,9 @@
 
 import {
   getProtocolVersion,
+  isBatchSafeBridgeCall,
+  MAX_BATCH_CALLS,
+  MAX_BATCH_CONCURRENCY,
   METHODS,
   summarizeBatchErrorItem,
   summarizeBatchResponseItem,
@@ -27,6 +30,10 @@ import { requestBridge } from './runtime.js';
  * }} InvalidBatchItem
  */
 
+/**
+ * @typedef {{ method: BridgeMethod, params: Record<string, unknown>, tabId: number | null }} PreparedBatchCall
+ */
+
 /**
  * @typedef {ReturnType<typeof summarizeBatchResponseItem>
  *   | ReturnType<typeof summarizeBatchErrorItem>
@@ -59,8 +66,8 @@ function invalidBatchItem(method, message) {
 }
 
 /**
- * Parse and execute `bbx batch '[...]'`: validate each call, run them in
- * parallel against the bridge, and return per-call summary items.
+ * Parse and execute `bbx batch '[...]'`: validate read-only calls, run them
+ * with bounded concurrency, and return ordered per-call summary items.
  *
  * @param {import('./client.js').BridgeClient} client
  * @param {string | undefined} input - Raw JSON array argument
@@ -80,61 +87,117 @@ export async function runBatchCalls(client, input, source) {
   if (!Array.isArray(calls)) {
     throw new Error('Batch input must be a JSON array.');
   }
-  if (!client.connected) {
-    await client.connect();
+  if (calls.length === 0 || calls.length > MAX_BATCH_CALLS) {
+    throw new Error(`Batch input must contain between 1 and ${MAX_BATCH_CALLS} calls.`);
+  }
+  const prepared = calls.map((call) => prepareBatchCall(call));
+  if (prepared.some((item) => 'error' in item)) {
+    return prepared.map((item) =>
+      'error' in item
+        ? item.error
+        : invalidBatchItem(
+            item.value.method,
+            'Batch was not executed because another call failed validation.'
+          )
+    );
+  }
+  const validPrepared = /** @type {Array<{ value: PreparedBatchCall }>} */ (prepared);
+  if (!client.connected) await client.connect();
+  return mapWithConcurrency(validPrepared, MAX_BATCH_CONCURRENCY, async (item) => {
+    const { method, params, tabId } = item.value;
+    const startTime = Date.now();
+    try {
+      const response = await requestBridge(client, method, params, {
+        tabId,
+        source,
+      });
+      return summarizeBatchResponseItem({
+        method,
+        tabId,
+        response,
+        durationMs: Date.now() - startTime,
+      });
+    } catch (err) {
+      return summarizeBatchErrorItem({
+        method,
+        tabId,
+        error: err,
+        durationMs: Date.now() - startTime,
+      });
+    }
+  });
+}
+
+/**
+ * @param {unknown} call
+ * @returns {{ value: PreparedBatchCall } | { error: InvalidBatchItem }}
+ */
+function prepareBatchCall(call) {
+  if (!call || typeof call !== 'object' || Array.isArray(call)) {
+    return { error: invalidBatchItem('', 'Each batch call needs a method.') };
+  }
+  const batchCall = /** @type {Record<string, unknown>} */ (call);
+  if (typeof batchCall.method !== 'string') {
+    return { error: invalidBatchItem('', 'Each batch call needs a method.') };
+  }
+  if (!METHODS.includes(/** @type {BridgeMethod} */ (batchCall.method))) {
+    return {
+      error: invalidBatchItem(batchCall.method, `Unknown bridge method "${batchCall.method}".`),
+    };
+  }
+  const method = /** @type {BridgeMethod} */ (batchCall.method);
+  if (method === 'sensitive.read') {
+    return {
+      error: invalidBatchItem(
+        method,
+        'sensitive.read is never allowed in batch execution. Call it sequentially.'
+      ),
+    };
+  }
+  if (
+    batchCall.params !== undefined &&
+    (!batchCall.params || typeof batchCall.params !== 'object' || Array.isArray(batchCall.params))
+  ) {
+    return { error: invalidBatchItem(method, 'Batch call params must be a JSON object.') };
+  }
+  const params =
+    batchCall.params === undefined ? {} : /** @type {Record<string, unknown>} */ (batchCall.params);
+  if (!isBatchSafeBridgeCall(method, params)) {
+    return {
+      error: invalidBatchItem(
+        method,
+        `${method} is not safe for batch execution. Call it sequentially.`
+      ),
+    };
   }
-  return Promise.all(
-    calls.map(async (call) => {
-      if (!call || typeof call !== 'object' || Array.isArray(call)) {
-        return invalidBatchItem('', 'Each batch call needs a method.');
-      }
-      const batchCall = /** @type {Record<string, unknown>} */ (call);
-      if (typeof batchCall.method !== 'string') {
-        return invalidBatchItem('', 'Each batch call needs a method.');
-      }
-      if (!METHODS.includes(/** @type {BridgeMethod} */ (batchCall.method))) {
-        return invalidBatchItem(batchCall.method, `Unknown bridge method "${batchCall.method}".`);
-      }
-      const method = /** @type {BridgeMethod} */ (batchCall.method);
-      if (
-        batchCall.params !== undefined &&
-        (!batchCall.params ||
-          typeof batchCall.params !== 'object' ||
-          Array.isArray(batchCall.params))
-      ) {
-        return invalidBatchItem(method, 'Batch call params must be a JSON object.');
-      }
-      const params =
-        batchCall.params === undefined
-          ? {}
-          : /** @type {Record<string, unknown>} */ (batchCall.params);
-      const tabId =
-        methodNeedsTab(method) &&
-        typeof batchCall.tabId === 'number' &&
-        Number.isInteger(batchCall.tabId) &&
-        batchCall.tabId > 0
-          ? batchCall.tabId
-          : null;
-      const startTime = Date.now();
-      try {
-        const response = await requestBridge(client, method, params, {
-          tabId,
-          source,
-        });
-        return summarizeBatchResponseItem({
-          method,
-          tabId,
-          response,
-          durationMs: Date.now() - startTime,
-        });
-      } catch (err) {
-        return summarizeBatchErrorItem({
-          method,
-          tabId,
-          error: err,
-          durationMs: Date.now() - startTime,
-        });
-      }
-    })
-  );
+  const tabId =
+    methodNeedsTab(method) &&
+    typeof batchCall.tabId === 'number' &&
+    Number.isInteger(batchCall.tabId) &&
+    batchCall.tabId > 0
+      ? batchCall.tabId
+      : null;
+  return { value: { method, params, tabId } };
+}
+
+/**
+ * @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;
 }

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

@@ -28,10 +28,17 @@ export async function printSummary(response, method) {
 
 /**
  * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @param {string} [method]
  * @returns {void}
  */
-export function printCallResponse(response) {
+export function printCallResponse(response, method) {
   if (response.ok) {
+    if (method === 'sensitive.read') {
+      process.stdout.write(
+        `${JSON.stringify(response.result, null, process.stdout.isTTY ? 2 : undefined)}\n`
+      );
+      return;
+    }
     printJson(response.result);
     return;
   }