@reclaimprotocol/agent 0.1.3 → 0.1.5

package/README.md

@@ -6,7 +6,7 @@ This package **is** the Reclaim MCP server (bin: `reclaim-mcp-server`). It depen
 
 ## Install
 
-**Prerequisites:** Node ≥ 22.18 and a local Chrome / Chromium / Edge (used for capture and the dashboard login). The first run downloads the ZK circuit files needed by `run_proof` (a `postinstall` step), so allow a moment on first launch.
+**Prerequisites:** Node ≥ 22.18 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.
 
 It runs as a **stdio MCP server**. Point any MCP-capable agent at this command:
 
@@ -111,13 +111,13 @@ Defaults target the production old-devtools backend, so **no env is needed for t
 
 See [Backends](#backends) for builder mode (`USE_OLD_DEVTOOLS=false`) and the full env-var list.
 
-### Companion skill (optional, recommended)
+### Provider-authoring guide
 
-The MCP server is all you need to start — but installing the companion skill makes the agent markedly better at the capture → prove → publish flow (login detection, choosing auth-bound endpoints, OPRF decisions, troubleshooting). See [Skill](#skill) for install steps.
+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.
 
 ## Using it from your agent
 
-Optional but recommended: install the [skill](#skill) so the agent follows the full authoring flow.
+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.:
 
@@ -138,28 +138,9 @@ The agent orchestrates the tools for you:
 
 Your only manual steps are signing in when the browser windows open and confirming the value you want to prove.
 
-## Skill
+## How it works (guide tool)
 
-Optional but recommended. The companion skill (`skill/SKILL.md`) is a Claude Code **Agent Skill** that teaches the agent the full mode-aware authoring flow — it ships inside the npm package and is also in this repo.
-
-```bash
-# macOS / Linux — from a global install of the package
-npm i -g @reclaimprotocol/agent
-mkdir -p ~/.claude/skills/reclaim-provider
-cp "$(npm root -g)/@reclaimprotocol/agent/skill/SKILL.md" ~/.claude/skills/reclaim-provider/SKILL.md
-
-# …or from a checkout of this repo
-cp packages/agent/skill/SKILL.md ~/.claude/skills/reclaim-provider/SKILL.md
-```
-
-```powershell
-# Windows (PowerShell) — from a global install
-npm i -g @reclaimprotocol/agent
-New-Item -ItemType Directory -Force $env:USERPROFILE\.claude\skills\reclaim-provider | Out-Null
-Copy-Item "$(npm root -g)\@reclaimprotocol\agent\skill\SKILL.md" $env:USERPROFILE\.claude\skills\reclaim-provider\SKILL.md
-```
-
-Claude Code auto-loads it once it's in `~/.claude/skills/`. **Other MCP clients** (Cursor, opencode, Antigravity, …) don't read `SKILL.md` automatically — the server's built-in instructions already cover the essentials, and you can paste or adapt the skill's content into that client's rules / system-prompt for the same depth.
+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.
 
 ## Provider-authoring tools
 
@@ -194,13 +175,13 @@ 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 fetches dependencies and runs this package's postinstall, which downloads the ZK circuit resources needed by `@reclaimprotocol/attestor-core` at proof time:
+For working on the package inside the monorepo (consumers should use [Install](#install) instead). A workspace install just fetches dependencies:
 
 ```bash
 npm install
 ```
 
-If postinstall is skipped (`npm ci --ignore-scripts`, or a corp policy disabling postinstall), run it manually:
+The ZK circuit resources needed by `@reclaimprotocol/attestor-core` are **not** fetched at install time — `run_proof` downloads them on the first proof (see the [first-run note](#install)). To pre-fetch them instead of paying the cost on that first proof, run:
 
 ```bash
 npm run download:zk-files --workspace=packages/agent
@@ -208,7 +189,7 @@ npm run download:zk-files --workspace=packages/agent
 
 ## Platform notes
 
-- **Node >=22.18** is required (declared in `engines`). The floor is 22.18 because the package's `postinstall` and helper scripts run as bare `.ts` files, and unflagged TypeScript type-stripping landed in Node 22.18.
+- **Node >=22.18** is required (declared in `engines`). The floor is 22.18 because the test suite and dev workflow run bare `.ts` files directly, and unflagged TypeScript type-stripping landed in Node 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
@@ -285,18 +266,6 @@ 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).
 
-### Skill
-
-Symlink the source `skill/` folder into `~/.claude/skills/` so edits to `SKILL.md` are picked up live (no re-copy):
-
-```bash
-# macOS / Linux — from the repo root
-ln -s "$(pwd)/packages/agent/skill" ~/.claude/skills/reclaim-provider
-```
-
-```powershell
-# Windows (PowerShell, Developer Mode or elevated) — from the repo root
-New-Item -ItemType SymbolicLink -Path $env:USERPROFILE\.claude\skills\reclaim-provider -Target (Resolve-Path packages\agent\skill)
-```
+### Authoring guide
 
-Claude Code auto-loads it once linked. opencode doesn't read `SKILL.md` automatically — paste or adapt its content into that client's rules / system-prompt for the same depth.
+`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.

package/lib/authoring/backend.d.ts

@@ -0,0 +1,95 @@
+import type { CaptureSession } from '../cdp/capture-engine.ts';
+import type { Extraction } from '../provider/draft.ts';
+import type { ReclaimProvider, SecretParamRef } from '../provider/schema.ts';
+/** Secret request params (cookie/auth headers), materialized only for the
+ *  replay/prove call — never surfaced in tool output. */
+export interface SecretParams {
+    headers: Record<string, string>;
+}
+/** A drafted recipe held server-side so the model only handles an opaque
+ *  `draftId` — the provider is secret-free but the captured secrets never enter
+ *  the transcript. Shared by propose → replay → run_proof. */
+export interface Draft {
+    provider: ReclaimProvider;
+    secretRefs: SecretParamRef[];
+    /** Real secret header values (cookie/auth) for replay/prove — never returned
+     *  to the model. */
+    secrets: Record<string, string>;
+    /** The captured request this draft was proposed from. */
+    requestId: string;
+    /** One entry per extracted value (value + its redaction), so replay can
+     *  validate each against its own selector. */
+    extractions: Extraction[];
+}
+/** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id. */
+export interface DraftStore {
+    put(draft: Draft): string;
+    get(id: string): Draft | undefined;
+}
+export declare function makeDraftStore(): DraftStore;
+/** Options for a proof run. `ownerAddress` selects the local signing credential
+ *  and `attestorUrl` overrides the attestor endpoint (both MCP-only); the
+ *  remote TEE backend ignores them (it signs in-enclave, own attestor). */
+export interface ProveOptions {
+    ownerAddress?: string;
+    attestorUrl?: string;
+}
+/**
+ * Everything the shared authoring tools need from one live session. Browser ops
+ * go through `sendCdp` (+ `waitForEvent` for load-style waits); capture reads
+ * use `capture`; proof/replay are whole operations because they genuinely
+ * differ (local attestor + live re-fetch vs remote TEE) — each backend shapes
+ * its own result, passed straight through as the tool's output.
+ */
+export interface AuthoringBackend {
+    /** Send a raw CDP command scoped to this session's page. */
+    sendCdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Resolve once `method` (a CDP event) fires on this session's page, or
+     *  after `timeoutMs`. Used for `Page.loadEventFired`-style waits. */
+    waitForEvent(method: string, timeoutMs: number): Promise<'fired' | 'timeout'>;
+    /** This session's captured requests (the shared capture engine). */
+    readonly capture: CaptureSession;
+    /** 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. */
+    prove(draft: Draft, opts?: ProveOptions): Promise<unknown>;
+    /**
+     * Validate/replay a drafted recipe before proving. With `withoutSecrets` it
+     * is the AUTH-BOUND check: re-issue the request stripped of the captured
+     * secrets (local: a Node re-fetch without them; remote: an anonymous `fetch`
+     * in the Popcorn page, `credentials: 'omit'`) and report whether the values
+     * are STILL extractable — i.e. 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.
+     */
+    replay(draft: Draft, opts?: {
+        withoutSecrets?: boolean;
+    }): Promise<unknown>;
+}
+/**
+ * How a host (MCP / cloud) supplies its environment to the shared authoring
+ * tools, which are authored once with the common `defineTool` primitive and
+ * built per host by `buildAuthoringTools(host)`:
+ *   - `resolveBackend`: hand back the backend for one call. The MCP resolves it
+ *     from `args.captureId` (multi-session); the cloud returns its one run
+ *     backend.
+ *   - `sessionSchema`: input-schema props merged into EVERY tool (the MCP adds
+ *     `captureId`; the cloud adds nothing — the backend is implicit).
+ *   - `toolExtras`: per-tool schema/description additions (the MCP's rich,
+ *     credential-aware `run_proof` contract).
+ */
+export interface AuthoringHost {
+    resolveBackend(args: Record<string, unknown>): AuthoringBackend;
+    sessionSchema?: {
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    toolExtras?: Record<string, {
+        description?: string;
+        properties?: Record<string, unknown>;
+        required?: string[];
+    }>;
+}

package/lib/authoring/backend.js

@@ -0,0 +1,24 @@
+/**
+ * Backend seam for the authoring tools. The tool LOGIC (drive the browser →
+ * capture → propose → replay → prove) is written once against this interface;
+ * each environment supplies a backend:
+ *   - local (MCP): a Chrome tab over CDP + the in-process attestor SDK.
+ *   - remote (cloud): the user's Popcorn browser over CDP + the TEE prover.
+ *
+ * One backend instance == one live session (a page + its capture). Multi
+ * session falls out of instancing: the MCP resolves a backend per tab/capture,
+ * the cloud one per run — so the shared tools never carry a session id and hold
+ * no cross-session state.
+ */
+import { randomUUID } from 'node:crypto';
+export function makeDraftStore() {
+    const map = new Map();
+    return {
+        put: (draft) => {
+            const id = `draft_${randomUUID()}`;
+            map.set(id, draft);
+            return id;
+        },
+        get: (id) => map.get(id),
+    };
+}

package/lib/authoring/index.d.ts

@@ -0,0 +1,4 @@
+export type { AuthoringBackend, AuthoringHost, Draft, DraftStore, ProveOptions, SecretParams, } from './backend.ts';
+export { makeDraftStore } from './backend.ts';
+export { buildAuthoringTools } from './tools.ts';
+export { defineTool, type RegisteredTool, type ToolDefinition, } from '../tools/registry.ts';

package/lib/authoring/index.js

@@ -0,0 +1,5 @@
+export { makeDraftStore } from "./backend.js";
+export { buildAuthoringTools } from "./tools.js";
+// The shared tool primitive — re-exported so consumers (the cloud loop) get the
+// RegisteredTool type/`defineTool` without importing the MCP subsystem.
+export { defineTool, } from "../tools/registry.js";

package/lib/authoring/tools.d.ts

@@ -0,0 +1,9 @@
+import { type RegisteredTool } from '../tools/registry.ts';
+import type { AuthoringHost } from './backend.ts';
+/**
+ * Build the authoring tools for a host as plain {@link RegisteredTool}s — the
+ * same primitive the MCP-only tools use. Each handler resolves the backend via
+ * `host.resolveBackend(args)`; the schema merges the host's `sessionSchema`
+ * (e.g. `captureId`) and any per-tool `toolExtras`.
+ */
+export declare function buildAuthoringTools(host: AuthoringHost): RegisteredTool[];

package/lib/authoring/tools.js

@@ -0,0 +1,378 @@
+import { draftProvider } from "../provider/draft.js";
+import { OPRF_MAX_BYTES } from "../provider/matcher.js";
+import { normalizeCandidates } from "../provider/normalize.js";
+import { verificationWarnings } from "../provider/verification-checks.js";
+import { defineTool } from "../tools/registry.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Secret-free projection of a captured request for tool output. */
+function publicRequest(r) {
+    return {
+        requestId: r.requestId,
+        method: r.method,
+        url: r.url,
+        status: r.status,
+        contentType: r.contentType,
+        size: r.size,
+        ...(r.graphqlOp ? { graphqlOp: r.graphqlOp } : {}),
+    };
+}
+function matchesFilter(r, f) {
+    if (f.method && r.method !== f.method.toUpperCase()) {
+        return false;
+    }
+    if (f.urlGlob && !globMatch(f.urlGlob, r.url)) {
+        return false;
+    }
+    if (f.statusMin !== undefined && r.status < f.statusMin) {
+        return false;
+    }
+    if (f.statusMax !== undefined && r.status > f.statusMax) {
+        return false;
+    }
+    if (f.contentType && !r.contentType.includes(f.contentType)) {
+        return false;
+    }
+    if (f.graphqlOp && r.graphqlOp !== f.graphqlOp) {
+        return false;
+    }
+    return true;
+}
+function globMatch(pattern, str) {
+    const re = new RegExp('^'
+        + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+        + '$');
+    return re.test(str);
+}
+async function evalInPage(backend, expression) {
+    const res = (await backend.sendCdp('Runtime.evaluate', {
+        expression, returnByValue: true, awaitPromise: true,
+    }));
+    if (res.exceptionDetails) {
+        return {
+            error: res.exceptionDetails.exception?.description
+                ?? res.exceptionDetails.text
+                ?? 'evaluation error',
+        };
+    }
+    return { value: res.result?.value };
+}
+/**
+ * Build the authoring tools for a host as plain {@link RegisteredTool}s — the
+ * same primitive the MCP-only tools use. Each handler resolves the backend via
+ * `host.resolveBackend(args)`; the schema merges the host's `sessionSchema`
+ * (e.g. `captureId`) and any per-tool `toolExtras`.
+ */
+export function buildAuthoringTools(host) {
+    const mk = (spec) => {
+        const extra = host.toolExtras?.[spec.name];
+        const required = [
+            ...(host.sessionSchema?.required ?? []),
+            ...(spec.required ?? []),
+            ...(extra?.required ?? []),
+        ];
+        const inputSchema = {
+            type: 'object',
+            properties: {
+                ...(host.sessionSchema?.properties ?? {}),
+                ...spec.properties,
+                ...(extra?.properties ?? {}),
+            },
+            ...(required.length ? { required } : {}),
+        };
+        return defineTool({
+            name: spec.name,
+            description: extra?.description ?? spec.description,
+            inputSchema,
+        }, (args) => spec.run(host.resolveBackend(args), args));
+    };
+    return [
+        mk({
+            name: 'navigate',
+            description: 'Navigate the browser tab to a URL, waiting for load.',
+            properties: {
+                url: { type: 'string' },
+                timeoutMs: { type: 'number' },
+            },
+            required: ['url'],
+            run: async (backend, args) => {
+                const timeoutMs = Number(args.timeoutMs) || 30_000;
+                await backend.sendCdp('Page.enable');
+                // Start listening BEFORE navigating so the load event isn't missed.
+                const load = backend.waitForEvent('Page.loadEventFired', timeoutMs);
+                const nav = (await backend.sendCdp('Page.navigate', { url: String(args.url) }));
+                if (nav.errorText) {
+                    return { ok: false, error: nav.errorText };
+                }
+                const loadStatus = await load;
+                const final = await evalInPage(backend, 'location.href');
+                return { ok: true, loadStatus, finalUrl: final.value };
+            },
+        }),
+        mk({
+            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.).',
+            properties: { expression: { type: 'string' } },
+            required: ['expression'],
+            run: (backend, args) => evalInPage(backend, String(args.expression)),
+        }),
+        mk({
+            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).',
+            properties: {
+                expression: { type: 'string' },
+                timeoutMs: { type: 'number' },
+            },
+            required: ['expression'],
+            run: async (backend, args) => {
+                const expr = String(args.expression);
+                const deadline = Date.now() + (Number(args.timeoutMs) || 180_000);
+                while (Date.now() < deadline) {
+                    const { value } = await evalInPage(backend, expr);
+                    if (value) {
+                        return { ready: true };
+                    }
+                    await sleep(1000);
+                }
+                return { ready: false };
+            },
+        }),
+        mk({
+            name: 'get_cookies',
+            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). '
+                + 'Includes httpOnly cookies the page JS cannot see.',
+            properties: {},
+            run: async (backend) => {
+                const res = (await backend.sendCdp('Network.getCookies'));
+                return (res.cookies ?? []).map((c) => ({
+                    name: c.name,
+                    ...(c.domain ? { domain: c.domain } : {}),
+                    ...(c.session ? { session: true } : {}),
+                    ...(c.httpOnly ? { httpOnly: true } : {}),
+                }));
+            },
+        }),
+        mk({
+            name: 'list_requests',
+            description: 'List captured network requests (method/url/status/size), newest '
+                + 'last. Optionally filter by method / urlGlob / status range / '
+                + 'contentType / graphqlOp. Metadata only — secrets never included.',
+            properties: {
+                filter: {
+                    type: 'object',
+                    properties: {
+                        method: { type: 'string' },
+                        urlGlob: { type: 'string' },
+                        statusMin: { type: 'number' },
+                        statusMax: { type: 'number' },
+                        contentType: { type: 'string' },
+                        graphqlOp: { type: 'string' },
+                    },
+                },
+            },
+            run: async (backend, args) => {
+                const filter = (args.filter ?? {});
+                return [...backend.capture.requests.values()]
+                    .filter((r) => matchesFilter(r, filter))
+                    .map(publicRequest);
+            },
+        }),
+        mk({
+            name: 'find_requests_containing',
+            description: 'Search captured responses for any encoding of `value` (raw, '
+                + 'URL/JSON/HTML-escaped, …). Returns a ranked candidate list with '
+                + 'the matched variant, score, and a short snippet — used to locate '
+                + 'the request that returns a target. Server-side; bodies stay here.',
+            properties: {
+                value: { type: 'string' },
+                limit: { type: 'number' },
+            },
+            required: ['value'],
+            run: async (backend, args) => {
+                const variants = normalizeCandidates(String(args.value));
+                const ranked = [];
+                for (const r of backend.capture.requests.values()) {
+                    if (!r.responseBody) {
+                        continue;
+                    }
+                    let hit;
+                    for (const v of variants) {
+                        const idx = r.responseBody.indexOf(v);
+                        if (idx >= 0) {
+                            const start = Math.max(0, idx - 40);
+                            const end = Math.min(r.responseBody.length, idx + v.length + 40);
+                            hit = {
+                                snippet: r.responseBody.slice(start, end), variant: v,
+                            };
+                            break;
+                        }
+                    }
+                    if (!hit) {
+                        continue;
+                    }
+                    // Prefer JSON responses + smaller bodies (likely API endpoints).
+                    const score = (r.contentType.includes('json') ? 10 : 0)
+                        + Math.max(0, 5 - Math.log10(Math.max(r.size, 1)));
+                    ranked.push({
+                        ...publicRequest(r),
+                        matchedVariant: hit.variant,
+                        snippet: hit.snippet,
+                        score,
+                    });
+                }
+                ranked.sort((a, b) => b.score - a.score);
+                const limit = Number(args.limit) || 10;
+                return { candidates: ranked.slice(0, limit) };
+            },
+        }),
+        mk({
+            name: 'propose_provider',
+            description: 'Draft a provider from ONE captured request. Pass `targets` (an '
+                + 'array): one entry per value to extract, each with its `value` '
+                + '(verbatim) and a distinct `name` (its param). The provider gets '
+                + 'one match + redaction per target. Returns a draftId + recipe '
+                + '(never secrets). Prefer a SINGLE request holding ALL values. '
+                + 'Single-value shorthand: `target` + `name`. Per-target `hash` '
+                + 'OPRF-hashes that value.',
+            properties: {
+                requestId: { type: 'string' },
+                name: { type: 'string' },
+                targets: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            value: { type: 'string' },
+                            name: { type: 'string' },
+                            hash: {
+                                type: 'string',
+                                enum: ['oprf-raw', 'oprf', 'oprf-mpc'],
+                            },
+                        },
+                        required: ['value', 'name'],
+                    },
+                },
+                target: { type: 'string' },
+                hash: { type: 'string', enum: ['oprf-raw', 'oprf', 'oprf-mpc'] },
+            },
+            required: ['requestId', 'name'],
+            run: async (backend, args) => {
+                const requestId = String(args.requestId);
+                const providerName = String(args.name);
+                const defaultHash = args.hash;
+                // Explicit multi-value `targets`, else the single `target` shorthand.
+                const raw = Array.isArray(args.targets) ? args.targets : [];
+                const targets = raw.length
+                    ? raw.map((t) => {
+                        const o = t;
+                        return {
+                            value: String(o.value),
+                            name: String(o.name),
+                            ...(typeof o.hash === 'string'
+                                ? { hash: o.hash }
+                                : {}),
+                        };
+                    })
+                    : typeof args.target === 'string'
+                        ? [{
+                                value: args.target,
+                                name: providerName,
+                                ...(defaultHash ? { hash: defaultHash } : {}),
+                            }]
+                        : [];
+                if (targets.length === 0) {
+                    throw new Error('propose_provider needs a `target` value or a non-empty '
+                        + '`targets` array');
+                }
+                for (const t of targets) {
+                    if ((t.hash ?? defaultHash) !== undefined
+                        && t.value.length > OPRF_MAX_BYTES) {
+                        throw new Error(`OPRF caps hashed values at ${OPRF_MAX_BYTES} bytes; got `
+                            + `${t.value.length}-byte "${t.value}". Use a tighter `
+                            + 'target or drop `hash`.');
+                    }
+                }
+                const captured = backend.capture.requests.get(requestId);
+                if (!captured) {
+                    throw new Error(`no captured request ${requestId}`);
+                }
+                if (!captured.responseBody) {
+                    throw new Error(`request body unavailable for ${requestId}`);
+                }
+                const { provider, secretRefs, extractions } = draftProvider(captured, targets, providerName, defaultHash);
+                // Materialize the real secret header values for later replay/prove;
+                // they stay in the server-side draft, never in this result.
+                const secrets = {};
+                for (const ref of secretRefs) {
+                    const real = captured.requestHeaders[ref.name];
+                    if (real !== undefined) {
+                        secrets[ref.name] = real;
+                    }
+                }
+                const draftId = backend.drafts.put({
+                    provider, secretRefs, secrets, requestId, extractions,
+                });
+                const warnings = verificationWarnings(provider);
+                return {
+                    draftId,
+                    provider,
+                    secretRefs,
+                    ...(warnings.length ? { verificationWarnings: warnings } : {}),
+                };
+            },
+        }),
+        mk({
+            name: 'replay_request',
+            description: 'Validate the drafted recipe before proving — confirm its selectors '
+                + 'extract the target value. Returns diagnostics; run before '
+                + 'proving. Set `withoutSecrets: true` for the AUTH-BOUND check: it '
+                + 're-issues the request with NO secrets/cookies (an anonymous '
+                + 'visitor). If the values still extract (valid:true), the endpoint '
+                + 'is PUBLIC and the proof would not bind to the user — reject it and '
+                + 'find an auth-bound request instead.',
+            properties: {
+                draftId: { type: 'string' },
+                withoutSecrets: { type: 'boolean' },
+            },
+            required: ['draftId'],
+            run: async (backend, args) => {
+                const draft = backend.drafts.get(String(args.draftId));
+                if (!draft) {
+                    throw new Error(`no draft ${String(args.draftId)}`);
+                }
+                return backend.replay(draft, {
+                    withoutSecrets: Boolean(args.withoutSecrets),
+                });
+            },
+        }),
+        mk({
+            name: 'run_proof',
+            description: 'Prove the drafted recipe (zkTLS). Only call after replay_request '
+                + 'looks right. Returns the proof result.',
+            properties: { draftId: { type: 'string' } },
+            required: ['draftId'],
+            // The backend shapes its own result: the cloud returns a lean,
+            // secret-free summary (and records the proven recipe for publish); the
+            // MCP persists the claim + returns the rich developer view. The MCP adds
+            // `ownerAddress`/`attestorUrl` to the schema via the host's toolExtras.
+            run: async (backend, args) => {
+                const draft = backend.drafts.get(String(args.draftId));
+                if (!draft) {
+                    throw new Error(`no draft ${String(args.draftId)}`);
+                }
+                const opts = {};
+                if (typeof args.ownerAddress === 'string') {
+                    opts.ownerAddress = args.ownerAddress;
+                }
+                if (typeof args.attestorUrl === 'string') {
+                    opts.attestorUrl = args.attestorUrl;
+                }
+                return backend.prove(draft, opts);
+            },
+        }),
+    ];
+}

package/lib/cdp/capture-engine.d.ts

@@ -30,6 +30,13 @@ export interface ResponseReceivedLike {
  *  `:`. Stripping at capture time keeps every downstream consumer
  *  (`get_request`, draft, replay, proof) clean by construction. */
 export declare function stripPseudoHeaders(headers: Record<string, string>): Record<string, string>;
+/** True when the URL's path names a static asset (by file extension; query and
+ *  hash are ignored, so `chunk.js?v=1` still counts). The capture engine drops
+ *  these up front — they never carry JSON/HTML a recipe matches. */
+export declare function isStaticAsset(url: string): boolean;
+/** True when a response Content-Type is a static asset (scripts/styles/fonts/
+ *  images/media). Parameters (`; charset=…`) and case are ignored. */
+export declare function isStaticAssetMime(mimeType: string | undefined): boolean;
 export interface CaptureSession {
     captureId: string;
     requests: Map<string, CapturedRequest>;