pi-browser-harness 0.8.0 → 0.8.3

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.8.1 — 2026-07-05
+
+### Fixed
+
+- **`browser_dispatch_key` now populates `keyCode`/`which`** on the synthesized `KeyboardEvent` (both the ref and selector paths). Legacy React/Vue key handlers commonly branch on `e.keyCode === 13` rather than `e.key`, so Enter on tag/autocomplete inputs previously did nothing. The event remains untrusted (`isTrusted === false`), so a few libraries may still ignore it.
+- **`browser_execute_js` IIFE auto-wrap no longer false-positives.** The wrap now triggers only when the trimmed source *starts with* a `return` statement, instead of whenever the string merely contained the substring `"return "` (which silently turned bare expressions — including ones mentioning `return` inside a string literal or comment — into `undefined`).
+
+### Changed
+
+- **`browser_fill` guidelines** now point at `browser_dispatch_key({ ref, key: 'Enter' })` for submitting tag/autocomplete inputs (not `browser_press_key`, which targets the focused element), and at the open → `browser_snapshot` → `browser_click` recipe for custom (div-based) dropdowns.
+
 ## 0.6.0 — 2026-06-21
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.8.0",
+  "version": "0.8.3",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",

package/src/client.ts

@@ -170,12 +170,14 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
 
   const evaluateJs = async (expression: string, sessionId?: string): Promise<Result<unknown, CdpError>> => {
     // Heuristic IIFE wrap: legacy convenience that lets agents write
-    // `return foo` instead of `(() => foo)()`. False-positive on substring
-    // `"return "` inside string literals or comments — agents that hit this
-    // can pass an explicit IIFE instead.
-    const wrapped = expression.includes("return ") && !expression.trim().startsWith("(")
-      ? `(function(){${expression}})()`
-      : expression;
+    // `return foo` instead of `(() => foo)()`. Only wrap when the trimmed
+    // source *starts with* a return statement — a bare expression, or one that
+    // merely mentions `return` inside a string literal or comment, is passed
+    // through untouched (previously any substring `"return "` triggered a wrap,
+    // silently turning such expressions into `undefined`).
+    const trimmed = expression.trim();
+    const isReturnStatement = /^return[\s(]/.test(trimmed);
+    const wrapped = isReturnStatement ? `(function(){${expression}})()` : expression;
     const r = sessionId
       ? await session.callOnTarget("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true }, sessionId)
       : await session.call("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true });

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/spawn.ts

@@ -10,25 +10,77 @@
  */
 
 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));
 
 /**
- * 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.
+ * 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 (): Promise<boolean> => {
+export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
+  // If the socket file doesn't exist, the daemon definitely isn't running.
   try {
     await access(DAEMON_SOCKET_PATH);
-    return true;
   } 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
+      unlink(DAEMON_SOCKET_PATH).catch(() => {});
+      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
+      unlink(DAEMON_SOCKET_PATH).catch(() => {});
+      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);
+    });
+  });
 };
 
 /**

package/src/domains/form.ts

@@ -119,6 +119,8 @@ export const fillTool = defineBrowserTool({
     "Pass the desired value; no browser_click is needed first.",
     "A 'ref is stale' error means the page changed — re-run browser_snapshot to get fresh refs.",
     "Use browser_type instead only for keystroke-sensitive widgets (autocomplete, masked/segmented inputs).",
+    "Fill sets the value but does not focus or submit. To submit a tag/autocomplete input, follow with browser_dispatch_key({ ref, key: 'Enter' }) — not browser_press_key, which targets the focused element and may miss this field.",
+    "For a custom (div-based) dropdown, browser_fill won't validate against its option list — open it, run browser_snapshot, then browser_click the option's ref.",
     "The result reports the field's value after writing and an appended page-changes diff — confirm both match what you intended before moving on.",
   ],
   parameters: FillArgs,

package/src/domains/keyboard.ts

@@ -129,12 +129,17 @@ export const dispatchKeyTool = defineBrowserTool({
     "PREFER `ref` from browser_snapshot over a CSS selector — survives re-renders.",
     "Dispatches a synthetic DOM KeyboardEvent — for React/Vue synthetic event listeners. Does NOT insert text (use browser_type or browser_press_key for actual typing).",
     "Try browser_press_key first; only use browser_dispatch_key when the page ignores raw CDP key events.",
+    "The event carries keyCode/which (e.g. 13 for Enter) for legacy handlers, but is untrusted (isTrusted === false) — a few libraries may still ignore it.",
     "eventType defaults to 'keydown'.",
   ],
   parameters: DispatchKeyArgs,
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const eventType = args.eventType ?? "keydown";
     const target = args.ref ?? args.selector ?? "";
+    // Legacy handlers commonly branch on e.keyCode/e.which (e.g. === 13 for
+    // Enter) rather than e.key, so populate both. virtualKeyCode maps named
+    // keys and single chars; 0 for anything unknown.
+    const code = virtualKeyCode(args.key);
     // Ref path: dispatch on the single resolved node. Selector path: dispatch on
     // all matches (preserves the original multi-match behavior).
     if (args.ref !== undefined) {
@@ -142,8 +147,8 @@ export const dispatchKeyTool = defineBrowserTool({
       if (!objectId.success) return objectId;
       const r = await client.session().call("Runtime.callFunctionOn", {
         objectId: objectId.data,
-        functionDeclaration: `function (type, key) { this.dispatchEvent(new KeyboardEvent(type, { key, bubbles: true, cancelable: true })); return 1; }`,
-        arguments: [{ value: eventType }, { value: args.key }],
+        functionDeclaration: `function (type, key, keyCode) { this.dispatchEvent(new KeyboardEvent(type, { key, keyCode, which: keyCode, bubbles: true, cancelable: true })); return 1; }`,
+        arguments: [{ value: eventType }, { value: args.key }, { value: code }],
         returnByValue: true,
       });
       if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -160,7 +165,7 @@ export const dispatchKeyTool = defineBrowserTool({
         const els = document.querySelectorAll(${args.selector});
         if (els.length === 0) return 0;
         for (const el of els) {
-          el.dispatchEvent(new KeyboardEvent(${eventType}, { key: ${args.key}, bubbles: true, cancelable: true }));
+          el.dispatchEvent(new KeyboardEvent(${eventType}, { key: ${args.key}, keyCode: ${code}, which: ${code}, bubbles: true, cancelable: true }));
         }
         return els.length;
       })()