@reclaimprotocol/agent 0.1.0 → 0.1.1

package/lib/types/openapi.gen.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "Reclaim Protocol agent — SDK, CLI, and MCP server in one package. SDK + CLI talk to the builder backend; MCP server adds Chrome CDP capture, provider synthesis, replay, and zkTLS proof.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -11,6 +11,18 @@
 			"types": "./lib/index.d.ts",
 			"import": "./lib/index.js"
 		},
+		"./provider": {
+			"types": "./lib/provider/index.d.ts",
+			"import": "./lib/provider/index.js"
+		},
+		"./capture": {
+			"types": "./lib/cdp/index.d.ts",
+			"import": "./lib/cdp/index.js"
+		},
+		"./proof": {
+			"types": "./lib/proof/index.d.ts",
+			"import": "./lib/proof/index.js"
+		},
 		"./mcp/register": {
 			"types": "./lib/mcp/register.d.ts",
 			"import": "./lib/mcp/register.js"
@@ -38,15 +50,14 @@
 	"websiteUrl": "https://docs.reclaimprotocol.org",
 	"scripts": {
 		"build": "tsc && node scripts/prepend-shebang.js && chmod 755 lib/cli.js lib/mcp-bin.js",
-		"openapi:typegen": "node ../app/scripts/mcp-tools-gen.ts",
 		"prepublishOnly": "npm run build",
 		"dev": "tsc --watch",
-		"test": "node --test tests/*.test.ts",
+		"test": "node --env-file=.test.env --test tests/*.test.ts",
+		"check": "tsc -p tsconfig.test.json",
 		"start:cli": "node lib/cli.js",
 		"start:mcp": "node lib/mcp-bin.js",
 		"inspect": "npx @modelcontextprotocol/inspector node lib/mcp-bin.js",
-		"download:zk-files": "node scripts/download-zk-files.js",
-		"postinstall": "node scripts/download-zk-files.js"
+		"download:zk-files": "node scripts/download-zk-files.js"
 	},
 	"keywords": [
 		"mcp",
@@ -69,15 +80,12 @@
 	"dependencies": {
 		"@hapi/boom": "^9.1.4",
 		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@noble/hashes": "^2.2.0",
-		"@noble/secp256k1": "^3.1.0",
 		"@reclaimprotocol/attestor-core": "^5.0.7",
 		"@reclaimprotocol/client": "*",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"pino": "^9.14.0",
-		"zod": "^3.25.76",
-		"zod-from-json-schema": "^0.1.0"
+		"zod": "^4.4.3"
 	},
 	"devDependencies": {
 		"@types/chrome-remote-interface": "^0.31.0",
@@ -86,4 +94,4 @@
 		"typescript": "^5.9.0",
 		"yaml": "^2.6.0"
 	}
-}
+}

package/skill/SKILL.md

@@ -20,7 +20,7 @@ This MCP server targets one of two backends. Detect which from the tools availab
 - **Old devtools (the default).** `get_me_providers` is present; the generated API tools (`get_me`, `create_verification`, `list_orgs`, …) are absent.
 - **Builder.** The generated API tools are present; `get_me_providers` is absent.
 
-Only **authentication** (below) and **publishing** (the final step) differ between modes. The capture → draft → replay → prove loop in between is identical, and OPRF is optional and supported in both.
+Only **authentication** (below), **publishing** (the final step), and the **consumer-supplied param namespace** differ between modes: values the Consumer supplies at verification time are templated `{{context.<name>}}` on builder vs `{{context_<name>}}` on old devtools (no dotted interpolation there) — see step 10. The capture → draft → replay → prove loop in between is identical, and OPRF is optional and supported in both.
 
 ## Getting authenticated
 
@@ -42,7 +42,7 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
 2. Tell the user: _"Open `<attachUrl>`, sign in, and click 'Authorize this device'."_
 3. After they confirm, call `authenticate({ code: "<code>" })`: `LINKED` → proceed; `PENDING` → wait and call again; `EXPIRED` → start a new session.
 
-The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (`RECLAIM_API_TOKEN` in the server env overrides it). To link an ETH credential to an org: `list_orgs` (ask which), then `link_credential({ address: "0x...", orgId })` — only needed to use the credential in production.
+The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (`RECLAIM_API_TOKEN` in the server env overrides it).
 
 ## The loop
 
