[STG-1859] fix(cli): use exact DevToolsActivePort websocket path (browserbase#2049)

## Summary

- move local CDP discovery into a dedicated module so the
DevToolsActivePort behavior is directly testable
- reuse the exact `DevToolsActivePort` websocket path for `browse env
local --auto-connect`
- reuse the same exact-path lookup for bare numeric CDP targets in
`resolveWsTarget`
- avoid the extra speculative websocket verification pass on the
file-backed discovery path
- add regression coverage for exact-path resolution, stale file cleanup,
ambiguity, and fallback port probing

## Root Cause

The CLI was reading `DevToolsActivePort` but then discarding the exact
websocket path and probing generic endpoints first. On Chrome's
remote-debugging approval flow that could trigger extra preflight
requests before the real attach.

## Validation

- `pnpm --filter @browserbasehq/stagehand gen-version`
- `pnpm --filter @browserbasehq/stagehand build-dom-scripts`
- `pnpm --filter @browserbasehq/stagehand build`
- `pnpm --filter @browserbasehq/browse-cli build`
- `pnpm --filter @browserbasehq/browse-cli typecheck`
- `pnpm --filter @browserbasehq/browse-cli test`

Linear:
https://linear.app/browserbase/issue/STG-1859/use-exact-devtoolsactiveport-websocket-path-for-browse-cli-auto

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes local CDP auto-connect by using the exact websocket path from
DevToolsActivePort to avoid extra probes and speed up attach in Chrome’s
approval flow. Addresses Linear STG-1859 and improves
`@browserbasehq/browse-cli` for `browse env local --auto-connect` and
bare port targets.

- **Bug Fixes**
- Reuse the exact DevToolsActivePort websocket path for local
auto-connect.
- Prefer exact-path resolution for bare numeric ports in
`resolveWsTarget`, then fall back to `/json/version`, then
`/devtools/browser`.
- Skip speculative websocket verification when a file provides the exact
path.
- Clean up stale DevToolsActivePort files and return null on ambiguity.

- **Refactors**
- Extracted local CDP discovery to `local-cdp-discovery.ts` with tests
for exact-path resolution, stale cleanup, ambiguity, and fallback
probing.

<sup>Written for commit 440eee4.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2049">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

Author: shrey150

.changeset/rare-falcons-camp.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/browse-cli": patch
+---
+
+Use the exact DevToolsActivePort websocket path for local auto-connect and bare-port CDP attach to avoid extra remote debugging probes before the real browser connection.

packages/cli/src/index.ts

@@ -23,11 +23,11 @@ import {
   DEFAULT_LOCAL_CONFIG,
   getLocalModeHint,
   type LocalBrowserLaunchOptions,
-  type LocalCdpDiscovery,
   type LocalConfig,
   type LocalInfo,
   resolveLocalStrategy,
 } from "./local-strategy";
+import { discoverLocalCdp } from "./local-cdp-discovery";
 import { resolveWsTarget } from "./resolve-ws";
 import { NodeHtmlMarkdown } from "node-html-markdown";
 
@@ -282,238 +282,6 @@ async function getDesiredMode(session: string): Promise<BrowseMode> {
   return hasBrowserbaseCredentials() ? "browserbase" : "local";
 }
 
-// ==================== CDP AUTO-DISCOVERY ====================
-
-/**
- * Well-known Chrome user-data directories per platform.
- * Each may contain a DevToolsActivePort file when Chrome is running with
- * remote debugging enabled.
- */
-function getChromeUserDataDirs(): string[] {
-  const home = os.homedir();
-  const dirs: string[] = [];
-
-  if (process.platform === "darwin") {
-    const base = path.join(home, "Library", "Application Support");
-    for (const name of [
-      "Google/Chrome",
-      "Google/Chrome Canary",
-      "Chromium",
-      "BraveSoftware/Brave-Browser",
-    ]) {
-      dirs.push(path.join(base, name));
-    }
-  } else if (process.platform === "linux") {
-    const config = path.join(home, ".config");
-    for (const name of [
-      "google-chrome",
-      "google-chrome-unstable",
-      "chromium",
-      "BraveSoftware/Brave-Browser",
-    ]) {
-      dirs.push(path.join(config, name));
-    }
-  }
-
-  return dirs;
-}
-
-/**
- * Read DevToolsActivePort file from a Chrome user-data directory.
- * Returns { port, wsPath } or null if file doesn't exist or is malformed.
- */
-async function readDevToolsActivePort(
-  userDataDir: string,
-): Promise<{ port: number; wsPath: string } | null> {
-  try {
-    const content = await fs.readFile(
-      path.join(userDataDir, "DevToolsActivePort"),
-      "utf-8",
-    );
-    const lines = content.trim().split("\n");
-    const port = parseInt(lines[0]?.trim(), 10);
-    if (isNaN(port) || port <= 0 || port > 65535) return null;
-    const wsPath = lines[1]?.trim() || "/devtools/browser";
-    return { port, wsPath };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check if a TCP port is reachable on localhost with a short timeout.
- */
-function isPortReachable(port: number, timeoutMs = 500): Promise<boolean> {
-  return new Promise((resolve) => {
-    const sock = net.createConnection({ host: "127.0.0.1", port });
-    const timer = setTimeout(() => {
-      sock.destroy();
-      resolve(false);
-    }, timeoutMs);
-    sock.on("connect", () => {
-      clearTimeout(timer);
-      sock.destroy();
-      resolve(true);
-    });
-    sock.on("error", () => {
-      clearTimeout(timer);
-      resolve(false);
-    });
-  });
-}
-
-/**
- * Probe a CDP endpoint at the given port.
- * Tries /json/version first, then falls back to a direct WebSocket handshake
- * (needed for Chrome 136+ with UI-based remote debugging).
- * Returns the webSocketDebuggerUrl on success, or null.
- */
-async function probeCdpEndpoint(port: number): Promise<string | null> {
-  // Try /json/version (standard path)
-  try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 2000);
-    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
-      signal: controller.signal,
-    });
-    clearTimeout(timer);
-    if (res.ok) {
-      const json = (await res.json()) as { webSocketDebuggerUrl?: string };
-      if (json.webSocketDebuggerUrl) {
-        return json.webSocketDebuggerUrl;
-      }
-    }
-  } catch {
-    // /json/version unavailable
-  }
-
-  // Fallback: direct WebSocket at /devtools/browser
-  // Chrome 136+ with chrome://inspect may only expose WS, not HTTP endpoints
-  const wsUrl = `ws://127.0.0.1:${port}/devtools/browser`;
-  try {
-    const verified = await verifyCdpWebSocket(wsUrl);
-    if (verified) return wsUrl;
-  } catch {
-    // WS fallback also failed
-  }
-
-  return null;
-}
-
-/**
- * Verify a WebSocket URL is a valid CDP endpoint by attempting an HTTP upgrade.
- * Sends a minimal WebSocket handshake and checks for a 101 Switching Protocols response.
- */
-function verifyCdpWebSocket(wsUrl: string): Promise<boolean> {
-  return new Promise((resolve) => {
-    const url = new URL(wsUrl);
-    const port = parseInt(url.port) || 80;
-    const wsKey = Buffer.from(
-      Array.from({ length: 16 }, () => Math.floor(Math.random() * 256)),
-    ).toString("base64");
-
-    const sock = net.createConnection({ host: url.hostname, port });
-    let response = "";
-
-    const timer = setTimeout(() => {
-      sock.destroy();
-      resolve(false);
-    }, 2000);
-
-    sock.on("connect", () => {
-      // Send a WebSocket upgrade request
-      sock.write(
-        `GET ${url.pathname} HTTP/1.1\r\n` +
-          `Host: ${url.hostname}:${port}\r\n` +
-          `Upgrade: websocket\r\n` +
-          `Connection: Upgrade\r\n` +
-          `Sec-WebSocket-Key: ${wsKey}\r\n` +
-          `Sec-WebSocket-Version: 13\r\n` +
-          `\r\n`,
-      );
-    });
-
-    sock.on("data", (data) => {
-      response += data.toString();
-      // Check for successful WebSocket upgrade (101 Switching Protocols)
-      if (/^HTTP\/1\.[01] 101(?:\s|$)/.test(response)) {
-        clearTimeout(timer);
-        sock.destroy();
-        resolve(true);
-      } else if (response.includes("\r\n\r\n")) {
-        // Got a complete HTTP response that isn't 101
-        clearTimeout(timer);
-        sock.destroy();
-        resolve(false);
-      }
-    });
-
-    sock.on("error", () => {
-      clearTimeout(timer);
-      resolve(false);
-    });
-  });
-}
-
-interface CdpCandidate {
-  wsUrl: string;
-  source: string; // e.g. "DevToolsActivePort (Google Chrome)" or "port 9222"
-}
-
-/**
- * Discover locally-running Chrome instances with CDP debugging enabled.
- * Returns the discovered CDP WebSocket URL, or null with a reason.
- *
- * Discovery order:
- * 1. DevToolsActivePort files in well-known Chrome user-data dirs
- * 2. Common debugging ports (9222, 9229)
- *
- * If multiple healthy candidates are found, returns null (ambiguity).
- */
-async function discoverLocalCdp(): Promise<LocalCdpDiscovery | null> {
-  const candidates: CdpCandidate[] = [];
-
-  // Phase 1: Scan DevToolsActivePort files
-  const userDataDirs = getChromeUserDataDirs();
-  for (const dir of userDataDirs) {
-    const info = await readDevToolsActivePort(dir);
-    if (!info) continue;
-
-    // Verify port is alive
-    if (!(await isPortReachable(info.port))) {
-      // Stale file — clean up
-      try {
-        await fs.unlink(path.join(dir, "DevToolsActivePort"));
-      } catch {}
-      continue;
-    }
-
-    const wsUrl = await probeCdpEndpoint(info.port);
-    if (wsUrl) {
-      const name = path.basename(dir);
-      candidates.push({ wsUrl, source: `DevToolsActivePort (${name})` });
-    }
-  }
-
-  // Phase 2: Probe common ports (only if DevToolsActivePort yielded nothing)
-  if (candidates.length === 0) {
-    for (const port of [9222, 9229]) {
-      if (!(await isPortReachable(port))) continue;
-      const wsUrl = await probeCdpEndpoint(port);
-      if (wsUrl) {
-        candidates.push({ wsUrl, source: `port ${port}` });
-      }
-    }
-  }
-
-  // Ambiguity check
-  if (candidates.length > 1) {
-    return null; // Caller should fall back to isolated and report ambiguity
-  }
-
-  return candidates[0] ?? null;
-}
-
 async function isDaemonRunning(session: string): Promise<boolean> {
   try {
     const pidFile = getPidPath(session);