pi-browser-harness 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.12.0 — 2026-10-19
+
+### Changed
+
+- **Browser guidance no longer repeats tool declarations.** The browser prompt now contains only cross-tool coordination, available before and after connection, and tool guidelines omit usage and argument details already present in descriptions and schemas. Tool names, schemas, handlers, and safety warnings are unchanged.
+
+### Added
+
+- **Per-tab extra HTTP request headers.** `browser_set_headers` applies headers to subsequent document, subresource, fetch, and XHR requests on the current owned tab through CDP, while `browser_clear_headers` removes them. Header values are not echoed in tool output, and guidance requires clearing them before switching tabs or navigating to another origin.
+
+### Fixed
+
+- **`pi -p` exits after using browser tools.** The client's socket to the daemon is kept open across sessions by design, and in non-interactive mode it was the last handle keeping Node alive, so a print-mode run that had connected to the browser printed its answer and then hung until killed. The socket no longer holds the event loop; in-flight requests keep their own timers, so nothing awaited is affected. (#39)
+- **`browser_download` no longer redirects the user's own downloads for good.** `Browser.setDownloadBehavior` was sent without a `browserContextId`, which Chrome applies to its default context — the one the user's own tabs are in — and the override lives on the browser connection, which the daemon keeps open across pi sessions. Every later download in that Chrome, the user's own included, went to the tool's temp directory, and nothing undid it when the session ended. The tool now takes `restore: true` to reset the behavior, and a clean session shutdown restores the default whenever this session's override is still in force (a killed session cannot, so call `restore: true` as soon as you are done).
+- **Browser state is no longer appended to the session on every callback.** Every ownership change, every `session_tree` event (even one that merely restored the entry already on the branch) and every shutdown appended a `browser-harness-state` entry, so the append-only session file and Pi Web's `+N custom` chain grew without bound. A snapshot is now written only when it differs from the last one persisted or restored; tab order does not count as a difference. (#26)
+- **The daemon starts from a pi-managed install without `typebox`.** pi installs packages with dev and peer dependencies omitted and maps host-provided packages such as `typebox` only inside the extension host, but the daemon is a separate Node process that resolved `typebox` through `src/cdp/discovery.ts` and died with `Cannot find module 'typebox'` before binding its socket, so `/browser-setup` reported `Could not start the browser daemon`. The daemon's `/json/version` parsing no longer uses `typebox`, and a test walks the daemon's import graph to keep every reachable package a runtime dependency. (#34)
+- **The daemon starts from a Bun-compiled pi binary.** Inside `pi.exe` (and any other `bun build --compile` host), `createRequire().resolve("tsx/cli")` is rooted at the binary's embedded virtual filesystem and cannot see the extension's real `node_modules`, so `browser_setup` failed instantly with `Could not start the browser daemon`. The resolver result is now checked on disk and, when it fails, the tsx CLI is found by walking up the `node_modules` chain the way Node does. Under Bun the daemon is launched with `node` from `PATH` instead of `process.execPath` (which is the pi binary itself); `PI_BROWSER_NODE` overrides the executable. (#27)
+
+## 0.11.1 — 2026-08-12
+
+### Fixed
+
+- **Chrome remote-debugging consent is no longer retriggered indefinitely in the background.** A cancelled, failed, or disconnected CDP connection now remains disconnected until the next explicit browser request, which makes one on-demand connection attempt instead of running an unbounded retry loop that can repeatedly interrupt normal browsing.
+- **`browser_run_script` accepts paths on Windows again.** The allowed-directory check compared against a hardcoded `/` separator, so every backslash path — including files inside `os.tmpdir()`, which the rejection message itself listed as allowed — was refused. Containment is now decided by `path.relative`, which carries each platform's own separator and case rules.
+- **The daemon starts from a production install.** `tsx` is needed to run the daemon but was declared only as a dev dependency, so `browser_setup` reported `Could not start the browser daemon` under `npm omit=dev`. It is now a runtime dependency, and the daemon is launched via the CLI entry that Node's resolver finds — a fixed `node_modules/.bin` path does not exist in a hoisted install, which is how pi lays extensions out.
+
 ## 0.11.0 — 2026-08-02
 
 ### Fixed

package/README.md

@@ -161,13 +161,19 @@ Both run in isolated tabs and never disturb your current page.
 |---|---|
 | `browser_network_requests` | Requests captured on the current tab since attach. Filter by URL, method, status, resource type, or recency; optional response bodies. |
 | `browser_http_get` | Plain GET outside the browser. Much faster than navigate-then-read for JSON APIs — but no JS rendering. |
+| `browser_set_headers` | Set extra HTTP request headers on the current owned tab. Values are not echoed in output. |
+| `browser_clear_headers` | Clear extra HTTP request headers from the current owned tab. |
+
+Extra headers persist for subsequent document, subresource, fetch, and XHR requests until cleared or
+the tab closes. Create or select an owned tab before setting them, and clear them before switching
+tabs or navigating the tab to another origin.
 
 ### Files and viewport
 
 | Tool | Purpose |
 |---|---|
 | `browser_upload_file` | Set files on a file input, with a DataTransfer fallback for stubborn pages. |
-| `browser_download` | Set the download directory and suppress the save-as prompt. |
+| `browser_download` | Set the download directory and suppress the save-as prompt, or restore the default. Applies to the user's own downloads until restored. |
 | `browser_print_to_pdf` | Print the page to PDF via `Page.printToPDF`. |
 | `browser_viewport_resize` | Override viewport size and device pixel ratio for responsive checks. |
 
@@ -316,6 +322,7 @@ re-runnable.
 | `BH_DEBUG_CLICKS` | Same as `--browser-debug-clicks`. |
 | `BU_CDP_PORTS` | Extra ports to probe during CDP discovery, beyond 9222. |
 | `BH_SCRIPT_DIR` | Additional directory `browser_run_script` will accept paths from. |
+| `PI_BROWSER_NODE` | Node executable used to run the daemon. Defaults to the one running pi, or `node` from `PATH` when pi is a Bun-compiled binary. |
 
 ---
 
@@ -346,6 +353,14 @@ A long-lived daemon owns the CDP connection, so it outlives individual pi sessio
 you only see Chrome's "Allow Remote Debugging" prompt once. `browser_run_script` executes in the
 harness process with direct daemon and Node access.
 
+### Prompt guidance
+
+Tool descriptions and parameter schemas own per-tool usage. Tool guidelines add only decisions
+and caveats not already covered there. The browser prompt carries cross-tool rules:
+tab isolation, concurrency, checking mutations, and stale-ref recovery. These rules are available
+before and after connection. Longer recipes remain in this README and the bundled skill
+rather than being copied into the browser prompt.
+
 ---
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",
@@ -52,7 +52,6 @@
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
     "@types/ws": "^8.18.1",
-    "tsx": "^4.22.4",
     "typebox": "*",
     "typescript": "^5.0.0"
   },
@@ -70,6 +69,7 @@
     "sharp": "^0.33.0"
   },
   "dependencies": {
+    "tsx": "^4.22.4",
     "ws": "^8.20.0"
   }
 }

