@reclaimprotocol/agent 0.1.21 → 0.1.23

package/lib/proof/replay.js

@@ -1,6 +1,6 @@
 /** Expand `{{name}}` placeholders from `paramValues`. Matches the attestor
  *  SDK's behavior so replay and proof both hit the same final URL. */
-function expandTemplate(s, params) {
+export function expandTemplate(s, params) {
     if (!params) {
         return s;
     }
@@ -9,7 +9,7 @@ function expandTemplate(s, params) {
         return v !== undefined ? v : match;
     });
 }
-export async function replayProvider(provider, secrets) {
+export function buildReplayRequest(provider, secrets) {
     const params = provider.paramValues;
     const url = expandTemplate(provider.url, params);
     const expandedHeaders = {};
@@ -17,21 +17,29 @@ export async function replayProvider(provider, secrets) {
         expandedHeaders[k] = expandTemplate(v, params);
     }
     const headers = { ...expandedHeaders, ...secrets };
-    const fetchInit = {
+    const body = provider.body !== undefined
+        ? expandTemplate(provider.body, params)
+        : undefined;
+    return {
+        url,
         method: provider.method,
         headers,
-        redirect: 'manual',
+        ...(body !== undefined ? { body } : {}),
     };
-    if (provider.body !== undefined) {
-        fetchInit.body = expandTemplate(provider.body, params);
-    }
-    const res = await fetch(url, fetchInit);
-    const body = await res.text();
+}
+/**
+ * Judge a replayed response against `provider`'s matchers — the part of
+ * replay that's identical regardless of HOW the request was sent (detached
+ * Node `fetch` or a live in-browser `fetch`). Separated from the actual
+ * network call so both transports share one evaluation.
+ */
+export function evaluateReplay(status, body, provider) {
+    const params = provider.paramValues;
     const hints = [];
-    if (res.status === 401 || res.status === 403) {
+    if (status === 401 || status === 403) {
         hints.push('auth/permission failed');
     }
-    if (res.status >= 500) {
+    if (status >= 500) {
         hints.push('upstream server error');
     }
     for (const m of provider.responseMatches) {
@@ -45,22 +53,35 @@ export async function replayProvider(provider, secrets) {
             value: expandTemplate(m.value, params),
         };
         if (!matchesBody(body, expanded)) {
-            if (res.status >= 200 && res.status < 300) {
+            if (status >= 200 && status < 300) {
                 hints.push(`matcher ${expanded.type} did not match — ` +
                     'value may have changed or matcher is too tight');
             }
-            const result = {
-                status: res.status,
-                body,
-                matchesOriginal: false,
-            };
+            const result = { status, body, matchesOriginal: false };
             if (hints.length > 0) {
                 result.hints = hints;
             }
             return result;
         }
     }
-    return { status: res.status, body, matchesOriginal: res.status < 400 };
+    return { status, body, matchesOriginal: status < 400 };
+}
+/** Detached Node-side replay: sends the request directly from this process,
+ *  NOT from any attached browser tab — its cookies/secrets are exactly the
+ *  `secrets` passed in, never a real browser session. Used by tests and by
+ *  any caller with no live browser to replay through (the MCP's authoring
+ *  backend instead runs the SAME request inside the attached tab — see
+ *  `proof/page-replay.ts` — so replay reflects real session cookies). */
+export async function replayProvider(provider, secrets) {
+    const req = buildReplayRequest(provider, secrets);
+    const res = await fetch(req.url, {
+        method: req.method,
+        headers: req.headers,
+        redirect: 'manual',
+        ...(req.body !== undefined ? { body: req.body } : {}),
+    });
+    const body = await res.text();
+    return evaluateReplay(res.status, body, provider);
 }
 function matchesBody(body, m) {
     if (m.type === 'regex') {

package/lib/provider/draft.d.ts

@@ -57,4 +57,6 @@ export declare function assertNoOprfUrlConflict(url: string, targets: DraftTarge
  *  header (same class of problem as {@link assertNoOprfUrlConflict} for
  *  OPRF-hashed targets, which has no such budget at all). */
 export declare function assertNoSecretUrlConflict(url: string, secrets: Record<string, string>, writeRedactionMode?: ReclaimProvider['writeRedactionMode']): void;
-export declare function draftProvider(req: CapturedRequest, targets: DraftTarget[], name: string, hash?: OprfMode): DraftResult;
+export declare function draftProvider(req: CapturedRequest, targets: DraftTarget[], name: string, hash?: OprfMode, opts?: {
+    shortenNames?: boolean;
+}): DraftResult;

package/lib/provider/draft.js

@@ -192,7 +192,32 @@ function deriveParamName(providerName) {
     const last = tokens[tokens.length - 1] ?? 'value';
     return last.toLowerCase();
 }
-export function draftProvider(req, targets, name, hash) {
+/** A `paramName` doubles as a regex NAMED CAPTURE GROUP (`(?<name>...)`) and a
+ *  `paramValues` object key — both require a plain identifier. Nothing
+ *  downstream validates this: an invalid name builds a syntactically broken
+ *  regex that silently fails to extract at verification time instead of
+ *  erroring here, at draft time, where it's actually fixable. */
+const VALID_PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Resolve a target's `paramName`: shortened (the default — last alphanumeric
+ *  token, lowercased) or, with `shorten: false`, the name verbatim — the
+ *  caller's choice, validated so it's still safe as a capture-group
+ *  identifier. */
+function resolveParamName(targetName, shorten) {
+    if (!shorten) {
+        if (!VALID_PARAM_NAME.test(targetName)) {
+            throw new Error(`target name "${targetName}" isn't safe as a param name with `
+                + 'shortenNames:false — it becomes a regex capture-group name AND '
+                + 'a paramValues key, so it must start with a letter/underscore and '
+                + 'contain only letters, digits, and underscores (we recommend '
+                + 'lower_snake_case, e.g. "employer_name"). Rename it, or drop '
+                + '`shortenNames: false` to auto-derive a safe one.');
+        }
+        return targetName;
+    }
+    return deriveParamName(targetName);
+}
+export function draftProvider(req, targets, name, hash, opts) {
+    const shortenNames = opts?.shortenNames ?? true;
     if (!req.responseBody) {
         throw new Error(`captured request ${req.requestId} has no response body`);
     }
@@ -207,14 +232,21 @@ export function draftProvider(req, targets, name, hash) {
     const extractions = [];
     const effectiveHashes = [];
     let paramValues;
-    const seenParams = new Set();
+    const seenParams = new Map();
     for (const t of targets) {
-        const paramName = deriveParamName(t.name);
-        if (seenParams.has(paramName)) {
-            throw new Error(`two targets resolve to the same param "${paramName}"; `
-                + 'give them distinct names');
+        const paramName = resolveParamName(t.name, shortenNames);
+        const priorName = seenParams.get(paramName);
+        if (priorName !== undefined) {
+            throw new Error(`targets "${priorName}" and "${t.name}" both resolve to the same `
+                + `param name "${paramName}"`
+                + (shortenNames
+                    ? ' (names are shortened to their last alphanumeric token) — '
+                        + 'give them more distinct names, e.g. "firstName"/"surname" '
+                        + 'instead of "first_name"/"last_name"'
+                    : ' — give them distinct names, or drop `shortenNames: false` '
+                        + 'to auto-derive distinct ones'));
         }
-        seenParams.add(paramName);
+        seenParams.set(paramName, t.name);
         // Precedence: explicit per-target hash → explicit request-wide hash →
         // the anti-leak floor (force-OPRF values whose SHAPE is unambiguous PII).
         // The model makes the contextual calls (which named fields are sensitive)

package/lib/provider/matcher.js

@@ -117,18 +117,34 @@ function jsonMatcher(body, target, paramName, valueClass, hash) {
     if (!jsonPath) {
         return undefined;
     }
-    const anchor = jsonKeyPrefix(body, target);
+    const anchor = jsonKeyPrefix(body, target, lastPathKey(jsonPath));
     if (!anchor) {
         return undefined;
     }
     return keyValueResult(anchor.prefix, anchor.close, target, paramName, valueClass, { jsonPath }, hash);
 }
+/** The trailing object-property name of a jsonPath (`$.total_records` →
+ *  `"total_records"`), or undefined for an array-index/bracket leaf, which
+ *  has no literal key to anchor a search on. */
+function lastPathKey(jsonPath) {
+    const m = jsonPath ? /\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(jsonPath) : null;
+    return m?.[1];
+}
 /**
  * The literal `"key":"` (or `"key":` for a raw number/bool) immediately before
  * `target` in `text`, plus the closing quote (`"` for a string value, `''`
  * otherwise). Returns undefined when the value isn't preceded by a JSON key.
+ *
+ * When `key` is given, anchors the search on occurrences of the KEY (not the
+ * value) — so a short/common value elsewhere in the body (e.g. the digit "5"
+ * inside `"investment_amount":354.85`) can't be mistaken for this field. Only
+ * falls back to a whole-body value search when there's no resolvable key
+ * (e.g. `findJsonPath` returned an array-index leaf).
  */
-function jsonKeyPrefix(text, target) {
+function jsonKeyPrefix(text, target, key) {
+    if (key !== undefined) {
+        return jsonKeyPrefixByKey(text, target, key);
+    }
     const { idx } = firstIndex(text, target);
     if (idx < 0) {
         return undefined;
@@ -157,6 +173,61 @@ function jsonKeyPrefix(text, target) {
     }
     return { prefix: text.slice(keyStart, idx), close: quoted ? '"' : '' };
 }
+/** `jsonKeyPrefix`'s key-anchored path: scan occurrences of `"key"`, and for
+ *  each, check whether the value that follows its `:` matches `target` (or a
+ *  normalized candidate) before accepting it. */
+function jsonKeyPrefixByKey(text, target, key) {
+    const keyToken = `"${key}"`;
+    let from = 0;
+    for (;;) {
+        const keyIdx = text.indexOf(keyToken, from);
+        if (keyIdx < 0) {
+            return undefined;
+        }
+        from = keyIdx + keyToken.length;
+        let i = from;
+        while (i < text.length && /\s/.test(text[i] ?? '')) {
+            i++;
+        }
+        if (text[i] !== ':') {
+            continue;
+        }
+        i++;
+        while (i < text.length && /\s/.test(text[i] ?? '')) {
+            i++;
+        }
+        const matched = matchJsonValueAt(text, i, target);
+        if (matched) {
+            return {
+                prefix: text.slice(keyIdx, matched.valueStart),
+                close: matched.close,
+            };
+        }
+    }
+}
+/** Whether the JSON value starting at `pos` in `text` — quoted string or a
+ *  raw number/bool/null token — equals `target` (or a normalized candidate).
+ *  Returns the position right after any opening quote (matching `firstIndex`'s
+ *  convention) and the delimiter to close the match template with. */
+function matchJsonValueAt(text, pos, target) {
+    const candidates = [target, ...normalizeCandidates(target)];
+    if (text[pos] === '"') {
+        let j = pos + 1;
+        while (j < text.length && text[j] !== '"') {
+            j += text[j] === '\\' ? 2 : 1;
+        }
+        const raw = text.slice(pos + 1, j);
+        return candidates.includes(raw)
+            ? { valueStart: pos + 1, close: '"' }
+            : undefined;
+    }
+    let j = pos;
+    while (j < text.length && !/[,}\]\s]/.test(text[j] ?? '')) {
+        j++;
+    }
+    const raw = text.slice(pos, j);
+    return candidates.includes(raw) ? { valueStart: pos, close: '' } : undefined;
+}
 function findJsonPath(body, target) {
     let parsed;
     try {
@@ -226,7 +297,9 @@ function htmlMatcher(body, target, paramName, valueClass, hash) {
     const scriptJson = scriptJsonContent(revealSlice);
     if (scriptJson) {
         const jsonPath = findJsonPath(scriptJson, target);
-        const kp = jsonPath ? jsonKeyPrefix(scriptJson, target) : undefined;
+        const kp = jsonPath
+            ? jsonKeyPrefix(scriptJson, target, lastPathKey(jsonPath))
+            : undefined;
         if (jsonPath && kp) {
             return keyValueResult(kp.prefix, kp.close, target, paramName, valueClass, { xPath: anchor.xPath, jsonPath }, hash);
         }
@@ -396,7 +469,7 @@ function contentMatcher(body, target, paramName, valueClass, hash) {
         return {
             match: {
                 type: 'contains',
-                value: buildContextualTemplate(body, target, paramName),
+                value: buildContextualTemplate(body, target, paramName, valueClass),
             },
             redaction,
             paramValues: { [paramName]: target },
@@ -421,12 +494,47 @@ function contentMatcher(body, target, paramName, valueClass, hash) {
  * must CONTAIN the match template (buildContextualTemplate), so the trailing
  * delimiter is kept unless it's whitespace (which the template also drops).
  */
+/** Indices where `cand` occurs in `body` as a WHOLE match of `valueClass` —
+ *  i.e. not a substring inside a longer run of the same class (the digit "5"
+ *  inside "354.85" is never a whole `\d+` match; "354" and "85" are). Only
+ *  meaningful for a structural (non-free-form) class. */
+function wholeTokenIndices(body, cand, valueClass) {
+    const indices = [];
+    let re;
+    try {
+        re = new RegExp(valueClass, 'g');
+    }
+    catch {
+        return indices;
+    }
+    let m;
+    while ((m = re.exec(body))) {
+        if (m[0] === cand) {
+            indices.push(m.index);
+        }
+        if (re.lastIndex === m.index) {
+            re.lastIndex++;
+        }
+    }
+    return indices;
+}
 function buildContentRegex(body, target, paramName, valueClass) {
+    const structural = inferValueClass(target) !== undefined;
     for (const cand of normalizeCandidates(target)) {
-        const idx = body.indexOf(cand);
+        const occurrences = structural
+            ? wholeTokenIndices(body, cand, valueClass)
+            : undefined;
+        const idx = occurrences ? occurrences[0] ?? -1 : body.indexOf(cand);
         if (idx < 0) {
             continue;
         }
+        if (occurrences && occurrences.length > 1
+            && cand.replace(/[^A-Za-z0-9]/g, '').length < 4) {
+            throw new Error(`target value "${target}" occurs ${occurrences.length} times as a `
+                + 'standalone token with no JSON key or HTML anchor to '
+                + "disambiguate — capture a request where it's unique, or use a "
+                + 'longer/more specific target.');
+        }
         const endIdx = idx + cand.length;
         const rawRight = findRightContext(body, endIdx);
         const right = /^\s/.test(rawRight) ? '' : escapeRegexFlexWs(rawRight);
@@ -456,8 +564,9 @@ function buildContentRegex(body, target, paramName, valueClass) {
  * literal contains can't flex whitespace); stable context (a JSON key, an HTML
  * opening tag) is kept so the match anchors on it.
  */
-function buildContextualTemplate(body, target, paramName) {
-    const idx = body.indexOf(target);
+function buildContextualTemplate(body, target, paramName, valueClass) {
+    const idx = wholeTokenIndices(body, target, valueClass)[0]
+        ?? body.indexOf(target);
     if (idx < 0) {
         return `{{${paramName}}}`;
     }

package/lib/provider/to-version.d.ts

@@ -54,14 +54,16 @@ export interface CreateVersionOptions {
     jsUserScripts?: string;
     /** Requests the injection script may fire, as `RequestSelectionTemplate`s. */
     allowedJsRequests?: AllowedJsRequest[];
-    /** In-app interception options, mapped verbatim to
-     *  `webSettings.clientOptions.inapp.interceptorOptions`. `interceptorType`
-     *  is required by the backend whenever the object is present.
-     *  `isDocumentRequestReplayEnabled` is the INVERSE of old-devtools'
-     *  `disableRequestReplay` (default false). */
+    /** In-app interception options, mapped to
+     *  `webSettings.clientOptions.inapp.interceptorOptions` — ONLY when this
+     *  is explicitly passed (builder's schema has no `NONE` interceptorType;
+     *  omitting `inapp` entirely IS the "no interception" signal, so omitting
+     *  this must omit `inapp`, not default it to HAWKEYE). When it IS passed,
+     *  `isDocumentRequestReplayEnabled` is still ALWAYS force-disabled
+     *  regardless of what's passed here — see `providerToCreateVersionRequest`;
+     *  there is no author-facing way to enable it. */
     interceptorOptions?: {
         interceptorType: 'HAWKEYE' | 'MSWJS' | 'CDP';
-        isDocumentRequestReplayEnabled?: boolean;
         interceptorSettings?: string;
     };
 }

package/lib/provider/to-version.js

@@ -130,14 +130,26 @@ export function providerToCreateVersionRequest(providers, initialUrl, opts = {})
             geoLocation: pickGeoLocation(providers),
             clientOptions: {
                 portal: { useProxy: true },
+                // Builder's schema has NO "NONE" interceptorType — the real
+                // no-interception signal is OMITTING `inapp` entirely (it's not
+                // `required` on `InAppClientOptions`). So `inapp` is only built at
+                // ALL when the author explicitly opts into a real interceptorType;
+                // omitting `interceptorOptions` must omit `inapp` too, or every
+                // standard (non-interception) provider would incorrectly publish
+                // as HAWKEYE. Within that block, `isDocumentRequestReplayEnabled`
+                // is still force-disabled — see `CreateVersionOptions
+                // .interceptorOptions`'s doc comment; there is no way to enable it.
                 ...(interceptorOptions
                     ? {
                         inapp: {
                             interceptorOptions: {
-                                // openapi `default: false` — the generated type
-                                // requires the key even when the author omits it.
+                                interceptorType: interceptorOptions.interceptorType,
                                 isDocumentRequestReplayEnabled: false,
-                                ...interceptorOptions,
+                                ...(interceptorOptions.interceptorSettings
+                                    ? {
+                                        interceptorSettings: interceptorOptions.interceptorSettings,
+                                    }
+                                    : {}),
                             },
                         },
                     }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.21",
+	"version": "0.1.23",
 	"description": "Reclaim Protocol's tools for agents — 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.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -83,10 +83,11 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.0.8",
-		"@reclaimprotocol/client": "0.1.21",
+		"@reclaimprotocol/client": "0.1.23",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",
+		"openid-client": "^6.8.5",
 		"parse5": "^8.0.0",
 		"parse5-htmlparser2-tree-adapter": "^8.0.0",
 		"pino": "^9.14.0",

package/skill/SKILL.builder.md

@@ -173,7 +173,9 @@ The value of any parameter marked secret is not included in the final proof, omi
 
     When done, tell the developer the version is live (PRIVATE) or submitted for review (PUBLIC), and that they can integrate using the `providerId`.
 
-    - **If a browser is still attached**, `create_provider_version_from_capture`'s response carries a `_notes` reminder about it. Surface that to the dev and ask whether they want to keep the session open for further edits — only call `dispose_browser` once they confirm they're done. Never close it unprompted; a `builder`-mode session is quota-accounted, but the dev may still be mid-workflow.
+    - **If a browser is still attached**, `create_provider_version_from_capture`'s response carries a `_notes` reminder about it. Surface that to the dev and ask whether they want to keep the session open for further edits — only call `dispose_browser` once they confirm they're done. Never close it unprompted; a `builder`-mode session is quota-accounted, but the dev may still be mid-workflow. Closing remote browsers
+    soon is also important to avoid wasting resources. So as best
+    practise, close remote browser session when not needed anymore.
 
 <!-- common: concerns-section -->
 
@@ -206,4 +208,4 @@ If `replay_request` or `run_proof` errors with `unknown draftId` (or `no capture
 
 ## Recognizing a HAWKEYE / live-interception provider
 
-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.
+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` exposes `interceptorOptions.interceptorType` as an author-settable input for exactly this — pass it (plus a script that calls `addResponseMiddleware`) to opt INTO real interception. Omit `interceptorOptions` entirely for the standard flow (the default) — the tool correctly omits `inapp` rather than defaulting it to `HAWKEYE`, since builder's schema has no `NONE` interceptorType and omitting the whole object IS the no-interception signal. `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. The tool always force-disables it (`false`) whenever `interceptorOptions` is passed at all — there is no way to enable it through `create_provider_version_from_capture`. See `injection-api.md` (embedded in the `jsUserScripts` field description) for the source-verified breakdown before guessing at what they mean.

package/skill/SKILL.common.md

@@ -11,13 +11,22 @@
 > If a developer calls the recipe a "verification," gently use "provider"
 > yourself rather than correcting them.
 
+> **Terminology note:** "JS injection", "custom injection", "user script",
+> and "web script" all refer to the SAME thing when talking about a
+> provider — the plain browser JS that runs before every page load to drive
+> navigation for data gated behind login/routing. Builder's schema field is
+> `jsUserScripts`; old-devtools' equivalent field is `customInjection`
+> (identical semantics, different name). Prefer **"user script"** in your
+> own prose regardless of which backend you're on; see `injection-api.md`
+> for the full field-level reference.
+
 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.
 
 <!-- section: step-attach -->
 1. **Attach.** Call `attach_browser`. If it returns `needsChoice: true`, ask the dev which browser source they want:
    - `dedicated` — agent auto-launches Chrome with a dedicated profile under `~/.reclaim/chrome-profile`. Easiest local path; works out of the box.
    - `attach` — connect to a Chrome the dev is already running. **Important Chrome 136+ gotcha:** the dev's Chrome must be launched with BOTH `--remote-debugging-port=9222` AND `--user-data-dir=<some-non-default-path>`. Since Chrome 136 (May 2025), the debug-port flag is silently ignored when the default user profile is in use. If `attach` fails, tell them this verbatim and offer to switch to `dedicated`.
-   - `builder` — allocate a quota-accounted remote Popcorn browser. Obtain an `orgId` with `list_builder_organizations` in old-devtools mode or the generated `list_orgs` tool in Builder mode. If Builder answers 401, authenticate with `authenticate_builder` in old-devtools mode or the existing `authenticate` flow in Builder mode, then retry. Return the FULL `liveViewUrl` to the dev verbatim — on its own line, never abbreviated, elided, or wrapped in prose that truncates it — so it stays one clean, copy-pasteable string; they'll share it with the volunteer operating the browser. This works in both publishing modes and consumes one VERIFICATION-pool use under the chosen organization's normal plan restrictions.
+   - `builder` — allocate a quota-accounted remote Popcorn browser. If Builder answers 401, authenticate with `authenticate_builder` in old-devtools mode or the existing `authenticate` flow in Builder mode, then retry. You can omit `orgId` and call `attach_browser` directly: it auto-resolves to the account's only organization, or — if the account belongs to more than one — comes back with `needsChoice: true` and an `organizations` list; **ask the dev which one to use** (don't guess or default to the first) and re-call `attach_browser` with that `orgId`. (`list_builder_organizations` in old-devtools mode / `list_orgs` in Builder mode still work directly if you want the list up front instead.) Return the FULL `liveViewUrl` to the dev verbatim — on its own line, never abbreviated, elided, or wrapped in prose that truncates it — so it stays one clean, copy-pasteable string; they'll share it with the volunteer operating the browser. This works in both publishing modes and consumes one VERIFICATION-pool use under the chosen organization's normal plan restrictions.
    - `custom` — connect to a `ws://` or `wss://` CDP URL supplied by the dev. The URL is a credential: never repeat it, log it, or persist it. An optional `liveViewUrl` may be returned — if so, share it FULL and verbatim, same as `builder` above.
 
    Re-call with the chosen `mode` and its required fields.

package/skill/SKILL.old.md

@@ -174,4 +174,4 @@ If `replay_request` or `run_proof` errors with `unknown secretParamsRef`:
 
 ## Recognizing a HAWKEYE / live-interception provider
 
-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.
+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. `create_provider_version_from_capture` now exposes `injectionType` as an author-settable input — pass one of `HAWKEYE`/`MSWJS`/`XHOOK`/`CDP` (plus a `customInjection` script that calls `addResponseMiddleware`) to author this flow. Omit it for the standard flow: there's no forced default, so the old backend's own schema default (`HAWKEYE`) applies, same as before this field was exposed — that's fine, it's inert with no interceptor script installed. Pass `NONE` explicitly instead if you want certainty rather than relying on the backend default. Don't assume `injectionType` present-but-not-`NONE` on an EXISTING provider (`get_provider_version_config`, `get_provider_info`) means something is broken — HAWKEYE-by-default is normal and harmless for the standard flow on both new and old providers. `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. `create_provider_version_from_capture` always force-publishes this `true` now (auto-following a fresh register with an add-version call to apply it, since register hardcodes it `false`) — there is no author-facing way to leave it off. 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/injection-api.md

@@ -53,18 +53,30 @@ 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.
+  HAWKEYE` — confirmed the literal field name against a real snapshot of
+  legacy-backend provider data (`packages/app/scripts/data/
+  provider-configs.snapshot.json`, captured straight from the old-devtools
+  Mongo `Provider`/`ProviderVersion.providerConfig`). The backend's own
+  column default is `HAWKEYE`, not `NONE` — harmless for the standard flow
+  (no interceptor script installed, so nothing calls
+  `addResponseMiddleware`). `create_provider_version_from_capture`
+  (old-devtools mode) now exposes `injectionType` as an author-settable
+  input, with NO forced default — omit it and the backend's own `HAWKEYE`
+  default applies, same as before this field was exposed at all; pass an
+  explicit value (including `NONE`) if you want certainty either way. When
+  passed, it's sent on both register and add-version; since it's unverified
+  whether the register controller actually persists it (no source access to
+  confirm), the tool's existing always-on add-version follow-up (see
+  `disableRequestReplay` below) reapplies it regardless, so an explicit value
+  is guaranteed correct by the time the follow-up version lands.
 - **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.
+  one of `HAWKEYE | MSWJS | CDP` (no `NONE`/`XHOOK` in this schema — omitting
+  `interceptorOptions` entirely is builder's NONE-equivalent).
+  `create_provider_version_from_capture` (builder mode) exposes
+  `interceptorOptions.interceptorType` as an author-settable input; passing
+  it is how you opt INTO real interception. Omit it (the default) for the
+  standard flow, and the tool correctly omits `inapp` — it does NOT default
+  to `HAWKEYE` (that was a bug in an earlier version of this tool; fixed).
 
 **The mechanisms, and why you'd pick one over plain replay:**
 - **`CDP`** — interception at the browser/DevTools-protocol level, below the
@@ -83,6 +95,24 @@ thing.
 
 ## `disableRequestReplay` / `isDocumentRequestReplayEnabled`
 
+**`create_provider_version_from_capture` always force-disables this now, in
+BOTH backends** — old-devtools always publishes `disableRequestReplay: true`
+(the tool auto-follows a fresh register with an add-version call to apply
+it, since the register endpoint hardcodes it `false` regardless of what's
+sent). Builder always publishes `isDocumentRequestReplayEnabled: false`
+under `webSettings.clientOptions.inapp.interceptorOptions` **whenever you
+pass `interceptorOptions` at all** — but if you don't (the standard,
+non-interception flow), the tool omits `inapp` entirely rather than forcing
+a default `interceptorType`, because builder's schema has no `NONE`
+interceptorType: omitting the whole object IS its no-interception signal,
+and defaulting it to (even inert) `HAWKEYE` would misrepresent the
+provider. There is no author-facing way to turn document replay back on
+through either tool once `interceptorOptions`/`injectionType` is in play.
+The rest of this section explains the underlying platform semantics for
+context (e.g. reading an existing provider someone else published outside
+these tools) — the replay sub-flag itself is no longer something you
+configure here.
+
 **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
@@ -125,10 +155,9 @@ Field names, per backend:
   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).
+There is nothing to configure here through `create_provider_version_from_capture`
+any more (see the note at the top of this section) — both backends always
+publish with document replay disabled.
 
 ## `bodySniff` — unrelated to the above
 

package/skill/old-mode.md

@@ -2,7 +2,7 @@ This server is running against the devtools backend, so its capabilities are int
 
 **Provider-authoring flow:**
 
-1. `reclaim_authenticate` — by default opens the dashboard in Chrome, waits for you to sign in, captures the token automatically, and closes the tab (or paste a `token` / pass an eth `ethAddress` to skip the browser). Do this once before publishing or listing.
+1. `reclaim_authenticate` — by default opens the dashboard in Chrome, waits for you to sign in, captures the token automatically, and closes the tab (or paste a `token` / pass an eth `ethAddress` to skip the browser). Do this once before publishing or listing. (Note: this old-devtools login is separate from `authenticate_builder`, which is needed only for the two Builder-exclusive features below — remote-browser allocation and org listing — see the auth troubleshooting note below.)
 2. `attach_browser` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`). Browser source is independent of this publishing mode: local Chrome works as before; `builder` uses `authenticate_builder` + `list_builder_organizations` to allocate a quota-accounted Popcorn browser and returns a shareable live-view URL; `custom` accepts a caller-supplied CDP websocket.
 3. `propose_provider` to draft a provider, `replay_request` to pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` redactions are optional and supported. When the data spans MULTIPLE requests (e.g. a landing call + a details call), propose + `run_proof` EACH request to get one proven draft per request.
 4. `create_provider_version_from_capture` to publish. With NO `providerId` it REGISTERS A NEW provider (re-running creates a duplicate); pass a `providerId` from `get_me_providers` to add a new version to an existing provider instead. For a MULTI-REQUEST provider, pass `providers: [draftA, draftB, …]` (every proven draft) so EACH becomes a parallel `requestData` entry on the one version — passing a single `provider` saves only that one request.
@@ -10,6 +10,8 @@ This server is running against the devtools backend, so its capabilities are int
 
 **Editing / new versions (ownership):** you can only add a version to a provider **you own** — the `providerId` must come from `get_me_providers`. Trying to version a public provider you don't own fails with a permission error; that is expected. To publish your own version of such a site, re-run `create_provider_version_from_capture` **without** `providerId` to register your own copy (a separate provider you own). If versioning a provider you *do* own fails, confirm you authenticated as the account that created it.
 
+**Two independent auth systems — don't confuse them:** `authenticate_builder` and `reclaim_authenticate` log into DIFFERENT backends and are NOT interchangeable. In THIS mode (old-devtools), `authenticate_builder` is needed only for two Builder-exclusive features — allocating a Popcorn remote browser (`attach_browser mode="builder"`) and listing Builder organizations (`list_builder_organizations`, since old-devtools has no generated org tool of its own). It does not authorize `create_provider_version_from_capture`, `get_me_providers`, or any other old-devtools call — those need their own `reclaim_authenticate` login. (Builder mode, by contrast, needs no separate login at all — its one native auth tool covers everything, org listing included via `list_orgs`.) `get_devtools_mode` reports the presence of both. If a publish or `get_me_providers` call fails with an auth error even though you (or the dev) already ran `reclaim_authenticate` once before, the old-devtools token has likely expired (Firebase tokens are short-lived, ~1h) — re-run `reclaim_authenticate` and retry; don't assume `authenticate_builder` fixes it.
+
 Only GET/POST endpoints can be captured into providers here. There is no Builder organization-management, credential-linking, or public-review workflow in this mode; the narrow `authenticate_builder` and `list_builder_organizations` exception exists only to allocate Builder-hosted authoring browsers.
 
 **Diagnosing a session:** `session_analytics_logs` fetches the analytics logs for a verification session by id (from the logs service) — use it to see what happened in a session (matches, claims, failures).

package/src/authoring/backend.ts

@@ -90,13 +90,15 @@ export interface AuthoringBackend {
 	 *  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.
+	 * Validate/replay a drafted recipe before proving. Both local and remote
+	 * backends re-issue the request FROM INSIDE the live attached page (a
+	 * `fetch` run over CDP), never a detached out-of-band call, so replay
+	 * 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
+	 * authenticated request. The shape is environment-specific and passed
+	 * straight through as the tool's result.
 	 */
 	replay(draft: Draft, opts?: { withoutSecrets?: boolean }): Promise<unknown>
 }