@vellumai/assistant 0.6.2 → 0.6.4

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

@@ -1,6 +1,8 @@
+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 {
   isPrivateOrLocalHost,
@@ -15,14 +17,58 @@ import {
   detectCaptchaChallenge,
   formatAuthChallenge,
 } from "./auth-detector.js";
-import type { PageResponse, RouteHandler } from "./browser-manager.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,
+} from "./cdp-client/accessibility-snapshot.js";
+import {
+  captureScreenshotJpeg,
+  dispatchClickAt,
+  dispatchHoverAt,
+  dispatchInsertText,
+  dispatchKeyPress,
+  dispatchWheelScroll,
+  evaluateExpression,
+  focusElement,
+  getCenterPoint,
+  getCurrentUrl,
+  getPageTitle,
+  navigateAndWait,
+  querySelectorBackendNodeId,
+  scrollIntoViewIfNeeded,
+  waitForSelector as cdpWaitForSelector,
+  waitForText as cdpWaitForText,
+} from "./cdp-client/cdp-dom-helpers.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");
 
@@ -32,43 +78,433 @@ export const NAVIGATE_TIMEOUT_MS = 15_000;
 
 export const ACTION_TIMEOUT_MS = 10_000;
 
-export const MAX_SNAPSHOT_ELEMENTS = 150;
-
-export const INTERACTIVE_SELECTOR = [
-  "a[href]",
-  "button",
-  "input",
-  "select",
-  "textarea",
-  '[role="button"]',
-  '[role="link"]',
-  '[role="checkbox"]',
-  '[role="radio"]',
-  '[role="tab"]',
-  '[role="menuitem"]',
-  '[role="option"]',
-  '[role="combobox"]',
-  '[role="listbox"]',
-  '[contenteditable="true"]',
-].join(", ");
-
-export type SnapshotElement = {
-  eid: string;
-  tag: string;
-  attrs: Record<string, string>;
-  text: string;
-};
-
 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]: [
+    "Controls the user's existing Chrome profile and tabs.",
+    "Requires the Vellum extension to be paired and actively connected.",
+    "Best when the user wants the assistant to operate in their real browser session.",
+  ],
+  [BROWSER_STATUS_MODE.CDP_INSPECT]: [
+    "Controls an existing Chrome instance launched with --remote-debugging-port.",
+    "Does not require the extension to be connected.",
+    "Requires remote debugging to stay enabled on localhost, which is more manual to maintain.",
+  ],
+  [BROWSER_STATUS_MODE.LOCAL]: [
+    "Runs a dedicated Playwright-managed Chromium profile.",
+    "Most isolated and reliable fallback when extension/CDP inspect are unavailable.",
+    "Does not use the user's existing browser profile, so sessions/cookies may differ.",
+  ],
+};
+
+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
+ * aren't exposed in the accessibility tree. Runs silently - if no
+ * matching modal is present the expression is a no-op.
+ */
+const DISMISS_MODALS_EXPRESSION = `(() => {
+  const dismissPatterns = /^(got it|accept|ok|dismiss|i understand|close)$/i;
+  const buttons = document.querySelectorAll('button, [role="button"], input[type="submit"]');
+  for (const btn of buttons) {
+    const text = (btn.textContent || '').trim();
+    if (dismissPatterns.test(text)) {
+      const modal = btn.closest('[role="dialog"], [class*="modal"], [class*="Modal"], [class*="overlay"], [class*="Overlay"]');
+      if (modal) {
+        btn.click();
+        break;
+      }
+    }
+  }
+})()`;
+
+/**
+ * IIFE evaluated by {@link executeBrowserExtract} when `include_links`
+ * is true. Walks `document.querySelectorAll('a[href]')`, caps at 200
+ * anchors, and shapes each entry as `{ text, href }`. Extracted to a
+ * module-level constant so the expression is shared between the
+ * runtime call site and any future refactors / tests that need to
+ * reason about the evaluated source.
+ */
+export const EXTRACT_LINKS_EXPRESSION = `
+(() => {
+  const anchors = Array.from(document.querySelectorAll('a[href]'));
+  return anchors.slice(0, 200).map(a => ({
+    text: (a.textContent || '').trim().slice(0, 80),
+    href: a.href,
+  }));
+})()
+`;
+
+// ── 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 Chrome/Chromium is running with --remote-debugging-port=9222.",
+    "Verify no firewall or antivirus is blocking localhost:9222.",
+    "Try: /Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=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;
+}
+
+/**
+ * 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 ────────────────────────────────────────
 
-export function resolveSelector(
+/**
+ * Discriminated union returned by {@link resolveElement}. The
+ * `"backend"` variant is produced when an `element_id` from the most
+ * recent AX-tree snapshot is resolved to a CDP `backendNodeId`; the
+ * `"selector"` variant is produced when the caller passed a raw CSS
+ * `selector` that should be resolved via `DOM.querySelector` at
+ * send-time by the individual tool.
+ *
+ * Consumed by CDP-native interaction tools (click, hover, type, …)
+ * that talk to CDP directly.
+ */
+export type ResolvedElement =
+  | { kind: "backend"; backendNodeId: number; eid: string }
+  | { kind: "selector"; selector: string };
+
+/**
+ * Resolve an element reference (either `element_id` from a prior
+ * snapshot or a raw `selector`) for CDP-native tools. Returns a
+ * {@link ResolvedElement} discriminated union so callers can branch
+ * on whether a backendNodeId was recovered from the snapshot map.
+ * Returns `{ resolved: null, error: "Error: …" }` on invalid input
+ * or when an `element_id` is provided but the snapshot map is
+ * empty/stale.
+ */
+export function resolveElement(
   conversationId: string,
   input: Record<string, unknown>,
-): { selector: string | null; error: string | null } {
+): { resolved: ResolvedElement | null; error: string | null } {
   const elementId =
     typeof input.element_id === "string" ? input.element_id : null;
   const rawSelector =
@@ -76,26 +512,32 @@ export function resolveSelector(
 
   if (!elementId && !rawSelector) {
     return {
-      selector: null,
+      resolved: null,
       error: "Error: Either element_id or selector is required.",
     };
   }
 
   if (elementId) {
-    const resolved = browserManager.resolveSnapshotSelector(
+    const backendNodeId = browserManager.resolveSnapshotBackendNodeId(
       conversationId,
       elementId,
     );
-    if (!resolved) {
+    if (backendNodeId !== null) {
       return {
-        selector: null,
-        error: `Error: element_id "${elementId}" not found. Run browser_snapshot first to get current element IDs.`,
+        resolved: { kind: "backend", backendNodeId, eid: elementId },
+        error: null,
       };
     }
-    return { selector: resolved, error: null };
+    return {
+      resolved: null,
+      error: `Error: element_id "${elementId}" not found. Run browser_snapshot first to get current element IDs.`,
+    };
   }
 
-  return { selector: rawSelector!, error: null };
+  return {
+    resolved: { kind: "selector", selector: rawSelector! },
+    error: null,
+  };
 }
 
 // ── browser_navigate ─────────────────────────────────────────────────
@@ -108,6 +550,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 {
@@ -122,7 +566,8 @@ export async function executeBrowserNavigate(
   const allowPrivateNetwork = input.allow_private_network === true;
   const safeRequestedUrl = sanitizeUrlForOutput(parsedUrl);
 
-  // Block private/local targets by default
+  // Block private/local targets by default. Runs before any CDP session
+  // is opened so we fail fast on obviously invalid URLs.
   if (!allowPrivateNetwork && isPrivateOrLocalHost(parsedUrl.hostname)) {
     return {
       content: `Error: Refusing to navigate to local/private network target (${parsedUrl.hostname}). Set allow_private_network=true if you explicitly need it.`,
@@ -130,7 +575,7 @@ export async function executeBrowserNavigate(
     };
   }
 
-  // DNS resolution check for non-literal hostnames
+  // DNS resolution check for non-literal hostnames.
   if (!allowPrivateNetwork) {
     const resolution = await resolveRequestAddress(
       parsedUrl.hostname,
@@ -145,29 +590,40 @@ export async function executeBrowserNavigate(
     }
   }
 
-  let routeHandler: RouteHandler | null = null;
-  let blockedUrl: string | null = null;
-
-  // Start screencast if a sender is registered for this conversation
-  const sender = getSender(context.conversationId);
-  if (sender) {
+  // 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
+  // user already has their own Chrome window, so both are no-ops.
+  const sender =
+    cdp.kind === "local" ? getSender(context.conversationId) : null;
+  if (cdp.kind === "local" && sender) {
     await ensureScreencast(context.conversationId);
   }
 
+  // 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;
+
   try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
-    );
     log.debug(
       { url: safeRequestedUrl, conversationId: context.conversationId },
       "Navigating",
     );
 
-    // Install request interception to block redirects/sub-requests to private networks.
-    // This prevents SSRF bypass via server-side redirects and DNS rebinding attacks,
-    // since Playwright follows redirects internally and performs its own DNS resolution.
-    // Only skip for connectOverCDP browsers where page.route() is unreliable.
-    if (!allowPrivateNetwork && browserManager.supportsRouteInterception) {
+    if (
+      cdp.kind === "local" &&
+      !allowPrivateNetwork &&
+      browserManager.supportsRouteInterception
+    ) {
       // Cache DNS results per-hostname to avoid redundant lookups on subrequests
       // (heavy sites like DoorDash fire hundreds of requests to the same CDN hostnames).
       // Use a short TTL to mitigate DNS rebinding attacks where a hostname first
@@ -242,47 +698,107 @@ export async function executeBrowserNavigate(
           );
         }
       };
+      // Bridge through browserManager to reach the Playwright Page for
+      // route installation. The route handler intercepts redirect-time
+      // requests before Page.navigate's network fetches can hit them.
+      const page = await browserManager.getOrCreateSessionPage(
+        context.conversationId,
+      );
       await page.route("**/*", routeHandler);
     }
 
-    // Use domcontentloaded but with a shorter timeout - if it times out,
-    // the page is likely still usable (heavy SPAs like DoorDash keep loading
-    // scripts after DOMContentLoaded). Fall back gracefully instead of failing.
-    let response: PageResponse | null = null;
-    let navigationTimedOut = false;
-    const urlBeforeNav = page.url();
-    try {
-      response = await page.goto(parsedUrl.href, {
-        waitUntil: "domcontentloaded",
-        timeout: NAVIGATE_TIMEOUT_MS,
-      });
-    } catch (navErr) {
-      const navMsg = navErr instanceof Error ? navErr.message : String(navErr);
-      if (navMsg.includes("Timeout") || navMsg.includes("timeout")) {
-        // If the page URL never changed from before navigation, the page
-        // never actually loaded - re-throw instead of reporting success.
-        if (page.url() === urlBeforeNav && urlBeforeNav !== parsedUrl.href) {
-          throw navErr;
+    // Read the current URL BEFORE calling navigateAndWait so we can
+    // detect the "page never moved" case on timeout.
+    const urlBeforeNav = await getCurrentUrl(cdp, context.signal);
+
+    // Navigate via CDP Page.navigate + document.readyState polling.
+    // navigateAndWait returns { finalUrl, timedOut }; HTTP status is
+    // not available on the CDP path because Page.navigate does not
+    // surface the response status.
+    const { finalUrl, timedOut: navigationTimedOut } = await navigateAndWait(
+      cdp,
+      parsedUrl.href,
+      { 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 tool calls (e.g. browser_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.
         }
-        navigationTimedOut = true;
-        log.info(
-          { url: safeRequestedUrl },
-          "Navigation timed out waiting for domcontentloaded, continuing with partial load",
+        // 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.
+      if (finalUrl === urlBeforeNav && urlBeforeNav !== parsedUrl.href) {
+        throw new Error(
+          `Navigation to ${parsedUrl.href} timed out after ${NAVIGATE_TIMEOUT_MS}ms`,
         );
-      } else {
-        throw navErr;
       }
+      log.info(
+        { url: safeRequestedUrl },
+        "Navigation timed out waiting for document.readyState, continuing with partial load",
+      );
     }
 
-    // Remove the route handler now that navigation is complete
+    // Remove the Playwright route handler now that navigation is
+    // complete (local path only — route interception is gated above).
     if (routeHandler) {
+      const page = await browserManager.getOrCreateSessionPage(
+        context.conversationId,
+      );
       await page.unroute("**/*", routeHandler);
       routeHandler = null;
     }
 
-    // Reposition the browser window after navigation so the user can watch.
-    // positionWindowSidebar() is a no-op when browserCdpSession is unavailable.
-    if (!browserManager.isInteractive(context.conversationId)) {
+    // Window positioning is a Playwright-internal affordance - on the
+    // extension path the user owns their Chrome window, so positioning
+    // is a no-op.
+    if (
+      cdp.kind === "local" &&
+      !browserManager.isInteractive(context.conversationId)
+    ) {
       await browserManager.positionWindowSidebar();
     }
 
@@ -293,38 +809,34 @@ export async function executeBrowserNavigate(
       };
     }
 
-    // Navigation changed the page content, so clear stale snapshot mappings.
-    // Without this, element IDs from a previous page could resolve and cause
-    // confusing Playwright timeout errors instead of the actionable
-    // "run browser_snapshot first" message.
-    browserManager.clearSnapshotMap(context.conversationId);
+    // Navigation changed the page content, so clear stale snapshot
+    // mappings regardless of backend. The backendNodeId map is shared
+    // per-conversation state that needs to be invalidated on any nav.
+    browserManager.clearSnapshotBackendNodeMap(context.conversationId);
 
-    // Auto-dismiss common blocker modals (regulatory notices, cookie banners)
-    // that aren't exposed in the accessibility tree. Runs silently - if no
-    // modal is present the evaluate is a no-op.
+    // Auto-dismiss common blocker modals (regulatory notices, cookie
+    // banners) that aren't exposed in the accessibility tree. Runs
+    // silently - if no modal is present the evaluate is a no-op.
     try {
-      await page.evaluate(`(() => {
-        const dismissPatterns = /^(got it|accept|ok|dismiss|i understand|close)$/i;
-        const buttons = document.querySelectorAll('button, [role="button"], input[type="submit"]');
-        for (const btn of buttons) {
-          const text = (btn.textContent || '').trim();
-          if (dismissPatterns.test(text)) {
-            const modal = btn.closest('[role="dialog"], [class*="modal"], [class*="Modal"], [class*="overlay"], [class*="Overlay"]');
-            if (modal) {
-              btn.click();
-              break;
-            }
-          }
-        }
-      })()`);
+      await evaluateExpression(
+        cdp,
+        DISMISS_MODALS_EXPRESSION,
+        {},
+        context.signal,
+      );
     } catch {
       // Page may have navigated during evaluate - safe to ignore
     }
 
-    const finalUrl = page.url();
     const safeFinalUrl = sanitizeUrlForOutput(new URL(finalUrl));
-    const title = await page.title();
-    const status = response?.status() ?? null;
+    const title = await getPageTitle(cdp, context.signal);
+    // HTTP status is not available on the CDP path: `Page.navigate`
+    // resolves the frame id and (on failure) an error text, but does
+    // not carry the response status code. Both the local and extension
+    // paths therefore print "unknown" here. A future phase may subscribe
+    // to `Network.responseReceived` events during the navigation window
+    // if the status is needed again.
+    const status: number | null = null;
 
     const lines: string[] = [
       `Requested URL: ${safeRequestedUrl}`,
@@ -335,7 +847,7 @@ export async function executeBrowserNavigate(
 
     if (navigationTimedOut) {
       lines.push(
-        `Note: Page is still loading (domcontentloaded 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 - use browser_snapshot to check.`,
       );
     }
 
@@ -343,10 +855,14 @@ export async function executeBrowserNavigate(
       lines.push(`Note: Page redirected from the requested URL.`);
     }
 
-    // Detect auth challenges (login pages, 2FA, OAuth consent) and CAPTCHA challenges
+    // Detect auth challenges (login pages, 2FA, OAuth consent) and CAPTCHA
+    // challenges via the CDP-migrated auth-detector helpers.
     try {
-      const authChallenge = await detectAuthChallenge(page);
-      const captchaChallenge = await detectCaptchaChallenge(page);
+      const authChallenge = await detectAuthChallenge(cdp, context.signal);
+      const captchaChallenge = await detectCaptchaChallenge(
+        cdp,
+        context.signal,
+      );
       // CAPTCHA takes priority - it blocks all interaction including login
       let challenge = captchaChallenge ?? authChallenge;
 
@@ -359,12 +875,12 @@ export async function executeBrowserNavigate(
             return { content: "Navigation cancelled.", isError: true };
           }
           await new Promise((r) => setTimeout(r, 1000));
-          const still = await detectCaptchaChallenge(page);
+          const still = await detectCaptchaChallenge(cdp, context.signal);
           if (!still) {
             log.info("CAPTCHA auto-resolved");
             // Re-check for auth challenge now that CAPTCHA is gone -
             // the page may have loaded a login form behind it.
-            challenge = await detectAuthChallenge(page);
+            challenge = await detectAuthChallenge(cdp, context.signal);
             break;
           }
         }
@@ -373,7 +889,11 @@ export async function executeBrowserNavigate(
       if (challenge) {
         if (challenge.type === "captcha") {
           // CAPTCHA persisted after auto-resolve wait - hand off to user
-          if (sender) {
+          // only when we have a local Playwright-managed Chrome window
+          // AND a sender is registered. The extension path falls back
+          // to the text-only "solve manually" branch because the user
+          // already owns their Chrome window.
+          if (cdp.kind === "local" && sender) {
             const { startHandoff } = await import("./browser-handoff.js");
             await startHandoff(context.conversationId, {
               reason: "captcha",
@@ -381,15 +901,18 @@ export async function executeBrowserNavigate(
                 "Cloudflare verification detected. Please solve the CAPTCHA in the Chrome window. The browser will automatically detect when you're done and resume.",
               bringToFront: true,
             });
-            const newUrl = page.url();
-            const newTitle = await page.title();
+            const newUrl = await getCurrentUrl(cdp, context.signal);
+            const newTitle = await getPageTitle(cdp, context.signal);
             lines.push("");
             lines.push(
               `CAPTCHA solved by user. Current page: ${newTitle} (${newUrl})`,
             );
 
             // Re-check for auth challenges - the page behind the CAPTCHA may have a login form
-            const postCaptchaAuth = await detectAuthChallenge(page);
+            const postCaptchaAuth = await detectAuthChallenge(
+              cdp,
+              context.signal,
+            );
             if (postCaptchaAuth) {
               lines.push("");
               lines.push(formatAuthChallenge(postCaptchaAuth));
@@ -448,7 +971,7 @@ export async function executeBrowserNavigate(
 
     return { content: lines.join("\n"), isError: false };
   } catch (err) {
-    // Best-effort cleanup of route handler on error
+    // Best-effort cleanup of route handler on error (local path only)
     if (routeHandler) {
       try {
         const page = await browserManager.getOrCreateSessionPage(
@@ -461,8 +984,8 @@ export async function executeBrowserNavigate(
     }
 
     // If the route handler blocked a redirect to a private network address,
-    // page.goto() throws. Return the clear security message instead of the
-    // raw Playwright error (which could leak credentials from the URL).
+    // Page.navigate throws. Return the clear security message instead of
+    // the raw underlying error (which could leak credentials from the URL).
     if (blockedUrl) {
       return {
         content: `Error: Navigation blocked. A request targeted a local/private network address (${blockedUrl}). Set allow_private_network=true if you explicitly need it.`,
@@ -470,9 +993,16 @@ 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 };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -482,79 +1012,49 @@ export async function executeBrowserSnapshot(
   _input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  const acquired = acquireCdpClientWithMode(_input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const { cdp, browserMode } = acquired;
+
   try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
+    const currentUrl = await getCurrentUrl(cdp, context.signal);
+    const title = await getPageTitle(cdp, context.signal);
+
+    // Pull the full accessibility tree via CDP and fold it into typed
+    // interactive elements + an `eid → backendNodeId` map. Interaction
+    // tools (click, hover, type, …) resolve element_id against this map
+    // and jump straight to CDP DOM commands without another round-trip
+    // through any selector engine.
+    await cdp.send("Accessibility.enable", {}, context.signal);
+    const rawTree = await cdp.send(
+      "Accessibility.getFullAXTree",
+      {},
+      context.signal,
     );
-    const currentUrl = page.url();
-    const title = await page.title();
-
-    const elements = (await page.evaluate(`
-      (() => {
-        const SELECTOR = ${JSON.stringify(INTERACTIVE_SELECTOR)};
-        const MAX = ${MAX_SNAPSHOT_ELEMENTS};
-        // Clear stale eid attributes from previous snapshots
-        document.querySelectorAll('[data-vellum-eid]').forEach(el => el.removeAttribute('data-vellum-eid'));
-        const els = Array.from(document.querySelectorAll(SELECTOR));
-        const visible = els.filter(el => {
-          const rect = el.getBoundingClientRect();
-          return rect.width > 0 && rect.height > 0;
-        });
-        return visible.slice(0, MAX).map((el, i) => {
-          const eid = 'e' + (i + 1);
-          el.setAttribute('data-vellum-eid', eid);
-          const tag = el.tagName.toLowerCase();
-          const attrs = {};
-          for (const attr of ['type', 'name', 'placeholder', 'href', 'value', 'role', 'aria-label', 'id']) {
-            if (el.hasAttribute(attr)) attrs[attr] = el.getAttribute(attr);
-          }
-          const text = (el.textContent || '').trim().slice(0, 80);
-          return { eid, tag, attrs, text };
-        });
-      })()
-    `)) as SnapshotElement[];
-
-    // Build and store selector map
-    const selectorMap = new Map<string, string>();
-    for (const el of elements) {
-      selectorMap.set(el.eid, `[data-vellum-eid="${el.eid}"]`);
-    }
-    browserManager.storeSnapshotMap(context.conversationId, selectorMap);
-
-    // Format output
-    const lines: string[] = [
-      `URL: ${currentUrl}`,
-      `Title: ${title || "(none)"}`,
-      "",
-    ];
+    const { elements, selectorMap: backendNodeMap } = transformAxTree(rawTree);
 
-    if (elements.length === 0) {
-      lines.push("(no interactive elements found)");
-    } else {
-      for (const el of elements) {
-        let desc = `<${el.tag}`;
-        for (const [key, val] of Object.entries(el.attrs)) {
-          desc += ` ${key}="${val}"`;
-        }
-        desc += ">";
-        if (el.text) {
-          desc += ` ${el.text}`;
-        }
-        lines.push(`[${el.eid}] ${desc}`);
-      }
-      lines.push("");
-      lines.push(
-        `${elements.length} interactive element${
-          elements.length === 1 ? "" : "s"
-        } found.`,
-      );
-    }
+    browserManager.storeSnapshotBackendNodeMap(
+      context.conversationId,
+      backendNodeMap,
+    );
 
-    return { content: lines.join("\n"), isError: false };
+    return {
+      content: formatAxSnapshot(
+        { elements, selectorMap: backendNodeMap },
+        { url: currentUrl, title },
+      ),
+      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 };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -564,17 +1064,17 @@ 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;
 
   try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
+    const buffer = await captureScreenshotJpeg(
+      cdp,
+      { quality: 80, fullPage },
+      context.signal,
     );
-    const buffer = await page.screenshot({
-      type: "jpeg",
-      quality: 80,
-      fullPage,
-    });
     const base64Data = buffer.toString("base64");
 
     const imageBlock: ImageContent = {
@@ -594,9 +1094,118 @@ 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 };
+  } finally {
+    cdp.dispose();
+  }
+}
+
+// ── 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();
   }
 }
 
@@ -606,29 +1215,62 @@ export async function executeBrowserClose(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
-    const sender = getSender(context.conversationId);
-    if (sender) {
-      await stopBrowserScreencast(context.conversationId);
-    }
+    if (cdp.kind === "local") {
+      // Local/sacrificial-profile path: tear down the Playwright page,
+      // screencast, and associated CDP state for this conversation.
+      const sender = getSender(context.conversationId);
+      if (sender) {
+        await stopBrowserScreencast(context.conversationId);
+      }
 
-    if (input.close_all_pages === true) {
-      await stopAllScreencasts();
-      await browserManager.closeAllPages();
+      if (input.close_all_pages === true) {
+        await stopAllScreencasts();
+        await browserManager.closeAllPages();
+        return {
+          content: "All browser pages and context closed.",
+          isError: false,
+        };
+      }
+      await browserManager.closeSessionPage(context.conversationId);
       return {
-        content: "All browser pages and context closed.",
+        content: "Browser page closed for this conversation.",
         isError: false,
       };
     }
-    await browserManager.closeSessionPage(context.conversationId);
+
+    // Extension path: the user owns their Chrome tab — we must not
+    // 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 page closed for this conversation.",
+      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 };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -638,32 +1280,115 @@ export async function executeBrowserClick(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const { selector, error } = resolveSelector(context.conversationId, input);
+  const { resolved, error } = resolveElement(context.conversationId, input);
   if (error) return { content: error, isError: true };
 
-  const timeout =
-    typeof input.timeout === "number" ? input.timeout : ACTION_TIMEOUT_MS;
-
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
-    );
-    await page.click(selector!, { timeout });
-    return { content: `Clicked element: ${selector}`, isError: false };
+    let backendNodeId: number;
+    if (resolved!.kind === "backend") {
+      backendNodeId = resolved!.backendNodeId;
+    } else {
+      // Wait until the selector matches a visible element. Mirrors
+      // Playwright's `page.click(selector, { timeout })` semantics
+      // and lets click work on async-hydrated pages where the
+      // target may not yet exist when the tool is invoked.
+      // cdpWaitForSelector returns the backendNodeId so we don't
+      // need a separate querySelectorBackendNodeId round-trip.
+      backendNodeId = await cdpWaitForSelector(
+        cdp,
+        resolved!.selector,
+        ACTION_TIMEOUT_MS,
+        context.signal,
+      );
+    }
+    await scrollIntoViewIfNeeded(cdp, backendNodeId, context.signal);
+    const point = await getCenterPoint(cdp, backendNodeId, context.signal);
+    await dispatchClickAt(cdp, point, context.signal);
+    const desc =
+      resolved!.kind === "backend"
+        ? `eid=${resolved!.eid}`
+        : 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, selector }, "Click failed");
+    log.error({ err }, "Click failed");
     return { content: `Error: Click failed: ${msg}`, isError: true };
+  } finally {
+    cdp.dispose();
   }
 }
 
+// ── Shared input helpers ─────────────────────────────────────────────
+
+/**
+ * Focus an element, clear its existing value (handling both
+ * `<input>`/`<textarea>` and `contentEditable` targets), re-focus
+ * (sites sometimes blur on a programmatic value reset), and insert
+ * the requested text via `Input.insertText`.
+ *
+ * Used by both `executeBrowserType` and `executeBrowserFillCredential`
+ * so credential fills cannot append to autofilled / pre-populated
+ * fields — appending would leak the existing value into the broker
+ * payload and corrupt the resulting password.
+ */
+async function clearAndInsertText(
+  cdp: CdpClient,
+  backendNodeId: number,
+  value: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  await focusElement(cdp, backendNodeId, signal);
+
+  // Resolve the node to a Runtime.RemoteObject so we can invoke a
+  // function on the element itself via Runtime.callFunctionOn. This
+  // is more reliable than a keyboard select-all + delete sequence
+  // across input, textarea, and contenteditable targets.
+  const { object } = await cdp.send<{ object: { objectId: string } }>(
+    "DOM.resolveNode",
+    { backendNodeId },
+    signal,
+  );
+  await cdp.send(
+    "Runtime.callFunctionOn",
+    {
+      objectId: object.objectId,
+      functionDeclaration: `function() {
+        if (typeof this.value === "string") {
+          this.value = "";
+        } else if (this.isContentEditable) {
+          this.textContent = "";
+        }
+        this.dispatchEvent(new Event("input", { bubbles: true }));
+      }`,
+      arguments: [],
+    },
+    signal,
+  );
+
+  // Re-focus after clearing — some sites move focus when the value
+  // property is reassigned programmatically.
+  await focusElement(cdp, backendNodeId, signal);
+
+  await dispatchInsertText(cdp, value, signal);
+}
+
 // ── browser_type ─────────────────────────────────────────────────────
 
 export async function executeBrowserType(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const { selector, error } = resolveSelector(context.conversationId, input);
+  const { resolved, error } = resolveElement(context.conversationId, input);
   if (error) return { content: error, isError: true };
 
   const text = typeof input.text === "string" ? input.text : "";
@@ -674,40 +1399,54 @@ export async function executeBrowserType(
   const clearFirst = input.clear_first !== false; // default true
   const pressEnter = input.press_enter === true;
 
-  try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
-    );
+  const targetDescription =
+    resolved!.kind === "backend"
+      ? `element_id "${resolved!.eid}"`
+      : resolved!.selector;
 
-    const fillTimeout =
-      typeof input.timeout === "number" ? input.timeout : ACTION_TIMEOUT_MS;
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
+  try {
+    let backendNodeId: number;
+    if (resolved!.kind === "backend") {
+      backendNodeId = resolved!.backendNodeId;
+    } else {
+      backendNodeId = await querySelectorBackendNodeId(
+        cdp,
+        resolved!.selector,
+        context.signal,
+      );
+    }
 
     if (clearFirst) {
-      await page.fill(selector!, text, { timeout: fillTimeout });
+      await clearAndInsertText(cdp, backendNodeId, text, context.signal);
     } else {
-      // Read existing content before appending. Use .value for form inputs,
-      // with fallback to .innerText for contenteditable elements (preserves
-      // visual line breaks from <br> and block elements, unlike textContent).
-      const currentValue = (await page.evaluate(
-        `(() => { const el = document.querySelector(${JSON.stringify(
-          selector!,
-        )}); if (!el) return ''; if (typeof el.value === 'string') return el.value; return el.innerText ?? ''; })()`,
-      )) as string;
-      await page.fill(selector!, currentValue + text, { timeout: fillTimeout });
+      await focusElement(cdp, backendNodeId, context.signal);
+      await dispatchInsertText(cdp, text, context.signal);
     }
 
     if (pressEnter) {
-      await page.press(selector!, "Enter");
+      await dispatchKeyPress(cdp, "Enter", context.signal);
     }
 
-    const lines = [`Typed into element: ${selector}`];
+    const lines = [`Typed into element: ${targetDescription}`];
     if (clearFirst) lines.push("(cleared existing content first)");
     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, selector }, "Type failed");
+    log.error({ err, target: targetDescription }, "Type failed");
     return { content: `Error: Type failed: ${msg}`, isError: true };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -722,39 +1461,65 @@ export async function executeBrowserPressKey(
     return { content: "Error: key is required.", isError: true };
   }
 
-  try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
-    );
-
-    // If element_id or selector is provided, press key on that element
-    const elementId =
-      typeof input.element_id === "string" ? input.element_id : null;
-    const rawSelector =
-      typeof input.selector === "string" ? input.selector : null;
+  const elementId =
+    typeof input.element_id === "string" ? input.element_id : null;
+  const rawSelector =
+    typeof input.selector === "string" ? input.selector : null;
+  const hasTarget = elementId !== null || rawSelector !== null;
+
+  let targetDescription: string | null = null;
+  let resolved: ResolvedElement | null = null;
+  if (hasTarget) {
+    const res = resolveElement(context.conversationId, input);
+    if (res.error) {
+      return { content: res.error, isError: true };
+    }
+    resolved = res.resolved;
+    targetDescription =
+      resolved!.kind === "backend"
+        ? `element_id "${resolved!.eid}"`
+        : resolved!.selector;
+  }
 
-    if (elementId || rawSelector) {
-      const { selector, error } = resolveSelector(
-        context.conversationId,
-        input,
-      );
-      if (error) {
-        return { content: error, isError: true };
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
+  try {
+    if (resolved) {
+      let backendNodeId: number;
+      if (resolved.kind === "backend") {
+        backendNodeId = resolved.backendNodeId;
+      } else {
+        backendNodeId = await querySelectorBackendNodeId(
+          cdp,
+          resolved.selector,
+          context.signal,
+        );
       }
-      await page.press(selector!, key);
+      await focusElement(cdp, backendNodeId, context.signal);
+      await dispatchKeyPress(cdp, key, context.signal);
       return {
-        content: `Pressed "${key}" on element: ${selector}`,
+        content: `Pressed "${key}" on element: ${targetDescription}`,
         isError: false,
       };
     }
 
-    // No target -> press key on the page (focused element)
-    await page.keyboard.press(key);
+    // No target -> press key on the currently focused element
+    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 };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -776,35 +1541,58 @@ export async function executeBrowserScroll(
   const amount =
     typeof input.amount === "number" ? Math.abs(input.amount) : 500;
 
+  let deltaX = 0;
+  let deltaY = 0;
+  switch (direction) {
+    case "up":
+      deltaY = -amount;
+      break;
+    case "down":
+      deltaY = amount;
+      break;
+    case "left":
+      deltaX = -amount;
+      break;
+    case "right":
+      deltaX = amount;
+      break;
+  }
+
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
+    // Fetch viewport dimensions so we can dispatch the wheel event at
+    // the viewport center — scrolling from (0, 0) misses sticky
+    // headers and overflow containers on many sites.
+    const { w, h } = await evaluateExpression<{ w: number; h: number }>(
+      cdp,
+      "({ w: window.innerWidth, h: window.innerHeight })",
+      {},
+      context.signal,
     );
 
-    let deltaX = 0;
-    let deltaY = 0;
-    switch (direction) {
-      case "up":
-        deltaY = -amount;
-        break;
-      case "down":
-        deltaY = amount;
-        break;
-      case "left":
-        deltaX = -amount;
-        break;
-      case "right":
-        deltaX = amount;
-        break;
-    }
-
-    await page.mouse.wheel(deltaX, deltaY);
+    await dispatchWheelScroll(
+      cdp,
+      { x: w / 2, y: h / 2 },
+      { deltaX, deltaY },
+      context.signal,
+    );
 
     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 };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -814,7 +1602,7 @@ export async function executeBrowserSelectOption(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const { selector, error } = resolveSelector(context.conversationId, input);
+  const { resolved, error } = resolveElement(context.conversationId, input);
   if (error) return { content: error, isError: true };
 
   const value = typeof input.value === "string" ? input.value : undefined;
@@ -828,32 +1616,115 @@ export async function executeBrowserSelectOption(
     };
   }
 
-  try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
-    );
+  const targetDescription =
+    resolved!.kind === "backend"
+      ? `element_id "${resolved!.eid}"`
+      : resolved!.selector;
 
-    const option: Record<string, string | number> = {};
-    if (value !== undefined) option.value = value;
-    else if (label !== undefined) option.label = label;
-    else if (index !== undefined) option.index = index;
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
+  try {
+    let backendNodeId: number;
+    if (resolved!.kind === "backend") {
+      backendNodeId = resolved!.backendNodeId;
+    } else {
+      backendNodeId = await querySelectorBackendNodeId(
+        cdp,
+        resolved!.selector,
+        context.signal,
+      );
+    }
 
-    await page.selectOption(selector!, option);
+    // CDP does not expose a native "set select value" command, so we
+    // resolve the node to a Runtime.RemoteObject and invoke a function
+    // on it that applies value/label/index and dispatches `input`
+    // followed by `change` (HTML spec order — Angular's
+    // DefaultValueAccessor listens for `input`, so missing it breaks
+    // form bindings on Angular sites).
+    const { object } = await cdp.send<{ object: { objectId: string } }>(
+      "DOM.resolveNode",
+      { backendNodeId },
+      context.signal,
+    );
+    const callResult = await cdp.send<{
+      result?: { value?: boolean };
+    }>(
+      "Runtime.callFunctionOn",
+      {
+        objectId: object.objectId,
+        functionDeclaration: `function(value, label, index) {
+          let matched = false;
+          if (value !== null && value !== undefined) {
+            for (const opt of this.options) {
+              if (opt.value === value) {
+                this.value = value;
+                matched = true;
+                break;
+              }
+            }
+          } else if (label !== null && label !== undefined) {
+            for (const opt of this.options) {
+              if (opt.label === label) {
+                this.value = opt.value;
+                matched = true;
+                break;
+              }
+            }
+          } else if (index !== null && index !== undefined) {
+            if (index >= 0 && index < this.options.length) {
+              this.selectedIndex = index;
+              matched = true;
+            }
+          }
+          if (matched) {
+            this.dispatchEvent(new Event("input", { bubbles: true }));
+            this.dispatchEvent(new Event("change", { bubbles: true }));
+          }
+          return matched;
+        }`,
+        arguments: [
+          { value: value ?? null },
+          { value: label ?? null },
+          { value: index ?? null },
+        ],
+        returnByValue: true,
+      },
+      context.signal,
+    );
 
+    const matched = callResult?.result?.value === true;
     const desc =
       value !== undefined
         ? `value="${value}"`
         : label !== undefined
           ? `label="${label}"`
           : `index=${index}`;
+
+    if (!matched) {
+      return {
+        content: `Error: Select option failed: no option matched ${desc} on ${targetDescription}.`,
+        isError: true,
+      };
+    }
+
     return {
-      content: `Selected option (${desc}) on element: ${selector}`,
+      content: `Selected option (${desc}) on element: ${targetDescription}`,
       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, selector }, "Select option failed");
+    log.error({ err, target: targetDescription }, "Select option failed");
     return { content: `Error: Select option failed: ${msg}`, isError: true };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -863,20 +1734,48 @@ export async function executeBrowserHover(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const { selector, error } = resolveSelector(context.conversationId, input);
+  const { resolved, error } = resolveElement(context.conversationId, input);
   if (error) return { content: error, isError: true };
 
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
-    );
-    await page.hover(selector!, { timeout: ACTION_TIMEOUT_MS });
-
-    return { content: `Hovered element: ${selector}`, isError: false };
+    let backendNodeId: number;
+    if (resolved!.kind === "backend") {
+      backendNodeId = resolved!.backendNodeId;
+    } else {
+      // Wait until the selector matches a visible element. See the
+      // matching note in executeBrowserClick — async-hydrated pages
+      // need this to behave like Playwright's hover-with-timeout.
+      backendNodeId = await cdpWaitForSelector(
+        cdp,
+        resolved!.selector,
+        ACTION_TIMEOUT_MS,
+        context.signal,
+      );
+    }
+    await scrollIntoViewIfNeeded(cdp, backendNodeId, context.signal);
+    const point = await getCenterPoint(cdp, backendNodeId, context.signal);
+    await dispatchHoverAt(cdp, point, context.signal);
+    const desc =
+      resolved!.kind === "backend"
+        ? `eid=${resolved!.eid}`
+        : 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, selector }, "Hover failed");
+    log.error({ err }, "Hover failed");
     return { content: `Error: Hover failed: ${msg}`, isError: true };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -917,39 +1816,59 @@ export async function executeBrowserWaitFor(
       ? Math.min(input.timeout, MAX_WAIT_MS)
       : MAX_WAIT_MS;
 
-  try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
-    );
+  // 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) {
+    const waitMs = Math.min(duration, MAX_WAIT_MS);
+    await new Promise((r) => setTimeout(r, waitMs));
+    return { content: `Waited ${waitMs}ms.`, isError: false };
+  }
 
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
+  try {
     if (selector) {
-      await page.waitForSelector(selector, { timeout });
+      // browser_wait_for selector mode is "did this node appear at
+      // all" — preserve the existing semantics by polling for DOM
+      // attachment, not full visibility. Tools that need
+      // visible-state polling (click/hover) get it via the default
+      // state in cdpWaitForSelector.
+      await cdpWaitForSelector(cdp, selector, timeout, context.signal, {
+        state: "attached",
+      });
       return {
         content: `Element matching "${selector}" appeared.`,
         isError: false,
       };
     }
 
-    if (text) {
-      const escaped = JSON.stringify(text);
-      await page.waitForFunction(
-        `document.body?.innerText?.includes(${escaped})`,
-        { timeout },
-      );
-      return {
-        content: `Text "${truncate(text, 80)}" appeared on page.`,
-        isError: false,
-      };
-    }
-
-    // duration mode (milliseconds)
-    const waitMs = Math.min(duration!, MAX_WAIT_MS);
-    await new Promise((r) => setTimeout(r, waitMs));
-    return { content: `Waited ${waitMs}ms.`, isError: false };
+    // text mode (validated above — modeCount === 1 means text is set)
+    await cdpWaitForText(cdp, text!, timeout, context.signal);
+    return {
+      content: `Text "${truncate(text!, 80)}" appeared on page.`,
+      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 };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -961,20 +1880,24 @@ export async function executeBrowserExtract(
 ): Promise<ToolExecutionResult> {
   const includeLinks = input.include_links === true;
 
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
+    const currentUrl = await getCurrentUrl(cdp, context.signal);
+    const title = await getPageTitle(cdp, context.signal);
+
+    let textContent = await evaluateExpression<string>(
+      cdp,
+      "document.body?.innerText ?? ''",
+      {},
+      context.signal,
     );
-    const currentUrl = page.url();
-    const title = await page.title();
-
-    let textContent = (await page.evaluate(
-      `document.body?.innerText ?? ''`,
-    )) as string;
 
     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[] = [
@@ -985,15 +1908,9 @@ export async function executeBrowserExtract(
     ];
 
     if (includeLinks) {
-      const links = (await page.evaluate(`
-        (() => {
-          const anchors = Array.from(document.querySelectorAll('a[href]'));
-          return anchors.slice(0, 200).map(a => ({
-            text: (a.textContent || '').trim().slice(0, 80),
-            href: a.href,
-          }));
-        })()
-      `)) as Array<{ text: string; href: string }>;
+      const links = await evaluateExpression<
+        Array<{ text: string; href: string }>
+      >(cdp, EXTRACT_LINKS_EXPRESSION, {}, context.signal);
 
       if (links.length > 0) {
         lines.push("");
@@ -1006,9 +1923,18 @@ 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 };
+  } finally {
+    cdp.dispose();
   }
 }
 
@@ -1028,26 +1954,43 @@ export async function executeBrowserFillCredential(
     return { content: "Error: field is required.", isError: true };
   }
 
-  const { selector, error } = resolveSelector(context.conversationId, input);
+  const { resolved, error } = resolveElement(context.conversationId, input);
   if (error) return { content: error, isError: true };
 
   const pressEnter = input.press_enter === true;
-
+  const targetDescription =
+    resolved!.kind === "backend"
+      ? `element_id "${resolved!.eid}"`
+      : resolved!.selector;
+
+  const acquired = acquireCdpClientWithMode(input, context);
+  if (acquired.errorResult) return acquired.errorResult;
+  const cdp = acquired.cdp;
   try {
-    const page = await browserManager.getOrCreateSessionPage(
-      context.conversationId,
-    );
+    let backendNodeId: number;
+    if (resolved!.kind === "backend") {
+      backendNodeId = resolved!.backendNodeId;
+    } else {
+      backendNodeId = await querySelectorBackendNodeId(
+        cdp,
+        resolved!.selector,
+        context.signal,
+      );
+    }
 
-    // Extract domain from the current page for domain policy enforcement
+    // Extract the current page's hostname for broker domain policy
+    // enforcement. Failures here (pre-navigation, about:blank, malformed
+    // URL) fall through with pageDomain undefined; if the credential
+    // has a domain policy the broker will deny the fill.
     let pageDomain: string | undefined;
     try {
-      const pageUrl = page.url();
+      const pageUrl = await getCurrentUrl(cdp, context.signal);
       if (pageUrl && pageUrl !== "about:blank") {
         const parsed = new URL(pageUrl);
         pageDomain = parsed.hostname;
       }
     } catch {
-      // Invalid URL - pageDomain stays undefined, broker will deny if domain policy exists
+      // pageDomain stays undefined
     }
 
     const result = await credentialBroker.browserFill({
@@ -1056,7 +1999,13 @@ export async function executeBrowserFillCredential(
       toolName: "browser_fill_credential",
       domain: pageDomain,
       fill: async (value) => {
-        await page.fill(selector!, value);
+        // Clear-then-focus-then-insert via the shared helper. We
+        // MUST clear first: Input.insertText writes at the cursor,
+        // so on autofilled / pre-populated fields a bare insert
+        // would append the credential to the existing value,
+        // producing a corrupted password and leaking partial state
+        // back into the page.
+        await clearAndInsertText(cdp, backendNodeId, value, context.signal);
       },
     });
 
@@ -1086,7 +2035,10 @@ export async function executeBrowserFillCredential(
           isError: true,
         };
       }
-      log.error({ selector, reason }, "Fill credential failed");
+      log.error(
+        { target: targetDescription, reason },
+        "Fill credential failed",
+      );
       return {
         content: `Error: Fill credential failed: ${reason}`,
         isError: true,
@@ -1094,7 +2046,7 @@ export async function executeBrowserFillCredential(
     }
 
     if (pressEnter) {
-      await page.press(selector!, "Enter");
+      await dispatchKeyPress(cdp, "Enter", context.signal);
     }
 
     return {
@@ -1102,8 +2054,501 @@ 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 };
+  } finally {
+    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 and enable the Vellum Relay Chrome extension.",
+    "Open the extension popup and click Pair with local assistant.",
+    "Keep the extension connected to the assistant relay.",
+  ];
+}
+
+function cdpInspectSetupActions(): string[] {
+  return [
+    "Launch Chrome with --remote-debugging-port=9222 (or your configured port).",
+    "Keep Chrome running while browser tools are in use.",
+    "Ensure the configured host is loopback (localhost / 127.0.0.1 / ::1).",
+  ];
+}
+
+function localSetupActions(): string[] {
+  return [
+    "Install assistant dependencies with bun install in assistant/.",
+    "Install Chromium for Playwright: bunx playwright install chromium.",
+  ];
+}
+
+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,
+      },
+    };
+  }
+
+  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 failed: ${msg}`,
+      isError: true,
+    };
   }
 }