@reclaimprotocol/agent 0.1.4 → 0.1.6

package/lib/provider/schema.d.ts

@@ -19,11 +19,13 @@ export type ResponseMatch = HttpParams['responseMatches'][number];
  */
 export type ResponseRedaction = NonNullable<HttpParams['responseRedactions']>[number];
 /**
- * OPRF mode for hashed redactions. `oprf-raw` is what the dev-loop defaults
- * to when privacy is requested — the only variant that runs without external
- * deps (gnark for `oprf`, a TEE for `oprf-mpc`). It is the weakest of the
- * three (the attestor participates in hashing) and is meant to be swapped
- * out before production.
+ * OPRF mode for hashed redactions:
+ *  - `oprf-mpc` — TEE-based MPC OPRF. The default for the cloud/hosted flow: a
+ *    TEE attestor accepts (and expects) this and REJECTS `oprf-raw`.
+ *  - `oprf` — client-side ZK OPRF via gnark (needs the gnark deps).
+ *  - `oprf-raw` — server-side OPRF, no external deps; the local dev-loop
+ *    default (Windows / non-TEE). Weakest of the three (the attestor
+ *    participates in hashing) and not accepted by a TEE attestor.
  */
 export type OprfMode = NonNullable<ResponseRedaction['hash']>;
 /** A single captured request + response, as we store it server-side. */

package/lib/tools/registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The ONE tool primitive for the agent. A tool is authored once with
+ * {@link defineTool} — `{ definition, handler }`, where the handler receives
+ * args already parsed + validated against the definition's JSON Schema (via
+ * zod), so the schema shown to the model and the validation applied to inbound
+ * args cannot drift.
+ *
+ * This lives outside `mcp/` on purpose: it depends only on zod (NOT the MCP
+ * SDK), so non-MCP consumers — the cloud authoring loop — can author and run
+ * these tools without pulling in `@modelcontextprotocol/sdk`. The MCP-specific
+ * glue (`registerToolList` onto an `McpServer`) stays in `mcp/server.ts`, which
+ * re-exports this primitive for the MCP-side tool files.
+ */
+import type { JSONSchema } from 'zod/v4/core';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema.ObjectSchema;
+}
+export interface RegisteredTool {
+    definition: ToolDefinition;
+    /**
+     * @param args Tool arguments (already zod-validated against the schema).
+     * @returns A JSON-stringifiable value to return to the LLM.
+     * @throws Any error; the host (MCP `registerToolList` / the cloud loop)
+     * catches it and surfaces it as an error tool-result.
+     */
+    handler: (args: unknown) => Promise<unknown>;
+}
+/**
+ * Define a tool with a single inputSchema (JSON Schema) as the source of truth.
+ * The handler receives args already parsed and type-narrowed via a Zod schema
+ * derived from that same JSON Schema — so the description sent to the client
+ * and the validation applied to inbound args cannot drift.
+ */
+export declare function defineTool<TArgs>(definition: ToolDefinition, handler: (args: TArgs) => Promise<unknown>): RegisteredTool;
+/**
+ * Adapt a tool to a host by WIDENING its input schema — add properties, mark
+ * some required, optionally override the description — without touching the
+ * handler. A host maps whichever shared tools it needs through this (e.g. the
+ * MCP adds its `captureId` session handle + the credential-aware `run_proof`
+ * contract). Args parse loosely, so the extra fields flow through to the
+ * handler (its backend resolver reads them); the base tool stays untouched for
+ * hosts that don't need them.
+ */
+export declare function extendTool(tool: RegisteredTool, extra: {
+    description?: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+}): RegisteredTool;

package/lib/tools/registry.js

