@reclaimprotocol/agent 0.1.23 → 0.1.24

package/src/old/tools/update-provider-metadata.ts

@@ -8,7 +8,7 @@ import type { ReclaimOldClient, UpdateProviderMetadataBody } from '../client.ts'
  * `create_provider_version_from_capture` paths: it does NOT touch
  * `providerConfig`/versions at all, and only the fields you pass here
  * change — everything else on the provider is left untouched (no need to
- * re-supply `requestData`/`customInjection`/etc., and
+ * re-supply `requestData`/`customInjection`, and so on, and
  * no new version is created).
  *
  * The backend 403s if you don't own the provider (and aren't an admin) —

package/src/old/tools/verify-sdk-setup.ts

@@ -122,7 +122,7 @@ export function verifySdkSetupTool(client: ReclaimOldClient): RegisteredTool {
 					: 'PUBLIC_URL not set — fine if you only read the proof from the ' +
 						'frontend flow, but the async webhook callback needs a ' +
 						'publicly-reachable URL or it will never fire. Get one via a ' +
-						'tunnel (e.g. `ngrok http <port>`) or by deploying to a ' +
+						'tunnel (for example, `ngrok http <port>`) or by deploying to a ' +
 						'dev/staging server you already have — ask the user which they ' +
 						'prefer.',
 			})

package/src/proof/attestor.ts

