@reclaimprotocol/agent 0.1.0-dev.1

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

@@ -0,0 +1,202 @@
+import { type CaptureSession, startCapture } from '../../../cdp/capture.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { AttachState } from './attach.ts'
+
+export interface CaptureStore {
+	sessions: Map<string, CaptureSession>
+	activeTab?: string
+}
+
+export function captureTools(
+	attachRef: { current?: AttachState },
+	captures: CaptureStore,
+): RegisteredTool[] {
+	const requireAttached = (): AttachState => {
+		if(!attachRef.current) {
+			throw new Error('Not attached. Call attach_chrome first.')
+		}
+
+		return attachRef.current
+	}
+
+	const startTool = defineTool<{ tabId: string }>(
+		{
+			name: 'start_capture',
+			description:
+				'Begin recording network requests on the specified tab. ' +
+				'Returns a captureId.',
+			inputSchema: {
+				type: 'object',
+				properties: { tabId: { type: 'string' } },
+				required: ['tabId'],
+			},
+		},
+		async({ tabId }) => {
+			const attached = requireAttached()
+			const tabClient = await attached.handles.attachToTab(tabId)
+			const session = await startCapture(tabClient)
+			captures.sessions.set(session.captureId, session)
+			captures.activeTab = tabId
+			return { captureId: session.captureId }
+		},
+	)
+
+	const stopTool = defineTool<{ captureId: string }>(
+		{
+			name: 'stop_capture',
+			description:
+				'Stop recording on the given capture. ' +
+				'Captured data remains queryable until reset_session.',
+			inputSchema: {
+				type: 'object',
+				properties: { captureId: { type: 'string' } },
+				required: ['captureId'],
+			},
+		},
+		async({ captureId }) => {
+			const session = captures.sessions.get(captureId)
+			if(!session) {
+				throw new Error(`no capture ${captureId}`)
+			}
+
+			await session.stop()
+			return { stopped: true, requestCount: session.requests.size }
+		},
+	)
+
+	const listTool = defineTool<{
+		captureId: string
+		filter?: {
+			method?: string
+			urlGlob?: string
+			statusMin?: number
+			statusMax?: number
+			contentType?: string
+			graphqlOp?: string
+		}
+	}>(
+		{
+			name: 'list_requests',
+			description:
+				'List metadata for captured requests. ' +
+				'Filter by method, URL glob, status, content-type, ' +
+				'or graphqlOp. Returns only metadata, never bodies — ' +
+				'use get_request for those.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					captureId: { type: 'string' },
+					filter: {
+						type: 'object',
+						properties: {
+							method: { type: 'string' },
+							urlGlob: { type: 'string' },
+							statusMin: { type: 'number' },
+							statusMax: { type: 'number' },
+							contentType: { type: 'string' },
+							graphqlOp: { type: 'string' },
+						},
+					},
+				},
+				required: ['captureId'],
+			},
+		},
+		async({ captureId, filter }) => {
+			const session = captures.sessions.get(captureId)
+			if(!session) {
+				throw new Error(`no capture ${captureId}`)
+			}
+
+			const out = []
+			for(const r of session.requests.values()) {
+				if(filter?.method && r.method !== filter.method.toUpperCase()) {
+					continue
+				}
+
+				if(filter?.urlGlob && !globMatch(filter.urlGlob, r.url)) {
+					continue
+				}
+
+				if(filter?.statusMin !== undefined && r.status < filter.statusMin) {
+					continue
+				}
+
+				if(filter?.statusMax !== undefined && r.status > filter.statusMax) {
+					continue
+				}
+
+				if(
+					filter?.contentType &&
+					!r.contentType.includes(filter.contentType)
+				) {
+					continue
+				}
+
+				if(filter?.graphqlOp && r.graphqlOp !== filter.graphqlOp) {
+					continue
+				}
+
+				const item: Record<string, unknown> = {
+					requestId: r.requestId,
+					method: r.method,
+					url: r.url,
+					status: r.status,
+					contentType: r.contentType,
+					size: r.size,
+				}
+				if(r.graphqlOp !== undefined) {
+					item.graphqlOp = r.graphqlOp
+				}
+
+				out.push(item)
+			}
+
+			return { requests: out }
+		},
+	)
+
+	const getTool = defineTool<{ captureId: string, requestId: string }>(
+		{
+			name: 'get_request',
+			description:
+				'Return full headers + bodies for a specific captured request.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					captureId: { type: 'string' },
+					requestId: { type: 'string' },
+				},
+				required: ['captureId', 'requestId'],
+			},
+		},
+		async({ captureId, requestId }) => {
+			const session = captures.sessions.get(captureId)
+			if(!session) {
+				throw new Error(`no capture ${captureId}`)
+			}
+
+			const r = session.requests.get(requestId)
+			if(!r) {
+				throw new Error(`no request ${requestId} in capture ${captureId}`)
+			}
+
+			const body = session.bodies.get(requestId)
+			if(!body.available) {
+				return { ...r, bodyAvailable: false, reason: body.reason }
+			}
+
+			return { ...r, responseBody: body.body, bodyAvailable: true }
+		},
+	)
+
+	return [startTool, stopTool, listTool, getTool]
+}
+
+function globMatch(pattern: string, str: string): boolean {
+	const re = new RegExp(
+		'^' +
+			pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') +
+			'$',
+	)
+	return re.test(str)
+}

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

