@reclaimprotocol/agent 0.1.4 → 0.1.6

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

@@ -2,160 +2,24 @@ import { listTabs } from '../../../cdp/tabs.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { AttachState } from './attach.ts'
 
-export function browserTools(attachRef: {
+/** The one browser tool that isn't session-bound: enumerate tabs so the caller
+ *  can pick one to `start_capture` on. Navigate/eval/wait are the shared
+ *  authoring tools (keyed by captureId — see `shared.ts`). */
+export function listTabsTool(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' }
-			},
-		),
-	]
+}): RegisteredTool {
+	return defineTool<Record<string, never>>(
+		{
+			name: 'list_tabs',
+			description: 'List open Chrome tabs.',
+			inputSchema: { type: 'object', properties: {} },
+		},
+		async() => {
+			if(!attachRef.current) {
+				throw new Error('Not attached. Call attach_chrome first.')
+			}
+
+			return { tabs: await listTabs(attachRef.current.port) }
+		},
+	)
 }

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

@@ -1,36 +1,37 @@
+/**
+ * `find_requests_containing` — search captured responses for any encoding of a
+ * value and rank the requests that return it. Authored once as a plain
+ * {@link RegisteredTool}; the MCP and cloud loop each pass their own backend
+ * resolver (see authoring/tools.ts / shared.ts). Server-side: response bodies
+ * stay here, only metadata + a short snippet leave.
+ */
+import {
+	objectSchema,
+	publicRequest,
+	type ResolveBackend,
+} from '../../../authoring/util.ts'
 import { normalizeCandidates } from '../../../provider/normalize.ts'
-import { defineTool, type RegisteredTool } from '../../server.ts'
-import type { CaptureStore } from './capture.ts'
+import { defineTool, type RegisteredTool } from '../../../tools/registry.ts'
 
-export function findTool(captures: CaptureStore): RegisteredTool {
-	return defineTool<{ captureId: string, value: string, limit?: number }>(
+export function findTool(resolveBackend: ResolveBackend): RegisteredTool {
+	return defineTool<Record<string, unknown>>(
 		{
 			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'],
-			},
+				'Search captured responses for any encoding of `value` (raw, '
+				+ 'URL/JSON/HTML-escaped, …). Returns a ranked candidate list with '
+				+ 'the matched variant, score, and a short snippet — used to locate '
+				+ 'the request that returns a target. Server-side; bodies stay here.',
+			inputSchema: objectSchema(
+				{ value: { type: 'string' }, limit: { type: 'number' } },
+				['value'],
+			),
 		},
-		async({ captureId, value, limit }) => {
-			const session = captures.sessions.get(captureId)
-			if(!session) {
-				throw new Error(`no capture ${captureId}`)
-			}
-
-			const variants = normalizeCandidates(value)
-
+		async(args) => {
+			const backend = resolveBackend(args)
+			const variants = normalizeCandidates(String(args.value))
 			const ranked = []
-			for(const r of session.requests.values()) {
+			for(const r of backend.capture.requests.values()) {
 				if(!r.responseBody) {
 					continue
 				}
@@ -50,16 +51,11 @@ export function findTool(captures: CaptureStore): RegisteredTool {
 					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)))
+				// 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,
+					...publicRequest(r),
 					matchedVariant: hit.variant,
 					snippet: hit.snippet,
 					score,
@@ -67,7 +63,8 @@ export function findTool(captures: CaptureStore): RegisteredTool {
 			}
 
 			ranked.sort((a, b) => b.score - a.score)
-			return { candidates: ranked.slice(0, limit ?? 10) }
+			const limit = Number(args.limit) || 10
+			return { candidates: ranked.slice(0, limit) }
 		},
 	)
 }

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

@@ -3,13 +3,10 @@ import { join } from 'node:path'
 import { agentTraceEnabled } from '../../../consts.ts'
 import { reclaimHomeDirPath } from '../../../paths.ts'
 import {
-	runAttestorProof,
+	type ProofResult,
 	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')
@@ -98,170 +95,100 @@ function isLikelyByteArray(v: unknown[]): boolean {
 	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: {
-					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
-				}
-			}
+/**
+ * The MCP's rich `run_proof` view: persist the full claim to disk, return
+ * identifier + extractedParameters + a prettified claim (request dropped, byte
+ * arrays as base64) + trimmed logs, and — under `RECLAIM_AGENT_TRACE=1` — a
+ * forensic run dump. This is the developer-facing shape; the cloud backend
+ * projects the same {@link ProofResult} to a lean summary instead.
+ */
+export function shapeRichProofResult(
+	result: ProofResult,
+	opts: { provider: unknown, hasSecrets: boolean, attestorUrl?: string },
+): Record<string, unknown> {
+	// 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
-			}
+	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(result.owner !== undefined) {
+		out.owner = result.owner
+	}
 
-			if(claimPath !== undefined) {
-				out.claimPath = claimPath
-			}
+	if(claimPath !== undefined) {
+		out.claimPath = claimPath
+	}
 
-			if(result.proof !== undefined && result.proof !== null) {
-				out.claim = prettifyClaim(result.proof)
-			}
+	if(result.proof !== undefined && result.proof !== null) {
+		out.claim = prettifyClaim(result.proof)
+	}
 
-			if(result.error !== undefined) {
-				out.error = result.error
-			}
+	if(result.error !== undefined) {
+		out.error = result.error
+	}
 
-			if(result.errorKind !== undefined) {
-				out.errorKind = result.errorKind
-			}
+	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
-				}
-			}
+	// 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
-			}
+	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(agentTraceEnabled()) {
-				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
-				}
-			}
+	// 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(agentTraceEnabled()) {
+		const runLogPath = writeProofRunDump({
+			provider: opts.provider,
+			hasSecretParamsRef: opts.hasSecrets,
+			attestorUrl: opts.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
-		},
-	)
+	return out
 }