@browserbridge/bbx 1.9.0 → 1.10.0

package/packages/protocol/src/budget-presets.js

@@ -0,0 +1,182 @@
+// @ts-check
+
+/**
+ * Shared budget-preset merge helpers. Presets fill gaps in method params;
+ * explicit per-call params always win. Used by both the MCP server and the
+ * agent CLI so `budgetPreset`/`--preset` behave identically.
+ */
+
+import {
+  DEFAULT_CONSOLE_LIMIT,
+  DEFAULT_HAR_LIMIT,
+  DEFAULT_LOG_TAIL_LIMIT,
+  DEFAULT_MAX_HTML_LENGTH,
+  DEFAULT_NETWORK_LIMIT,
+  DEFAULT_PAGE_TEXT_BUDGET,
+  getBudgetPreset,
+  isBudgetPresetName,
+} from './defaults.js';
+
+/**
+ * @param {unknown} value
+ * @returns {import('./defaults.js').BudgetPresetName | null}
+ */
+export function getBudgetPresetName(value) {
+  return isBudgetPresetName(value) ? value : null;
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, maxNodes?: unknown, maxDepth?: unknown, textBudget?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyTreeBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const preset = getBudgetPreset(presetName);
+  return /** @type {T} */ ({
+    ...args,
+    maxNodes: args.maxNodes ?? preset.maxNodes,
+    maxDepth: args.maxDepth ?? preset.maxDepth,
+    textBudget: args.textBudget ?? preset.textBudget,
+  });
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, textBudget?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyTextBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const preset = getBudgetPreset(presetName);
+  return /** @type {T} */ ({
+    ...args,
+    textBudget: args.textBudget ?? preset.textBudget,
+  });
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, textBudget?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyPageTextBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const textBudgetByPreset = {
+    quick: 2000,
+    normal: DEFAULT_PAGE_TEXT_BUDGET,
+    deep: DEFAULT_PAGE_TEXT_BUDGET * 2,
+  };
+  return /** @type {T} */ ({
+    ...args,
+    textBudget: args.textBudget ?? textBudgetByPreset[presetName],
+  });
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, limit?: unknown }} T
+ * @param {T} args
+ * @param {{ quick: number, normal: number, deep: number }} defaults
+ * @returns {T}
+ */
+export function applyLimitBudgetPreset(args, defaults) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  return /** @type {T} */ ({
+    ...args,
+    limit: args.limit ?? defaults[presetName],
+  });
+}
+
+/**
+ * @template {{ budgetPreset?: unknown, maxLength?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyHtmlBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const maxLengthByPreset = {
+    quick: 600,
+    normal: DEFAULT_MAX_HTML_LENGTH,
+    deep: 6000,
+  };
+  return /** @type {T} */ ({
+    ...args,
+    maxLength: args.maxLength ?? maxLengthByPreset[presetName],
+  });
+}
+
+/**
+ * Apply a preset to method parameters before dispatch. Explicit method params
+ * always win over preset defaults.
+ *
+ * @param {import('./types.js').BridgeMethod} method
+ * @param {Record<string, unknown>} params
+ * @param {unknown} budgetPreset
+ * @returns {Record<string, unknown>}
+ */
+export function applyMethodBudgetPreset(method, params, budgetPreset) {
+  const args = { ...params, budgetPreset };
+  /** @type {Record<string, unknown>} */
+  let normalized = args;
+  if (
+    method === 'dom.query' ||
+    method === 'dom.get_accessibility_tree' ||
+    method === 'dom.baseline.create'
+  ) {
+    normalized = applyTreeBudgetPreset(args);
+  } else if (method === 'dom.baseline.compare') {
+    const preset = getBudgetPresetName(budgetPreset);
+    const defaults = { quick: 10, normal: 50, deep: 100 };
+    normalized = {
+      ...args,
+      maxChanges: params.maxChanges ?? (preset ? defaults[preset] : undefined),
+    };
+  } else if (method === 'dom.get_text') {
+    normalized = applyTextBudgetPreset(args);
+  } else if (method === 'dom.get_html') {
+    normalized = applyHtmlBudgetPreset(args);
+  } else if (method === 'page.get_text' || method === 'page.extract_content') {
+    normalized = applyPageTextBudgetPreset(args);
+  } else if (method === 'page.get_console') {
+    normalized = applyLimitBudgetPreset(args, {
+      quick: 10,
+      normal: DEFAULT_CONSOLE_LIMIT,
+      deep: 100,
+    });
+  } else if (method === 'page.get_network') {
+    normalized = applyLimitBudgetPreset(args, {
+      quick: 10,
+      normal: DEFAULT_NETWORK_LIMIT,
+      deep: 100,
+    });
+  } else if (method === 'network.export_har') {
+    normalized = applyLimitBudgetPreset(args, {
+      quick: 20,
+      normal: DEFAULT_HAR_LIMIT,
+      deep: 100,
+    });
+  } else if (method === 'log.tail') {
+    normalized = applyLimitBudgetPreset(args, {
+      quick: 10,
+      normal: DEFAULT_LOG_TAIL_LIMIT,
+      deep: 100,
+    });
+  }
+  const { budgetPreset: _budgetPreset, ...methodParams } = normalized;
+  return methodParams;
+}

