@browserbridge/bbx 1.8.0 → 1.10.0

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

@@ -2,9 +2,15 @@
 
 import {
   DEFAULT_CONSOLE_LIMIT,
+  DEFAULT_HAR_LIMIT,
   DEFAULT_NETWORK_LIMIT,
+  describeBridgeMethods,
   ERROR_CODES,
   getErrorRecovery,
+  isBatchSafeBridgeCall,
+  isHarDocument,
+  MAX_BATCH_CALLS,
+  MAX_BATCH_CONCURRENCY,
   METHOD_SET,
 } from '../../protocol/src/index.js';
 import { createBridgeClientForDestination } from '../../agent-client/src/remotes.js';
@@ -33,63 +39,6 @@ import { createScreenshotResult } from './handlers-capture.js';
 /** @typedef {import('../../agent-client/src/client.js').BridgeClient} BridgeClient */
 /** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
 
-export const MAX_BATCH_CALLS = 20;
-export const MAX_BATCH_CONCURRENCY = 5;
-
-/** @type {ReadonlySet<BridgeMethod>} */
-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.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',
-]);
-
-/**
- * @param {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 === true) {
-    return false;
-  }
-  if (
-    method === 'page.get_network' &&
-    params.source === 'cdp' &&
-    params.capture !== undefined &&
-    params.capture !== 'read'
-  ) {
-    return false;
-  }
-  return true;
-}
-
 /** @type {Record<string, { method: BridgeMethod, params: (a: Record<string, unknown>) => Record<string, unknown> }>} */
 export const PAGE_ACTIONS = {
   state: { method: 'page.get_state', params: () => ({}) },
@@ -152,11 +101,19 @@ export const PAGE_ACTIONS = {
       capture: a.capture,
     }),
   },