package/skills/pi-browser-harness/SKILL.md

@@ -21,6 +21,9 @@ What do you need to know?
   ├─ Network behavior on the current page?
   │     → browser_network_requests
   │
+  ├─ A page requires custom request headers?
+  │     → create/select owned tab → browser_set_headers → navigate/interact → browser_clear_headers
+  │
   ├─ Find pages on the web about a topic?
   │     → browser_web_search    (ranked SERP — links only; follow up with browser_read_page)
   │
@@ -73,6 +76,14 @@ it by opening tabs elsewhere — a different profile means different accounts.
 
 You're attached to the user's real Chrome — never launch your own. If auth is required, stop and ask the user. If `browser_page_info` returns a dialog, handle it first with `browser_handle_dialog`.
 
+## Downloads land in the user's context
+
+`browser_download` calls `Browser.setDownloadBehavior` with no `browserContextId`, which Chrome applies to its **default browser context** — the same one the user's own tabs are in. The override redirects the user's manual downloads too, and it lives on the browser connection the daemon keeps open, so it outlives the tab and the pi session. Symptom the user reports: *"I download things in Chrome and nothing appears in Downloads."*
+
+A clean session shutdown restores the default; a killed session does not. Call `browser_download({ restore: true })` as soon as you are done with a download path, and if a user reports the symptom, call it first.
+
+`browser_run_script` is the same hazard: a script that sets download behavior and then throws partway leaves Chrome mutated. Reset it in a `finally`, not after the last line.
+
 ## Diagnosing a "nothing happened" moment
 
 When an action runs but the page didn't change, capture `browser_console`'s `nextCursor` *before* the action, take the action, then call `browser_console({ sinceSeq: <cursor> })` after — this isolates what your action caused from what was already there. Pair with `browser_network_requests({ sinceMs: 5000 })` to see if an API call fired and failed. The console buffer is page-scoped: it clears on tab switch, capacity 500.
@@ -97,3 +108,21 @@ When a workflow repeats 3+ times or needs Node.js APIs, write a script to disk a
 **Don't:**
 - Use scripts for one-off actions — call `browser_*` tools directly.
 - Call `browser_*` tools from inside a script — sequence them as separate tool calls outside.
