@reclaimprotocol/agent 0.1.34 → 0.1.36

package/src/mcp/tools/agent/check-attestor.ts

@@ -0,0 +1,49 @@
+import {
+	checkAttestor,
+	type CheckAttestorOptions,
+} from '../../../proof/check-attestor.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+
+/** `check_attestor`: proves a public request to show whether the attestor
+ *  works from this machine. `check` is injectable so tests need no network. */
+export function checkAttestorTool(
+	check: (opts: CheckAttestorOptions) => ReturnType<typeof checkAttestor>
+		= checkAttestor,
+): RegisteredTool {
+	return defineTool<{ attestorUrl?: string }>(
+		{
+			name: 'check_attestor',
+			description:
+				'Checks that the Reclaim attestor works from this machine by proving '
+				+ 'a public CoinGecko price request with a throwaway key. It uses no '
+				+ 'credential, provider, or logged-in site, and takes up to 45 '
+				+ 'seconds (about 8 when healthy). Call it once when you set up a '
+				+ 'new provider build, and after `run_proof` fails with a network '
+				+ 'error. Returns `{ ok, attestorUrl, durationMs, '
+				+ 'extractedParameters, error, errorKind }`. If `ok` is true, the '
+				+ 'attestor is fine and a failing proof points to the target site. '
+				+ 'If `errorKind` is `attestor-unreachable`, this machine cannot '
+				+ 'reach the attestor (network, VPN, firewall, or proxy): tell the '
+				+ 'developer. If it is `setup-failed`, the ZK file download failed '
+				+ 'before the attestor was contacted: tell the developer to check '
+				+ 'network access to the circuit download. If it is '
+				+ '`attestor-error`, the attestor rejected the claim: report '
+				+ '`error`.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					attestorUrl: {
+						type: 'string',
+						description:
+							'Attestor websocket URL. Set it only if the developer '
+							+ 'supplied one; the default is the public attestor.',
+					},
+				},
+			},
+			annotations: { openWorldHint: true, readOnlyHint: true },
+		},
+		async({ attestorUrl }) => {
+			return check(attestorUrl ? { attestorUrl } : {})
+		},
+	)
+}

package/src/mcp/tools/agent/live-view.ts

@@ -3,9 +3,10 @@
  * attached container browser's built-in viewer behind a public URL, so someone
  * who is not at this machine can watch it and optionally drive it.
  *
- * The server never runs, downloads or resolves cloudflared: the agent runs it
- * itself and passes the resulting `trycloudflare.com` URL back to get the link
- * to hand out.
+ * The server never runs, downloads or resolves cloudflared. The developer
+ * chooses who runs it: they run it themselves (recommended) or approve the
+ * agent running it. Either way the `trycloudflare.com` URL it prints comes
+ * back as `publicUrl` to get the link to hand out.
  *
  * Scoped to `container` mode on purpose. A `builder`-mode browser already has
  * a hosted live view at `attach_browser`'s `liveViewUrl`.
@@ -30,9 +31,13 @@ export function liveViewTools(
 					'Returns a link that lets someone who is not at this machine watch '
 					+ 'and drive the attached `container` browser, for example to sign '
 					+ 'in. This server opens no tunnel itself. Step 1: call with no '
-					+ 'arguments to get the local viewer URL and the `cloudflared` '
-					+ 'command for the developer to run. Step 2: after cloudflared '
-					+ 'prints its `https://*.trycloudflare.com` URL, call again with it '
+					+ 'arguments. It returns the local viewer URL, the `cloudflared` '
+					+ 'command, and two `choices`. Ask the developer to pick one before '
+					+ 'any tunnel runs: (a, recommended) they run `! cloudflared tunnel '
+					+ '--url http://localhost:<port>` themselves and paste the printed '
+					+ '`https://*.trycloudflare.com` URL; (b) they explicitly approve '
+					+ 'you running the command in the background. Never install '
+					+ '`cloudflared` without approval. Step 2: call again with the URL '
 					+ 'as `publicUrl` to get the link to relay. The link grants access '
 					+ 'to that browser session only, so share it only with the person '
 					+ 'who needs it. For `builder`, use the `liveViewUrl` from '
@@ -90,28 +95,47 @@ export function liveViewTools(
 							+ 'separate window is visible too.',
 							'Opening it on a phone lays the page out for that phone, with '
 							+ 'touch, pinch-zoom and the soft keyboard.',
-							'When they are done, stop the cloudflared process you started. '
-							+ 'The browser keeps running until `dispose_browser`.',
+							'When they are done, stop the cloudflared process: yourself if '
+							+ 'you started it, otherwise ask the developer. The browser '
+							+ 'keeps running until `dispose_browser`.',
 						],
 					}
 				}
 
 				const localUrl = `http://localhost:${viewerPort}`