@@ -53,13 +53,13 @@ export interface RunAttestorProofOptions {
 	/** When resolving the key from env/.env/file, the address the caller expects
 	 *  to sign with (sanity check). Ignored when `ownerPrivateKey` is given. */
 	ownerAddress?: string
-	/** Sign with this key directly (e.g. the app/VC's ephemeral per-session key)
-	 *  instead of resolving from env/.env/file. */
+	/** Sign with this key directly (for example, the app or VC's ephemeral
+	 *  per-session key) instead of resolving from env/.env/file. */
 	ownerPrivateKey?: string
 	/** ZK engine for `createClaimOnAttestor`. Defaults to `'stwo'` — a pure-WASM
 	 *  prover that runs everywhere (no native shared library, so it works on
 	 *  Windows where `'gnark'` fails to load its `.dll`). Server-side paths that
-	 *  want gnark's speed pin it explicitly (e.g. the verify runner). */
+	 *  want gnark's speed pin it explicitly (for example, the verify runner). */
 	zkEngine?: 'gnark' | 'snarkjs' | 'stwo'
 	/** Extract the structured {@link AttestorClaim} (claim + attestor signature)
 	 *  onto the result for nested-proof construction. */

package/src/proof/debug-response-dump.ts

@@ -1,10 +1,10 @@
 // Debug helper (gated by RECLAIM_AGENT_DUMP_RESPONSE): capture the EXACT
 // response bytes the attestor validates a claim against, plus a per-match
 // presence check. A "Response does not contain X" failure means the attestor's
-// server-side re-fetch differs from what the browser (replay) saw — e.g. GitHub
-// embeds nav/userMenu data for browser requests but not for the attestor's raw
-// fetch. Seeing the attestor's actual response is the only way to tell what it
-// really returned.
+// server-side re-fetch differs from what the browser (replay) saw — for
+// example, GitHub embeds nav/userMenu data for browser requests but not for the
+// attestor's raw fetch. Seeing the attestor's actual response is the only way
+// to tell what it really returned.
 //
 // On each getResponseRedactions call it writes the response to
 // `attestor-last-response.html` in the process CWD and logs the byte count +,

package/src/proof/index.ts

@@ -15,6 +15,14 @@ export {
 	parseClaim,
 	resolveAttestorUrl,
 } from './proof-core.ts'
+export {
+	type HttpParams,
+	type HttpSecretParams,
+	type PopcornProveOptions,
+	popcornProve,
+	popcornValidateExtraction,
+	type ValidateExtractionResult,
+} from './pod-prover.ts'
 export { ensureZkFiles } from './zk-files.ts'
 // Re-exported attestor-core claim primitive so the agent is the single
 // integration point with @reclaimprotocol/attestor-core across the builder.

package/src/proof/page-replay.ts

@@ -102,7 +102,7 @@ function authenticatedPageFetch(
  * (`authenticatedPageFetch`) so cookies are the real browser's, which a
  * detached call could never reproduce without manually re-deriving them.
  * WITH `withoutSecrets` (the auth-bound check — "does this still work with
- * no credentials, i.e. is it actually public"), replay instead through the
+ * no credentials, that is, is it actually public"), replay instead through the
  * detached Node-side `replayProvider`: the whole point of that check is to
  * prove NO secret rides along, and the live page's own global `fetch` can't
  * give that guarantee — a site (or a script installed via test_user_script)

package/src/proof/pod-prover.ts

@@ -0,0 +1,231 @@
+/**
+ * PopcornPodProver — run the zkTLS proof inside a Popcorn browser session's
+ * OWN TEE pod instead of the in-process attestor SDK (`runAttestorProof`).
+ * POSTs the recipe + captured secrets to the pod's `/reclaim/prove` (the same
+ * attestor TEE+MPC protocol) and re-shapes the response into the shared
+ * {@link ProofResult}, so every caller consumes proof results identically
+ * regardless of which path produced them.
+ *
+ * This is the pod's OWN api for creating a proof from a live session — used
+ * by both the app's server-driven verification runner and the MCP's
+ * `run_proof_via_pod` tool. Proving here (rather than locally) matters
+ * specifically when the session is country-routed: Popcorn allocated the
+ * browser with an exit country, and this is the SAME enclave holding that
+ * browser's TLS session, so the proof reaches the target from the identical
+ * exit IP the browser used — a local attestor SDK proof runs from the
+ * app/agent's OWN network instead.
+ *
+ * Contract (verified against ../popcorn-images oapi.go + ../reclaim-tee):
+ *   POST {apiUrl}/reclaim/prove  body { provider_params_json, config_json? }
+ *   provider_params_json = JSON of { name, params, secretParams, context? }
+ *   → 200 { session_id, claim, signature } (ReclaimProveResult, snake_case):
+ *     claim has provider/parameters/owner/timestamp_s/context/identifier/epoch;
+ *     signature has attestor_address + claim_signature(b64) +
+ *     result_signature(b64). A proof failure/timeout is a 500 whose `message`
+ *     carries the reason.
+ *
+ * The pod API is unauthenticated (gateway/session is the trust boundary); call
+ * it over the same internal host used for CDP. Consumers verify
+ * `claim_signature` only (see `@reclaimprotocol/client`'s `verifyNestedProof`),
+ * so this hands back a {@link AttestorClaim} whose hex `claimSignature` the
+ * shared `wrapProofAsJws` (app-side) turns into the nested result proof.
+ * `result_signature` is unused by any consumer.
+ */
+import { bytesToHex } from '@noble/hashes/utils.js'
+import type { ProviderParams } from '@reclaimprotocol/attestor-core'
+import type { AttestorClaim, ProofResult } from './attestor.ts'
+
+/** Attestor HTTP provider params — the recipe the agent synthesis produces. */
+export type HttpParams = ProviderParams<'http'>
+
+/** Captured secrets for the replay, exactly as `/reclaim/prove` wants them. */
+export interface HttpSecretParams {
+	cookieStr?: string
+	authorisationHeader?: string
+	headers?: Record<string, string>
+	paramValues?: Record<string, string>
+}
+
+/**
+ * The pod's `/reclaim/prove` 200 body (ReclaimProveResult, snake_case; fields
+ * optional because we validate). Note `timestamp_s` and the whole `signature`
+ * object are snake_case; matching them is exactly what fixes the false
+ * "no claim/signature".
+ */
+interface ReclaimProveResponse {
+	session_id?: string
+	claim?: {
+		provider?: string
+		parameters?: string
+		owner?: string
+		timestamp_s?: number
+		context?: string
+		identifier?: string
+		epoch?: number
+	}
+	signature?: {
+		attestor_address?: string
+		claim_signature?: string
+		result_signature?: string
+	}
+}
+
+export interface PopcornProveOptions {
+	/** Pod API base (the session's `apiUrl`). */
+	apiUrl: string
+	params: HttpParams
+	secretParams: HttpSecretParams
+	/** Session context, stringified into the claim context if given. */
+	context?: Record<string, unknown>
+	fetchImpl?: typeof fetch
+}
+
+export interface ValidateExtractionResult {
+	valid: boolean
+	extractedValue?: string
+	error?: string
+	steps?: string[]
+}
+
+/**
+ * The cloud "replay": validate that a drafted recipe's selectors extract the
+ * expected value from a captured response, inside the TEE — `POST {apiUrl}
+ * /reclaim/validate-extraction`. Reuses the prover's own redaction engine, so
+ * a pass means the selectors won't diverge at proof time. No proof/secrets.
+ */
+export async function popcornValidateExtraction(opts: {
+	apiUrl: string
+	responseBody: string
+	expectedValue: string
+	xPath?: string
+	jsonPath?: string
+	regex?: string
+	fetchImpl?: typeof fetch
+}): Promise<ValidateExtractionResult> {
+	const doFetch = opts.fetchImpl ?? fetch
+	const base = opts.apiUrl.replace(/\/$/, '')
+	try {
+		const res = await doFetch(`${base}/reclaim/validate-extraction`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				responseBody: opts.responseBody,
+				expectedValue: opts.expectedValue,
+				...(opts.xPath ? { xPath: opts.xPath } : {}),
+				...(opts.jsonPath ? { jsonPath: opts.jsonPath } : {}),
+				...(opts.regex ? { regex: opts.regex } : {}),
+			}),
+		})
+		if(!res.ok) {
+			const detail = await res.text().catch(() => '')
+			return { valid: false, error: `${res.status}: ${detail.slice(0, 300)}` }
+		}
+
+		const body = (await res.json()) as ValidateExtractionResult
+		return body
+	} catch(err) {
+		const error = err instanceof Error ? err.message : String(err)
+		return { valid: false, error }
+	}
+}
+
+/** Decode standard base64 (Go `base64.StdEncoding` from Popcorn) to bytes. */
+function b64ToBytes(b64: string): Uint8Array {
+	return new Uint8Array(Buffer.from(b64, 'base64'))
+}
+
+/**
+ * Prove a single request through the Popcorn TEE. Returns the shared
+ * {@link ProofResult}; on any failure `verified` is false and `error` carries
+ * the reason (never throws for an expected proof failure).
+ */
+export async function popcornProve(
+	opts: PopcornProveOptions,
+): Promise<ProofResult> {
+	const { apiUrl, params, secretParams, context } = opts
+	const doFetch = opts.fetchImpl ?? fetch
+	const base = apiUrl.replace(/\/$/, '')
+
+	const providerParamsJson = JSON.stringify({
+		name: 'http',
+		params,
+		secretParams,
+		...(context ? { context: JSON.stringify(context) } : {}),
+	})
+	const fail = (error: string): ProofResult => ({
+		proof: undefined,
+		extractedValue: '',
+		extractedParameters: {},
+		verified: false,
+		error,
+	})
+
+	let resp: ReclaimProveResponse
+	let raw = ''
+	try {
+		const res = await doFetch(`${base}/reclaim/prove`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ provider_params_json: providerParamsJson }),
+		})
+		// Read the body as text first: a proof failure/timeout is a 500 whose
+		// `message` we want to surface verbatim, and on an unexpected 200 shape we
+		// echo the raw body instead of a blind "no claim/signature".
+		raw = await res.text().catch(() => '')
+		if(!res.ok) {
+			return fail(`/reclaim/prove ${res.status}: ${raw.slice(0, 300)}`)
+		}
+
+		resp = JSON.parse(raw) as ReclaimProveResponse
+	} catch(err) {
+		return fail(err instanceof Error ? err.message : String(err))
+	}
+
+	const claim = resp.claim
+	const sig = resp.signature
+	if(!claim || !sig?.attestor_address || !sig?.claim_signature) {
+		return fail(
+			'popcorn /reclaim/prove returned no claim/signature: '
+			+ raw.slice(0, 300),
+		)
+	}
+
+	// claim.context is the JSON string carrying { extractedParameters, ... } —
+	// the same place the in-process path reads them from.
+	let extractedParameters: Record<string, string> = {}
+	if(typeof claim.context === 'string') {
+		try {
+			const ctx = JSON.parse(claim.context) as {
+				extractedParameters?: Record<string, string>
+			}
+			extractedParameters = ctx.extractedParameters ?? {}
+		} catch{
+			// leave empty if context isn't valid JSON
+		}
+	}
+
+	const attestorClaim: AttestorClaim = {
+		claim: {
+			provider: claim.provider ?? '',
+			parameters: claim.parameters ?? '',
+			owner: claim.owner ?? '',
+			timestampS: claim.timestamp_s ?? 0,
+			context: claim.context ?? '',
+			identifier: claim.identifier ?? '',
+			epoch: claim.epoch ?? 0,
+		},
+		attestorAddress: sig.attestor_address,
+		// Consumer-side verification expects hex; Popcorn signs in base64.
+		claimSignature: '0x' + bytesToHex(b64ToBytes(sig.claim_signature)),
+	}
+
+	return {
+		proof: resp,
+		verified: true,
+		extractedParameters,
+		extractedValue: Object.values(extractedParameters)[0] ?? '',
+		...(claim.identifier ? { identifier: claim.identifier } : {}),
+		...(claim.owner ? { owner: claim.owner } : {}),
+		attestorClaim,
+	}
+}

