@reclaimprotocol/agent 0.1.23 → 0.1.24

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,13 @@ 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.
+- **`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 +52,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 +79,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 +87,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 through local Chrome, Builder-hosted Popcorn, or a custom CDP websocket. All four options — including how each one is watched live — are spelled out in the tool description, 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 a LOCAL attached tab behind a public HTTPS URL (cloudflared quick tunnel) so someone elsewhere can watch it and, by default, click and type in it. Local CDP modes only — a `builder` browser already returns a hosted `liveViewUrl` |
 | `dispose_browser`                           | Stop captures, disconnect CDP, and immediately release a Builder-hosted browser                               |
 | `get_session`, `reset_session`              | Session state                                                                                                  |
 
@@ -114,7 +118,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 +132,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 +153,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 +211,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/browser-proxy.d.ts

@@ -0,0 +1,78 @@
+/** The minimal CDP surface this module needs. Both the agent's `CdpTabClient`
+ *  and an app-side session-scoped wrapper around `chrome-remote-interface`'s
+ *  `CDP.Client` already satisfy this. */
+export interface CdpProxySender {
+    send: (method: string, params?: object) => Promise<unknown>;
+    subscribe: <T = unknown>(method: string, listener: (params: T) => void) => () => void;
+}
+export interface BrowserProxyCredentials {
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+}
+export interface TemplatedProxyUsernameOptions {
+    /** Vendor's env-configured base, e.g.
+     *  `brd-customer-<id>-zone-<zone>-country-{{COUNTRY_LOCATION}}`. */
+    template: string;
+    countryCode: string;
+    /** Sticky-session key — the same value must be used for every request
+     *  that should exit through the same proxy IP. */
+    proxySessionId: string;
+}
+/** Substitute `{{COUNTRY_LOCATION}}` in the vendor's username template (or
+ *  append `-country-<cc>` if the template has no placeholder), then append
+ *  the sticky-session suffix. */
+export declare function buildTemplatedProxyUsername(opts: TemplatedProxyUsernameOptions): string;
+/** A short alphanumeric sticky-session id suggestion for a proxy vendor's
+ *  session placeholder (e.g. Bright Data's `-session-<id>` suffix) —
+ *  deliberately not `captureId`/`sessionId` (long UUIDs, wrong shape for
+ *  most vendors' conventions and for the attestor's own `proxySessionId`
+ *  constraint: smallcase alphanumeric, 8-14 chars). Only a suggestion — the
+ *  caller's own `proxySessionId`, when given, is used instead. */
+export declare function generateProxySessionId(): string;
+/** Parse a `PROXY_SERVER`-style `host:port` string. Throws on a malformed
+ *  value — a bad env var should fail loudly, not silently proxy nowhere. */
+export declare function parseProxyServer(server: string): {
+    host: string;
+    port: number;
+};
+/**
+ * Route the browser's network traffic through `host:port` via the Popcorn
+ * extension's page API. Never throws — a `false` return means the extension
+ * couldn't be reached (e.g. this isn't a Popcorn browser); callers still get
+ * proxy auth wired up by {@link setupProxyAuthViaCdp} independently, since a
+ * caller-supplied proxy might already be configured another way.
+ */
+export declare function configureBrowserProxyViaExtension(sender: CdpProxySender, config: BrowserProxyCredentials): Promise<boolean>;
+/** Clear the extension-configured proxy, routing the browser direct again. */
+export declare function clearBrowserProxyViaExtension(sender: CdpProxySender): Promise<boolean>;
+/**
+ * Answer the proxy's Basic-auth challenge over CDP `Fetch`, since Popcorn's
+ * extension only sets host/port routing (not credentials — the proxy vendor
+ * still challenges the browser for them the normal way). Self-disables once
+ * the first challenge is answered (or after a timeout with none), rather
+ * than intercepting every request for the session's whole lifetime.
+ */
+export declare function setupProxyAuthViaCdp(sender: CdpProxySender, credentials: Pick<BrowserProxyCredentials, 'username' | 'password'>): Promise<void>;
+export interface ApplyBrowserProxyOptions extends BrowserProxyCredentials {
+    /** Defaults to true — proxy routing only affects new connections, so
+     *  existing page state must reload to actually go through it. */
+    reload?: boolean;
+}
+export interface ApplyBrowserProxyResult {
+    /** False means the extension wasn't reachable (not a Popcorn browser, or
+     *  it isn't installed) — auth handling was still armed regardless, in
+     *  case the proxy is configured another way. */
+    appliedViaExtension: boolean;
+}
+/** Configure routing + auth + reload, in the right order: routing must be
+ *  live before the reload navigates, and auth must be armed before that
+ *  navigation's requests go out. */
+export declare function applyBrowserProxy(sender: CdpProxySender, opts: ApplyBrowserProxyOptions): Promise<ApplyBrowserProxyResult>;
+/** Clear proxy routing and reload so subsequent requests go direct again. */
+export declare function clearBrowserProxy(sender: CdpProxySender, opts?: {
+    reload?: boolean;
+}): Promise<{
+    cleared: boolean;
+}>;

package/lib/cdp/browser-proxy.js

@@ -0,0 +1,186 @@
+/**
+ * Native browser-level proxy for a Popcorn remote browser session.
+ *
+ * Routes the browser's OWN network traffic (not the attestor's zkTLS egress —
+ * that's `geoLocation`/`useProxy` on `ProviderWebSettings`) through a
+ * user-supplied proxy. Applied via the Popcorn kiosk image's `window.__pcn`
+ * page API rather than a Playwright/CDP launch arg or a new browser context —
+ * both of those would spawn a browser outside the pod's `--kiosk` window,
+ * breaking the live-view stream this session is already being watched
+ * through. Proxy auth (username/password) is answered separately over CDP's
+ * `Fetch` domain, since Popcorn's extension only sets host/port routing.
+ *
+ * Shared between the app's verification runner and the agent's MCP tools —
+ * both drive a Popcorn browser over `chrome-remote-interface`, just through
+ * different wrapper types, so this module only depends on the minimal
+ * {@link CdpProxySender} shape rather than either package's CDP client.
+ */
+import { randomInt } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { LOGGER } from "../logger.js";
+/** Substitute `{{COUNTRY_LOCATION}}` in the vendor's username template (or
+ *  append `-country-<cc>` if the template has no placeholder), then append
+ *  the sticky-session suffix. */
+export function buildTemplatedProxyUsername(opts) {
+    const { template, countryCode, proxySessionId } = opts;
+    const cc = countryCode.toLowerCase();
+    const base = template.includes('{{COUNTRY_LOCATION}}')
+        ? template.replaceAll('{{COUNTRY_LOCATION}}', cc)
+        : `${template}-country-${cc}`;
+    return `${base}-session-${proxySessionId}`;
+}
+const PROXY_SESSION_ID_CHARS = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const PROXY_SESSION_ID_LENGTH = 10;
+/** A short alphanumeric sticky-session id suggestion for a proxy vendor's
+ *  session placeholder (e.g. Bright Data's `-session-<id>` suffix) —
+ *  deliberately not `captureId`/`sessionId` (long UUIDs, wrong shape for
+ *  most vendors' conventions and for the attestor's own `proxySessionId`
+ *  constraint: smallcase alphanumeric, 8-14 chars). Only a suggestion — the
+ *  caller's own `proxySessionId`, when given, is used instead. */
+export function generateProxySessionId() {
+    let out = '';
+    for (let i = 0; i < PROXY_SESSION_ID_LENGTH; i++) {
+        out += PROXY_SESSION_ID_CHARS[randomInt(PROXY_SESSION_ID_CHARS.length)];
+    }
+    return out;
+}
+/** Parse a `PROXY_SERVER`-style `host:port` string. Throws on a malformed
+ *  value — a bad env var should fail loudly, not silently proxy nowhere. */
+export function parseProxyServer(server) {
+    const match = /^([^:/]+):(\d+)$/.exec(server.trim());
+    if (!match) {
+        throw new Error(`PROXY_SERVER must be "host:port", got "${server}"`);
+    }
+    return { host: match[1], port: Number(match[2]) };
+}
+const PCN_READY_TIMEOUT_MS = 5000;
+const PCN_READY_POLL_MS = 100;
+/** Chrome caches a proxy credential per host:port after the first successful
+ *  challenge, so this only needs to cover the FIRST request. If no challenge
+ *  ever arrives (proxy doesn't require auth), don't leave `Fetch` enabled —
+ *  it would otherwise hold every request pending on this handler forever. */
+const PROXY_AUTH_SAFETY_TIMEOUT_MS = 15000;
+async function isExtensionReady(sender) {
+    const { result } = await sender.send('Runtime.evaluate', {
+        expression: 'Boolean(window.__pcn && window.__pcn.ready)',
+        returnByValue: true,
+    });
+    return result?.value === true;
+}
+async function waitForExtensionReady(sender) {
+    const deadline = Date.now() + PCN_READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await isExtensionReady(sender)) {
+            return true;
+        }
+        await delay(PCN_READY_POLL_MS);
+    }
+    return false;
+}
+/**
+ * Route the browser's network traffic through `host:port` via the Popcorn
+ * extension's page API. Never throws — a `false` return means the extension
+ * couldn't be reached (e.g. this isn't a Popcorn browser); callers still get
+ * proxy auth wired up by {@link setupProxyAuthViaCdp} independently, since a
+ * caller-supplied proxy might already be configured another way.
+ */
+export async function configureBrowserProxyViaExtension(sender, config) {
+    try {
+        if (!await isExtensionReady(sender)) {
+            // Force the content script to (re-)run so `window.__pcn` appears.
+            await sender.send('Page.navigate', { url: 'about:blank' });
+            if (!await waitForExtensionReady(sender)) {
+                LOGGER.warn('popcorn proxy extension not ready; skipping __pcn.set');
+                return false;
+            }
+        }
+        const { result } = await sender.send('Runtime.evaluate', {
+            expression: `(async () => {
+				try { await window.__pcn.set(${JSON.stringify(config)}); return true }
+				catch(e) { return false }
+			})()`,
+            awaitPromise: true,
+            returnByValue: true,
+        });
+        return result?.value === true;
+    }
+    catch (err) {
+        LOGGER.warn({ err }, 'configureBrowserProxyViaExtension failed');
+        return false;
+    }
+}
+/** Clear the extension-configured proxy, routing the browser direct again. */
+export async function clearBrowserProxyViaExtension(sender) {
+    try {
+        const { result } = await sender.send('Runtime.evaluate', {
+            expression: `(async () => {
+				try { await window.__pcn.clear(); return true }
+				catch(e) { return false }
+			})()`,
+            awaitPromise: true,
+            returnByValue: true,
+        });
+        return result?.value === true;
+    }
+    catch (err) {
+        LOGGER.warn({ err }, 'clearBrowserProxyViaExtension failed');
+        return false;
+    }
+}
+/**
+ * Answer the proxy's Basic-auth challenge over CDP `Fetch`, since Popcorn's
+ * extension only sets host/port routing (not credentials — the proxy vendor
+ * still challenges the browser for them the normal way). Self-disables once
+ * the first challenge is answered (or after a timeout with none), rather
+ * than intercepting every request for the session's whole lifetime.
+ */
+export async function setupProxyAuthViaCdp(sender, credentials) {
+    await sender.send('Fetch.enable', { handleAuthRequests: true });
+    let settled = false;
+    const finish = () => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        unsubAuth();
+        unsubPaused();
+        sender.send('Fetch.disable').catch(() => { });
+    };
+    const unsubAuth = sender.subscribe('Fetch.authRequired', (params) => {
+        sender.send('Fetch.continueWithAuth', {
+            requestId: params.requestId,
+            authChallengeResponse: {
+                response: 'ProvideCredentials',
+                username: credentials.username,
+                password: credentials.password,
+            },
+        }).then(finish).catch(() => { });
+    });
+    // Requests still need releasing while `Fetch` is enabled, whether or not
+    // they end up challenged. Fire-and-forget: serializing behind auth
+    // negotiation would stall unrelated requests.
+    const unsubPaused = sender.subscribe('Fetch.requestPaused', (params) => {
+        sender.send('Fetch.continueRequest', { requestId: params.requestId })
+            .catch(() => { });
+    });
+    setTimeout(finish, PROXY_AUTH_SAFETY_TIMEOUT_MS);
+}
+/** Configure routing + auth + reload, in the right order: routing must be
+ *  live before the reload navigates, and auth must be armed before that
+ *  navigation's requests go out. */
+export async function applyBrowserProxy(sender, opts) {
+    const appliedViaExtension = await configureBrowserProxyViaExtension(sender, opts);
+    await setupProxyAuthViaCdp(sender, opts);
+    if (opts.reload !== false) {
+        await sender.send('Page.reload', {});
+    }
+    return { appliedViaExtension };
+}
+/** Clear proxy routing and reload so subsequent requests go direct again. */
+export async function clearBrowserProxy(sender, opts = {}) {
+    const cleared = await clearBrowserProxyViaExtension(sender);
+    if (opts.reload !== false) {
+        await sender.send('Page.reload', {});
+    }
+    return { cleared };
+}

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/client.d.ts

@@ -19,6 +19,16 @@ interface CdpTabEventMap {
     'Network.loadingFinished': {
         requestId: string;
     };
+    /** Screencast frames, for the live view (`live/viewer.ts`). Each carries a
+     *  `sessionId` that MUST be acked with `Page.screencastFrameAck`, or CDP
+     *  stops sending. */
+    'Page.screencastFrame': {
+        data: string;
+        sessionId: number;
+        metadata?: {
+            timestamp?: number;
+        };
+    };
 }
 export interface CdpTabClient {
     send: (method: string, params?: object) => Promise<unknown>;