+				const command = `cloudflared tunnel --url ${localUrl}`
 				return {
 					localViewerUrl: ensureLiveViewUrl(localUrl),
 					port: viewerPort,
-					command: `cloudflared tunnel --url ${localUrl}`,
+					command,
+					choices: [
+						{
+							id: 'developer-runs',
+							recommended: true,
+							action: `Run \`! ${command}\` in the prompt, then paste the `
+								+ 'https://*.trycloudflare.com URL it prints.',
+						},
+						{
+							id: 'agent-runs',
+							recommended: false,
+							action: 'Approve the agent to run the command in the '
+								+ 'background and read the URL from its output.',
+						},
+					],
 					_notes: [
-						'Run `command` yourself in a background process. If `cloudflared` '
-						+ 'is not installed, tell the developer and ask them to install '
-						+ 'it (https://developers.cloudflare.com/cloudflare-one/'
-						+ 'connections/connect-networks/downloads/) — do not install it '
+						'Ask the developer to choose before any tunnel runs. Do not run '
+						+ '`command` until they pick `agent-runs`.',
+						'If they pick `developer-runs`, wait for the pasted URL. If they '
+						+ 'pick `agent-runs`, run `command` in a background process and '
+						+ 'read its output for a line containing '
+						+ '`https://<words>.trycloudflare.com`.',
+						'If `cloudflared` is not installed, tell the developer and ask '
+						+ 'them to install it '
+						+ '(https://developers.cloudflare.com/cloudflare-one/'
+						+ 'connections/connect-networks/downloads/). Never install it '
 						+ 'without their approval.',
-						'Read its output for a line containing '
-						+ '`https://<words>.trycloudflare.com`. That is the public URL.',
-						'Call share_browser_view again with that value as `publicUrl` '
-						+ 'to get the link to relay. Never guess or reconstruct the '
-						+ 'hostname.',
+						'Call share_browser_view again with the URL as `publicUrl` to get '
+						+ 'the link to relay. Never guess or reconstruct the hostname.',
 						'Expose only this port. Never tunnel the browser\'s CDP port.',
 					],
 				}

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

@@ -7,6 +7,11 @@ import {
 	tailLogs,
 	warnsAndErrors,
 } from '../../../proof/attestor.ts'