@@ -0,0 +1,161 @@
+import { listTabs } from '../../../cdp/tabs.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { AttachState } from './attach.ts'
+
+export function browserTools(attachRef: {
+	current?: AttachState
+}): RegisteredTool[] {
+	const requireAttached = (): AttachState => {
+		if(!attachRef.current) {
+			throw new Error('Not attached. Call attach_chrome first.')
+		}
+
+		return attachRef.current
+	}
+
+	return [
+		defineTool<Record<string, never>>(
+			{
+				name: 'list_tabs',
+				description: 'List open Chrome tabs.',
+				inputSchema: { type: 'object', properties: {} },
+			},
+			async() => {
+				const attached = requireAttached()
+				return { tabs: await listTabs(attached.port) }
+			},
+		),
+		defineTool<{ tabId: string, expression: string }>(
+			{
+				name: 'eval_in_page',
+				description:
+					'Run a JS expression in a tab via Runtime.evaluate ' +
+					'and return the result. ' +
+					'Useful for reading visible values from the DOM.',
+				inputSchema: {
+					type: 'object',
+					properties: {
+						tabId: { type: 'string' },
+						expression: { type: 'string' },
+					},
+					required: ['tabId', 'expression'],
+				},
+			},
+			async({ tabId, expression }) => {
+				const attached = requireAttached()
+				const { Runtime } = await attached.handles.attachToTab(tabId)
+				const result = await Runtime.evaluate({
+					expression,
+					returnByValue: true,
+				})
+				if(result.exceptionDetails) {
+					return { error: result.exceptionDetails.text }
+				}
+
+				return { value: result.result.value }
+			},
+		),
+		defineTool<{ tabId: string, url: string, timeoutMs?: number }>(
+			{
+				name: 'navigate',
+				description:
+					'Navigate a tab to a URL via Page.navigate, ' +
+					'waiting for the load event. ' +
+					'Use this to drive the browser yourself ' +
+					'instead of asking the developer to navigate. ' +
+					'Returns the final URL after navigation ' +
+					'(which may differ from the requested URL due to redirects).',
+				inputSchema: {
+					type: 'object',
+					properties: {
+						tabId: { type: 'string' },
+						url: { type: 'string' },
+						timeoutMs: { type: 'number' },
+					},
+					required: ['tabId', 'url'],
+				},
+			},
+			async({ tabId, url, timeoutMs }) => {
+				const attached = requireAttached()
+				const { Page, Runtime } = await attached.handles.attachToTab(tabId)
+
+				await Page.enable()
+				const loadPromise = new Promise<void>((resolve) => {
+					Page.loadEventFired(() => resolve())
+				})
+				const nav = await Page.navigate({ url })
+				if(nav.errorText) {
+					return { ok: false, error: nav.errorText }
+				}
+
+				const t = timeoutMs ?? 30_000
+				const raced = await Promise.race([
+					loadPromise.then(() => 'loaded' as const),
+					new Promise<'timeout'>(
+						(resolve) => setTimeout(() => resolve('timeout'), t),
+					),
+				])
+				const final = await Runtime.evaluate({
+					expression: 'location.href',
+					returnByValue: true,
+				})
+				return {
+					ok: true,
+					loadStatus: raced,
+					finalUrl: final.result.value,
+				}
+			},
+		),
+		defineTool<{
+			tabId: string
+			expression: string
+			timeoutMs?: number
+			pollMs?: number
+		}>(
+			{
+				name: 'wait_for_page',
+				description:
+					'Poll a JS expression in a tab until it ' +
+					'returns truthy (or timeout). ' +
+					'Use this for steps that require the ' +
+					'developer to do something in the browser — ' +
+					'most commonly waiting for them to finish logging in. ' +
+					'Pass an expression that ' +
+					'evaluates true once the desired state is reached, e.g. ' +
+					'`!!document.querySelector' +
+					'(\'summary[aria-label*="View profile"]\')`' +
+					' for GitHub post-login.',
+				inputSchema: {
+					type: 'object',
+					properties: {
+						tabId: { type: 'string' },
+						expression: { type: 'string' },
+						timeoutMs: { type: 'number' },
+						pollMs: { type: 'number' },
+					},
+					required: ['tabId', 'expression'],
+				},
+			},
+			async({ tabId, expression, timeoutMs, pollMs }) => {
+				const attached = requireAttached()
+				const { Runtime } = await attached.handles.attachToTab(tabId)
+				const deadline = Date.now() + (timeoutMs ?? 120_000)
+				const interval = pollMs ?? 1000
+				while(Date.now() < deadline) {
+					const r = await Runtime.evaluate({ expression, returnByValue: true })
+					if(r.exceptionDetails) {
+						return { matched: false, error: r.exceptionDetails.text }
+					}
+
+					if(r.result.value) {
+						return { matched: true, value: r.result.value }
+					}
+
+					await new Promise((resolve) => setTimeout(resolve, interval))
+				}
+
+				return { matched: false, reason: 'timeout' }
+			},
+		),
+	]
+}

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

