@vellumai/assistant 0.6.3 → 0.6.5

package/src/tools/browser/browser-execution.ts

@@ -1,7 +1,10 @@
+import { getConfig } from "../../config/loader.js";
 import type { ImageContent } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import { truncate } from "../../util/truncate.js";
+import { safeStringSlice } from "../../util/unicode.js";
 import { credentialBroker } from "../credentials/broker.js";
+import { BROWSER_FILL_CAPABILITY } from "../credentials/tool-policy.js";
 import {
   isPrivateOrLocalHost,
   parseUrl,
@@ -17,12 +20,22 @@ import {
 } from "./auth-detector.js";
 import type { RouteHandler } from "./browser-manager.js";
 import { browserManager } from "./browser-manager.js";
+import { type BrowserMode, normalizeBrowserMode } from "./browser-mode.js";
+import { BROWSER_MODE } from "./browser-mode-constants.js";
 import {
   ensureScreencast,
   getSender,
   stopAllScreencasts,
   stopBrowserScreencast,
 } from "./browser-screencast.js";
+import {
+  BROWSER_STATUS_INPUT_FIELD,
+  BROWSER_STATUS_MODE,
+  BROWSER_STATUS_MODES,
+  type BrowserStatusMode,
+  CDP_INSPECT_STATUS_DISCOVERY_CODE,
+  EXTENSION_STATUS_ERROR_MARKER,
+} from "./browser-status-constants.js";
 import {
   formatAxSnapshot,
   transformAxTree,
@@ -45,8 +58,18 @@ import {
   waitForSelector as cdpWaitForSelector,
   waitForText as cdpWaitForText,
 } from "./cdp-client/cdp-dom-helpers.js";
-import { getCdpClient } from "./cdp-client/factory.js";
-import type { CdpClient } from "./cdp-client/types.js";
+import { CdpError } from "./cdp-client/errors.js";
+import {
+  buildCandidateList,
+  getCdpClient,
+  isDesktopAutoCooldownActive,
+} from "./cdp-client/factory.js";
+import type {
+  AttemptDiagnostic,
+  CdpClient,
+  CdpClientKind,
+} from "./cdp-client/types.js";
+import { checkBrowserRuntime } from "./runtime-check.js";
 
 const log = getLogger("headless-browser");
 
@@ -60,6 +83,40 @@ export const MAX_WAIT_MS = 30_000;
 
 export const MAX_EXTRACT_LENGTH = 50_000;
 
+type StatusCheckMode = BrowserStatusMode;
+
+const MODE_TRADEOFFS: Record<StatusCheckMode, string[]> = {
+  [BROWSER_STATUS_MODE.EXTENSION]: [
+    "This is the preferred approach for all things browser-use.",
+    "It requires a one-time install of the Vellum Assistant Chrome Extension.",
+    "More secure than relying on Chrome's native remote debugging functionality.",
+    "Requires the Vellum extension to be paired and actively connected.",
+  ],
+  [BROWSER_STATUS_MODE.CDP_INSPECT]: [
+    "This is the second-best approach for all things browser-use, after the native Vellum Assistant Chrome Extension.",
+    "It requires Chrome version 146 or greater",
+    "It requires toggling on remote debugging in Chrome Settings",
+    "It's prone to phishing attacks from other local processes that may try to do their own remote debugging.",
+  ],
+  [BROWSER_STATUS_MODE.LOCAL]: [
+    "The least-preferred approach for all things browser-use.",
+    "Considered a last-resort fallback if the user has not installed the Chrome Extension or enabled remote debugging in Chrome, and has indicated that they do not want to.",
+    "Does not use the user's existing browser profile, so sessions/cookies may differ.",
+    "Requires that Playwright and Chromium are installed on the host machine,",
+  ],
+};
+
+interface BrowserStatusModeResult {
+  mode: StatusCheckMode;
+  available: boolean;
+  verified: "active_probe" | "preflight";
+  autoCandidate: boolean;
+  summary: string;
+  userActions: string[];
+  tradeoffs: string[];
+  details: Record<string, unknown>;
+}
+
 /**
  * IIFE evaluated inside the page via `Runtime.evaluate` to auto-dismiss
  * common blocker modals (regulatory notices, cookie banners) that
@@ -99,6 +156,337 @@ export const EXTRACT_LINKS_EXPRESSION = `
 })()
 `;
 
+// ── browser_mode parsing ─────────────────────────────────────────────
+
+/**
+ * Parse the `browser_mode` field from a tool input map. Returns either
+ * a normalized {@link BrowserMode} or a pre-formatted error string
+ * suitable for returning directly in a tool response.
+ *
+ * When the value is absent, undefined, or empty the default `"auto"`
+ * is returned. Invalid values produce a descriptive error listing
+ * accepted values and aliases.
+ */
+export function parseBrowserMode(
+  input: Record<string, unknown>,
+): { ok: true; mode: BrowserMode } | { ok: false; error: string } {
+  const raw = input.browser_mode;
+  const result = normalizeBrowserMode(raw);
+  if ("error" in result) {
+    return { ok: false, error: `Error: ${result.error}` };
+  }
+  return { ok: true, mode: result.mode };
+}
+
+// ── Mode-selection failure formatter ─────────────────────────────────
+
+/**
+ * Remediation hints keyed by (candidateKind, discoveryCode | errorCode).
+ * Discovery codes come from DevToolsDiscoveryError; error codes come
+ * from CdpError. The formatter walks these in priority order: exact
+ * (kind, discoveryCode) first, then (kind, errorCode), then a generic
+ * per-kind fallback.
+ */
+const REMEDIATION_HINTS: Record<string, string[]> = {
+  // Extension backend
+  "extension:transport_error": [
+    "Ensure the Vellum browser extension is installed and enabled.",
+    "Check that the extension WebSocket connection is active (extension popup → status).",
+    "Try reconnecting the extension or reloading the extension service worker.",
+  ],
+  // cdp-inspect backend — discovery-level failures
+  "cdp-inspect:unreachable": [
+    "Ensure that Chrome is on version 146 or higher by going to chrome://settings/help.",
+    'Ensure that you have toggled on "Allow remote debugging for this browser instance" by going to chrome://inspect/#remote-debugging',
+    "Verify no firewall or antivirus is blocking localhost:9222.",
+  ],
+  "cdp-inspect:non_chrome": [
+    "The process listening on the configured port is not Chrome/Chromium.",
+    "Check if another application (dev server, proxy) is using port 9222.",
+    "Ensure Chrome is launched with --remote-debugging-port=9222.",
+  ],
+  "cdp-inspect:timeout": [
+    "Chrome DevTools endpoint did not respond within the probe timeout.",
+    "Ensure Chrome is running and listening on the configured port.",
+    "Try increasing hostBrowser.cdpInspect.probeTimeoutMs in config.",
+  ],
+  "cdp-inspect:no_targets": [
+    "Chrome is reachable but has no open page targets.",
+    "Open at least one browser tab, then retry.",
+  ],
+  "cdp-inspect:non_loopback": [
+    "CDP inspect only allows loopback hosts (localhost, 127.0.0.1, ::1).",
+    "Update hostBrowser.cdpInspect.host in config to a loopback address.",
+  ],
+  "cdp-inspect:transport_error": [
+    "CDP endpoint unreachable. Ensure Chrome is running with --remote-debugging-port.",
+    "Verify the configured host:port matches Chrome's DevTools listener.",
+    "Consider using browser_mode: 'extension' or 'local' as an alternative.",
+  ],
+  // Local/Playwright backend
+  "local:transport_error": [
+    "The local Playwright-managed browser failed to start or connect.",
+    "Check that the Playwright browser binary is downloaded (bun run install).",
+    "Try closing any stale Chromium processes and retrying.",
+  ],
+};
+
+/**
+ * Build a human-readable, tool-response-ready error string from a
+ * pinned-mode failure. Includes:
+ *   - the requested mode
+ *   - ordered attempted modes with exact failure reasons
+ *   - a remediation checklist tailored by backend and failure code
+ *
+ * Exported for testing.
+ */
+export function formatModeSelectionFailure(
+  requestedMode: BrowserMode,
+  error: CdpError,
+): string {
+  const lines: string[] = [];
+  lines.push(`Error: Browser mode "${requestedMode}" failed.`);
+  lines.push("");
+
+  const diagnostics: readonly AttemptDiagnostic[] =
+    error.attemptDiagnostics ?? [];
+
+  if (diagnostics.length > 0) {
+    lines.push("Attempted backends:");
+    for (const diag of diagnostics) {
+      const status =
+        diag.stage === "success" ? "OK" : `FAILED at ${diag.stage}`;
+      lines.push(`  - ${diag.candidateKind}: ${status}`);
+      if (diag.errorMessage) {
+        lines.push(`    Reason: ${diag.errorMessage}`);
+      }
+      if (diag.discoveryCode) {
+        lines.push(`    Discovery code: ${diag.discoveryCode}`);
+      }
+    }
+    lines.push("");
+  }
+
+  // Collect remediation hints
+  const hints = collectRemediationHints(diagnostics, error);
+  if (hints.length > 0) {
+    lines.push("Remediation:");
+    for (const hint of hints) {
+      lines.push(`  - ${hint}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Gather remediation hints based on attempt diagnostics and the error.
+ * Walks each diagnostic and looks up hints by (kind, discoveryCode),
+ * then (kind, errorCode), then generic kind-level fallback.
+ */
+function collectRemediationHints(
+  diagnostics: readonly AttemptDiagnostic[],
+  error: CdpError,
+): string[] {
+  const seen = new Set<string>();
+  const hints: string[] = [];
+
+  const addHints = (key: string) => {
+    const list = REMEDIATION_HINTS[key];
+    if (!list) return;
+    for (const hint of list) {
+      if (!seen.has(hint)) {
+        seen.add(hint);
+        hints.push(hint);
+      }
+    }
+  };
+
+  for (const diag of diagnostics) {
+    if (diag.stage === "success") continue;
+    if (diag.discoveryCode) {
+      addHints(`${diag.candidateKind}:${diag.discoveryCode}`);
+    }
+    if (diag.errorCode) {
+      addHints(`${diag.candidateKind}:${diag.errorCode}`);
+    }
+  }
+
+  // Fallback: if no diagnostics but we have a top-level error, use
+  // the error code with a generic candidate kind derived from the mode.
+  if (diagnostics.length === 0 && error.code) {
+    // Try to infer the candidate kind from the error message
+    for (const kind of BROWSER_STATUS_MODES) {
+      if (error.message.toLowerCase().includes(kind)) {
+        addHints(`${kind}:${error.code}`);
+      }
+    }
+  }
+
+  return hints;
+}
+
+/**
+ * Detect the common extension CDP failure where the active tab is a
+ * restricted Chrome internal page (e.g. `chrome://newtab`).
+ */
+function isRestrictedChromePageProbeError(error: CdpError): boolean {
+  return error.message.toLowerCase().includes("chrome://");
+}
+
+/**
+ * Parse browser_mode from input and acquire a CdpClient. Returns
+ * either a `{ cdp, browserMode }` pair on success or a pre-formatted
+ * `{ errorResult }` on failure (invalid mode or pinned-mode
+ * precondition not met).
+ *
+ * This is the single integration point for all CDP-backed tool
+ * functions. Using it ensures every tool:
+ *   - normalizes aliases (`cdp-debugger` -> `cdp-inspect`, etc.)
+ *   - passes the mode preference to the factory
+ *   - surfaces a remediation-rich error on pinned-mode failures
+ *
+ * Per-conversation stickiness: when the incoming `browser_mode` is
+ * `"auto"` and the conversation has already resolved to a backend
+ * kind on a prior call, the factory is pinned to that kind instead
+ * of re-running the auto priority list. This prevents
+ * `browser_navigate` (e.g. pinned to `local`) and `browser_screenshot`
+ * (default auto) in the same conversation from landing on different
+ * Chrome instances. Explicit non-auto modes override and update the
+ * memo; teardown via browser_close / browser_detach clears it.
+ *
+ * The returned client is wrapped so its first successful `send()`
+ * writes the resolved kind back to the conversation memo.
+ */
+export function acquireCdpClientWithMode(
+  input: Record<string, unknown>,
+  context: ToolContext,
+):
+  | {
+      cdp: ReturnType<typeof getCdpClient>;
+      browserMode: BrowserMode;
+      errorResult?: never;
+    }
+  | { cdp?: never; browserMode?: never; errorResult: ToolExecutionResult } {
+  const modeResult = parseBrowserMode(input);
+  if (!modeResult.ok) {
+    return {
+      errorResult: { content: modeResult.error, isError: true },
+    };
+  }
+  const browserMode = modeResult.mode;
+
+  const rememberedKind = browserManager.getPreferredBackendKind(
+    context.conversationId,
+  );
+  const effectiveMode: BrowserMode =
+    browserMode === "auto" && rememberedKind !== null
+      ? rememberedKind
+      : browserMode;
+
+  try {
+    const raw = getCdpClient(context, { mode: effectiveMode });
+    const cdp = wrapWithKindMemo(raw, context.conversationId);
+    return { cdp, browserMode };
+  } catch (err) {
+    // Sticky-mode fallback: the caller requested "auto" but we pinned to
+    // a remembered backend kind that has since become unavailable. Drop
+    // the stale memo and retry with fresh auto selection so a dead
+    // sticky preference doesn't surface as a hard failure.
+    if (browserMode === "auto" && effectiveMode !== "auto") {
+      browserManager.clearPreferredBackendKind(context.conversationId);
+      try {
+        const raw = getCdpClient(context, { mode: "auto" });
+        const cdp = wrapWithKindMemo(raw, context.conversationId);
+        return { cdp, browserMode };
+      } catch (retryErr) {
+        if (retryErr instanceof CdpError) {
+          return {
+            errorResult: {
+              content: formatModeSelectionFailure("auto", retryErr),
+              isError: true,
+            },
+          };
+        }
+        throw retryErr;
+      }
+    }
+    if (err instanceof CdpError && browserMode !== "auto") {
+      return {
+        errorResult: {
+          content: formatModeSelectionFailure(browserMode, err),
+          isError: true,
+        },
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Wrap a {@link ScopedCdpClient} so the first successful `send()`
+ * records the resolved backend kind in the conversation's
+ * `preferredBackendKinds` memo. Subsequent sends are no-ops for the
+ * memo; dispose() delegates to the underlying client.
+ */
+function wrapWithKindMemo(
+  inner: ReturnType<typeof getCdpClient>,
+  conversationId: string,
+): ReturnType<typeof getCdpClient> {
+  let recorded = false;
+  return {
+    get kind() {
+      return inner.kind;
+    },
+    conversationId: inner.conversationId,
+    async send<T = unknown>(
+      method: string,
+      params?: Record<string, unknown>,
+      signal?: AbortSignal,
+    ): Promise<T> {
+      const result = await inner.send<T>(method, params, signal);
+      if (!recorded) {
+        browserManager.setPreferredBackendKind(conversationId, inner.kind);
+        recorded = true;
+      }
+      return result;
+    },
+    dispose(): void {
+      inner.dispose();
+    },
+  };
+}
+
+// ── CDP error diagnostics helper ─────────────────────────────────────
+
+/**
+ * Check whether a caught error is a {@link CdpError} carrying
+ * {@link AttemptDiagnostic attempt diagnostics} from the factory's
+ * failover walk. When the browser_mode is pinned (not "auto") and
+ * diagnostics are present, format the error with the full remediation
+ * checklist via {@link formatModeSelectionFailure}. Otherwise return
+ * `null` so the caller falls through to its generic error message.
+ *
+ * This handles the case where pinned-mode unavailability is surfaced
+ * on the first `cdp.send()` (via `sendWithFailover`) rather than
+ * during client construction (which `acquireCdpClientWithMode` already
+ * covers).
+ */
+function formatCdpSendDiagnostics(
+  err: unknown,
+  browserMode: BrowserMode,
+): string | null {
+  if (
+    err instanceof CdpError &&
+    browserMode !== "auto" &&
+    err.code === "transport_error" &&
+    err.attemptDiagnostics
+  ) {
+    return formatModeSelectionFailure(browserMode, err);
+  }
+  return null;
+}
+
 // ── Shared element resolution ────────────────────────────────────────
 
 /**
@@ -154,7 +542,7 @@ export function resolveElement(
     }
     return {
       resolved: null,
-      error: `Error: element_id "${elementId}" not found. Run browser_snapshot first to get current element IDs.`,
+      error: `Error: element_id "${elementId}" not found. Run a snapshot first to get current element IDs.`,
     };
   }
 
@@ -174,6 +562,8 @@ export async function executeBrowserNavigate(
     return { content: "Error: operation was cancelled", isError: true };
   }
 
+  // Pre-flight URL validation runs before CDP acquisition so we fail
+  // fast on obviously invalid URLs without opening a browser session.
   const parsedUrl = parseUrl(input.url);
   if (!parsedUrl) {
     return {
@@ -212,7 +602,10 @@ export async function executeBrowserNavigate(
     }
   }
 
-  const cdp = getCdpClient(context);
+  // URL validation passed — acquire the CDP client.
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const { cdp, browserMode } = acquired;
 
   // Screencast + handoff are Playwright-backed and only meaningful
   // for the local sacrificial-profile path. On the extension path the
@@ -223,10 +616,12 @@ export async function executeBrowserNavigate(
     await ensureScreencast(context.conversationId);
   }
 
-  // SSRF route interception is a Playwright-specific affordance used on
-  // the local path to block redirect-time requests to private networks.
-  // On the extension path we rely on the pre-CDP URL validation above;
-  // see phase3-cdp-migration.md PR 7 for the rationale.
+  // SSRF route interception uses the Playwright page.route() API to
+  // block redirect-time requests to private networks. This only works
+  // on the local path where Playwright manages the browser; on the
+  // extension/cdp-inspect paths, CDP navigates a different browser so
+  // the Playwright route handler would be a no-op. The post-navigation
+  // final URL check below provides defense-in-depth for all paths.
   let routeHandler: RouteHandler | null = null;
   let blockedUrl: string | null = null;
 
@@ -338,6 +733,53 @@ export async function executeBrowserNavigate(
       { timeoutMs: NAVIGATE_TIMEOUT_MS },
       context.signal,
     );
+
+    // Defense-in-depth: check the final URL after navigation completes.
+    // This catches redirect-based SSRF even when Playwright route
+    // interception is unavailable (e.g. extension-backed sessions where
+    // the CDP transport is separate from the Playwright page).
+    if (!allowPrivateNetwork) {
+      const finalParsed = parseUrl(finalUrl);
+      if (
+        finalParsed &&
+        (isPrivateOrLocalHost(finalParsed.hostname) ||
+          (
+            await resolveRequestAddress(
+              finalParsed.hostname,
+              resolveHostAddresses,
+              false,
+            )
+          ).blockedAddress)
+      ) {
+        // Navigate the page away from the private target to prevent
+        // follow-up operations (e.g. snapshot) from reading the
+        // already-loaded private content.
+        try {
+          await navigateAndWait(
+            cdp,
+            "about:blank",
+            { timeoutMs: 3_000 },
+            context.signal,
+          );
+        } catch {
+          // Best-effort — if the reset fails, the CDP session will be
+          // disposed in the finally block anyway.
+        }
+        // Clean up the route handler before returning to avoid leaking
+        // a stale interception handler on the session page.
+        if (routeHandler) {
+          const page = await browserManager.getOrCreateSessionPage(
+            context.conversationId,
+          );
+          await page.unroute("**/*", routeHandler);
+          routeHandler = null;
+        }
+        return {
+          content: `Error: Navigation blocked. Final URL resolved to a local/private network target (${sanitizeUrlForOutput(finalParsed)}). Set allow_private_network=true if you explicitly need it.`,
+          isError: true,
+        };
+      }
+    }
     if (navigationTimedOut) {
       // If the page URL never changed from before navigation, the page
       // never actually loaded - re-throw instead of reporting success.
@@ -353,7 +795,7 @@ export async function executeBrowserNavigate(
     }
 
     // Remove the Playwright route handler now that navigation is
-    // complete (local path only).
+    // complete (local path only — route interception is gated above).
     if (routeHandler) {
       const page = await browserManager.getOrCreateSessionPage(
         context.conversationId,
@@ -417,7 +859,7 @@ export async function executeBrowserNavigate(
 
     if (navigationTimedOut) {
       lines.push(
-        `Note: Page is still loading (document.readyState timed out). The page should still be interactive - use browser_snapshot to check.`,
+        `Note: Page is still loading (document.readyState timed out). The page should still be interactive - take a snapshot to check.`,
       );
     }
 
@@ -487,14 +929,12 @@ export async function executeBrowserNavigate(
               lines.push("");
               lines.push(formatAuthChallenge(postCaptchaAuth));
               lines.push("");
+              lines.push("Handle this by interacting with the login form:");
               lines.push(
-                "Handle this by using browser tools to interact with the login form:",
+                "1. Take a snapshot to find the sign-in form elements",
               );
               lines.push(
-                "1. Use browser_snapshot to find the sign-in form elements",
-              );
-              lines.push(
-                "2. Use browser_fill_credential to fill email/password from credential_store",
+                "2. Use credential fill to enter email/password from credential_store",
               );
               lines.push(
                 "3. For email verification codes, use ui_show with a form to ask the user for the code mid-turn",
@@ -514,18 +954,14 @@ export async function executeBrowserNavigate(
           }
         } else {
           // Login / 2FA / OAuth - the agent should handle these itself
-          // using browser tools + credential_store. Don't hand off.
+          // using browser operations + credential_store. Don't hand off.
           lines.push("");
           lines.push(formatAuthChallenge(challenge));
           lines.push("");
+          lines.push("Handle this by interacting with the login form:");
+          lines.push("1. Take a snapshot to find the sign-in form elements");
           lines.push(
-            "Handle this by using browser tools to interact with the login form:",
-          );
-          lines.push(
-            "1. Use browser_snapshot to find the sign-in form elements",
-          );
-          lines.push(
-            "2. Use browser_fill_credential to fill email/password from credential_store",
+            "2. Use credential fill to enter email/password from credential_store",
           );
           lines.push(
             "3. For email verification codes, use ui_show with a form to ask the user for the code mid-turn",
@@ -563,6 +999,11 @@ export async function executeBrowserNavigate(
       };
     }
 
+    const diagnosticMessage = formatCdpSendDiagnostics(err, browserMode);
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
+
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err, url: safeRequestedUrl }, "Navigation failed");
     return { content: `Error: Navigation failed: ${msg}`, isError: true };
@@ -571,13 +1012,16 @@ export async function executeBrowserNavigate(
   }
 }
 
-// ── browser_snapshot ─────────────────────────────────────────────────
+// ── snapshot ─────────────────────────────────────────────────────────
 
 export async function executeBrowserSnapshot(
   _input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(_input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const { cdp, browserMode } = acquired;
+
   try {
     const currentUrl = await getCurrentUrl(cdp, context.signal);
     const title = await getPageTitle(cdp, context.signal);
@@ -608,6 +1052,10 @@ export async function executeBrowserSnapshot(
       isError: false,
     };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(err, browserMode);
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Snapshot failed");
     return { content: `Error: Snapshot failed: ${msg}`, isError: true };
@@ -622,9 +1070,11 @@ export async function executeBrowserScreenshot(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const { cdp, browserMode } = acquired;
   const fullPage = input.full_page === true;
 
-  const cdp = getCdpClient(context);
   try {
     const buffer = await captureScreenshotJpeg(
       cdp,
@@ -650,6 +1100,10 @@ export async function executeBrowserScreenshot(
       contentBlocks: [imageBlock],
     };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(err, browserMode);
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Screenshot failed");
     return { content: `Error: Screenshot failed: ${msg}`, isError: true };
@@ -658,13 +1112,118 @@ export async function executeBrowserScreenshot(
   }
 }
 
+// ── browser_attach ───────────────────────────────────────────────────
+
+export async function executeBrowserAttach(
+  _input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const acquired = acquireCdpClientWithMode(_input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
+  try {
+    if (cdp.kind === "extension") {
+      // Extension path: explicitly attach the debugger via a synthetic
+      // Vellum.attach command so the debugging session is established
+      // before any navigation or interaction.
+      const result = await cdp.send<{ attached?: boolean; target?: unknown }>(
+        "Vellum.attach",
+        {},
+        context.signal,
+      );
+      log.debug(
+        { conversationId: context.conversationId, result },
+        "Browser debugger attached (extension)",
+      );
+      return {
+        content: "Browser debugger attached.",
+        isError: false,
+      };
+    }
+
+    // Non-extension backends (local / cdp-inspect): explicit attach is
+    // not required — the backend manages its own connection lifecycle.
+    // Return a deterministic no-op success.
+    return {
+      content:
+        "Browser session ready. (Explicit attach is not required on this backend.)",
+      isError: false,
+    };
+  } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ err }, "Attach failed");
+    return { content: `Error: Attach failed: ${msg}`, isError: true };
+  } finally {
+    cdp.dispose();
+  }
+}
+
+// ── browser_detach ──────────────────────────────────────────────────
+
+export async function executeBrowserDetach(
+  _input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const acquired = acquireCdpClientWithMode(_input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
+  try {
+    if (cdp.kind === "extension") {
+      // Extension path: explicitly detach the debugger via a synthetic
+      // Vellum.detach command so the Chrome debugging banner clears.
+      const result = await cdp.send<{ detached?: boolean; target?: unknown }>(
+        "Vellum.detach",
+        {},
+        context.signal,
+      );
+      log.debug(
+        { conversationId: context.conversationId, result },
+        "Browser debugger detached (extension)",
+      );
+    }
+
+    return {
+      content: "Browser debugger detached and snapshot state cleared.",
+      isError: false,
+    };
+  } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ err }, "Detach failed");
+    return { content: `Error: Detach failed: ${msg}`, isError: true };
+  } finally {
+    // Always reset conversation-scoped browser state, even if the
+    // Vellum.detach round-trip failed (target gone, transport dropped).
+    // browser_detach is the user's recovery path — leaving a stale
+    // sticky backend or snapshot map behind would defeat its purpose.
+    browserManager.clearSnapshotBackendNodeMap(context.conversationId);
+    browserManager.clearPreferredBackendKind(context.conversationId);
+    cdp.dispose();
+  }
+}
+
 // ── browser_close ────────────────────────────────────────────────────
 
 export async function executeBrowserClose(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     if (cdp.kind === "local") {
       // Local/sacrificial-profile path: tear down the Playwright page,
@@ -690,15 +1249,29 @@ export async function executeBrowserClose(
     }
 
     // Extension path: the user owns their Chrome tab — we must not
-    // close it. Only drop the cached snapshot state so stale eids
-    // from prior snapshots cannot be resolved by later tool calls.
+    // close it. Detach the debugger (so the Chrome debugging banner
+    // clears promptly) and drop the cached snapshot state so stale
+    // eids from prior snapshots cannot be resolved by later tool calls.
+    try {
+      await cdp.send("Vellum.detach", {}, context.signal);
+    } catch {
+      // Tolerate detach failures (already detached, tab closed, etc.)
+    }
     browserManager.clearSnapshotBackendNodeMap(context.conversationId);
+    browserManager.clearPreferredBackendKind(context.conversationId);
     return {
       content:
         "Browser session cleared. (Your Chrome tab was not closed — close it yourself if desired.)",
       isError: false,
     };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Close failed");
     return { content: `Error: Close failed: ${msg}`, isError: true };
@@ -716,7 +1289,9 @@ export async function executeBrowserClick(
   const { resolved, error } = resolveElement(context.conversationId, input);
   if (error) return { content: error, isError: true };
 
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     let backendNodeId: number;
     if (resolved!.kind === "backend") {
@@ -744,6 +1319,13 @@ export async function executeBrowserClick(
         : resolved!.selector;
     return { content: `Clicked element: ${desc}`, isError: false };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Click failed");
     return { content: `Error: Click failed: ${msg}`, isError: true };
@@ -828,7 +1410,9 @@ export async function executeBrowserType(
       ? `element_id "${resolved!.eid}"`
       : resolved!.selector;
 
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     let backendNodeId: number;
     if (resolved!.kind === "backend") {
@@ -857,6 +1441,13 @@ export async function executeBrowserType(
     if (pressEnter) lines.push("(pressed Enter after typing)");
     return { content: lines.join("\n"), isError: false };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err, target: targetDescription }, "Type failed");
     return { content: `Error: Type failed: ${msg}`, isError: true };
@@ -896,7 +1487,9 @@ export async function executeBrowserPressKey(
         : resolved!.selector;
   }
 
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     if (resolved) {
       let backendNodeId: number;
@@ -921,6 +1514,13 @@ export async function executeBrowserPressKey(
     await dispatchKeyPress(cdp, key, context.signal);
     return { content: `Pressed "${key}"`, isError: false };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err, key }, "Press key failed");
     return { content: `Error: Press key failed: ${msg}`, isError: true };
@@ -964,7 +1564,9 @@ export async function executeBrowserScroll(
       break;
   }
 
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     // Fetch viewport dimensions so we can dispatch the wheel event at
     // the viewport center — scrolling from (0, 0) misses sticky
@@ -985,6 +1587,13 @@ export async function executeBrowserScroll(
 
     return { content: `Scrolled ${direction} by ${amount}px`, isError: false };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err, direction }, "Scroll failed");
     return { content: `Error: Scroll failed: ${msg}`, isError: true };
@@ -1018,7 +1627,9 @@ export async function executeBrowserSelectOption(
       ? `element_id "${resolved!.eid}"`
       : resolved!.selector;
 
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     let backendNodeId: number;
     if (resolved!.kind === "backend") {
@@ -1108,6 +1719,13 @@ export async function executeBrowserSelectOption(
       isError: false,
     };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err, target: targetDescription }, "Select option failed");
     return { content: `Error: Select option failed: ${msg}`, isError: true };
@@ -1125,7 +1743,9 @@ export async function executeBrowserHover(
   const { resolved, error } = resolveElement(context.conversationId, input);
   if (error) return { content: error, isError: true };
 
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     let backendNodeId: number;
     if (resolved!.kind === "backend") {
@@ -1150,6 +1770,13 @@ export async function executeBrowserHover(
         : resolved!.selector;
     return { content: `Hovered element: ${desc}`, isError: false };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Hover failed");
     return { content: `Error: Hover failed: ${msg}`, isError: true };
@@ -1195,6 +1822,13 @@ export async function executeBrowserWaitFor(
       ? Math.min(input.timeout, MAX_WAIT_MS)
       : MAX_WAIT_MS;
 
+  // Validate browser_mode even on the duration path so invalid values
+  // are rejected consistently regardless of which wait mode is used.
+  const modeResult = parseBrowserMode(input);
+  if (!modeResult.ok) {
+    return { content: modeResult.error, isError: true };
+  }
+
   // Duration mode has no CDP interaction — handle without acquiring
   // a CdpClient so the common "sleep" path stays transport-agnostic.
   if (duration != null) {
@@ -1203,7 +1837,9 @@ export async function executeBrowserWaitFor(
     return { content: `Waited ${waitMs}ms.`, isError: false };
   }
 
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     if (selector) {
       // browser_wait_for selector mode is "did this node appear at
@@ -1227,6 +1863,13 @@ export async function executeBrowserWaitFor(
       isError: false,
     };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Wait failed");
     return { content: `Error: Wait failed: ${msg}`, isError: true };
@@ -1243,7 +1886,9 @@ export async function executeBrowserExtract(
 ): Promise<ToolExecutionResult> {
   const includeLinks = input.include_links === true;
 
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     const currentUrl = await getCurrentUrl(cdp, context.signal);
     const title = await getPageTitle(cdp, context.signal);
@@ -1257,7 +1902,8 @@ export async function executeBrowserExtract(
 
     if (textContent.length > MAX_EXTRACT_LENGTH) {
       textContent =
-        textContent.slice(0, MAX_EXTRACT_LENGTH) + "\n... (truncated)";
+        safeStringSlice(textContent, 0, MAX_EXTRACT_LENGTH) +
+        "\n... (truncated)";
     }
 
     const lines: string[] = [
@@ -1283,6 +1929,13 @@ export async function executeBrowserExtract(
 
     return { content: lines.join("\n"), isError: false };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Extract failed");
     return { content: `Error: Extract failed: ${msg}`, isError: true };
@@ -1291,7 +1944,7 @@ export async function executeBrowserExtract(
   }
 }
 
-// ── browser_fill_credential ──────────────────────────────────────────
+// ── browser credential fill ──────────────────────────────────────────
 
 export async function executeBrowserFillCredential(
   input: Record<string, unknown>,
@@ -1316,7 +1969,9 @@ export async function executeBrowserFillCredential(
       ? `element_id "${resolved!.eid}"`
       : resolved!.selector;
 
-  const cdp = getCdpClient(context);
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
     let backendNodeId: number;
     if (resolved!.kind === "backend") {
@@ -1347,7 +2002,7 @@ export async function executeBrowserFillCredential(
     const result = await credentialBroker.browserFill({
       service,
       field,
-      toolName: "browser_fill_credential",
+      toolName: BROWSER_FILL_CAPABILITY,
       domain: pageDomain,
       fill: async (value) => {
         // Clear-then-focus-then-insert via the shared helper. We
@@ -1405,6 +2060,13 @@ export async function executeBrowserFillCredential(
       isError: false,
     };
   } catch (err) {
+    const diagnosticMessage = formatCdpSendDiagnostics(
+      err,
+      acquired.browserMode,
+    );
+    if (diagnosticMessage) {
+      return { content: diagnosticMessage, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Fill credential failed");
     return { content: `Error: Fill credential failed: ${msg}`, isError: true };
@@ -1412,3 +2074,508 @@ export async function executeBrowserFillCredential(
     cdp.dispose();
   }
 }
+
+function dedupeStrings(values: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const value of values) {
+    if (!value) continue;
+    if (seen.has(value)) continue;
+    seen.add(value);
+    out.push(value);
+  }
+  return out;
+}
+
+function modeTradeoffs(mode: StatusCheckMode): string[] {
+  return MODE_TRADEOFFS[mode];
+}
+
+function extensionSetupActions(): string[] {
+  return [
+    "Install the Vellum Assistant Chrome extension from the Chrome Web Store: https://chromewebstore.google.com/detail/vellum-assistant-browser/hphbdmpffeigpcdjkckleobjmhhokpne",
+    "Open the extension and pair with your assistant.",
+  ];
+}
+
+function cdpInspectSetupActions(): string[] {
+  return [
+    "Update Chrome to the latest version by going to chrome://settings/help",
+    "Navigate directly to chrome://inspect/#remote-debugging",
+    'Check the box next to "Allow remote debugging for this browser instance"',
+  ];
+}
+
+function localSetupActions(): string[] {
+  return [
+    "Ask your assistant to install playwright and chromium on your host machine.",
+  ];
+}
+
+function extractDiscoveryCodes(error: CdpError): string[] {
+  const diagnostics = error.attemptDiagnostics ?? [];
+  const codes: string[] = [];
+  for (const diag of diagnostics) {
+    if (diag.discoveryCode) codes.push(diag.discoveryCode);
+  }
+  return dedupeStrings(codes);
+}
+
+function containsTokenCaseInsensitive(text: string, token: string): boolean {
+  return text.toLowerCase().includes(token.toLowerCase());
+}
+
+function probeFailureActions(mode: StatusCheckMode, error: CdpError): string[] {
+  const actions: string[] = [];
+  const message = error.message.toLowerCase();
+  const discoveryCodes = extractDiscoveryCodes(error).map((c) =>
+    c.toLowerCase(),
+  );
+
+  if (mode === BROWSER_STATUS_MODE.EXTENSION) {
+    actions.push(...extensionSetupActions());
+    if (
+      containsTokenCaseInsensitive(
+        message,
+        EXTENSION_STATUS_ERROR_MARKER.UNAUTHORIZED_ORIGIN,
+      )
+    ) {
+      actions.push(
+        "Ensure this extension ID is present in meta/browser-extension/chrome-extension-allowlist.json and restart the assistant.",
+      );
+    }
+    if (
+      containsTokenCaseInsensitive(
+        message,
+        EXTENSION_STATUS_ERROR_MARKER.NATIVE_MESSAGING_HOST,
+      )
+    ) {
+      actions.push(
+        "Reinstall the native messaging host manifest and confirm it allows this extension ID.",
+      );
+    }
+    if (
+      containsTokenCaseInsensitive(
+        message,
+        EXTENSION_STATUS_ERROR_MARKER.HTTP_401,
+      )
+    ) {
+      actions.push(
+        "Re-pair the extension so it refreshes its local relay credential.",
+      );
+    }
+  }
+
+  if (mode === BROWSER_STATUS_MODE.CDP_INSPECT) {
+    actions.push(...cdpInspectSetupActions());
+    if (discoveryCodes.includes(CDP_INSPECT_STATUS_DISCOVERY_CODE.NO_TARGETS)) {
+      actions.push("Open at least one normal web page tab and retry.");
+    }
+    if (
+      discoveryCodes.includes(
+        CDP_INSPECT_STATUS_DISCOVERY_CODE.INVALID_RESPONSE,
+      ) ||
+      discoveryCodes.includes(
+        CDP_INSPECT_STATUS_DISCOVERY_CODE.WS_FALLBACK_FAILED,
+      )
+    ) {
+      actions.push(
+        "Verify nothing else is bound to the configured CDP port and exposing non-DevTools responses.",
+      );
+    }
+  }
+
+  if (mode === BROWSER_STATUS_MODE.LOCAL) {
+    actions.push(...localSetupActions());
+  }
+
+  return dedupeStrings(actions);
+}
+
+async function probePinnedBrowserMode(
+  mode: StatusCheckMode,
+  context: ToolContext,
+): Promise<
+  | {
+      ok: true;
+      backendKind: CdpClientKind;
+    }
+  | {
+      ok: false;
+      error: CdpError;
+      diagnostic: string;
+    }
+> {
+  let cdp: ReturnType<typeof getCdpClient> | null = null;
+  try {
+    cdp = getCdpClient(context, { mode });
+    await cdp.send(
+      "Runtime.evaluate",
+      {
+        expression: "document.readyState",
+        returnByValue: true,
+      },
+      context.signal,
+    );
+    return { ok: true, backendKind: cdp.kind };
+  } catch (err) {
+    if (err instanceof CdpError) {
+      return {
+        ok: false,
+        error: err,
+        diagnostic: formatModeSelectionFailure(mode, err),
+      };
+    }
+    const wrapped = new CdpError(
+      "transport_error",
+      err instanceof Error ? err.message : String(err),
+      { underlying: err },
+    );
+    return {
+      ok: false,
+      error: wrapped,
+      diagnostic: formatModeSelectionFailure(mode, wrapped),
+    };
+  } finally {
+    cdp?.dispose();
+  }
+}
+
+async function checkExtensionModeStatus(
+  context: ToolContext,
+  autoCandidate: boolean,
+): Promise<BrowserStatusModeResult> {
+  const proxyBound = Boolean(context.hostBrowserProxy);
+  const proxyConnected = context.hostBrowserProxy?.isAvailable() ?? false;
+
+  if (!proxyBound) {
+    return {
+      mode: BROWSER_STATUS_MODE.EXTENSION,
+      available: false,
+      verified: "preflight",
+      autoCandidate,
+      summary:
+        "Extension mode is unavailable: no host browser proxy is bound to this conversation.",
+      userActions: extensionSetupActions(),
+      tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
+      details: {
+        proxyBound,
+        proxyConnected,
+      },
+    };
+  }
+
+  if (!proxyConnected) {
+    return {
+      mode: BROWSER_STATUS_MODE.EXTENSION,
+      available: false,
+      verified: "preflight",
+      autoCandidate,
+      summary:
+        "Extension mode is unavailable: the extension transport is currently disconnected.",
+      userActions: extensionSetupActions(),
+      tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
+      details: {
+        proxyBound,
+        proxyConnected,
+      },
+    };
+  }
+
+  const probe = await probePinnedBrowserMode(
+    BROWSER_STATUS_MODE.EXTENSION,
+    context,
+  );
+  if (probe.ok) {
+    return {
+      mode: BROWSER_STATUS_MODE.EXTENSION,
+      available: true,
+      verified: "active_probe",
+      autoCandidate,
+      summary: "Extension mode is ready and responded to an active CDP probe.",
+      userActions: [],
+      tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
+      details: {
+        proxyBound,
+        proxyConnected,
+        backendKind: probe.backendKind,
+      },
+    };
+  }
+
+  if (isRestrictedChromePageProbeError(probe.error)) {
+    return {
+      mode: BROWSER_STATUS_MODE.EXTENSION,
+      available: true,
+      verified: "active_probe",
+      autoCandidate,
+      summary:
+        "Extension mode transport is connected, but the active Chrome tab is a restricted chrome:// page. Switch to a regular website tab if browser actions fail.",
+      userActions: [
+        "Switch Chrome to a regular http(s) tab (not chrome://...) and retry.",
+      ],
+      tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
+      details: {
+        proxyBound,
+        proxyConnected,
+        restrictedActiveTab: true,
+        errorCode: probe.error.code,
+        diagnostic: probe.diagnostic,
+        attemptDiagnostics: probe.error.attemptDiagnostics ?? [],
+      },
+    };
+  }
+
+  return {
+    mode: BROWSER_STATUS_MODE.EXTENSION,
+    available: false,
+    verified: "active_probe",
+    autoCandidate,
+    summary: `Extension mode probe failed: ${probe.error.message}`,
+    userActions: probeFailureActions(
+      BROWSER_STATUS_MODE.EXTENSION,
+      probe.error,
+    ),
+    tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
+    details: {
+      proxyBound,
+      proxyConnected,
+      errorCode: probe.error.code,
+      diagnostic: probe.diagnostic,
+      attemptDiagnostics: probe.error.attemptDiagnostics ?? [],
+    },
+  };
+}
+
+async function checkCdpInspectModeStatus(
+  context: ToolContext,
+  autoCandidate: boolean,
+): Promise<BrowserStatusModeResult> {
+  const cdpInspectConfig = getConfig().hostBrowser.cdpInspect;
+  const desktopAutoEnabled =
+    context.transportInterface === "macos" &&
+    cdpInspectConfig.desktopAuto.enabled;
+  const cooldownActive =
+    desktopAutoEnabled &&
+    isDesktopAutoCooldownActive(cdpInspectConfig.desktopAuto.cooldownMs);
+
+  const probe = await probePinnedBrowserMode(
+    BROWSER_STATUS_MODE.CDP_INSPECT,
+    context,
+  );
+  if (probe.ok) {
+    return {
+      mode: BROWSER_STATUS_MODE.CDP_INSPECT,
+      available: true,
+      verified: "active_probe",
+      autoCandidate,
+      summary:
+        "CDP inspect mode is ready and responded to an active CDP probe.",
+      userActions: [],
+      tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.CDP_INSPECT),
+      details: {
+        backendKind: probe.backendKind,
+        configEnabled: cdpInspectConfig.enabled,
+        configHost: cdpInspectConfig.host,
+        configPort: cdpInspectConfig.port,
+        desktopAutoEnabled,
+        desktopAutoCooldownActive: cooldownActive,
+      },
+    };
+  }
+
+  return {
+    mode: BROWSER_STATUS_MODE.CDP_INSPECT,
+    available: false,
+    verified: "active_probe",
+    autoCandidate,
+    summary: `CDP inspect probe failed: ${probe.error.message}`,
+    userActions: probeFailureActions(
+      BROWSER_STATUS_MODE.CDP_INSPECT,
+      probe.error,
+    ),
+    tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.CDP_INSPECT),
+    details: {
+      errorCode: probe.error.code,
+      discoveryCodes: extractDiscoveryCodes(probe.error),
+      diagnostic: probe.diagnostic,
+      attemptDiagnostics: probe.error.attemptDiagnostics ?? [],
+      configEnabled: cdpInspectConfig.enabled,
+      configHost: cdpInspectConfig.host,
+      configPort: cdpInspectConfig.port,
+      desktopAutoEnabled,
+      desktopAutoCooldownActive: cooldownActive,
+    },
+  };
+}
+
+async function checkLocalModeStatus(
+  context: ToolContext,
+  autoCandidate: boolean,
+  checkLocalLaunch: boolean,
+): Promise<BrowserStatusModeResult> {
+  const runtime = await checkBrowserRuntime();
+  if (!runtime.playwrightAvailable || !runtime.chromiumInstalled) {
+    return {
+      mode: BROWSER_STATUS_MODE.LOCAL,
+      available: false,
+      verified: "preflight",
+      autoCandidate,
+      summary:
+        runtime.error ??
+        "Local mode preflight failed: Playwright Chromium runtime is not ready.",
+      userActions: localSetupActions(),
+      tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.LOCAL),
+      details: {
+        runtime,
+        launchProbeRequested: checkLocalLaunch,
+      },
+    };
+  }
+
+  if (!checkLocalLaunch) {
+    return {
+      mode: BROWSER_STATUS_MODE.LOCAL,
+      available: true,
+      verified: "preflight",
+      autoCandidate,
+      summary:
+        "Local mode preflight passed (Playwright + Chromium are present). Launch probe was skipped.",
+      userActions: [],
+      tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.LOCAL),
+      details: {
+        runtime,
+        launchProbeRequested: checkLocalLaunch,
+      },
+    };
+  }
+
+  const probe = await probePinnedBrowserMode(
+    BROWSER_STATUS_MODE.LOCAL,
+    context,
+  );
+  if (probe.ok) {
+    return {
+      mode: BROWSER_STATUS_MODE.LOCAL,
+      available: true,
+      verified: "active_probe",
+      autoCandidate,
+      summary: "Local mode is ready and responded to an active CDP probe.",
+      userActions: [],
+      tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.LOCAL),
+      details: {
+        runtime,
+        launchProbeRequested: checkLocalLaunch,
+        backendKind: probe.backendKind,
+      },
+    };
+  }
+
+  return {
+    mode: BROWSER_STATUS_MODE.LOCAL,
+    available: false,
+    verified: "active_probe",
+    autoCandidate,
+    summary: `Local mode probe failed: ${probe.error.message}`,
+    userActions: probeFailureActions(BROWSER_STATUS_MODE.LOCAL, probe.error),
+    tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.LOCAL),
+    details: {
+      runtime,
+      launchProbeRequested: checkLocalLaunch,
+      errorCode: probe.error.code,
+      diagnostic: probe.diagnostic,
+      attemptDiagnostics: probe.error.attemptDiagnostics ?? [],
+    },
+  };
+}
+
+// ── browser_status ────────────────────────────────────────────────────
+
+export async function executeBrowserStatus(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const parsedMode = parseBrowserMode(input);
+  if (!parsedMode.ok) {
+    return { content: parsedMode.error, isError: true };
+  }
+
+  if (
+    input[BROWSER_STATUS_INPUT_FIELD.CHECK_LOCAL_LAUNCH] !== undefined &&
+    typeof input[BROWSER_STATUS_INPUT_FIELD.CHECK_LOCAL_LAUNCH] !== "boolean"
+  ) {
+    return {
+      content: `Error: ${BROWSER_STATUS_INPUT_FIELD.CHECK_LOCAL_LAUNCH} must be a boolean when provided.`,
+      isError: true,
+    };
+  }
+
+  const checkLocalLaunch =
+    input[BROWSER_STATUS_INPUT_FIELD.CHECK_LOCAL_LAUNCH] === true;
+  const requestedMode = parsedMode.mode;
+  const modesToCheck: readonly StatusCheckMode[] =
+    requestedMode === BROWSER_MODE.AUTO
+      ? BROWSER_STATUS_MODES
+      : [requestedMode];
+
+  const autoCandidateKinds = buildCandidateList(context).map((c) => c.kind);
+  const autoCandidateSet = new Set<CdpClientKind>(autoCandidateKinds);
+
+  try {
+    const modeResults: BrowserStatusModeResult[] = [];
+    for (const mode of modesToCheck) {
+      const autoCandidate = autoCandidateSet.has(mode);
+      if (mode === BROWSER_STATUS_MODE.EXTENSION) {
+        modeResults.push(
+          await checkExtensionModeStatus(context, autoCandidate),
+        );
+      } else if (mode === BROWSER_STATUS_MODE.CDP_INSPECT) {
+        modeResults.push(
+          await checkCdpInspectModeStatus(context, autoCandidate),
+        );
+      } else {
+        modeResults.push(
+          await checkLocalModeStatus(context, autoCandidate, checkLocalLaunch),
+        );
+      }
+    }
+
+    const stickyMode = browserManager.getPreferredBackendKind(
+      context.conversationId,
+    );
+    const availableModes = modeResults
+      .filter((r) => r.available)
+      .map((r) => r.mode);
+    const recommendedMode =
+      autoCandidateKinds.find((candidate) =>
+        modeResults.some(
+          (result) => result.mode === candidate && result.available,
+        ),
+      ) ??
+      availableModes[0] ??
+      null;
+
+    return {
+      content: JSON.stringify(
+        {
+          requestedMode,
+          checkedModes: modesToCheck,
+          autoCandidateOrder: autoCandidateKinds,
+          stickyConversationMode: stickyMode,
+          recommendedMode,
+          checkLocalLaunch,
+          modes: modeResults,
+        },
+        null,
+        2,
+      ),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      content: `Error: browser status check failed: ${msg}`,
+      isError: true,
+    };
+  }
+}