@@ -144,16 +144,30 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
    - Do not hand-write a named-capture regex unless `hash` was requested AND the synthesizer's output doesn't already have one. (It will, for any digit/slug/email-shaped target.)
    - Do not remove `paramValues` — that's how the template resolves at proof time.
    - The redaction's xPath/jsonPath is what the prover reveals; the match's template is what the attestor verifies post-substitution. They serve different purposes — don't conflate them.
+   - Do not prefix the match-template's param with `context.`/`context_` — that namespace is reserved for consumer-supplied URL/body params (step 10). Match templates are extraction params and stay bare.
 
    Permitted edits: narrowing the `contains` template, picking a more distinctive xPath class/id if the synthesizer's pick is too generic, fixing the `name` field, adding/removing secret headers. If you're tempted to rewrite the provider from scratch, call `propose_provider` again with different inputs instead.
 
-10. **Parameterize user-specific URL segments** so the provider isn't user-specific at the URL level. The matcher already populates `paramValues` with the _captured value_ (e.g. `{username: "Scratch-net"}` for a username target). If the URL ALSO contains user-identifying segments, add those as additional paramValues entries:
+10. **Parameterize user-specific URL segments** so the provider isn't user-specific at the URL level. The matcher already populates `paramValues` with the _captured value_ (e.g. `{username: "Scratch-net"}` for a username target). If the URL ALSO contains user-identifying segments, those are **consumer-supplied context params** — at verification time their values come from the Consumer's session `context`, not from extraction. They use a namespaced placeholder, and the namespace differs by mode:
 
