pi-browser-harness 0.4.0 → 0.6.0

package/src/prompt.ts

@@ -36,6 +36,7 @@ to interact with pages visually, and other tools alongside them.
 | browser_switch_tab | Switch to a different tab by targetId |
 | browser_execute_js | Execute JavaScript and return the result |
 | browser_http_get | Direct HTTP GET (outside browser, for APIs) |
+| browser_console | Read JS errors / console output on the current tab (diagnostic — use when an action looks broken; pass sinceSeq from the previous nextCursor to see only new messages) |
 | browser_wait | Wait N seconds |
 | browser_wait_for_load | Wait for document.readyState === 'complete' (returns a typed timeout error if the page doesn't reach readyState=complete in N seconds, default 15) |
 | browser_handle_dialog | Accept or dismiss a JS dialog |
@@ -73,6 +74,8 @@ browser_screenshot() + browser_page_info() + browser_execute_js("document.title"
 browser_http_get("https://api.example.com/data") + browser_click(x, y)
 \`\`\`
 
+**Multi-agent note**: When multiple subagents use the browser, tab switching by one agent changes the active tab for all agents. Per-tab data (console buffers, network traces, dialogs, page info cache) is isolated — switching tabs does not destroy another agent's collected data. Call \`browser_current_tab\` before mutation tools to confirm you're on the expected tab. If \`browser_page_info\` returns a dialog, handle it with \`browser_handle_dialog\` promptly — dialogs block page interaction and are not queued across agents.
+
 ### Common Patterns
 
 **Navigation:**

package/src/registry.ts

@@ -14,13 +14,17 @@ import { uploadFileTool, downloadTool, printToPdfTool } from "./domains/files";
 import { viewportResizeTool } from "./domains/viewport";
 import { dragAndDropTool } from "./domains/drag";
 import { httpGetTool, networkRequestsTool } from "./domains/network";
+import { consoleTool } from "./domains/console";
 import { snapshotTool } from "./domains/snapshot";
 import { executeJsTool, runScriptTool } from "./domains/js";
+import { setupTool } from "./domains/setup";
 
 // Mutation tools that modify page / browser state are marked `serialized: true`
 // so they run through a shared async mutex.  Observation / read-only tools are
 // left unmarked and can execute in parallel.
 const TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
+  // setup comes first — the agent calls this to self-recover from not-initialized
+  setupTool,
   { ...clickTool, serialized: true },
   { ...typeTool, serialized: true },
   { ...pressKeyTool, serialized: true },
@@ -48,6 +52,7 @@ const TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
   { ...dragAndDropTool, serialized: true },
   httpGetTool,
   networkRequestsTool,
+  consoleTool,
   snapshotTool,
   executeJsTool,
   runScriptTool,

package/src/setup.ts

@@ -1,37 +1,50 @@
 /**
- * Setup command — verifies Chrome is running with remote debugging
- * and connects the pi agent to it.
+ * Setup — verifies Chrome is running with remote debugging and connects
+ * the pi agent to it. Exposed as both a slash command (/browser-setup) for
+ * users and a tool (browser_setup) for the agent to self-recover.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { execSync } from "node:child_process";
 import type { BrowserClient } from "./client";
+import { ensureDaemon } from "./daemon/spawn";
+
+// ── Public: register the /browser-setup slash command ──────────────────────
 
 export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient): void {
   pi.registerCommand("browser-setup", {
     description: "Connect pi to your Chrome browser",
     handler: async (_args, ctx) => {
-      await runSetup(ctx, client);
+      const result = await performSetup(client);
+      if (result.success) {
+        ctx.ui.notify(result.data, "info");
+      } else {
+        ctx.ui.notify(result.error, "error");
+      }
     },
   });
 }
 
-async function runSetup(ctx: ExtensionContext, client: BrowserClient): Promise<void> {
-  ctx.ui.notify("browser setup: checking Chrome...", "info");
+// ── Shared setup result ────────────────────────────────────────────────────
+
+export type SetupResult = { success: true; data: string } | { success: false; error: string };
+
+// ── Shared setup logic (used by both the command and the tool) ─────────────
 
+export async function performSetup(client: BrowserClient): Promise<SetupResult> {
   // Step 1: Check Chrome is running
   const chromeRunning = checkChromeRunning();
   if (!chromeRunning) {
-    ctx.ui.notify(
-      "No browser instance running. Please open your browser and then run /browser-setup.",
-      "error",
-    );
-    return;
+    return { success: false, error: "No browser instance running. Please open your browser and then run /browser-setup." };
   }
-  ctx.ui.notify("Chrome is running ✓", "info");
 
-  // Step 2: Try to connect to Chrome DevTools
-  ctx.ui.notify("Connecting to Chrome DevTools...", "info");
+  // Step 2: Start the browser daemon (spawns if not running, silently reuses if alive)
+  const daemonReady = await ensureDaemon();
+  if (!daemonReady) {
+    return { success: false, error: "Could not start the browser daemon. Check /tmp/pi-browser-daemon.sock." };
+  }
+
+  // Step 3: Connect to Chrome DevTools
   const startResult = await client.start();
   if (!startResult.success) {
     const msg = startResult.error.message;
@@ -43,30 +56,23 @@ async function runSetup(ctx: ExtensionContext, client: BrowserClient): Promise<v
       lower.includes("econnrefused") ||
       lower.includes("cannot reach chrome devtools")
     ) {
-      ctx.ui.notify(
-        "Chrome remote debugging needs to be enabled.\n\n" +
-          "Open chrome://inspect/#remote-debugging in your browser, tick the\n" +
-          "\"Discover network targets\" / Allow checkbox, then run /browser-setup again.\n\n" +
+      return {
+        success: false,
+        error:
+          "Chrome remote debugging needs to be enabled.\n\n" +
+          'Open chrome://inspect/#remote-debugging in your browser, tick the\n' +
+          '"Discover network targets" / Allow checkbox, then retry.\n\n' +
           "Or set BU_CDP_WS to a remote browser WebSocket URL.",
-        "warning",
-      );
-      return;
+      };
     }
 
-    ctx.ui.notify(`Connection failed: ${msg}`, "error");
-    return;
+    return { success: false, error: `Connection failed: ${msg}` };
   }
-  ctx.ui.notify("Connected to Chrome ✓", "info");
 
-  // Step 3: Verify with test navigation
-  ctx.ui.notify("Testing browser control...", "info");
+  // Step 4: Verify with test navigation
   const tabResult = await client.newTab("https://github.com");
   if (!tabResult.success) {
-    ctx.ui.notify(
-      `Browser connected but test navigation failed: ${tabResult.error.message}`,
-      "warning",
-    );
-    return;
+    return { success: false, error: `Browser connected but test navigation failed: ${tabResult.error.message}` };
   }
 
   const info = await client.pageInfo();
@@ -75,24 +81,24 @@ async function runSetup(ctx: ExtensionContext, client: BrowserClient): Promise<v
   }
 
   const pageUrl = info.success && !("dialog" in info.data) ? info.data.url : "github.com";
-  ctx.ui.notify(`Browser control verified ✓\nNavigated to: ${pageUrl}`, "info");
+  return { success: true, data: `Browser connected ✓\nNavigated to: ${pageUrl}` };
 }
 
+// ── Chrome process detection ───────────────────────────────────────────────
+
 function checkChromeRunning(): boolean {
   try {
     if (process.platform === "darwin") {
-      // Exact line matching — excludes "Google Chrome Helper" etc.
-      // that linger after the user quits the browser.
+      // ps -o comm= returns the full executable path on modern macOS.
+      // We check for "Google Chrome" anywhere in the path (case-insensitive),
+      // excluding helper/renderer subprocesses.
       const out = execSync("ps -A -o comm=", { timeout: 5000 }).toString().toLowerCase();
       const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
-      const browserProcesses = ["google chrome", "chromium", "microsoft edge"];
       return lines.some((l) => {
-        if (l.includes("helper") || l.includes("renderer")) return false;
-        return browserProcesses.includes(l);
+        if (l.includes("helper") || l.includes("renderer") || l.includes("crashpad")) return false;
+        return l.includes("google chrome") || l.includes("chromium") || l.includes("microsoft edge");
       });
     } else if (process.platform === "linux") {
-      // Use args to distinguish the main browser process from sub-processes
-      // (GPU, renderer, utility, etc.) which carry --type= flags.
       const out = execSync("ps -A -o comm=,args=", { timeout: 5000 }).toString().toLowerCase();
       const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
       const browserComms = ["chrome", "chromium", "chromium-browser", "msedge", "microsoft-edge", "google-chrome"];

package/src/util/tool.ts

@@ -9,6 +9,8 @@ import type {
   ToolRenderResultOptions,
 } from "@mariozechner/pi-coding-agent";
 import type { Component } from "@mariozechner/pi-tui";
+import { access } from "node:fs/promises";
+import { DAEMON_SOCKET_PATH } from "../daemon/protocol";
 import type { BrowserClient } from "../client";
 import type { Result } from "./result";
 
@@ -142,6 +144,23 @@ export const registerBrowserTool = (
       : {}),
     async execute(_toolCallId, args, signal, onUpdate, extensionCtx) {
       if (def.ensureAlive !== false) {
+        // Check daemon socket exists before attempting browser control.
+        // If missing, the user hasn't run /browser-setup yet. Return a clear
+        // error so the agent knows to direct the user to initialize.
+        try {
+          await access(DAEMON_SOCKET_PATH);
+        } catch {
+          return toToolResult(
+            {
+              success: false,
+              error: {
+                kind: "not_connected",
+                message: "Browser harness not initialized. Run /browser-setup first",
+              },
+            },
+            def.name,
+          );
+        }
         const alive = await client.ensureAlive();
         if (!alive.success) {
           return toToolResult(