@@ -0,0 +1,73 @@
+import { normalizeCandidates } from '../../../provider/normalize.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { CaptureStore } from './capture.ts'
+
+export function findTool(captures: CaptureStore): RegisteredTool {
+	return defineTool<{ captureId: string, value: string, limit?: number }>(
+		{
+			name: 'find_requests_containing',
+			description:
+				'Search captured responses for any encoding of `value`.' +
+				'Returns a ranked candidate list ' +
+				'with the JSON path (when applicable), score, and a short snippet.' +
+				'Server-side; bodies stay here.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					captureId: { type: 'string' },
+					value: { type: 'string' },
+					limit: { type: 'number' },
+				},
+				required: ['captureId', 'value'],
+			},
+		},
+		async({ captureId, value, limit }) => {
+			const session = captures.sessions.get(captureId)
+			if(!session) {
+				throw new Error(`no capture ${captureId}`)
+			}
+
+			const variants = normalizeCandidates(value)
+
+			const ranked = []
+			for(const r of session.requests.values()) {
+				if(!r.responseBody) {
+					continue
+				}
+
+				let hit: { snippet: string, variant: string } | undefined
+				for(const v of variants) {
+					const idx = r.responseBody.indexOf(v)
+					if(idx >= 0) {
+						const start = Math.max(0, idx - 40)
+						const end = Math.min(r.responseBody.length, idx + v.length + 40)
+						hit = { snippet: r.responseBody.slice(start, end), variant: v }
+						break
+					}
+				}
+
+				if(!hit) {
+					continue
+				}
+
+				// Score: prefer JSON responses + smaller bodies (likely API endpoints).
+				const score =
+					(r.contentType.includes('json') ? 10 : 0) +
+					Math.max(0, 5 - Math.log10(Math.max(r.size, 1)))
+				ranked.push({
+					requestId: r.requestId,
+					url: r.url,
+					method: r.method,
+					status: r.status,
+					contentType: r.contentType,
+					matchedVariant: hit.variant,
+					snippet: hit.snippet,
+					score,
+				})
+			}
+
+			ranked.sort((a, b) => b.score - a.score)
+			return { candidates: ranked.slice(0, limit ?? 10) }
+		},
+	)
+}

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

