pi-browser-harness 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.13.0 — 2026-10-20
+
+### Fixed
+
+- **A killed daemon no longer crashes pi with `read ECONNRESET`.** The daemon's liveness probe, the client transport and the IPC server read the wire protocol through `node:readline`, which re-emits the socket's errors on its own interface with no listener. They now share a small line reader in `src/daemon/lines.ts` that only emits lines.
+- **Waking from sleep no longer stacks up "Allow remote debugging" prompts.** Each dial to Chrome is one prompt, and the daemon abandoned a dial after 10s and started another on the next tool call, so an agent mid-task could open a dozen prompts before anyone was back at the keyboard. A dial now stays open for 5 minutes while callers get a "waiting for the Allow prompt" answer after 10s, every caller joins the dial in flight, and an outright failure starts a doubling cooldown (30s to 5min) during which no automatic dial happens. A dropped connection still re-dials once at the next demand. `/browser-setup` and `/browser-reload-daemon` send `Daemon.reconnect`, which bypasses the cooldown.
+- **Tool failures now reach the model as errors.** `defineBrowserTool` set `isError` on the returned result, but pi only flags a result as an error when `execute` rejects, so every failed browser tool read as a success. Failed handlers now throw with the rendered error text; replayed errors still render in the UI.
+- **The daemon transport no longer exits mid-handshake.** The connect timer was cleared on TCP connect, before the daemon's `registered` reply, and the socket was already unref'd, so a print-mode run could exit before registering. The timer now stays armed until the handshake settles; a daemon that accepts but never registers times out instead of hanging.
+- **Disconnected clients are cleaned up in the daemon.** The idle-timer registration overwrote the bridge's disconnect handler, so router ownership and armed timers leaked per client. The IPC server now keeps a handler list; `deregister` is handled.
+- **`--browser-namespace` works.** The flag was read before it was registered, so it was always undefined.
+- **CDP sessions are reused or detached.** Switching tabs re-attached every time and left the old session alive; destroying the current target left `current()` pointing at it for up to 30s. Sessions are now tracked per target, detached on re-attach, and cleared on `Target.targetDestroyed` / `Inspector.detached`.
+- **Connect timeouts no longer kick every client off the daemon**, overlapping `connect()` calls share one handshake, the detach release reads the session from `params`, and the duplicate-clientId reply is flushed before the socket closes.
+- **Time budgets in `browser_network_requests` and `browser_snapshot` actually bound the work** through a concurrency-limited runner that honours the abort signal.
+- **`browser_handle_dialog` clears the recorded dialog**, so the next `browser_page_info` no longer reports an already-handled dialog.
+- **`browser_press_key` sends virtual key codes for function and modifier keys.**
+- **`browser_open_urls` applies the tab-title marker after the page loads** instead of to the document being replaced.
+- **`browser_print_to_pdf`, screenshots and uploads return `io_error`** on unwritable or unreadable paths instead of throwing.
+- **Element refs are released** (`Runtime.releaseObject`) on every ref path; `browser_read_page` and `browser_open_urls` detach the sessions they attach.
+- sharp "missing" is classified correctly under ESM; `isPathWithin` accepts siblings starting with `..`; `BH_DEBUG_CLICKS=0` disables debug; Linux `chromium-browser` process names are matched after `ps` truncation; discovery probes stale `DevToolsActivePort` candidates concurrently under one deadline.
+
+### Changed
+
+- **Bad arguments return `invalid_args`** instead of `invalid_state`.
+- **`browser_switch_tab` resolves targetId prefixes against owned tabs only**, matching `browser_close_tab`.
+- **`browser_execute_js` details hold a bounded preview**; the full value lives in the text.
+- **CDP calls require params when the method needs them**, and `Input.*`, `Emulation.setDeviceMetricsOverride`, `Page.printToPDF` and `Page.captureScreenshot` have real schemas.
+- **Tool `details` are typed** via a TypeBox schema on the definition and validated on replay.
+- **Page-side JS is TypeScript** under `src/domains/page/*.page.ts`, type-checked against the DOM lib and injected via `fn.toString()`. `src/domains/fill-engine.ts` is removed.
+- The browser prompt's lane lists and the skill file's tool reference are generated from the registry (`npm run gen:skill`).
+
+### Added
+
+- **Other pi extensions can contribute browser tools** through `registerBrowserTools` (see README, Extending).
+- Type-aware ESLint (`npm run lint`) and `npm run check` running typecheck, boundaries, lint and tests. The boundary scanner gained a `raw-js-template` rule.
+- Injection seams on the daemon entry, extension factory, setup and profile binding; tests for every tool in `src/domains` and the previously untested util, profile and daemon modules (365 tests to 1017).
+
+## 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. |
 
