pi-browser-harness 0.8.1 → 0.9.0

package/src/client.ts

@@ -16,10 +16,12 @@ export type BrowserClientOptions = {
   readonly initialOwnership?: {
     readonly ownedTargetIds?: ReadonlyArray<string>;
     readonly harnessWindowTargetId?: string;
+    readonly harnessWindowId?: number;
   };
   readonly onOwnershipChange?: (snapshot: {
     readonly ownedTargetIds: ReadonlyArray<string>;
     readonly harnessWindowTargetId: string | undefined;
+    readonly harnessWindowId: number | undefined;
   }) => void;
 };
 
@@ -32,6 +34,9 @@ export type BrowserClient = {
   /** Detach from the current page target (removes the "Chrome is being controlled" banner)
    *  while keeping the transport connection alive. Call on session shutdown. */
   detach(): Promise<void>;
+  /** Close every tab this session owns and clear the window binding. Best-effort —
+   *  used on session shutdown so no stale harness tabs survive. */
+  closeOwnedTabs(): Promise<void>;
   evaluateJs(expression: string, sessionId?: string): Promise<Result<unknown, CdpError>>;
   pageInfo(): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>>;
   takeDialog(): DialogInfo | null;
@@ -82,13 +87,16 @@ const parsePageInfoPayload = (v: unknown): Result<PageInfo, CdpError> => {
 
 export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient => {
   const transport = opts.transport ?? createCdpTransport();
-  const ownershipInit: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string } = {};
+  const ownershipInit: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string; harnessWindowId?: number } = {};
   if (opts.initialOwnership?.ownedTargetIds !== undefined) {
     ownershipInit.ownedTargetIds = opts.initialOwnership.ownedTargetIds;
   }
   if (opts.initialOwnership?.harnessWindowTargetId !== undefined) {
     ownershipInit.harnessWindowTargetId = opts.initialOwnership.harnessWindowTargetId;
   }
+  if (opts.initialOwnership?.harnessWindowId !== undefined) {
+    ownershipInit.harnessWindowId = opts.initialOwnership.harnessWindowId;
+  }
   const ownership = createOwnershipRegistry(ownershipInit);
   if (opts.onOwnershipChange) {
     const cb = opts.onOwnershipChange;
@@ -96,6 +104,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
       cb({
         ownedTargetIds: ownership.list(),
         harnessWindowTargetId: ownership.harnessWindow(),
+        harnessWindowId: ownership.harnessWindowId(),
       });
     });
   }
@@ -256,6 +265,15 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return ok(undefined);
   };
 
