@reclaimprotocol/agent 0.1.22 → 0.1.23

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.22",
+	"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.22",
+		"@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

@@ -208,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,6 +11,15 @@
 > 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 -->

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>
 }

package/src/authoring/tools.ts

@@ -179,6 +179,118 @@ export function authoringTools(
 				return { ready: false }
 			},
 		),
+		defineTool<Record<string, unknown>>(
+			{
+				name: 'test_user_script',
+				description:
+					'Dry-run a USER SCRIPT — the same thing as the `jsUserScripts` / '
+					+ '`customInjection` field on a published provider: plain browser '
+					+ 'JS that runs before every page load, used to drive navigation '
+					+ 'for data gated behind login/routing — in the LIVE attached tab, '
+					+ 'BEFORE publishing. Installs `script` via CDP so it runs on the '
+					+ 'next navigation exactly like the real field would, then reports '
+					+ 'whether it ran and any errors it threw. Catches bugs (e.g. a '
+					+ 'listener registered with setTimeout that never fires because the '
+					+ "page was already past 'load' by the time it ran) before they "
+					+ 'surface in a real end-user session instead of after. If '
+					+ '`navigateUrl` is given, navigates there after installing, then '
+					+ 'removes the script again once the result is read (self-cleaning '
+					+ '— safe to call repeatedly). Without `navigateUrl` the script is '
+					+ 'left installed for you to navigate yourself (any way you like) '
+					+ 'then re-call this tool, or read '
+					+ '`window.__reclaimUserScriptResult` via eval_in_page — in that '
+					+ 'manual mode it is NOT auto-removed and keeps running on every '
+					+ 'later navigation until a follow-up call with `navigateUrl` '
+					+ 'removes it, so avoid stacking several manual-mode calls in a '
+					+ 'row.',
+				inputSchema: objectSchema(
+					{
+						script: { type: 'string' },
+						navigateUrl: { type: 'string' },
+						timeoutMs: { type: 'number' },
+					},
+					['script'],
+				),
+			},
+			async(args) => {
+				const backend = resolveBackend(args)
+				const script = String(args.script)
+				// The user's script is spliced in as a STRING and compiled at
+				// runtime via `new Function`, not as raw top-level source: a
+				// syntax error in it would otherwise fail to parse the entire
+				// wrapper (result init, error listener, and try/catch included),
+				// so the tool would report ran:false / errors:[] instead of the
+				// actual SyntaxError.
+				const wrapped = `
+					window.__reclaimUserScriptResult = { ran: false, errors: [] };
+					window.addEventListener('error', function(e) {
+						window.__reclaimUserScriptResult.errors.push(String(e.message));
+					});
+					try {
+						(new Function(${JSON.stringify(script)}))();
+						window.__reclaimUserScriptResult.ran = true;
+					} catch(e) {
+						window.__reclaimUserScriptResult.errors.push(
+							String((e && e.message) || e),
+						);
+					}
+				`
+				const installed = (await backend.sendCdp(
+					'Page.addScriptToEvaluateOnNewDocument', { source: wrapped },
+				)) as { identifier?: string }
+
+				if(typeof args.navigateUrl !== 'string') {
+					return {
+						installed: true,
+						note:
+							'Installed for the NEXT navigation only — it did not run on '
+							+ 'the current page, and stays installed (runs on every later '
+							+ 'navigation too) until a follow-up call with navigateUrl '
+							+ 'removes it. Navigate now (e.g. the navigate tool), then read '
+							+ 'window.__reclaimUserScriptResult via eval_in_page, or call '
+							+ 'test_user_script again with navigateUrl.',
+					}
+				}
+
+				try {
+					const timeoutMs = Number(args.timeoutMs) || 30_000
+					await backend.sendCdp('Page.enable')
+					const load = backend.waitForEvent('Page.loadEventFired', timeoutMs)
+					const nav = (await backend.sendCdp(
+						'Page.navigate', { url: String(args.navigateUrl) },
+					)) as { errorText?: string }
+					if(nav.errorText) {
+						return { installed: true, navigated: false, error: nav.errorText }
+					}
+
+					await load
+					const { value, error } = await evalInPage(
+						backend, 'window.__reclaimUserScriptResult',
+					)
+					if(error) {
+						return { installed: true, navigated: true, error }
+					}
+
+					const result =
+						value as { ran?: boolean, errors?: string[] } | undefined
+					return {
+						installed: true,
+						navigated: true,
+						ran: result?.ran ?? false,
+						errors: result?.errors ?? [],
+					}
+				} finally {
+					// One-shot test: remove it so it doesn't keep running (and
+					// potentially redirecting the tab) on every later navigation.
+					if(installed.identifier) {
+						await backend.sendCdp(
+							'Page.removeScriptToEvaluateOnNewDocument',
+							{ identifier: installed.identifier },
+						)
+					}
+				}
+			},
+		),
 		defineTool<Record<string, unknown>>(
 			{
 				name: 'get_cookies',
@@ -321,7 +433,13 @@ export function authoringTools(
 				name: 'run_proof',
 				description:
 					'Prove the drafted recipe (zkTLS). Only call after replay_request '
-					+ 'looks right. Returns the proof result.',
+					+ 'looks right. Returns the proof result. NOTE: unlike '
+					+ 'replay_request (which re-issues from inside the live attached '
+					+ 'browser tab), the ATTESTOR calls the target from its OWN '
+					+ 'network/IP, separate from the browser\'s. A request that '
+					+ 'replayed fine can still fail here for geo/IP-bound content '
+					+ '(country-locked pages, IP-allowlisted APIs) — if that happens, '
+					+ 'it\'s a property of the site, not a bug in the draft.',
 				inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
 			},
 			// The backend shapes its own result: the cloud returns a lean,