@reclaimprotocol/agent 0.1.18 → 0.1.20

package/src/mcp/tools/agent/attach.ts

@@ -1,4 +1,11 @@
-import { type CdpHandles, connectCdp } from '../../../cdp/client.ts'
+import { badRequest } from '@hapi/boom'
+import type { ReclaimClient } from '@reclaimprotocol/client'
+import assert from 'node:assert'
+import {
+	type CdpHandles,
+	connectCdp,
+	connectCdpUrl,
+} from '../../../cdp/client.ts'
 import {
 	defaultProfileDir,
 	launchChrome,
@@ -8,88 +15,222 @@ import type { ConfigStore } from '../../../config/store.ts'
 import { defaultConfigPath } from '../../../config/store.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 
+export type BrowserMode = 'dedicated' | 'attach' | 'builder' | 'custom'
+
 export interface AttachState {
 	handles: CdpHandles
-	port: number
+	mode: BrowserMode
+	port?: number
+	liveViewUrl?: string
+	browserSessionId?: string
+	orgId?: string
+	disposeRemote?: () => Promise<void>
 }
 
-export function attachTool(state: {
+export interface AttachRef {
 	current?: AttachState
 	config: ConfigStore
-}): RegisteredTool {
-	return defineTool<{ attachMode?: 'dedicated' | 'attach', port?: number }>(
+}
+
+interface AttachArgs {
+	mode?: BrowserMode
+	/** Backward-compatible local-mode spelling. */
+	attachMode?: 'dedicated' | 'attach'
+	port?: number
+	orgId?: string
+	cdpUrl?: string
+	liveViewUrl?: string
+}
+
+interface AttachDependencies {
+	connectLocal: typeof connectCdp
+	connectRemote: typeof connectCdpUrl
+}
+
+const DEFAULT_DEPENDENCIES: AttachDependencies = {
+	connectLocal: connectCdp,
+	connectRemote: connectCdpUrl,
+}
+
+export function attachTool(
+	state: AttachRef,
+	builderClient?: ReclaimClient,
+	name: 'attach_browser' | 'attach_chrome' = 'attach_browser',
+	beforeReplace?: () => Promise<void>,
+	dependencies: AttachDependencies = DEFAULT_DEPENDENCIES,
+): RegisteredTool {
+	return defineTool<AttachArgs>(
 		{
-			name: 'attach_chrome',
+			name,
 			description:
-				'Attach to a Chrome instance via CDP. ' +
-				'Auto-launches a dedicated-profile Chrome ' +
-				'on first call if no attachMode is persisted. ' +
-				'Persists the chosen mode in ~/.reclaim/config.json.',
+				name === 'attach_chrome'
+					? 'Backward-compatible alias for attach_browser.'
+					: 'Connect the provider-authoring tools to a browser. Choose '
+						+ 'dedicated (launch local Chrome), attach (existing local CDP '
+						+ 'port), builder (quota-accounted Popcorn browser with a '
+						+ 'shareable live view), or custom (caller-supplied CDP '
+						+ 'websocket). '
+						+ 'Builder and custom CDP credentials are held in memory and never '
+						+ 'returned.',
 			inputSchema: {
 				type: 'object',
 				properties: {
-					attachMode: { type: 'string', enum: ['dedicated', 'attach'] },
-					port: { type: 'number' },
+					mode: {
+						type: 'string',
+						enum: ['dedicated', 'attach', 'builder', 'custom'],
+					},
+					attachMode: {
+						type: 'string',
+						enum: ['dedicated', 'attach'],
+						description: 'Deprecated local-mode alias for mode.',
+					},
+					port: { type: 'number', minimum: 1, maximum: 65535 },
+					orgId: { type: 'string', format: 'uuid' },
+					cdpUrl: { type: 'string', maxLength: 4000 },
+					liveViewUrl: { type: 'string', format: 'uri', maxLength: 4000 },
 				},
 			},
 		},
 		async(parsed) => {
-			let cfg = state.config.read()?.browser_agent
-			if(parsed.attachMode || parsed.port) {
-				cfg = {
-					attachMode: parsed.attachMode ?? cfg?.attachMode ?? 'dedicated',
-					port: parsed.port ?? cfg?.port ?? 9222,
-				}
-				state.config.write({ browser_agent: cfg })
-			}
-
-			if(!cfg) {
+			const persisted = state.config.read()?.browser_agent
+			const mode = parsed.mode ?? parsed.attachMode ?? persisted?.attachMode
+			if(!mode) {
 				return {
 					needsChoice: true,
 					message:
-						'First-run: choose attach mode. ' +
-						'Call attach_chrome again with attachMode="dedicated" ' +
-						'(auto-launch a Chrome profile under ~/.reclaim/chrome-profile) ' +
-						'or attachMode="attach" ' +
-						'(connect to a Chrome you launched yourself with ' +
-						'BOTH --remote-debugging-port=9222 AND ' +
-						'--user-data-dir=<some-non-default-path>; ' +
-						'since Chrome 136 the debug-port flag is silently ' +
-						'ignored if the default profile is in use).',
+						'Choose a browser mode and call attach_browser again: '
+						+ '"dedicated" launches a local dedicated Chrome profile; '
+						+ '"attach" connects to a local Chrome debugging port; '
+						+ '"builder" creates a quota-accounted remote browser and '
+						+ 'requires orgId; "custom" requires a CDP websocket URL.',
 					configPath: defaultConfigPath(),
 				}
 			}
 
-			if(cfg.attachMode === 'dedicated') {
-				try {
-					await waitForCdpReady(cfg.port, 500)
-				} catch{
-					launchChrome({ port: cfg.port, profileDir: defaultProfileDir() })
-					await waitForCdpReady(cfg.port, 10_000)
-				}
-			} else {
-				await waitForCdpReady(cfg.port, 2_000).catch(() => {
-					throw new Error(
-						`attach mode: nothing answering CDP on port ${cfg.port}. ` +
-						'Chrome must be launched with BOTH ' +
-						`--remote-debugging-port=${cfg.port} AND ` +
-						'--user-data-dir=<some-non-default-path>. ' +
-						'Since Chrome 136 (May 2025), the debug-port flag is ' +
-						'silently ignored when the default ' +
-						"user profile is in use — that's why nothing opens the port. " +
-						'Either re-launch Chrome with ' +
-						'a custom --user-data-dir, or switch to attachMode="dedicated".',
-					)
-				})
+			const next = await connect(
+				mode, parsed, persisted, builderClient, dependencies,
+			)
+			try {
+				await beforeReplace?.()
+				await disposeAttached(state)
+			} catch(err) {
+				await disposeState(next).catch(() => {})
+				throw err
 			}
 
-			if(state.current) {
-				await state.current.handles.close().catch(() => {})
+			state.current = next
+			if(mode === 'dedicated' || mode === 'attach') {
+				state.config.write({
+					browser_agent: { attachMode: mode, port: next.port! },
+				})
 			}
 
-			const handles = await connectCdp(cfg.port)
-			state.current = { handles, port: cfg.port }
-			return { attached: true, port: cfg.port, mode: cfg.attachMode }
+			return {
+				attached: true,
+				mode,
+				...(next.port ? { port: next.port } : {}),
+				...(next.browserSessionId
+					? { browserSessionId: next.browserSessionId }
+					: {}),
+				...(next.liveViewUrl ? { liveViewUrl: next.liveViewUrl } : {}),
+			}
 		},
 	)
 }
+
+export async function disposeAttached(state: AttachRef) {
+	const current = state.current
+	if(!current) {
+		return
+	}
+
+	delete state.current
+	await disposeState(current)
+}
+
+async function connect(
+	mode: BrowserMode,
+	parsed: AttachArgs,
+	persisted: { attachMode: 'dedicated' | 'attach', port: number } | undefined,
+	builderClient: ReclaimClient | undefined,
+	dependencies: AttachDependencies,
+): Promise<AttachState> {
+	if(mode === 'builder') {
+		assert(builderClient, badRequest('Builder browser service is unavailable'))
+		assert(parsed.orgId, badRequest('orgId is required for builder mode'))
+		const { data } = await builderClient.call('CreateAgentBrowserSession', {
+			params: { orgId: parsed.orgId },
+		})
+		let handles: CdpHandles
+		try {
+			handles = await dependencies.connectRemote(data.cdpUrl)
+		} catch(err) {
+			await builderClient.call('DisposeAgentBrowserSession', {
+				params: {
+					orgId: parsed.orgId,
+					browserSessionId: data.id,
+				},
+			}).catch(() => {})
+			throw err
+		}
+
+		return {
+			handles,
+			mode,
+			liveViewUrl: data.liveViewUrl,
+			browserSessionId: data.id,
+			orgId: parsed.orgId,
+			disposeRemote: async() => {
+				await builderClient.call('DisposeAgentBrowserSession', {
+					params: {
+						orgId: parsed.orgId!,
+						browserSessionId: data.id,
+					},
+				})
+			},
+		}
+	}
+
+	if(mode === 'custom') {
+		assert(parsed.cdpUrl, badRequest('cdpUrl is required for custom mode'))
+		const url = new URL(parsed.cdpUrl)
+		assert(
+			url.protocol === 'ws:' || url.protocol === 'wss:',
+			badRequest('cdpUrl must use ws:// or wss://'),
+		)
+		return {
+			handles: await dependencies.connectRemote(parsed.cdpUrl),
+			mode,
+			...(parsed.liveViewUrl ? { liveViewUrl: parsed.liveViewUrl } : {}),
+		}
+	}
+
+	const port = parsed.port ?? persisted?.port ?? 9222
+	if(mode === 'dedicated') {
+		try {
+			await waitForCdpReady(port, 500)
+		} catch{
+			launchChrome({ port, profileDir: defaultProfileDir() })
+			await waitForCdpReady(port, 10_000)
+		}
+	} else {
+		await waitForCdpReady(port, 2_000).catch(() => {
+			throw new Error(
+				`attach mode: nothing answering CDP on port ${port}. Chrome must `
+				+ `be launched with --remote-debugging-port=${port} AND `
+				+ '--user-data-dir=<some-non-default-path>. Chrome 136+ ignores '
+				+ 'the debugging flag for the default profile.',
+			)
+		})
+	}
+
+	return { handles: await dependencies.connectLocal(port), mode, port }
+}
+
+async function disposeState(state: AttachState) {
+	try {
+		await state.handles.close()
+	} finally {
+		await state.disposeRemote?.()
+	}
+}

package/src/mcp/tools/agent/build.ts

@@ -16,7 +16,7 @@ import { ensureAttestorCrypto } from '../../../proof/proof-core.ts'
 import { type RegisteredTool } from '../../server.ts'
 import { analyzeTool } from './analyze.ts'
 import { type AttachState, attachTool } from './attach.ts'
-import { type CaptureStore, captureTools } from './capture.ts'
+import { type CaptureStore, captureTools, resetCaptures } from './capture.ts'
 import { listTabsTool } from './eval.ts'
 import { howItWorksTool } from './how-it-works.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
@@ -42,6 +42,7 @@ function buildAgentState(): AgentState {
  *  capture/proof tools — old mode supplies its own publish tool. */
 export function buildAgentTools(
 	client?: ReclaimClient,
+	builderClient: ReclaimClient | undefined = client,
 ): RegisteredTool[] {
 	const state = buildAgentState()
 	ensureAttestorCrypto()
@@ -49,7 +50,13 @@ export function buildAgentTools(
 	// Stateless docs tool — serve the mode-specific authoring guide to any
 	// client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
 	tools.push(howItWorksTool(!client))
-	tools.push(attachTool(state.attach))
+	const beforeReplace = () => resetCaptures(state.captures)
+	tools.push(attachTool(
+		state.attach, builderClient, 'attach_browser', beforeReplace,
+	))
+	tools.push(attachTool(
+		state.attach, builderClient, 'attach_chrome', beforeReplace,
+	))
 	tools.push(listTabsTool(state.attach))
 	for(const t of captureTools(state.attach, state.captures)) {
 		tools.push(t)

package/src/mcp/tools/agent/capture.ts

@@ -20,13 +20,22 @@ export interface CaptureStore {
 	activeTab?: string
 }
 
+export async function resetCaptures(captures: CaptureStore) {
+	for(const entry of captures.sessions.values()) {
+		await entry.session.stop().catch(() => {})
+	}
+
+	captures.sessions.clear()
+	delete captures.activeTab
+}
+
 export function captureTools(
 	attachRef: { current?: AttachState },
 	captures: CaptureStore,
 ): RegisteredTool[] {
 	const requireAttached = (): AttachState => {
 		if(!attachRef.current) {
-			throw new Error('Not attached. Call attach_chrome first.')
+			throw new Error('Not attached. Call attach_browser first.')
 		}
 
 		return attachRef.current

package/src/mcp/tools/agent/eval.ts

@@ -1,4 +1,3 @@
-import { listTabs } from '../../../cdp/tabs.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { AttachState } from './attach.ts'
 
@@ -16,10 +15,10 @@ export function listTabsTool(attachRef: {
 		},
 		async() => {
 			if(!attachRef.current) {
-				throw new Error('Not attached. Call attach_chrome first.')
+				throw new Error('Not attached. Call attach_browser first.')
 			}
 
-			return { tabs: await listTabs(attachRef.current.port) }
+			return { tabs: await attachRef.current.handles.listTabs() }
 		},
 	)
 }

package/src/mcp/tools/agent/how-it-works.ts

@@ -11,7 +11,7 @@ import { defineTool, type RegisteredTool } from '../../server.ts'
  * so any MCP client — not just Claude Code, which alone auto-loads skills — can
  * pull it. `oldMode` selects the backend-specific guide so the agent is never
  * told to call auth/publish tools that aren't registered in its mode.
- * Stateless: callable before `attach_chrome`.
+ * Stateless: callable before `attach_browser`.
  */
 export function howItWorksTool(oldMode: boolean): RegisteredTool {
 	const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER

package/src/mcp/tools/agent/publish.ts

@@ -234,7 +234,28 @@ export function createVersionFromCaptureTool(
 						description:
 							'Extra requests the injection script is allowed to fire ' +
 							'(e.g. paginated API calls), as RequestSelectionTemplates. ' +
-							'`multiple`/`required` default to true.',
+							'`multiple`/`required` default to true. ' +
+							'⚠️ BEFORE populating this to gate ' +
+							'`verifyProof(proof, { providerId })` (old-devtools calls the ' +
+							'same concept `allowedInjectedRequestData` — same mechanics, ' +
+							'different field name): 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 — populating' +
+							' this for such a provider makes verifyProof reject every real ' +
+							'proof, which is worse than leaving it 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 ' +
+							'injection script\'s guide for the full mechanics and when to ' +
+							'reach for it.',
 						items: ALLOWED_JS_REQUEST_SCHEMA,
 					},
 					interceptorOptions: {

package/src/mcp/tools/agent/session.ts

@@ -1,7 +1,7 @@
 import type { ConfigStore } from '../../../config/store.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
-import type { AttachState } from './attach.ts'
-import type { CaptureStore } from './capture.ts'
+import { type AttachState, disposeAttached } from './attach.ts'
+import { type CaptureStore, resetCaptures } from './capture.ts'
 
 export function sessionTools(
 	attachRef: { current?: AttachState, config: ConfigStore },
@@ -18,11 +18,29 @@ export function sessionTools(
 			async() => ({
 				config: attachRef.config.read()?.browser_agent,
 				attached: Boolean(attachRef.current),
+				mode: attachRef.current?.mode,
 				port: attachRef.current?.port,
+				liveViewUrl: attachRef.current?.liveViewUrl,
+				browserSessionId: attachRef.current?.browserSessionId,
+				orgId: attachRef.current?.orgId,
 				captures: [...captures.sessions.keys()],
 				activeTab: captures.activeTab,
 			}),
 		),
+		defineTool<Record<string, never>>(
+			{
+				name: 'dispose_browser',
+				description:
+					'Stop captures, disconnect the current browser, and immediately '
+					+ 'delete a Builder-hosted Popcorn session. Custom CDP sessions '
+					+ 'are disconnected but never deleted by Reclaim.',
+				inputSchema: { type: 'object', properties: {} },
+			},
+			async() => {
+				await resetAll(attachRef, captures)
+				return { disposed: true }
+			},
+		),
 		defineTool<Record<string, never>>(
 			{
 				name: 'reset_session',
@@ -32,14 +50,17 @@ export function sessionTools(
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => {
-				for(const entry of captures.sessions.values()) {
-					await entry.session.stop().catch(() => {})
-				}
-
-				captures.sessions.clear()
-				delete captures.activeTab
+				await resetAll(attachRef, captures)
 				return { reset: true }
 			},
 		),
 	]
 }
+
+async function resetAll(
+	attachRef: { current?: AttachState, config: ConfigStore },
+	captures: CaptureStore,
+) {
+	await resetCaptures(captures)
+	await disposeAttached(attachRef)
+}

package/src/mcp/tools/agent/shared.ts

@@ -54,19 +54,14 @@ function withLocalOprfMode(provider: ReclaimProvider): ReclaimProvider {
  *  captured requests, prove via the in-process attestor, replay by re-fetch. */
 function localBackend(entry: CaptureEntry): AuthoringBackend {
 	const { tabClient, session, drafts } = entry
-	// The per-tab CDP client is strongly typed to `keyof Commands`; the shared
-	// tools drive it with dynamic method/event names, so view it as string-keyed.
-	const client = tabClient as unknown as {
-		send: (method: string, params: object) => Promise<unknown>
-		once: (e: string, cb: () => void) => void
-		removeListener: (e: string, cb: () => void) => void
-	}
 
 	return {
 		capture: session,
 		drafts,
-		sendCdp: (method, params) => client.send(method, params ?? {}),
+		sendCdp: (method, params) => tabClient.send(method, params ?? {}),
 		waitForEvent: (method, timeoutMs) => new Promise((resolve) => {
+			let stopListening = () => {}
+
 			const onEvent = () => {
 				cleanup()
 				resolve('fired')
@@ -78,10 +73,10 @@ function localBackend(entry: CaptureEntry): AuthoringBackend {
 			}, timeoutMs)
 			const cleanup = () => {
 				clearTimeout(timer)
-				client.removeListener(method, onEvent)
+				stopListening()
 			}
 
-			client.once(method, onEvent)
+			stopListening = tabClient.subscribeOnce(method, onEvent)
 		}),
 		replay: async(draft, opts) => {
 			// Auth-bound check: re-fetch with the secrets dropped. replayProvider

package/src/mcp/tools/authenticate/authenticate.ts

@@ -9,13 +9,23 @@ import { writeSession } from './session-cache.ts'
 const SCOPE = 'openid profile email'
 const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000
 
-export function authenticateTool(client: ReclaimClient): RegisteredTool {
+export function authenticateTool(
+	client: ReclaimClient,
+	name: 'reclaim_authenticate' | 'authenticate_builder' =
+		'reclaim_authenticate',
+): RegisteredTool {
 	return defineTool<Record<string, never>>(
 		{
-			name: 'reclaim_authenticate',
+			name,
 			description:
-				'Authorize the CLI / MCP to make authenticated API calls. Opens the ' +
-				'browser to the builder sign-in page (standard OAuth 2.0 ' +
+				(name === 'authenticate_builder'
+					? 'Authenticate specifically with Builder. Available regardless '
+						+ 'of '
+						+ 'the selected publishing backend. '
+					: '')
+				+ 'Authorize the CLI / MCP to make authenticated API calls. Opens '
+				+ 'the '
+				+ 'browser to the builder sign-in page (standard OAuth 2.0 ' +
 				'authorization-code + PKCE with a localhost redirect) and waits for ' +
 				'the user to sign in and approve. On success the access token is ' +
 				'cached in ~/.reclaim/config.json and activated for this session.\n\n' +

package/src/mcp/tools/authenticate/builder-access.ts

@@ -0,0 +1,42 @@
+import type { ReclaimClient } from '@reclaimprotocol/client'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { authenticateTool } from './authenticate.ts'
+
+/** Legacy-devtools mode needs a distinct Builder login solely for allocating
+ * quota-accounted Popcorn sessions. Builder mode uses its native auth tool. */
+export function buildBuilderAuthenticationTools(
+	client: ReclaimClient,
+): RegisteredTool[] {
+	return [authenticateTool(client, 'authenticate_builder')]
+}
+
+/** Legacy-devtools mode lacks generated Builder API tools, so it needs this
+ * narrow organization-discovery bridge for remote-browser allocation. */
+export function buildBuilderOrganizationTools(
+	client: ReclaimClient,
+): RegisteredTool[] {
+	return [
+		defineTool<{ cursor?: string }>(
+			{
+				name: 'list_builder_organizations',
+				description:
+					'List organizations available to the authenticated Builder user. '
+					+ 'Use an organization id from this result when calling '
+					+ 'attach_browser with mode="builder". Available only in '
+					+ 'legacy-devtools publishing mode; Builder mode uses list_orgs.',
+				inputSchema: {
+					type: 'object',
+					properties: {
+						cursor: { type: 'string', maxLength: 500 },
+					},
+				},
+			},
+			async({ cursor }) => {
+				const { data } = await client.call('ListOrgs', {
+					query: { ...(cursor ? { cursor } : {}) },
+				})
+				return data
+			},
+		),
+	]
+}

package/src/mcp/tools/authenticate/index.ts

@@ -1,4 +1,8 @@
 // Barrel for the credential tool group: local eth proof-owner key (env/PEM)
 // and the org-token-authenticated builder tools. Import from here.
+export {
+	buildBuilderAuthenticationTools,
+	buildBuilderOrganizationTools,
+} from './builder-access.ts'
 export { buildCredentialTools, buildLocalCredentialTools } from './build.ts'
 export { readSession } from './session-cache.ts'

package/src/old/login-cdp.ts

@@ -138,15 +138,14 @@ export async function captureFirebaseTokenViaCdp(opts: {
 
 	try {
 		const session = await handles.attachToTab(targetId)
-		const { Runtime } = session
 		const deadline = Date.now() + timeoutMs
 		while(Date.now() < deadline) {
-			const r = await Runtime.evaluate({
+			const result = await session.send('Runtime.evaluate', {
 				expression: EXTRACT_TOKEN_JS,
 				awaitPromise: true,
 				returnByValue: true,
 			})
-			const value = r.result?.value
+			const value = runtimeResultValue(result)
 			if(typeof value === 'string' && value.length > 0) {
 				return { token: value, closedBrowser: launchedByUs }
 			}
@@ -173,3 +172,14 @@ export async function captureFirebaseTokenViaCdp(opts: {
 		await handles.close().catch(() => {})
 	}
 }
+
+function runtimeResultValue(value: unknown): unknown {
+	if(typeof value !== 'object' || !value || !('result' in value)) {
+		return undefined
+	}
+
+	const result = value.result
+	return typeof result === 'object' && result && 'value' in result
+		? result.value
+		: undefined
+}

package/src/old/tools/publish.ts

@@ -288,7 +288,29 @@ export function createVersionFromCaptureTool(
 							'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.',
+							'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.',
 						items: {
 							type: 'object',
 							properties: {
@@ -528,9 +550,9 @@ export function createVersionFromCaptureTool(
 						'reads them when adding a version. ' +
 						(followUp
 							? 'They were applied by the follow-up version the tool ' +
-								'created to set disableRequestReplay.'
+							'created to set disableRequestReplay.'
 							: 'Publish once to create the provider, then call this ' +
-								'again WITH the returned providerId to set them.'),
+							'again WITH the returned providerId to set them.'),
 					)
 				}