@browserbridge/bbx 1.8.0 → 1.9.0

package/packages/protocol/src/recovery-telemetry.js

@@ -0,0 +1,302 @@
+// @ts-check
+
+export const RECOVERY_WINDOW_MS = 5 * 60 * 1000;
+export const RECOVERY_BUCKET_MS = 5 * 1000;
+export const RECOVERY_LOOP_WINDOW_MS = 60 * 1000;
+export const RECOVERY_LOOP_THRESHOLD = 3;
+export const RECOVERY_MAX_GROUPS = 64;
+export const RECOVERY_PUBLIC_COUNT_LIMIT = 10_000;
+
+/** @type {readonly import('./types.js').RecoveryEventKind[]} */
+export const RECOVERY_EVENT_KINDS = Object.freeze([
+  'automatic_mcp_retry',
+  'stale_ref_recovery',
+  'debugger_reattach',
+  'content_script_reinjection',
+  'native_host_reconnect',
+  'request_outcome',
+]);
+
+const RECOVERY_EVENT_KIND_SET = new Set(RECOVERY_EVENT_KINDS);
+const BUCKET_COUNT = RECOVERY_WINDOW_MS / RECOVERY_BUCKET_MS + 1;
+
+/**
+ * Fixed-bucket, process-local recovery telemetry. Group names are used only to
+ * detect repeated failures and are never included in public snapshots.
+ */
+export class RecoveryTelemetryCollector {
+  /** @param {{ now?: () => number }} [options] */
+  constructor({ now = Date.now } = {}) {
+    this.now = now;
+    /** @type {Array<{ start: number, events: Map<import('./types.js').RecoveryEventKind, { attempts: number, successes: number, failures: number, lastEventAt: number }> } | null>} */
+    this.buckets = Array.from({ length: BUCKET_COUNT }, () => null);
+    /** @type {Map<string, { failures: [number, number, number], next: number, count: number, touchedAt: number, kind: import('./types.js').RecoveryEventKind }>} */
+    this.groups = new Map();
+  }
+
+  /**
+   * @param {import('./types.js').RecoveryEventKind} kind
+   * @param {'success' | 'failure'} outcome
+   * @param {string} [group='default']
+   */
+  record(kind, outcome, group = 'default') {
+    if (!RECOVERY_EVENT_KIND_SET.has(kind)) return;
+    const now = normalizeNow(this.now());
+    const start = Math.floor(now / RECOVERY_BUCKET_MS) * RECOVERY_BUCKET_MS;
+    const index = Math.floor(start / RECOVERY_BUCKET_MS) % BUCKET_COUNT;
+    let bucket = this.buckets[index];
+    if (!bucket || bucket.start !== start) {
+      bucket = { start, events: new Map() };
+      this.buckets[index] = bucket;
+    }
+    const event = bucket.events.get(kind) ?? {
+      attempts: 0,
+      successes: 0,
+      failures: 0,
+      lastEventAt: 0,
+    };
+    event.attempts += 1;
+    event.successes += outcome === 'success' ? 1 : 0;
+    event.failures += outcome === 'failure' ? 1 : 0;
+    event.lastEventAt = now;
+    bucket.events.set(kind, event);
+
+    this.pruneGroups(now);
+    if (outcome !== 'failure') return;
+    const groupKey = `${kind}\u0000${group}`;
+    let state = this.groups.get(groupKey);
+    if (!state) {
+      while (this.groups.size >= RECOVERY_MAX_GROUPS) {
+        const oldest = [...this.groups].reduce((left, right) =>
+          left[1].touchedAt <= right[1].touchedAt ? left : right
+        );
+        this.groups.delete(oldest[0]);
+      }
+      state = {
+        failures: [0, 0, 0],
+        next: 0,
+        count: 0,
+        touchedAt: now,
+        kind,
+      };
+      this.groups.set(groupKey, state);
+    }
+    state.failures[state.next] = now;
+    state.next = (state.next + 1) % RECOVERY_LOOP_THRESHOLD;
+    state.count = Math.min(RECOVERY_LOOP_THRESHOLD, state.count + 1);
+    state.touchedAt = now;
+  }
+
+  /** @param {import('./types.js').RecoveryScope} scope */
+  snapshot(scope) {
+    const now = normalizeNow(this.now());
+    this.pruneGroups(now);
+    /** @type {Record<import('./types.js').RecoveryEventKind, import('./types.js').RecoveryEventSummary>} */
+    const events =
+      /** @type {Record<import('./types.js').RecoveryEventKind, import('./types.js').RecoveryEventSummary>} */ ({});
+    for (const kind of RECOVERY_EVENT_KINDS) {
+      let attempts = 0;
+      let successes = 0;
+      let failures = 0;
+      let lastEventAt = 0;
+      for (const bucket of this.buckets) {
+        if (
+          !bucket ||
+          bucket.start + RECOVERY_BUCKET_MS <= now - RECOVERY_WINDOW_MS ||
+          bucket.start > now
+        ) {
+          continue;
+        }
+        const event = bucket.events.get(kind);
+        if (!event) continue;
+        attempts += event.attempts;
+        successes += event.successes;
+        failures += event.failures;
+        lastEventAt = Math.max(lastEventAt, event.lastEventAt);
+      }
+      const activeLoop = [...this.groups.values()].some((group) => {
+        if (group.kind !== kind || group.count < RECOVERY_LOOP_THRESHOLD) return false;
+        return group.failures.every((at) => at >= now - RECOVERY_LOOP_WINDOW_MS && at <= now);
+      });
+      events[kind] = createPublicEventSummary(
+        attempts,
+        successes,
+        failures,
+        activeLoop,
+        lastEventAt
+      );
+    }
+    return {
+      scope,
+      windowMs: RECOVERY_WINDOW_MS,
+      bucketMs: RECOVERY_BUCKET_MS,
+      loopWindowMs: RECOVERY_LOOP_WINDOW_MS,
+      loopThreshold: RECOVERY_LOOP_THRESHOLD,
+      asOf: now,
+      activeLoop: RECOVERY_EVENT_KINDS.some((kind) => events[kind].activeLoop),
+      events,
+    };
+  }
+
+  /** @param {number} now */
+  pruneGroups(now) {
+    const cutoff = now - RECOVERY_LOOP_WINDOW_MS;
+    for (const [key, group] of this.groups) {
+      let recent = 0;
+      for (let index = 0; index < group.count; index += 1) {
+        const at = group.failures[index];
+        if (at >= cutoff && at <= now) recent += 1;
+      }
+      if (recent === 0) this.groups.delete(key);
+    }
+  }
+}
+
+/**
+ * Strictly reconstruct a public summary from an untrusted transport value.
+ * @param {unknown} value
+ * @param {import('./types.js').RecoveryScope} expectedScope
+ * @returns {import('./types.js').RecoveryTelemetrySummary | null}
+ */
+export function normalizeRecoveryTelemetrySummary(value, expectedScope) {
+  const source = asRecord(value);
+  if (!source || source.scope !== expectedScope) return null;
+  const asOf = strictTimestamp(source.asOf);
+  if (asOf === null) return null;
+  const eventsSource = asRecord(source.events);
+  if (!eventsSource) return null;
+  /** @type {Record<import('./types.js').RecoveryEventKind, import('./types.js').RecoveryEventSummary>} */
+  const events =
+    /** @type {Record<import('./types.js').RecoveryEventKind, import('./types.js').RecoveryEventSummary>} */ ({});
+  for (const kind of RECOVERY_EVENT_KINDS) {
+    const event = asRecord(eventsSource[kind]);
+    if (!event) return null;
+    const attempts = rawCount(event.attempts);
+    const successes = rawCount(event.successes);
+    const failures = rawCount(event.failures);
+    const pending = rawCount(event.pending);
+    const saturated = event.saturated;
+    if (
+      attempts === null ||
+      successes === null ||
+      failures === null ||
+      pending === null ||
+      typeof saturated !== 'boolean' ||
+      successes + failures + pending !== attempts ||
+      (saturated
+        ? attempts !== RECOVERY_PUBLIC_COUNT_LIMIT
+        : attempts > RECOVERY_PUBLIC_COUNT_LIMIT)
+    ) {
+      return null;
+    }
+    const lastEventAt = normalizeLastEventAt(event.lastEventAt, attempts, asOf);
+    if (lastEventAt === undefined) return null;
+    events[kind] = {
+      attempts,
+      successes,
+      failures,
+      pending,
+      saturated,
+      successRate: saturated || attempts === 0 ? null : roundRate(successes / attempts),
+      failureRate: saturated || attempts === 0 ? null : roundRate(failures / attempts),
+      activeLoop: event.activeLoop === true && failures >= RECOVERY_LOOP_THRESHOLD,
+      lastEventAt,
+    };
+  }
+  return {
+    scope: expectedScope,
+    windowMs: RECOVERY_WINDOW_MS,
+    bucketMs: RECOVERY_BUCKET_MS,
+    loopWindowMs: RECOVERY_LOOP_WINDOW_MS,
+    loopThreshold: RECOVERY_LOOP_THRESHOLD,
+    asOf,
+    activeLoop: RECOVERY_EVENT_KINDS.some((kind) => events[kind].activeLoop),
+    events,
+  };
+}
+
+/** @param {unknown} value */
+function asRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? /** @type {Record<string, unknown>} */ (value)
+    : null;
+}
+
+/** @param {unknown} value @returns {number | null} */
+function rawCount(value) {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+/** @param {unknown} value @returns {number | null} */
+function strictTimestamp(value) {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+/** @param {number} value */
+function normalizeNow(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} attempts
+ * @param {number} asOf
+ * @returns {number | null | undefined}
+ */
+function normalizeLastEventAt(value, attempts, asOf) {
+  if (attempts === 0) return value === null ? null : undefined;
+  const timestamp = strictTimestamp(value);
+  if (
+    timestamp === null ||
+    timestamp > asOf ||
+    timestamp < asOf - RECOVERY_WINDOW_MS - RECOVERY_BUCKET_MS
+  ) {
+    return undefined;
+  }
+  return timestamp;
+}
+
+/** @param {number} value */
+function roundRate(value) {
+  return Math.round(value * 10_000) / 10_000;
+}
+
+/**
+ * @param {number} attempts
+ * @param {number} successes
+ * @param {number} failures
+ * @param {boolean} activeLoop
+ * @param {number} lastEventAt
+ * @returns {import('./types.js').RecoveryEventSummary}
+ */
+function createPublicEventSummary(attempts, successes, failures, activeLoop, lastEventAt) {
+  if (attempts <= RECOVERY_PUBLIC_COUNT_LIMIT) {
+    return {
+      attempts,
+      successes,
+      failures,
+      pending: 0,
+      saturated: false,
+      successRate: attempts > 0 ? roundRate(successes / attempts) : null,
+      failureRate: attempts > 0 ? roundRate(failures / attempts) : null,
+      activeLoop,
+      lastEventAt: attempts > 0 ? lastEventAt : null,
+    };
+  }
+  const proportionalFailures = Math.floor((failures / attempts) * RECOVERY_PUBLIC_COUNT_LIMIT);
+  const cappedFailures = Math.min(
+    RECOVERY_PUBLIC_COUNT_LIMIT,
+    Math.max(activeLoop ? RECOVERY_LOOP_THRESHOLD : 0, proportionalFailures)
+  );
+  return {
+    attempts: RECOVERY_PUBLIC_COUNT_LIMIT,
+    successes: RECOVERY_PUBLIC_COUNT_LIMIT - cappedFailures,
+    failures: cappedFailures,
+    pending: 0,
+    saturated: true,
+    successRate: null,
+    failureRate: null,
+    activeLoop,
+    lastEventAt,
+  };
+}

package/packages/protocol/src/registry.js

@@ -40,6 +40,7 @@ const METHOD_POLICIES = Object.freeze({
     capability: CAPABILITIES.NETWORK_INTERCEPT,
     debuggerBacked: true,
   }),
+  sensitiveRead: Object.freeze({ capability: CAPABILITIES.SENSITIVE_READ }),
   navigationControl: Object.freeze({ capability: CAPABILITIES.NAVIGATION_CONTROL }),
   navigationControlDebugger: Object.freeze({
     capability: CAPABILITIES.NAVIGATION_CONTROL,
@@ -110,12 +111,15 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
     'Inspect or explicitly act on the current JavaScript dialog. expectedDialogId is only a stale-decision check immediately before dispatch; Chrome cannot bind the CDP command atomically to that identifier.',
   'page.wait_for_load_state':
     'Wait for truthful tab-complete state and/or an event-aware URL condition.',
-  'page.get_storage': 'Read local or session storage values.',
+  'page.get_storage': 'Read local or session storage key metadata without values.',
+  'sensitive.read': 'Deliberately read one exact local or session storage value.',
   'page.get_text': 'Read bounded visible text from the page.',
   'page.extract_content':
     'Extract bounded semantic page content as text or Markdown without returning source HTML.',
   'page.get_network':
     'Read buffered fetch/XHR activity or explicitly manage bounded all-resource CDP capture.',
+  'network.export_har':
+    'Export bounded captured network evidence as a HAR 1.2 document, inline or as a daemon-owned artifact.',
   'network.intercept.add': 'Add a request interception rule (CDP Fetch domain).',
   'network.intercept.remove': 'Remove a request interception rule by ID.',
   'network.intercept.list': 'List active interception rules.',
@@ -125,6 +129,10 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'navigation.go_back': 'Navigate backward in tab history.',
   'navigation.go_forward': 'Navigate forward in tab history.',
   'dom.query': 'Query a DOM subtree and return compact node summaries.',
+  'dom.baseline.create': 'Create a short-lived compact semantic DOM baseline for later comparison.',
+  'dom.baseline.compare': 'Compare the current DOM with a retained semantic baseline.',
+  'dom.baseline.describe': 'Describe a retained semantic DOM baseline and its scope.',
+  'dom.baseline.release': 'Release a retained semantic DOM baseline.',
   'dom.describe': 'Describe one element by elementRef.',
   'dom.get_text': 'Read bounded text for one element.',
   'dom.get_attributes': 'Read selected attributes for one element.',
@@ -156,6 +164,8 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'screenshot.capture_region': 'Capture a screenshot of a viewport region.',
   'screenshot.capture_element': 'Capture a screenshot of one element.',
   'screenshot.capture_full_page': 'Capture a full-page screenshot beyond the viewport.',
+  'artifact.read': 'Read one bounded chunk from a daemon-owned artifact.',
+  'artifact.delete': 'Delete one daemon-owned artifact.',
   'patch.apply_styles': 'Apply a reversible inline style patch.',
   'patch.apply_dom': 'Apply a reversible DOM patch.',
   'patch.list': 'List active reversible patches.',
@@ -167,7 +177,8 @@ const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'cdp.get_box_model': 'Read a CDP box model for a node.',
   'cdp.get_computed_styles_for_node': 'Read CDP computed styles for a node.',
   'cdp.dispatch_key_event': 'Dispatch a key press through Chrome DevTools Protocol input.',
-  'performance.get_metrics': 'Read browser performance metrics.',
+  'performance.get_metrics':
+    'Read a raw Chrome/CDP counter point sample; names and units vary, and BBX measures no navigation window, LCP, CLS, or INP.',
   'log.tail': 'Tail recent bridge log entries.',
   'health.ping': 'Check daemon, extension, and access-routing health.',
   'daemon.metrics': 'Daemon health and performance metrics.',
@@ -304,6 +315,14 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'low',
     METHOD_POLICIES.pageRead
   ),
+  'sensitive.read': createRegistryEntry(
+    'sensitive.read',
+    'sensitive',
+    true,
+    ['source', 'key'],
+    'low',
+    METHOD_POLICIES.sensitiveRead
+  ),
   'page.get_text': createRegistryEntry(
     'page.get_text',
     'page',
@@ -328,6 +347,14 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'low',
     METHOD_POLICIES.networkRead
   ),
+  'network.export_har': createRegistryEntry(
+    'network.export_har',
+    'page',
+    true,
+    ['limit', 'urlPattern', 'delivery'],
+    'moderate',
+    METHOD_POLICIES.networkRead
+  ),
   // network intercept - moderate (holds debugger session)
   'network.intercept.add': createRegistryEntry(
     'network.intercept.add',
@@ -411,6 +438,38 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'low',
     METHOD_POLICIES.domRead
   ),
+  'dom.baseline.create': createRegistryEntry(
+    'dom.baseline.create',
+    'inspect',
+    true,
+    ['selector', 'maxNodes', 'maxDepth', 'textBudget', 'attributeAllowlist'],
+    'low',
+    METHOD_POLICIES.domRead
+  ),
+  'dom.baseline.compare': createRegistryEntry(
+    'dom.baseline.compare',
+    'inspect',
+    true,
+    ['baselineId', 'maxChanges'],
+    'low',
+    METHOD_POLICIES.domRead
+  ),
+  'dom.baseline.describe': createRegistryEntry(
+    'dom.baseline.describe',
+    'inspect',
+    true,
+    ['baselineId'],
+    'low',
+    METHOD_POLICIES.domRead
+  ),
+  'dom.baseline.release': createRegistryEntry(
+    'dom.baseline.release',
+    'inspect',
+    true,
+    ['baselineId'],
+    'low',
+    METHOD_POLICIES.domRead
+  ),
   'dom.describe': createRegistryEntry(
     'dom.describe',
     'inspect',
@@ -612,7 +671,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'screenshot.capture_region',
     'capture',
     true,
-    ['x', 'y', 'width', 'height', 'format', 'quality'],
+    ['x', 'y', 'width', 'height', 'format', 'quality', 'delivery', 'scale'],
     'high',
     METHOD_POLICIES.screenshotPartialDebugger
   ),
@@ -620,7 +679,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'screenshot.capture_element',
     'capture',
     true,
-    ['elementRef', 'format', 'quality'],
+    ['elementRef', 'format', 'quality', 'delivery', 'scale'],
     'high',
     METHOD_POLICIES.screenshotPartialDebugger
   ),
@@ -628,10 +687,24 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'screenshot.capture_full_page',
     'capture',
     true,
-    ['format', 'quality'],
+    ['format', 'quality', 'delivery', 'scale'],
     'high',
     METHOD_POLICIES.screenshotPartialDebugger
   ),
+  'artifact.read': createRegistryEntry(
+    'artifact.read',
+    'artifact',
+    false,
+    ['artifactId', 'offset', 'maxBytes'],
+    'low'
+  ),
+  'artifact.delete': createRegistryEntry(
+    'artifact.delete',
+    'artifact',
+    false,
+    ['artifactId'],
+    'low'
+  ),
   // patch - moderate (side effects)
   'patch.apply_styles': createRegistryEntry(
     'patch.apply_styles',
@@ -686,7 +759,7 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'cdp.get_dom_snapshot',
     'cdp',
     true,
-    [],
+    ['computedStyles'],
     'high',
     METHOD_POLICIES.cdpDomSnapshotDebugger
   ),
@@ -733,6 +806,70 @@ export const BRIDGE_METHODS = Object.freeze(
 /** @type {ReadonlySet<import('./types.js').BridgeMethod>} */
 export const METHOD_SET = new Set(BRIDGE_METHODS);
 
+/** Methods whose read-only forms may run concurrently without side effects. */
+const BATCH_SAFE_METHODS = new Set([
+  'health.ping',
+  'daemon.metrics',
+  'tabs.list',
+  'skill.get_runtime_context',
+  'setup.get_status',
+  'log.tail',
+  'page.get_state',
+  'page.get_console',
+  'page.wait_for_load_state',
+  'page.get_storage',
+  'page.get_text',
+  'page.extract_content',
+  'page.get_network',
+  'dom.query',
+  'dom.baseline.compare',
+  'dom.baseline.describe',
+  'dom.describe',
+  'dom.get_text',
+  'dom.get_attributes',
+  'dom.wait_for',
+  'dom.find_by_text',
+  'dom.find_by_role',
+  'dom.get_html',
+  'dom.get_accessibility_tree',
+  'layout.get_box_model',
+  'layout.hit_test',
+  'styles.get_computed',
+  'styles.get_matched_rules',
+  'network.intercept.list',
+  'patch.list',
+  'performance.get_metrics',
+]);
+
+/**
+ * Classify a normalized or raw bridge call for parallel read-only execution.
+ * Parameter checks deliberately reject malformed truthy mutation flags before
+ * protocol normalization can coerce them.
+ *
+ * @param {import('./types.js').BridgeMethod} method
+ * @param {Record<string, unknown>} [params]
+ * @returns {boolean}
+ */
+export function isBatchSafeBridgeCall(method, params = {}) {
+  if (!BATCH_SAFE_METHODS.has(method)) return false;
+  if (
+    (method === 'page.get_console' || method === 'page.get_network') &&
+    params.clear !== undefined &&
+    params.clear !== false
+  ) {
+    return false;
+  }
+  if (
+    method === 'page.get_network' &&
+    params.source === 'cdp' &&
+    params.capture !== undefined &&
+    params.capture !== 'read'
+  ) {
+    return false;
+  }
+  return true;
+}
+
 /**
  * @returns {Record<string, import('./types.js').BridgeMethod[]>}
  */