@@ -297,6 +303,91 @@ Scripts must live under the OS temp dir, the cwd, or `BH_SCRIPT_DIR`, and every
 mandatory timeout (60s default, 600s max). They land on disk first, so they're reviewable and
 re-runnable.
 
+### Contributing tools from another pi extension
+
+Another extension can add its own `browser_*` tools to this harness. Contributed tools share the
+same client, mutation mutex, tab ownership, and lane prompt as the built-ins, so a `serialized` tool
+you add queues behind `browser_click` exactly as `browser_fill` does.
+
+Define the tool with `defineBrowserTool` and hand it to `registerBrowserTools` at your extension's
+load time, before pi emits `session_start`. The harness registers it with pi on the next
+`session_start` alongside the built-ins.
+
+```ts
+// my-extension/src/index.ts
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { defineBrowserTool, registerBrowserTools, ok } from "pi-browser-harness/src/index.ts";
+import { evalJs } from "pi-browser-harness/src/domains/cdp-call.ts";
+
+const pageHeightTool = defineBrowserTool({
+  name: "browser_page_height",
+  label: "Browser Page Height",
+  description: "Report the document's full scroll height in CSS pixels.",
+  promptSnippet: "Measure the page's scroll height",
+  promptGuidelines: [],
+  parameters: Type.Object({}),
+  concurrency: "parallel",
+  handler: async (_args, { client }) => {
+    const height = await evalJs(client, "document.documentElement.scrollHeight");
+    if (!height.success) return height;
+    return ok({ text: `Scroll height: ${String(height.data)}px` });
+  },
+});
+
+export default function myExtension(_pi: ExtensionAPI): void {
+  const added = registerBrowserTools([pageHeightTool]);
+  if (!added.success) console.warn(added.error.message);
+}
+```
+
+`registerBrowserTools` returns a `Result`. The whole batch is rejected, and nothing is added, when any
+name is already taken by a built-in, an earlier contribution, or another tool in the same batch. Pick
+`concurrency: "serialized"` for anything that changes page or tab state; `"parallel"` for reads.
+`browserTools()` lists what the harness will register, built-ins plus contributions so far.
+
+A tool that wants a custom result view declares a `details` schema next to `parameters`. The handler
+then returns `details` of that shape, and `renderResult` receives them typed. pi stores details with
+the session and replays them later; the harness validates replayed details against the schema first,
+so a renderer never sees a stale shape from an older session (it falls back to the stored text instead).
+Details must be plain JSON: no `Map`s, and omit a key rather than setting it to `undefined`.
+
+```ts
+import { Text } from "@mariozechner/pi-tui";
+
+const PageHeightDetails = Type.Object({ height: Type.Number(), unit: Type.Literal("px") });
+
+const pageHeightTool = defineBrowserTool({
+  // ...name, label, description, promptSnippet, promptGuidelines, parameters, concurrency as above
+  details: PageHeightDetails,
+  handler: async (_args, { client }) => {
+    const height = await evalJs(client, "document.documentElement.scrollHeight");
+    if (!height.success) return height;
+    const px = typeof height.data === "number" ? height.data : 0;
+    return ok({ text: `Scroll height: ${px}px`, details: { height: px, unit: "px" } });
+  },
+  renderResult: (result, _expanded, theme) =>
+    new Text(theme.fg("muted", `${result.details.height}${result.details.unit}`), 0, 0),
+});
+```
+
+Tools without a `details` schema need nothing extra: they may still attach any JSON object for logs,
+and their `renderResult` (if any) sees it untyped.
+
+### Known limits
+
+Two extension points are documented but not implemented; the escape hatches that exist today are
+listed with each.
+
+- **No per-tab extension slot.** `TabSession` in `src/cdp/session.ts` carries only the harness's own
+  per-tab state (session id, dialog, page-info cache). A contributed tool cannot stash its own state
+  on a tab. Keep per-tab state in your extension keyed by `targetId` from `browser_current_tab` or
+  `browser_list_tabs`, or compute it on demand with `browser_run_script` through `daemon.session(targetId)`.
+- **Hardcoded browser list.** `src/profile/paths.ts` knows the user-data directories of a fixed set
+  of Chromium browsers, so `/browser-profile` cannot discover one that is not on that list. Point the
+  harness at any Chromium profile directory with `CHROME_USER_DATA_DIR`, or skip discovery entirely
+  by attaching to a running browser's DevTools endpoint with `BU_CDP_WS`.
+
 ---
 
 ## Commands, flags, and environment
