pi-browser-harness 0.11.0 → 0.12.0

package/src/daemon/bridge.ts

@@ -5,6 +5,8 @@ import type { CdpRawMessage } from "../cdp/types";
 import type { WireRequest, WireResponse, WireEvent } from "./protocol";
 import { CDP_CONNECT_TIMEOUT_MS, CDP_COMMAND_TIMEOUT_MS } from "./protocol";
 import { asString, isRecord } from "../util/guards";
+import type { CdpError } from "../cdp/errors";
+import type { Result } from "../util/result";
 
 export type SendToClient = (clientId: string, msg: WireResponse | WireEvent) => void;
 
@@ -117,9 +119,22 @@ export const createEventRouter = (): EventRouter => {
   };
 };
 
-const CONNECT_WAIT_MS = 15_000;
+type CdpBridgeDependencies = {
+  discoverWsUrl?: () => Promise<Result<string, CdpError>>;
+  createWebSocket?: (url: string) => WebSocket;
+  connectTimeoutMs?: number;
+  onAttemptSettled?: () => void;
+};
+
+export const createCdpBridge = (options: CdpBridgeDependencies = {}): CdpBridge => {
+  const {
+    discoverWsUrl: discoverWsUrlImpl = discoverWsUrl,
+    createWebSocket: createWebSocketImpl = (url: string): WebSocket =>
+      new WebSocket(url, { perMessageDeflate: false }),
+    connectTimeoutMs = CDP_CONNECT_TIMEOUT_MS,
+    onAttemptSettled,
+  } = options;
 
-export const createCdpBridge = (): CdpBridge => {
   let ws: WebSocket | null = null;
   let wsUrl: string | null = null;
   const mux = createIdMultiplexer();
@@ -127,23 +142,15 @@ export const createCdpBridge = (): CdpBridge => {
   let eventHandler: EventHandler | null = null;
   let closeHandler: CloseHandler | null = null;
 
-  const connectedWaiters: Array<() => void> = [];
-  const signalConnected = (): void => {
-    for (const w of connectedWaiters.splice(0)) w();
-  };
+  // daemonId -> { generation, clientId }: lets a failed attempt reject only its own
+  // in-flight requests, and a gone client's entries be dropped without late answers.
+  const generations = new Map<number, { generation: number; clientId: string }>();
 
-  const waitForConnection = (timeoutMs: number): Promise<void> =>
-    new Promise((resolve) => {
-      let settled = false;
-      const finish = (): void => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        resolve();
-      };
-      const timer = setTimeout(finish, timeoutMs);
-      connectedWaiters.push(finish);
-    });
+  let stopped = false;
+  let connecting = false;
+  let attemptGeneration = 0;
+  let activeAttempt = 0;
+  let activeSocket: WebSocket | null = null;
 
   const onChromeMessage = (raw: string): void => {
     let parsed: unknown;
@@ -152,6 +159,7 @@ export const createCdpBridge = (): CdpBridge => {
     const msg: CdpRawMessage = parsed;
 
     if (msg.id !== undefined) {
+      generations.delete(msg.id);
       const cb = mux.take(msg.id);
       if (!cb) return;
       const localId = cb.localId;
@@ -195,98 +203,215 @@ export const createCdpBridge = (): CdpBridge => {
     }
   };
 
-  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-  let reconnectAttempt = 0;
-  let stopped = false;
+  const rejectCallbacksWhere = (
+    pred: (info: { generation: number; clientId: string }) => boolean,
+  ): void => {
+    for (const [daemonId, info] of generations) {
+      if (!pred(info)) continue;
+      generations.delete(daemonId);
+      const cb = mux.take(daemonId);
+      if (!cb) continue;
+      cb.send(cb.clientId, {
+        type: "response",
+        id: cb.localId,
+        error: { code: -32000, message: "Chrome disconnected" },
+      });
+    }
+  };
+
+  const rejectAttemptCallbacks = (generation: number): void => {
+    rejectCallbacksWhere((info) => info.generation === generation);
+  };
+
+  const rejectAllPendingCallbacks = (): void => {
+    rejectCallbacksWhere(() => true);
+  };
+
+  const closeSocket = (socket: WebSocket): void => {
+    try {
+      socket.close();
+    } catch {}
+  };
+
+  const isCurrentAttempt = (generation: number): boolean =>
+    generation === activeAttempt && !stopped;
+
+  const isCurrentAttemptSocket = (generation: number, socket: WebSocket): boolean =>
+    isCurrentAttempt(generation) && activeSocket === socket;
+
+  const clearActiveAttempt = (generation: number): void => {
+    if (activeAttempt === generation) {
+      activeAttempt = 0;
+      activeSocket = null;
+    }
+  };
 
+  // On-demand Chrome connection. Attempts happen only from start() and from
+  // handleRequest() while disconnected; a failed or disconnected bridge stays
+  // disconnected until the next explicit browser demand. No background retry loop.
   const tryConnect = (): void => {
-    if (stopped) return;
-    if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+    if (stopped || connecting || (ws && ws.readyState === WebSocket.OPEN)) return;
 
-    const attempt = async (): Promise<void> => {
-      if (ws && ws.readyState === WebSocket.OPEN) return;
+    const generation = ++attemptGeneration;
+    activeAttempt = generation;
+    connecting = true;
 
-      const cachedUrl = wsUrl;
-      let url: string;
-      if (cachedUrl === null || cachedUrl === "" || reconnectAttempt > 0) {
-        const d = await discoverWsUrl();
-        if (!d.success) { scheduleRetry(); return; }
-        url = d.data;
-        wsUrl = url;
-      } else {
-        url = cachedUrl;
-      }
+    const attempt = async (): Promise<void> => {
+      let settled = false;
+      let sock: WebSocket | null = null;
+      let timeout: ReturnType<typeof setTimeout> | null = null;
+      let settleAttempt: () => void = () => {};
 
-      const settledPromise = new Promise<void>((settle) => {
-        let settled = false;
-        const settleOnce = (): void => {
+      const settledPromise = new Promise<void>((resolve) => {
+        settleAttempt = (): void => {
           if (settled) return;
           settled = true;
-          settle();
+          if (timeout) {
+            clearTimeout(timeout);
+            timeout = null;
+          }
+          if (generation === activeAttempt && !stopped) {
+            wsUrl = null;
+            connecting = false;
+          }
+          rejectAttemptCallbacks(generation);
+          onAttemptSettled?.();
+          resolve();
         };
+      });
 
-        let sock: WebSocket;
-        try {
-          sock = new WebSocket(url, { perMessageDeflate: false });
-        } catch {
-          scheduleRetry();
+      const clearAttemptTimeout = (): void => {
+        if (timeout) {
+          clearTimeout(timeout);
+          timeout = null;
+        }
+      };
+
+      const failCurrentAttempt = (notifyClose: boolean): void => {
+        clearAttemptTimeout();
+        const isCurrent = isCurrentAttempt(generation);
+        if (!isCurrent) {
+          rejectAttemptCallbacks(generation);
           return;
         }
 
-        const timer = setTimeout(() => {
-          sock.close();
-          settleOnce();
-        }, CDP_CONNECT_TIMEOUT_MS);
+        clearActiveAttempt(generation);
+        if (ws === sock) ws = null;
+        wsUrl = null;
+        connecting = false;
+        // Not via settleAttempt: a connection that opened already settled its attempt, so
+        // its requests would otherwise hang to the command timeout instead of failing now.
+        rejectAttemptCallbacks(generation);
+        if (notifyClose) closeHandler?.();
+        settleAttempt();
+      };
 
-        sock.on("open", () => {
-          clearTimeout(timer);
-          ws = sock;
-          reconnectAttempt = 0;
-          ws.send(JSON.stringify({ id: 0, method: "Target.setDiscoverTargets", params: { discover: true } }));
-          console.log("[pi-browser-daemon] Connected to Chrome ✓");
-          signalConnected();
-          settleOnce();
-        });
+      timeout = setTimeout(() => {
+        if (!isCurrentAttempt(generation) || stopped) {
+          failCurrentAttempt(false);
+          return;
+        }
 
-        sock.on("message", (data: WebSocket.Data) => {
-          onChromeMessage(typeof data === "string" ? data : data.toString());
-        });
+        if (sock && sock.readyState !== WebSocket.CLOSED) {
+          closeSocket(sock);
+        }
+        failCurrentAttempt(true);
+      }, connectTimeoutMs);
+
+      let url = wsUrl;
+      if (!url) {
+        const d = await discoverWsUrlImpl();
+        if (!isCurrentAttempt(generation) || stopped) {
+          failCurrentAttempt(false);
+          return;
+        }
+        if (!d.success) {
+          failCurrentAttempt(false);
+          return;
+        }
+        url = d.data;
+      }
 
-        sock.on("error", () => {
-          clearTimeout(timer);
-          settleOnce();
-        });
+      if (!isCurrentAttempt(generation) || stopped) {
+        failCurrentAttempt(false);
+        return;
+      }
 
-        sock.on("close", () => {
-          clearTimeout(timer);
-          ws = null;
-          for (const cb of mux.takeAll()) {
-            cb.send(cb.clientId, {
-              type: "response",
-              id: cb.localId,
-              error: { code: -32000, message: "Chrome disconnected" },
-            });
+      try {
+        sock = createWebSocketImpl(url);
+      } catch {
+        failCurrentAttempt(false);
+        return;
+      }
+
+      if (!isCurrentAttempt(generation) || stopped) {
+        closeSocket(sock);
+        failCurrentAttempt(false);
+        return;
+      }
+
+      wsUrl = url;
+      activeSocket = sock;
+
+      const onOpen = (): void => {
+        if (!sock || !isCurrentAttemptSocket(generation, sock)) {
+          clearAttemptTimeout();
+          if (sock && sock.readyState !== WebSocket.CLOSED) {
+            closeSocket(sock);
           }
-          closeHandler?.();
-          scheduleRetry();
-        });
-      });
+          failCurrentAttempt(false);
+          return;
+        }
+
+        clearAttemptTimeout();
+        ws = sock;
+        try {
+          ws.send(JSON.stringify({ id: 0, method: "Target.setDiscoverTargets", params: { discover: true } }));
+        } catch {
+          failCurrentAttempt(true);
+          if (sock.readyState !== WebSocket.CLOSED) {
+            closeSocket(sock);
+          }
+          return;
+        }
+        console.log("[pi-browser-daemon] Connected to Chrome ✓");
+        settleAttempt();
+      };
 
+      const onMessage = (data: WebSocket.Data): void => {
+        if (!sock || !isCurrentAttemptSocket(generation, sock)) return;
+        onChromeMessage(typeof data === "string" ? data : data.toString());
+      };
+
+      const onError = (): void => {
+        clearAttemptTimeout();
+        const notifyClose = !!sock && isCurrentAttemptSocket(generation, sock);
+        failCurrentAttempt(notifyClose);
+        if (sock && sock.readyState !== WebSocket.CLOSED) {
+          closeSocket(sock);
+        }
+      };
+
+      const onClose = (): void => {
+        clearAttemptTimeout();
+        const notifyClose = !!sock && isCurrentAttemptSocket(generation, sock);
+        failCurrentAttempt(notifyClose);
+      };
+
+      sock.on("open", onOpen);
+      sock.on("message", onMessage);
+      sock.on("error", onError);
+      sock.on("close", onClose);
+
+      // The promise must always settle even on constructor errors.
       await settledPromise;
-      if (!ws || ws.readyState !== WebSocket.OPEN) {
-        scheduleRetry();
-      }
     };
 
-    attempt().catch(() => scheduleRetry());
-  };
-
-  const scheduleRetry = (): void => {
-    if (stopped) return;
-    const delay = Math.min(1000 * Math.pow(2, Math.min(reconnectAttempt, 6)), 60_000);
-    reconnectAttempt++;
-    wsUrl = null;
-    reconnectTimer = setTimeout(tryConnect, delay);
+    attempt().catch(() => {
+      if (isCurrentAttempt(generation)) {
+        connecting = false;
+      }
+    });
   };
 
   const start = async (): Promise<void> => {
@@ -296,22 +421,51 @@ export const createCdpBridge = (): CdpBridge => {
 
   const stop = async (): Promise<void> => {
     stopped = true;
-    if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
-    mux.takeAll();
-    signalConnected();
-    if (ws) { try { ws.close(1000, "Shutdown"); } catch {} ws = null; }
+    attemptGeneration += 1;
+    activeAttempt = 0;
+    activeSocket = null;
+    connecting = false;
+    rejectAllPendingCallbacks();
+    if (ws) {
+      try {
+        ws.close(1000, "Shutdown");
+      } catch {}
+      ws = null;
+    }
     wsUrl = null;
   };
 
+  const waitForConnection = async (): Promise<boolean> => {
+    const deadline = Date.now() + connectTimeoutMs;
+    while (connecting && Date.now() < deadline) {
+      if (ws && ws.readyState === WebSocket.OPEN) return true;
+      await new Promise((r) => setTimeout(r, 5));
+    }
+    return ws !== null && ws.readyState === WebSocket.OPEN;
+  };
+
   const handleRequest = async (
     req: WireRequest,
     clientId: string,
     send: SendToClient,
   ): Promise<void> => {
-    // Every queued request awaits the same connect signal rather than each spinning its own poll loop.
-    if (!ws || ws.readyState !== WebSocket.OPEN) await waitForConnection(CONNECT_WAIT_MS);
+    let activeSocket = ws;
+    if (!activeSocket || activeSocket.readyState !== WebSocket.OPEN) {
+      // Connection attempts happen only in response to explicit browser work.
+      tryConnect();
+      const ready = await waitForConnection();
+      if (!ready) {
+        send(clientId, {
+          type: "response",
+          id: req.id,
+          error: { code: -32000, message: "Chrome not connected" },
+        });
+        return;
+      }
+    }
 
-    if (!ws || ws.readyState !== WebSocket.OPEN) {
+    activeSocket = ws;
+    if (!activeSocket || activeSocket.readyState !== WebSocket.OPEN) {
       send(clientId, {
         type: "response",
         id: req.id,
@@ -323,11 +477,14 @@ export const createCdpBridge = (): CdpBridge => {
     const isDetach = req.method === "Target.detachFromTarget";
     if (isDetach && req.sessionId) router.release(req.sessionId);
 
+    const isAttach = req.method === "Target.attachToTarget";
+
     const daemonId = mux.allocate(
-      { clientId, localId: req.id, send, isAttach: req.method === "Target.attachToTarget" },
+      { clientId, localId: req.id, send, isAttach },
       (id) =>
         setTimeout(() => {
           mux.take(id);
+          generations.delete(id);
           send(clientId, {
             type: "response",
             id: req.id,
@@ -335,6 +492,7 @@ export const createCdpBridge = (): CdpBridge => {
           });
         }, CDP_COMMAND_TIMEOUT_MS),
     );
+    generations.set(daemonId, { generation: attemptGeneration, clientId });
 
     const payload: Record<string, unknown> = {
       id: daemonId,
@@ -344,9 +502,10 @@ export const createCdpBridge = (): CdpBridge => {
     if (req.sessionId) payload["sessionId"] = req.sessionId;
 
     try {
-      ws.send(JSON.stringify(payload));
+      activeSocket.send(JSON.stringify(payload));
     } catch (e) {
       mux.take(daemonId);
+      generations.delete(daemonId);
       send(clientId, {
         type: "response",
         id: req.id,
@@ -361,7 +520,11 @@ export const createCdpBridge = (): CdpBridge => {
     handleRequest,
     isAlive: () => ws !== null && ws.readyState === WebSocket.OPEN,
     getSessionOwner: (sid) => router.getOwner(sid),
-    removeClient: (cid) => { mux.clearClient(cid); router.removeClient(cid); },
+    removeClient: (cid) => {
+      rejectCallbacksWhere((info) => info.clientId === cid);
+      mux.clearClient(cid);
+      router.removeClient(cid);
+    },
     onEvent: (h) => { eventHandler = h; },
     onClose: (h) => { closeHandler = h; },
   };

package/src/daemon/spawn.ts

@@ -1,6 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
+import { accessSync } from "node:fs";
 import { access, unlink } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { createConnection } from "node:net";
@@ -8,6 +9,8 @@ import { DAEMON_SOCKET_PATH, serialize, type WireControl } from "./protocol";
 
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 
+const requireFromHere = createRequire(import.meta.url);
+
 const isWindows = process.platform === "win32";
 
 // No-op on Windows: a named pipe is not a filesystem entry and unlinking a pipe path throws.
@@ -78,28 +81,83 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
   });
 };
 
-export const spawnDaemon = (): ChildProcess | null => {
-  const daemonScript = join(moduleDir, "index.ts");
+// Walks upward like Node's own node_modules lookup. Exported with an injectable start so the
+// hoisted layout pi uses can be exercised against a fixture instead of this checkout.
+export const resolveTsxCliFromFilesystem = (startDir: string = moduleDir): string | null => {
+  let dir = startDir;
+
+  while (true) {
+    const candidate = join(dir, "node_modules", "tsx", "dist", "cli.mjs");
+    try {
+      accessSync(candidate);
+      return candidate;
+    } catch {
+      // Keep walking toward the filesystem root. This mirrors Node's node_modules lookup
+      // without relying on createRequire().resolve(), which is broken for external modules
+      // loaded through jiti/static inside a Bun-compiled executable such as pi.exe.
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+};
 
-  // Windows npm binaries are `.cmd` shims, which only launch through a shell — spawning one directly yields EINVAL.
-  const tsxBinBase = join(moduleDir, "..", "..", "node_modules", ".bin", "tsx");
-  const tsxBin = isWindows ? `${tsxBinBase}.cmd` : tsxBinBase;
-  const hasLocalTsx = existsSync(tsxBin);
+const resolveTsxCli = (): string | null => {
+  try {
+    const resolved = requireFromHere.resolve("tsx/cli");
+    // A compiled runtime may theoretically return a virtual path that a separately spawned
+    // Node process cannot read. Only accept a resolver result that exists on the host FS.
+    accessSync(resolved);
+    return resolved;
+  } catch {
+    return resolveTsxCliFromFilesystem();
+  }
+};
 
-  const cmd = hasLocalTsx ? tsxBin : isWindows ? "npx.cmd" : "npx";
-  const args = hasLocalTsx ? [daemonScript] : ["tsx", daemonScript];
+export const daemonNodeExecutable = (
+  env: NodeJS.ProcessEnv = process.env,
+  versions: Readonly<Record<string, string | undefined>> = process.versions,
+  platform: NodeJS.Platform = process.platform,
+  execPath: string = process.execPath,
+): string => {
+  const override = env["PI_BROWSER_NODE"];
+  if (override) return override;
 
-  // With shell: true Node passes the command line verbatim, so a path containing spaces must be quoted or it splits into tokens.
-  const quote = (s: string): string => (isWindows ? `"${s}"` : s);
+  // Under normal Node keep the exact executable that launched pi/the extension. Under Bun,
+  // process.execPath is bun/pi.exe, not Node, so run the tsx CLI with the required Node runtime.
+  if ("bun" in versions) return platform === "win32" ? "node.exe" : "node";
 
-  const child = spawn(quote(cmd), args.map(quote), {
+  return execPath;
+};
+
+export const daemonSpawnCommand = (): { readonly command: string; readonly args: ReadonlyArray<string> } | null => {
+  const daemonScript = join(moduleDir, "index.ts");
+  const tsxCli = resolveTsxCli();
+  if (!tsxCli) return null;
+
+  return {
+    command: daemonNodeExecutable(),
+    args: [tsxCli, daemonScript],
+  };
+};
+
+export const spawnDaemon = (): ChildProcess | null => {
+  const spec = daemonSpawnCommand();
+  if (!spec) return null;
+
+  const child = spawn(spec.command, [...spec.args], {
     detached: true,
     stdio: "ignore",
     env: { ...process.env },
-    shell: isWindows,
-    windowsVerbatimArguments: isWindows,
+    windowsHide: true,
   });
 
+  // `spawn` reports a missing executable (a bare `node` that is not on PATH under a Bun host)
+  // asynchronously via `error`; without a listener that is an uncaught exception in pi.
+  // ensureDaemon's poll loop reports the failure as a timeout, which is what the user sees.
+  child.on("error", () => {});
+
   child.unref();
   return child;
 };

package/src/daemon/transport.ts

@@ -13,7 +13,7 @@ import {
   serialize,
 } from "./protocol";
 
-export const createDaemonTransport = (clientId: string): CdpTransport => {
+export const createDaemonTransport = (clientId: string, socketPath: string = DAEMON_SOCKET_PATH): CdpTransport => {
   let socket: Socket | null = null;
   let rl: ReturnType<typeof createInterface> | null = null;
   let queue = makeEventQueue();
@@ -51,12 +51,17 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
 
       let sock: Socket;
       try {
-        sock = createConnection(DAEMON_SOCKET_PATH);
+        sock = createConnection(socketPath);
       } catch (e) {
         settle(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e))));
         return;
       }
       socket = sock;
+      // The client is kept connected across sessions on purpose (index.ts session_shutdown), so this
+      // socket must not be what keeps the process alive: in `pi -p` it was the last handle standing
+      // and pi never exited (#39). In-flight requests hold their own ref'd timers, so nothing a
+      // caller is awaiting can be dropped by this.
+      sock.unref();
 
       const connectTimer = setTimeout(() => {
         cleanup("Connection timeout");

package/src/domains/click.ts

@@ -58,11 +58,6 @@ export const clickTool = defineBrowserTool({
     "Click an element. PREFERRED: pass `ref` (e.g. 'e12') from browser_snapshot — it re-resolves the element's position at click time, so it works even after the page re-renders and moves things. Fallback: pass viewport CSS-pixel `x`/`y`. Compositor-level click works through iframes, shadow DOM, and cross-origin content. After clicking, a compact diff of page changes is appended.",
   promptSnippet: "Click an element by ref (preferred) or pixel coordinates",
   promptGuidelines: [
-    "PREFER `ref` from browser_snapshot (the outline shows '[eN]' for every interactive element) — it survives re-renders, unlike coordinates which go stale after a save/edit reflows the page.",
-    "Fallback: pass (x, y) from the snapshot's '@(x,y)' hint when there's no ref.",
-    "A 'ref is stale' error means the page changed — re-run browser_snapshot to get fresh refs.",
-    "After clicking, read the appended page-changes diff to confirm the action landed before moving on (no separate snapshot needed for a quick check).",
-    "Coordinates are viewport CSS pixels (not device pixels). Compositor-level clicks pass through iframes, shadow DOM, and cross-origin content.",
     "If a click doesn't register, run pi with --browser-debug-clicks (or set BH_DEBUG_CLICKS=1) to get annotated screenshots. For React/Vue components ignoring clicks, try browser_dispatch_key.",
   ],
   parameters: ClickArgs,

package/src/domains/console.ts

@@ -158,8 +158,6 @@ export const consoleTool = defineBrowserTool({
     "Read JS errors and console messages from the active tab. Diagnostic — use when an action looks broken or silent.",
   promptSnippet: "Read JS errors / console output on the current tab",
   promptGuidelines: [
-    "Use after a click, submit, or navigate produced no visible change — errors often explain it.",
-    "Pass `sinceSeq` from the previous call's `nextCursor` to see only new messages after an action.",
     "Buffer is reset on tab switch (capacity 500 records). bufferOverflowed:true means older entries were dropped.",
     "Don't use as a default observation tool — prefer browser_snapshot for page structure.",
   ],