-- Path segments that identify the dev (username, user-id, slug) → replace with `{{name}}`. E.g. `https://github.com/Scratch-net/repos` → `https://github.com/{{username}}/repos`, with `paramValues: { ..., username: "Scratch-net" }` (extending the matcher's existing entry, not replacing it).
+- **Builder mode:** replace with `{{context.<name>}}`. E.g. `https://github.com/Scratch-net/repos` → `https://github.com/{{context.username}}/repos`, with `paramValues: { ..., "context.username": "Scratch-net" }` for replay/proof (the paramValues key must match the placeholder name exactly, dot included). Declare these in the version's `requiredContext` at publish time (step 13).
+- **Old devtools mode:** same idea, but the legacy backend doesn't support dotted interpolation — use `{{context_<name>}}` and `paramValues: { ..., "context_username": "Scratch-net" }`.
 - Query parameters with user-specific values → same treatment.
 - Generic segments (`/api/v3`, `/users`, `/repos`) stay literal.
 - If the URL has no user-identifying segments (e.g. `/settings/profile`), leave it untouched — the matcher already handled the value via paramValues.
 
+**Do not rename the match-template param.** The synthesizer's `{{name}}` in `responseMatches[].value` is an _extraction_ template (the attestor pulls the value out of the response) — it stays bare and never gets the `context.` prefix. Only URL/body placeholders whose values the Consumer must supply are context params.
+
+**How the verification client resolves these at runtime** (builder mode — use this to make the context-vs-bare call):
+
+- Requests are matched by **exact origin+path** (query ignored). A `{{context.<name>}}` segment matches **only the value the consumer sent** in the session context (validated by `requiredContext`); a bare `{{name}}` segment matches any one path segment and its value is **auto-extracted from the live traffic**.
+- Interpolation and `contains` matching are **plain text** — they work for any captured content (JSON, XML, HTML, form-encoded bodies, …).
+- Extract selectors apply **client-side in spec order xPath → jsonPath → regex**, each to the prior selection — so only the FIRST selector constrains the full response (an `xPath`→`jsonPath` chain reads JSON embedded in an HTML page; a jsonPath-first extract needs the whole response to be JSON). Only the selected portions reach the attestor.
+- A matched response that can't satisfy the recipe is **skipped**, not failed: the first selector can't operate on it (e.g. jsonPath-first against the HTML navigation of a URL whose JSON XHR was captured), or a required `contains` match is missing. The VC keeps polling for a satisfying request until timeout.
+- So: choose `{{context.<name>}}` when the consumer knows the value up front and the proof should be **pinned to it**; keep it bare when the value should come from whatever the logged-in user's traffic shows.
+
+`propose_provider` returns `verificationWarnings` for the calls only an author can make (currently: a captured value baked literally into the URL, needing the `{{context.<name>}}`-vs-bare-vs-re-capture decision). They are advisory, never blocking — **surface each warning to the dev verbatim** and resolve it before publishing.
+
 11. **Replay.** Call `replay_request(provider, secretParamsRef)`. Three outcomes:
 
 - `matchesOriginal: true` → proceed.
@@ -167,7 +181,7 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
 12. **Prove.** Call `run_proof(provider, secretParamsRef)`. On `verified: true`, the full claim has been written to `~/.reclaim/claims/<timestamp>.json` and the tool returns `{verified, extractedValue, extractedParameters, identifier, owner, claimPath, claim}`. The `claim` field is a display-ready version of the proof — its huge `request` payload has been stripped and all byte arrays converted to base64, so it renders cleanly. **Show it to the dev as a fenced JSON code block at the end** along with the provider JSON. That's the final result. On `verified: false`, diagnose using the returned error and iterate.
 
-    **Missing signing credential (`errorKind: "missing-owner-key"`)** — the dev hasn't set up a credential yet. Tell them what's happening, then drive the bootstrap yourself: call `list_cached_credentials` to see if anything's already cached; if not, ask once _"shall I mint a fresh credential via `issue_credentials`? Persisted to `~/.reclaim/config.json` for this and future sessions."_; on yes, call `issue_credentials` and retry the same `run_proof` call. **No restart needed** — the credential is read live from the cache on each `run_proof`, and the existing `secretParamsRef` from `propose_provider` is still valid.
+    **Missing signing credential (`errorKind: "missing-owner-key"`)** — the dev hasn't set up an eth proof-owner key yet. Tell them what's happening, then drive the bootstrap yourself: call `resolve_owner_key`; if it returns no key, ask once _"shall I mint a fresh eth key via `issue_credentials` (or `import_credentials` if you already hold one)? It's written to the project `.env` (mode 0600, gitignored) for this and future sessions."_; on yes, call `issue_credentials` (or `import_credentials`) and retry the same `run_proof` call. **No restart needed** — the key is read live from `.env` on each `run_proof`, and the existing `secretParamsRef` from `propose_provider` is still valid.
 
     **On any `verified: false` response, the result includes (inline):**
     - `error` — the SDK's thrown error message verbatim
@@ -191,11 +205,18 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
     - **New version of an existing verification:** pass its `providerId` — the patch is auto-bumped above the highest existing version. Pass `notes` (≥10 chars) as the change note.
     - `get_me_providers({ searchQuery? })` lists the verifications you own — use it to find a `providerId` or to confirm the result. It's the only provider-listing tool in this mode.
     - There's no separate "create-then-version" step and no org / public-review workflow here.
+    - Consumer-supplied params (step 10) keep the `{{context_<name>}}` form in this mode; there is no `requiredContext` declaration on the legacy backend.
 
     **Builder mode:**
     1. **Create the verification if it doesn't exist:** `create_verification(orgId, domain, slug, title, description)` — find `orgId` via `list_orgs`. `domain` e.g. `github.com`; `slug` e.g. `github-username`; `title` e.g. "GitHub Username". Starts PRIVATE with an empty seed version. Skip if the dev already has a `providerId`.
-    2. **Persist the version:** `create_provider_version_from_capture(providerId, provider, initialUrl, notes)` — `notes` e.g. `"Initial draft from browser capture"`. PRIVATE → live immediately; PUBLIC → lands on the `draft` branch.
-    3. **For PUBLIC verifications:** `submit_provider_version_for_review(providerId, version)` (the semver returned above). Tell the dev it's awaiting admin review.
+    2. **Persist the version:** `create_provider_version_from_capture(providerId, provider, initialUrl, notes)` — `notes` e.g. `"Initial draft from browser capture"`. The version lands on the `draft` branch.
+    3. **`requiredContext` is derived for you.** The publish tool scans the recipe's url/body for `{{context.<name>}}` placeholders (step 10) and emits a JSON Schema requiring each one — the Builder then validates every session-create's `context` against it (a clear 400 instead of a late attestor failure). Extra context fields are always allowed. The derived properties are plain strings; to refine types or add human-readable descriptions, call `update_provider_version` with a `requiredContext` override while the version is on `draft`, e.g.:
+
+       ```json
+       { "requiredContext": { "type": "object", "required": ["username"], "properties": { "username": { "type": "string", "description": "GitHub username to verify" } } } }
+       ```
+    4. **Go live:** PRIVATE → `publish_provider_version`; PUBLIC → `submit_provider_version_for_review(providerId, version)` and tell the dev it's awaiting admin review.
+    5. **Tell the dev how consumers call it:** sessions for this verification must include the context params, e.g. `context: { "username": "..." }` in `POST /verifications/sessions`. Quote the `requiredContext` returned on the created version — a session missing those fields gets a 400, and verification matches the supplied values exactly.
 
     When done, tell the developer the version is live (PRIVATE) or submitted for review (PUBLIC), and that they can integrate using the `providerId`.
 
@@ -225,17 +246,17 @@ If `attach_chrome` errors, times out, or `waitForCdpReady` reports the port isn'
 - **Pre-existing `chrome.exe` processes hijack the new launch (Windows).** If any Chrome is already running, a new launch with `--remote-debugging-port` gets delegated to the existing process group and the debug port silently doesn't open. Tell the dev to kill all `chrome.exe` first (`taskkill /F /IM chrome.exe` in cmd/PowerShell, or via Task Manager), then retry. Affects both `attach` and `dedicated` modes when the existing instance was launched with the same profile dir.
 - **Chrome 136+ silently disables remote debugging on the default user profile.** Already noted in step 1, but worth raising again here: the only fix is a non-default `--user-data-dir`. `dedicated` mode is always safe; `attach` mode needs the dev to have launched with both flags.
 
-**Credential for signing the proof.** `run_proof` requires an `ownerAddress` — the app credential whose key signs the claim. It does **no** resolution itself; get the address from `resolve_owner_key` first. The private key is resolved locally (cache → env → `.env`) and never enters the conversation.
+**Credential for signing the proof.** `run_proof` requires an `ownerAddress` — the eth proof-owner key whose private half signs the claim. It does **no** resolution itself; get the address from `resolve_owner_key` first. The private key is resolved locally (`RECLAIM_PRIVATE_KEY` env → a `RECLAIM_PRIVATE_KEY=0x…` line in the project `.env` → a file at `RECLAIM_PRIVATE_KEY_FILE`) and never enters the conversation.
 
-1. **Call `resolve_owner_key`.** It checks `RECLAIM_PRIVATE_KEY` (MCP env) → the project `.env` → the best cached credential for this directory.
+1. **Call `resolve_owner_key`.** It checks `RECLAIM_PRIVATE_KEY` (MCP env) → the project `.env` → `RECLAIM_PRIVATE_KEY_FILE`, and returns only the derived address.
    - `{ ready: true, address }` → call `run_proof({ provider, ownerAddress: address, … })`. No prompts.
-   - `{ ready: false }` → no credential exists yet. Ask the dev once how to set one up:
-     - **Provide their own key** → `import_credentials({ privateKey: "0x…" })`.
+   - `{ ready: false }` → no key exists yet. Ask the dev once how to set one up:
+     - **Provide their own key** → `import_credentials({ privateKey: "0x…" })` (also accepts a `keyFile` path).
      - **Create a new one** → `issue_credentials({})`. (Fine default for test proofs — owner identity doesn't matter.)
-     - **Persist or memory-only?** Writing the key to `.env` is opt-in — **never write `.env` without asking.** Pass `writeEnv: false` to keep it in the local cache (memory) only. Either way it's cached, so `resolve_owner_key` finds it next.
+     - Either way the key is written to the project `.env` (mode 0600; `.env` is added to `.gitignore`) — never to `~/.reclaim`.
    - Then call `resolve_owner_key` again and `run_proof` with the returned address.
-2. All fully local — no network, no server registration. `list_cached_credentials` shows what's cached if the dev wants to pick a specific one.
-- **Advanced:** setting `RECLAIM_PRIVATE_KEY` directly in the MCP server's env also works, but env vars are snapshotted at Claude Code startup, so that route needs a full restart (which invalidates every `secretParamsRef`). The cache/`.env` flow above avoids that — prefer it.
+2. All fully local — no network, no server registration. The key is read live from `.env` on each `run_proof`, so no restart is needed after issuing/importing.
+- **Advanced:** setting `RECLAIM_PRIVATE_KEY` directly in the MCP server's env also works, but env vars are snapshotted at Claude Code startup, so that route needs a full restart (which invalidates every `secretParamsRef`). The `.env` flow above avoids that — prefer it.
 - **Multiple MCP config files exist on Windows.** `~/.claude.json` takes precedence over `~/.claude/mcp.json`. When advising config edits, point them at the right file or tell them to use `claude mcp list` / `claude mcp add --scope user` rather than editing JSON by hand.
 
 If `replay_request` or `run_proof` errors with `unknown secretParamsRef`:

package/skill/builder-mode.md

@@ -0,0 +1,9 @@
+This server targets the Reclaim BUILDER backend. It exposes three tool layers: generated API tools (one per builder operation, snake_case), credential/verification helpers, and browser agent tools (CDP capture, synthesis, replay, proof).
+
+**Authentication:** try `get_me` first. On 401, `authenticate({})` opens a device-pairing session — give the user the `attachUrl`, then poll `authenticate({ code })` until LINKED. Tokens are cached ~2 days.
+
+**Provider-authoring flow:** `attach_chrome` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`) → `propose_provider` → `replay_request` → `run_proof` → `create_provider_version_from_capture` (lands on the draft branch) → `publish_provider_version` (PRIVATE) or `submit_provider_version_for_review` (PUBLIC).
+
+**Templating:** bare `{{name}}` placeholders are provider params (values extracted from the response by the attestor). Values the CONSUMER must supply at verification time (e.g. a username in the URL path) are templated `{{context.<name>}}` and declared on the version as `requiredContext` — a JSON Schema set via `update_provider_version` while the version is on draft. The Builder validates every session-create's `context` against it (400 on mismatch; extra context fields are always allowed). `requiredContext` is optional — skip it when the recipe has no `{{context.*}}` placeholders. At verification time, requests are matched by exact origin+path: `{{context.<name>}}` segments match the consumer-sent value only, bare `{{name}}` values are extracted from the live traffic (plain-text alignment — works for JSON, XML, HTML, form-encoded, any text). Extract selectors apply client-side in spec order xPath → jsonPath → regex, each to the prior selection, so only the first selector constrains the full response; responses that cannot satisfy it (or miss a required match) are skipped. `propose_provider` returns advisory `verificationWarnings` for author-only decisions — surface them to the dev before publishing.
+
+**Verification sessions:** consumers authenticate with a per-org token (`rorg_…`, issued in the dashboard via `POST /orgs/{orgId}/token`) and create sessions via `POST /verifications/sessions`. Results are JWE-encrypted (ECDH-ES + A256GCM over X25519) to the org's single encryption credential — set via `PUT /orgs/{orgId}/credential` with an X25519 public JWK — and delivered to the org's callback subscriptions (plaintext when no credential is set). Use the org/session tools (`get_verification_session`, `list_verification_events`, `list_org_verification_sessions`) to troubleshoot.

package/skill/old-mode.md

@@ -0,0 +1,13 @@
+This server is running against the LEGACY Reclaim devtools backend (temporary, while the new builder backend is in development), so its capabilities are intentionally limited.
+
+**Provider-authoring flow:**
+
+1. `reclaim_authenticate` — by default opens the dashboard in Chrome, waits for you to sign in, captures the token automatically, and closes the tab (or paste a `token` / pass an eth `ethAddress` to skip the browser). Do this once before publishing or listing.
+2. `attach_chrome` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`).
+3. `propose_provider` to draft a provider, `replay_request` to pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` redactions are optional and supported.
+4. `create_provider_version_from_capture` to publish. With NO `providerId` it REGISTERS A NEW provider (re-running creates a duplicate); pass a `providerId` from `get_me_providers` to add a new version to an existing provider instead.
+5. `get_me_providers` lists the providers you own (the only provider-listing tool available in this mode).
+
+Only GET/POST endpoints can be captured into providers here. There is no organization, credential-linking, or public-review workflow in this mode.
+
+**Templating:** bare `{{name}}` placeholders are provider params (values extracted from the response). Values the CONSUMER must supply at verification time (e.g. a username in the URL path) use the `{{context_<name>}}` form — this backend does not support the dotted `{{context.<name>}}` interpolation the new builder uses.

package/src/cdp/capture-engine.ts

@@ -0,0 +1,256 @@
+/**
+ * Transport-agnostic CDP Network → CapturedRequest state machine. The agent
+ * (local CDP, page-level `Network.*` bindings) and the app (remote Popcorn,
+ * events read off a session-filtered `event` stream) share this entire engine;
+ * only how events are delivered and how a response body is fetched differ, so
+ * those two are injected. See `cdp/capture.ts` and the app's
+ * `capture/capture.ts` for the two thin transports that wire into it.
+ */
+import { randomUUID } from 'node:crypto'
+import { extractGraphqlOp } from '../provider/graphql.ts'
+import type { CapturedRequest } from '../provider/schema.ts'
+import { BodyStore } from './eviction.ts'
+
+/** The slice of CDP `Network.requestWillBeSent` the engine reads. Kept
+ *  structural — not devtools-protocol's full event type — so a transport
+ *  pinned to a different devtools-protocol version still satisfies it. */
+export interface RequestWillBeSentLike {
+	requestId: string
+	request: {
+		method: string
+		url: string
+		headers: Record<string, string>
+		postData?: string
+	}
+}
+
+/** The slice of CDP `Network.responseReceived` the engine reads. */
+export interface ResponseReceivedLike {
+	requestId: string
+	response: {
+		status: number
+		mimeType: string
+		encodedDataLength: number
+		headers: Record<string, string>
+	}
+}
+
+/** Drop HTTP/2 pseudo-headers (`:authority`, `:method`, `:path`, `:scheme`,
+ *  `:status`) from a CDP header map. Chrome emits them on HTTP/2 requests,
+ *  but they're a transport-layer abstraction with no place in our domain:
+ *  the URL already carries authority/path/scheme, the request object carries
+ *  method, and Node's `fetch` (undici) throws on any header starting with
+ *  `:`. Stripping at capture time keeps every downstream consumer
+ *  (`get_request`, draft, replay, proof) clean by construction. */
+export function stripPseudoHeaders(
+	headers: Record<string, string>,
+): Record<string, string> {
+	const out: Record<string, string> = {}
+	for(const [k, v] of Object.entries(headers)) {
+		if(!k.startsWith(':')) {
+			out[k] = v
+		}
+	}
+
+	return out
+}
+
+export interface CaptureSession {
+	captureId: string
+	requests: Map<string, CapturedRequest>
+	bodies: BodyStore
+	stop: () => Promise<void>
+}
+
+/** Public knobs a transport accepts; mapped into `CaptureEngineOptions`. */
+export interface StartCaptureOptions {
+	maxBodyBytes?: number
+}
+
+export interface CaptureEngineOptions {
+	maxBodyBytes?: number
+	/** Fetch a finished response body. Transport-specific: the agent calls
+	 *  `Network.getResponseBody` on the page binding, the app routes the
+	 *  command through its Popcorn session. */
+	fetchBody: (
+		requestId: string,
+	) => Promise<{ body: string, base64Encoded: boolean }>
+}
+
+interface InFlight {
+	requestId: string
+	method: string
+	url: string
+	requestHeaders: Record<string, string>
+	requestBody?: string
+	startedAt: number
+}
+
+/** The engine state plus the handlers a transport drives. A transport feeds
+ *  raw CDP events into these and exposes `captureId`/`requests`/`bodies` to
+ *  its caller. */
+export interface CaptureEngine {
+	captureId: string
+	requests: Map<string, CapturedRequest>
+	bodies: BodyStore
+	onRequestWillBeSent: (p: RequestWillBeSentLike) => void
+	mergeRequestHeaders: (
+		requestId: string,
+		extra: Record<string, string>,
+	) => void
+	onResponseReceived: (p: ResponseReceivedLike) => void
+	mergeResponseHeaders: (
+		requestId: string,
+		extra: Record<string, string>,
+	) => void
+	onLoadingFinished: (requestId: string) => Promise<void>
+}
+
+export function createCaptureEngine(opts: CaptureEngineOptions): CaptureEngine {
+	const captureId = randomUUID()
+	const requests = new Map<string, CapturedRequest>()
+	const inFlight = new Map<string, InFlight>()
+	const bodies = new BodyStore({
+		maxBytes: opts.maxBodyBytes ?? 200 * 1024 * 1024,
+	})
+	// CDP doesn't guarantee `requestWillBeSent` arrives before
+	// `requestWillBeSentExtraInfo` (same for the response pair). When extra
+	// info lands first, buffer it here and drain on the matching primary
+	// event. Without this, headers (Cookie, Authorization, …) get silently
+	// dropped for any request whose events race in the unlucky order.
+	const pendingRequestExtra = new Map<string, Record<string, string>>()
+	const pendingResponseExtra = new Map<string, Record<string, string>>()
+
+	return {
+		captureId,
+		requests,
+		bodies,
+		onRequestWillBeSent,
+		mergeRequestHeaders,
+		onResponseReceived,
+		mergeResponseHeaders,
+		onLoadingFinished,
+	}
+
+	/** Merge extra headers from the ...ExtraInfo events into either the
+	 *  in-flight entry or the finalized captured request, whichever has
+	 *  arrived. If neither exists yet (extra-info-first race), buffer the
+	 *  headers and drain on the matching primary event. */
+	function mergeRequestHeaders(
+		requestId: string,
+		extra: Record<string, string>,
+	) {
+		const clean = stripPseudoHeaders(extra)
+		const f = inFlight.get(requestId)
+		if(f) {
+			f.requestHeaders = { ...f.requestHeaders, ...clean }
+			return
+		}
+
+		const r = requests.get(requestId)
+		if(r) {
+			r.requestHeaders = { ...r.requestHeaders, ...clean }
+			return
+		}
+
+		const buffered = pendingRequestExtra.get(requestId) ?? {}
+		pendingRequestExtra.set(requestId, { ...buffered, ...clean })
+	}
+
+	function mergeResponseHeaders(
+		requestId: string,
+		extra: Record<string, string>,
+	) {
+		const clean = stripPseudoHeaders(extra)
+		const r = requests.get(requestId)
+		if(r) {
+			r.responseHeaders = { ...r.responseHeaders, ...clean }
+			return
+		}
+
+		const buffered = pendingResponseExtra.get(requestId) ?? {}
+		pendingResponseExtra.set(requestId, { ...buffered, ...clean })
+	}
+
+	function onRequestWillBeSent(p: RequestWillBeSentLike) {
+		const f: InFlight = {
+			requestId: p.requestId,
+			method: p.request.method,
+			url: p.request.url,
+			requestHeaders: stripPseudoHeaders(p.request.headers),
+			startedAt: Date.now(),
+		}
+		if(p.request.postData !== undefined) {
+			f.requestBody = p.request.postData
+		}
+
+		// Drain any extra-info that arrived before us.
+		const buffered = pendingRequestExtra.get(p.requestId)
+		if(buffered) {
+			f.requestHeaders = { ...f.requestHeaders, ...buffered }
+			pendingRequestExtra.delete(p.requestId)
+		}
+
+		inFlight.set(p.requestId, f)
+	}
+
+	function onResponseReceived(p: ResponseReceivedLike) {
+		const f = inFlight.get(p.requestId)
+		if(!f) {
+			return
+		}
+
+		const captured: CapturedRequest = {
+			requestId: p.requestId,
+			method: f.method,
+			url: f.url,
+			status: p.response.status,
+			contentType: p.response.mimeType,
+			size: p.response.encodedDataLength,
+			requestHeaders: f.requestHeaders,
+			responseHeaders: stripPseudoHeaders(p.response.headers),
+			finishedAt: 0,
+		}
+
+		// Drain any response extra-info that arrived before us.
+		const bufferedResp = pendingResponseExtra.get(p.requestId)
+		if(bufferedResp) {
+			captured.responseHeaders = {
+				...captured.responseHeaders,
+				...bufferedResp,
+			}
+			pendingResponseExtra.delete(p.requestId)
+		}
+
+		if(f.requestBody !== undefined) {
+			captured.requestBody = f.requestBody
+		}
+
+		const op = extractGraphqlOp(f.requestBody)
+		if(op !== undefined) {
+			captured.graphqlOp = op
+		}
+
+		requests.set(p.requestId, captured)
+	}
+
+	async function onLoadingFinished(requestId: string) {
+		const r = requests.get(requestId)
+		if(!r) {
+			return
+		}
+
+		try {
+			const { body, base64Encoded } = await opts.fetchBody(requestId)
+			const text = base64Encoded
+				? Buffer.from(body, 'base64').toString('utf8')
+				: body
+			bodies.set(requestId, text)
+			r.responseBody = text
+			r.finishedAt = Date.now()
+		} catch{
+			// Body might be unavailable for
+			// some content-types (e.g. websocket). Skip.
+		}
+	}
+}