@@ -316,6 +407,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 +438,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
@@ -378,6 +478,7 @@ path-restricted and timeout-bounded, but that is a blast-radius limit, not a san
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, conventions, and the PR process.
+`npm run check` runs the typecheck, the boundary scan, the type-aware ESLint pass and the test suite in that order; it is the one command a PR must pass.
 Release history lives in [CHANGELOG.md](CHANGELOG.md).
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",
@@ -49,19 +49,24 @@
     "typebox": "*"
   },
   "devDependencies": {
+    "@eslint/js": "10.0.1",
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
     "@types/ws": "^8.18.1",
-    "tsx": "^4.22.4",
+    "eslint": "10.11.0",
     "typebox": "*",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "typescript-eslint": "8.71.0"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util}/**/*-test.ts\"",
+    "typecheck": "tsc -b tsconfig.page.json && tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util,types}/**/*-test.ts\"",
     "boundaries": "tsx scripts/check-boundaries.ts",
-    "check": "npm run typecheck && npm run boundaries && npm test",
-    "prepublishOnly": "tsc --noEmit"
+    "gen:skill": "node --conditions=import --import tsx scripts/gen-skill.ts",
+    "check": "npm run typecheck && npm run boundaries && npm run lint && npm test",
+    "prepublishOnly": "npm run typecheck",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   },
   "publishConfig": {
     "access": "public"
@@ -70,6 +75,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)
   │
@@ -38,6 +41,61 @@ Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot
 
 `browser_web_search` and `browser_read_page` each run in their own isolated tab and never touch the user's current tab. Pair them for a research question: search for candidate URLs, then read the promising ones.
 
