pi-browser-harness 0.3.1 → 0.4.0

package/src/prompt.ts

@@ -21,7 +21,7 @@ to interact with pages visually, and other tools alongside them.
 
 | Tool | Purpose |
 |------|---------|
-| browser_screenshot | Capture a PNG screenshot of the current page (result details include path and attached: false — the LLM reads the image via the saved file path) |
+| browser_screenshot | Capture a PNG or JPEG screenshot of the current page (rendered inline in the TUI; the LLM reads the image via the saved file path) |
 | browser_click | Click at viewport coordinates |
 | browser_type | Type text into the focused element |
 | browser_press_key | Press a keyboard key (Enter, Tab, Escape, arrows, etc.) |
@@ -63,6 +63,16 @@ browser_run_script("/tmp/scrape-pages.js", { urls: [...] })
 
 Script bindings: params, daemon, require, signal, onUpdate, ctx, console, fetch, JSON, Buffer, setTimeout, clearTimeout.
 
+### Parallel Execution
+
+Observation tools (browser_screenshot, browser_page_info, browser_execute_js, browser_list_tabs, browser_http_get, etc.) can run in parallel with each other and with mutation tools. The harness automatically serializes mutation tools (click, type, scroll, navigate, switch_tab, etc.) so they never race on shared state. When operations are independent, emit them in the same turn for better performance.
+
+**Examples of safe parallel calls:**
+\`\`\`
+browser_screenshot() + browser_page_info() + browser_execute_js("document.title")
+browser_http_get("https://api.example.com/data") + browser_click(x, y)
+\`\`\`
+
 ### Common Patterns
 
 **Navigation:**
@@ -85,9 +95,9 @@ browser_http_get("https://api.example.com/data")
 
 **Scrolling:**
 \`\`\`
-browser_screenshot() → browser_scroll({ deltaY: -500 }) → browser_screenshot()
+browser_screenshot() → browser_scroll({ deltaY: 500 }) → browser_screenshot()
 \`\`\`
-Note: deltaY follows W3C wheel-event convention: positive=up, negative=down. Default deltaY=-300 scrolls down.
+Note: deltaY follows W3C wheel-event convention: positive=down, negative=up. Default deltaY=300 scrolls down.
 
 **Research Workflow (search + browser):**
 \`\`\`

package/src/registry.ts

@@ -9,40 +9,46 @@ import { handleDialogTool } from "./domains/dialog";
 import { screenshotTool } from "./domains/screenshot";
 import { navigateTool, openUrlsTool } from "./domains/navigate";
 import { goBackTool, goForwardTool, reloadTool } from "./domains/history";
-import { listTabsTool, currentTabTool, switchTabTool, newTabTool } from "./domains/tabs";
+import { listTabsTool, currentTabTool, switchTabTool, newTabTool, closeTabTool } from "./domains/tabs";
 import { uploadFileTool, downloadTool, printToPdfTool } from "./domains/files";
 import { viewportResizeTool } from "./domains/viewport";
 import { dragAndDropTool } from "./domains/drag";
-import { httpGetTool, getNetworkLogTool } from "./domains/network";
+import { httpGetTool, networkRequestsTool } from "./domains/network";
+import { snapshotTool } from "./domains/snapshot";
 import { executeJsTool, runScriptTool } from "./domains/js";
 
+// 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> = [
-  clickTool,
-  typeTool,
-  pressKeyTool,
-  dispatchKeyTool,
-  scrollTool,
+  { ...clickTool, serialized: true },
+  { ...typeTool, serialized: true },
+  { ...pressKeyTool, serialized: true },
+  { ...dispatchKeyTool, serialized: true },
+  { ...scrollTool, serialized: true },
   pageInfoTool,
   waitTool,
-  waitForLoadTool,
-  handleDialogTool,
+  { ...waitForLoadTool, serialized: true },
+  { ...handleDialogTool, serialized: true },
   screenshotTool,
-  navigateTool,
-  openUrlsTool,
-  goBackTool,
-  goForwardTool,
-  reloadTool,
+  { ...navigateTool, serialized: true },
+  { ...openUrlsTool, serialized: true },
+  { ...goBackTool, serialized: true },
+  { ...goForwardTool, serialized: true },
+  { ...reloadTool, serialized: true },
   listTabsTool,
   currentTabTool,
-  switchTabTool,
-  newTabTool,
-  uploadFileTool,
-  downloadTool,
-  printToPdfTool,
-  viewportResizeTool,
-  dragAndDropTool,
+  { ...switchTabTool, serialized: true },
+  { ...newTabTool, serialized: true },
+  { ...closeTabTool, serialized: true },
+  { ...uploadFileTool, serialized: true },
+  { ...downloadTool, serialized: true },
+  { ...printToPdfTool, serialized: true },
+  { ...viewportResizeTool, serialized: true },
+  { ...dragAndDropTool, serialized: true },
   httpGetTool,
-  getNetworkLogTool,
+  networkRequestsTool,
+  snapshotTool,
   executeJsTool,
   runScriptTool,
 ];

package/src/setup.ts

@@ -23,7 +23,7 @@ async function runSetup(ctx: ExtensionContext, client: BrowserClient): Promise<v
   const chromeRunning = checkChromeRunning();
   if (!chromeRunning) {
     ctx.ui.notify(
-      "Chrome/Chromium/Edge not detected. Please start your browser and retry /browser-setup.",
+      "No browser instance running. Please open your browser and then run /browser-setup.",
       "error",
     );
     return;
@@ -80,11 +80,29 @@ async function runSetup(ctx: ExtensionContext, client: BrowserClient): Promise<v
 
 function checkChromeRunning(): boolean {
   try {
-    if (process.platform === "darwin" || process.platform === "linux") {
+    if (process.platform === "darwin") {
+      // Exact line matching — excludes "Google Chrome Helper" etc.
+      // that linger after the user quits the browser.
       const out = execSync("ps -A -o comm=", { timeout: 5000 }).toString().toLowerCase();
-      return ["google chrome", "chrome", "chromium", "microsoft edge", "msedge"].some(
-        (n) => out.includes(n),
-      );
+      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);
+      });
+    } 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"];
+      return lines.some((line) => {
+        const parts = line.split(/\s+/);
+        const comm = parts[0] ?? "";
+        if (!comm || !browserComms.includes(comm)) return false;
+        const isSubprocess = line.includes("--type=") && !line.includes("--type=browser");
+        return !isSubprocess;
+      });
     } else if (process.platform === "win32") {
       const out = execSync("tasklist", { timeout: 5000 }).toString().toLowerCase();
       return ["chrome.exe", "msedge.exe"].some((n) => out.includes(n));

package/src/state.ts

@@ -10,9 +10,14 @@ import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-age
 export type BrowserState = {
   readonly namespace: string;
   readonly remoteBrowserId?: string;
+  readonly ownedTargetIds?: ReadonlyArray<string>;
+  readonly harnessWindowTargetId?: string;
 };
 
-export const defaultState = (namespace = "default"): BrowserState => ({ namespace });
+export const defaultState = (namespace = "default"): BrowserState => ({
+  namespace,
+  ownedTargetIds: [],
+});
 
 export const persistState = (pi: ExtensionAPI, state: BrowserState): void => {
   pi.appendEntry<BrowserState>("browser-harness-state", state);

package/src/util/mutex.ts

@@ -0,0 +1,25 @@
+/**
+ * Lightweight async mutex (~10 lines). Acquire returns a release function.
+ * When the mutex is free, acquire() resolves immediately. When held,
+ * callers are queued and execute serially in FIFO order.
+ */
+export type Mutex = {
+  acquire(): Promise<() => void>;
+};
+
+export const createMutex = (): Mutex => {
+  let queue = Promise.resolve<unknown>(undefined);
+
+  return {
+    async acquire(): Promise<() => void> {
+      let release = () => {};
+      const next = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      const prev = queue;
+      queue = prev.then(() => next);
+      await prev;
+      return release;
+    },
+  };
+};

package/src/util/tool.ts

@@ -53,6 +53,10 @@ export type BrowserToolDefinition<S extends TSchema> = {
   readonly handler: ToolHandler<S>;
   readonly renderCall?: (args: Static<S>, theme: Theme) => Component;
   readonly renderResult?: (result: AgentToolResult<unknown>, expanded: boolean, theme: Theme) => Component;
+  /** If true, the tool acquires the client's mutation mutex before executing.
+   *  This ensures that two serialized tools never run concurrently,
+   *  preventing race conditions on shared CDP session/page state. */
+  readonly serialized?: boolean;
   readonly ensureAlive?: boolean;
 };
 
@@ -146,23 +150,43 @@ export const registerBrowserTool = (
           );
         }
       }
-      const result = await def.handler(args, {
-        client,
-        signal,
-        onUpdate: (u) => {
-          if (onUpdate) {
-            // AgentToolUpdateCallback expects AgentToolResult<TDetails>; we use unknown for TDetails.
-            const update: AgentToolResult<OkDetails> = {
-              content: [{ type: "text", text: u.text }],
-              details: { ok: true, ...(u.details ?? {}) },
-            };
-            // Cast needed: onUpdate is AgentToolUpdateCallback<unknown> (generic TDetails).
-            (onUpdate as AgentToolUpdateCallback<OkDetails>)(update);
-          }
-        },
-        extensionCtx,
-      });
-      return toToolResult(result, def.name);
+      // Serialized tools acquire the client's mutation mutex so that only one
+      // mutation tool runs at a time. Observation tools skip this and run freely
+      // in parallel. AbortSignal is checked after acquiring the lock so that a
+      // cancelled task doesn't hold the mutex forever.
+      let release: (() => void) | undefined;
+      if (def.serialized) {
+        const acquire = await client.mutationMutex().acquire();
+        release = acquire;
+        if (signal?.aborted) {
+          release();
+          return toToolResult(
+            { success: false, error: { kind: "invalid_state", message: "Tool execution aborted before entering serialized lane" } },
+            def.name,
+          );
+        }
+      }
+      try {
+        const result = await def.handler(args, {
+          client,
+          signal,
+          onUpdate: (u) => {
+            if (onUpdate) {
+              // AgentToolUpdateCallback expects AgentToolResult<TDetails>; we use unknown for TDetails.
+              const update: AgentToolResult<OkDetails> = {
+                content: [{ type: "text", text: u.text }],
+                details: { ok: true, ...(u.details ?? {}) },
+              };
+              // Cast needed: onUpdate is AgentToolUpdateCallback<unknown> (generic TDetails).
+              (onUpdate as AgentToolUpdateCallback<OkDetails>)(update);
+            }
+          },
+          extensionCtx,
+        });
+        return toToolResult(result, def.name);
+      } finally {
+        release?.();
+      }
     },
   };
   pi.registerTool(td);