@reclaimprotocol/agent 0.1.23 → 0.1.25

package/README.md

@@ -1,6 +1,6 @@
 # @reclaimprotocol/agent
 
-Reclaim Protocol lets your app verify **data points** about its users — a follower count, an account balance, an order history. This package gives your AI coding agent the tools to **find, build, test and fix the _data verification providers_** (the recipes that verify a data point) by inspecting and replaying captured requests, checking sessions, evaluate proofs, publishing updates, and much more.
+Reclaim Protocol lets your app verify **data points** about its users — a follower count, an account balance, an order history. This package gives your AI coding agent the tools to find, build, test, and fix **data verification providers**: the recipes that verify a data point. With it, your agent inspects and replays captured requests, checks verification sessions, evaluates proofs, and publishes provider updates.
 
 Under the hood it's Chrome-CDP + zkTLS provider-authoring tooling: it captures network traffic from a browser, synthesizes provider definitions from it (`contains` matchers + `jsonPath` / `xPath` / `regex` redactions), runs a local replay diagnostic, and produces a verified attestor proof via `@reclaimprotocol/attestor-core`.
 
@@ -8,9 +8,14 @@ This package **is** the Reclaim MCP server (bin: `reclaim-mcp-server`). It depen
 
 ## Install
 
-**Prerequisites:** **Node ≥ 20** — **works best on a current LTS release (22 or 24)** — and a local Chrome / Chromium / Edge (used for capture and the dashboard login). The first time you call `run_proof`, the agent downloads the ZK circuit files it needs (~280 MB) — so allow a moment for that first proof. The download is deferred to first proof on purpose (not an install step), so the MCP server itself starts immediately.
+**Prerequisites:**
 
-> **Any Node ≥ 20 works, including non-LTS lines like 25** however an LTS line (22 or 24) is *recommended*.
+- **Node 20 or later.** Any line works, including non-LTS ones such as 25, but a current LTS line (22 or 24) is recommended.
+- **A local Chrome, Chromium, or Edge**, used for capture and for the dashboard login.
+- **Docker** — only for `attach_browser`'s `container` mode, which runs the Reclaim browser runtime (the same image the hosted browser uses) and gives you a link you can send to whoever holds the account. It is the free way to get that link; the hosted remote browser is the other, and it is chargeable. Not needed if you are doing the work yourself. The image is amd64, so Apple Silicon runs it translated. OrbStack handles that itself; Docker Desktop needs Rosetta enabled. `RECLAIM_BROWSER_RUNTIME_IMAGE` overrides the pinned digest.
+- **`cloudflared`** — not required up front. `share_browser_view` uses an existing install if one is on `PATH`, and otherwise downloads it once to `~/.reclaim/bin` on first share (never at install time). Set `RECLAIM_CLOUDFLARED_PATH` to point at your own copy.
+
+The first time you call `run_proof`, the agent downloads the ZK circuit files it needs (about 280 MB), so allow a moment for that first proof. The download is deferred to the first proof rather than run at install time, so the MCP server itself starts immediately.
 
 It runs as a **stdio MCP server**. Point any MCP-capable agent at this command:
 
