@reclaimprotocol/agent 0.1.17 → 0.1.20

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/mcp/tools/mode/mode.ts

@@ -1,10 +1,12 @@
 import type { ConfigStore, DevtoolsMode } from '../../../config/store.ts'
 import { defaultConfigPath } from '../../../config/store.ts'
+import { oldModeSource } from '../../../consts.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 
 /**
- * The `set_devtools_mode` tool: persist which backend the MCP server targets
- * (legacy `old` devtools vs the new `builder`). The choice is written to
+ * The `set_devtools_mode` / `get_devtools_mode` tools: persist which backend
+ * the MCP server targets (`old` devtools vs the `builder`), and
+ * report the mode currently in effect. The choice is written to
  * `~/.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
@@ -25,8 +27,8 @@ export function buildModeTools(
 			{
 				name: 'set_devtools_mode',
 				description:
-					'Choose which backend the MCP server targets: "old" (legacy '
-					+ 'Reclaim devtools) or "builder" (the new builder backend). '
+					'Choose which backend the MCP server targets: "old" (devtools) '
+					+ 'or "builder" (the builder backend). '
 					+ 'Persists the choice to ~/.reclaim/config.json; it takes effect '
 					+ 'the next time the MCP server starts, so restart/reconnect after '
 					+ 'switching. An explicit USE_OLD_DEVTOOLS env var overrides this.',
@@ -54,5 +56,27 @@ export function buildModeTools(
 				}
 			},
 		),
+		defineTool<Record<string, never>>(
+			{
+				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.',
+				inputSchema: { type: 'object', properties: {} },
+			},
+			async() => {
+				const persisted = config.read()?.mode
+				return {
+					mode: current,
+					source: oldModeSource(persisted),
+					persistedMode: persisted ?? null,
+					configPath: defaultConfigPath(),
+				}
+			},
+		),
 	]
 }

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/to-register.ts

@@ -1,3 +1,4 @@
+import assert from 'node:assert'
 import type { ReclaimProvider } from '../provider/schema.ts'
 import type { AllowedJsRequest, DraftRequest } from '../provider/to-version.ts'
 import type {
@@ -6,7 +7,7 @@ import type {
 } from './client.ts'
 
 /** Default web settings, mirroring the builder openapi defaults
- *  (`ProviderWebSettings.geoLocation`, `PortalClientOptions.useProxy`). The old
+ *  (`ProviderWebSettings.geoLocation`, `PortalClientOptions.useProxy`). The
  *  backend accepts both: `geoLocation` lives on the providerConfig, `useProxy`
  *  is a Provider-level flag (register only). */
 const DEFAULT_GEO_LOCATION = '{{DYNAMIC_GEO}}'
@@ -14,15 +15,15 @@ const DEFAULT_USE_PROXY = true
 
 /**
  * Translate a drafted `ReclaimProvider` (from `propose_provider`) into the
- * OLD devtools backend shapes. Deliberately a SEPARATE module from
+ * devtools backend shapes. Deliberately a SEPARATE module from
  * `provider/to-version.ts` (the builder translator) — the two backends have
  * structurally different bodies:
  *
  *   - builder NESTS each redaction into its match's `extract`;
- *   - old devtools keeps `responseMatches` and `responseRedactions` as
+ *   - devtools keeps `responseMatches` and `responseRedactions` as
  *     PARALLEL arrays on each `requestData` entry.
  *
- * Old-devtools limit we enforce here (a clear error beats a confusing
+ * Devtools limit we enforce here (a clear error beats a confusing
  * server-side 400): only `GET` / `POST` methods. OPRF redactions are passed
  * through unchanged — the backend's `hash` field accepts them.
  */
