pi-browser-harness 0.10.2 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 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
+
+- **`--browser-debug-clicks` now does something.** The flag was registered and documented but never read; the only working switch was the undocumented `BH_DEBUG_CLICKS` environment variable. Both now drive the same setting.
+- **`BU_CDP_WS` now actually attaches to a remote browser.** The client read the variable and passed the URL to `transport.connect()`, but the daemon transport discards that argument and always dials the daemon socket — and the daemon's own discovery never looked at the variable, so setting it changed nothing. The override moved into `discoverEndpoint`, which both processes go through. It is read when the daemon starts, so a running daemon must be stopped first.
+- **A disconnected client's pending requests no longer fire at a dead socket.** `removeClient` cleared the daemon's id multiplexer but not its callback map, so a gone client's command timeouts stayed armed and later tried to answer it.
+
+### Changed
+
+- **One route from a tool to the browser.** Four coexisted; `src/domains/cdp-call.ts` is now the only one, and two boundary-scanner rules scoped to `src/domains/` keep it that way. A CDP timeout now surfaces as `kind: "timeout"` instead of `cdp_error` at the sites that previously flattened it.
+- **Shared logic moved out of tool files** into `ax-tree.ts`, `element-call.ts`, and `screenshot-capture.ts`, so importing one tool no longer pulls in another tool's module. `cdp/attach.ts` and `cdp/window.ts` became `session.attach()` and `session.windowId()`; `cdp/daemon-transport.ts` became `daemon/transport.ts`; the request-timeout half of `cdp/event-queue.ts` became `cdp/pending-requests.ts`.
+- **The daemon's request bookkeeping is one map instead of two**, and a request that arrives while Chrome is down awaits a single connect signal rather than spinning its own 250 ms poll loop.
+
+### Removed
+
+- **The second CDP transport.** `createCdpTransport` was a full WebSocket-to-Chrome implementation reachable only through a fallback in `client.ts` that production never took. `cdp/transport.ts` now holds just the `CdpTransport` interface, and a client must be given a transport.
+- **Dead exports and a fake config knob:** `isInternalUrl`, `SPECIAL_KEYS`, `andThen`, `mapErr`, `BrowserState.remoteBrowserId`, `IpcServer.disconnectClient`, `IpcServer.clients()`, and `DAEMON_STALE_SOCKET_CLEANUP` (a hardcoded `true` with a branch around it).
+
+- **The `deep-research` skill, the `/deep-research` command, and the `web-search-researcher` subagent.** The harness ships browser tools; orchestrating multi-agent research on top of them belongs to the agent, not to this extension. `browser_web_search` and `browser_read_page` are unaffected — search then read still works, it is just no longer wrapped in a fan-out workflow.
+
+## 0.10.3 — 2026-07-26
+
+### Fixed
+
+- **Profile binding after an in-place browser upgrade.** Linux appends `" (deleted)"` to `/proc/<pid>/exe` once the running binary is unlinked — which is exactly what a `google-chrome` package update does while the browser stays open. `detectRunningBrowser` returned that literal string as the executable path, so every profile launch tried to spawn `/opt/google/chrome/chrome (deleted)` and failed with `ENOENT`. Executable paths are now validated against disk, with the marker stripped (and argv[0] used) when the linked binary is gone.
+- **A failed browser launch no longer reports as a sentinel timeout.** `spawn()` signals a missing or non-executable binary asynchronously via an `error` event rather than by throwing, and that event was discarded — so `openProfileWindow` returned success, no window ever opened, and the caller blamed the browser 15 seconds later with `couldn't open a window in "<profile>" automatically`. The launch now waits for `spawn`/`error` and returns the real cause, and removes its handshake page on the failure path.
+
 ## 0.10.2 — 2026-07-26
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@
 
 Your profile, your logins, your cookies. The agent reads pages as an accessibility tree with stable
 element handles, fills forms that React won't revert, captures network traffic and console errors,