@@ -48,24 +53,24 @@ See [Backends](#backends) for builder mode (`USE_OLD_DEVTOOLS=false`) and the fu
 
 ### Provider-authoring guide
 
-The MCP server is all you need — it ships a `how_it_works` tool that returns the full capture → prove → publish guide (login detection, choosing auth-bound endpoints, OPRF decisions, troubleshooting). Any MCP client can call it on demand; there's nothing extra to install.
+The MCP server is all you need — it ships a `how_it_works` tool that serves the capture → prove → publish guide **one topic at a time** (`overview`, `auth`, `browser`, `capture`, `draft`, `params`, `prove`, `publish`, `discover`, `user-script`, `interception`, `hash-validation`, `credentials`, `never-do`, `troubleshooting`). Call it with no arguments for the overview plus the topic index; every response repeats that index, so an agent that guessed wrong self-corrects without a second round-trip. Any MCP client can call it on demand; there's nothing extra to install.
 
 ## Using it from your agent
 
 Tip: have your agent call the `how_it_works` tool first so it follows the full authoring flow.
 
-Then just ask in plain language, e.g.:
+Then ask in plain language. For example:
 
 > "Use Reclaim to create a provider that proves my GitHub follower count."
 
-or you can even ask it like:
+Or more loosely:
 
 > "I want to verify Github follow count"
 
 The agent orchestrates the tools for you:
 
 1. **`reclaim_authenticate`** — a Chrome window opens the Reclaim dashboard; you sign in. The token is captured automatically and the tab closes. (Or it reuses a still-valid cached identity.)
-2. **`attach_browser` + `navigate`** — uses local Chrome, a Builder-hosted remote browser, or a custom CDP websocket; **`wait_for_page`** waits while the operator logs in.
+2. **`attach_browser` + `navigate`** — uses local Chrome, a Builder-hosted remote browser, or a custom CDP websocket; **`wait_for_page`** waits while you log in.
 3. **`start_capture` → `find_requests_containing` → `get_request`** — records network traffic and locates the request carrying your value.
 4. **`propose_provider`** — drafts the provider (a `contains` match + `jsonPath`/`xPath`/`regex` redaction), keeping any secret headers server-side.
 5. **`replay_request` → `run_proof`** — pre-flights the draft, then produces a verified zkTLS proof via the attestor.
@@ -75,7 +80,7 @@ Your only manual steps are signing in when the browser windows open and confirmi
 
 ## How it works (guide tool)
 
-The full, mode-aware authoring guide (`skill/SKILL.builder.md` / `skill/SKILL.old.md`, one per backend) is served on demand by the **`how_it_works`** MCP tool — call it from any MCP client (Claude Code, Cursor, opencode, Antigravity, …) to get the deep capture → prove → publish workflow, decision frameworks, and troubleshooting. The server's always-on `instructions` cover the essentials; `how_it_works` is the in-depth version, with nothing to install.
+The mode-aware authoring guide (`skill/SKILL.builder.md` / `skill/SKILL.old.md`, one per backend) is served on demand by the **`how_it_works`** MCP tool — call it from any MCP client (Claude Code, Cursor, opencode, Antigravity, …) to get the deep capture → prove → publish workflow, decision frameworks, and troubleshooting. It is served per topic rather than all at once, so pulling one answer costs a fraction of the guide. The server's always-on `instructions` cover the essentials; `how_it_works` is the in-depth version, with nothing to install.
 
 ## Provider-authoring tools
 
@@ -83,20 +88,20 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 
 | Tool                                        | Purpose                                                                                                        |
 | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `attach_browser`                            | Connect via local Chrome, Builder-hosted Popcorn with a shareable live view, or a custom CDP websocket          |
-| `attach_chrome`                             | Backward-compatible alias for `attach_browser`                                                                  |
+| `attach_browser`                            | Connect to a browser. Grouped by use case: working alone → local Chrome (launched, or the one already open); someone else has to sign in → the Reclaim runtime in Docker (free) or a hosted remote browser (chargeable). The tool description asks which case applies before listing anything, so an agent can put the choice to the developer and connect in one call |
 | `list_tabs`                                 | List open Chrome tabs                                                                                          |
 | `navigate`, `wait_for_page`, `eval_in_page` | Drive the tab; poll for login completion                                                                       |
 | `start_capture`, `stop_capture`             | Network capture lifecycle                                                                                      |
 | `list_requests`, `get_request`              | Inspect captured traffic                                                                                       |
 | `find_requests_containing`                  | Deterministic search for a target value across captured responses                                              |
-| `analyze_request_constraints`               | Flag concerns (signed, csrf, graphql, etc.)                                                                    |
+| `analyze_request_constraints`               | Flag concerns: signed request, CSRF dependency, bot challenge, short-lived token, GraphQL |
 | `propose_provider`                          | Synthesize a provider — `contains` match + `jsonPath`/`xPath`/`regex` redaction                                |
 | `replay_request`                            | Pre-flight replay via Node `fetch` (no attestor); also used for auth-bound check by omitting `secretParamsRef` |
 | `run_proof`                                 | End-to-end zkTLS proof through the attestor SDK                                                                |
 | `create_provider_version_from_capture`      | Publish a drafted provider to the backend                                                                      |
 | `authenticate_builder`                      | In old-devtools mode only, sign in to Builder for remote-browser allocation                                   |
 | `list_builder_organizations`                | In old-devtools mode only, list organization ids for a quota-accounted Builder browser                         |
+| `share_browser_view`, `stop_browser_view`   | Put the `container` browser's own live view behind a public HTTPS URL (cloudflared quick tunnel), so someone elsewhere can watch it and act in it — from a phone if they like. Container mode only: a `builder` browser already returns a hosted `liveViewUrl`, and a plain local browser has no view to share |
 | `dispose_browser`                           | Stop captures, disconnect CDP, and immediately release a Builder-hosted browser                               |
 | `get_session`, `reset_session`              | Session state                                                                                                  |
 
@@ -114,7 +119,7 @@ Relevant env vars: `RECLAIM_OLD_API_URL` (default `https://devapi.reclaimprotoco
 
 ## Local development (from source)
 
-For working on the package inside the monorepo (consumers should use [Install](#install) instead). A workspace install just fetches dependencies:
+For working on the package inside the monorepo (consumers should use [Install](#install) instead). A workspace install only fetches dependencies:
 
 ```bash
 npm install
@@ -128,14 +133,18 @@ npm run download:zk-files --workspace=packages/agent
 
 ## Platform notes
 
-- **Node >=20** is required to run the published package (declared in `engines`) — it ships compiled `lib/*.js`, so no TypeScript type-stripping is needed at runtime. Any line ≥ 20 works, including non-LTS like 25: the one native addon that used to break this, `re2`, is an **optional** dependency as of `@reclaimprotocol/attestor-core` 5.0.8 and degrades to native `RegExp` when its binary is absent. (The other native dep, `koffi`, is N-API — ABI-independent, all-platform prebuilts — so it was never version-sensitive.) An LTS line (22/24) is recommended so `re2` is present for faster, ReDoS-safe matching. Working on the package **from a checkout** additionally needs **Node >=22.18**, because the test suite and dev workflow run bare `.ts` files directly and unflagged TypeScript type-stripping landed in 22.18.
+- **Node 20 or later** is required to run the published package (declared in `engines`). The package ships compiled `lib/*.js`, so no TypeScript type-stripping is needed at runtime.
+
+  Any line works, including non-LTS ones such as 25. The one native addon that used to break this, `re2`, became an **optional** dependency in `@reclaimprotocol/attestor-core` 5.0.8 and degrades to the native `RegExp` when its binary is absent. The other native dependency, `koffi`, is N-API, so it ships ABI-independent prebuilts for every platform and was never version-sensitive. An LTS line (22 or 24) is still recommended, because `re2` is present there and gives faster, ReDoS-safe matching.
+
+  Working on the package **from a checkout** additionally needs **Node 22.18 or later**: the test suite and the dev workflow run bare `.ts` files directly, and unflagged TypeScript type-stripping landed in 22.18.
 - **Chrome 136+ silently disables `--remote-debugging-port`** when launched against the default user profile. `dedicated` mode (the default) sidesteps this by always passing `--user-data-dir=~/.reclaim/chrome-profile`.
 
 ## Tests
 
-`npm test` runs the unit + integration suite (no Chrome needed).
+`npm test` runs the unit and integration suite. Chrome isn't needed.
 
-The Chrome CDP end-to-end test at `tests/e2e-chrome.test.ts` is gated behind an env var. It launches headless Chrome with a dedicated temp profile, captures a navigation against a local fixture server, and asserts the synthesiser finds the right request. To run it:
+The Chrome CDP end-to-end test at `tests/e2e-chrome.test.ts` is gated behind an env var. It launches headless Chrome with a dedicated temp profile, captures a navigation against a local fixture server, and asserts the synthesizer finds the right request. To run it:
 
 ```bash
 # bash / macOS / Linux
@@ -145,11 +154,11 @@ RECLAIM_AGENT_E2E=1 npm test --workspace=packages/agent
 $env:RECLAIM_AGENT_E2E=1; npm test --workspace=packages/agent
 ```
 
-Requires Chrome / Chromium / Edge installed somewhere `findChromeBinary` can locate (or `RECLAIM_AGENT_CHROME_PATH` set). The test self-skips if no binary is found.
+The test requires Chrome, Chromium, or Edge installed somewhere `findChromeBinary` can locate it, or `RECLAIM_AGENT_CHROME_PATH` pointing at the binary. It self-skips when no binary is found.
 
-## Disabling
+## Disable the browser tools
 
-The MCP server registers the provider-authoring (Chrome/CDP) tools by default in both modes. To disable them (e.g. in hosted deployments where no local Chrome is available):
+The MCP server registers the provider-authoring (Chrome and CDP) tools by default in both modes. To disable them — for example, in a hosted deployment with no local Chrome — set:
 
 ```bash
 RECLAIM_AGENT_DISABLED=1
@@ -203,8 +212,35 @@ claude mcp add reclaim -- node "$(pwd)/packages/agent/lib/mcp-bin.js"
 }
 ```
 
-To target a specific backend while developing, add an `env` block (Claude Code / `.mcp.json`) or `environment` (opencode) — e.g. `"USE_OLD_DEVTOOLS": "false"` for builder mode. See [Backends](#backends).
+To target a specific backend while developing, add an `env` block (Claude Code / `.mcp.json`) or `environment` (opencode) — for example, `"USE_OLD_DEVTOOLS": "false"` for builder mode. See [Backends](#backends).
 
 ### Authoring guide
 
-`skill/SKILL.builder.md` and `skill/SKILL.old.md` are the sources the `how_it_works` tool serves — one per backend, so an agent is never shown tools its mode doesn't have. The server picks by `USE_OLD_DEVTOOLS`. Edit the relevant file and rebuild (`npm run build`) to update what the tool returns.
+Everything the `how_it_works` tool serves lives in `skill/` as markdown — edit it and rebuild (`npm run build`) to change what the tool returns.
+
+| file | what it is |
+| --- | --- |
+| `builder-mode.md`, `old-mode.md` | The server's **always-on** `instructions`, one per backend. Every client pays for these on every turn — keep them short and keep the depth in a topic. |
+| `SKILL.builder.md`, `SKILL.old.md` | The authoring guide per backend, split into `<!-- topic: name -->` blocks. Each block is one `how_it_works` topic. |
+| `SKILL.common.md` | Prose shared by both guides, in `<!-- section: name -->` blocks. A guide splices one in with `<!-- common: name -->`. |
+| `user-script.md`, `interception.md`, `hash-validation.md` | Backend-independent topics, served as-is to both modes. |
+| `js-sdk-integration.md` | Served by the old-devtools `get_js_sdk_integration_guide` tool, not by `how_it_works`. |
+
+Two mechanics to know when editing:
+
+- `%CTX%` expands to the mode's consumer-param namespace (`context.` on builder, `context_` on old-devtools). It is usually the *only* difference between the two modes, which is what lets a block stay in `SKILL.common.md` instead of being duplicated and drifting.
+- Every topic needs a one-line entry in `TOPIC_SUMMARIES` (`src/mcp/instructions.ts`) — it's what the tool advertises in its index. Assembly asserts on a missing section or summary, so a typo fails at server start rather than silently serving an empty topic.
+
+**Do not inline docs into a tool's input schema.** A schema description is sent to the model on every request; the injection guide that used to live in the publish tool's `jsUserScripts` field was about half the entire old-devtools tool surface on its own. Put the prose in a topic and leave a pointer.
+
+### Writing conventions for `skill/` and tool descriptions
+
+These follow the [Agent Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) and the [Google developer documentation style guide](https://developers.google.com/style):
+
+- **Assume the model is smart.** Only write what it can't infer. Every token in a topic competes with the task.
+- **Keep each topic focused and one level deep.** A topic links to other topics by name; it never chains through a third file. Give any topic over 100 lines a `## Contents` list at the top, so a partial read still shows its full scope.
+- **One term per concept.** "provider", not "verification" or "recipe". "developer", not "dev", "user", or "operator". "user script", not "injection".
+- **Reserve capitals for hard rules.** NEVER, MUST, ONLY, and NOT earn all caps; use bold for ordinary emphasis.
+- **Write in American English, in the second person, in the present tense.** Spell out "for example" and "that is" rather than "e.g." and "i.e.".
+- **Every tool description says what the tool does and when to call it**, plus any constraint the model can't discover by calling it.
+- **No time-sensitive statements.** Pin facts to a version or a named behavior, not to a date.

package/lib/authoring/backend.d.ts

@@ -56,9 +56,10 @@ export interface AuthoringBackend {
     /** This session's drafts (propose → replay/run_proof). */
     readonly drafts: DraftStore;
     /** Prove a drafted recipe. Local: attestor SDK (rich claim view). Remote: TEE
-     *  `/reclaim/prove` (lean, secret-free summary). Returns the environment's
-     *  display shape. A backend may record the proven recipe internally (e.g.
-     *  the cloud publish step) — that side effect is the backend's, not ours. */
+     * `/reclaim/prove` (lean, secret-free summary). Returns the environment's
+     * display shape. A backend may record the proven recipe internally (for
+     * example, the cloud publish step) — that side effect is the backend's, not
+     * ours. */
     prove(draft: Draft, opts?: ProveOptions): Promise<unknown>;
     /**
      * Validate/replay a drafted recipe before proving. Both local and remote
@@ -67,7 +68,7 @@ export interface AuthoringBackend {
      * always reflects the real browser session. With `withoutSecrets` it is
      * the AUTH-BOUND check: re-issue anonymously (`credentials: 'omit'`, no
      * secret headers) and report whether the values are STILL extractable —
-     * i.e. the endpoint is public. Without it, validate extraction for the
+     * that is, the endpoint is public. Without it, validate extraction for the
      * authenticated request. The shape is environment-specific and passed
      * straight through as the tool's result.
      */

package/lib/authoring/tools.js

@@ -80,7 +80,9 @@ export function authoringTools(resolveBackend) {
     return [
         defineTool({
             name: 'navigate',
-            description: 'Navigate the browser tab to a URL, waiting for load.',
+            description: 'Navigate the captured tab to a URL and wait for its load event. '
+                + 'Returns the URL the tab actually landed on, so you can detect a '
+                + 'redirect to a login page.',
             inputSchema: objectSchema({ url: { type: 'string' }, timeoutMs: { type: 'number' } }, ['url']),
         }, async (args) => {
             const backend = resolveBackend(args);
@@ -98,14 +100,18 @@ export function authoringTools(resolveBackend) {
         }),
         defineTool({
             name: 'eval_in_page',
-            description: 'Evaluate a JavaScript expression in the page and return its value '
-                + '(use to read the displayed value, check login state, etc.).',
+            description: 'Evaluate a JavaScript expression in the page and return its value. '
+                + 'Use it to read the value being proven out of the DOM, to check '
+                + 'login state, or to trigger the target request (for example, '
+                + '`location.reload()`).',
             inputSchema: objectSchema({ expression: { type: 'string' } }, ['expression']),
         }, (args) => evalInPage(resolveBackend(args), String(args.expression))),
         defineTool({
             name: 'wait_for_page',
-            description: 'Poll a JavaScript expression until it is truthy or the timeout '
-                + 'elapses (e.g. wait for the user to finish logging in).',
+            description: 'Poll a JavaScript expression once a second until it is truthy or '
+                + 'the timeout elapses. Use it to wait for content to appear. To '
+                + 'wait for a login, use wait_for_login instead — page JavaScript '
+                + 'cannot see the httpOnly session cookie.',
             inputSchema: objectSchema({ expression: { type: 'string' }, timeoutMs: { type: 'number' } }, ['expression']),
         }, async (args) => {
             const backend = resolveBackend(args);
@@ -122,26 +128,18 @@ export function authoringTools(resolveBackend) {
         }),
         defineTool({
             name: 'test_user_script',
-            description: 'Dry-run a USER SCRIPT — the same thing as the `jsUserScripts` / '
-                + '`customInjection` field on a published provider: plain browser '
-                + 'JS that runs before every page load, used to drive navigation '
-                + 'for data gated behind login/routing — in the LIVE attached tab, '
-                + 'BEFORE publishing. Installs `script` via CDP so it runs on the '
-                + 'next navigation exactly like the real field would, then reports '
-                + 'whether it ran and any errors it threw. Catches bugs (e.g. a '
-                + 'listener registered with setTimeout that never fires because the '
-                + "page was already past 'load' by the time it ran) before they "
-                + 'surface in a real end-user session instead of after. If '
-                + '`navigateUrl` is given, navigates there after installing, then '
-                + 'removes the script again once the result is read (self-cleaning '
-                + '— safe to call repeatedly). Without `navigateUrl` the script is '
-                + 'left installed for you to navigate yourself (any way you like) '
-                + 'then re-call this tool, or read '
-                + '`window.__reclaimUserScriptResult` via eval_in_page — in that '
-                + 'manual mode it is NOT auto-removed and keeps running on every '
-                + 'later navigation until a follow-up call with `navigateUrl` '
-                + 'removes it, so avoid stacking several manual-mode calls in a '
-                + 'row.',
+            description: 'Dry-run a USER SCRIPT (the `jsUserScripts` / `customInjection` '
+                + 'field) in the LIVE attached tab, BEFORE publishing. Installs '
+                + '`script` via CDP so it runs on the next navigation exactly as '
+                + 'the real field would, then reports whether it ran and what it '
+                + 'threw. With `navigateUrl`, it navigates there and removes the '
+                + 'script once the result is read — self-cleaning, safe to repeat. '
+                + 'WITHOUT `navigateUrl` the script stays installed (navigate '
+                + 'yourself, then re-call this tool or read '
+                + '`window.__reclaimUserScriptResult` via eval_in_page) and keeps '
+                + 'running on every later navigation until a call WITH '
+                + '`navigateUrl` removes it — so don\'t stack manual-mode calls. '
+                + 'Guide: how_it_works({ topic: "user-script" }).',
             inputSchema: objectSchema({
                 script: { type: 'string' },
                 navigateUrl: { type: 'string' },
@@ -177,8 +175,9 @@ export function authoringTools(resolveBackend) {
                     note: 'Installed for the NEXT navigation only — it did not run on '
                         + 'the current page, and stays installed (runs on every later '
                         + 'navigation too) until a follow-up call with navigateUrl '
-                        + 'removes it. Navigate now (e.g. the navigate tool), then read '
-                        + 'window.__reclaimUserScriptResult via eval_in_page, or call '
+                        + 'removes it. Navigate now (for example, with the navigate '
+                        + 'tool), then read window.__reclaimUserScriptResult via '
+                        + 'eval_in_page, or call '
                         + 'test_user_script again with navigateUrl.',
                 };
             }
@@ -216,7 +215,8 @@ export function authoringTools(resolveBackend) {
             description: 'List the NAMES of cookies currently set for the page (values are '
                 + 'NEVER returned). The most reliable, language- and DOM-independent '
                 + 'login signal: after the user logs in, an auth/session cookie '
-                + 'appears (e.g. session/sid/token/auth/jwt/_user/logged_in). '
+                + 'appears (for example, session, sid, token, auth, jwt, _user, '
+                + 'logged_in). '
                 + 'Includes httpOnly cookies the page JS cannot see.',
             inputSchema: objectSchema({}),
         }, async (args) => {
@@ -257,8 +257,8 @@ export function authoringTools(resolveBackend) {
                 'userFirstVisit', 'cf_', '_dd_', 'bcookie', 'bscookie', 'lidc',
             ].join('|') + ')', 'i');
             // A real session/auth cookie name. Deliberately NOT bare `token` — a
-            // challenge/CSRF token (e.g. LinkedIn `chp_token`) contains it and is
-            // set BEFORE auth completes. Any new httpOnly cookie is also a
+            // challenge/CSRF token (for example, LinkedIn `chp_token`) contains it
+            // and is set BEFORE auth completes. Any new httpOnly cookie is also a
             // candidate (server-set session cookies are usually httpOnly).
             const SESSION = /sess|sid|jwt|_session|auth|logged.?in|remember|li_at/i;
             // Auth/challenge URL paths — while the page is still on one, login is

package/lib/cdp/capture-engine.js

@@ -56,9 +56,10 @@ export function isStaticAsset(url) {
     return STATIC_ASSET_EXTENSIONS.has(base.slice(dot + 1).toLowerCase());
 }
 /** Response Content-Types for static assets. The URL-extension filter misses
- *  extension-less bundler/CDN URLs (e.g. `/assets/3b8f1c`), so we also drop by
- *  MIME at response time. `text/html`, `application/json`, and `text/plain`
- *  are NOT here — those are the document/API shapes recipes match. */
+ *  extension-less bundler/CDN URLs (for example, `/assets/3b8f1c`), so we also
+ *  drop by MIME at response time. `text/html`, `application/json`, and
+ *  `text/plain` are NOT here — those are the document/API shapes recipes
+ *  match. */
 const STATIC_ASSET_MIME_EXACT = new Set([
     'text/css',
     'application/javascript', 'text/javascript', 'application/x-javascript',
@@ -165,9 +166,9 @@ export function createCaptureEngine(opts) {
     function onResponseReceived(p) {
         const f = inFlight.get(p.requestId);
         if (!f) {
-            // No in-flight entry → the request was skipped (e.g. a static asset)
-            // or never seen. Discard any buffered response extra-info so a skipped
-            // asset can't leave a dangling entry.
+            // No in-flight entry → the request was skipped (for example, a static
+            // asset) or never seen. Discard any buffered response extra-info so a
+            // skipped asset can't leave a dangling entry.
             pendingResponseExtra.delete(p.requestId);
             return;
         }
@@ -225,7 +226,7 @@ export function createCaptureEngine(opts) {
         }
         catch {
             // Body might be unavailable for
-            // some content-types (e.g. websocket). Skip.
+            // some content-types (for example, websocket). Skip.
         }
     }
 }

package/lib/cdp/claims.d.ts

@@ -0,0 +1,21 @@
+/** Whether a process is still running. Signal 0 checks without delivering. */
+export declare function processAlive(pid: number): boolean;
+/** Slots with at least one live claimant, so a caller can avoid them. */
+export declare function busySlots(): Set<string>;
+/**
+ * Slots THIS process already holds.
+ *
+ * Its own claim must not push it onto a new slot: re-attaching in one session
+ * should come back to the browser it is already running, not start a second.
+ */
+export declare function ownSlots(): Set<string>;
+/** Take a claim on `slot`. Returns the token to release it with. */
+export declare function claim(slot: string): string;
+/**
+ * Give up this process's claim.
+ *
+ * Returns true when nobody is left, which is the caller's signal to stop the
+ * container. Returns false while another live session still holds it — stopping
+ * then would pull the browser out from under them.
+ */
+export declare function release(slot: string, token: string): boolean;

package/lib/cdp/claims.js

@@ -0,0 +1,129 @@
+/**
+ * Which sessions are using which browser container.
+ *
+ * A container is worth sharing: about 2 GB of RAM and 7 to 17 seconds to start,
+ * so a developer running one session after another should get the same one back
+ * rather than pay for a new one each time.
+ *
+ * It can only be shared SEQUENTIALLY, and the profile is why. Every container
+ * mounts a host directory as Chromium's `user-data-dir`, and the runtime
+ * deletes `SingletonLock` on boot — so a second container on the same profile
+ * is a second writer on one cookie jar. Chromium does not support that, and the
+ * failure is silent corruption of the thing most worth keeping: the login.
+ *
+ * So each container gets a SLOT. A slot has one profile and at most one live
+ * claimant. A session adopts the first slot nobody holds; when the last claim
+ * on a slot goes, the container stops.
+ *
+ * State lives in a file because each MCP session is its own OS process, with
+ * no shared memory to count in. Claims are process ids, and liveness is a
+ * signal-0 check — the same test the orphan reaper uses. It fails the harmless
+ * way: a recycled pid keeps a container alive rather than pulling one out from
+ * under a running session.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { LOGGER } from "../logger.js";
+import { reclaimHomeDirPath } from "../paths.js";
+/** Distinguishes claims made by this same process. */
+let claimSeq = 0;
+/** The pid a token belongs to, or 0 when it is malformed. */
+function tokenPid(token) {
+    const pid = Number(token.split('.')[0]);
+    return Number.isInteger(pid) ? pid : 0;
+}
+function claimsPath() {
+    return join(reclaimHomeDirPath(), 'browser-runtime-claims.json');
+}
+function read() {
+    try {
+        const parsed = JSON.parse(readFileSync(claimsPath(), 'utf8'));
+        // Drop claims whose process is gone: that is what makes a slot free again
+        // after a session was killed without cleaning up.
+        const live = {};
+        for (const [slot, tokens] of Object.entries(parsed)) {
+            const alive = (Array.isArray(tokens) ? tokens : [])
+                .filter((token) => processAlive(tokenPid(token)));
+            if (alive.length) {
+                live[slot] = alive;
+            }
+        }
+        return live;
+    }
+    catch {
+        // Missing or unreadable: nobody has claimed anything.
+        return {};
+    }
+}
+function write(claims) {
+    const path = claimsPath();
+    mkdirSync(dirname(path), { recursive: true });
+    // Write then rename, so a reader never sees a half-written file. Two sessions
+    // racing here means last-writer-wins on a file that is pruned on every read,
+    // which costs at most one redundant container.
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(claims, null, '\t')}\n`);
+    renameSync(temp, path);
+}
+/** Whether a process is still running. Signal 0 checks without delivering. */
+export function processAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists but belongs to another user — alive either way.
+        return err.code === 'EPERM';
+    }
+}
+/** Slots with at least one live claimant, so a caller can avoid them. */
+export function busySlots() {
+    return new Set(Object.keys(read()));
+}
+/**
+ * Slots THIS process already holds.
+ *
+ * Its own claim must not push it onto a new slot: re-attaching in one session
+ * should come back to the browser it is already running, not start a second.
+ */
+export function ownSlots() {
+    const mine = new Set();
+    for (const [slot, tokens] of Object.entries(read())) {
+        if (tokens.some((token) => tokenPid(token) === process.pid)) {
+            mine.add(slot);
+        }
+    }
+    return mine;
+}
+/** Take a claim on `slot`. Returns the token to release it with. */
+export function claim(slot) {
+    const token = `${process.pid}.${++claimSeq}`;
+    const claims = read();
+    claims[slot] = [...claims[slot] ?? [], token];
+    write(claims);
+    LOGGER.debug({ slot, held: claims[slot] }, 'claimed a browser slot');
+    return token;
+}
+/**
+ * Give up this process's claim.
+ *
+ * Returns true when nobody is left, which is the caller's signal to stop the
+ * container. Returns false while another live session still holds it — stopping
+ * then would pull the browser out from under them.
+ */
+export function release(slot, token) {
+    const claims = read();
+    const remaining = (claims[slot] ?? []).filter((held) => held !== token);
+    if (remaining.length) {
+        claims[slot] = remaining;
+        write(claims);
+        LOGGER.debug({ slot, remaining }, 'released a claim; others still hold it');
+        return false;
+    }
+    delete claims[slot];
+    write(claims);
+    return true;
+}

package/lib/cdp/container.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The pinned runtime image.
+ *
+ * A digest, not a tag. Upstream publishes 40-char git SHAs plus moving
+ * `main`/`latest` aliases and no semver at all, and its own docs say to
+ * "prefer immutable digests". Pinning one means an agent release cannot have
+ * the browser changed underneath it.
+ *
+ * Digest of `latest` as of 2026-08-22, built from popcorn-oss
+ * `4df751c25c7b329699033957b93f6486837e4acb`.
+ */
+export declare const BROWSER_RUNTIME_IMAGE: string;
+export interface ContainerBrowser {
+    /** Local viewer origin — what `share_browser_view` tunnels. */
+    viewerUrl: string;
+    /** Browser-level CDP websocket, for `connectCdpUrl`. */
+    cdpUrl: string;
+    /** Loopback port the viewer is published on. */
+    viewerPort: number;
+    /** Docker's name for this container. */
+    name: string;
+    /** Whether the image had to be pulled first — worth telling the developer. */
+    pulled: boolean;
+    /** Which slot this browser occupies, for diagnostics. */
+    slot: number;
+    stop: () => Promise<void>;
+}
+export interface ContainerOptions {
+    /** Loopback port for the viewer. Allocated when omitted. */
+    viewerPort?: number;
+    /** Loopback port for full CDP. Allocated when omitted. */
+    cdpPort?: number;
+    /** Override the pinned image, e.g. a local `build.sh` output. */
+    image?: string;
+    /** Framebuffer size, which is also the browser window's size. */
+    width?: number;
+    height?: number;
+    /** Page to open on start. */
+    url?: string;
+}
+/**
+ * Where the container's Chromium profile lives on the host.
+ *
+ * Mounted, unlike the reference dev script, for two reasons. Provider authoring
+ * means signing in once and capturing an authenticated request, which a profile
+ * that dies with the container makes impossible. And the profile holds the
+ * persisted fingerprint identity — canvas/audio seed, timezone, locale — which
+ * upstream warns must stay stable, since "flipping any of them against the same
+ * cookie jar is itself a bot signal".
+ */
+export declare function containerProfileDir(slot?: number): string;
+/** Docker CLI present AND its daemon reachable. */
+export declare function dockerAvailable(): Promise<boolean>;
+/** Message for the case we cannot fix for them. */
+export declare function dockerMissingMessage(): string;
+/**
+ * The `docker run` argv.
+ *
+ * A pure function because every flag here is load bearing and none of it is
+ * obvious from the outside: which ports are loopback-only, that the image is
+ * digest-pinned, that the profile is mounted. Tests assert on this directly
+ * rather than trying to observe a running container.
+ */
+export declare function buildRunArgs(opts: ContainerOptions & {
+    viewerPort: number;
+    cdpPort: number;
+}, image: string, name: string, profileDir: string): string[];
+/**
+ * Start a browser container and wait until it is actually serving.
+ *
+ * Ports are allocated per call, so concurrent sessions never land on the same
+ * container. Pass `viewerPort` to pin one — re-attaching with the same port
+ * reuses the container that is already there.
+ */
+export declare function startContainer(options?: ContainerOptions): Promise<ContainerBrowser>;
+/**
+ * Remove containers whose owning process is gone.
+ *
+ * Shutdown cleanup covers an orderly exit, but a SIGKILL or a crash runs
+ * nothing — and a 1.3 GB container with a live browser in it should not outlive
+ * the session that made it. Reaping at startup catches those, and the owner-PID
+ * label keeps it safe: a container whose owner still runs belongs to another
+ * session and is left alone.
+ */
+export declare function reapOrphanedContainers(): Promise<string[]>;