+## Tool reference
+
+Every tool, its concurrency lane, and a one-line summary. `serialized` tools queue through one
+shared mutation lane; `parallel` tools may run alongside them. The decision tree above says which
+to reach for first; the tool descriptions and parameter schemas carry per-tool detail.
+
+<!-- tools:start -->
+Generated from `src/registry.ts` by `npm run gen:skill`; do not edit by hand.
+
+| Tool | Lane | Summary |
+|---|---|---|
+| `browser_clear_headers` | serialized | Clear extra request headers from the current owned tab |
+| `browser_click` | serialized | Click an element by ref (preferred) or pixel coordinates |
+| `browser_close_tab` | serialized | Close an owned tab |
+| `browser_console` | parallel | Read JS errors / console output on the current tab |
+| `browser_current_tab` | parallel | Get current tab info |
+| `browser_dispatch_key` | serialized | Dispatch a DOM KeyboardEvent on an element by ref (preferred) or selector |
+| `browser_download` | serialized | Configure download directory |
+| `browser_drag_and_drop` | serialized | Drag and drop between two coordinates |
+| `browser_execute_js` | parallel | Execute JS in the page — surgical DOM reads (preferred over screenshot) |
+| `browser_fill` | serialized | Fill a form field by ref (preferred) or selector (works with React/Vue controlled inputs) |
+| `browser_fill_form` | serialized | Fill many form fields at once by ref — React-safe, self-confirming |
+| `browser_focus` | serialized | Focus an element by ref (preferred) or selector |
+| `browser_go_back` | serialized | Go back one page |
+| `browser_go_forward` | serialized | Go forward one page |
+| `browser_handle_dialog` | serialized | Accept or dismiss a JS dialog |
+| `browser_http_get` | parallel | HTTP GET (outside browser; for APIs/static pages) |
+| `browser_list_tabs` | parallel | List browser tabs |
+| `browser_navigate` | serialized | Navigate to a URL |
+| `browser_network_requests` | parallel | Inspect recent network requests on the current page |
+| `browser_new_tab` | serialized | Open a new tab |
+| `browser_open_urls` | serialized | Open multiple URLs in new tabs (parallel) |
+| `browser_page_info` | parallel | Get current page URL, title, viewport, and scroll position |
+| `browser_press_key` | serialized | Press a key (Enter, Tab, Escape, arrows, or any character) |
+| `browser_print_to_pdf` | serialized | Print the current page to PDF |
+| `browser_read_page` | parallel | Read a page's main content as clean text |
+| `browser_reload` | serialized | Reload the page |
+| `browser_run_script` | parallel | Run a temporary script with daemon + Node access (security-bounded) |
+| `browser_screenshot` | parallel | Capture a screenshot — visual verification only |
+| `browser_scroll` | serialized | Scroll the page (deltaY positive=down, negative=up) |
+| `browser_select_option` | serialized | Select an option in a native <select> by ref (preferred) or selector |
+| `browser_set_checked` | serialized | Set a checkbox/radio checked state by ref |
+| `browser_set_headers` | serialized | Set extra request headers on the current owned tab |
+| `browser_setup` | parallel | Initialize browser connection |
+| `browser_snapshot` | parallel | Get accessibility-tree snapshot with stable element refs (default for page inspection) |
+| `browser_switch_tab` | serialized | Switch tabs |
+| `browser_type` | serialized | Type text into the focused element |
+| `browser_upload_file` | serialized | Upload a file to a file input by ref (preferred) or selector |
+| `browser_viewport_resize` | serialized | Resize the viewport (responsive testing) |
+| `browser_wait` | parallel | Wait N seconds |
+| `browser_wait_for` | parallel | Wait for an element or text to appear (or an element to disappear) |
+| `browser_wait_for_load` | serialized | Wait for the page to finish loading |
+| `browser_web_search` | serialized | Search the web for a query |
+<!-- tools:end -->
+
 ## Connection Setup
 
 Browser control is **on-demand** — the daemon does NOT start automatically.
@@ -73,6 +131,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 +163,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/main.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/main.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

@@ -1,3 +1,17 @@
+// The typed CDP command table — the extension point for everything the harness sends to Chrome.
+//
+// To add a command:
+//   1. Look the method up in the Chrome DevTools Protocol viewer (https://chromedevtools.github.io/devtools-protocol/).
+//   2. Add a `"Domain.method": cmd(ParamsSchema, ResultSchema)` entry below, in its domain's block.
+//      - Mark optional protocol fields with `Type.Optional(...)` — never with `Type.Union([..., Type.Undefined()])`:
+//        the project compiles with exactOptionalPropertyTypes, so callers must omit a field rather than pass undefined.
+//      - Use `Type.Union([Type.Literal(...), ...])` for enumerated strings so a typo fails to compile.
+//      - Result schemas are `additionalProperties: true` where Chrome may add fields; param schemas are closed.
+//   3. `ParamsOf<"Domain.method">` / `ResultOf<"Domain.method">` now exist, and `session.call("Domain.method", ...)`
+//      requires params exactly when the schema has a required key (see `CallArgs` in session.ts).
+//   4. Results are validated at runtime by `decodeResult`; a payload that does not match is an `invalid_response` error.
+// Events live in ./events.ts and follow the same pattern.
+
 import { Type, type Static, type TSchema } from "typebox";
 import { Compile } from "typebox/compile";
 import { type Result, err, ok } from "../util/result";