package/packages/protocol/src/har.js

@@ -0,0 +1,34 @@
+// @ts-check
+
+/**
+ * Minimal structural validation for HAR 1.2 documents shared by the CLI and
+ * the MCP server. Only the envelope is validated (`log.version` and the
+ * `entries` array); deeper field checks are left to HAR consumers.
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {value is import('./types.js').HarLog}
+ */
+export function isHarLog(value) {
+  return Boolean(
+    value &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Reflect.get(value, 'version') === '1.2' &&
+    Array.isArray(Reflect.get(value, 'entries'))
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is import('./types.js').HarDocument}
+ */
+export function isHarDocument(value) {
+  return Boolean(
+    value &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    isHarLog(Reflect.get(value, 'log'))
+  );
+}

package/packages/protocol/src/index.js

@@ -4,10 +4,12 @@
  * Public protocol barrel for shared bridge helpers, errors, capabilities, and
  * request/response normalization utilities.
  */
+export * from './budget-presets.js';
 export * from './budget.js';
 export * from './capabilities.js';
 export * from './defaults.js';
 export * from './errors.js';
+export * from './har.js';
 export * from './incidental-sanitizer.js';
 export * from './json-lines.js';
 export * from './payload-cost.js';

package/packages/protocol/src/json-lines.js

@@ -7,7 +7,7 @@ import { MAX_JSON_LINE_BYTES } from './defaults.js';
  *
  * @param {import('node:net').Socket} socket
  * @param {(message: unknown) => void} onMessage
- * @param {{ maxLineBytes?: number, onProtocolError?: (error: Error) => void }} [options]
+ * @param {{ maxLineBytes?: number, onProtocolError?: (error: Error) => void, onInvalidLine?: (error: Error) => void }} [options]
  * @returns {void}
  */
 export function parseJsonLines(socket, onMessage, options = {}) {
@@ -50,8 +50,9 @@ export function parseJsonLines(socket, onMessage, options = {}) {
       }
       try {
         onMessage(JSON.parse(line));
-      } catch {
+      } catch (error) {
         // Malformed JSON line - skip it.
+        options.onInvalidLine?.(error instanceof Error ? error : new Error(String(error)));
       }
     }
   });