@@ -35,7 +36,7 @@ export interface OldProviderOpts {
 	/** Defaults to `true` when omitted. Register only (Provider-level flag). */
 	useProxy?: boolean
 	providerType?: 'PRIVATE' | 'PUBLIC'
-	/** Page-injection script — old-devtools' name for the builder's
+	/** 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. */
@@ -59,6 +60,14 @@ export interface OldProviderOpts {
 	/** Config (add-version) ONLY — the register endpoint never reads this
 	 *  field from the request body. Free-form JSON. */
 	extensionConfig?: unknown
+	/** Provider-level `disableRequestReplay` (HAWKEYE document replay skip).
+	 *  Config (add-version) ONLY: the register endpoint hardcodes it to false
+	 *  — the publish tool follows a register up with an add-version call to
+	 *  apply it for new providers (see `old/tools/publish.ts`). NOTE the
+	 *  builder backend has NO equivalent; its inverse is
+	 *  `webSettings.clientOptions.inapp.interceptorOptions
+	 *  .isDocumentRequestReplayEnabled`. */
+	disableRequestReplay?: boolean
 }
 
 interface OldResponseMatch {
@@ -80,11 +89,11 @@ interface OldResponseRedaction {
 
 interface OldRequestData {
 	url: string
-	urlType: 'CONSTANT' | 'TEMPLATE'
+	urlType: 'REGEX' | 'CONSTANT' | 'TEMPLATE'
 	method: 'GET' | 'POST'
 	responseMatches: OldResponseMatch[]
 	responseRedactions: OldResponseRedaction[]
-	credentials: 'include'
+	credentials: 'omit' | 'same-origin' | 'include'
 	bodySniff?: { enabled: boolean, template: string }
 }
 
@@ -103,36 +112,42 @@ export interface OldInjectedRequestData extends OldRequestData {
  *  entries — a `ReclaimProvider` satisfies it structurally either way. */
 function requestDataFromProvider(provider: DraftRequest): OldRequestData {
 	const method = String(provider.method).toUpperCase()
-	if(method !== 'GET' && method !== 'POST') {
-		throw new Error(
-			'Old devtools supports only GET/POST requests; got ' +
+	assert(
+		method === 'GET' || method === 'POST',
+		new Error(
+			'Devtools supports only GET/POST requests; got ' +
 			`"${provider.method}". Re-capture against a GET/POST endpoint.`,
 		)
-	}
+	)
 
-	// The old backend has no dotted interpolation: consumer-supplied params
+	// The devtools backend has no dotted interpolation: consumer-supplied params
 	// must use the `{{context_<name>}}` form here, not the builder's
 	// `{{context.<name>}}`. Catch the mix-up at publish with a clear error
 	// instead of a template that silently never resolves.
 	const dotted = `${provider.url}\n${provider.body ?? ''}`
 		.match(/\{\{context\.[A-Za-z_][A-Za-z0-9_]*\}\}/)
-	if(dotted) {
-		throw new Error(
-			`Old devtools does not support ${dotted[0]} — rename ` +
+	assert(
+		!dotted,
+		new Error(
+			`Devtools does not support ${dotted?.[0]} — rename ` +
 			'consumer-supplied params to the {{context_<name>}} form ' +
 			'for this backend.',
 		)
-	}
+	)
 
 	const responseMatches: OldResponseMatch[] = (provider.responseMatches ?? [])
 		.map((m, i) => ({
 			value: m.value,
 			type: m.type ?? 'contains',
-			isOptional: false,
+			// The backend honors isOptional on BOTH register and add-version
+			// (responseMatches pass through verbatim) — forward the author's
+			// flag, default false. (`invert` has no old-backend equivalent and
+			// stays dropped.)
+			isOptional: m.isOptional ?? false,
 			order: i,
 		}))
 
-	// Old devtools wants `responseMatches` and `responseRedactions` as PARALLEL
+	// Devtools wants `responseMatches` and `responseRedactions` as PARALLEL
 	// arrays — same shape the builder uses, so pass them through directly. We do
 	// NOT enforce any match/redaction count relationship here (and never pad —
 	// empty placeholder matches break proof generation): the author keeps full
@@ -166,36 +181,38 @@ function requestDataFromProvider(provider: DraftRequest): OldRequestData {
 
 	const requestData: OldRequestData = {
 		url: provider.url,
-		// `{{param}}` placeholders → TEMPLATE so the backend templates them;
-		// otherwise a fixed CONSTANT url. (REGEX is never drafted.)
-		urlType: provider.url.includes('{{') ? 'TEMPLATE' : 'CONSTANT',
+		// Explicit override wins; otherwise `{{param}}` placeholders → TEMPLATE
+		// so the backend templates them, else a fixed CONSTANT url.
+		urlType: provider.urlType
+			?? (provider.url.includes('{{') ? 'TEMPLATE' : 'CONSTANT'),
 		method: method,
 		responseMatches,
 		responseRedactions,
 		// The verification client re-supplies cookies/auth at runtime; secrets
 		// are never persisted (propose_provider already stripped them).
-		credentials: 'include',
+		credentials: provider.credentials ?? 'include',
 	}
 	if(provider.body !== undefined) {
 		requestData.bodySniff = { enabled: true, template: provider.body }
 	}
 
-	// NOTE: `responseVariables` is intentionally omitted — the old backend
+	// NOTE: `responseVariables` is intentionally omitted — the devtools backend
 	// auto-extracts it from `{{var}}` placeholders in responseMatches. Sending
 	// it ourselves would risk drifting from the server's own extraction.
 	return requestData
 }
 
 /** One `requestData` entry per drafted provider. A multi-request provider
- *  becomes parallel entries that the old backend runs together at verification
- *  (the same way the builder version carries multiple `requests`). */
+ *  becomes parallel entries that the devtools backend runs together at
+ *  verification (the same way the builder version carries multiple
+ *  `requests`). */
 function requestDataFrom(providers: ReclaimProvider[]): OldRequestData[] {
 	return providers.map(requestDataFromProvider)
 }
 
 /** Translate fresh `allowedInjectedRequestData` drafts (the author's input
  *  shape, `AllowedJsRequest[]` — same shape the builder translator uses for
- *  its own `allowedJsRequests`) into the old backend's shape. A
+ *  its own `allowedJsRequests`) into the devtools backend's shape. A
  *  carried-forward value read back from an existing version is ALREADY in
  *  this shape and should be passed straight through instead — don't run it
  *  through this a second time. */
@@ -300,10 +317,16 @@ export function providerToConfigBody(
 		providerConfig.extensionConfig = opts.extensionConfig
 	}
 
+	// The config (add-version) controller persists providerConfig verbatim,
+	// so this lands as-is; the register controller ignores it entirely.
+	if(opts.disableRequestReplay !== undefined) {
+		providerConfig.disableRequestReplay = opts.disableRequestReplay
+	}
+
 	return { providerConfig, version, versionInfo }
 }
 
-/** Minimal version triplet as the old backend stores it. */
+/** Minimal version triplet as the devtools backend stores it. */
 export interface SemverTriplet {
 	major: number
 	minor: number

package/src/old/tools/publish.ts

@@ -19,6 +19,16 @@ import {
 
 const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture'
 
+/** Pull the new provider's id out of a register response, tolerant of the
+ *  envelope (`{providerId}`, `{provider:{providerId}}`, `{id}`). */
+function extractProviderId(resp: unknown): string | undefined {
+	const obj = resp as
+		{ providerId?: string, provider?: { providerId?: string }, id?: string }
+		| null
+		| undefined
+	return obj?.providerId ?? obj?.provider?.providerId ?? obj?.id
+}
+
 /**
  * The old backend lets you add a version only to a provider YOU own. A
  * `providerId` for a public provider (or anyone else's) comes back as
@@ -81,11 +91,12 @@ export function createVersionFromCaptureTool(
 		stepsToFollow?: string
 		useIncognitoWebview?: boolean
 		extensionConfig?: unknown
+		disableRequestReplay?: boolean
 	}>(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Publish drafted ReclaimProvider(s) to the OLD devtools backend. ' +
+				'Publish drafted ReclaimProvider(s) to the devtools backend. ' +
 				'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' +
@@ -103,7 +114,7 @@ export function createVersionFromCaptureTool(
 				"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 ' +
-				'page-injection script (old-devtools\' name for the builder\'s ' +
+				'page-injection script (the devtools name for the builder\'s ' +
 				'jsUserScripts) 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 ' +
@@ -120,7 +131,14 @@ export function createVersionFromCaptureTool(
 				'values plus your change) back into this call. ' +
 				'`allowedInjectedRequestData`/`useIncognitoWebview`/' +
 				'`extensionConfig` only take effect on add-version — the register ' +
-				'endpoint (no `providerId`) ignores them. \n\n' +
+				'endpoint (no `providerId`) ignores them. `disableRequestReplay` ' +
+				'is also add-version-only, but when it is true the tool follows ' +
+				'a register up with an add-version call automatically so it takes ' +
+				'effect on new providers too. 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.',
 			inputSchema: {
 				type: 'object',
@@ -136,6 +154,21 @@ export function createVersionFromCaptureTool(
 							method: { type: 'string' },
 							headers: { type: 'object' },
 							body: { type: 'string' },
+							credentials: {
+								type: 'string',
+								enum: ['omit', 'same-origin', 'include'],
+								description:
+									'How the verification client supplies cookies/auth ' +
+									'when replaying this request. Default `include`.',
+							},
+							urlType: {
+								type: 'string',
+								enum: ['REGEX', 'CONSTANT', 'TEMPLATE'],
+								description:
+									'How the backend treats the URL. Default derived: ' +
+									'TEMPLATE when the URL has {{placeholders}}, else ' +
+									'CONSTANT.',
+							},
 							responseMatches: { type: 'array' },
 							responseRedactions: { type: 'array' },
 							paramValues: { type: 'object' },
@@ -165,6 +198,14 @@ export function createVersionFromCaptureTool(
 								method: { type: 'string' },
 								headers: { type: 'object' },
 								body: { type: 'string' },
+								credentials: {
+									type: 'string',
+									enum: ['omit', 'same-origin', 'include'],
+								},
+								urlType: {
+									type: 'string',
+									enum: ['REGEX', 'CONSTANT', 'TEMPLATE'],
+								},
 								responseMatches: { type: 'array' },
 								responseRedactions: { type: 'array' },
 								paramValues: { type: 'object' },
@@ -247,12 +288,42 @@ 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: {
 								url: { type: 'string' },
 								method: { type: 'string' },
+								urlType: {
+									type: 'string',
+									enum: ['REGEX', 'CONSTANT', 'TEMPLATE'],
+									description:
+										'How the backend treats this URL. Default derived ' +
+										'from {{placeholders}} (TEMPLATE) like a normal ' +
+										'request entry.',
+								},
 								body: {
 									type: 'string',
 									description:
@@ -375,6 +446,15 @@ export function createVersionFromCaptureTool(
 							'Free-form JSON passed through to the client. Add-version ' +
 							'ONLY.',
 					},
+					disableRequestReplay: {
+						type: 'boolean',
+						description:
+							'Skip replaying the main document request (HAWKEYE ' +
+							'provider-level flag). Honored on add-version; for a ' +
+							'provider (no `providerId`) the register endpoint ignores ' +
+							'it, so when true the tool automatically follows the ' +
+							'register up with an add-version call that applies it.',
+					},
 				},
 				required: ['initialUrl'],
 			},
@@ -413,6 +493,7 @@ export function createVersionFromCaptureTool(
 				stepsToFollow: args.stepsToFollow,
 				useIncognitoWebview: args.useIncognitoWebview,
 				extensionConfig: args.extensionConfig,
+				disableRequestReplay: args.disableRequestReplay,
 				allowedInjectedRequestData: args.allowedInjectedRequestData
 					? injectedRequestDataFrom(
 						args.allowedInjectedRequestData,
@@ -448,6 +529,12 @@ export function createVersionFromCaptureTool(
 					)
 				}
 
+				// disableRequestReplay is honored ONLY on add-version, so a
+				// register can't set it — when true we immediately follow the
+				// register with an add-version call (which also lands any other
+				// register-ignored fields).
+				const followUp = args.disableRequestReplay === true
+
 				const REGISTER_IGNORED_KEYS = [
 					'allowedInjectedRequestData',
 					'useIncognitoWebview',
@@ -459,15 +546,50 @@ export function createVersionFromCaptureTool(
 					notes.push(
 						`${ignoredOnRegister.join(', ')} ` +
 						`${ignoredOnRegister.length > 1 ? 'are' : 'is'} ` +
-						'ignored on register (no providerId) — the old backend only ' +
-						'reads them when adding a version. Publish once to create ' +
-						'the provider, then call this again WITH the returned ' +
-						'providerId to set them.',
+						'ignored on register (no providerId) — the devtools backend only ' +
+						'reads them when adding a version. ' +
+						(followUp
+							? 'They were applied by the follow-up version the tool ' +
+							'created to set disableRequestReplay.'
+							: 'Publish once to create the provider, then call this ' +
+							'again WITH the returned providerId to set them.'),
 					)
 				}
 
 				const body = providerToRegisterBody(providers, opts)
-				return withNotes(await client.registerProvider(body))
+				const registered = await client.registerProvider(body)
+
+				if(followUp) {
+					const newProviderId = extractProviderId(registered)
+					if(newProviderId) {
+						const versionsResp = await client.listVersions(newProviderId)
+						const followVersion = bumpPatchString(
+							extractVersions(versionsResp),
+						)
+						const configBody = providerToConfigBody(
+							providers,
+							{ ...opts, disableRequestReplay: true },
+							followVersion,
+							DEFAULT_VERSION_INFO,
+						)
+						await client.updateProviderConfig(newProviderId, configBody)
+						notes.push(
+							'disableRequestReplay is ignored by the register endpoint — ' +
+							`applied it via a follow-up version (${followVersion}) on ` +
+							'the new provider, which also lands any register-ignored ' +
+							'fields you passed.',
+						)
+					} else {
+						notes.push(
+							'Could not apply disableRequestReplay: the register ' +
+							'response did not include the new providerId. Call this ' +
+							'tool again WITH `providerId` and `disableRequestReplay: ' +
+							'true` to set it.',
+						)
+					}
+				}
+
+				return withNotes(registered)
 			}
 
 			// New version of an existing provider — pick the next patch above