@@ -77,6 +91,82 @@ const AxNode = Type.Object(
 
 export type AxNodeResult = Static<typeof AxNode>;
 
+// Page.Viewport: a clip rectangle in CSS pixels.
+const Viewport = Type.Object({
+  x: Type.Number(),
+  y: Type.Number(),
+  width: Type.Number(),
+  height: Type.Number(),
+  scale: Type.Number(),
+});
+
+// Browser.setDownloadBehavior — "allowAndName" saves under the download's GUID; "default" restores Chrome's own policy.
+const DownloadBehavior = Type.Union([
+  Type.Literal("deny"),
+  Type.Literal("allow"),
+  Type.Literal("allowAndName"),
+  Type.Literal("default"),
+]);
+
+const ScreenshotFormat = Type.Union([Type.Literal("jpeg"), Type.Literal("png"), Type.Literal("webp")]);
+
+// Input.MouseButton
+const MouseButton = Type.Union([
+  Type.Literal("none"),
+  Type.Literal("left"),
+  Type.Literal("middle"),
+  Type.Literal("right"),
+  Type.Literal("back"),
+  Type.Literal("forward"),
+]);
+
+const MouseEventType = Type.Union([
+  Type.Literal("mousePressed"),
+  Type.Literal("mouseReleased"),
+  Type.Literal("mouseMoved"),
+  Type.Literal("mouseWheel"),
+]);
+
+const KeyEventType = Type.Union([
+  Type.Literal("keyDown"),
+  Type.Literal("keyUp"),
+  Type.Literal("rawKeyDown"),
+  Type.Literal("char"),
+]);
+
+const DragEventType = Type.Union([
+  Type.Literal("dragEnter"),
+  Type.Literal("dragOver"),
+  Type.Literal("drop"),
+  Type.Literal("dragCancel"),
+]);
+
+// Input.DragDataItem / Input.DragData. `data` is the payload as a string (binary payloads are base64).
+const DragDataItem = Type.Object({
+  mimeType: Type.String(),
+  data: Type.String(),
+  title: Type.Optional(Type.String()),
+  baseURL: Type.Optional(Type.String()),
+});
+
+const DragData = Type.Object({
+  items: Type.Array(DragDataItem),
+  files: Type.Optional(Type.Array(Type.String())),
+  // Bit field of allowed operations: 1=Copy, 2=Link, 16=Move.
+  dragOperationsMask: Type.Integer(),
+});
+
+// Emulation.ScreenOrientation
+const ScreenOrientation = Type.Object({
+  type: Type.Union([
+    Type.Literal("portraitPrimary"),
+    Type.Literal("portraitSecondary"),
+    Type.Literal("landscapePrimary"),
+    Type.Literal("landscapeSecondary"),
+  ]),
+  angle: Type.Integer(),
+});
+
 export const COMMANDS = {
   "Target.attachToTarget": cmd(
     Type.Object({ targetId: Type.String(), flatten: Type.Optional(Type.Boolean()) }),
@@ -117,7 +207,8 @@ export const COMMANDS = {
   ),
   "Browser.setDownloadBehavior": cmd(
     Type.Object({
-      behavior: Type.String(),
+      behavior: DownloadBehavior,
+      browserContextId: Type.Optional(Type.String()),
       downloadPath: Type.Optional(Type.String()),
       eventsEnabled: Type.Optional(Type.Boolean()),
     }),
@@ -147,14 +238,39 @@ export const COMMANDS = {
   "Page.navigateToHistoryEntry": cmd(Type.Object({ entryId: Type.Number() }), Empty),
   "Page.captureScreenshot": cmd(
     Type.Object({
-      format: Type.Optional(Type.String()),
-      quality: Type.Optional(Type.Number()),
-      clip: Type.Optional(Type.Unknown()),
+      format: Type.Optional(ScreenshotFormat),
+      // 0–100, jpeg and webp only.
+      quality: Type.Optional(Type.Integer()),
+      clip: Type.Optional(Viewport),
+      fromSurface: Type.Optional(Type.Boolean()),
       captureBeyondViewport: Type.Optional(Type.Boolean()),
+      optimizeForSpeed: Type.Optional(Type.Boolean()),
     }),
     Type.Object({ data: Type.String() }),
   ),
-  "Page.printToPDF": cmd(Type.Object({}, { additionalProperties: true }), Type.Object({ data: Type.String() })),
+  "Page.printToPDF": cmd(
+    Type.Object({
+      landscape: Type.Optional(Type.Boolean()),
+      displayHeaderFooter: Type.Optional(Type.Boolean()),
+      printBackground: Type.Optional(Type.Boolean()),
+      scale: Type.Optional(Type.Number()),
+      // Paper size and margins are in inches.
+      paperWidth: Type.Optional(Type.Number()),
+      paperHeight: Type.Optional(Type.Number()),
+      marginTop: Type.Optional(Type.Number()),
+      marginBottom: Type.Optional(Type.Number()),
+      marginLeft: Type.Optional(Type.Number()),
+      marginRight: Type.Optional(Type.Number()),
+      pageRanges: Type.Optional(Type.String()),
+      headerTemplate: Type.Optional(Type.String()),
+      footerTemplate: Type.Optional(Type.String()),
+      preferCSSPageSize: Type.Optional(Type.Boolean()),
+      transferMode: Type.Optional(Type.Union([Type.Literal("ReturnAsBase64"), Type.Literal("ReturnAsStream")])),
+      generateTaggedPDF: Type.Optional(Type.Boolean()),
+      generateDocumentOutline: Type.Optional(Type.Boolean()),
+    }),
+    Type.Object({ data: Type.String(), stream: Type.Optional(Type.String()) }),
+  ),
   "Page.handleJavaScriptDialog": cmd(
     Type.Object({ accept: Type.Boolean(), promptText: Type.Optional(Type.String()) }),
     Empty,
@@ -219,18 +335,91 @@ export const COMMANDS = {
     Empty,
   ),
 
-  "Input.dispatchMouseEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
-  "Input.dispatchKeyEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
-  "Input.dispatchDragEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Input.dispatchMouseEvent": cmd(
+    Type.Object({
+      type: MouseEventType,
+      x: Type.Number(),
+      y: Type.Number(),
+      // Bit field: 1=Alt, 2=Ctrl, 4=Meta/Command, 8=Shift.
+      modifiers: Type.Optional(Type.Integer()),
+      timestamp: Type.Optional(Type.Number()),
+      button: Type.Optional(MouseButton),
+      // Bit field of pressed buttons: 1=Left, 2=Right, 4=Middle, 8=Back, 16=Forward.
+      buttons: Type.Optional(Type.Integer()),
+      clickCount: Type.Optional(Type.Integer()),
+      force: Type.Optional(Type.Number()),
+      tangentialPressure: Type.Optional(Type.Number()),
+      tiltX: Type.Optional(Type.Number()),
+      tiltY: Type.Optional(Type.Number()),
+      twist: Type.Optional(Type.Integer()),
+      deltaX: Type.Optional(Type.Number()),
+      deltaY: Type.Optional(Type.Number()),
+      pointerType: Type.Optional(Type.Union([Type.Literal("mouse"), Type.Literal("pen")])),
+    }),
+    Empty,
+  ),
+  "Input.dispatchKeyEvent": cmd(
+    Type.Object({
+      type: KeyEventType,
+      modifiers: Type.Optional(Type.Integer()),
+      timestamp: Type.Optional(Type.Number()),
+      text: Type.Optional(Type.String()),
+      unmodifiedText: Type.Optional(Type.String()),
+      keyIdentifier: Type.Optional(Type.String()),
+      code: Type.Optional(Type.String()),
+      key: Type.Optional(Type.String()),
+      windowsVirtualKeyCode: Type.Optional(Type.Integer()),
+      nativeVirtualKeyCode: Type.Optional(Type.Integer()),
+      autoRepeat: Type.Optional(Type.Boolean()),
+      isKeypad: Type.Optional(Type.Boolean()),
+      isSystemKey: Type.Optional(Type.Boolean()),
+      // 0=Standard, 1=Left, 2=Right, 3=Numpad.
+      location: Type.Optional(Type.Integer()),
+      commands: Type.Optional(Type.Array(Type.String())),
+    }),
+    Empty,
+  ),
+  "Input.dispatchDragEvent": cmd(
+    Type.Object({
+      type: DragEventType,
+      x: Type.Number(),
+      y: Type.Number(),
+      data: DragData,
+      modifiers: Type.Optional(Type.Integer()),
+    }),
+    Empty,
+  ),
   "Input.insertText": cmd(Type.Object({ text: Type.String() }), Empty),
 
   "Network.getResponseBody": cmd(
     Type.Object({ requestId: Type.String() }),
     Type.Object({ body: Type.String(), base64Encoded: Type.Optional(Type.Boolean()) }),
   ),
-  "Emulation.setDeviceMetricsOverride": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Network.setExtraHTTPHeaders": cmd(
+    Type.Object({ headers: Type.Record(Type.String(), Type.String()) }),
+    Empty,
+  ),
+  "Emulation.setDeviceMetricsOverride": cmd(
+    Type.Object({
+      // 0 disables the override for that dimension.
+      width: Type.Integer(),
+      height: Type.Integer(),
+      // 0 disables the override.
+      deviceScaleFactor: Type.Number(),
+      mobile: Type.Boolean(),
+      scale: Type.Optional(Type.Number()),
+      screenWidth: Type.Optional(Type.Integer()),
+      screenHeight: Type.Optional(Type.Integer()),
+      positionX: Type.Optional(Type.Integer()),
+      positionY: Type.Optional(Type.Integer()),
+      dontSetVisibleSize: Type.Optional(Type.Boolean()),
+      screenOrientation: Type.Optional(ScreenOrientation),
+      viewport: Type.Optional(Viewport),
+    }),
+    Empty,
+  ),
   "Accessibility.getFullAXTree": cmd(
-    Type.Object({ depth: Type.Optional(Type.Number()) }, { additionalProperties: true }),
+    Type.Object({ depth: Type.Optional(Type.Number()), frameId: Type.Optional(Type.String()) }),
     Type.Object({ nodes: Type.Array(AxNode) }),
   ),
 };
@@ -243,14 +432,15 @@ export const decodeResult = <M extends CdpMethod>(
   method: M,
   raw: unknown,
 ): Result<ResultOf<M>, CdpError> => {
+  // `method` is a key of COMMANDS, so the lookup cannot miss.
   const spec = COMMANDS[method];
-  if (spec === undefined) {
-    return err(cdpError("invalid_response", `unknown CDP method`, method));
-  }
   if (!spec.validate.Check(raw)) {
     const why = spec.validate.Errors(raw).map((e) => e.message).join("; ");
     return err(cdpError("invalid_response", why, method));
   }
-  // Guarded assertion: the check above proves `raw` matches COMMANDS[method].result, which TS cannot correlate from a generic key.
+  // Guarded assertion: the check above proves `raw` matches COMMANDS[method].result. TS resolves
+  // `spec.validate` through a generic key to the union of every validator, so the predicate
+  // narrows `raw` to the union of every result type rather than to ResultOf<M>.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- sanctioned decoder, see scripts/boundary-allowlist.ts
   return ok(raw as ResultOf<M>);
 };