-searches the web, and drops to raw CDP when the tools run out. 38 tools over a single CDP connection —
+searches the web, and drops to raw CDP when the tools run out. 40 tools over a single CDP connection —
 no MCP hop, no second browser, no extra API keys.
 
 ---
@@ -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. |
 
@@ -238,11 +244,7 @@ browser_web_search({ query: "chrome devtools protocol overview", limit: 5 })
 browser_read_page({ url: "<the best result's url>" })
 ```
 
-For a question that needs several sources synthesized into a **cited report**, use
-`/deep-research <question>`. It decomposes the question, fans out one isolated
-`web-search-researcher` subagent per sub-question, loops for coverage under a hard ceiling, and
-writes a Markdown report where every claim carries a source link. The skill also auto-triggers on
-research-shaped requests without the command.
+Both tools open their own isolated tab, so neither disturbs the tab you are working in.
 
 ### Keyboard modifiers
 
@@ -310,16 +312,17 @@ re-runnable.
 | `/browser-setup` | Connect pi to your browser. Run once; idempotent. |
 | `/browser-profile` | Pick which browser profile the agent works in. Remembered across sessions. |
 | `/browser-status` | Connection state, selected profile, and current page. |
-| `/deep-research <question>` | Multi-source web research → cited Markdown report. |
 | `/browser-reload-daemon` | Force a client restart. Rarely needed — the transport reconnects on its own. |
 
 | Flag / variable | Effect |
 |---|---|
 | `--browser-namespace <name>` | Override the session namespace (default: auto-generated). |
-| `--browser-debug-clicks` | Save annotated click screenshots for debugging. |
-| `BU_CDP_WS` | Attach to a remote browser by WebSocket URL instead of discovering a local one. |
+| `--browser-debug-clicks` | Save annotated click screenshots for debugging. Equivalent to `BH_DEBUG_CLICKS=1`. |
+| `BU_CDP_WS` | Attach to a remote browser by WebSocket URL instead of discovering a local one. The daemon reads this when it starts, so stop a running daemon first. |
+| `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. |
 
 ---
 
@@ -350,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.10.2",
+  "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,12 +52,14 @@
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
     "@types/ws": "^8.18.1",
-    "tsx": "^4.22.4",
     "typebox": "*",
     "typescript": "^5.0.0"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util}/**/*-test.ts\"",
+    "boundaries": "tsx scripts/check-boundaries.ts",
+    "check": "npm run typecheck && npm run boundaries && npm test",
     "prepublishOnly": "tsc --noEmit"
   },
   "publishConfig": {
@@ -67,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)
   │
@@ -36,7 +39,7 @@ What do you need to know?
 
 Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot round-trip.
 