+
+## Troubleshooting: "Could not start the browser daemon"
+
+`browser_setup` spawns the daemon as `node <tsx cli> <pkg>/src/daemon/index.ts` with `stdio: "ignore"` (tsx is resolved from the package directory upward, so in pi's hoisted install it sits beside the package rather than inside it). A crash before the socket binds is completely silent and all you see is `Could not start the browser daemon. Check /tmp/pi-browser-daemon.sock.`
+
+Run it in the foreground to see the real error (it prints whether it reached Chrome):
+
+    cd <pkg> && node "$(node -p "require.resolve('tsx/cli')")" src/daemon/index.ts
+
+Known cause (package 0.11.1): `Error: Cannot find module 'typebox'` at `src/cdp/discovery.ts`. The package declares `typebox` in `peerDependencies` and `devDependencies`, and pi installs packages with dev and peer dependencies omitted, so the tree has no physical copy. It still resolves inside the pi extension host, which maps `typebox` to pi's bundled copy, but not in the spawned daemon process, which resolves modules from the package directory upward. The daemon dies, no socket appears, and every browser tool reports `not_connected`.
+
+Fix it without touching the manifest, which must keep `typebox` out of `dependencies` (pi warns on it and `npm run check` rejects it):
+
+    cd <pkg> && npm install --no-save typebox --no-audit --no-fund
+
+or restore the full tree with `npm ci`, which installs the `devDependencies` copy. Then confirm with `node -e "console.log(require.resolve('typebox'))"` inside the package directory, and start the daemon with `NODE_PATH` unset to prove no environment workaround is in play. A fresh clone or update reinstalls the tree, so the missing copy can come back; the manifest itself is correct upstream.
+
+Do not work around it with `npm install typebox --save` (that writes `typebox` into `dependencies`, tripping pi's extension warning and the manifest check), a global `NODE_PATH`, or a hand-made symlink: the spawn inherits the extension host environment, so a shell-level export may not reach it, and the underlying problem is an incomplete install, not an undeclared dependency.

package/src/cdp/commands.ts

@@ -228,6 +228,10 @@ export const COMMANDS = {
     Type.Object({ requestId: Type.String() }),
     Type.Object({ body: Type.String(), base64Encoded: Type.Optional(Type.Boolean()) }),
   ),
+  "Network.setExtraHTTPHeaders": cmd(
+    Type.Object({ headers: Type.Record(Type.String(), Type.String()) }),
+    Empty,
+  ),
   "Emulation.setDeviceMetricsOverride": cmd(Type.Object({}, { additionalProperties: true }), Empty),
   "Accessibility.getFullAXTree": cmd(
     Type.Object({ depth: Type.Optional(Type.Number()) }, { additionalProperties: true }),

package/src/cdp/discovery.ts

@@ -2,23 +2,27 @@ import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { connect as netConnect } from "node:net";
 import { request as httpRequest } from "node:http";
-import { Type } from "typebox";
-import { Compile } from "typebox/compile";
-import { parseJson } from "../schemas/parse";
 import { type Result, err, ok } from "../util/result";
 import { userDataDirCandidates } from "../profile/paths";
 import { type CdpError, cdpError } from "./errors";
-import { errnoCode } from "../util/guards";
+import { asString, errnoCode, isRecord } from "../util/guards";
 
 const PORT_PROBE_DEADLINE_MS = 30_000;
 const PORT_PROBE_INTERVAL_MS = 1_000;
 
-const VersionResponse = Type.Object(
-  { webSocketDebuggerUrl: Type.Optional(Type.String()) },
-  { additionalProperties: true },
-);
-
-const versionValidator = Compile(VersionResponse);
+// Hand-rolled on purpose: this file runs inside the daemon, a separate Node process that pi does not
+// supply host-provided packages (typebox) to. Everything the daemon imports must be a runtime
+// dependency or a builtin; test/daemon/entry-imports-test.ts enforces that.
+export const parseVersionResponse = (raw: string): string | null => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  return asString(parsed["webSocketDebuggerUrl"]) ?? null;
+};
 
 export type CdpEndpoint = {
   readonly wsUrl: string;
@@ -72,8 +76,7 @@ const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null>
         const chunks: Buffer[] = [];
         res.on("data", (c: Buffer) => chunks.push(c));
         res.on("end", () => {
-          const parsed = parseJson(Buffer.concat(chunks).toString("utf8"), versionValidator);
-          resolve(parsed.success ? parsed.data.webSocketDebuggerUrl ?? null : null);
+          resolve(parseVersionResponse(Buffer.concat(chunks).toString("utf8")));
         });
       },
     );