package/src/provider/dom-xpath.ts

@@ -183,9 +183,10 @@ export function elementAnchor(
 /** The tightest element that DIRECTLY holds a target. Prefers a COMPLETE-value
  *  occurrence — an attribute whose value IS the target, or a text child that IS
  *  the target — over one where the target is merely embedded in a longer string
- *  (e.g. a userid inside a `1234567+user@…` noreply address). The complete
- *  field is the semantic source and yields a portable anchor; the embedded one
- *  is incidental. Smallest byte span wins within the chosen tier. */
+ *  (for example, a userid inside a `1234567+user@…` noreply address). The
+ *  complete field is the semantic source and yields a portable anchor; the
+ *  embedded one is incidental. Smallest byte span wins within the chosen
+ *  tier. */
 function findElement(root: Node, targets: string[]): Element | undefined {
 	const complete: Element[] = []
 	const embedded: Element[] = []
@@ -250,8 +251,8 @@ function* candidateXPaths(el: Element): Generator<Candidate> {
 
 	// A uniquely-identified DIRECT child pins the parent without a positional
 	// path (`//span[span[@id="labels"]]`). Self-verification discards it when the
-	// child id/attr isn't unique — e.g. GitHub reuses `id="labels"` per email row
-	// — so it never silently matches the wrong node.
+	// child id/attr isn't unique — for example, GitHub reuses `id="labels"` per
+	// email row — so it never silently matches the wrong node.
 	for(const child of el.children) {
 		if(!isTag(child)) {
 			continue
@@ -295,8 +296,9 @@ function distinctiveClass(cls: string | undefined): string | undefined {
 		.sort((x, y) => y.length - x.length)[0]
 }
 
-/** Positional path from `anc` (exclusive) down to `el` (inclusive), e.g.
- *  `/ul[1]/li[3]/a[1]`; empty string when `anc` is not an ancestor of `el`. */
+/** Positional path from `anc` (exclusive) down to `el` (inclusive), for
+ *  example `/ul[1]/li[3]/a[1]`. Empty string when `anc` is not an ancestor
+ *  of `el`. */
 function relativeSteps(anc: Element, el: Element): string {
 	const parts: string[] = []
 	let node: Node | null = el
@@ -392,8 +394,8 @@ function absolutePath(el: Element): string {
 
 /** True when `expression` selects EXACTLY `el` (one match) against `doc`. The
  *  attestor applies the redaction regex to EVERY xPath match and throws if any
- *  fails, so a non-unique selector (e.g. a class shared by sibling rows) is
- *  unusable — it must resolve to the single target element. */
+ *  fails, so a non-unique selector (for example, a class shared by sibling
+ *  rows) is unusable — it must resolve to the single target element. */
 function matchesUniquely(doc: unknown, expression: string, el: Node): boolean {
 	try {
 		const engine = xpath as unknown as {

package/src/provider/draft.ts

@@ -57,7 +57,8 @@ export interface DraftTarget {
 
 /** The realized extraction for one target — its value paired with the
  *  redaction that reveals it (absent when matched literally). Lets a consumer
- *  validate each value against its own selector (e.g. the cloud replay). */
+ *  validate each value against its own selector (for example, the cloud
+ *  replay). */
 export interface Extraction {
 	name: string
 	value: string
@@ -110,12 +111,14 @@ function sanitizeRequestHeaders(
  *  match or redaction — either a neighbouring target's value or a target's own
  *  value left un-templated. The matcher builds each target's window
  *  independently and drops the per-user WORDS it can see, but it cannot know a
- *  neighbouring value is itself user-specific (e.g. a name sharing a text node
- *  with an id — a `<b>{{id}}</b>` sitting beside a `<td>{{name}}</td>`).
- *  Cross-checking every value against every match here catches that: a portable
- *  provider contains NO captured value as a literal — each appears only as its
- *  `{{param}}`. Throwing discards the draft so the agent re-captures or
- *  re-proposes rather than shipping a provider pinned to this one user. */
+ *  neighbouring value is itself user-specific (for example, a name sharing a
+ *  text node with an id — a `<b>{{id}}</b>` sitting beside a
+ *  `<td>{{name}}</td>`). Cross-checking every value against every match here
+ *  catches
+ *  that: a portable provider contains NO captured value as a literal — each
+ *  appears only as its `{{param}}`. Throwing discards the draft so the agent
+ *  re-captures or re-proposes rather than shipping a provider pinned to this
+ *  one user. */
 export function assertPortableMatches(
 	matches: ResponseMatch[],
 	redactions: ResponseRedaction[],
@@ -294,7 +297,7 @@ function resolveParamName(targetName: string, shorten: boolean): string {
 				+ '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 '
+				+ 'lower_snake_case, for example, "employer_name"). Rename it, or drop '
 				+ '`shortenNames: false` to auto-derive a safe one.',
 			)
 		}
@@ -340,8 +343,8 @@ export function draftProvider(
 				+ `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 more distinct names, for example '
+						+ '"firstName"/"surname" instead of "first_name"/"last_name"'
 					: ' — give them distinct names, or drop `shortenNames: false` '
 						+ 'to auto-derive distinct ones'),
 			)

package/src/provider/injection-doc.ts

@@ -1,28 +1,41 @@
 /**
- * Guidance for authoring page-injection scripts (`webSettings.jsUserScripts` on
- * the builder, `customInjection` on old-devtools), surfaced to the authoring
- * model from the publish tool description. The prose lives in
- * `skill/injection-api.md` so it can be edited as markdown without touching
- * code — the same pattern as `mcp/instructions.ts`. The path resolves the same
- * from `src/provider` (dev) and `lib/provider` (published): both are two levels
- * below the package root.
+ * Short field hints for the user-script inputs on both publish tools
+ * (`webSettings.jsUserScripts` on the builder, `customInjection` on
+ * old-devtools).
  *
- * The guide leads with plain browser JavaScript (navigation/interaction via
- * standard APIs; the client already intercepts page requests) and treats
- * `window.Reclaim` as a rarely-needed edge-case bridge, pointing at the
- * authoritative `src/support/env.d.ts` rather than reproducing its surface.
- * It also covers the HAWKEYE-style live-interception path (`injectionType` /
- * `interceptorType`, `disableRequestReplay` / `isDocumentRequestReplayEnabled`)
- * and `bodySniff`, reverse-engineered from the old-devtools Prisma schema,
- * controller code, and dashboard field hints. The replay flag IS settable via
- * the publish tools (`disableRequestReplay` on old-devtools — add-version or
- * the register follow-up; `interceptorOptions` on the builder), so this is
- * recognition + authoring guidance for the remaining internals.
+ * These used to inline the whole `skill/injection-api.md` guide (~22 KB) into
+ * the tool's input schema. That guide is needed by a small minority of
+ * providers, but an input-schema description is sent to the model on EVERY
+ * request — it was roughly half the old-devtools tool surface on its own. The
+ * prose now lives in `skill/user-script.md`, `skill/interception.md` and
+ * `skill/hash-validation.md`, served on demand as `how_it_works` topics; what
+ * stays here is the pointer plus the one warning that must be seen BEFORE the
+ * field is filled in, since acting on it wrongly is worse than not acting.
+ *
+ * Shared by both publish tools so the two can't drift apart.
  */
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
 
-export const INJECTION_GUIDE = readFileSync(
-	fileURLToPath(new URL('../../skill/injection-api.md', import.meta.url)),
-	'utf8',
-).trim()
+/** What the script is and where the real guidance lives. */
+export const USER_SCRIPT_HINT =
+	'Plain JavaScript injected into the provider page before every page load. '
+	+ 'Use standard browser APIs (window.location, element.click(), forms) to '
+	+ 'drive login/navigation so the target request fires — the client already '
+	+ 'intercepts page requests, and window.Reclaim is only for rare edge cases, '
+	+ 'not navigation. Full guide: how_it_works({ topic: "user-script" }).'
+
+/** Prefixes the `allowedJsRequests` / `allowedInjectedRequestData` field. The
+ *  trap it describes is silent and total — a mis-declared entry makes
+ *  `verifyProof({ providerId })` reject EVERY real proof — so the warning
+ *  itself stays in the schema even though its explanation moved to a topic. */
+export const ALLOWED_REQUESTS_HINT =
+	'⚠️ Only populate this if you intend to gate '
+	+ '`verifyProof(proof, { providerId })`: each entry feeds a client-side '
+	+ 'hash-equality check and its `url` is hashed VERBATIM (no regex/template '
+	+ 'resolution, even with urlType REGEX/TEMPLATE). If the real captured URL '
+	+ 'carries ANY per-session part (nonce, CSRF token, cache-busting '
+	+ 'timestamp), no declared spec can ever hash-match a real proof — '
+	+ 'populating it then makes verifyProof reject every real proof, which is '
+	+ 'worse than leaving it empty. Diff the same endpoint\'s captured URL '
+	+ 'across two sessions first. Mechanics, the body-templating rules and the '
+	+ 'dangerouslyDisableContentValidation fallback: '
+	+ 'how_it_works({ topic: "hash-validation" }).'

package/src/provider/match-redaction-warning.ts

@@ -6,8 +6,8 @@
  * index and may not behave correctly when there are fewer matches than
  * redactions. This is NOT enforced — the author keeps full control over what
  * they publish in either old-devtools or builder mode. The tools surface these
- * strings so the dev can make an informed decision (e.g. add a functional match
- * per redaction) rather than being blocked.
+ * strings so the dev can make an informed decision (for example, add a
+ * functional match per redaction) rather than being blocked.
  */
 
 /** One request's match/redaction counts, with a human label for the message. */
@@ -26,7 +26,7 @@ export function matchRedactionWarnings(requests: RequestCounts[]): string[] {
 			warnings.push(
 				`${req.label}: ${req.matchCount} response match(es) but ` +
 				`${req.redactionCount} response redaction(s). Some verification ` +
-				'clients (e.g. the InApp SDK) may not work correctly when ' +
+				'clients (for example, the InApp SDK) may not work correctly when ' +
 				'responseMatches is shorter than responseRedactions — they pair the ' +
 				'two by index. This is allowed; add a functional match per redaction ' +
 				'if you hit verification issues.',

package/src/provider/matcher.ts

@@ -54,7 +54,7 @@ export function synthesizeMatcher(
 			'OPRF hashing requires a target with a known-safe character class '
 			+ '(digits, slug, or email). '
 			+ `Got "${target}" which is free-form. Use a tighter target `
-			+ '(e.g. just the alphanumeric portion of the value) '
+			+ '(for example, just the alphanumeric portion of the value) '
 			+ 'or call propose_provider without `hash`.',
 		)
 	}
@@ -196,10 +196,10 @@ function lastPathKey(jsonPath: string | undefined): string | undefined {
  * 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).
+ * value) — so a short/common value elsewhere in the body (for example, 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 (for example, `findJsonPath` returned an array-index leaf).
  */
 function jsonKeyPrefix(
 	text: string,
@@ -497,9 +497,9 @@ function portableWindow(
 /** Value is element text content. Left anchor: if only punctuation/whitespace
  *  sits between the opening tag and the value, fold the stable opening tag in;
  *  but if WORDS precede the value in the same text node they may be per-user
- *  (e.g. `<li>Full Name ( {{id}} )` — the name), so drop through the last
- *  alphanumeric and keep only the trailing punctuation as the anchor. Right:
- *  include a closing tag, but stop at a sibling. */
+ *  (for example, `<li>Full Name ( {{id}} )` — the name), so drop through the
+ *  last alphanumeric and keep only the trailing punctuation as the anchor.
+ *  Right: include a closing tag, but stop at a sibling. */
 function textWindow(
 	markup: string,
 	valueIdx: number,
@@ -671,9 +671,9 @@ function contentMatcher(
  * 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. */
+ * that is, 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: string,
 	cand: string,
@@ -859,7 +859,8 @@ function inferValueClass(target: string): string | undefined {
 		return '\\d+'
 	}
 
-	// Numbers with thousands separators / decimals, e.g. "1,908" or "12,345.6".
+	// Numbers with thousands separators / decimals, for example, "1,908" or
+	// "12,345.6".
 	if(/^[0-9][0-9,.]*[0-9]$/.test(target)) {
 		return '[0-9,.]+'
 	}

package/src/provider/secrets.ts

@@ -126,9 +126,9 @@ export function secretUrlCharBudget(
 }
 
 /** A `paramValues`/context key is secret iff its name contains `SECRET`
- *  (case-insensitive) — e.g. `SECRET_apiKey`, `context.SECRET_apiKey`. Same
- *  naming-convention classifier reclaim-inapp-sdk and reclaim-portal use for
- *  their `witnessParams`/`paramValues` maps (no separate boolean flag). */
+ *  (case-insensitive) — for example, `SECRET_apiKey`, `context.SECRET_apiKey`.
+ *  Same naming-convention classifier reclaim-inapp-sdk and reclaim-portal use
+ *  for their `witnessParams`/`paramValues` maps (no separate boolean flag). */
 export function classifyParamName(name: string): boolean {
 	return name.toUpperCase().includes('SECRET')
 }

package/src/provider/to-version.ts

@@ -41,14 +41,14 @@ export interface DraftRequest {
  *  pagination/optionality flags of `RequestSelectionTemplate`. Reuses the
  *  shared `DraftRequest` shape — no provider `name`/`paramValues` required. */
 export interface AllowedJsRequest extends DraftRequest {
-	/** Allow the template to match many requests (e.g. pagination). Default
-	 *  true. */
+	/** Allow the template to match many requests (for example, pagination).
+	 *  Default true. */
 	multiple?: boolean
 	/** Fail validation if no request matches this template. Default true. */
 	required?: boolean
 	/** Names of `${var}` placeholders in this template's `responseMatches`/
 	 *  `responseRedactions` that get substituted at verify time from the
-	 *  submitted proof's own witness params (e.g. an index list a
+	 *  submitted proof's own witness params (for example, an index list a
 	 *  `Reclaim.requestClaim` call attached alongside its `{{var}}`
 	 *  extractions). Omit (or leave empty) when the template has no such
 	 *  placeholders — verification then matches it literally as-is. */
@@ -74,12 +74,13 @@ export interface CreateVersionOptions {
 	 *  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. */
+	 *  `isDocumentRequestReplayEnabled` defaults to `false` (disabled) unless
+	 *  explicitly overridden here — see `providerToCreateVersionRequest`. Only
+	 *  meaningful for `HAWKEYE`/`MSWJS`; inert for `CDP`. */
 	interceptorOptions?: {
 		interceptorType: 'HAWKEYE' | 'MSWJS' | 'CDP'
 		interceptorSettings?: string
+		isDocumentRequestReplayEnabled?: boolean
 	}
 }
 
@@ -249,14 +250,15 @@ export function providerToCreateVersionRequest(
 				// 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.
+				// defaults to disabled but is author-overridable — see
+				// `CreateVersionOptions.interceptorOptions`'s doc comment.
 				...(interceptorOptions
 					? {
 						inapp: {
 							interceptorOptions: {
 								interceptorType: interceptorOptions.interceptorType,
-								isDocumentRequestReplayEnabled: false,
+								isDocumentRequestReplayEnabled:
+									interceptorOptions.isDocumentRequestReplayEnabled ?? false,
 								...(interceptorOptions.interceptorSettings
 									? {
 										interceptorSettings:

package/src/tools/registry.ts

@@ -70,11 +70,11 @@ export function errorAsToolText(err: unknown): string {
 /**
  * Adapt a tool to a host by WIDENING its input schema — add properties, mark
  * some required, optionally override the description — without touching the
- * handler. A host maps whichever shared tools it needs through this (e.g. the
- * MCP adds its `captureId` session handle + the credential-aware `run_proof`
- * contract). Args parse loosely, so the extra fields flow through to the
- * handler (its backend resolver reads them); the base tool stays untouched for
- * hosts that don't need them.
+ * handler. A host maps whichever shared tools it needs through this (for
+ * example, the MCP adds its `captureId` session handle + the credential-aware
+ * `run_proof` contract). Args parse loosely, so the extra fields flow through
+ * to the handler (its backend resolver reads them); the base tool stays
+ * untouched for hosts that don't need them.
  */
 export function extendTool(
 	tool: RegisteredTool,