+  // Ask Chrome for the real windowId hosting a target. Undefined on failure —
+  // callers treat the window binding as best-effort.
+  const getWindowId = async (targetId: string): Promise<number | undefined> => {
+    const r = await session.callBrowser("Browser.getWindowForTarget", { targetId });
+    if (!r.success) return undefined;
+    const wid = (r.data as { windowId?: number }).windowId;
+    return typeof wid === "number" ? wid : undefined;
+  };
+
   const newTab = async (url?: string): Promise<Result<string, CdpError>> => {
     // Verify the recorded harness window still exists. Querying the live
     // target list also gives listTabs's reconciliation a chance to run.
@@ -263,22 +281,35 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     if (!tabsResult.success) return tabsResult;
     const live = new Set(tabsResult.data.map((t) => t.targetId));
     const hw = ownership.harnessWindow();
+    // Pick an opener that keeps us inside the harness window. Prefer the seed
+    // tab; if the user closed it but other owned tabs survive, reuse one of
+    // those instead of spawning a second window (avoids window scatter).
+    const opener = hw && live.has(hw)
+      ? hw
+      : ownership.list().find((id) => live.has(id));
 
     const params: Record<string, unknown> = { url: "about:blank" };
-    if (hw && live.has(hw)) {
-      // Open as a child of the harness window's seed tab — Chrome places
-      // it in the same window, giving us visual grouping for free.
-      params["openerId"] = hw;
+    if (opener) {
+      // Open as a child of an owned tab — Chrome places it in the same window,
+      // giving us visual grouping for free and keeping the session single-window.
+      params["openerId"] = opener;
     } else {
-      // Either fresh session or the harness window was closed by the user.
-      // Spawn a new dedicated window.
+      // Fresh session, or the whole harness window was closed by the user.
+      // Spawn a new dedicated window and rebind to it.
       params["newWindow"] = true;
     }
     const created = await session.callBrowser("Target.createTarget", params);
     if (!created.success) return created;
     const c = created.data as { targetId: string };
 
-    if (params["newWindow"]) ownership.setHarnessWindow(c.targetId);
+    if (params["newWindow"]) {
+      ownership.setHarnessWindow(c.targetId);
+      const wid = await getWindowId(c.targetId);
+      if (wid !== undefined) ownership.setHarnessWindowId(wid);
+    } else if (opener && opener !== hw) {
+      // Re-seeded onto a surviving owned tab; keep the seed pointer live.
+      ownership.setHarnessWindow(opener);
+    }
     ownership.add(c.targetId);
 
     const switched = await switchTab(c.targetId);
@@ -297,6 +328,18 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return ok(undefined);
   };
 
+  const closeOwnedTabs = async (): Promise<void> => {
+    // Snapshot first — remove() mutates the list, and targetDestroyed events
+    // may also prune concurrently. Failures are swallowed: a tab the user
+    // already closed, or a dead transport, must not block shutdown.
+    for (const id of ownership.list()) {
+      await session.callBrowser("Target.closeTarget", { targetId: id }).catch(() => {});
+      ownership.remove(id);
+    }
+    ownership.setHarnessWindow(undefined);
+    ownership.setHarnessWindowId(undefined);
+  };
+
   const status = (): DaemonStatus => ({
     alive: transport.state() === "open" && session.current() !== null,
     sessionId: session.current()?.sessionId ?? null,
@@ -316,7 +359,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
 
   return {
     namespace: opts.namespace,
-    ensureAlive, status, start, stop, detach,
+    ensureAlive, status, start, stop, detach, closeOwnedTabs,
     evaluateJs, pageInfo,
     takeDialog: () => session.takeDialog(),
     listTabs, switchTab, newTab, closeTab,

package/src/daemon/bridge.ts

@@ -29,7 +29,7 @@ export type CdpBridge = {
    *  are initialized (not when Chrome is connected — that may take retries). */
   start(): Promise<void>;
   stop(): Promise<void>;
-  handleRequest(req: WireRequest, clientId: string, send: SendToClient): void;
+  handleRequest(req: WireRequest, clientId: string, send: SendToClient): Promise<void>;
   /** True when the Chrome WebSocket is open and ready. */
   isAlive(): boolean;
   recordSession(clientId: string, sessionId: string): void;
@@ -339,11 +339,21 @@ export const createCdpBridge = (): CdpBridge => {
     wsUrl = null;
   };
 
-  const handleRequest = (
+  const handleRequest = async (
     req: WireRequest,
     clientId: string,
     send: SendToClient,
-  ): void => {
+  ): Promise<void> => {
+    // ponytail: wait for Chrome to connect (user may still be clicking "Allow").
+    // Bridge retries in background; this polls so the client doesn't fail first try.
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+      const deadline = Date.now() + 15_000;
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 250));
+        if (ws && ws.readyState === WebSocket.OPEN) break;
+      }
+    }
+
     if (!ws || ws.readyState !== WebSocket.OPEN) {
       send(clientId, {
         type: "response",

package/src/daemon/protocol.ts

@@ -133,8 +133,18 @@ export const deserialize = (line: string): WireMessage | null => {
 
 // ── Constants ──────────────────────────────────────────────────────────────────
 
-/** Filesystem path for the daemon's Unix domain socket. */
-export const DAEMON_SOCKET_PATH = "/tmp/pi-browser-daemon.sock";
+/**
+ * IPC endpoint for the daemon.
+ *
+ * On POSIX platforms this is a Unix domain socket path. On Windows, Node's IPC
+ * requires a named pipe of the form `\\.\pipe\<name>` — a Unix path like
+ * `/tmp/…` is not a valid `net` listen/connect target there and causes setup
+ * to fail. See https://nodejs.org/api/net.html#ipc-support.
+ */
+export const DAEMON_SOCKET_PATH =
+  process.platform === "win32"
+    ? "\\\\.\\pipe\\pi-browser-daemon"
+    : "/tmp/pi-browser-daemon.sock";
 
 /**
  * How long the daemon stays alive with zero connected clients before exiting

package/src/daemon/spawn.ts

@@ -10,25 +10,94 @@
  */
 
 import { spawn, type ChildProcess } from "node:child_process";
-import { access } from "node:fs/promises";
+import { access, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { DAEMON_SOCKET_PATH } from "./protocol";
+import { createConnection } from "node:net";
+import { DAEMON_SOCKET_PATH, serialize, type WireControl } from "./protocol";
 
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 
+const isWindows = process.platform === "win32";
+
 /**
- * Check whether the daemon is running by testing if its Unix socket exists.
- * The socket file is created by the daemon on startup and removed on shutdown.
+ * Remove a stale POSIX socket file. On Windows the daemon endpoint is a named
+ * pipe, which is not a filesystem entry and is torn down automatically when the
+ * owning process exits — so there is nothing to unlink, and calling unlink on a
+ * pipe path throws. This is a no-op on Windows.
  */
-export const isDaemonRunning = async (): Promise<boolean> => {
-  try {
-    await access(DAEMON_SOCKET_PATH);
-    return true;
-  } catch {
-    return false;
+const cleanupStaleSocket = (): void => {
+  if (isWindows) return;
+  unlink(DAEMON_SOCKET_PATH).catch(() => {});
+};
+
+/**
+ * Check whether the daemon is running by probing its Unix socket.
+ * A file-existence check is unreliable — a crashed daemon leaves a stale socket.
+ * We connect, send a register, wait for the registered ack, then disconnect.
+ * On failure, clean up the stale socket so ensureDaemon can spawn a fresh one.
+ */
+export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
+  // On POSIX, a missing socket file means the daemon definitely isn't running,
+  // so we can short-circuit. Windows named pipes are not filesystem entries —
+  // access() always fails there — so skip the pre-check and probe directly.
+  if (!isWindows) {
+    try {
+      await access(DAEMON_SOCKET_PATH);
+    } catch {
+      return false;
+    }
   }
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (alive: boolean): void => {
+      if (settled) return;
+      settled = true;
+      resolve(alive);
+    };
+
+    const sock = createConnection(DAEMON_SOCKET_PATH);
+    const timer = setTimeout(() => {
+      sock.destroy();
+      // ponytail: stale socket cleanup; ENOENT = already gone, fine
+      cleanupStaleSocket();
+      done(false);
+    }, timeoutMs);
+
+    sock.on("connect", () => {
+      const regMsg: WireControl = { type: "control", action: "register", clientId: "_liveness_probe" };
+      sock.write(serialize(regMsg) + "\n");
+    });
+
+    sock.on("data", (chunk: Buffer) => {
+      const text = chunk.toString();
+      if (text.includes('"registered"')) {
+        clearTimeout(timer);
+        // Send deregister so the probe doesn't hog a slot
+        const deregMsg: WireControl = { type: "control", action: "deregister", clientId: "_liveness_probe" };
+        try { sock.write(serialize(deregMsg) + "\n"); } catch {}
+        sock.destroy();
+        done(true);
+      }
+    });
+
+    sock.on("error", () => {
+      clearTimeout(timer);
+      sock.destroy();
+      // ponytail: connection refused = daemon dead, clean up stale socket
+      cleanupStaleSocket();
+      done(false);
+    });
+
+    // close without 'registered' ack = daemon alive but rejected us (e.g. max clients);
+    // don't unlink — the daemon is still using that socket.
+    sock.on("close", () => {
+      clearTimeout(timer);
+      done(false);
+    });
+  });
 };
 
 /**
@@ -44,18 +113,34 @@ export const isDaemonRunning = async (): Promise<boolean> => {
 export const spawnDaemon = (): ChildProcess | null => {
   // Resolve the daemon entry point and tsx binary.
   const daemonScript = join(moduleDir, "index.ts");
-  const tsxBin = join(moduleDir, "..", "..", "node_modules", ".bin", "tsx");
 
-  // Use tsx to run the daemon TypeScript source directly.
-  // The spawed process inherits the parent's env so module resolution works.
+  // On Windows, npm installs binaries as `.cmd` shims, not bare executables,
+  // and the npx fallback is `npx.cmd`. A `.cmd` file can only be launched
+  // through a shell (spawning it directly yields EINVAL), so set shell: true
+  // whenever we invoke one.
+  const tsxBinBase = join(moduleDir, "..", "..", "node_modules", ".bin", "tsx");
+  const tsxBin = isWindows ? `${tsxBinBase}.cmd` : tsxBinBase;
+  const hasLocalTsx = existsSync(tsxBin);
+
+  // Use the local tsx binary to run the daemon TypeScript source directly.
+  // The spawned process inherits the parent's env so module resolution works.
   // Fall back to `npx tsx` if the local binary isn't available.
-  const cmd = existsSync(tsxBin) ? tsxBin : "npx";
-  const args = existsSync(tsxBin) ? [daemonScript] : ["tsx", daemonScript];
+  const cmd = hasLocalTsx ? tsxBin : isWindows ? "npx.cmd" : "npx";
+  const args = hasLocalTsx ? [daemonScript] : ["tsx", daemonScript];
+
+  // With shell: true, Node passes the command line to the shell verbatim
+  // without quoting, so any path containing spaces (e.g. C:\Users\Some Name)
+  // would be split into multiple tokens. Wrap each token in double quotes on
+  // Windows to keep space-containing paths intact.
+  const quote = (s: string): string => (isWindows ? `"${s}"` : s);
 
-  const child = spawn(cmd, args, {
+  const child = spawn(quote(cmd), args.map(quote), {
     detached: true,
     stdio: "ignore",
     env: { ...process.env },
+    // `.cmd` shims (local tsx or npx.cmd on Windows) must run via a shell.
+    shell: isWindows,
+    windowsVerbatimArguments: isWindows,
   });
 
   child.unref();

package/src/deep-research.ts

@@ -0,0 +1,41 @@
+/**
+ * Deep research — the /deep-research slash command. An explicit entry point
+ * (alongside the auto-triggering deep-research skill) that kicks off a research
+ * run for a given question.
+ *
+ * The command is thin: it validates a non-empty question and injects a user
+ * message that starts the deep-research flow. The actual orchestration
+ * (decompose → fan out web-search-researcher subagents → synthesize a cited
+ * report) lives in skills/deep-research/SKILL.md, which the injected prompt
+ * triggers. pi.sendUserMessage always starts a turn.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// ── Shared core: build the prompt that starts a deep-research run ───────────
+
+export function buildDeepResearchPrompt(question: string): string {
+  return (
+    `Do deep research on the following question and produce a cited Markdown report. ` +
+    `Use the deep-research skill: decompose it into sub-questions, fan out web-search-researcher ` +
+    `subagents to research each against the live web, then synthesize a source-cited report file.\n\n` +
+    `Question: ${question}`
+  );
+}
+
+// ── Public: register the /deep-research slash command ──────────────────────
+
+export function registerDeepResearchCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("deep-research", {
+    description: "Research a question on the web and write a cited report",
+    handler: async (args, ctx) => {
+      const question = args.trim();
+      if (question.length === 0) {
+        ctx.ui.notify('Usage: /deep-research <question>. Example: /deep-research "compare CDP vs WebDriver"', "warning");
+        return;
+      }
+      ctx.ui.notify(`Starting deep research: ${question}`, "info");
+      pi.sendUserMessage(buildDeepResearchPrompt(question));
+    },
+  });
+}