@vellumai/assistant 0.6.3 → 0.6.4

package/src/tools/browser/cdp-client/factory.ts

@@ -8,135 +8,835 @@ import {
   createLocalBackend,
 } from "../../../browser-session/index.js";
 import { getConfig } from "../../../config/loader.js";
+import { getLogger } from "../../../util/logger.js";
 import type { ToolContext } from "../../types.js";
 import { createCdpInspectClient } from "./cdp-inspect-client.js";
 import { CdpError } from "./errors.js";
 import { createExtensionCdpClient } from "./extension-cdp-client.js";
 import { createLocalCdpClient } from "./local-cdp-client.js";
-import type { CdpClient, CdpClientKind, ScopedCdpClient } from "./types.js";
+import type {
+  AttemptDiagnostic,
+  BackendCandidate,
+  BrowserMode,
+  CdpClient,
+  CdpClientKind,
+  ScopedCdpClient,
+} from "./types.js";
+
+const log = getLogger("cdp-factory");
+
+// ---------------------------------------------------------------------------
+// Desktop-auto cdp-inspect cooldown tracker
+// ---------------------------------------------------------------------------
+
+/**
+ * Module-level timestamp (epoch ms) of the last transport-level failure for
+ * a desktop-auto cdp-inspect attempt. While `Date.now() - _desktopAutoCooldownSince`
+ * is less than the configured `desktopAuto.cooldownMs`, the factory skips the
+ * automatic cdp-inspect candidate and goes straight to the local backend.
+ *
+ * **Process-global scope**: this is a module-level singleton that affects ALL
+ * conversations in the process. A cdp-inspect failure on any conversation
+ * suppresses desktop-auto probes for every conversation in this daemon until
+ * the cooldown expires. This is intentional -- the local loopback CDP
+ * endpoint is per-machine, not per-conversation, so a failure on one
+ * conversation implies all others would fail the same way.
+ *
+ * Reset to 0 when the cooldown expires or when manually cleared via
+ * {@link _resetDesktopAutoCooldown} (for testing).
+ */
+let _desktopAutoCooldownSince = 0;
+
+/**
+ * Record a cooldown after a desktop-auto cdp-inspect transport failure.
+ * Called by {@link maybeRecordDesktopAutoCooldown} in production; also
+ * exported directly for use in tests.
+ */
+export function recordDesktopAutoCooldown(): void {
+  _desktopAutoCooldownSince = Date.now();
+}
+
+/**
+ * Whether the desktop-auto cdp-inspect cooldown is currently active.
+ * Returns `true` if a failure was recorded and the configured cooldown
+ * window has not yet elapsed.
+ */
+export function isDesktopAutoCooldownActive(cooldownMs: number): boolean {
+  if (_desktopAutoCooldownSince === 0 || cooldownMs <= 0) return false;
+  return Date.now() - _desktopAutoCooldownSince < cooldownMs;
+}
+
+/**
+ * Reset the desktop-auto cooldown state. Exported for testing only.
+ */
+export function _resetDesktopAutoCooldown(): void {
+  _desktopAutoCooldownSince = 0;
+}
+
+/**
+ * Get the raw cooldown-since timestamp. Exported for testing only.
+ */
+export function _getDesktopAutoCooldownSince(): number {
+  return _desktopAutoCooldownSince;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for {@link getCdpClient}. All fields are optional — omitting
+ * them preserves the existing auto-mode behavior.
+ */
+export interface GetCdpClientOptions {
+  /**
+   * Backend mode preference. When omitted or `"auto"`, the factory
+   * uses the existing priority-ordered fallback chain. When set to a
+   * specific backend kind, the factory pins to that single backend
+   * and disables failover.
+   */
+  mode?: BrowserMode;
+}
 
 /**
  * Select the appropriate CdpClient implementation for a tool
  * invocation based on the ToolContext and config. Three backends are
  * considered in priority order:
  *
- *  1. **Extension** — When `context.hostBrowserProxy` is set (macOS
- *     desktop / cloud-hosted with a chrome-extension bound to the
- *     conversation), register an extension backend so CDP commands
- *     ride the host_browser_request / host_browser_result round-trip.
- *  2. **cdp-inspect** — When the extension is absent and
- *     `hostBrowser.cdpInspect.enabled` is `true` in config, construct
- *     a `CdpInspectClient` that attaches to an already-running Chrome
- *     via the DevTools JSON protocol (`--remote-debugging-port`).
- *  3. **Local** — Default. Drives Playwright's CDPSession
- *     against the sacrificial-profile browser managed by
- *     browserManager.
+ *  1. **Extension** -- When `context.hostBrowserProxy` is set AND
+ *     `hostBrowserProxy.isAvailable()` returns `true` (i.e. the
+ *     proxy exists and the client is actually connected). This
+ *     prevents selecting the extension transport when the proxy
+ *     object exists but the underlying WebSocket is disconnected.
+ *  2. **cdp-inspect** -- When `hostBrowser.cdpInspect.enabled` is
+ *     `true` in config, construct a `CdpInspectClient` that attaches
+ *     to an already-running Chrome via the DevTools JSON protocol.
+ *     On macOS, cdp-inspect is also included automatically when
+ *     `desktopAuto.enabled` is true (the default), even when the
+ *     top-level `enabled` flag is false.
+ *  3. **Local** -- Default. Drives Playwright's CDPSession against
+ *     the sacrificial-profile browser managed by browserManager.
+ *
+ * When `options.mode` is set to a specific backend kind, the factory
+ * builds exactly one candidate and disables failover. If the pinned
+ * backend is unavailable (e.g. pinned `extension` without an
+ * available host browser proxy), the factory throws a typed
+ * `CdpError` with `transport_error` code and a diagnostic indicating
+ * the precondition that was not met.
+ *
+ * The factory builds an ordered candidate list and returns a
+ * {@link ScopedCdpClient} with per-invocation failover semantics:
  *
- * All three paths go through a per-invocation `BrowserSessionManager`
- * so the manager is the single choke point for CDP routing, session
- * lifetime, and (future) session invalidation handling. The returned
- * client is `kind`-tagged so tools can branch on transport — e.g.
- * browser_navigate skips Playwright-specific screencast and handoff
- * hooks when `kind === "extension"`.
+ *  - On the first `send()`, the top-ranked candidate is selected and
+ *    its backend is materialised.
+ *  - If the first command fails with a **transport-level** error
+ *    (`transport_error`), the factory tears down the failed backend
+ *    and retries the same command against the next candidate.
+ *  - **CDP protocol errors** (`cdp_error`) do NOT trigger failover --
+ *    they indicate the browser understood the command and rejected it,
+ *    so hopping transports would not help.
+ *  - After the first successful CDP command, the backend becomes
+ *    **sticky** for the remainder of the invocation. Subsequent
+ *    commands always route through the same backend so multi-command
+ *    tool flows do not hop transports mid-step.
  *
  * IMPORTANT: the returned client is per-invocation. Tools MUST call
  * `dispose()` in a finally block. Dispose tears down the manager's
  * session and the underlying CDP client. Disposing an extension-backed
- * client does NOT dispose the underlying HostBrowserProxy — that is
+ * client does NOT dispose the underlying HostBrowserProxy -- that is
  * owned by the conversation.
  */
-export function getCdpClient(context: ToolContext): ScopedCdpClient {
+export function getCdpClient(
+  context: ToolContext,
+  options?: GetCdpClientOptions,
+): ScopedCdpClient {
+  const mode: BrowserMode = options?.mode ?? "auto";
+  const candidates =
+    mode === "auto"
+      ? buildCandidateList(context)
+      : buildPinnedCandidateList(context, mode);
+
+  log.debug(
+    {
+      conversationId: context.conversationId,
+      mode,
+      candidates: candidates.map((c) => ({ kind: c.kind, reason: c.reason })),
+    },
+    "CDP factory: built candidate list",
+  );
+
+  return buildChainedClient(context.conversationId, candidates, mode);
+}
+
+// ---------------------------------------------------------------------------
+// Pinned candidate list construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a single-element candidate list for a pinned backend mode.
+ * Throws a typed `CdpError` with structured diagnostics when the
+ * requested backend's preconditions are not met.
+ *
+ * Exported for testing.
+ */
+export function buildPinnedCandidateList(
+  context: ToolContext,
+  mode: Exclude<BrowserMode, "auto">,
+): BackendCandidate[] {
   const { conversationId, hostBrowserProxy } = context;
 
-  // 1. Extension backend — preferred when a chrome-extension is bound.
-  if (hostBrowserProxy) {
-    const client = createExtensionCdpClient(hostBrowserProxy, conversationId);
-    const backend = createExtensionBackend({
-      isAvailable: () => true,
-      sendCdp: (command, signal) =>
-        dispatchThroughClient(client, command, signal),
-      dispose: () => client.dispose(),
+  switch (mode) {
+    case "extension": {
+      if (!hostBrowserProxy || !hostBrowserProxy.isAvailable()) {
+        const reason = !hostBrowserProxy
+          ? "no host browser proxy provisioned for this conversation"
+          : "host browser proxy exists but is not connected";
+        throw new CdpError(
+          "transport_error",
+          `Pinned mode "extension" unavailable: ${reason}`,
+          {
+            attemptDiagnostics: [
+              {
+                candidateKind: "extension",
+                inclusionReason: `pinned mode: extension`,
+                stage: "candidate_selection",
+                errorCode: "transport_error",
+                errorMessage: reason,
+              },
+            ],
+          },
+        );
+      }
+      return [
+        {
+          kind: "extension",
+          reason: "pinned mode: extension",
+          create() {
+            const client = createExtensionCdpClient(
+              hostBrowserProxy,
+              conversationId,
+            );
+            const backend = createExtensionBackend({
+              isAvailable: () => true,
+              sendCdp: (command, signal) =>
+                dispatchThroughClient(client, command, signal),
+              dispose: () => client.dispose(),
+            });
+            return { client, backend };
+          },
+        },
+      ];
+    }
+    case "cdp-inspect": {
+      const cdpInspectConfig = getConfig().hostBrowser.cdpInspect;
+      return [
+        {
+          kind: "cdp-inspect",
+          reason: "pinned mode: cdp-inspect",
+          create() {
+            const client = createCdpInspectClient(conversationId, {
+              host: cdpInspectConfig.host,
+              port: cdpInspectConfig.port,
+              discoveryTimeoutMs: cdpInspectConfig.probeTimeoutMs,
+            });
+            const backend = createCdpInspectBackend({
+              isAvailable: () => true,
+              sendCdp: (command, signal) =>
+                dispatchThroughClient(client, command, signal),
+              dispose: () => client.dispose(),
+            });
+            return { client, backend };
+          },
+        },
+      ];
+    }
+    case "local": {
+      return [
+        {
+          kind: "local",
+          reason: "pinned mode: local",
+          create() {
+            const client = createLocalCdpClient(conversationId);
+            const backend = createLocalBackend({
+              isAvailable: () => true,
+              sendCdp: (command, signal) =>
+                dispatchThroughClient(client, command, signal),
+              dispose: () => client.dispose(),
+            });
+            return { client, backend };
+          },
+        },
+      ];
+    }
+    default: {
+      // Exhaustive check — if new modes are added, TypeScript will
+      // flag this as an error.
+      const _exhaustive: never = mode;
+      throw new Error(`Unknown pinned mode: ${_exhaustive}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Candidate list construction (auto mode)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an ordered list of backend candidates from the tool context
+ * and config. Candidates are evaluated lazily -- `create()` is only
+ * called when the candidate is actually selected.
+ *
+ * Exported for testing.
+ */
+export function buildCandidateList(context: ToolContext): BackendCandidate[] {
+  const { conversationId, hostBrowserProxy } = context;
+  const candidates: BackendCandidate[] = [];
+
+  // 1. Extension -- preferred when a chrome-extension is bound AND
+  //    the proxy reports it is connected. Checking isAvailable()
+  //    prevents selecting the extension transport when the proxy
+  //    object exists (e.g. it was provisioned at conversation start)
+  //    but the client has since disconnected.
+  if (hostBrowserProxy && hostBrowserProxy.isAvailable()) {
+    candidates.push({
+      kind: "extension",
+      reason: "hostBrowserProxy present and available",
+      create() {
+        const client = createExtensionCdpClient(
+          hostBrowserProxy,
+          conversationId,
+        );
+        const backend = createExtensionBackend({
+          isAvailable: () => true,
+          sendCdp: (command, signal) =>
+            dispatchThroughClient(client, command, signal),
+          dispose: () => client.dispose(),
+        });
+        return { client, backend };
+      },
     });
-    return buildManagedClient("extension", conversationId, backend);
+  } else if (hostBrowserProxy) {
+    log.debug(
+      { conversationId },
+      "CDP factory: hostBrowserProxy present but not available, skipping extension candidate",
+    );
   }
 
-  // 2. cdp-inspect backend — opt-in via config when the extension is absent.
+  // 2. cdp-inspect -- opt-in via config OR desktop-auto for macOS turns.
   const cdpInspectConfig = getConfig().hostBrowser.cdpInspect;
   if (cdpInspectConfig.enabled) {
-    const client = createCdpInspectClient(conversationId, {
-      host: cdpInspectConfig.host,
-      port: cdpInspectConfig.port,
-      discoveryTimeoutMs: cdpInspectConfig.probeTimeoutMs,
-    });
-    const backend = createCdpInspectBackend({
-      isAvailable: () => true,
-      sendCdp: (command, signal) =>
-        dispatchThroughClient(client, command, signal),
-      dispose: () => client.dispose(),
+    // Explicitly enabled in config -- always include regardless of platform.
+    candidates.push({
+      kind: "cdp-inspect",
+      reason: "cdpInspect enabled in config",
+      create() {
+        const client = createCdpInspectClient(conversationId, {
+          host: cdpInspectConfig.host,
+          port: cdpInspectConfig.port,
+          discoveryTimeoutMs: cdpInspectConfig.probeTimeoutMs,
+        });
+        const backend = createCdpInspectBackend({
+          isAvailable: () => true,
+          sendCdp: (command, signal) =>
+            dispatchThroughClient(client, command, signal),
+          dispose: () => client.dispose(),
+        });
+        return { client, backend };
+      },
     });
-    return buildManagedClient("cdp-inspect", conversationId, backend);
+  } else if (
+    context.transportInterface === "macos" &&
+    cdpInspectConfig.desktopAuto.enabled
+  ) {
+    // macOS desktop-auto: include cdp-inspect as a candidate unless:
+    // (a) the hostBrowserProxy exists but is temporarily unavailable
+    //     (extension transport expected but transiently disconnected --
+    //     inserting cdp-inspect here would cause a silent takeover), or
+    // (b) the cooldown from a recent failure is still active.
+    //
+    // When no hostBrowserProxy is present at all (extension not
+    // provisioned for this conversation), cdp-inspect remains available
+    // as a fallback per the desktop-auto contract.
+    if (hostBrowserProxy && !hostBrowserProxy.isAvailable()) {
+      log.debug(
+        { conversationId },
+        "CDP factory: desktop-auto cdp-inspect skipped (extension transport expected but temporarily unavailable)",
+      );
+    } else {
+      const { cooldownMs } = cdpInspectConfig.desktopAuto;
+      if (isDesktopAutoCooldownActive(cooldownMs)) {
+        log.debug(
+          {
+            conversationId,
+            cooldownMs,
+            cooldownSince: _desktopAutoCooldownSince,
+          },
+          "CDP factory: desktop-auto cdp-inspect skipped (cooldown active)",
+        );
+      } else {
+        candidates.push({
+          kind: "cdp-inspect",
+          reason: "desktopAuto: macOS turn, cdp-inspect auto-attempted",
+          create() {
+            const client = createCdpInspectClient(conversationId, {
+              host: cdpInspectConfig.host,
+              port: cdpInspectConfig.port,
+              discoveryTimeoutMs: cdpInspectConfig.probeTimeoutMs,
+              wsConnectTimeoutMs: cdpInspectConfig.probeTimeoutMs,
+            });
+            const backend = createCdpInspectBackend({
+              isAvailable: () => true,
+              sendCdp: (command, signal) =>
+                dispatchThroughClient(client, command, signal),
+              dispose: () => client.dispose(),
+            });
+            return { client, backend };
+          },
+        });
+      }
+    }
   }
 
-  // 3. Local backend — default (Playwright-backed Chromium).
-  const client = createLocalCdpClient(conversationId);
-  const backend = createLocalBackend({
-    isAvailable: () => true,
-    sendCdp: (command, signal) =>
-      dispatchThroughClient(client, command, signal),
-    dispose: () => client.dispose(),
+  // 3. Local -- always present as the final fallback.
+  candidates.push({
+    kind: "local",
+    reason: "default Playwright fallback",
+    create() {
+      const client = createLocalCdpClient(conversationId);
+      const backend = createLocalBackend({
+        isAvailable: () => true,
+        sendCdp: (command, signal) =>
+          dispatchThroughClient(client, command, signal),
+        dispose: () => client.dispose(),
+      });
+      return { client, backend };
+    },
   });
-  return buildManagedClient("local", conversationId, backend);
+
+  return candidates;
 }
 
+// ---------------------------------------------------------------------------
+// Chained client with per-invocation failover
+// ---------------------------------------------------------------------------
+
 /**
- * Build a ScopedCdpClient whose `send()` routes through a
- * BrowserSessionManager seeded with a single backend + session. This
- * lets tool call sites remain backend-agnostic while giving the
- * manager a seam for future session-invalidation and multi-target
- * routing work.
+ * Build a {@link ScopedCdpClient} that walks the candidate list on
+ * the first command, failing over on transport-level errors, and
+ * becomes sticky after the first successful CDP command.
+ *
+ * Exported for testing.
  */
-function buildManagedClient(
-  kind: CdpClientKind,
+export function buildChainedClient(
   conversationId: string,
-  backend: BrowserBackend,
+  candidates: BackendCandidate[],
+  mode: BrowserMode = "auto",
 ): ScopedCdpClient {
-  const manager = new BrowserSessionManager({ backends: [backend] });
-  const session = manager.createSession();
+  if (candidates.length === 0) {
+    throw new Error("CDP factory: no backend candidates available");
+  }
+
+  /** Active backend state -- populated after first successful command. */
+  let active: {
+    kind: CdpClientKind;
+    manager: BrowserSessionManager;
+    sessionId: string;
+  } | null = null;
+
+  /** Set to true after the first successful CDP command. */
+  let sticky = false;
+
   let disposed = false;
 
-  return {
-    kind,
+  /**
+   * Track all materialised backends so dispose() can tear them all
+   * down, even ones that were tried and failed before the sticky
+   * backend was established.
+   */
+  const materialisedManagers: BrowserSessionManager[] = [];
+
+  /**
+   * The kind of the currently active (or last attempted) backend.
+   * Before the first send this reflects the first candidate; after
+   * the sticky backend is established it reflects the chosen kind.
+   */
+  let currentKind: CdpClientKind = candidates[0].kind;
+
+  const scopedClient: ScopedCdpClient = {
+    get kind(): CdpClientKind {
+      return active?.kind ?? currentKind;
+    },
     conversationId,
+
     async send<T = unknown>(
       method: string,
       params?: Record<string, unknown>,
       signal?: AbortSignal,
     ): Promise<T> {
       if (disposed) {
-        const clientName =
-          kind === "extension"
-            ? "ExtensionCdpClient"
-            : kind === "cdp-inspect"
-              ? "CdpInspectClient"
-              : "LocalCdpClient";
-        throw new CdpError("disposed", `${clientName} already disposed`, {
+        throw new CdpError("disposed", "CdpClient already disposed", {
           cdpMethod: method,
           cdpParams: params,
         });
       }
-      const command: CdpCommand = { method, params };
-      const envelope = await manager.send(session.id, command, signal);
-      return unwrapResult<T>(envelope, method, params);
+
+      // Fast path: backend is already sticky -- route directly.
+      if (sticky && active) {
+        const command: CdpCommand = { method, params };
+        const envelope = await active.manager.send(
+          active.sessionId,
+          command,
+          signal,
+        );
+        return unwrapResult<T>(envelope, method, params);
+      }
+
+      // Slow path: walk the candidate list with failover.
+      return sendWithFailover<T>(
+        candidates,
+        materialisedManagers,
+        method,
+        params,
+        signal,
+        (established) => {
+          active = established;
+          sticky = true;
+          currentKind = established.kind;
+        },
+        () => disposed,
+        conversationId,
+        mode,
+      );
     },
+
     dispose(): void {
       if (disposed) return;
       disposed = true;
-      // disposeAll() tears down the per-invocation backend (which in
-      // turn disposes the underlying CdpClient) and clears the single
-      // session we created in buildManagedClient.
-      manager.disposeAll();
+      for (const m of materialisedManagers) {
+        m.disposeAll();
+      }
+      materialisedManagers.length = 0;
+      active = null;
     },
   };
+
+  return scopedClient;
+}
+
+/**
+ * Walk the candidate list attempting to execute a single CDP command.
+ * Transport-level failures trigger failover to the next candidate;
+ * CDP protocol errors propagate immediately.
+ *
+ * When a desktop-auto cdp-inspect candidate fails with a transport
+ * error, the factory records a cooldown so subsequent calls skip the
+ * probe until the window expires.
+ *
+ * In auto mode, each attempted candidate is recorded as an
+ * {@link AttemptDiagnostic}. When fallback occurs, a production-visible
+ * log is emitted with the full candidate sequence and per-candidate
+ * failure reasons. If all candidates are exhausted, the diagnostics
+ * are attached to the thrown {@link CdpError}.
+ */
+async function sendWithFailover<T>(
+  candidates: BackendCandidate[],
+  materialisedManagers: BrowserSessionManager[],
+  method: string,
+  params: Record<string, unknown> | undefined,
+  signal: AbortSignal | undefined,
+  onEstablished: (active: {
+    kind: CdpClientKind;
+    manager: BrowserSessionManager;
+    sessionId: string;
+  }) => void,
+  isDisposed: () => boolean,
+  conversationId: string,
+  mode: BrowserMode,
+): Promise<T> {
+  let lastError: CdpError | undefined;
+  const diagnostics: AttemptDiagnostic[] = [];
+
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i];
+    if (isDisposed()) {
+      throw new CdpError("disposed", "CdpClient already disposed", {
+        cdpMethod: method,
+        cdpParams: params,
+      });
+    }
+
+    log.debug(
+      {
+        conversationId,
+        candidateKind: candidate.kind,
+        candidateIndex: i,
+        method,
+      },
+      "CDP factory: attempting candidate",
+    );
+
+    let backend: BrowserBackend;
+    try {
+      const created = candidate.create();
+      backend = created.backend;
+    } catch (err) {
+      // Backend construction failed -- treat as transport error and
+      // try the next candidate.
+      const errorMessage = `Backend ${candidate.kind} construction failed: ${err instanceof Error ? err.message : String(err)}`;
+      log.debug(
+        { conversationId, candidateKind: candidate.kind, err },
+        "CDP factory: candidate construction failed, trying next",
+      );
+      lastError = new CdpError("transport_error", errorMessage, {
+        cdpMethod: method,
+        cdpParams: params,
+        underlying: err,
+      });
+      diagnostics.push({
+        candidateKind: candidate.kind,
+        inclusionReason: candidate.reason,
+        stage: "construction",
+        errorCode: "transport_error",
+        errorMessage,
+      });
+      maybeRecordDesktopAutoCooldown(candidate);
+
+      // Emit production-visible fallback log in auto mode
+      if (mode === "auto" && i < candidates.length - 1) {
+        log.warn(
+          {
+            conversationId,
+            failedCandidate: candidate.kind,
+            nextCandidate: candidates[i + 1].kind,
+            attemptedSoFar: diagnostics.map((d) => ({
+              kind: d.candidateKind,
+              stage: d.stage,
+              errorCode: d.errorCode,
+              errorMessage: d.errorMessage,
+            })),
+          },
+          "CDP factory: auto-mode fallback triggered",
+        );
+      }
+      continue;
+    }
+
+    const manager = new BrowserSessionManager({ backends: [backend] });
+    materialisedManagers.push(manager);
+    const session = manager.createSession();
+
+    const command: CdpCommand = { method, params };
+    let envelope: CdpResult;
+    try {
+      envelope = await manager.send(session.id, command, signal);
+    } catch (err) {
+      // Manager-level errors (unknown session, no available backend)
+      // are transport-level problems -- try the next candidate.
+      const errorMessage = `Backend ${candidate.kind} send threw: ${err instanceof Error ? err.message : String(err)}`;
+      log.debug(
+        { conversationId, candidateKind: candidate.kind, err },
+        "CDP factory: candidate send threw, trying next",
+      );
+      manager.disposeAll();
+      lastError = new CdpError("transport_error", errorMessage, {
+        cdpMethod: method,
+        cdpParams: params,
+        underlying: err,
+      });
+      diagnostics.push({
+        candidateKind: candidate.kind,
+        inclusionReason: candidate.reason,
+        stage: "send",
+        errorCode: "transport_error",
+        errorMessage,
+        discoveryCode: extractDiscoveryCode(err),
+      });
+      maybeRecordDesktopAutoCooldown(candidate);
+
+      // Emit production-visible fallback log in auto mode
+      if (mode === "auto" && i < candidates.length - 1) {
+        log.warn(
+          {
+            conversationId,
+            failedCandidate: candidate.kind,
+            nextCandidate: candidates[i + 1].kind,
+            attemptedSoFar: diagnostics.map((d) => ({
+              kind: d.candidateKind,
+              stage: d.stage,
+              errorCode: d.errorCode,
+              errorMessage: d.errorMessage,
+            })),
+          },
+          "CDP factory: auto-mode fallback triggered",
+        );
+      }
+      continue;
+    }
+
+    // Inspect the envelope for errors. Transport-level errors trigger
+    // failover; CDP protocol errors propagate immediately.
+    if (envelope.error) {
+      const cdpError = extractCdpError(envelope, method, params);
+
+      if (isTransportFailover(cdpError) && i < candidates.length - 1) {
+        log.debug(
+          {
+            conversationId,
+            candidateKind: candidate.kind,
+            errorCode: cdpError.code,
+            errorMessage: cdpError.message,
+          },
+          "CDP factory: transport-level failure, failing over to next candidate",
+        );
+        manager.disposeAll();
+        lastError = cdpError;
+        diagnostics.push({
+          candidateKind: candidate.kind,
+          inclusionReason: candidate.reason,
+          stage: "send",
+          errorCode: cdpError.code,
+          errorMessage: cdpError.message,
+          discoveryCode: extractDiscoveryCode(cdpError.underlying),
+        });
+        maybeRecordDesktopAutoCooldown(candidate);
+
+        // Emit production-visible fallback log in auto mode
+        if (mode === "auto") {
+          log.warn(
+            {
+              conversationId,
+              failedCandidate: candidate.kind,
+              nextCandidate: candidates[i + 1].kind,
+              attemptedSoFar: diagnostics.map((d) => ({
+                kind: d.candidateKind,
+                stage: d.stage,
+                errorCode: d.errorCode,
+                errorMessage: d.errorMessage,
+              })),
+            },
+            "CDP factory: auto-mode fallback triggered",
+          );
+        }
+        continue;
+      }
+
+      // Either a CDP protocol error or we've exhausted candidates --
+      // propagate the error as-is, attaching diagnostics.
+      diagnostics.push({
+        candidateKind: candidate.kind,
+        inclusionReason: candidate.reason,
+        stage: "send",
+        errorCode: cdpError.code,
+        errorMessage: cdpError.message,
+        discoveryCode: extractDiscoveryCode(cdpError.underlying),
+      });
+      throw new CdpError(cdpError.code, cdpError.message, {
+        cdpMethod: cdpError.cdpMethod,
+        cdpParams: cdpError.cdpParams,
+        underlying: cdpError.underlying,
+        attemptDiagnostics: diagnostics.length > 0 ? diagnostics : undefined,
+      });
+    }
+
+    // Success! Establish this backend as the sticky choice.
+    diagnostics.push({
+      candidateKind: candidate.kind,
+      inclusionReason: candidate.reason,
+      stage: "success",
+    });
+
+    // If there were prior failed candidates in auto mode, log the
+    // full sequence for observability.
+    if (mode === "auto" && diagnostics.length > 1) {
+      log.warn(
+        {
+          conversationId,
+          stickyCandidate: candidate.kind,
+          attemptSequence: diagnostics.map((d) => ({
+            kind: d.candidateKind,
+            stage: d.stage,
+            errorCode: d.errorCode,
+            errorMessage: d.errorMessage,
+          })),
+        },
+        "CDP factory: auto-mode fallback completed, backend established after retries",
+      );
+    }
+
+    log.debug(
+      { conversationId, candidateKind: candidate.kind, method },
+      "CDP factory: candidate succeeded, backend is now sticky",
+    );
+    onEstablished({ kind: candidate.kind, manager, sessionId: session.id });
+    return envelope.result as T;
+  }
+
+  // All candidates exhausted -- throw the last transport error with
+  // full attempt diagnostics attached.
+  throw lastError
+    ? new CdpError(lastError.code, lastError.message, {
+        cdpMethod: lastError.cdpMethod,
+        cdpParams: lastError.cdpParams,
+        underlying: lastError.underlying,
+        attemptDiagnostics: diagnostics.length > 0 ? diagnostics : undefined,
+      })
+    : new CdpError("transport_error", "All backend candidates exhausted", {
+        cdpMethod: method,
+        cdpParams: params,
+        attemptDiagnostics: diagnostics.length > 0 ? diagnostics : undefined,
+      });
+}
+
+/**
+ * If the failed candidate is a desktop-auto cdp-inspect attempt,
+ * record the cooldown so subsequent calls skip the probe.
+ */
+function maybeRecordDesktopAutoCooldown(candidate: BackendCandidate): void {
+  if (
+    candidate.kind === "cdp-inspect" &&
+    candidate.reason.startsWith("desktopAuto:")
+  ) {
+    log.debug(
+      "CDP factory: recording desktop-auto cdp-inspect cooldown after transport failure",
+    );
+    recordDesktopAutoCooldown();
+  }
+}
+
+/**
+ * Determine whether a CdpError should trigger failover to the next
+ * candidate. Only transport-level failures are eligible -- CDP
+ * protocol errors indicate the browser understood the command and
+ * rejected it, so retrying on a different transport would not help.
+ */
+function isTransportFailover(err: CdpError): boolean {
+  return err.code === "transport_error";
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (shared with the old implementation)
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a CdpError from a CdpResult envelope that carries an error.
+ */
+function extractCdpError(
+  envelope: CdpResult,
+  method: string,
+  params?: Record<string, unknown>,
+): CdpError {
+  if (envelope.error?.data instanceof CdpError) {
+    return envelope.error.data;
+  }
+  return new CdpError(
+    "cdp_error",
+    envelope.error?.message ?? "Unknown CDP error",
+    {
+      cdpMethod: method,
+      cdpParams: params,
+      underlying: envelope.error,
+    },
+  );
 }
 
 /**
@@ -148,7 +848,7 @@ function buildManagedClient(
  *
  * The per-command `command.sessionId` (populated by the manager from
  * a session's opaque `targetId`) is intentionally not forwarded to
- * the underlying CdpClient today — both LocalCdpClient and
+ * the underlying CdpClient today -- both LocalCdpClient and
  * ExtensionCdpClient take their CDP sessionId at construction time
  * and tools run one client per invocation. The seam is preserved so
  * a future multi-target backend can read it off the CdpCommand.
@@ -163,9 +863,9 @@ async function dispatchThroughClient(
     return { result };
   } catch (err) {
     if (err instanceof CdpError) {
-      // Preserve the original CdpError so unwrapResult can re-throw it
-      // verbatim. CdpResult's error channel is opaque to the manager,
-      // so stashing the instance under `data` is safe.
+      // Preserve the original CdpError so extractCdpError can
+      // re-throw it verbatim. CdpResult's error channel is opaque
+      // to the manager, so stashing the instance under `data` is safe.
       return {
         error: {
           code: -1,
@@ -191,14 +891,24 @@ function unwrapResult<T>(
   params?: Record<string, unknown>,
 ): T {
   if (envelope.error) {
-    if (envelope.error.data instanceof CdpError) {
-      throw envelope.error.data;
-    }
-    throw new CdpError("cdp_error", envelope.error.message, {
-      cdpMethod: method,
-      cdpParams: params,
-      underlying: envelope.error,
-    });
+    throw extractCdpError(envelope, method, params);
   }
   return envelope.result as T;
 }
+
+/**
+ * Attempt to extract a discovery-level error code from an underlying
+ * error. Some CdpInspectClient errors embed a discovery code (e.g.
+ * "ECONNREFUSED", "DISCOVERY_TIMEOUT") that is useful for diagnostics.
+ */
+function extractDiscoveryCode(underlying: unknown): string | undefined {
+  if (underlying == null) return undefined;
+  if (typeof underlying === "object" && "code" in underlying) {
+    const code = (underlying as Record<string, unknown>).code;
+    if (typeof code === "string") return code;
+  }
+  if (underlying instanceof Error && "cause" in underlying) {
+    return extractDiscoveryCode(underlying.cause);
+  }
+  return undefined;
+}