@browserbridge/bbx 1.9.0 → 1.10.0

package/package.json

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

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

@@ -1,9 +1,12 @@
 // @ts-check
 
-import { METHODS } from '../../protocol/src/index.js';
+import { applyMethodBudgetPreset, isBudgetPresetName, METHODS } from '../../protocol/src/index.js';
 import { methodNeedsTab, parseIntArg, parseJsonObject } from './cli-helpers.js';
 
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('../../protocol/src/defaults.js').BudgetPresetName} BudgetPresetName */
+
+const CALL_USAGE = 'Usage: call [--tab <tabId>] [--preset quick|normal|deep] <method> [paramsJson]';
 
 /**
  * Read all of stdin as UTF-8 text. Resolves once stdin closes.
@@ -119,18 +122,44 @@ export function extractHarFlags(args) {
   return { limit, urlPattern, delivery: rawDelivery, rest };
 }
 
+/**
+ * Extract the --preset flag from anywhere in the argument list. Preset names
+ * are validated against the shared budget presets; explicit per-call params
+ * always override preset defaults.
+ *
+ * @param {string[]} args
+ * @returns {{ preset: BudgetPresetName | null, rest: string[] }}
+ */
+export function extractPresetFlag(args) {
+  const rest = [...args];
+  const index = rest.indexOf('--preset');
+  if (index === -1) {
+    return { preset: null, rest };
+  }
+  const value = rest[index + 1];
+  if (!value || value.startsWith('--')) {
+    throw new Error('--preset requires a value: quick, normal, or deep.');
+  }
+  if (!isBudgetPresetName(value)) {
+    throw new Error(`Unknown preset "${value}". Valid presets: quick, normal, deep.`);
+  }
+  rest.splice(index, 2);
+  return { preset: value, rest };
+}
+
 /**
  * @param {string[]} args
  * @returns {Promise<{ tabId: number | null, method: BridgeMethod, params: Record<string, unknown> }>}
  */
 export async function parseCallCommand(args) {
-  const parsed = extractTabFlag(args);
+  const presetParsed = extractPresetFlag(args);
+  const parsed = extractTabFlag(presetParsed.rest);
   const [first, second, ...extra] = parsed.rest;
   if (!first) {
-    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+    throw new Error(CALL_USAGE);
   }
   if (extra.length > 0) {
-    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+    throw new Error(CALL_USAGE);
   }
 
   if (first.includes('.')) {
@@ -146,11 +175,11 @@ export async function parseCallCommand(args) {
     return {
       method,
       tabId: methodNeedsTab(method) ? parsed.tabId : null,
-      params: parseJsonObject(rawParams),
+      params: applyMethodBudgetPreset(method, parseJsonObject(rawParams), presetParsed.preset),
     };
   }
 
-  throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+  throw new Error(CALL_USAGE);
 }
 
 /**

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

@@ -1,6 +1,7 @@
 // @ts-check
 
 import {
+  applyMethodBudgetPreset,
   getProtocolVersion,
   isBatchSafeBridgeCall,
   MAX_BATCH_CALLS,
@@ -14,6 +15,7 @@ import { requestBridge } from './runtime.js';
 
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
 /** @typedef {import('./types.js').BridgeRequestSource} BridgeRequestSource */
+/** @typedef {import('../../protocol/src/defaults.js').BudgetPresetName} BudgetPresetName */
 
 /**
  * @typedef {{
@@ -72,9 +74,10 @@ function invalidBatchItem(method, message) {
  * @param {import('./client.js').BridgeClient} client
  * @param {string | undefined} input - Raw JSON array argument
  * @param {BridgeRequestSource} source - Request source tag (e.g. 'cli')
+ * @param {{ preset?: BudgetPresetName | null }} [options] - Optional budget preset applied to every call
  * @returns {Promise<BatchResultItem[]>}
  */
-export async function runBatchCalls(client, input, source) {
+export async function runBatchCalls(client, input, source, options = {}) {
   if (!input) {
     throw new Error('Usage: batch \'[{"method":"...","params":{...}}, ...]\'');
   }
@@ -90,7 +93,7 @@ export async function runBatchCalls(client, input, source) {
   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));
+  const prepared = calls.map((call) => prepareBatchCall(call, options.preset ?? null));
   if (prepared.some((item) => 'error' in item)) {
     return prepared.map((item) =>
       'error' in item
@@ -130,9 +133,10 @@ export async function runBatchCalls(client, input, source) {
 
 /**
  * @param {unknown} call
+ * @param {BudgetPresetName | null} preset
  * @returns {{ value: PreparedBatchCall } | { error: InvalidBatchItem }}
  */
-function prepareBatchCall(call) {
+function prepareBatchCall(call, preset) {
   if (!call || typeof call !== 'object' || Array.isArray(call)) {
     return { error: invalidBatchItem('', 'Each batch call needs a method.') };
   }
@@ -162,7 +166,8 @@ function prepareBatchCall(call) {
   }
   const params =
     batchCall.params === undefined ? {} : /** @type {Record<string, unknown>} */ (batchCall.params);
-  if (!isBatchSafeBridgeCall(method, params)) {
+  const mergedParams = applyMethodBudgetPreset(method, params, preset);
+  if (!isBatchSafeBridgeCall(method, mergedParams)) {
     return {
       error: invalidBatchItem(
         method,
@@ -177,7 +182,7 @@ function prepareBatchCall(call) {
     batchCall.tabId > 0
       ? batchCall.tabId
       : null;
-  return { value: { method, params, tabId } };
+  return { value: { method, params: mergedParams, tabId } };
 }
 
 /**

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

@@ -3,6 +3,14 @@
 import readline from 'node:readline';
 import { bridgeMethodNeedsTab } from '../../protocol/src/index.js';
 
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isElementRef(value) {
+  return value.startsWith('el_');
+}
+
 /**
  * Strip ANSI escape sequences from a string to prevent terminal injection
  * from malicious page content (e.g. DOM text, console output, eval results).

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

@@ -150,7 +150,8 @@ export async function runInstallMcpCommand(args) {
   /** @type {string[]} */
   const positionals = [];
 
-  for (const arg of args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
     if (arg === '--local') {
       isGlobal = false;
       continue;
@@ -276,6 +277,7 @@ export async function runInstallMcpCommand(args) {
     projectPath: process.cwd(),
     stdout: process.stdout,
   });
+
   process.exit(0);
 }
 

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

@@ -10,7 +10,13 @@ import { fileURLToPath } from 'node:url';
 
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
-import { createRuntimeContext, METHODS } from '../../protocol/src/index.js';
+import {
+  createRuntimeContext,
+  describeBridgeMethods,
+  isBridgeMethod,
+  isHarDocument,
+  METHODS,
+} from '../../protocol/src/index.js';
 import {
   restartRegisteredMcpProcesses,
   tryStartMcpProcessControl,
@@ -19,6 +25,7 @@ import { startBridgeMcpServer } from '../../mcp-server/src/server.js';
 import {
   extractRemoteFlag,
   extractHarFlags,
+  extractPresetFlag,
   extractScreenshotFlags,
   extractTabFlag,
   parseCallCommand,
@@ -26,7 +33,7 @@ import {
   readStdin,
 } from './cli-args.js';
 import { runBatchCalls } from './cli-batch.js';
-import { parseIntArg } from './cli-helpers.js';
+import { isElementRef, parseIntArg } from './cli-helpers.js';
 import { printCallResponse, printJson, printSummary, printUsage } from './cli-output.js';
 import { handleProxyCommand, handleRemoteCommand } from './cli-proxy-remote.js';
 import {
@@ -64,6 +71,7 @@ const LOCAL_ONLY_COMMANDS = new Set([
   '--version',
   '-v',
   'skill',
+  'protocol',
   'install',
   'uninstall',
   'install-skill',
@@ -111,6 +119,22 @@ if (command === 'skill') {
   process.exit(0);
 }
 
+if (command === 'protocol') {
+  const [subcommand, target, ...extra] = rest;
+  if (subcommand !== 'describe' || extra.length > 0) {
+    process.stderr.write('Usage: bbx protocol describe [method|group]\n');
+    process.exit(1);
+  }
+  await runLocalCommand(async () => {
+    printJson(
+      target
+        ? describeBridgeMethods(isBridgeMethod(target) ? { method: target } : { group: target })
+        : describeBridgeMethods()
+    );
+  });
+  process.exit();
+}
+
 if (command === 'install') {
   const { execFileSync } = await import('node:child_process');
   const installScript = path.resolve(
@@ -142,7 +166,7 @@ if (command === 'install-mcp') {
 }
 
 if (command === 'mcp') {
-  const [subcommand, clientName] = rest;
+  const [subcommand, clientName, ...extra] = rest;
   if (subcommand === 'serve') {
     const control = await tryStartMcpProcessControl();
     try {
@@ -154,7 +178,7 @@ if (command === 'mcp') {
     await new Promise(() => {});
   }
   if (subcommand === 'config') {
-    if (!clientName || !isMcpClientName(clientName)) {
+    if (!clientName || !isMcpClientName(clientName) || extra.length > 0) {
       process.stderr.write(`Usage: bbx mcp config <${MCP_CLIENT_NAMES.join('|')}>\n`);
       process.exit(1);
     }
@@ -260,8 +284,10 @@ async function main() {
     }
 
     if (command === 'access-request') {
+      if (rest.length > 1) throw new Error('Usage: bbx access-request [intent]');
+      const params = SHORTCUT_COMMANDS['access-request'].build(rest);
       await printSummary(
-        await requestBridge(client, 'access.request', {}, { source: REQUEST_SOURCE })
+        await requestBridge(client, 'access.request', params, { source: REQUEST_SOURCE })
       );
       return;
     }
@@ -377,7 +403,8 @@ async function main() {
     }
 
     if (command === 'batch') {
-      const results = await runBatchCalls(client, rest[0], REQUEST_SOURCE);
+      const { preset, rest: batchArgs } = extractPresetFlag(rest);
+      const results = await runBatchCalls(client, batchArgs[0], REQUEST_SOURCE, { preset });
       if (results.some((result) => !result.ok)) {
         process.exitCode = 1;
       }
@@ -412,7 +439,7 @@ async function main() {
       const [key, refOrSelector] = rest;
       if (!key) throw new Error('Usage: press-key <key> [ref|selector]');
       const target = refOrSelector
-        ? refOrSelector.startsWith('el_')
+        ? isElementRef(refOrSelector)
           ? { elementRef: refOrSelector }
           : { selector: refOrSelector }
         : undefined;
@@ -755,14 +782,7 @@ function assertValidHarDocument(document) {
   if (!document || typeof document !== 'object' || Array.isArray(document)) {
     throw new Error('HAR response does not contain an inline HAR object.');
   }
-  const log = Reflect.get(document, 'log');
-  if (
-    !log ||
-    typeof log !== 'object' ||
-    Array.isArray(log) ||
-    Reflect.get(log, 'version') !== '1.2' ||
-    !Array.isArray(Reflect.get(log, 'entries'))
-  ) {
+  if (!isHarDocument(document)) {
     throw new Error('HAR response does not contain a valid HAR 1.2 document.');
   }
 }

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

@@ -2,6 +2,7 @@
 
 import { BRIDGE_METHOD_REGISTRY, BRIDGE_METHODS } from '../../protocol/src/index.js';
 import {
+  isElementRef,
   parseCommaList,
   parseIntArg,
   parseNumberArg,
@@ -39,7 +40,7 @@ function createShortcutCommand(method, usage, build, options = {}) {
  */
 function createAtomicTarget(value) {
   if (!value) throw new Error('A ref or selector is required.');
-  return value.startsWith('el_') ? { elementRef: value } : { selector: value };
+  return isElementRef(value) ? { elementRef: value } : { selector: value };
 }
 
 /** @type {Record<string, ShortcutCommand>} */
@@ -266,6 +267,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx uninstall                                                      Remove native host manifests, Browser Bridge runtime files, and managed MCP/skill installs',
       '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',
+      '  MCP starts with common tools; browser_toolset loads one specialized typed tool by name when needed.',
       'bbx status                                                         Check bridge connection',
       'bbx doctor                                                         Consolidated local runtime, setup, protocol, and readiness diagnostics',
       'bbx restart                                                        Restart the local daemon and running MCP servers',
@@ -285,15 +287,17 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx tab-close <tabId>                                              Close a tab',
       'bbx tab-activate <tabId>                                           Bring a tab to the foreground',
       'bbx skill                                                          Runtime budget presets and method groups',
+      'bbx protocol describe [method|group]                                Describe method params or list registry groups locally',
       'bbx mcp serve                                                      Start Browser Bridge as an MCP stdio server',
     ],
   },
   {
     title: 'Generic RPC',
     lines: [
-      'bbx call [--tab <tabId>] <method> [paramsJson|-]                   Call any bridge method (- reads JSON from stdin)',
+      'bbx call [--tab <tabId>] [--preset quick|normal|deep] <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?},...]'                           Up to 20 parallel read-only calls",
+      "bbx batch [--preset quick|normal|deep] '[{method,params,tabId?},...]'  Up to 20 parallel read-only calls",
+      '--preset fills budget gaps (maxNodes, maxDepth, textBudget, limit) from the shared quick|normal|deep presets; explicit params always win.',
       '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.',

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

@@ -91,23 +91,23 @@ export function getMcpConfigShape(clientName) {
  *   env: Record<string, string>
  * } | {
  *   type: 'local',
- *   command: string[]
+ *   command: string[],
+ *   environment?: Record<string, string>
  * }}
  */
 function createBaseServerConfig(clientName) {
-  const serverConfig = {
-    command: MCP_COMMAND,
-    args: [...MCP_ARGS],
-    env: {},
-  };
-
   if (clientName === 'opencode') {
     return {
       type: 'local',
       command: [MCP_COMMAND, ...MCP_ARGS],
     };
   }
-  return serverConfig;
+
+  return {
+    command: MCP_COMMAND,
+    args: [...MCP_ARGS],
+    env: {},
+  };
 }
 
 /** @type {Record<McpClientName, { key: string, includeType: boolean, keepEmptyBlock?: boolean }>} */

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

@@ -33,7 +33,7 @@ import {
   sanitizeIncidentalPath,
   sanitizeIncidentalText,
 } from '../../protocol/src/index.js';
-import { methodNeedsTab } from './cli-helpers.js';
+import { isElementRef, methodNeedsTab } from './cli-helpers.js';
 import { BridgeClient } from './client.js';
 import { applyConfiguredAutoUpdate } from './config.js';
 import { readRemoteConfig } from './remotes.js';
@@ -140,7 +140,7 @@ export async function requestBridge(client, method, params = {}, options = {}) {
  * @returns {Promise<string>}
  */
 export async function resolveRef(client, refOrSelector, tabId = null, source) {
-  if (refOrSelector.startsWith('el_')) {
+  if (isElementRef(refOrSelector)) {
     return refOrSelector;
   }
 

package/packages/mcp-server/src/guidance.js

@@ -1,17 +1,48 @@
 // @ts-check
 
-export const MCP_SERVER_INSTRUCTIONS = [
-  "Browser Bridge MCP inspects and interacts with the user's real Chrome tab through typed MCP tools.",
-  'In permission-ask hosts, use browser_call as the default Browser Bridge MCP tool so the user can approve one BBX tool instead of separate browser_status, browser_page, browser_dom, browser_input, and other tools.',
+/**
+ * Guidance lines shared by the progressive tool surface.
+ *
+ * @type {readonly string[]}
+ */
+const SHARED_INSTRUCTIONS = Object.freeze([
   'Prefer Browser Bridge MCP tools over shelling out to bbx. Use bbx only for explicit CLI setup, doctor, logs, or raw debugging requests.',
   'Start with browser_call method health.ping. If window access is disabled, call browser_call method access.request once, ask the user to click Enable in the Browser Bridge popup or side panel, then retry once.',
   'Use structured reads first through browser_call: page.get_state, dom.query, page.get_text, page.extract_content, styles.get_computed, or layout.get_box_model. Prefer semantic extraction for articles and documentation. Use browser_batch only for parallel reads; run mutations sequentially and keep limits tight before widening.',
-  'Reuse elementRef values returned by DOM tools. Use attribute allowlists for focused DOM reads.',
+  'Reuse elementRef values returned by DOM reads. Use attribute allowlists for focused DOM reads.',
   'Escalate to screenshot.capture_element, screenshot.capture_region, dom.get_accessibility_tree, page.evaluate, viewport.resize, or CDP only when structured reads cannot answer the question.',
   'Use patch.apply_styles or patch.apply_dom for temporary experiments, and rollback patches before finishing unless the user asks to keep them.',
-  'Only use the specialized Browser Bridge MCP tools directly when the host has already allowed them or the user explicitly wants typed tool calls.',
+]);
+
+/**
+ * Workflow guidance appended after the tool-selection rules.
+ *
+ * @type {readonly string[]}
+ */
+const WORKFLOW_INSTRUCTIONS = Object.freeze([
   '',
   'Page investigation: read page state, scoped DOM, and relevant page text first, batching independent reads. Find targets by text or role when selectors are unknown. Add styles, console, or network reads only when they directly answer the objective, and use screenshots or evaluation only when structured evidence is insufficient.',
   'Layout debugging: locate the target, read only relevant computed properties and its box model, and inspect matched rules only when the cascade is unclear. Prototype the smallest fix with a reversible style patch, verify the result, check for new console errors, then rollback before editing source unless the user asks to keep the patch.',
   'Flow verification: read initial page state, locate controls semantically, reuse elementRef values, interact through input tools, and wait for navigation or UI state changes. Verify the final DOM or page text plus console and network state when relevant. Do not create a new tab unless requested or required by the flow.',
-].join('\n');
+]);
+
+const SERVER_HEADER =
+  "Browser Bridge MCP inspects and interacts with the user's real Chrome tab through a compact tool set.";
+
+const TOOL_RULES = Object.freeze([
+  'The common tools are available immediately. When a specialized typed tool is useful, call browser_toolset with its exact tool name; browser_call always reaches every bridge method without loading another tool.',
+  'Use browser_call method protocol.describe with method or group params to load unfamiliar signatures cheaply.',
+]);
+
+/**
+ * Build instructions for progressive tool discovery.
+ *
+ * @returns {string}
+ */
+export function getMcpServerInstructions() {
+  return [SERVER_HEADER, ...TOOL_RULES, ...SHARED_INSTRUCTIONS, ...WORKFLOW_INSTRUCTIONS].join(
+    '\n'
+  );
+}
+
+export const MCP_SERVER_INSTRUCTIONS = getMcpServerInstructions();

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

@@ -153,7 +153,7 @@ export function createScreenshotResult(response, method) {
       return summarizeToolError(new Error(`${method} returned invalid artifact metadata.`));
     }
     return createToolResult(
-      `Captured screenshot artifact (${artifact.byteLength} bytes, expires ${artifact.expiresAt ?? 'soon'}).`,
+      `Captured screenshot artifact (${artifact.byteLength} bytes, expires ${artifact.expiresAt ?? 'soon'}). Read it in chunks with the browser_artifact tool (action "read", paging offset until nextOffset is null), then delete it with browser_artifact action "delete" when done.`,
       {
         ok: true,
         method,

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

@@ -4,9 +4,11 @@ import {
   DEFAULT_CONSOLE_LIMIT,
   DEFAULT_HAR_LIMIT,
   DEFAULT_NETWORK_LIMIT,
+  describeBridgeMethods,
   ERROR_CODES,
   getErrorRecovery,
   isBatchSafeBridgeCall,
+  isHarDocument,
   MAX_BATCH_CALLS,
   MAX_BATCH_CONCURRENCY,
   METHOD_SET,
@@ -166,6 +168,157 @@ export async function handlePageTool(args) {
   });
 }
 
+/**
+ * Read one chunk of a daemon-owned artifact or delete it. Reads are paged by
+ * the caller: pass the returned nextOffset until it comes back null, then
+ * verify the reassembled bytes against sha256.
+ *
+ * @param {{ action: string, artifactId?: string, offset?: number, limit?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleArtifactTool(args) {
+  if (args.action !== 'read' && args.action !== 'delete') {
+    return summarizeToolError(`Unsupported artifact action "${args.action}".`);
+  }
+  if (typeof args.artifactId !== 'string' || !args.artifactId.trim()) {
+    return summarizeToolError('artifactId is required.');
+  }
+  if (args.offset !== undefined && (!Number.isInteger(args.offset) || args.offset < 0)) {
+    return summarizeToolError('offset must be a non-negative integer.');
+  }
+  if (args.limit !== undefined && (!Number.isInteger(args.limit) || args.limit < 1)) {
+    return summarizeToolError('limit must be a positive integer.');
+  }
+  const method = /** @type {BridgeMethod} */ (
+    args.action === 'read' ? 'artifact.read' : 'artifact.delete'
+  );
+  const params =
+    args.action === 'read'
+      ? {
+          artifactId: args.artifactId,
+          offset: args.offset ?? 0,
+          ...(typeof args.limit === 'number' ? { maxBytes: args.limit } : {}),
+        }
+      : { artifactId: args.artifactId };
+  return withToolClient(
+    async (client) => {
+      const response = await requestBridgeWithRetry(client, method, params, {
+        tabId: null,
+        source: REQUEST_SOURCE,
+        tokenBudget: getToolTokenBudget(args),
+      });
+      return method === 'artifact.read'
+        ? createArtifactReadResult(response)
+        : summarizeToolResponse(response, method, params);
+    },
+    { destinationId: args.destinationId ?? null }
+  );
+}
+
+/**
+ * Manage CDP Fetch request interception rules for a tab.
+ *
+ * @param {{ action: string, urlPattern?: string, ruleAction?: 'block' | 'fulfill' | 'continue', statusCode?: number, body?: string, headers?: Record<string, string>, ruleId?: string, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleInterceptTool(args) {
+  const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
+  return withToolClient(
+    async (client) => {
+      /** @type {BridgeMethod} */
+      let method;
+      /** @type {Record<string, unknown>} */
+      let params;
+      switch (args.action) {
+        case 'add': {
+          if (typeof args.urlPattern !== 'string' || !args.urlPattern.trim()) {
+            return summarizeToolError('urlPattern is required for intercept add.');
+          }
+          method = 'network.intercept.add';
+          params = {
+            urlPattern: args.urlPattern,
+            ...(args.ruleAction ? { action: args.ruleAction } : {}),
+            ...(typeof args.statusCode === 'number' ? { statusCode: args.statusCode } : {}),
+            ...(typeof args.body === 'string' ? { body: args.body } : {}),
+            ...(args.headers ? { headers: args.headers } : {}),
+          };
+          break;
+        }
+        case 'remove': {
+          if (typeof args.ruleId !== 'string' || !args.ruleId.trim()) {
+            return summarizeToolError('ruleId is required for intercept remove.');
+          }
+          method = 'network.intercept.remove';
+          params = { ruleId: args.ruleId };
+          break;
+        }
+        case 'list':
+          method = 'network.intercept.list';
+          params = {};
+          break;
+        case 'clear':
+          method = 'network.intercept.clear';
+          params = {};
+          break;
+        default:
+          return summarizeToolError(`Unsupported intercept action "${args.action}".`);
+      }
+      const response = await requestBridgeWithRetry(client, method, params, {
+        tabId: requestedTabId,
+        source: REQUEST_SOURCE,
+        tokenBudget: getToolTokenBudget(args),
+      });
+      return summarizeToolResponse(response, method, params);
+    },
+    { destinationId: args.destinationId ?? null }
+  );
+}
+
+/**
+ * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @returns {ToolResult}
+ */
+function createArtifactReadResult(response) {
+  if (!response.ok) return summarizeToolResponse(response, 'artifact.read', {});
+  const result =
+    response.result && typeof response.result === 'object' && !Array.isArray(response.result)
+      ? /** @type {Record<string, unknown>} */ (response.result)
+      : {};
+  if (
+    typeof result.artifactId !== 'string' ||
+    typeof result.data !== 'string' ||
+    typeof result.offset !== 'number' ||
+    typeof result.byteLength !== 'number' ||
+    typeof result.totalBytes !== 'number' ||
+    typeof result.sha256 !== 'string' ||
+    (result.nextOffset !== null && typeof result.nextOffset !== 'number')
+  ) {
+    return summarizeToolError('artifact.read returned invalid chunk metadata.');
+  }
+  const nextOffset = /** @type {number | null} */ (result.nextOffset);
+  return createToolResult(
+    `Read ${result.byteLength} bytes from artifact ${result.artifactId} at offset ${result.offset} (${result.totalBytes} bytes total). ${
+      nextOffset === null
+        ? 'Artifact fully read; verify the reassembled bytes against sha256.'
+        : `Continue reading with offset ${nextOffset}.`
+    }`,
+    {
+      ok: true,
+      method: 'artifact.read',
+      artifactId: result.artifactId,
+      data: result.data,
+      offset: result.offset,
+      byteLength: result.byteLength,
+      nextOffset,
+      totalBytes: result.totalBytes,
+      sha256: result.sha256,
+      chunkIndex: result.chunkIndex,
+      chunkCount: result.chunkCount,
+      expiresAt: result.expiresAt,
+    }
+  );
+}
+
 /**
  * Deliberately read one exact storage value without retries, budgeting, or
  * value-derived delivery metrics.
@@ -355,6 +508,14 @@ export async function handleRawCallTool(args) {
   if (!METHOD_SET.has(/** @type {BridgeMethod} */ (args.method))) {
     return summarizeToolError(`Unknown bridge method "${args.method}".`);
   }
+  if (args.method === 'protocol.describe') {
+    try {
+      const result = describeBridgeMethods(args.params);
+      return createToolResult('Bridge protocol description loaded.', result);
+    } catch (error) {
+      return summarizeToolError(error);
+    }
+  }
   return withToolClient(
     async (client) => {
       const method = /** @type {BridgeMethod} */ (args.method);
@@ -422,15 +583,7 @@ export function createHarExportResult(response) {
   }
 
   if (result.delivery === 'inline') {
-    const har =
-      result.har && typeof result.har === 'object' && !Array.isArray(result.har)
-        ? /** @type {Record<string, unknown>} */ (result.har)
-        : {};
-    const log =
-      har.log && typeof har.log === 'object' && !Array.isArray(har.log)
-        ? /** @type {Record<string, unknown>} */ (har.log)
-        : {};
-    if (log.version !== '1.2' || !Array.isArray(log.entries)) {
+    if (!isHarDocument(result.har)) {
       return summarizeToolError('network.export_har returned an invalid inline HAR document.');
     }
   } else if (result.delivery === 'artifact') {