+import {
+	type AttestorCheckResult,
+	type CheckAttestorOptions,
+	isNetworkError,
+} from '../../../proof/check-attestor.ts'
 
 function claimsDir(): string {
 	return join(reclaimHomeDirPath(), 'claims')
@@ -192,3 +197,53 @@ export function shapeRichProofResult(
 
 	return out
 }
+
+export interface ProofDiagnosis {
+	attestor: AttestorCheckResult
+	likelyCause: string
+	next: string
+}
+
+/**
+ * When an unverified proof failed with a network-like error, runs the
+ * attestor check once and says whether the attestor or the target site is the
+ * likely cause. Returns `undefined` for verified proofs and other errors.
+ */
+export async function diagnoseNetworkFailure(
+	result: Pick<ProofResult, 'verified' | 'error' | 'errorKind'>,
+	check: (opts: CheckAttestorOptions) => Promise<AttestorCheckResult>,
+	attestorUrl?: string,
+): Promise<ProofDiagnosis | undefined> {
+	if(
+		result.verified
+		|| result.errorKind !== undefined
+		|| !isNetworkError(result.error)
+	) {
+		return undefined
+	}
+
+	const attestor = await check(attestorUrl ? { attestorUrl } : {})
+	if(attestor.ok) {
+		return {
+			attestor,
+			likelyCause:
+				'The attestor works from this machine, so the target site likely '
+				+ 'blocks or drops the attestor\'s network (geo or IP restriction).',
+			next:
+				'If the browser attach mode is "builder", call `run_proof_via_pod`. '
+				+ 'Otherwise tell the developer and suggest asking the Reclaim team. '
+				+ 'Do not retry the same proof.',
+		}
+	}
+
+	return {
+		attestor,
+		likelyCause:
+			'The attestor check also failed, so this machine cannot reach the '
+			+ 'attestor (network, VPN, firewall, or proxy).',
+		next:
+			'Tell the developer. To see the connection details, suggest '
+			+ 'restarting the MCP server with `RECLAIM_AGENT_TRACE=1`. Do not '
+			+ 'retry the same proof.',
+	}
+}

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

@@ -15,11 +15,12 @@ import {
 	type KeptScriptRef,
 } from '../../../authoring/index.ts'
 import { runAttestorProof } from '../../../proof/attestor.ts'
+import { checkAttestor } from '../../../proof/check-attestor.ts'
 import { replayProviderInPage } from '../../../proof/page-replay.ts'
 import type { OprfMode, ReclaimProvider } from '../../../provider/schema.ts'
 import type { RegisteredTool } from '../../server.ts'
 import type { CaptureEntry, CaptureStore } from './capture.ts'
-import { shapeRichProofResult } from './proof.ts'
+import { diagnoseNetworkFailure, shapeRichProofResult } from './proof.ts'
 
 /**
  * OPRF mode this LOCAL (non-TEE) attestor can actually run. Recipes carry
@@ -58,6 +59,7 @@ function withLocalOprfMode(provider: ReclaimProvider): ReclaimProvider {
 function localBackend(
 	entry: CaptureEntry,
 	kept: KeptScriptRef,
+	check: typeof checkAttestor,
 ): AuthoringBackend {
 	const { tabClient, session, drafts } = entry
 	const sendCdp = (method: string, params?: Record<string, unknown>) => {
@@ -112,11 +114,15 @@ function localBackend(
 					...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
 				},
 			)
-			return shapeRichProofResult(result, {
+			const shaped = shapeRichProofResult(result, {
 				provider: draft.provider,
 				hasSecrets: Object.keys(draft.secrets).length > 0,
 				...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
 			})
+			const diagnosis = await diagnoseNetworkFailure(
+				result, check, opts?.attestorUrl,
+			)
+			return diagnosis ? { ...shaped, diagnosis } : shaped
 		},
 	}
 }
@@ -126,25 +132,26 @@ function localBackend(
  *  of this). */
 const RUN_PROOF_EXTRAS = {
 	description:
-		'Run a full zkTLS proof of the drafted recipe through the Reclaim '
-		+ 'attestor SDK. Use only after replay_request looks right — attestor '
-		+ 'calls are expensive. Writes the full claim to '
-		+ '~/.reclaim/claims/<timestamp>.json and returns identifier + '
-		+ 'extractedParameters + claimPath + a prettified `claim` (request '
-		+ 'dropped, byte arrays as base64). With RECLAIM_AGENT_TRACE=1, also '
-		+ 'writes a per-call diagnostic dump (input provider, sentParams, full '
-		+ 'attestor log stream, result) and returns it as `runLogPath`. '
-		+ '`attestorUrl` overrides the default only when the dev supplies a '
-		+ 'specific alternative — do NOT invent backup URLs. `ownerAddress` '
-		+ '(the credential to sign with) is REQUIRED — call resolve_owner_key '
-		+ 'first. errorKind="missing-owner-key" means that address has no known '
-		+ 'private key; re-run resolve_owner_key or issue/import a credential. '
-		+ 'NOTE: unlike replay_request (which re-issues from inside the live '
-		+ 'attached browser tab), the ATTESTOR calls the target from its OWN '
-		+ 'network/IP, separate from the browser\'s. A request that replayed '
-		+ 'fine can still fail here for geo/IP-bound content (country-locked '
-		+ "pages, IP-allowlisted APIs) — if that happens, it's a property of "
-		+ 'the site, not a bug in the draft.',
+		'Proves the drafted recipe with a full zkTLS proof through the attestor '
+		+ 'SDK. Call it after `replay_request` looks right; attestor calls are '
+		+ 'expensive. Call `resolve_owner_key` first and pass its address as '
+		+ '`ownerAddress`. Writes the full claim to '
+		+ '`~/.reclaim/claims/<timestamp>.json`. Returns `identifier`, '
+		+ '`extractedParameters`, `claimPath`, and a readable `claim` (request '
+		+ 'removed, byte arrays as base64). Set `RECLAIM_AGENT_TRACE=1` to also '
+		+ 'get `runLogPath`, a diagnostic dump with the attestor log stream. '
+		+ 'Set `attestorUrl` only if the developer supplied one; never invent '
+		+ 'backup URLs. If `errorKind` is `missing-owner-key`, the address has '
+		+ 'no known private key: run `resolve_owner_key` again, or issue or '
+		+ 'import a credential. Unlike `replay_request`, which re-sends from '
+		+ 'inside the attached browser tab, the attestor calls the target from '
+		+ 'its own network and IP. A request that replayed can still fail here '
+		+ 'for geo- or IP-bound content, such as country-locked pages or '
+		+ 'IP-allowlisted APIs. That is a property of the site, not a draft '
+		+ 'bug. After a network-like failure ("connection closed", '
+		+ '`ERROR_NETWORK_ERROR`, timeout), the result includes `diagnosis` '
+		+ 'with `attestor` (a `check_attestor` result), `likelyCause`, and '
+		+ '`next`. Follow `next`; do not retry the same proof.',
 	properties: {
 		ownerAddress: {
 			type: 'string',
@@ -168,7 +175,10 @@ const RUN_PROOF_EXTRAS = {
  *  takes `captureId`; `run_proof` also gets the credential-aware contract. The
  *  tools are authored plain in `../../../authoring`; this only wraps them with
  *  `extendTool` (handlers untouched — loose arg parse keeps `captureId`). */
-export function sharedAuthoringTools(captures: CaptureStore): RegisteredTool[] {
+export function sharedAuthoringTools(
+	captures: CaptureStore,
+	check: typeof checkAttestor = checkAttestor,
+): RegisteredTool[] {
 	const resolveBackend = (args: Record<string, unknown>): AuthoringBackend => {
 		const captureId = String(args.captureId)
 		const entry = captures.sessions.get(captureId)
@@ -179,7 +189,7 @@ export function sharedAuthoringTools(captures: CaptureStore): RegisteredTool[] {
 			)
 		}
 
-		return localBackend(entry, captures)
+		return localBackend(entry, captures, check)
 	}
 
 	return authoringTools(resolveBackend).map((tool) => {

package/src/mcp/tools/agent/start-integration.ts

@@ -19,10 +19,11 @@ export function startIntegrationTool(): RegisteredTool {
 			name: 'start_integration',
 			description:
 				'Returns a step-by-step plan for adding Reclaim verification to the '
-				+ 'current codebase: sign in, build or choose a provider, then add the '
-				+ 'session route, callback, and Verify button. Call it first when a '
-				+ 'developer wants their users to prove something, and follow the '
-				+ 'plan to the end. Changes nothing itself.',
+				+ 'current codebase: sign in, set up the app (session route, callback, '
+				+ 'Verify button, local event proxy) in parallel with building or '
+				+ 'choosing the provider, then wire the provider and test. Call it '
+				+ 'first when a developer wants their users to prove something, and '
+				+ 'follow the plan to the end. Changes nothing itself.',
 			inputSchema: {
 				type: 'object',
 				required: ['goal'],

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

@@ -1,4 +1,6 @@
 import type { RegisteredTool } from '../../server.ts'
+import { proxyCallbackEventsTool } from './proxy-callback-events.ts'
+import { readCallbackEventsTool } from './read-callback-events.ts'
 import { verificationResultTool } from './result.ts'
 
 /**
@@ -6,11 +8,17 @@ import { verificationResultTool } from './result.ts'
  * generated API surface. `get_verification_result` authenticates with the org
  * token, checks status, pulls the stored payload, and decrypts it locally with
  * the optional eth key — a flow the generated raw-API tools can't express
- * (the decryption key never leaves the consumer). Diagnosis is left to the
+ * (the decryption key never leaves the consumer). `read_callback_events` and
+ * `proxy_callback_events` read and forward the org's pull-listener events.
+ * Diagnosis is left to the
  * agent over the generated tools (`get_verification_session`,
  * `list_verification_events`, `list_verification_deliveries`), whose
  * descriptions carry the lifecycle and delivery semantics.
  */
 export function buildVerificationTools(): RegisteredTool[] {
-	return [verificationResultTool()]
+	return [
+		verificationResultTool(),
+		readCallbackEventsTool(),
+		proxyCallbackEventsTool(),
+	]
 }

package/src/mcp/tools/verification/callback-listener.ts

@@ -0,0 +1,203 @@
+import { badGateway } from '@hapi/boom'
+import { ReclaimClient } from '@reclaimprotocol/client/api'
+import type { IOperationResponse } from '@reclaimprotocol/client/openapi'
+import assert from 'node:assert'
+import { setTimeout as delay } from 'node:timers/promises'
+import { apiUrl } from '../../../consts.ts'
+import { LOGGER } from '../../../logger.ts'
+import { NAME, VERSION } from '../../../pkg.ts'
+
+/** Runtime seams. Production passes none; tests pass a stub `fetch`. */
+export interface CallbackDeps {
+	fetch?: typeof globalThis.fetch
+	/** Waits between heartbeats and polls. Resolves, without error, on abort. */
+	sleep?: (ms: number, signal: AbortSignal) => Promise<void>
+	keeper?: ListenerKeeper
+}
+
+/**
+ * Events the org's pull listener subscribes to: the five session-ending
+ * events (the first four carry the signed result; `session_expired` has no
+ * result) plus the lifecycle milestones an app developer checks while testing.
+ * High-volume diagnostics (`network_request_observed`, `provider_script_log`,
+ * `user_interaction_*`) are left out, so a forwarded session sends the app at
+ * most 11 requests instead of dozens.
+ */
+export const LISTENER_EVENTS = [
+	'verification_success',
+	'verification_rejected',
+	'verification_error',
+	'verification_cancelled',
+	'session_expired',
+	'session_pending',
+	'verification_client_opened',
+	'authenticated',
+	'verification_proofs_completed',
+	'verification_result_submitting',
+	'verification_result_submission_failed',
+] as const
+
+export type ListenerInfo = {
+	subscriptionId: string
+	created: boolean
+	/** When the lease lapses unless the heartbeat renews it. */
+	expiresAt: string
+}
+
+export type CallbackEvent
+	= IOperationResponse<'ListCallbackEvents'>['items'][number]
+
+/**
+ * A client that presents the organization's API key. With a `signal`, every
+ * request aborts when it does.
+ */
+export function orgClient(
+	secret: string,
+	deps: CallbackDeps = {},
+	signal?: AbortSignal,
+) {
+	const base = deps.fetch || globalThis.fetch
+	return new ReclaimClient({
+		baseUrl: apiUrl(),
+		token: secret,
+		fetch: signal
+			? (input, init) => base(input, { ...init, signal })
+			: deps.fetch,
+		headers: { 'User-Agent': `${NAME}/${VERSION}` },
+	})
+}
+
+/** Renewal interval. The backend lease lasts 90 seconds. */
+const HEARTBEAT_MS = 30_000
+/** Upper bound for releasing all listeners at shutdown. */
+const RELEASE_TIMEOUT_MS = 3_000
+
+type Entry = {
+	/** Aborts with the entry, so a renew in flight cannot outlive a release. */
+	client: ReclaimClient
+	/** Not bound to the abort signal: it must still send the release. */
+	releaseClient: ReclaimClient
+	abort: AbortController
+	/** The first lease; concurrent callers share it. */
+	ready: Promise<ListenerInfo>
+	settled: boolean
+}
+
+/**
+ * Keeps each org's pull listener alive while this MCP process runs. Creating
+ * the subscription is the heartbeat: it renews a lease, and the listener
+ * stops receiving events when the lease lapses. {@link release} ends the
+ * lease at shutdown.
+ */
+export class ListenerKeeper {
+	#entries = new Map<string, Entry>()
+
+	/** Creates or renews the listener and starts its heartbeat (once). */
+	async ensure(secret: string, deps: CallbackDeps = {}): Promise<ListenerInfo> {
+		const existing = this.#entries.get(secret)
+		if(existing) {
+			const wasSettled = existing.settled
+			const first = await existing.ready
+			// Callers that arrived during creation share its result.
+			return wasSettled ? await renew(existing.client) : first
+		}
+
+		const abort = new AbortController()
+		const client = orgClient(secret, deps, abort.signal)
+		const sleep = deps.sleep || sleepFor
+		const entry: Entry = {
+			client,
+			releaseClient: orgClient(secret, deps),
+			abort,
+			settled: false,
+			ready: renew(client).then((info) => {
+				entry.settled = true
+				void this.#beat(entry, sleep)
+				return info
+			}, (err: unknown) => {
+				if(this.#entries.get(secret) === entry) {
+					this.#entries.delete(secret)
+				}
+
+				abort.abort()
+				throw err
+			}),
+		}
+		this.#entries.set(secret, entry)
+		return await entry.ready
+	}
+
+	/** Ends every lease and stops the heartbeats, within a short timeout. */
+	async release() {
+		const entries = [...this.#entries.values()]
+		this.#entries.clear()
+		const timeout = AbortSignal.timeout(RELEASE_TIMEOUT_MS)
+		await Promise.all(entries.map(async({ releaseClient, abort }) => {
+			abort.abort()
+			try {
+				await Promise.race([
+					releaseClient.call('ReleaseCallbackListener', {}),
+					new Promise((_, reject) => {
+						timeout.addEventListener('abort', () => reject(timeout.reason))
+					}),
+				])
+			} catch(err) {
+				LOGGER.warn({ err }, 'releasing the callback listener failed')
+			}
+		}))
+	}
+
+	async #beat(entry: Entry, sleep: NonNullable<CallbackDeps['sleep']>) {
+		const { signal } = entry.abort
+		while(!signal.aborted) {
+			await sleep(HEARTBEAT_MS, signal)
+			if(signal.aborted) {
+				return
+			}
+
+			try {
+				await renew(entry.client)
+			} catch(err) {
+				if(signal.aborted) {
+					return
+				}
+
+				LOGGER.warn({ err }, 'callback listener heartbeat failed; retrying')
+			}
+		}
+	}
+}
+
+const defaultKeeper = new ListenerKeeper()
+
+/** Releases every listener this process keeps alive. Runs at MCP shutdown. */
+export function releaseAllListeners() {
+	return defaultKeeper.release()
+}
+
+/**
+ * Create the org's pull listener and keep it alive until shutdown. An org has
+ * one, so a second call returns the existing subscription (HTTP 200).
+ */
+export function ensureListener(secret: string, deps: CallbackDeps = {}) {
+	return (deps.keeper || defaultKeeper).ensure(secret, deps)
+}
+
+async function renew(client: ReclaimClient): Promise<ListenerInfo> {
+	const { data, response } = await client.call('CreateCallbackSubscription', {
+		body: { deliveryMode: 'pull', events: [...LISTENER_EVENTS] },
+	})
+	assert(
+		data.listenerExpiresAt,
+		badGateway('Builder returned a pull listener without a lease.'),
+	)
+	return {
+		subscriptionId: data.id,
+		created: response.status === 201,
+		expiresAt: data.listenerExpiresAt,
+	}
+}
+
+export async function sleepFor(ms: number, signal: AbortSignal) {
+	await delay(ms, undefined, { signal }).catch(() => undefined)
+}

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

@@ -1,2 +1,4 @@
 // Barrel for the verification tool group (result retrieval + decryption).
 export { buildVerificationTools } from './build.ts'
+export { stopAllForwarders } from './proxy-callback-events.ts'
+export { releaseAllListeners } from './callback-listener.ts'