-`browser_web_search` and `browser_read_page` each run in their own isolated tab and never touch the user's current tab. For a multi-source question that needs a synthesized, cited report, use the **deep-research** skill (or `/deep-research <question>`): it fans out isolated `web-search-researcher` subagents over both tools and writes a source-cited Markdown report.
+`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.
 
 ## Connection Setup
 
@@ -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

@@ -0,0 +1,260 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Compile } from "typebox/compile";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+
+const cmd = <P extends TSchema, R extends TSchema>(params: P, result: R) => ({
+  params,
+  result,
+  validate: Compile(result),
+});
+
+const Empty = Type.Object({});
+
+const TargetInfo = Type.Object(
+  {
+    targetId: Type.String(),
+    type: Type.String(),
+    title: Type.String(),
+    url: Type.String(),
+    attached: Type.Optional(Type.Boolean()),
+    openerId: Type.Optional(Type.String()),
+    browserContextId: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+const RemoteObject = Type.Object(
+  {
+    type: Type.String(),
+    subtype: Type.Optional(Type.String()),
+    className: Type.Optional(Type.String()),
+    value: Type.Optional(Type.Unknown()),
+    description: Type.Optional(Type.String()),
+    objectId: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+const CallArgument = Type.Object(
+  {
+    value: Type.Optional(Type.Unknown()),
+    objectId: Type.Optional(Type.String()),
+    unserializableValue: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+const ExceptionDetails = Type.Object(
+  { text: Type.String(), exception: Type.Optional(RemoteObject) },
+  { additionalProperties: true },
+);
+
+const AxValue = Type.Object({ value: Type.Optional(Type.Unknown()) }, { additionalProperties: true });
+
+const AxNode = Type.Object(
+  {
+    nodeId: Type.String(),
+    parentId: Type.Optional(Type.String()),
+    childIds: Type.Optional(Type.Array(Type.String())),
+    ignored: Type.Optional(Type.Boolean()),
+    role: Type.Optional(AxValue),
+    name: Type.Optional(AxValue),
+    value: Type.Optional(AxValue),
+    description: Type.Optional(AxValue),
+    properties: Type.Optional(
+      Type.Array(
+        Type.Object(
+          { name: Type.Optional(Type.String()), value: Type.Optional(AxValue) },
+          { additionalProperties: true },
+        ),
+      ),
+    ),
+    backendDOMNodeId: Type.Optional(Type.Number()),
+  },
+  { additionalProperties: true },
+);
+
+export type AxNodeResult = Static<typeof AxNode>;
+
+export const COMMANDS = {
+  "Target.attachToTarget": cmd(
+    Type.Object({ targetId: Type.String(), flatten: Type.Optional(Type.Boolean()) }),
+    Type.Object({ sessionId: Type.String() }),
+  ),
+  "Target.detachFromTarget": cmd(
+    Type.Object({ sessionId: Type.Optional(Type.String()) }),
+    Empty,
+  ),
+  "Target.createTarget": cmd(
+    Type.Object({
+      url: Type.String(),
+      newWindow: Type.Optional(Type.Boolean()),
+      background: Type.Optional(Type.Boolean()),
+      windowId: Type.Optional(Type.Number()),
+      openerId: Type.Optional(Type.String()),
+    }),
+    Type.Object({ targetId: Type.String() }),
+  ),
+  "Target.closeTarget": cmd(
+    Type.Object({ targetId: Type.String() }),
+    Type.Object({ success: Type.Optional(Type.Boolean()) }),
+  ),
+  "Target.activateTarget": cmd(Type.Object({ targetId: Type.String() }), Empty),
+  "Target.getTargetInfo": cmd(
+    Type.Object({ targetId: Type.Optional(Type.String()) }),
+    Type.Object({ targetInfo: TargetInfo }),
+  ),
+  "Target.getTargets": cmd(
+    Type.Object({}),
+    Type.Object({ targetInfos: Type.Array(TargetInfo) }),
+  ),
+  "Target.setDiscoverTargets": cmd(Type.Object({ discover: Type.Boolean() }), Empty),
+
+  "Browser.getWindowForTarget": cmd(
+    Type.Object({ targetId: Type.Optional(Type.String()) }),
+    Type.Object({ windowId: Type.Number(), bounds: Type.Optional(Type.Unknown()) }),
+  ),
+  "Browser.setDownloadBehavior": cmd(
+    Type.Object({
+      behavior: Type.String(),
+      downloadPath: Type.Optional(Type.String()),
+      eventsEnabled: Type.Optional(Type.Boolean()),
+    }),
+    Empty,
+  ),
+
+  "Page.enable": cmd(Type.Object({}), Empty),
+  "Page.bringToFront": cmd(Type.Object({}), Empty),
+  "Page.navigate": cmd(
+    Type.Object({ url: Type.String(), referrer: Type.Optional(Type.String()) }),
+    Type.Object({
+      frameId: Type.String(),
+      loaderId: Type.Optional(Type.String()),
+      errorText: Type.Optional(Type.String()),
+    }),
+  ),
+  "Page.reload": cmd(Type.Object({ ignoreCache: Type.Optional(Type.Boolean()) }), Empty),
+  "Page.getNavigationHistory": cmd(
+    Type.Object({}),
+    Type.Object({
+      currentIndex: Type.Number(),
+      entries: Type.Array(
+        Type.Object({ id: Type.Number(), url: Type.String(), title: Type.String() }),
+      ),
+    }),
+  ),
+  "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()),
+      captureBeyondViewport: Type.Optional(Type.Boolean()),
+    }),
+    Type.Object({ data: Type.String() }),
+  ),
+  "Page.printToPDF": cmd(Type.Object({}, { additionalProperties: true }), Type.Object({ data: Type.String() })),
+  "Page.handleJavaScriptDialog": cmd(
+    Type.Object({ accept: Type.Boolean(), promptText: Type.Optional(Type.String()) }),
+    Empty,
+  ),
+
+  "Runtime.evaluate": cmd(
+    Type.Object(
+      {
+        expression: Type.String(),
+        returnByValue: Type.Optional(Type.Boolean()),
+        awaitPromise: Type.Optional(Type.Boolean()),
+        userGesture: Type.Optional(Type.Boolean()),
+      },
+      { additionalProperties: true },
+    ),
+    Type.Object({ result: RemoteObject, exceptionDetails: Type.Optional(ExceptionDetails) }),
+  ),
+  "Runtime.callFunctionOn": cmd(
+    Type.Object(
+      {
+        functionDeclaration: Type.String(),
+        objectId: Type.Optional(Type.String()),
+        arguments: Type.Optional(Type.Array(CallArgument)),
+        returnByValue: Type.Optional(Type.Boolean()),
+        awaitPromise: Type.Optional(Type.Boolean()),
+        userGesture: Type.Optional(Type.Boolean()),
+      },
+      { additionalProperties: true },
+    ),
+    Type.Object({ result: RemoteObject, exceptionDetails: Type.Optional(ExceptionDetails) }),
+  ),
+  "Runtime.releaseObject": cmd(Type.Object({ objectId: Type.String() }), Empty),
+
+  "DOM.getDocument": cmd(
+    Type.Object({ depth: Type.Optional(Type.Number()), pierce: Type.Optional(Type.Boolean()) }),
+    Type.Object({ root: Type.Object({ nodeId: Type.Number() }, { additionalProperties: true }) }),
+  ),
+  "DOM.querySelector": cmd(
+    Type.Object({ nodeId: Type.Number(), selector: Type.String() }),
+    Type.Object({ nodeId: Type.Number() }),
+  ),
+  "DOM.getBoxModel": cmd(
+    Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
+    Type.Object({
+      model: Type.Object(
+        { content: Type.Array(Type.Number()), width: Type.Number(), height: Type.Number() },
+        { additionalProperties: true },
+      ),
+    }),
+  ),
+  "DOM.resolveNode": cmd(
+    Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
+    Type.Object({ object: RemoteObject }),
+  ),
+  "DOM.setFileInputFiles": cmd(
+    Type.Object({
+      files: Type.Array(Type.String()),
+      nodeId: Type.Optional(Type.Number()),
+      backendNodeId: Type.Optional(Type.Number()),
+      objectId: Type.Optional(Type.String()),
+    }),
+    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.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()) }),
+  ),
+  "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 }),
+    Type.Object({ nodes: Type.Array(AxNode) }),
+  ),
+};
+
+export type CdpMethod = keyof typeof COMMANDS;
+export type ParamsOf<M extends CdpMethod> = Static<(typeof COMMANDS)[M]["params"]>;
+export type ResultOf<M extends CdpMethod> = Static<(typeof COMMANDS)[M]["result"]>;
+
+export const decodeResult = <M extends CdpMethod>(
+  method: M,
+  raw: unknown,
+): Result<ResultOf<M>, CdpError> => {
+  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.
+  return ok(raw as ResultOf<M>);
+};