package/packages/protocol/src/registry.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import { CAPABILITIES } from './capability-values.js';
+import { BridgeError, ERROR_CODES } from './errors.js';
 
 /**
  * @typedef {'trivial' | 'low' | 'moderate' | 'high'} BridgeMethodComplexity
@@ -97,6 +98,8 @@ const METHOD_POLICIES = Object.freeze({
 const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
   'access.request':
     'Request Browser Bridge access for the focused window. Do not repeat while access is already pending.',
+  'protocol.describe':
+    'Describe bridge method parameters and metadata by method or registry group.',
   'tabs.list': 'List tabs in the enabled window.',
   'tabs.create': 'Create a new tab in the enabled window.',
   'tabs.close': 'Close a tab in the enabled window.',
@@ -222,6 +225,13 @@ function createRegistryEntry(
 export const BRIDGE_METHOD_REGISTRY = Object.freeze({
   // system - trivial
   'access.request': createRegistryEntry('access.request', 'system', false, ['intent'], 'trivial'),
+  'protocol.describe': createRegistryEntry(
+    'protocol.describe',
+    'system',
+    false,
+    ['method', 'group'],
+    'trivial'
+  ),
   'skill.get_runtime_context': createRegistryEntry(
     'skill.get_runtime_context',
     'system',
@@ -888,6 +898,79 @@ export function createBridgeMethodGroups() {
   return groups;
 }
 
+/**
+ * @typedef {{
+ *   method: import('./types.js').BridgeMethod,
+ *   group: string,
+ *   tab: boolean,
+ *   params: readonly string[],
+ *   description: string,
+ *   complexity: BridgeMethodComplexity
+ * }} BridgeMethodDescription
+ */
+
+/**
+ * @param {import('./types.js').BridgeMethod} method
+ * @returns {BridgeMethodDescription}
+ */
+function createBridgeMethodDescription(method) {
+  const entry = BRIDGE_METHOD_REGISTRY[method];
+  return {
+    method,
+    group: entry.group,
+    tab: entry.tab,
+    params: entry.params,
+    description: entry.description,
+    complexity: entry.complexity,
+  };
+}
+
+/**
+ * Return a compact registry index or detailed descriptions for one method or group.
+ *
+ * @param {{ method?: unknown, group?: unknown }} [options]
+ * @returns {{ groups: Array<{ group: string, count: number }> } | BridgeMethodDescription | { group: string, methods: BridgeMethodDescription[] }}
+ */
+export function describeBridgeMethods(options = {}) {
+  const { method, group } = options;
+  if (method !== undefined && group !== undefined) {
+    throw new BridgeError(
+      ERROR_CODES.INVALID_REQUEST,
+      'protocol.describe accepts either method or group, not both.'
+    );
+  }
+  if (method !== undefined) {
+    if (typeof method !== 'string' || !isBridgeMethod(method)) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        `Unknown bridge method "${String(method)}".`
+      );
+    }
+    return createBridgeMethodDescription(method);
+  }
+
+  const groups = createBridgeMethodGroups();
+  if (group !== undefined) {
+    if (typeof group !== 'string' || !Object.hasOwn(groups, group)) {
+      throw new BridgeError(
+        ERROR_CODES.INVALID_REQUEST,
+        `Unknown bridge method group "${String(group)}".`
+      );
+    }
+    return {
+      group,
+      methods: groups[group].map(createBridgeMethodDescription),
+    };
+  }
+
+  return {
+    groups: Object.entries(groups).map(([groupName, methods]) => ({
+      group: groupName,
+      count: methods.length,
+    })),
+  };
+}
+
 /**
  * @param {string} method
  * @returns {method is import('./types.js').BridgeMethod}

package/packages/protocol/src/types.ts

@@ -63,6 +63,7 @@ export type ErrorCode =
 
 export type BridgeMethod =
   | 'access.request'
+  | 'protocol.describe'
   | 'tabs.list'
   | 'tabs.create'
   | 'tabs.close'

package/skills/browser-bridge/SKILL.md

@@ -14,6 +14,8 @@ Permission prompts are controlled by the host agent, not by Browser Bridge. In p
 Skill name: `browser-bridge` (also known as `bbx`). In GitHub Copilot, invoke as `/browser-bridge`. `bbx` is the CLI command used throughout this skill.
 When the runtime supports subagents, delegate bridge inspection to a smaller, lower-cost worker and return only concise findings to the parent.
 For open-ended investigation, start with structured reads (`page.get_state`, `dom.query`, `page.get_text`, `page.extract_content`, `styles.get_computed`, and `bbx batch` for CLI or `browser_batch` for MCP) and escalate to screenshots or debugger-backed methods only when structured evidence is insufficient. `browser_call` accepts one protocol method at a time; `batch` is not a valid `browser_call` method.
+When an unfamiliar method is needed, run `bbx protocol describe <method|group>` before guessing parameters. In MCP mode, call `browser_call` with method `protocol.describe` and params `{ "method": "dom.query" }` or `{ "group": "inspect" }`.
+MCP exposes common tools first. Load one specialized typed tool only when needed by calling `browser_toolset` with its exact name, for example `{ "tool": "browser_dom" }`; `browser_call` remains the universal fallback.
 
 ## CLI
 
@@ -32,6 +34,7 @@ bbx tab-create [url]        # open a new tab (avoid unless necessary)
 bbx tab-close <tabId>       # close a tab
 bbx tab-activate <tabId>    # bring a tab to the foreground
 bbx skill                   # live runtime presets + limits
+bbx protocol describe [method|group] # local method params or compact group index
 ```
 
 Use the globally installed `bbx` command or `node packages/agent-client/src/cli.js ...` for live readiness checks from this repository. Avoid `rtk npm exec -- bbx status` as a health signal: that path can restart/replace the daemon and report `Extension: disconnected` before Chrome reconnects. If it happens, wait a few seconds and verify with `bbx status`.
@@ -351,6 +354,7 @@ Every CLI shortcut command produces consistent `{ok, summary, evidence}` JSON. U
 - `network.export_har` requires that explicit capture to still be armed. Params are `limit` (1-200), sanitized-URL substring `urlPattern`, and `delivery` (`auto`, `inline`, `artifact`). Inline bounds remove whole oldest entries; export never changes capture state. `bbx har` uses the same client to download, length/SHA-256 verify, delete, validate, and atomically write artifacts locally.
 - `page.handle_dialog` mutations are not atomically bound to `expectedDialogId`; treat `commandDispatched` as dispatch evidence and verify follow-up state.
 - Raw screenshot calls default to inline base64. Use `delivery: "auto"` for size-aware artifact fallback, or explicit `inline` when MCP image content is required; prefer `bbx screenshot <ref> [outPath]` when one element is enough because the CLI downloads and verifies artifacts locally.
+- Artifact delivery returns a descriptor (artifactId, sha256, byteLength), not bytes. From MCP, read chunks with the `browser_artifact` tool (`action: "read"`, paging `offset` until `nextOffset` is null, then verify the reassembled bytes against `sha256`) and free storage with `action: "delete"`. Each standalone CLI invocation has a new artifact owner, so use `bbx screenshot` / `bbx har` to capture, download, verify, and delete within one CLI process; use `delivery: "inline"` for raw CLI screenshot calls that need the bytes in their immediate result.
 
 ## Response Shapes
 

package/skills/browser-bridge/references/protocol.md

@@ -27,11 +27,16 @@ The table below includes the legacy capability bucket for each method so agents
 - `-` means the method is global/system-scoped and was never gated by a former capability bucket.
 - Capability names are descriptive coverage labels only. Browser Bridge access is window-scoped now; there are no capability-scoped sessions.
 
-## All Methods (75)
+Use `bbx protocol describe <method|group>` for a compact local signature lookup. In MCP mode,
+call `browser_call` with method `protocol.describe` and params containing `method` or `group`;
+omit both for the group index.
+
+## All Methods (76)
 
 | Method                             | Tab? | CDP?       | Group       | Capability           | Notes                                                                                      |
 | ---------------------------------- | ---- | ---------- | ----------- | -------------------- | ------------------------------------------------------------------------------------------ |
 | `access.request`                   | No   | -          | system      | `intent?`            | Request window access with bounded operation context in the extension UI                    |
+| `protocol.describe`                | No   | -          | system      | `-`                  | Local compact method/group parameters and metadata                                          |
 | `tabs.list`                        | No   | -          | tabs        | `-`                  | Discover tabs in the enabled window                                                        |
 | `tabs.create`                      | No   | -          | tabs        | `tabs.manage`        | Open a new tab; optional `url` and `active`                                                |
 | `tabs.close`                       | No   | -          | tabs        | `tabs.manage`        | Close a tab by `tabId`                                                                     |
@@ -115,6 +120,7 @@ stopped.
 
 ```bash
 bbx status | doctor | restart | logs | tabs | skill # no routed tab needed
+bbx protocol describe [method|group]             # local signature or compact group index
 bbx call <method> '{"key":"val"}'           # generic RPC (routes to active tab in enabled window)
 bbx call --tab 123 <method> '{...}'         # explicit tab target inside enabled window
 bbx batch '[{"method":"...","params":{}}]'  # parallel calls
@@ -437,7 +443,7 @@ artifact, and atomically write the output on the CLI host.
 
 ### dom.get_accessibility_tree
 
-Retrieve a depth-limited accessibility tree via CDP. Full reads use `Accessibility.getFullAXTree`; an optional unique `selector` resolves through CDP DOM methods and uses `Accessibility.getPartialAXTree`, retaining only the selected subtree and required ancestor chain. Missing and ambiguous selectors return typed errors instead of selecting an arbitrary candidate. Nodes include `role`, `name`, `description`, `value`, state fields, `interactive`, `semanticInteractive`, `focusable`, `focusableAndEnabled`, `ignored`, and `childIds`. `interactive` is semantic/focusability metadata, not current pointer actionability.
+Retrieve a depth-limited accessibility tree via CDP. Full reads use `Accessibility.getFullAXTree`; an optional unique `selector` resolves through CDP DOM methods, starts with `Accessibility.getPartialAXTree`, and incrementally fetches selected descendant layers with `Accessibility.getChildAXNodes`. Only the selected subtree and required ancestor chain are retained. Missing and ambiguous selectors return typed errors instead of selecting an arbitrary candidate. Nodes include `role`, `name`, `description`, `value`, state fields, `interactive`, `semanticInteractive`, `focusable`, `focusableAndEnabled`, `ignored`, and `childIds`. `interactive` is semantic/focusability metadata, not current pointer actionability.
 
 This is debugger-backed. Prefer `dom.find_by_role`, `dom.find_by_text`, and targeted `dom.query`/`dom.describe` first.
 
@@ -449,7 +455,7 @@ bbx call dom.get_accessibility_tree '{"maxNodes":100,"maxDepth":6,"interactiveOn
 bbx call dom.get_accessibility_tree '{"selector":"[role=dialog]","maxNodes":50,"compact":true}'
 ```
 
-Filtering occurs before `maxNodes`. Compact mode drops ignored, decorative, and empty nodes while reconnecting retained descendants; interactive-only keeps non-ignored semantic interactive roles. Because CDP applies `maxDepth` before Browser Bridge receives the tree, every result truthfully reports `truncated: true`, `partialTopology: true`, depth metadata, missing-child counts, and a continuation hint. No AX node is written into the page DOM or converted directly into an actionable element ref; use role/name with `dom.find_by_role` before input.
+Filtering occurs before `maxNodes`. Compact mode drops ignored, decorative, and empty nodes while reconnecting retained descendants; interactive-only keeps non-ignored semantic interactive roles. Full reads ask CDP for the requested depth, while selector-scoped reads fetch descendant layers up to that same bound. Every result reports `truncated: true`, `partialTopology: true`, depth metadata, missing-child counts, and a continuation hint. No AX node is written into the page DOM or converted directly into an actionable element ref; use role/name with `dom.find_by_role` before input.
 
 ### viewport.resize
 
@@ -482,7 +488,7 @@ Capture a complete element, a tight viewport region, or a full document. All met
 
 Element capture uses full page-coordinate bounds with CDP capture beyond the viewport. If Browser Bridge cannot guarantee the entire element, or if an element/page exceeds Chrome capture limits, it returns a typed failure rather than a viewport-clipped image labeled complete. Use full-page capture only when element or tight region captures cannot express the issue.
 
-Raw calls default to inline base64 for compatibility. `auto` keeps small captures inline and returns a short-lived, daemon-owned opaque artifact handle for large captures; explicit `inline` preserves MCP image content when model vision is needed. Artifact handles expose no browser-host path and support owner-scoped bounded `artifact.read` and `artifact.delete` calls. Prefer `bbx screenshot [--format png|jpeg|webp] [--quality 0-100] <ref> [outPath]` when one element is enough; the CLI downloads, verifies, deletes, and atomically writes the artifact on the CLI host.
+Raw calls default to inline base64 for compatibility. `auto` keeps small captures inline and returns a short-lived, daemon-owned opaque artifact handle for large captures; explicit `inline` preserves MCP image content when model vision is needed. Artifact handles expose no browser-host path and support owner-scoped bounded `artifact.read` and `artifact.delete` calls. Each standalone CLI invocation uses a new artifact owner, so raw CLI screenshot calls should keep inline delivery. Prefer `bbx screenshot [--format png|jpeg|webp] [--quality 0-100] <ref> [outPath]` when one element is enough; the CLI downloads, verifies, deletes, and atomically writes the artifact within one process.
 
 Artifact handles expire after five minutes and can be read or deleted only by
 the requesting client. The daemon creates a private artifact directory and
@@ -490,7 +496,7 @@ owner-only files on POSIX hosts, removes artifacts on expiry/teardown, and never
 returns its browser-host filesystem path.
 
 ```bash
-bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75,"delivery":"auto","scale":0.75}'
+bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75,"delivery":"inline","scale":0.75}'
 ```
 
 ## Recovery Telemetry