@reclaimprotocol/agent 0.1.23 → 0.1.24

package/src/mcp/tools/mode/mode.ts

@@ -24,7 +24,7 @@ function hasValidBuilderSession(config: ConfigStore): boolean {
  * `~/.reclaim/config.json` and applied the NEXT time the server starts —
  * the registered tool set, server instructions, and backend client are all
  * fixed at connect time, so the switch requires a restart/reconnect. Follows
- * the `attach_chrome` persist-through-config pattern.
+ * the `attach_browser` persist-through-config pattern.
  *
  * Registered in BOTH modes (so the user can switch either direction) and
  * outside `buildAgentTools` (so it survives `RECLAIM_AGENT_DISABLED=1`). An
@@ -74,27 +74,15 @@ export function buildModeTools(
 			{
 				name: 'get_devtools_mode',
 				description:
-					'Report which backend this MCP server is currently targeting: '
-					+ '"old" (devtools) or "builder" (the builder '
-					+ 'backend). Also reports WHY that mode is in effect (source: '
-					+ 'a USE_OLD_DEVTOOLS env override, the persisted config, or '
-					+ 'the default) and which mode is persisted for the next '
-					+ 'start. Use set_devtools_mode to change it. Also reports '
-					+ 'AUTH status for BOTH auth systems — builderAuthenticated (the '
-					+ 'Builder OAuth login). In BUILDER mode this is the only login '
-					+ 'that exists and covers everything, including org listing '
-					+ '(list_orgs) and remote-browser allocation. In OLD-DEVTOOLS '
-					+ 'mode it is a SEPARATE, additional login (authenticate_builder) '
-					+ 'needed only for two Builder-exclusive features: remote-browser '
-					+ '(Popcorn) allocation and org listing (list_builder_organizations '
-					+ '— old-devtools has no generated org tool of its own). '
-					+ 'oldDevtoolsAuthenticated (the OLD-mode reclaim_authenticate) is '
-					+ 'required separately for create_provider_version_from_capture '
-					+ 'and get_me_providers, and only exists/matters in old-devtools '
-					+ 'mode. Both are presence checks, not '
-					+ 'validity checks — a stale old-devtools token still reports '
-					+ 'true here; a real publish/list call will surface staleness '
-					+ 'with a clear error pointing back at reclaim_authenticate.',
+					'Report which backend this server targets ("old" devtools or '
+					+ '"builder"), WHY (a USE_OLD_DEVTOOLS env override, the persisted '
+					+ 'config, or the default), and which mode is persisted for the '
+					+ 'next start. Change it with set_devtools_mode. Also reports auth '
+					+ 'status for both login systems: builderAuthenticated and '
+					+ 'oldDevtoolsAuthenticated. Both are PRESENCE checks, not validity '
+					+ 'checks — a stale token still reports true; a real call surfaces '
+					+ 'the staleness with an error naming the tool to re-run. Which '
+					+ 'login authorizes what: how_it_works({ topic: "auth" }).',
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => {

package/src/old/client.ts

@@ -50,7 +50,7 @@ export interface RegisterProviderBody {
 	/** Interception mechanism (`NONE` = standard replay flow, the default;
 	 *  `HAWKEYE`/`MSWJS`/`XHOOK` = JS-context interception; `CDP` = browser-
 	 *  level). Column default is `HAWKEYE` when omitted entirely — unlike
-	 *  `stepsToFollow` etc. above, whether the register endpoint actually
+	 *  `stepsToFollow`, and so on. above, whether the register endpoint actually
 	 *  PERSISTS this field is UNVERIFIED (no source access to confirm); sent
 	 *  here on the chance it does, but the publish tool always follows up
 	 *  with a config (add-version) call regardless, which is confirmed to
@@ -370,7 +370,7 @@ export class ReclaimOldClient {
 		// An identity ALREADY SET (as opposed to `#requireIdentity`'s "never
 		// authenticated" case, which never reaches the backend) plus either a
 		// 401/403 OR a message that itself names token verification means the
-		// backend rejected a token we had — i.e. it's stale/invalid, not merely
+		// backend rejected a token we had — that is, it's stale/invalid, not merely
 		// absent. The message check matters because this backend does NOT
 		// reliably use 401/403 for it — confirmed live: an actually-expired
 		// Firebase token surfaced as "Error while verifying token" with a

package/src/old/instructions.ts

@@ -2,14 +2,8 @@
  * MCP server instructions shown to the LLM when running in OLD-devtools mode
  * (`USE_OLD_DEVTOOLS` unset or not `false`). Describes the REDUCED tool
  * surface — there are no org/credential-link/review flows and no generated
- * API tools here. The prose lives in `skill/old-mode.md` (published via the
- * `files` array); the path resolves identically from `src/old` (dev) and
- * `lib/old` (published).
+ * API tools here. Both modes' instructions load together in
+ * `mcp/instructions` (alongside the topic-split authoring guide); re-exported
+ * here so old-mode callers keep importing from their own module.
  */
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-
-export const OLD_MODE_INSTRUCTIONS = readFileSync(
-	fileURLToPath(new URL('../../skill/old-mode.md', import.meta.url)),
-	'utf8',
-).trim()
+export { OLD_MODE_INSTRUCTIONS } from '../mcp/instructions.ts'

package/src/old/login-cdp.ts

@@ -97,8 +97,8 @@ export interface CdpLoginResult {
  * finish signing in, read the resulting Firebase ID token from page storage,
  * then clean up. If we had to launch a dedicated Chrome for this, we close the
  * whole browser afterwards; if we attached to a Chrome that was already up
- * (e.g. the capture flow's), we only close the tab we opened so we don't
- * disrupt it.
+ * (for example, the capture flow's), we only close the tab we opened so we
+ * don't disrupt it.
  */
 export async function captureFirebaseTokenViaCdp(opts: {
 	loginUrl?: string
@@ -107,7 +107,13 @@ export async function captureFirebaseTokenViaCdp(opts: {
 }): Promise<CdpLoginResult> {
 	const loginUrl =
 		opts.loginUrl || oldLoginUrl() || DEFAULT_LOGIN_URL
-	const timeoutMs = opts.timeoutMs ?? 180_000
+	// 6 minutes, not 3. On a FRESH Chrome profile the dashboard is a cold load
+	// of an ~8.6 MB uncompressed bundle before the login form is even
+	// interactive — tens of seconds on a slow link — and only then does the
+	// developer start typing credentials and a 2FA code. The old 3-minute
+	// budget was routinely spent before they could finish, and the retry that
+	// followed looked like a 6-minute hang with no output.
+	const timeoutMs = opts.timeoutMs ?? 360_000
 	const pollMs = opts.pollMs ?? 1000
 
 	const cfg = new ConfigStore().read()?.browser_agent
@@ -123,7 +129,7 @@ export async function captureFirebaseTokenViaCdp(opts: {
 			throw new Error(
 				`attach mode: nothing answering CDP on port ${port}. Launch Chrome ` +
 				`with --remote-debugging-port=${port} AND a non-default ` +
-				'--user-data-dir, or switch to dedicated mode (attach_chrome).',
+				'--user-data-dir, or switch to dedicated mode (attach_browser).',
 			)
 		}
 
@@ -139,6 +145,10 @@ export async function captureFirebaseTokenViaCdp(opts: {
 	try {
 		const session = await handles.attachToTab(targetId)
 		const deadline = Date.now() + timeoutMs
+		// Tracks how far the page got, so a timeout can say WHICH thing stalled:
+		// a bundle that never finished downloading is a different problem from a
+		// developer who walked away mid-sign-in.
+		let sawInteractivePage = false
 		while(Date.now() < deadline) {
 			const result = await session.send('Runtime.evaluate', {
 				expression: EXTRACT_TOKEN_JS,
@@ -150,12 +160,24 @@ export async function captureFirebaseTokenViaCdp(opts: {
 				return { token: value, closedBrowser: launchedByUs }
 			}
 
+			if(!sawInteractivePage) {
+				sawInteractivePage = await pageIsInteractive(session)
+			}
+
 			await new Promise((resolve) => setTimeout(resolve, pollMs))
 		}
 
+		const waited = Math.round(timeoutMs / 1000)
 		throw new Error(
-			'Timed out waiting for login. Finish signing in at the opened ' +
-			'page, or re-run reclaim_authenticate with a longer timeoutMs.',
+			`Timed out after ${waited}s waiting for login. `
+			+ (sawInteractivePage
+				? 'The page finished loading, so sign-in was never completed — '
+					+ 'ask the developer to finish signing in at the opened window, '
+					+ 'then re-run reclaim_authenticate.'
+				: 'The page never became interactive, so the dashboard was still '
+					+ 'loading the whole time. On a fresh Chrome profile its bundle '
+					+ 'is a large cold download. Retry (the profile is now warm), or '
+					+ 'pass a bigger timeoutMs.'),
 		)
 	} finally {
 		// Best-effort cleanup — never mask the real result/error.
@@ -173,6 +195,28 @@ export async function captureFirebaseTokenViaCdp(opts: {
 	}
 }
 
+/**
+ * Whether the login page has reached a usable state. `readyState` alone is not
+ * enough for a single-bundle SPA: the document is 'complete' while the app is
+ * still parsing, and nothing is clickable yet. Requiring a rendered root as
+ * well is what distinguishes "still loading" from "waiting for the human".
+ */
+async function pageIsInteractive(
+	session: { send: (m: string, p?: object) => Promise<unknown> },
+): Promise<boolean> {
+	try {
+		const result = await session.send('Runtime.evaluate', {
+			expression:
+				'document.readyState === "complete" '
+				+ '&& !!document.body && document.body.innerText.trim().length > 0',
+			returnByValue: true,
+		})
+		return runtimeResultValue(result) === true
+	} catch{
+		return false
+	}
+}
+
 function runtimeResultValue(value: unknown): unknown {
 	if(typeof value !== 'object' || !value || !('result' in value)) {
 		return undefined

package/src/old/to-register.ts

@@ -39,7 +39,8 @@ export interface OldProviderOpts {
 	/** Page-injection script — the devtools name for the builder's
 	 *  `webSettings.jsUserScripts`. Top-level on register, nested under
 	 *  `providerConfig` on config (add-version). The backend rejects a few
-	 *  deprecated injection APIs (e.g. `window.payloadData`) with a 400. */
+	 *  deprecated injection APIs (for example, `window.payloadData`) with a
+	 *  400. */
 	customInjection?: string
 	/** Accepted at register too (unlike the four fields below, which the
 	 *  backend only accepts on config/add-version). */
@@ -355,7 +356,7 @@ export interface SemverTriplet {
 /**
  * Pull `{major,minor,patch}` triplets out of a `/versions` response, tolerant
  * of the exact envelope (array, `{ providerVersions: [...] }`, `{ items }`,
- * etc.). Each entry's `version` is the triplet.
+ *, and so on). Each entry's `version` is the triplet.
  */
 export function extractVersions(resp: unknown): SemverTriplet[] {
 	const list = pickArray(resp)

package/src/old/tools/authenticate.ts

@@ -46,6 +46,11 @@ export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
 				'and closes the tab. A previously stored identity that is still ' +
 				'valid is reused first (pass `useBrowser: true` to force a fresh ' +
 				'login). \n\n' +
+				'EXPECT THIS TO TAKE A WHILE ON A FIRST RUN: a fresh Chrome ' +
+				'profile downloads the dashboard cold, so tell the developer it is ' +
+				'loading and that the window is waiting for them — do not re-run ' +
+				'the tool while it is still waiting. It polls for up to 6 minutes ' +
+				'and reports whether the page ever became interactive.\n\n' +
 				'Manual overrides:\n' +
 				'- `token`: paste a Firebase ID token (skips the browser).\n' +
 				'- `ethAddress`: an `eth:0x…` / `0x…` uid for an already-provisioned ' +
@@ -73,7 +78,10 @@ export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
 					timeoutMs: {
 						type: 'number',
 						description:
-							'How long to wait for sign-in, in ms (default 180000).',
+							'How long to wait for sign-in, in ms (default 360000, i.e. 6 '
+							+ 'minutes). A fresh Chrome profile loads the dashboard cold, '
+							+ 'which can take tens of seconds before the form is usable — '
+							+ 'that time comes out of this budget.',
 					},
 					useBrowser: {
 						type: 'boolean',

package/src/old/tools/get-provider-info.ts

@@ -3,8 +3,8 @@ import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
 import type { ReclaimSdkClient } from '../sdk-client.ts'
 
 /** Best-effort call: resolve to the response, or to an error string instead
- *  of throwing — one endpoint 404ing (e.g. a bad `versionNumber`) shouldn't
- *  hide a result the other endpoint DID have. */
+ *  of throwing — one endpoint 404ing (for example, a bad `versionNumber`)
+ *  shouldn't hide a result the other endpoint DID have. */
 async function attempt(
 	label: string,
 	call: () => Promise<unknown>,
@@ -51,8 +51,9 @@ export function getProviderInfoTool(client: ReclaimSdkClient): RegisteredTool {
 				'computed `isScriptRequestingClaim` flag). Read `provider` here ' +
 				'BEFORE create_provider_version_from_capture so you can pass the ' +
 				'whole existing config back — that tool always creates a new ' +
-				'version and carries nothing forward. One endpoint failing (e.g. ' +
-				'an invalid `versionNumber`) is reported under `errors` without ' +
+				'version and carries nothing forward. One endpoint failing (for ' +
+				'example, an invalid `versionNumber`) is reported under `errors` ' +
+				'without ' +
 				'hiding a result the other endpoint did return.',
 			inputSchema: {
 				type: 'object',
@@ -64,7 +65,7 @@ export function getProviderInfoTool(client: ReclaimSdkClient): RegisteredTool {
 					versionNumber: {
 						type: 'string',
 						description:
-							'Specific version, e.g. "1.0.2". Omit for the ' +
+							'Specific version, for example, "1.0.2". Omit for the ' +
 							"provider's current latest version.",
 					},
 				},

package/src/old/tools/issue-app-credentials.ts

@@ -24,8 +24,9 @@ export function issueAppCredentialsTool(
 				'starts UNLINKED and sandboxed (100 sessions) — call ' +
 				'link_app_to_account to attach it to your dashboard account and ' +
 				'check_app_status to check its state. Store `appSecret` like a ' +
-				'password (e.g. in a gitignored .env as RECLAIM_APP_SECRET) — it ' +
-				'is returned once and cannot be recovered from the server.',
+				'password (for example, in a gitignored .env as ' +
+				'RECLAIM_APP_SECRET) — it is returned once and cannot be ' +
+				'recovered from the server.',
 			inputSchema: { type: 'object', properties: {} },
 		},
 		async() => {

package/src/old/tools/publish.ts

@@ -1,7 +1,10 @@
 import { Boom, isBoom } from '@hapi/boom'
 import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
 import type { AttachState } from '../../mcp/tools/agent/attach.ts'
-import { INJECTION_GUIDE } from '../../provider/injection-doc.ts'
+import {
+	ALLOWED_REQUESTS_HINT,
+	USER_SCRIPT_HINT,
+} from '../../provider/injection-doc.ts'
 import {
 	countsFor,
 	matchRedactionWarnings,
@@ -35,8 +38,8 @@ function extractProviderId(resp: unknown): string | undefined {
  * `providerId` for a public provider (or anyone else's) comes back as
  * 401/403/404 — the dev's likely intent is to publish their OWN version of that
  * site, which on this backend means registering a separate copy. Rethrow those
- * failures with that actionable suggestion; leave other errors (e.g. a 400
- * version collision) untouched so their real detail surfaces.
+ * failures with that actionable suggestion; leave other errors (for example, a
+ * 400 version collision) untouched so their real detail surfaces.
  */
 function rethrowOwnershipError(err: unknown, providerId: string): never {
 	const status = isBoom(err) ? err.output.statusCode : undefined
@@ -62,7 +65,7 @@ function rethrowOwnershipError(err: unknown, providerId: string): never {
 /**
  * Publish a drafted provider to the OLD devtools backend. Keeps the builder
  * tool NAME (`create_provider_version_from_capture`) so the skill flow is
- * unchanged, but the behaviour differs:
+ * unchanged, but the behavior differs:
  *
  *   - WITHOUT `providerId` → `POST /api/providers/register`: creates a
  *     brand-new provider + version 1.0.0. Re-running creates a DUPLICATE.
@@ -100,67 +103,43 @@ export function createVersionFromCaptureTool(
 		useIncognitoWebview?: boolean
 		extensionConfig?: unknown
 		injectionType?: 'NONE' | 'MSWJS' | 'XHOOK' | 'CDP' | 'HAWKEYE'
+		disableRequestReplay?: boolean
 	}>(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Publish drafted ReclaimProvider(s) to the devtools backend. ' +
-				'Requires its OWN old-devtools login via reclaim_authenticate — ' +
-				'separate from authenticate_builder/Builder auth, which does not ' +
-				'authorize this call. Check status with get_devtools_mode. \n\n' +
-				'Pass the `provider` object from propose_provider VERBATIM and the ' +
-				'`initialUrl` the user landed on (the login/landing page, NOT the ' +
-				'API url). \n\n' +
-				'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
-				'proven draft from propose_provider) — every entry becomes one ' +
-				'`requestData` entry on the SAME version, and all are verified ' +
-				'together. Pass a single `provider` for the one-request case ' +
-				'(provide exactly one of `provider` / `providers`). \n\n' +
-				'Omit `providerId` to REGISTER A NEW provider (creates it + version ' +
-				'1.0.0; re-running creates a duplicate). Pass `providerId` (from ' +
-				'get_me_providers) to add a NEW VERSION to that existing provider ' +
-				'(the patch is auto-bumped). \n\n' +
-				'You can only add versions to a provider YOU own — the `providerId` ' +
-				'must come from get_me_providers. To publish your own version of a ' +
-				"PUBLIC provider you don't own, omit `providerId` to register your " +
-				'own copy (you cannot edit someone else\'s provider here). \n\n' +
-				'For data gated behind login/navigation, pass `customInjection` — a ' +
-				'USER SCRIPT (same concept as the builder\'s `jsUserScripts` — ' +
-				'devtools just calls the field `customInjection`) that drives the ' +
-				'page to where the request fires. \n\n' +
-				'BY DESIGN, this backend only ever CREATES A NEW VERSION (POST) — ' +
-				'there is no partial-patch/edit endpoint, and this tool does NOT ' +
-				'read or carry anything forward from the previous version. Every ' +
-				'new version replaces the WHOLE providerConfig with exactly what ' +
-				'you pass in THIS call. Therefore any field you want present in the ' +
-				'new version MUST be supplied here — `customInjection`, `userAgent`, ' +
-				'`pageTitle`, `allowedInjectedRequestData`, `stepsToFollow`, ' +
-				'`useIncognitoWebview`, `extensionConfig`, and `requestData` (via ' +
-				'`provider`/`providers`). Anything you OMIT is published blank/' +
-				'default in the new version, NOT preserved. To change one field ' +
-				'while keeping the rest, first read the current version with ' +
-				'get_provider_info, then pass the full desired config (the existing ' +
-				'values plus your change) back into this call. ' +
-				'`allowedInjectedRequestData`/`useIncognitoWebview`/' +
-				'`extensionConfig` only take effect on add-version — the register ' +
-				'endpoint (no `providerId`) ignores them, so on a fresh register ' +
-				'this tool automatically follows up with an add-version call that ' +
-				'applies them (also where document replay gets force-disabled — ' +
-				'see below). Per-request fields you may set on ' +
-				'`provider`/`providers`: `credentials` (omit/same-origin/include, ' +
-				'default include), `urlType` (REGEX/CONSTANT/TEMPLATE, default ' +
-				'derived from {{placeholders}}), and `isOptional` on each ' +
-				'responseMatch (default false). \n\n' +
-				'Captured requests must be GET/POST. OPRF redactions are supported. ' +
-					'Document replay — the HAWKEYE-level flag controlling whether the ' +
-					'page\'s own document/navigation request gets genuinely re-sent ' +
-					'through the interceptor at verification time — is ALWAYS ' +
-					'published disabled (`disableRequestReplay: true`); there is no ' +
-					'way to enable it here. ' +
-					'On success, if a browser is still attached, the response\'s ' +
-					'`_notes` reminds you to confirm with the developer before ' +
-					'calling `dispose_browser` — never close it unprompted, they ' +
-					'may want it for further edits.',
+				'Publish drafted ReclaimProvider(s) to the devtools backend. Needs '
+				+ 'its OWN reclaim_authenticate login — authenticate_builder does NOT '
+				+ 'authorize this call. Pass the `provider` object(s) from '
+				+ 'propose_provider VERBATIM, plus the `initialUrl` the user landed '
+				+ 'on (the login/landing page, NOT the API url). Exactly one of '
+				+ '`provider` (one request) or `providers` (a multi-request '
+				+ 'provider — every entry becomes a parallel requestData entry, all '
+				+ 'verified together). Captured requests must be GET/POST; OPRF '
+				+ 'redactions are supported.\n\n'
+				+ 'Omit `providerId` to REGISTER A NEW provider (creates it + '
+				+ 'version 1.0.0 — re-running creates a DUPLICATE). Pass '
+				+ '`providerId` (from get_me_providers) to add a NEW VERSION to it; '
+				+ 'the patch auto-bumps. You can only version a provider YOU own — '
+				+ 'to publish your own take on one you don\'t own, omit '
+				+ '`providerId` to register your own copy.\n\n'
+				+ 'THIS BACKEND ONLY EVER CREATES A NEW VERSION — there is no '
+				+ 'partial-patch endpoint, and this tool carries NOTHING forward '
+				+ 'from the previous version: every version replaces the WHOLE '
+				+ 'providerConfig with exactly what you pass in THIS call. Any '
+				+ 'field you want to survive must be re-supplied here '
+				+ '(`customInjection`, `userAgent`, `pageTitle`, '
+				+ '`allowedInjectedRequestData`, `stepsToFollow`, '
+				+ '`useIncognitoWebview`, `extensionConfig`, `requestData`); '
+				+ 'anything omitted is published blank. To change one field, read '
+				+ 'the current config with get_provider_info first and pass it back '
+				+ 'with your edit. `allowedInjectedRequestData`/'
+				+ '`useIncognitoWebview`/`extensionConfig` apply on add-version '
+				+ 'only, so a fresh register auto-follows with an add-version call '
+				+ 'that applies them (and disables document replay — see '
+				+ '`disableRequestReplay`).\n\n'
+				+ 'Always read the response\'s `_notes`. '
+				+ 'Full walkthrough: how_it_works({ topic: "publish" }).',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -272,15 +251,11 @@ export function createVersionFromCaptureTool(
 					customInjection: {
 						type: 'string',
 						description:
-							'Plain JavaScript injected into the provider page before every ' +
-							'page load — old-devtools\' name for what the builder calls ' +
-							'`webSettings.jsUserScripts`. Use standard browser APIs ' +
-							'(window.location, element.click(), forms) to drive login/' +
-							'navigation so the target request fires — window.Reclaim is ' +
-							'only for rare edge cases, not navigation. The backend rejects ' +
-							'a few deprecated injection APIs (e.g. window.payloadData, ' +
-							'window.ReclaimInjected) with a 400. Guide:\n\n' +
-							INJECTION_GUIDE,
+							USER_SCRIPT_HINT
+							+ ' Old-devtools\' name for what the builder calls '
+							+ 'webSettings.jsUserScripts. The backend rejects a few '
+							+ 'deprecated injection APIs (window.payloadData, '
+							+ 'window.ReclaimInjected) with a 400.',
 					},
 					userAgent: {
 						type: 'object',
@@ -299,39 +274,15 @@ export function createVersionFromCaptureTool(
 					allowedInjectedRequestData: {
 						type: 'array',
 						description:
-							'Extra requests the customInjection script is allowed to ' +
-							'fire (e.g. pagination) — add-version ONLY, the register ' +
-							'endpoint ignores this. Each item has the same shape as ' +
-							'`provider`, plus `multiple`/`required` (default true). ' +
-							'IMPORTANT whenever a claim\'s request HAS a body: set `body` ' +
-							'here (see its own description below) — if only a small part ' +
-							'of the real body varies per user/run (e.g. one id field, not ' +
-							'the whole payload), template just that part with ' +
-							'`{{paramName}}` and keep the rest as fixed literal text; see ' +
-							'the "bodySniff" section of the customInjection field\'s guide ' +
-							'for the exact mechanics and a worked example. ' +
-							'⚠️ BEFORE populating this to gate ' +
-							'`verifyProof(proof, { providerId })`: this whole entry (url, ' +
-							'method, body, responseMatches, responseRedactions) feeds a ' +
-							'client-side hash-equality check, and `url` is hashed VERBATIM ' +
-							'— no regex/template resolution, even with `urlType: REGEX` or ' +
-							'`TEMPLATE`. If the real captured URL contains ANY per-session ' +
-							'part (a tracking nonce, CSRF token, cache-busting timestamp), ' +
-							'no declared spec can EVER hash-match a real proof, no matter ' +
-							'how correct the rest of this entry is — populating' +
-							'it for such ' +
-							'a provider makes verifyProof reject every real proof,' +
-							'which is ' +
-							'worse than leaving this field empty. Diff the same endpoint\'s' +
-							' captured URL across two separate sessions before wiring this ' +
-							'up. If provider-hash validation keeps causing problems ' +
-							'(unstable url, or any other persistent mismatch), the ' +
-							'fallback on the verifying side is `verifyProof(proof, { ' +
-							'dangerouslyDisableContentValidation: true })` — trusts only ' +
-							'the attestor\'s signature, skips the hash-equality check ' +
-							'entirely; see the "Provider-hash validation" section of the ' +
-							'customInjection field\'s guide for the full mechanics and ' +
-							'when to reach for it.',
+							'Extra requests the customInjection user script is allowed to '
+							+ 'fire (for example, pagination) — add-version ONLY, the '
+							+ 'register '
+							+ 'endpoint ignores it. Each item has the same shape as '
+							+ '`provider`, plus `multiple`/`required` (default true). Set '
+							+ '`body` whenever the request has one (see its own description '
+							+ 'below). The builder calls the same concept '
+							+ '`allowedJsRequests`. '
+							+ ALLOWED_REQUESTS_HINT,
 						items: {
 							type: 'object',
 							properties: {
@@ -353,7 +304,8 @@ export function createVersionFromCaptureTool(
 										'body at all (skip only for a genuinely bodyless ' +
 										'request, typically GET). If the real body is FIXED ' +
 										'(identical for every user/run), put that literal body ' +
-										'text here verbatim. If only PART of it varies (e.g. ' +
+										'text here verbatim. If only PART of it varies (for ' +
+										'example, ' +
 										'`{"request":1,"type":"user_info","id":"12345"}` where ' +
 										'only `id` differs per user), template ONLY that part: ' +
 										'`{"request":1,"type":"user_info",' +
@@ -376,7 +328,7 @@ export function createVersionFromCaptureTool(
 										'reproduces the real captured request body ' +
 										'byte-for-byte. Fallback if per-field templating keeps ' +
 										'mismatching (more fields vary than expected, unstable ' +
-										'key order, etc.) and you can\'t pin down every ' +
+										'key order, and so on) and you can\'t pin down every ' +
 										'variable field: template the WHOLE body as one ' +
 										'placeholder instead, `{{REQ_BODY_GRD}}` — the `GRD` ' +
 										'suffix makes it a greedy match (captures everything) ' +
@@ -394,7 +346,7 @@ export function createVersionFromCaptureTool(
 										'`value` must literally appear (or match, if `regex`) ' +
 										'somewhere in the response body for the claim to be ' +
 										'accepted; it commonly embeds one or more ' +
-										'`{{paramName}}` extraction placeholders (e.g. ' +
+										'`{{paramName}}` extraction placeholders (for example, ' +
 										'`"name":"{{name_0}}"`) whose real value is redacted ' +
 										'out and supplied separately as a witness/extracted ' +
 										'param. Use `${var}` (not `{{var}}`) inside this string ' +
@@ -410,7 +362,8 @@ export function createVersionFromCaptureTool(
 										'Each item: `{ jsonPath?: string, xPath?: string, ' +
 										'regex?: string, hash?: string }`. Identifies WHICH ' +
 										'part of the response the matching `{{paramName}}` in ' +
-										'`responseMatches` actually redacts/extracts — e.g. ' +
+										'`responseMatches` actually redacts or extracts — for ' +
+										'example, ' +
 										'`jsonPath: "$.data.items[0].name"` for a JSON response. ' +
 										'Order/count should line up with `responseMatches`\' ' +
 										'placeholders one-to-one for a typical claim.',
@@ -475,17 +428,28 @@ export function createVersionFromCaptureTool(
 							'unset — the devtools backend\'s own column default ' +
 							'(`HAWKEYE`) applies, which is inert and harmless for the ' +
 							'standard capture→replay flow with no interceptor script ' +
-							'installed. Only set this to `HAWKEYE`/`MSWJS`/`XHOOK` ' +
-							'when you are ALSO supplying a `customInjection` script ' +
-							'that calls ' +
+							'installed. Only set `HAWKEYE`/`MSWJS`/`XHOOK` when you are ' +
+							'ALSO supplying a `customInjection` script that calls ' +
 							'`window.reclaimInterceptor.addResponseMiddleware(...)` for ' +
-							'genuine live interception, or set `NONE` explicitly if you ' +
-							'want to be certain no interception is configured — see ' +
-							'injection-api.md\'s "Recognizing this on a provider you ' +
-							'didn\'t author" section for what these values actually do. ' +
-							'Builder calls the equivalent concept `interceptorType` (no ' +
-							'`NONE` there — omitting the whole `interceptorOptions` ' +
-							'object is its no-interception signal instead).',
+							'genuine live interception, or set `NONE` explicitly to be ' +
+							'certain none is configured. Builder calls the equivalent ' +
+							'concept `interceptorType` (no `NONE` there — omitting the ' +
+							'whole `interceptorOptions` object is its no-interception ' +
+							'signal instead). What each value actually does: ' +
+							'how_it_works({ topic: "interception" }).',
+					},
+					disableRequestReplay: {
+						type: 'boolean',
+						description:
+							'Whether the page\'s own document/navigation request is ' +
+							'skipped (constructed locally) instead of genuinely replayed ' +
+							'through the interceptor. Defaults to `true` (disabled) when ' +
+							'omitted. Only meaningful for `injectionType` ' +
+							'HAWKEYE/MSWJS/XHOOK — pass `false` to enable real document ' +
+							'replay for those (for example, the target value is embedded ' +
+							'in the page\'s own HTML). Inert when `injectionType` is ' +
+							'`CDP` or ' +
+							'unset.',
 					},
 				},
 				required: ['initialUrl'],
@@ -529,9 +493,9 @@ export function createVersionFromCaptureTool(
 				// column default applies when omitted, same as before this field
 				// existed at all.
 				injectionType: args.injectionType,
-				// Always disabled — see the tool description above; there is no
-				// author-facing way to enable document replay.
-				disableRequestReplay: true,
+				// Author-settable; defaults to disabled (see tool description).
+				// Only meaningful for HAWKEYE/MSWJS/XHOOK — inert for CDP.
+				disableRequestReplay: args.disableRequestReplay ?? true,
 				allowedInjectedRequestData: args.allowedInjectedRequestData
 					? injectedRequestDataFrom(
 						args.allowedInjectedRequestData,
@@ -584,12 +548,12 @@ export function createVersionFromCaptureTool(
 					)
 				}
 
-				// disableRequestReplay is honored ONLY on add-version, and it's now
-				// always forced true — so every register is immediately followed by
-				// an add-version call that actually applies it (which also lands
-				// an explicit injectionType, when passed — unverified whether
-				// register persists it — and any other register-ignored fields the
-				// caller passed).
+				// disableRequestReplay is honored ONLY on add-version — so every
+				// register is immediately followed by an add-version call that
+				// actually applies it (whatever value — default or author-set;
+				// which also lands an explicit injectionType, when passed —
+				// unverified whether register persists it — and any other
+				// register-ignored fields the caller passed).
 				const REGISTER_IGNORED_KEYS = [
 					'allowedInjectedRequestData',
 					'useIncognitoWebview',
@@ -603,8 +567,8 @@ export function createVersionFromCaptureTool(
 						`${ignoredOnRegister.length > 1 ? 'are' : 'is'} ` +
 						'ignored on register (no providerId) — the devtools backend only ' +
 						'reads them when adding a version. They were applied by the ' +
-						'automatic follow-up version this tool always creates to ' +
-						'force-disable document replay.',
+						'automatic follow-up version this tool always creates to apply ' +
+						'disableRequestReplay.',
 					)
 				}
 
@@ -633,7 +597,7 @@ export function createVersionFromCaptureTool(
 						await client.updateProviderConfig(newProviderId, configBody)
 						notes.push(
 							`Created an automatic follow-up version (${followVersion}) to ` +
-							'force-disable document replay (disableRequestReplay)' +
+							`apply disableRequestReplay (${opts.disableRequestReplay})` +
 							(opts.injectionType !== undefined
 								? ` and set injectionType (${opts.injectionType})`
 								: '') +
@@ -657,7 +621,7 @@ export function createVersionFromCaptureTool(
 					}
 				} else {
 					notes.push(
-						'Could not force-disable document replay: the ' +
+						'Could not apply disableRequestReplay: the ' +
 						'register response did not include the new providerId. Call ' +
 						'this tool again WITH `providerId` to create a version that ' +
 						'applies them.',
@@ -668,7 +632,7 @@ export function createVersionFromCaptureTool(
 			}
 
 			// New version of an existing provider — pick the next patch above
-			// the highest existing version. A provider you don't own (e.g. a
+			// the highest existing version. A provider you don't own (for example, a
 			// public one) fails here with 401/403/404; surface the register-a-copy
 			// workaround instead of a bare permission error.
 			const providerId = args.providerId