@browserbridge/bbx 1.9.0 → 1.11.0

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

@@ -1,17 +1,54 @@
 // @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 LEGACY_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.',
+]);
+
+const MODERN_TOOL_RULES = Object.freeze([
+  'The compact tool list is static for stateless MCP. browser_call reaches every bridge method, and browser_skill returns runtime groups and limits.',
+  'Use browser_call method protocol.describe with method or group params to load unfamiliar signatures cheaply.',
+]);
+
+/**
+ * Build instructions for the negotiated MCP era.
+ *
+ * @param {'legacy' | 'modern'} [era='legacy']
+ * @returns {string}
+ */
+export function getMcpServerInstructions(era = 'legacy') {
+  const toolRules = era === 'modern' ? MODERN_TOOL_RULES : LEGACY_TOOL_RULES;
+  return [SERVER_HEADER, ...toolRules, ...SHARED_INSTRUCTIONS, ...WORKFLOW_INSTRUCTIONS].join('\n');
+}
+
+export const MCP_SERVER_INSTRUCTIONS = getMcpServerInstructions();
+export const MODERN_MCP_SERVER_INSTRUCTIONS = getMcpServerInstructions('modern');

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') {

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

@@ -1,12 +1,12 @@
 // @ts-check
 
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 
 import {
   BridgeError,
   bridgeMethodNeedsTab,
   DEFAULT_CONSOLE_LIMIT,
-  DEFAULT_HAR_LIMIT,
   DEFAULT_LOG_TAIL_LIMIT,
   DEFAULT_MAX_HTML_LENGTH,
   DEFAULT_MAX_NODES,
@@ -15,11 +15,21 @@ import {
   DEFAULT_TEXT_BUDGET,
   estimateJsonPayloadCost,
   getBudgetPreset,
+  getBudgetPresetName,
   getErrorRecovery,
-  isBudgetPresetName,
   summarizeBatchErrorItem,
   summarizeBatchResponseItem,
 } from '../../protocol/src/index.js';
+
+export {
+  applyHtmlBudgetPreset,
+  applyLimitBudgetPreset,
+  applyMethodBudgetPreset,
+  applyPageTextBudgetPreset,
+  applyTextBudgetPreset,
+  applyTreeBudgetPreset,
+  getBudgetPresetName,
+} from '../../protocol/src/index.js';
 import {
   getDoctorReport,
   requestBridge,
@@ -37,6 +47,18 @@ import { annotateBridgeSummary, summarizeBridgeResponse } from '../../agent-clie
 
 export const REQUEST_SOURCE = 'mcp';
 const MCP_CLIENT_ID = `mcp_${randomUUID()}`;
+/** @type {AsyncLocalStorage<import('../../protocol/src/types.js').McpProtocolEra>} */
+const MCP_REQUEST_ERA = new AsyncLocalStorage();
+
+/**
+ * @template T
+ * @param {import('../../protocol/src/types.js').McpProtocolEra} era
+ * @param {() => T} callback
+ * @returns {T}
+ */
+export function runWithMcpRequestEra(era, callback) {
+  return MCP_REQUEST_ERA.run(era, callback);
+}
 
 /** @type {ReadonlySet<BridgeMethod>} */
 const RETRY_SAFE_METHODS = new Set([
@@ -68,6 +90,8 @@ const RETRY_SAFE_METHODS = new Set([
   'screenshot.capture_region',
   'screenshot.capture_element',
   'screenshot.capture_full_page',
+  'artifact.read',
+  'network.intercept.list',
   'performance.get_metrics',
   'cdp.get_document',
   'cdp.get_dom_snapshot',
@@ -240,14 +264,6 @@ export async function resolveToolRef(client, input, tabId = null) {
   throw new BridgeError('INVALID_REQUEST', 'Provide either elementRef or selector.');
 }
 
-/**
- * @param {unknown} value
- * @returns {'quick' | 'normal' | 'deep' | null}
- */
-export function getBudgetPresetName(value) {
-  return isBudgetPresetName(value) ? value : null;
-}
-
 /**
  * @param {{ budgetPreset?: unknown, selector?: unknown, elementRef?: unknown }} args
  * @returns {'quick' | 'normal' | 'deep' | null}
@@ -271,162 +287,6 @@ export function getToolTokenBudget(args) {
   return presetName ? getBudgetPreset(presetName).tokenBudget : 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 {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;
-}
-
 /**
  * @param {unknown} input
  * @param {{ maxEntries?: number, maxCharacters?: number, maxStringLength?: number }} [options]
@@ -586,6 +446,14 @@ function getRequestAwareEvidence(rawResult, method, params, fallback) {
       limit: { maxEntries },
     };
   }
+  if (method?.startsWith('network.intercept.')) {
+    const bounded = boundToolValue(result, { maxEntries: 100, maxCharacters: 10_000 });
+    return {
+      value: bounded.value,
+      truncated: bounded.truncated,
+      limit: { maxEntries: 100, maxCharacters: 10_000 },
+    };
+  }
   if (
     (method === 'page.get_console' || method === 'page.get_network' || method === 'log.tail') &&
     Array.isArray(result.entries)
@@ -661,15 +529,123 @@ function compactDomNode(value) {
   return compact;
 }
 
+/**
+ * Socket-level Node error codes that mean the daemon connection itself was
+ * lost, as opposed to an application-level bridge failure.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const CONNECTION_LOSS_CODES = new Set([
+  'ENOTCONN',
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'EPIPE',
+  'ERR_SOCKET_CLOSED',
+]);
+
+const RECONNECT_WAIT_TIMEOUT_MS = 5_000;
+const RECONNECT_POLL_INTERVAL_MS = 250;
+
+/**
+ * Detect thrown transport errors caused by a lost daemon connection. These
+ * never arrive as bridge failure responses because the socket died before (or
+ * while) the daemon could reply.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isConnectionLossError(error) {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  const code = /** @type {{ code?: unknown }} */ (error).code;
+  if (typeof code === 'string' && CONNECTION_LOSS_CODES.has(code)) {
+    return true;
+  }
+  const message = error instanceof Error ? error.message : '';
+  return /Bridge socket closed|BridgeClient is not connected/u.test(message);
+}
+
+/**
+ * Wait, bounded, for the client to regain its daemon connection.
+ *
+ * When the client's own auto-reconnect loop is active it owns reconnecting and
+ * emits `reconnected`; otherwise one manual connect is attempted per poll
+ * interval. Application state is never touched here - this only restores the
+ * transport.
+ *
+ * @param {import('../../agent-client/src/client.js').BridgeClient} client
+ * @param {number} [timeoutMs=RECONNECT_WAIT_TIMEOUT_MS]
+ * @returns {Promise<boolean>}
+ */
+export async function waitForClientReconnect(client, timeoutMs = RECONNECT_WAIT_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  while (!client.connected && Date.now() < deadline) {
+    if (client.autoReconnect) {
+      await new Promise((resolve) => {
+        const remaining = Math.max(0, deadline - Date.now());
+        /** @type {ReturnType<typeof setTimeout>} */
+        let timer;
+        const cleanup = () => {
+          clearTimeout(timer);
+          client.off('reconnected', onReconnected);
+          resolve(undefined);
+        };
+        const onReconnected = () => cleanup();
+        timer = setTimeout(cleanup, Math.min(RECONNECT_POLL_INTERVAL_MS, remaining));
+        client.on('reconnected', onReconnected);
+      });
+      continue;
+    }
+    try {
+      await client.connect();
+    } catch (error) {
+      if (error instanceof Error && /already connected/u.test(error.message)) {
+        break;
+      }
+      // Daemon still unreachable; keep waiting inside the bounded window.
+    }
+    if (!client.connected) {
+      const remaining = Math.max(0, deadline - Date.now());
+      await new Promise((resolve) =>
+        setTimeout(resolve, Math.min(RECONNECT_POLL_INTERVAL_MS, remaining))
+      );
+    }
+  }
+  return client.connected;
+}
+
 /**
  * @param {import('../../agent-client/src/client.js').BridgeClient} client
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} params
- * @param {{ tabId?: number | null, source?: import('../../protocol/src/types.js').BridgeRequestSource, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} options
+ * @param {{ tabId?: number | null, source?: import('../../protocol/src/types.js').BridgeRequestSource, mcpEra?: import('../../protocol/src/types.js').McpProtocolEra, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} options
  * @returns {Promise<BridgeResponse>}
  */
 export async function requestBridgeWithRetry(client, method, params, options) {
-  const response = await requestBridge(client, method, params, options);
+  const requestOptions = {
+    ...options,
+    mcpEra: options.mcpEra ?? MCP_REQUEST_ERA.getStore(),
+  };
+  /** @type {BridgeResponse} */
+  let response;
+  try {
+    response = await requestBridge(client, method, params, requestOptions);
+  } catch (error) {
+    if (!isConnectionLossError(error) || !isRetrySafeBridgeMethod(method, params)) {
+      throw error;
+    }
+    process.stderr.write(
+      `[bbx-mcp] ${method} lost its daemon connection; waiting up to ${RECONNECT_WAIT_TIMEOUT_MS}ms for reconnect before one retry.\n`
+    );
+    if (!(await waitForClientReconnect(client))) {
+      throw error;
+    }
+    return requestBridge(client, method, params, {
+      ...requestOptions,
+      automaticRetry: 'mcp_second_attempt',
+    });
+  }
   const recovery =
     !response.ok && response.error
       ? (response.error.recovery ?? getErrorRecovery(response.error.code))
@@ -681,7 +657,7 @@ export async function requestBridgeWithRetry(client, method, params, options) {
     );
     await new Promise((r) => setTimeout(r, delay));
     return requestBridge(client, method, params, {
-      ...options,
+      ...requestOptions,
       automaticRetry: 'mcp_second_attempt',
     });
   }