@@ -0,0 +1,49 @@
+import { toZod } from "../mcp/api/to-zod.js";
+/**
+ * Define a tool with a single inputSchema (JSON Schema) as the source of truth.
+ * The handler receives args already parsed and type-narrowed via a Zod schema
+ * derived from that same JSON Schema — so the description sent to the client
+ * and the validation applied to inbound args cannot drift.
+ */
+export function defineTool(definition, handler) {
+    const schema = toZod(definition.inputSchema);
+    return {
+        definition,
+        handler: async (raw) => {
+            const args = schema.parse(raw);
+            return await handler(args);
+        },
+    };
+}
+/**
+ * Adapt a tool to a host by WIDENING its input schema — add properties, mark
+ * some required, optionally override the description — without touching the
+ * handler. A host maps whichever shared tools it needs through this (e.g. the
+ * MCP adds its `captureId` session handle + the credential-aware `run_proof`
+ * contract). Args parse loosely, so the extra fields flow through to the
+ * handler (its backend resolver reads them); the base tool stays untouched for
+ * hosts that don't need them.
+ */
+export function extendTool(tool, extra) {
+    const base = tool.definition;
+    const required = [
+        ...(base.inputSchema.required ?? []),
+        ...(extra.required ?? []),
+    ];
+    const inputSchema = {
+        ...base.inputSchema,
+        properties: {
+            ...base.inputSchema.properties,
+            ...extra.properties,
+        },
+        ...(required.length ? { required } : {}),
+    };
+    return {
+        definition: {
+            name: base.name,
+            description: extra.description ?? base.description,
+            inputSchema,
+        },
+        handler: tool.handler,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.4",
+	"version": "0.1.6",
 	"description": "Reclaim Protocol agent — SDK, CLI, and MCP server in one package. SDK + CLI talk to the builder backend; MCP server adds Chrome CDP capture, provider synthesis, replay, and zkTLS proof.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -11,6 +11,10 @@
 			"types": "./lib/index.d.ts",
 			"import": "./lib/index.js"
 		},
+		"./authoring": {
+			"types": "./lib/authoring/index.d.ts",
+			"import": "./lib/authoring/index.js"
+		},
 		"./provider": {
 			"types": "./lib/provider/index.d.ts",
 			"import": "./lib/provider/index.js"
@@ -83,7 +87,11 @@
 		"@reclaimprotocol/client": "*",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
+		"domhandler": "^6.0.0",
+		"parse5": "^8.0.0",
+		"parse5-htmlparser2-tree-adapter": "^8.0.0",
 		"pino": "^9.14.0",
+		"xpath": "^0.0.34",
 		"zod": "^4.4.3"
 	},
 	"devDependencies": {

package/skill/SKILL.builder.md

@@ -1,10 +1,14 @@
-# Authoring a Reclaim Provider / Verification
-
-> **Terminology note:** "provider" and "verification" refer to the same
-> thing. The API and tool parameters use **provider** / **providerId**
-> (the technical term). Conversations with developers prefer
-> **verification** (the user-facing term). Either is acceptable — never
-> correct the developer for using one or the other.
+# Authoring a Reclaim Provider
+
+> **Terminology note:** A **provider** is the recipe you author here — the
+> instructions for extracting a data point from a website (the
+> `responseMatches` / `responseRedactions` spec, identified by a
+> `providerId`). Always call it a **provider**; never call a provider a
+> "verification." A **verification** (or **verification session**) is the
+> separate runtime act in which an end-user proves a data point *using* a
+> provider — reserve that word for the session/result, never for the recipe.
+> If a developer calls the recipe a "verification," gently use "provider"
+> yourself rather than correcting them.
 
 You drive the browser through the capture → draft → replay → prove loop using the `reclaim-agent` MCP server. **Your default stance is driver, not orchestrator.** Only pause to ask the dev for things that genuinely require a human: typing credentials, completing 2FA, solving a captcha, confirming an ambiguous value. Navigation, reloads, DOM inspection, request capture — all yours.
 
@@ -28,9 +32,9 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
    Re-call with the chosen `attachMode`.
 
-2. **Pick a tab and open the site yourself.** Call `list_tabs`. If there's already a tab on the right origin, use it. Otherwise pick any tab (the first one is usually fine) and call `navigate(tabId, url)` to send it to the site you've inferred from the dev's request (e.g. "GitHub username" → `https://github.com`). Don't ask the dev to navigate.
+2. **Pick a tab and start a capture.** Call `list_tabs` and pick a tab (if one is already on the right origin use it; otherwise the first is usually fine). Then call `start_capture(tabId)` — it returns a **`captureId`** that is your session handle for the rest of the flow: `navigate`, `eval_in_page`, `wait_for_page`, `get_cookies`, `list_requests`, `find_requests_containing`, `propose_provider` all take it as their first argument. Capturing from the start is harmless (it just also records the login navigation). Then `navigate(captureId, url)` to the site you inferred from the dev's request (e.g. "GitHub username" → `https://github.com`). Don't ask the dev to navigate.
 
-3. **Check login state, wait if needed.** Use `eval_in_page(tabId, ...)` to evaluate a site-specific check.
+3. **Check login state, wait if needed.** Use `eval_in_page(captureId, ...)` to evaluate a site-specific check.
 
    **Combine a positive signal (logged-in-only element present) with a negative signal (login button absent), AND them together.** Single signals are too prone to false positives — most notably, `<meta>` tags often exist on every page regardless of login state; only their `.content` attribute is populated. The check `!!document.querySelector('meta[name="user-login"]')` returns true even when logged out — DO NOT use existence-only checks on meta tags or other persistent-but-empty elements.
 
@@ -41,13 +45,13 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
    If the result is truthy, skip to step 4.
 
-   If falsy: **navigate to the site's login URL yourself first**, so the dev lands directly on the login form instead of having to find it. Common patterns: `https://<host>/login`, `https://<host>/signin`, `https://<host>/i/flow/login` (Twitter/X). Pick the one you know works for the site. Call `navigate(tabId, "<login-url>")`. Then tell the dev once: "I've opened the login page on `<site>` — please log in (with 2FA if needed). I'll detect when you're done." Then call `wait_for_page(tabId, expression="<same composite expression>", timeoutMs=180000)`. The MCP polls every second and returns when the expression goes truthy. **Do not** instruct the dev to "tell me when you're done" — just wait via the tool.
+   If falsy: **navigate to the site's login URL yourself first**, so the dev lands directly on the login form instead of having to find it. Common patterns: `https://<host>/login`, `https://<host>/signin`, `https://<host>/i/flow/login` (Twitter/X). Pick the one you know works for the site. Call `navigate(captureId, "<login-url>")`. Then tell the dev once: "I've opened the login page on `<site>` — please log in (with 2FA if needed). I'll detect when you're done." Then call `wait_for_page(captureId, expression="<same composite expression>", timeoutMs=180000)`. The MCP polls every second and returns when the expression goes truthy. **Do not** instruct the dev to "tell me when you're done" — just wait via the tool.
 
    **Self-check before trusting the result:** if your detector says "already logged in" on a freshly-launched Chrome profile (cookies-clean), the detector is wrong. Brand-new profile means brand-new cookie jar — there's no way to be already authenticated. If you see that contradiction, your check is matching something that's present regardless of login (a meta tag, a generic class). Rewrite the expression and re-evaluate.
 
-4. **Navigate to the page that displays the value.** Use what you know about the site to construct the URL. If you need the dev's username, eval it (e.g. on GitHub: `document.querySelector('meta[name="user-login"]')?.content`). Then `navigate(tabId, url)`. Don't ask the dev to navigate.
+4. **Navigate to the page that displays the value.** Use what you know about the site to construct the URL. If you need the dev's username, eval it (e.g. on GitHub: `document.querySelector('meta[name="user-login"]')?.content`). Then `navigate(captureId, url)`. Don't ask the dev to navigate.
 
-5. **Start capture, then trigger the request.** Call `start_capture(tabId)` first. Then issue a reload so the relevant API call fires while capture is live: `eval_in_page(tabId, "location.reload()")`. For some pages you may need to click a specific element or call a SPA route — use `eval_in_page` to do that programmatically rather than asking the dev to click.
+5. **Trigger the request.** Capture has been live since step 2, so just make the relevant API call fire: issue a reload with `eval_in_page(captureId, "location.reload()")`. For some pages you may need to click a specific element or call a SPA route — use `eval_in_page` to do that programmatically rather than asking the dev to click.
 
 6. **Identify the value from the DOM.** `eval_in_page` to read the displayed value (e.g. the logged-in username from `meta[name="user-login"]`'s `content` attribute). If the value is unambiguous, proceed without asking. Only confirm with the dev when there are multiple plausible interpretations (e.g. the page shows both a display name "John Doe" and a handle "@jdoe" and you need to pick which to prove).
 
@@ -79,11 +83,24 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
    **Hard constraint:** OPRF-hashed values are capped at **62 bytes**. If the value is longer and the dev picks any hash, surface that and propose either a tighter `target` (e.g. just the email local-part) or no hash. `propose_provider` will return a clean error if you try anyway.
 
-9. **Draft.** Call `propose_provider(captureId, requestId, target, name, hash?)`. Pass `hash` only if the dev opted in. Inspect the returned provider:
+9. **Draft.** Call `propose_provider`. It returns a **`draftId`** (the handle you pass to `replay_request` and `run_proof`), the secret-free `provider`, and `secretRefs`. The recipe **and the captured secret values** are held server-side under that `draftId` — the secret values never enter the transcript, so you carry the `draftId`, not the provider JSON, into replay/prove.
+
+   **Extracting MORE THAN ONE value?** Prefer a **single request whose response contains ALL of them**, and draft them together — the provider gets one `responseMatches` + `responseRedactions` entry per value. First locate that request: run `find_requests_containing` for each value and pick a `requestId` that appears for all. Then pass a `targets` array — one entry per value, each with its `value` (exactly as it appears) and a distinct `name` (its parameter):
+
+   ```
+   propose_provider(captureId, requestId, name, targets: [
+     { value: "Scratch-net", name: "username" },
+     { value: "Alex",        name: "name" },
+   ])
+   ```
+
+   For a single value, the shorthand `propose_provider(captureId, requestId, target, name, hash?)` still works (one target). Pass `hash` only if the dev opted in (per-target `hash` also works inside `targets`). Inspect the returned provider:
    - Is the right header marked secret? (cookies, Authorization, X-\* tokens)
    - Is `responseMatches[0].value` a `contains` with a `{{name}}` template (matching the captured value's structural context)?
    - Is `paramValues[name]` set to the original captured value?
-   - Does `responseRedactions[0]` carry an `xPath` or `jsonPath` anchor? (And if `hash` was requested, also a `regex` with a named capture and a `hash: oprf-…` field?)
+   - Does each `responseRedactions` entry carry an `xPath` or `jsonPath` anchor **plus** a named-capture `regex` that isolates just the value? The synthesizer adds the regex for BOTH cases — an HTML element reveal is the element markup and a jsonPath reveal is the surrounding `"key":"value"`, so neither is the bare value without the regex. (And if `hash` was requested, the regex also carries a `hash: oprf-…` field.)
+
+   **Provenance — match the structure, never the bare value.** The `contains` template and the redaction `regex` are always anchored on the value's surrounding context — the JSON key (`"login":"{{username}}"`) or the enclosing element (`<div class="handle">{{username}}</div>`), never just `{{username}}` or `>{{username}}<`. This ties the proof to *where the value legitimately appears*; a bare-value match would let a user surface the same string from any field they control. The synthesizer does this for you.
 
    **Canonical drafted shape** (no hash):
 
@@ -92,7 +109,12 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
    	"responseMatches": [
    		{ "type": "contains", "value": "\"login\":\"{{username}}\"" }
    	],
-   	"responseRedactions": [{ "xPath": "//script[@id=\"client-env\"]" }],
+   	"responseRedactions": [
+   		{
+   			"xPath": "//script[@id=\"client-env\"]",
+   			"regex": "\"login\":\"(?<username>[A-Za-z0-9_-]+)\""
+   		}
+   	],
    	"paramValues": { "username": "Scratch-net" }
    }
    ```
@@ -143,20 +165,20 @@ replace with `{{context.<name>}}`. E.g. `https://github.com/Scratch-net/repos`
 
 `propose_provider` returns `verificationWarnings` for the calls only an author can make (currently: a captured value baked literally into the URL, needing the `{{context.<name>}}`-vs-bare-vs-re-capture decision). They are advisory, never blocking — **surface each warning to the dev verbatim** and resolve it before publishing.
 
-11. **Replay.** Call `replay_request(provider, secretParamsRef)`. Three outcomes:
+11. **Replay.** Call `replay_request(captureId, draftId)`. Three outcomes:
 
 - `matchesOriginal: true` → proceed.
 - `matchesOriginal: false` with `hints` mentioning auth/csrf → re-trigger the action yourself: navigate or reload via the tools, then loop to step 5. Don't ask the dev to redo it manually.
 - `matchesOriginal: false` with stable diff (timestamps etc.) → tighten the matcher and retry.
 
-**After replay succeeds, run an authentication-bound check.** Call `replay_request(provider)` _without_ the `secretParamsRef` (omit it). This sends the request stripped of all secret headers — the same shape an unauthenticated visitor would send.
+**After replay succeeds, run the authentication-bound check — this is mandatory.** Call `replay_request(captureId, draftId, withoutSecrets: true)`. This re-issues the request with NO secrets/cookies (an anonymous visitor).
 
-- If `matchesOriginal: false` (e.g. 401/403, or the value differs) → the endpoint is auth-bound. Good. The proof will actually mean "the holder of these secrets saw this value."
-- If `matchesOriginal: true` with the same value → the endpoint is fully public. Tell the dev verbatim: "I verified this endpoint returns the same value with no authentication — the proof won't prove your identity, only that this URL returned the value. Anyone could generate the same proof. Want to keep digging for an auth-bound endpoint, or proceed anyway?" Wait for their decision before continuing.
+- If it FAILS to extract (401/403/redirect, or the value is gone) → the endpoint is auth-bound. Good — the proof genuinely means "the holder of these secrets saw this value."
+- If it STILL extracts the value → the endpoint is **PUBLIC**: anyone gets the same value with no login, so the proof binds to nobody. **Do NOT prove it.** Find a request whose response *depends on the session* (an API keyed to the logged-in user, e.g. `/settings/*` or a `viewer`/`currentUser` API), and re-check. If a value only ever appears on public responses, tell the dev it can't be proven as an identity claim rather than proving a public one.
 
-12. **Prove.** Call `run_proof(provider, secretParamsRef)`. On `verified: true`, the full claim has been written to `~/.reclaim/claims/<timestamp>.json` and the tool returns `{verified, extractedValue, extractedParameters, identifier, owner, claimPath, claim}`. The `claim` field is a display-ready version of the proof — its huge `request` payload has been stripped and all byte arrays converted to base64, so it renders cleanly. **Show it to the dev as a fenced JSON code block at the end** along with the provider JSON. That's the final result. On `verified: false`, diagnose using the returned error and iterate.
+12. **Prove.** Call `run_proof(captureId, draftId, ownerAddress)`. On `verified: true`, the full claim has been written to `~/.reclaim/claims/<timestamp>.json` and the tool returns `{verified, extractedValue, extractedParameters, identifier, owner, claimPath, claim}`. The `claim` field is a display-ready version of the proof — its huge `request` payload has been stripped and all byte arrays converted to base64, so it renders cleanly. **Show it to the dev as a fenced JSON code block at the end** along with the provider JSON. That's the final result. On `verified: false`, diagnose using the returned error and iterate.
 
-    **Missing signing credential (`errorKind: "missing-owner-key"`)** — the dev hasn't set up an eth proof-owner key yet. Tell them what's happening, then drive the bootstrap yourself: call `resolve_owner_key`; if it returns no key, ask once _"shall I mint a fresh eth key via `issue_credentials` (or `import_credentials` if you already hold one)? It's written to the project `.env` (mode 0600, gitignored) for this and future sessions."_; on yes, call `issue_credentials` (or `import_credentials`) and retry the same `run_proof` call. **No restart needed** — the key is read live from `.env` on each `run_proof`, and the existing `secretParamsRef` from `propose_provider` is still valid.
+    **Missing signing credential (`errorKind: "missing-owner-key"`)** — the dev hasn't set up an eth proof-owner key yet. Tell them what's happening, then drive the bootstrap yourself: call `resolve_owner_key`; if it returns no key, ask once _"shall I mint a fresh eth key via `issue_credentials` (or `import_credentials` if you already hold one)? It's written to the project `.env` (mode 0600, gitignored) for this and future sessions."_; on yes, call `issue_credentials` (or `import_credentials`) and retry the same `run_proof` call. **No restart needed** — the key is read live from `.env` on each `run_proof`, and the existing `draftId` from `propose_provider` is still valid.
 
     **On any `verified: false` response, the result includes (inline):**
     - `error` — the SDK's thrown error message verbatim
@@ -175,15 +197,16 @@ replace with `{{context.<name>}}`. E.g. `https://github.com/Scratch-net/repos`
 
 13. **Publish the proved provider.** `provider` is the exact JSON from step 9 with the step-10 URL parameterisation applied, and `initialUrl` is the page where the user logs in / the value is displayed (e.g. `https://github.com/Syed`) — **not** the API endpoint URL inside the provider.
 
-    1. **Create the verification if it doesn't exist:** `create_verification(orgId, domain, slug, title, description)` — find `orgId` via `list_orgs`. `domain` e.g. `github.com`; `slug` e.g. `github-username`; `title` e.g. "GitHub Username". Starts PRIVATE with an empty seed version. Skip if the dev already has a `providerId`.
+    1. **Create the provider if it doesn't exist:** `create_provider(orgId, domain, slug, title, description)` — find `orgId` via `list_orgs`. `domain` e.g. `github.com`; `slug` e.g. `github-username`; `title` e.g. "GitHub Username". Starts PRIVATE with an empty seed version. Skip if the dev already has a `providerId`.
     2. **Persist the version:** `create_provider_version_from_capture(providerId, provider, initialUrl, notes)` — `notes` e.g. `"Initial draft from browser capture"`. The version lands on the `draft` branch.
+       - **Multi-request provider** (e.g. a landing-page call plus a details call, or a CSRF-preflight/refresh-token chain): run steps 5–12 ONCE PER REQUEST — a separate `propose_provider` → `replay_request` → `run_proof` cycle for each — then pass `providers: [draftA, draftB, ...]` instead of the single-draft `provider` in this same call. Every entry becomes its own request in the version, and all are required at verification time.
     3. **`requiredContext` is derived for you.** The publish tool scans the recipe's url/body for `{{context.<name>}}` placeholders (step 10) and emits a JSON Schema requiring each one — the Builder then validates every session-create's `context` against it (a clear 400 instead of a late attestor failure). Extra context fields are always allowed. The derived properties are plain strings; to refine types or add human-readable descriptions, call `update_provider_version` with a `requiredContext` override while the version is on `draft`, e.g.:
 
        ```json
        { "requiredContext": { "type": "object", "required": ["username"], "properties": { "username": { "type": "string", "description": "GitHub username to verify" } } } }
        ```
     4. **Go live:** PRIVATE → `publish_provider_version`; PUBLIC → `submit_provider_version_for_review(providerId, version)` and tell the dev it's awaiting admin review.
-    5. **Tell the dev how consumers call it:** sessions for this verification must include the context params, e.g. `context: { "username": "..." }` in `POST /verifications/sessions`. Quote the `requiredContext` returned on the created version — a session missing those fields gets a 400, and verification matches the supplied values exactly.
+    5. **Tell the dev how consumers call it:** sessions for this provider must include the context params, e.g. `context: { "username": "..." }` in `POST /verifications/sessions`. Quote the `requiredContext` returned on the created version — a session missing those fields gets a 400, and verification matches the supplied values exactly.
 
     When done, tell the developer the version is live (PRIVATE) or submitted for review (PUBLIC), and that they can integrate using the `providerId`.
 
@@ -196,10 +219,10 @@ When `analyze_request_constraints` returns concerns, repeat each `message` to th
 - Never echo a raw `Authorization`, `Cookie`, or `X-*-Token` value back to the dev or write one to any file. The MCP guarantees these don't appear in tool responses — keep that guarantee.
 - Never call `run_proof` before `replay_request` succeeds. Attestor calls are expensive.
 - Never pretend a proof succeeded when `verified: false` came back. Show the error and iterate.
-- **Never hand-craft `responseMatches` or `responseRedactions`.** If you find yourself typing a regex by hand, OR writing `(?<name>...)`-style patterns by hand, OR copying the captured value literally into the match — stop. The synthesizer in `propose_provider` already produces the canonical shape: `contains` template + paramValues for the match, xPath/jsonPath (optionally + regex+hash when `hash` is passed) for the redaction. The named-capture regex in the redaction is the synthesizer's job, not yours.
+- **Never hand-craft `responseMatches` or `responseRedactions`.** If you find yourself typing a regex by hand, OR writing `(?<name>...)`-style patterns by hand, OR copying the captured value literally into the match — stop. The synthesizer in `propose_provider` already produces the canonical shape: `contains` template + paramValues for the match, xPath/jsonPath for the redaction — plus a value-isolating named-capture `regex` (for every xPath/jsonPath anchor — the reveal is a byte range, never the bare value). The named-capture regex in the redaction is the synthesizer's job, not yours.
 - Never write a literal value into `responseMatches.value` — the synthesizer always emits `{{name}}` templates with paramValues. A literal value bakes the original user into the provider.
 - Never pass `hash` to `propose_provider` for a free-form (unicode / spaces / punctuation) target — the synthesizer will error, and the right move is either to use a tighter `target` or accept cleartext (no `hash`).
-- Never accept "the synthesizer's xPath looks too narrow, let me write a regex" — the xPath is fine, the attestor will reveal the whole matched element which is naturally ≥16 bytes.
+- Never accept "the synthesizer's xPath looks too narrow, let me write a regex" — the synthesizer already pairs the xPath with a structure-anchored named-capture regex (for HTML) that both reveals the element and isolates the value. If extraction still looks wrong, re-run `propose_provider` with a better request/target — don't hand-write patterns.
 
 ## Common first-time issues — surface these proactively
 
@@ -216,21 +239,21 @@ If `attach_chrome` errors, times out, or `waitForCdpReady` reports the port isn'
 **Credential for signing the proof.** `run_proof` requires an `ownerAddress` — the eth proof-owner key whose private half signs the claim. It does **no** resolution itself; get the address from `resolve_owner_key` first. The private key is resolved locally (`RECLAIM_PRIVATE_KEY` env → a `RECLAIM_PRIVATE_KEY=0x…` line in the project `.env` → a file at `RECLAIM_PRIVATE_KEY_FILE`) and never enters the conversation.
 
 1. **Call `resolve_owner_key`.** It checks `RECLAIM_PRIVATE_KEY` (MCP env) → the project `.env` → `RECLAIM_PRIVATE_KEY_FILE`, and returns only the derived address.
-   - `{ ready: true, address }` → call `run_proof({ provider, ownerAddress: address, … })`. No prompts.
+   - `{ ready: true, address }` → call `run_proof(captureId, draftId, address)`. No prompts.
    - `{ ready: false }` → no key exists yet. Ask the dev once how to set one up:
      - **Provide their own key** → `import_credentials({ privateKey: "0x…" })` (also accepts a `keyFile` path).
      - **Create a new one** → `issue_credentials({})`. (Fine default for test proofs — owner identity doesn't matter.)
      - Either way the key is written to the project `.env` (mode 0600; `.env` is added to `.gitignore`) — never to `~/.reclaim`.
    - Then call `resolve_owner_key` again and `run_proof` with the returned address.
 2. All fully local — no network, no server registration. The key is read live from `.env` on each `run_proof`, so no restart is needed after issuing/importing.
-- **Advanced:** setting `RECLAIM_PRIVATE_KEY` directly in the MCP server's env also works, but env vars are snapshotted at Claude Code startup, so that route needs a full restart (which invalidates every `secretParamsRef`). The `.env` flow above avoids that — prefer it.
+- **Advanced:** setting `RECLAIM_PRIVATE_KEY` directly in the MCP server's env also works, but env vars are snapshotted at Claude Code startup, so that route needs a full restart (which invalidates every `draftId`). The `.env` flow above avoids that — prefer it.
 - **Multiple MCP config files exist on Windows.** `~/.claude.json` takes precedence over `~/.claude/mcp.json`. When advising config edits, point them at the right file or tell them to use `claude mcp list` / `claude mcp add --scope user` rather than editing JSON by hand.
 
-If `replay_request` or `run_proof` errors with `unknown secretParamsRef`:
+If `replay_request` or `run_proof` errors with `unknown draftId` (or `no capture`):
 
-- **The ref is bound to the MCP server process.** Anything that restarts the server (Claude Code restart, `reset_session`, machine reboot) invalidates every previously-issued ref. The fix is always: re-run `start_capture` → interact → `propose_provider` to mint a fresh ref. Don't ask the dev to "re-enter the value" — walk them back through capture.
-- **Exception:** if the drafted provider has empty `secretRefs: []` (no secret headers were captured), you can call `replay_request` and `run_proof` without `secretParamsRef` at all — both tools accept it as optional in that case.
+- **The draft is bound to its capture, held in the MCP server process.** Anything that restarts the server (Claude Code restart, `reset_session`, machine reboot) drops every capture and its drafts. The fix is always: re-run `start_capture` → interact → `propose_provider` to mint a fresh `draftId`. Don't ask the dev to "re-enter the value" — walk them back through capture.
+- **Auth-bound check:** to replay/prove the request as an unauthenticated visitor (no secret headers), pass `withoutSecrets: true` to `replay_request` — the draft still carries the captured secrets, so you never re-supply them.
 
-## Out of scope (v0)
+## Recognizing a HAWKEYE / live-interception provider
 
-If the dev needs a provider for a flow that requires multiple sequential requests (CSRF preflight, refresh-token chains), tell them: "multi-request providers are v1. For now, we can produce a single-request provider for the target value — let's see if one exists in this capture."
+Everything above builds the STANDARD flow: capture → draft → replay → prove. There is a second flow — `webSettings.inapp.interceptorOptions.interceptorType: HAWKEYE` (or `MSWJS`/`CDP`) plus a `jsUserScripts` script that calls `window.reclaimInterceptor.addResponseMiddleware(...)` to observe the page's REAL responses as they happen, instead of an independent replay. `create_provider_version_from_capture` never sets `inapp` at all, so you will not author this flow with the current tools — but you may see these fields on a version someone else published outside this flow. `isDocumentRequestReplayEnabled` is a NARROWER, separate toggle from the interception itself — it does not gate `addResponseMiddleware` in general (that fires for every `interceptorType` including `CDP`); it only controls whether the current page's own document/navigation request specifically gets pulled through a non-CDP interceptor, as a site-compatibility escape hatch. See `injection-api.md` (embedded in the `jsUserScripts` field description) for the source-verified breakdown before guessing at what they mean.

package/skill/SKILL.old.md

@@ -1,10 +1,14 @@
-# Authoring a Reclaim Provider / Verification
-
-> **Terminology note:** "provider" and "verification" refer to the same
-> thing. The API and tool parameters use **provider** / **providerId**
-> (the technical term). Conversations with developers prefer
-> **verification** (the user-facing term). Either is acceptable — never
-> correct the developer for using one or the other.
+# Authoring a Reclaim Provider
+
+> **Terminology note:** A **provider** is the recipe you author here — the
+> instructions for extracting a data point from a website (the
+> `responseMatches` / `responseRedactions` spec, identified by a
+> `providerId`). Always call it a **provider**; never call a provider a
+> "verification." A **verification** (or **verification session**) is the
+> separate runtime act in which an end-user proves a data point *using* a
+> provider — reserve that word for the session/result, never for the recipe.
+> If a developer calls the recipe a "verification," gently use "provider"
+> yourself rather than correcting them.
 
 You drive the browser through the capture → draft → replay → prove loop using the `reclaim-agent` MCP server. **Your default stance is driver, not orchestrator.** Only pause to ask the dev for things that genuinely require a human: typing credentials, completing 2FA, solving a captcha, confirming an ambiguous value. Navigation, reloads, DOM inspection, request capture — all yours.
 
@@ -164,9 +168,13 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
 13. **Publish the proved provider.** `provider` is the exact JSON from step 9 with the step-10 URL parameterisation applied, and `initialUrl` is the page where the user logs in / the value is displayed (e.g. `https://github.com/Syed`) — **not** the API endpoint URL inside the provider.
 
     Call `create_provider_version_from_capture`:
-    - **New verification:** omit `providerId`. It registers a new provider (version 1.0.0). Pass `provider`, `initialUrl`, and optionally `description`, `geoLocation`, `providerType` (`PRIVATE` default | `PUBLIC`).
-    - **New version of an existing verification:** pass its `providerId` — the patch is auto-bumped above the highest existing version. Pass `notes` (≥10 chars) as the change note.
-    - `get_me_providers({ searchQuery? })` lists the verifications you own — use it to find a `providerId` or to confirm the result. It's the only provider-listing tool in this mode.
+    - **New provider:** omit `providerId`. It registers a new provider (version 1.0.0). Pass `provider`, `initialUrl`, and optionally `description`, `geoLocation`, `providerType` (`PRIVATE` default | `PUBLIC`).
+    - **New version of an existing provider:** pass its `providerId` — the patch is auto-bumped above the highest existing version. Pass `notes` (≥10 chars) as the change note.
+    - **Multi-request provider** (e.g. a landing-page call plus a details call, or a CSRF-preflight/refresh-token chain): run steps 5–12 ONCE PER REQUEST — a separate `propose_provider` → `replay_request` → `run_proof` cycle for each — then publish all of them together in ONE call by passing `providers: [draftA, draftB, ...]` instead of the single-draft `provider`. Every entry becomes its own parallel `requestData` entry on the SAME version, and all are required at verification time.
+    - `get_me_providers({ searchQuery? })` lists the providers you own — use it to find a `providerId` or to confirm the result. It's the only provider-listing tool in this mode.
+    - **Before adding a version to an EXISTING provider, call `get_provider_version_config(providerId)` first.** This backend has no partial-patch endpoint — a version replaces the WHOLE `providerConfig` — so seeing what's currently live (`customInjection`, `userAgent`, `pageTitle`, `stepsToFollow`, etc.) tells you what you're about to change vs. carry forward before you commit to it, rather than finding out after. (`create_provider_version_from_capture` carries forward anything you omit automatically, but knowing what that IS before publishing beats being surprised after.)
+    - **To rename, redescribe, retag, flip `providerType`, or toggle `isActive` on a provider you own — WITHOUT creating a new version** — use `update_provider_metadata(providerId, {...})` instead. It's a genuine partial update on the provider itself; don't route a pure metadata edit through `create_provider_version_from_capture`.
+    - **To look up any published provider (not just ones you own), or to see exactly what the live verification client would fetch** — use `get_provider_info(providerId, versionNumber?)`. It reads the public production SDK backend directly (no auth needed), separate from everything else in this mode.
     - There's no separate "create-then-version" step and no org / public-review workflow here.
     - Consumer-supplied params (step 10) keep the `{{context_<name>}}` form in this mode; there is no `requiredContext` declaration on the legacy backend.
 
@@ -216,6 +224,6 @@ If `replay_request` or `run_proof` errors with `unknown secretParamsRef`:
 - **The ref is bound to the MCP server process.** Anything that restarts the server (Claude Code restart, `reset_session`, machine reboot) invalidates every previously-issued ref. The fix is always: re-run `start_capture` → interact → `propose_provider` to mint a fresh ref. Don't ask the dev to "re-enter the value" — walk them back through capture.
 - **Exception:** if the drafted provider has empty `secretRefs: []` (no secret headers were captured), you can call `replay_request` and `run_proof` without `secretParamsRef` at all — both tools accept it as optional in that case.
 
-## Out of scope (v0)
+## Recognizing a HAWKEYE / live-interception provider
 
-If the dev needs a provider for a flow that requires multiple sequential requests (CSRF preflight, refresh-token chains), tell them: "multi-request providers are v1. For now, we can produce a single-request provider for the target value — let's see if one exists in this capture."
+Everything above builds the STANDARD flow: capture → draft → replay (the backend independently re-sends the request) → prove. There is a second, separate flow — `injectionType: HAWKEYE` (or `MSWJS`/`XHOOK`/`CDP`) plus a `customInjection` script that calls `window.reclaimInterceptor.addResponseMiddleware(...)` to observe the page's REAL responses as they happen, instead of the backend replaying anything. You will not author this flow with the current tools — `create_provider_version_from_capture` only builds the standard one. But you WILL see the fields when reading an existing provider (`get_provider_version_config`, `get_provider_info`): don't assume `injectionType` present-but-not-`NONE` means something is broken — the old backend's own schema DEFAULTS `injectionType` to `HAWKEYE` for every provider, standard-flow ones included; it's inert with no interceptor script installed. `disableRequestReplay` is a NARROWER, separate toggle — it does not gate interception in general (that fires regardless, for every `injectionType` including `CDP`); it only controls whether the current page's own document/navigation request specifically gets pulled through a non-CDP interceptor, and exists as a site-compatibility escape hatch, not an architecture choice. See `injection-api.md` (embedded in the `customInjection` field description) for the full, source-verified breakdown of `injectionType`/`disableRequestReplay`/`bodySniff` before guessing at any of these three.

package/skill/builder-mode.md

@@ -2,7 +2,7 @@ This server targets the Reclaim BUILDER backend. It exposes three tool layers: g
 
 **Authentication:** try `get_me` first. On 401, `authenticate({})` opens a device-pairing session — give the user the `attachUrl`, then poll `authenticate({ code })` until LINKED. Tokens are cached ~2 days.
 
-**Provider-authoring flow:** `attach_chrome` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`) → `propose_provider` → `replay_request` → `run_proof` → resolve a `providerId` (**Reuse before create**, below) → `create_provider_version_from_capture` (lands on the draft branch) → `publish_provider_version` (PRIVATE) or `submit_provider_version_for_review` (PUBLIC).
+**Provider-authoring flow:** `attach_chrome` → `start_capture(tabId)` ⇒ a **`captureId`** (the session handle every browser/inspect tool takes as its first arg) → drive the page (`navigate`, `wait_for_page`, `eval_in_page`, `get_cookies`) → inspect (`list_requests`, `get_request`, `find_requests_containing`) → `propose_provider` ⇒ a **`draftId`** (the recipe + captured secrets held server-side; secrets never enter the transcript) → `replay_request(captureId, draftId)` → `run_proof(captureId, draftId, ownerAddress)` → resolve a `providerId` (**Reuse before create**, below) → `create_provider_version_from_capture` (lands on the draft branch) → `publish_provider_version` (PRIVATE) or `submit_provider_version_for_review` (PUBLIC).
 
 **Reuse before create (avoid duplicates):** `create_provider_version_from_capture` requires a `providerId`. Before minting a new one with `create_provider`, search your existing providers with `providers` (by domain / data point) — a site you've already built will be there. If one matches, pass its `providerId` so the capture lands as a NEW VERSION on that provider. Only `create_provider` (then use its returned id) when none exists. Re-running the flow against `create_provider` each time is what stacks duplicate providers in "My providers".
 

package/skill/injection-api.md

@@ -40,3 +40,120 @@ than guessing.
 > provider's `initialUrl`), and old-devtools runs `customInjection` the same
 > way. (`window.Reclaim` itself is still only forwarded/available in the cases
 > noted above.)
+
+## Interception mode: `injectionType` / `interceptorType`
+
+Separate from the script's CONTENT is HOW the client captures network traffic
+for it to consume — a per-version field alongside `customInjection`/
+`jsUserScripts`, not something you write into the script itself. Whichever
+mechanism is selected, the injected script consumes what it caught through
+the SAME API: `window.reclaimInterceptor.addResponseMiddleware(middleware,
+middlewareName?)`. That consumption API fires for any intercepted request
+under EVERY mechanism below, including `CDP` — it is not a HAWKEYE-specific
+thing.
+
+- **old-devtools** field: `injectionType`, one of `NONE | MSWJS | XHOOK | CDP |
+  HAWKEYE`. Verified from the backend's Prisma schema: **the column default is
+  `HAWKEYE`**, not `NONE` — every provider `create_provider_version_from_capture`
+  registers gets `injectionType: HAWKEYE` implicitly, since neither this tool
+  nor the old backend's register/config controllers ever set it explicitly.
+  This is harmless for the normal capture→replay→prove flow: with no
+  interceptor script installed, there's nothing calling
+  `addResponseMiddleware`, so the standard flow behaves identically
+  regardless of this field's value.
+- **builder** field: `webSettings.inapp.interceptorOptions.interceptorType`,
+  one of `HAWKEYE | MSWJS | CDP` (no `NONE`/`XHOOK` in this schema).
+  `create_provider_version_from_capture` (builder mode) never sets `inapp` at
+  all, so this is a no-op for the standard flow there too.
+
+**The mechanisms, and why you'd pick one over plain replay:**
+- **`CDP`** — interception at the browser/DevTools-protocol level, below the
+  page's own JS. Works uniformly for every request the page makes, INCLUDING
+  its own document/navigation load — no caveats, "works best."
+- **`HAWKEYE` / `MSWJS` / `XHOOK`** — interception done IN the page's JS
+  context (different underlying libraries; same idea). These see the page's
+  ordinary sub-resource/API requests fine, but the page's OWN document
+  request is a special case — see `disableRequestReplay` below.
+- Reach for ANY of the above (over the plain replay flow, `injectionType:
+  NONE` / no `inapp`) only when the data genuinely can't be reproduced by an
+  independent replay — e.g. it depends on one-time server-side state (a
+  nonce, a websocket push) that asking again wouldn't give you back. For
+  everything else, the standard flow is simpler and is what `propose_provider`
+  / `run_proof` are built for.
+
+## `disableRequestReplay` / `isDocumentRequestReplayEnabled`
+
+**This does NOT gate `addResponseMiddleware` in general** — that fires for
+any intercepted request regardless of this field. What it actually controls:
+whether the CURRENT PAGE'S OWN document/navigation request (the request that
+loads the page's HTML — not a sub-resource or API call) is sent for real
+over the network at all, for the non-CDP mechanisms above. And it only
+matters if the request you're proving *is* that document request — e.g. the
+target value is embedded straight in the page's own HTML rather than
+fetched via a separate API call.
+
+- `false` (old-devtools' schema default) — the document request IS sent for
+  real (for `HAWKEYE`/`MSWJS`/`XHOOK`), so `addResponseMiddleware` sees it
+  like any other intercepted request. This is what you need if you're
+  proving data straight out of the current page's own HTML.
+- `true` — the document request is constructed/synthesized locally instead
+  of actually being sent, so the interceptor never observes it (every OTHER
+  request the page makes is still intercepted normally). This exists as a
+  **compatibility escape hatch**: some websites misbehave when their own
+  top-level navigation request gets pulled through a JS-level interceptor —
+  flip this to `true` for those sites. It's not a privacy or architecture
+  choice, it's a per-site workaround.
+- **`CDP` is exempt from all of this** — it intercepts at the browser level,
+  so the document request is never a special case for it.
+  `disableRequestReplay`/`isDocumentRequestReplayEnabled` is simply inert
+  when `injectionType`/`interceptorType` is `CDP`.
+
+Field names, per backend:
+- **old-devtools**: `disableRequestReplay` (boolean, schema default `false`).
+  The dashboard's own field hint (verbatim): *"When enabled (default), the
+  main document HTTP request is actually sent to get the response. When
+  disabled, the expected request and response are constructed locally
+  without making the network call."* Note the double negative: the
+  dashboard's checkbox is labeled "Enable Document Request Replay" and is
+  CHECKED when `disableRequestReplay` is `false` — the checkbox and the field
+  it writes are inverted from each other.
+- **builder**: `webSettings.inapp.interceptorOptions.isDocumentRequestReplayEnabled`
+  (boolean, positive naming this time — `true` means the document request IS
+  sent). Per its openapi description, the schema's own stated default is
+  `false`. Don't assume the two backends' defaults line up just because the
+  concept is the same — old effectively defaults to "sent", the builder
+  schema's stated default is "not sent"; verify against whichever backend
+  you're publishing to rather than carrying an assumption across.
+
+If you're not authoring a non-CDP interceptor script that specifically needs
+to observe the current page's own document request, leave this alone (the
+default already matches the standard flow on old-devtools; on builder, this
+field isn't touched by `create_provider_version_from_capture` at all).
+
+## `bodySniff` — unrelated to the above
+
+A per-request field (sits next to `url`/`method` on each `requestData` entry,
+not a version-level setting): `{ enabled: boolean, template: string }`. Per
+the InApp SDK's own type comment, it's "the template used for matching and
+extracting params from `requestBody`" — the REQUEST-body counterpart of
+`responseMatches`/`responseRedactions`, which only ever look at the response.
+It applies regardless of `injectionType`/`interceptorType`. Both publish
+tools in this package already set it for you from `provider.body` — you
+should not need to touch it directly.
+
+## Recognizing this on a provider you didn't author
+
+`get_provider_version_config` (old-devtools) and `get_provider_info` (public
+SDK backend) both return the raw `providerConfig`. If you see
+`injectionType`/`interceptorType` set to anything other than the inert
+default AND a `customInjection`/`jsUserScripts` that calls
+`reclaimInterceptor.addResponseMiddleware` (or references `MSWJS`/`XHook`),
+that provider is on the live-interception path, not the standard replay
+flow — read the script before assuming you can safely carry it forward or
+edit around it. If, on top of that, the request being proven IS the login/
+landing page itself (its `url` matches `loginUrl`, i.e. it's the document
+request, not a separate API call) and `injectionType`/`interceptorType`
+isn't `CDP`, also check `disableRequestReplay`/
+`isDocumentRequestReplayEnabled` — `true` there means that request was
+deliberately routed around live interception for site-compatibility
+reasons, not an oversight.