+  har: {
+    method: 'network.export_har',
+    params: (a) => ({
+      limit: a.limit,
+      urlPattern: a.urlPattern,
+      delivery: a.delivery,
+    }),
+  },
   performance: { method: 'performance.get_metrics', params: () => ({}) },
 };
 
 /**
- * @param {{ action: string, expression?: string, awaitPromise?: boolean, timeoutMs?: number, returnByValue?: boolean, level?: string, clear?: boolean, limit?: number, type?: string, keys?: string[], textBudget?: number, format?: 'text' | 'markdown', selector?: string, includeMetadata?: boolean, consistency?: 'best_effort' | 'settled', settleTimeoutMs?: number, urlPattern?: string, source?: 'fetch-xhr' | 'cdp', capture?: 'read' | 'start' | 'clear' | 'stop', dialogAction?: string, promptText?: string, expectedDialogId?: string, waitForLoad?: boolean, url?: string, urlMatch?: string, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, expression?: string, awaitPromise?: boolean, timeoutMs?: number, returnByValue?: boolean, level?: string, clear?: boolean, limit?: number, type?: string, keys?: string[], textBudget?: number, format?: 'text' | 'markdown', selector?: string, includeMetadata?: boolean, consistency?: 'best_effort' | 'settled', settleTimeoutMs?: number, urlPattern?: string, source?: 'fetch-xhr' | 'cdp', capture?: 'read' | 'start' | 'clear' | 'stop', delivery?: 'auto' | 'inline' | 'artifact', dialogAction?: string, promptText?: string, expectedDialogId?: string, waitForLoad?: boolean, url?: string, urlMatch?: string, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handlePageTool(args) {
@@ -175,6 +132,12 @@ export async function handlePageTool(args) {
       normal: DEFAULT_NETWORK_LIMIT,
       deep: 100,
     });
+  } else if (args.action === 'har') {
+    normalizedArgs = applyLimitBudgetPreset(args, {
+      quick: 20,
+      normal: DEFAULT_HAR_LIMIT,
+      deep: 100,
+    });
   }
   const entry = PAGE_ACTIONS[normalizedArgs.action];
   if (!entry) return summarizeToolError(`Unsupported page action "${args.action}".`);
@@ -184,13 +147,204 @@ export async function handlePageTool(args) {
   ) {
     return summarizeToolError('expression is required for page evaluate.');
   }
-  return callBridgeTool(entry.method, entry.params(normalizedArgs), {
+  const params = entry.params(normalizedArgs);
+  if (entry.method === 'network.export_har') {
+    return withToolClient(
+      async (client) => {
+        const response = await requestBridgeWithRetry(client, entry.method, params, {
+          tabId: typeof normalizedArgs.tabId === 'number' ? normalizedArgs.tabId : null,
+          source: REQUEST_SOURCE,
+          tokenBudget: getToolTokenBudget(normalizedArgs),
+        });
+        return createHarExportResult(response);
+      },
+      { destinationId: normalizedArgs.destinationId ?? null }
+    );
+  }
+  return callBridgeTool(entry.method, params, {
     tabId: typeof normalizedArgs.tabId === 'number' ? normalizedArgs.tabId : null,
     tokenBudget: getToolTokenBudget(normalizedArgs),
     destinationId: normalizedArgs.destinationId ?? null,
   });
 }
 
+/**
+ * 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.
+ *
+ * @param {{ source: 'local_storage' | 'session_storage', key: string, tabId?: number, destinationId?: string }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleSensitiveReadTool(args) {
+  return withToolClient(
+    async (client) => {
+      const response = await requestBridgeWithRetry(
+        client,
+        'sensitive.read',
+        { source: args.source, key: args.key },
+        {
+          tabId: typeof args.tabId === 'number' ? args.tabId : null,
+          source: REQUEST_SOURCE,
+          tokenBudget: null,
+        }
+      );
+      return createSensitiveReadResult(response);
+    },
+    { destinationId: args.destinationId ?? null }
+  );
+}
+
 /**
  * @param {{ calls?: Array<{ method?: string, params?: Record<string, unknown>, tabId?: number, destinationId?: string, budgetPreset?: 'quick' | 'normal' | 'deep' }> }} args
  * @returns {Promise<ToolResult>}
@@ -354,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);
@@ -361,17 +523,128 @@ export async function handleRawCallTool(args) {
       const response = await requestBridgeWithRetry(client, method, params, {
         tabId: typeof args.tabId === 'number' ? args.tabId : null,
         source: REQUEST_SOURCE,
-        tokenBudget: method.startsWith('screenshot.') ? null : getToolTokenBudget(args),
+        tokenBudget:
+          method.startsWith('screenshot.') || method === 'sensitive.read'
+            ? null
+            : getToolTokenBudget(args),
       });
       if (response.ok && method.startsWith('screenshot.')) {
         return createScreenshotResult(response, method);
       }
+      if (method === 'network.export_har') {
+        return createHarExportResult(response);
+      }
+      if (method === 'sensitive.read') {
+        return createSensitiveReadResult(response);
+      }
       return summarizeToolResponse(response, method, params);
     },
     { destinationId: args.destinationId ?? null }
   );
 }
 
+/**
+ * Preserve the atomic HAR payload exactly. Generic evidence bounding must not
+ * turn a valid HAR document into a structurally invalid partial document.
+ *
+ * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @returns {ToolResult}
+ */
+export function createHarExportResult(response) {
+  if (!response.ok) return summarizeToolResponse(response, 'network.export_har', {});
+  const result =
+    response.result && typeof response.result === 'object' && !Array.isArray(response.result)
+      ? /** @type {Record<string, unknown>} */ (response.result)
+      : {};
+  const numericFields = [
+    'byteLength',
+    'entryCount',
+    'totalEntries',
+    'dropped',
+    'abandoned',
+    'inflight',
+  ];
+  const captureState = result.captureState;
+  const validMetadata =
+    result.format === 'har' &&
+    result.harVersion === '1.2' &&
+    result.mimeType === 'application/json' &&
+    numericFields.every((field) => typeof result[field] === 'number') &&
+    (typeof result.startedAt === 'number' || result.startedAt === null) &&
+    (captureState === 'armed' ||
+      captureState === 'stop_failed' ||
+      captureState === 'stopped' ||
+      captureState === 'instrumented') &&
+    typeof result.truncated === 'boolean' &&
+    result.truncation !== null &&
+    typeof result.truncation === 'object';
+  if (!validMetadata) {
+    return summarizeToolError('network.export_har returned invalid HAR metadata.');
+  }
+
+  if (result.delivery === 'inline') {
+    if (!isHarDocument(result.har)) {
+      return summarizeToolError('network.export_har returned an invalid inline HAR document.');
+    }
+  } else if (result.delivery === 'artifact') {
+    const artifact =
+      result.artifact && typeof result.artifact === 'object' && !Array.isArray(result.artifact)
+        ? /** @type {Record<string, unknown>} */ (result.artifact)
+        : {};
+    if (
+      artifact.kind !== 'har' ||
+      artifact.mimeType !== 'application/json' ||
+      typeof artifact.artifactId !== 'string' ||
+      typeof artifact.byteLength !== 'number' ||
+      typeof artifact.sha256 !== 'string' ||
+      !/^[a-f0-9]{64}$/u.test(artifact.sha256) ||
+      typeof artifact.chunkSize !== 'number' ||
+      typeof artifact.chunkCount !== 'number' ||
+      typeof artifact.createdAt !== 'string' ||
+      typeof artifact.expiresAt !== 'string'
+    ) {
+      return summarizeToolError('network.export_har returned invalid artifact metadata.');
+    }
+  } else {
+    return summarizeToolError('network.export_har returned an invalid delivery mode.');
+  }
+
+  const summary = summarizeBridgeResponse(response, 'network.export_har');
+  return createToolResult(summary.summary, result);
+}
+
+/**
+ * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @returns {ToolResult}
+ */
+function createSensitiveReadResult(response) {
+  if (!response.ok) return summarizeToolResponse(response, 'sensitive.read', {});
+  const result =
+    response.result && typeof response.result === 'object'
+      ? /** @type {Record<string, unknown>} */ (response.result)
+      : {};
+  if (
+    (result.source !== 'local_storage' && result.source !== 'session_storage') ||
+    typeof result.value !== 'string' ||
+    result.exact !== true
+  ) {
+    return summarizeToolError('sensitive.read returned an invalid exact-value response.');
+  }
+  return {
+    content: [
+      {
+        type: 'text',
+        text: 'Sensitive storage read succeeded. The exact value is available in structuredContent.value.',
+      },
+    ],
+    structuredContent: {
+      source: result.source,
+      value: result.value,
+      exact: true,
+    },
+  };
+}
+
 /**
  * @typedef {{ method: BridgeMethod, params: (args: Record<string, unknown>) => Record<string, unknown> }} InvestigateStep
  */