@@ -0,0 +1,272 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { reclaimHomeDirPath } from '../../../paths.ts'
+import {
+	runAttestorProof,
+	tailLogs,
+	warnsAndErrors,
+} from '../../../proof/attestor.ts'
+import type { ReclaimProvider } from '../../../provider/schema.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { SecretStore } from './propose.ts'
+
+function claimsDir(): string {
+	return join(reclaimHomeDirPath(), 'claims')
+}
+
+function proofRunsDir(): string {
+	return join(reclaimHomeDirPath(), 'proof-runs')
+}
+
+/** Persist everything we know about this proof attempt — input provider,
+ *  sentParams the SDK saw, full captured logs, and the final result — to
+ *  a file the dev can `cat` directly. This is the source of truth when
+ *  the LLM's summary disagrees with reality. */
+function writeProofRunDump(payload: {
+	provider: unknown
+	hasSecretParamsRef: boolean
+	attestorUrl?: string
+	result: Record<string, unknown>
+}): string | undefined {
+	try {
+		mkdirSync(proofRunsDir(), { recursive: true })
+		const path = join(proofRunsDir(), `${Date.now()}.json`)
+		writeFileSync(path, JSON.stringify(payload, null, 2), 'utf8')
+		return path
+	} catch{
+		// Persistence is best-effort; never fail the proof for it.
+		return undefined
+	}
+}
+
+/**
+ * Walk a claim object for display:
+ *   - drop any `request` field at any depth (it's huge and only useful
+ *     for low-level debugging — the on-disk claim still has it)
+ *   - convert byte-like values (Uint8Array, or arrays where every entry
+ *     is a number in [0,255]) to base64 strings so they render as
+ *     readable text instead of `{"0":12,"1":34,...}`
+ *
+ * The on-disk file at claimPath is the raw, unprettified claim — this
+ * function only affects what we return in the MCP tool response.
+ */
+function prettifyClaim(value: unknown): unknown {
+	if(value === null || value === undefined) {
+		return value
+	}
+
+	if(value instanceof Uint8Array) {
+		return Buffer.from(value).toString('base64')
+	}
+
+	if(Array.isArray(value)) {
+		if(isLikelyByteArray(value)) {
+			return Buffer.from(value as number[]).toString('base64')
+		}
+
+		return value.map(prettifyClaim)
+	}
+
+	if(typeof value === 'object') {
+		const out: Record<string, unknown> = {}
+		for(const [k, v] of Object.entries(value as Record<string, unknown>)) {
+			if(k === 'request') {
+				continue
+			}
+
+			out[k] = prettifyClaim(v)
+		}
+
+		return out
+	}
+
+	return value
+}
+
+function isLikelyByteArray(v: unknown[]): boolean {
+	if(v.length === 0) {
+		return false
+	}
+
+	for(const x of v) {
+		if(typeof x !== 'number' || !Number.isInteger(x) || x < 0 || x > 255) {
+			return false
+		}
+	}
+
+	return true
+}
+
+export function proofTool(secrets: SecretStore): RegisteredTool {
+	return defineTool<{
+		provider: unknown
+		secretParamsRef?: string
+		attestorUrl?: string
+		ownerAddress?: string
+	}>(
+		{
+			name: 'run_proof',
+			description:
+				'Run a full zkTLS proof through the Reclaim attestor SDK. ' +
+				'Use only after replay_request ' +
+				'returns matchesOriginal=true — attestor calls are expensive. ' +
+				'Writes the full claim to ' +
+				'~/.reclaim/claims/<timestamp>.json and ' +
+				'returns identifier + extractedParameters + ' +
+				'claimPath + a prettified `claim` field ' +
+				'(request dropped, byte arrays as base64) suitable ' +
+				'for displaying directly to the dev. ' +
+				'When the MCP server is started with ' +
+				'`RECLAIM_AGENT_TRACE=1`, ALSO writes ' +
+				'a per-call diagnostic dump (input provider, ' +
+				'sentParams the SDK saw post-substitution, ' +
+				'FULL attestor log stream, result) to ' +
+				'~/.reclaim/proof-runs/<timestamp>.json and ' +
+				'returns the path as `runLogPath`. ' +
+				'`attestorUrl` overrides the default attestor URL only when the dev ' +
+				'supplies a specific ' +
+				'alternative — do NOT invent backup URLs ' +
+				'(there is one live public attestor right now; ' +
+				'surface real errors to the dev instead of guessing). ' +
+				'`ownerAddress` (the credential to sign with) is REQUIRED — ' +
+				'call resolve_owner_key first to obtain it, then pass it here. ' +
+				'errorKind="missing-owner-key" means that address has no known ' +
+				'private key; re-run resolve_owner_key or issue/import a credential.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					// `type: 'object'` is required so MCP clients (the LLM)
+					// serialize the value as an object, not a JSON-stringified
+					// string. `properties: {}` is required so zod-from-json-schema
+					// compiles to a passthrough instead of strict-strip — leaving
+					// it off makes the server receive `{}`.
+					provider: { type: 'object', properties: {} },
+					secretParamsRef: { type: 'string' },
+					attestorUrl: { type: 'string' },
+					ownerAddress: {
+						type: 'string',
+						pattern: '^0x[0-9a-fA-F]{40}$',
+						description:
+							'ETH address of the credential to sign the claim with. ' +
+							'Get it from resolve_owner_key first. The private key is ' +
+							'resolved locally (cache / env / .env) — never passed here.',
+					},
+				},
+				required: ['provider', 'ownerAddress'],
+			},
+		},
+		async({ provider, secretParamsRef, attestorUrl, ownerAddress }) => {
+			let resolved: Record<string, string> = {}
+			if(secretParamsRef !== undefined) {
+				const r = secrets.resolve(secretParamsRef)
+				if(!r) {
+					throw new Error(
+						`unknown secretParamsRef "${secretParamsRef}" — ` +
+						'the MCP server has restarted or reset_session was called. ' +
+							'Re-run propose_provider to mint a fresh ref.',
+					)
+				}
+
+				resolved = r
+			}
+
+			const result = await runAttestorProof(
+				provider as ReclaimProvider,
+				resolved,
+				attestorUrl,
+				ownerAddress,
+			)
+
+			// Persist the full claim to disk for the dev to inspect/share.
+			let claimPath: string | undefined
+			if(result.proof !== undefined && result.proof !== null) {
+				try {
+					mkdirSync(claimsDir(), { recursive: true })
+					claimPath = join(claimsDir(), `${Date.now()}.json`)
+					writeFileSync(
+						claimPath,
+						JSON.stringify(result.proof, null, 2),
+						'utf8',
+					)
+				} catch{
+					// Persistence is best-effort; don't fail the proof for it.
+					claimPath = undefined
+				}
+			}
+
+			const out: Record<string, unknown> = {
+				verified: result.verified,
+				extractedValue: result.extractedValue,
+				extractedParameters: result.extractedParameters,
+			}
+			if(result.identifier !== undefined) {
+				out.identifier = result.identifier
+			}
+
+			if(result.owner !== undefined) {
+				out.owner = result.owner
+			}
+
+			if(claimPath !== undefined) {
+				out.claimPath = claimPath
+			}
+
+			if(result.proof !== undefined && result.proof !== null) {
+				out.claim = prettifyClaim(result.proof)
+			}
+
+			if(result.error !== undefined) {
+				out.error = result.error
+			}
+
+			if(result.errorKind !== undefined) {
+				out.errorKind = result.errorKind
+			}
+
+			// Trim the LLM-visible logs — full stream goes to runLogPath.
+			if(result.attestorLogs !== undefined && result.attestorLogs.length > 0) {
+				out.attestorLogs = result.verified
+					? warnsAndErrors(result.attestorLogs)
+					: tailLogs(result.attestorLogs)
+				if((out.attestorLogs as unknown[]).length === 0) {
+					delete out.attestorLogs
+				}
+			}
+
+			if(result.sentParams !== undefined) {
+				out.sentParams = result.sentParams
+			}
+
+			// Persist a diagnostic dump for forensics — gated behind
+			// RECLAIM_AGENT_TRACE=1 (matches the attestor logger capture).
+			// Off by default since happy-path runs don't need it; turn on
+			// when investigating proof failures and the file at runLogPath
+			// will carry the input provider, sentParams, full attestor log
+			// stream, and result.
+			if(process.env['RECLAIM_AGENT_TRACE'] === '1') {
+				const runLogPath = writeProofRunDump({
+					provider,
+					hasSecretParamsRef: secretParamsRef !== undefined,
+					attestorUrl,
+					result: {
+						verified: result.verified,
+						error: result.error,
+						errorKind: result.errorKind,
+						extractedValue: result.extractedValue,
+						extractedParameters: result.extractedParameters,
+						identifier: result.identifier,
+						owner: result.owner,
+						sentParams: result.sentParams,
+						attestorLogs: result.attestorLogs,
+						claimPath,
+					},
+				})
+				if(runLogPath !== undefined) {
+					out.runLogPath = runLogPath
+				}
+			}
+
+			return out
+		},
+	)
+}