@reclaimprotocol/agent 0.1.5 → 0.1.7

package/src/authoring/tools.ts

@@ -0,0 +1,273 @@
+/**
+ * The authoring tools, authored ONCE — each directly with the shared
+ * `defineTool` primitive (no parallel tool spec). `authoringTools(resolve)`
+ * returns them as plain {@link RegisteredTool}s; the MCP (local Chrome +
+ * attestor) and the cloud loop (Popcorn + TEE) each pass their own backend
+ * resolver, so navigate/inspect/propose/replay/prove logic lives in one place.
+ *
+ * The resolver hands back the backend per call — the MCP keys it by `captureId`
+ * (multi-session), the cloud returns its one run backend. A host that needs
+ * extra input schema (the MCP's `captureId` + rich `run_proof` contract) MAPS
+ * these tools through `extendTool` at registration; the tools stay plain.
+ *
+ * Secret guarantee: captured cookie/auth values never enter a tool result. The
+ * draft (recipe + secrets) is held server-side; the model only sees an opaque
+ * `draftId` and the secret-free provider.
+ */
+import { findTool } from '../mcp/tools/agent/find.ts'
+import { proposeTool } from '../mcp/tools/agent/propose.ts'
+import { replayTool } from '../mcp/tools/agent/replay.ts'
+import type { CapturedRequest } from '../provider/schema.ts'
+import { defineTool, type RegisteredTool } from '../tools/registry.ts'
+import type { AuthoringBackend } from './backend.ts'
+import { objectSchema, publicRequest, type ResolveBackend } from './util.ts'
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
+
+interface RequestFilter {
+	method?: string
+	urlGlob?: string
+	statusMin?: number
+	statusMax?: number
+	contentType?: string
+	graphqlOp?: string
+}
+
+function matchesFilter(r: CapturedRequest, f: RequestFilter): boolean {
+	if(f.method && r.method !== f.method.toUpperCase()) {
+		return false
+	}
+
+	if(f.urlGlob && !globMatch(f.urlGlob, r.url)) {
+		return false
+	}
+
+	if(f.statusMin !== undefined && r.status < f.statusMin) {
+		return false
+	}
+
+	if(f.statusMax !== undefined && r.status > f.statusMax) {
+		return false
+	}
+
+	if(f.contentType && !r.contentType.includes(f.contentType)) {
+		return false
+	}
+
+	if(f.graphqlOp && r.graphqlOp !== f.graphqlOp) {
+		return false
+	}
+
+	return true
+}
+
+function globMatch(pattern: string, str: string): boolean {
+	const re = new RegExp(
+		'^'
+		+ pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+		+ '$',
+	)
+	return re.test(str)
+}
+
+interface EvalResult {
+	result?: { value?: unknown }
+	exceptionDetails?: { exception?: { description?: string }, text?: string }
+}
+
+async function evalInPage(
+	backend: AuthoringBackend,
+	expression: string,
+): Promise<{ value?: unknown, error?: string }> {
+	const res = (await backend.sendCdp('Runtime.evaluate', {
+		expression, returnByValue: true, awaitPromise: true,
+	})) as EvalResult
+	if(res.exceptionDetails) {
+		return {
+			error: res.exceptionDetails.exception?.description
+				?? res.exceptionDetails.text
+				?? 'evaluation error',
+		}
+	}
+
+	return { value: res.result?.value }
+}
+
+/**
+ * The authoring tools — navigate/inspect authored inline here; find/propose/
+ * replay live in their own files ({@link findTool}/{@link proposeTool}/
+ * {@link replayTool}) and are composed in below. Each is a plain `defineTool`
+ * primitive, so there is one canonical `RegisteredTool` per tool and no
+ * parallel tool shape. Every handler resolves its session backend via
+ * `resolveBackend(args)`: the cloud passes `() => backend` (one backend per
+ * run); the MCP passes an `args.captureId`-keyed resolver. Hosts that need
+ * extra input schema (the MCP's `captureId` session handle + the
+ * credential-aware `run_proof` contract) MAP these tools through `extendTool`
+ * (see mcp/tools/agent/shared.ts) — the tools themselves stay plain, and args
+ * parse loosely so the extra fields still reach the resolver/handler.
+ */
+export function authoringTools(
+	resolveBackend: ResolveBackend,
+): RegisteredTool[] {
+	return [
+		defineTool<Record<string, unknown>>(
+			{
+				name: 'navigate',
+				description: 'Navigate the browser tab to a URL, waiting for load.',
+				inputSchema: objectSchema(
+					{ url: { type: 'string' }, timeoutMs: { type: 'number' } },
+					['url'],
+				),
+			},
+			async(args) => {
+				const backend = resolveBackend(args)
+				const timeoutMs = Number(args.timeoutMs) || 30_000
+				await backend.sendCdp('Page.enable')
+				// Start listening BEFORE navigating so the load event isn't missed.
+				const load = backend.waitForEvent('Page.loadEventFired', timeoutMs)
+				const nav = (await backend.sendCdp(
+					'Page.navigate', { url: String(args.url) },
+				)) as { errorText?: string }
+				if(nav.errorText) {
+					return { ok: false, error: nav.errorText }
+				}
+
+				const loadStatus = await load
+				const final = await evalInPage(backend, 'location.href')
+				return { ok: true, loadStatus, finalUrl: final.value }
+			},
+		),
+		defineTool<Record<string, unknown>>(
+			{
+				name: 'eval_in_page',
+				description:
+					'Evaluate a JavaScript expression in the page and return its value '
+					+ '(use to read the displayed value, check login state, etc.).',
+				inputSchema: objectSchema(
+					{ expression: { type: 'string' } }, ['expression'],
+				),
+			},
+			(args) => evalInPage(resolveBackend(args), String(args.expression)),
+		),
+		defineTool<Record<string, unknown>>(
+			{
+				name: 'wait_for_page',
+				description:
+					'Poll a JavaScript expression until it is truthy or the timeout '
+					+ 'elapses (e.g. wait for the user to finish logging in).',
+				inputSchema: objectSchema(
+					{ expression: { type: 'string' }, timeoutMs: { type: 'number' } },
+					['expression'],
+				),
+			},
+			async(args) => {
+				const backend = resolveBackend(args)
+				const expr = String(args.expression)
+				const deadline = Date.now() + (Number(args.timeoutMs) || 180_000)
+				while(Date.now() < deadline) {
+					const { value } = await evalInPage(backend, expr)
+					if(value) {
+						return { ready: true }
+					}
+
+					await sleep(1000)
+				}
+
+				return { ready: false }
+			},
+		),
+		defineTool<Record<string, unknown>>(
+			{
+				name: 'get_cookies',
+				description:
+					'List the NAMES of cookies currently set for the page (values are '
+					+ 'NEVER returned). The most reliable, language- and DOM-independent '
+					+ 'login signal: after the user logs in, an auth/session cookie '
+					+ 'appears (e.g. session/sid/token/auth/jwt/_user/logged_in). '
+					+ 'Includes httpOnly cookies the page JS cannot see.',
+				inputSchema: objectSchema({}),
+			},
+			async(args) => {
+				const backend = resolveBackend(args)
+				const res = (await backend.sendCdp('Network.getCookies')) as {
+					cookies?: {
+						name: string
+						domain?: string
+						session?: boolean
+						httpOnly?: boolean
+					}[]
+				}
+				return (res.cookies ?? []).map((c) => ({
+					name: c.name,
+					...(c.domain ? { domain: c.domain } : {}),
+					...(c.session ? { session: true } : {}),
+					...(c.httpOnly ? { httpOnly: true } : {}),
+				}))
+			},
+		),
+		defineTool<Record<string, unknown>>(
+			{
+				name: 'list_requests',
+				description:
+					'List captured network requests (method/url/status/size), newest '
+					+ 'last. Optionally filter by method / urlGlob / status range / '
+					+ 'contentType / graphqlOp. Metadata only — secrets never included.',
+				inputSchema: objectSchema({
+					filter: {
+						type: 'object',
+						properties: {
+							method: { type: 'string' },
+							urlGlob: { type: 'string' },
+							statusMin: { type: 'number' },
+							statusMax: { type: 'number' },
+							contentType: { type: 'string' },
+							graphqlOp: { type: 'string' },
+						},
+					},
+				}),
+			},
+			async(args) => {
+				const backend = resolveBackend(args)
+				const filter = (args.filter ?? {}) as RequestFilter
+				return [...backend.capture.requests.values()]
+					.filter((r) => matchesFilter(r, filter))
+					.map(publicRequest)
+			},
+		),
+		findTool(resolveBackend),
+		proposeTool(resolveBackend),
+		replayTool(resolveBackend),
+		defineTool<Record<string, unknown>>(
+			{
+				name: 'run_proof',
+				description:
+					'Prove the drafted recipe (zkTLS). Only call after replay_request '
+					+ 'looks right. Returns the proof result.',
+				inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
+			},
+			// The backend shapes its own result: the cloud returns a lean,
+			// secret-free summary (and records the proven recipe for publish); the
+			// MCP persists the claim + returns the rich developer view. The MCP adds
+			// `ownerAddress`/`attestorUrl` to the schema via `extendTool`; the
+			// handler reads them from args (loose parse keeps them).
+			async(args) => {
+				const backend = resolveBackend(args)
+				const draft = backend.drafts.get(String(args.draftId))
+				if(!draft) {
+					throw new Error(`no draft ${String(args.draftId)}`)
+				}
+
+				const opts: { ownerAddress?: string, attestorUrl?: string } = {}
+				if(typeof args.ownerAddress === 'string') {
+					opts.ownerAddress = args.ownerAddress
+				}
+
+				if(typeof args.attestorUrl === 'string') {
+					opts.attestorUrl = args.attestorUrl
+				}
+
+				return backend.prove(draft, opts)
+			},
+		),
+	]
+}

package/src/authoring/util.ts

@@ -0,0 +1,42 @@
+/**
+ * Small shared helpers for the authoring tools (see tools.ts). Kept separate so
+ * the per-tool files (find.ts, propose.ts, replay.ts) and the inline tools in
+ * tools.ts share one copy without a circular import.
+ */
+import type { JSONSchema } from 'zod/v4/core'
+import type { CapturedRequest } from '../provider/schema.ts'
+import type { AuthoringBackend } from './backend.ts'
+
+/**
+ * Resolves the session backend for a tool call. The MCP keys it by
+ * `args.captureId` (multi-session); the cloud loop returns its one run backend.
+ * Each authoring tool closes over this so the same tool works for both hosts.
+ */
+export type ResolveBackend =
+	(args: Record<string, unknown>) => AuthoringBackend
+
+/** Build an `object` JSON Schema for a tool input — a small literal shortener,
+ *  not a tool abstraction. */
+export function objectSchema(
+	properties: Record<string, unknown>,
+	required?: string[],
+): JSONSchema.ObjectSchema {
+	return {
+		type: 'object',
+		properties,
+		...(required?.length ? { required } : {}),
+	} as unknown as JSONSchema.ObjectSchema
+}
+
+/** Secret-free projection of a captured request for tool output. */
+export function publicRequest(r: CapturedRequest) {
+	return {
+		requestId: r.requestId,
+		method: r.method,
+		url: r.url,
+		status: r.status,
+		contentType: r.contentType,
+		size: r.size,
+		...(r.graphqlOp ? { graphqlOp: r.graphqlOp } : {}),
+	}
+}

package/src/consts.ts

@@ -19,6 +19,7 @@ import { DEFAULT_BASE_URL } from '@reclaimprotocol/client'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL } from './old/client.ts'
+import { DEFAULT_SDK_API_URL } from './old/sdk-client.ts'
 
 // ---------------------------------------------------------------------------
 // Default / fallback literals (used only as env fallbacks).
@@ -30,9 +31,14 @@ export const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws'
 /** The devtools dashboard login page — fallback for `RECLAIM_OLD_LOGIN_URL`. */
 export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org'
 
-// Re-export the two non-env-fallback defaults so callers can keep importing
+// Re-export the non-env-fallback defaults so callers can keep importing
 // their URL defaults from a single place if they wish.
-export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL }
+export {
+	DEFAULT_BASE_URL,
+	DEFAULT_OLD_API_URL,
+	DEFAULT_OLD_LOGS_URL,
+	DEFAULT_SDK_API_URL,
+}
 
 // ---------------------------------------------------------------------------
 // Logging.
@@ -101,6 +107,13 @@ export function oldLogsUrl(): string {
 	return process.env.RECLAIM_OLD_LOGS_URL || DEFAULT_OLD_LOGS_URL
 }
 
+/** Public production SDK-backend base URL — the service the verification
+ *  SDK/attestor itself reads a provider's recipe from at runtime. A
+ *  DIFFERENT host from the old-devtools dashboard backend (`oldApiUrl`). */
+export function sdkApiUrl(): string {
+	return process.env.RECLAIM_SDK_API_URL || DEFAULT_SDK_API_URL
+}
+
 /** Builder backend base URL. Shared by mcp/start and the verification tool. */
 export function apiUrl(): string {
 	return process.env.RECLAIM_API_URL || DEFAULT_BASE_URL

package/src/mcp/server.ts

@@ -1,65 +1,16 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { JSONSchema } from 'zod/v4/core'
+import { type RegisteredTool } from '../tools/registry.ts'
 import { toZod } from './api/to-zod.ts'
 import { remapErrorAsResponse } from './remap_errors.ts'
 
-export interface ToolDefinition {
-	name: string
-	description: string
-	inputSchema: JSONSchema.ObjectSchema
-}
-
-/**
- * Passed to every tool handler alongside its parsed args. Long-running,
- * human-in-the-loop tools (e.g. a browser login flow that waits for someone
- * to sign in) should call `reportProgress` every few seconds while waiting.
- * MCP clients that attach a progress token to their request (most desktop
- * clients do) treat an incoming `notifications/progress` as proof the call
- * is still alive and reset their own request timeout instead of giving up —
- * the SDK's client-side default is 60s, far shorter than a human can be
- * expected to take to log in. A no-op when the client didn't request
- * progress tracking for this call.
- */
-export interface ToolContext {
-	reportProgress: (message: string) => Promise<void>
-}
-
-const NOOP_CONTEXT: ToolContext = { reportProgress: async() => {} }
-
-export interface RegisteredTool {
-	definition: ToolDefinition
-	/**
-	 * @param args Tool arguments
-	 * @param ctx Progress-reporting context (see {@link ToolContext}).
-	 *   Optional so direct/test callers can omit it.
-	 * @returns A JSON stringifiable content to be returned to the llm
-	 * @throws Any error encountered during tool execution will be caught and
-	 * returned as a response using
-	 * [remapErrorAsResponse](./src/mcp/remap_errors.ts).
-	 */
-	handler: (args: unknown, ctx?: ToolContext) => Promise<unknown>
-}
-
-/**
- * Define a tool with a single inputSchema (JSON Schema) used as the
- * source of truth. The handler receives args already parsed and
- * type-narrowed via a Zod schema derived from that same JSON Schema —
- * so the description sent to the MCP client and the validation applied
- * to inbound args cannot drift.
- */
-export function defineTool<TArgs>(
-	definition: ToolDefinition,
-	handler: (args: TArgs, ctx: ToolContext) => Promise<unknown>,
-): RegisteredTool {
-	const schema = toZod(definition.inputSchema)
-	return {
-		definition,
-		handler: async(raw, ctx = NOOP_CONTEXT) => {
-			const args = schema.parse(raw) as TArgs
-			return await handler(args, ctx)
-		},
-	}
-}
+// The tool primitive lives in `../tools/registry.ts` (SDK-free, so the cloud
+// loop can use it too). Re-exported here so the MCP-side tool files can keep
+// importing `defineTool`/`RegisteredTool` from the server module.
+export {
+	defineTool,
+	type RegisteredTool,
+	type ToolDefinition,
+} from '../tools/registry.ts'
 
 /**
  * Registers a list of RegisteredTool entries on a high-level McpServer.
@@ -74,31 +25,13 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 				description: tool.definition.description,
 				inputSchema: toZod(tool.definition.inputSchema),
 			},
-			async(args, extra) => {
+			async(args) => {
 				try {
-					const progressToken = extra?._meta?.progressToken
-					let progress = 0
-					const ctx: ToolContext = {
-						reportProgress: async(message) => {
-							if(progressToken === undefined) {
-								return
-							}
-
-							progress += 1
-							await extra.sendNotification({
-								method: 'notifications/progress',
-								params: { progressToken, progress, message },
-							}).catch(() => {})
-						},
-					}
-
 					return {
 						content: [
 							{
 								type: 'text' as const,
-								text: JSON.stringify(
-									await tool.handler(args, ctx), null, 2,
-								),
+								text: JSON.stringify(await tool.handler(args), null, 2),
 							},
 						],
 					}

package/src/mcp/start.ts

@@ -7,11 +7,13 @@ import {
 	apiUrl,
 	oldApiUrl,
 	oldLogsUrl,
+	sdkApiUrl,
 	useOldDevtools,
 } from '../consts.ts'
 import { ReclaimOldClient } from '../old/client.ts'
 import { resolveInitialIdentity } from '../old/identity.ts'
 import { OLD_MODE_INSTRUCTIONS } from '../old/instructions.ts'
+import { ReclaimSdkClient } from '../old/sdk-client.ts'
 import { buildOldBackendTools } from '../old/tools/build.ts'
 import { NAME, VERSION } from '../pkg.ts'
 import { registerTools } from './api/tools.ts'
@@ -53,9 +55,10 @@ export async function startMcpServer() {
 			logsBaseUrl: oldLogsUrl(),
 			identity: resolveInitialIdentity(),
 		})
+		const sdkClient = new ReclaimSdkClient({ baseUrl: sdkApiUrl() })
 
 		registerToolList(server, buildLocalCredentialTools())
-		registerToolList(server, buildOldBackendTools(oldClient))
+		registerToolList(server, buildOldBackendTools(oldClient, sdkClient))
 		if(agentToolsEnabled) {
 			// No builder client → no builder publish tool (old mode has its own).
 			registerToolList(server, buildAgentTools())

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

@@ -18,12 +18,12 @@ export function analyzeTool(captures: CaptureStore): RegisteredTool {
 			},
 		},
 		async({ captureId, requestId }) => {
-			const session = captures.sessions.get(captureId)
-			if(!session) {
+			const entry = captures.sessions.get(captureId)
+			if(!entry) {
 				throw new Error(`no capture ${captureId}`)
 			}
 
-			const r = session.requests.get(requestId)
+			const r = entry.session.requests.get(requestId)
 			if(!r) {
 				throw new Error(`no request ${requestId} in capture ${captureId}`)
 			}

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

@@ -4,8 +4,10 @@
  * `@modelcontextprotocol/sdk` `McpServer`. Folds the agent's tools
  * alongside the auto-generated API tools.
  *
- * Shared state — Chrome attach state, capture store, secret store — is
- * built once per server and threaded through every tool factory.
+ * Shared state — Chrome attach state + capture store — is built once per
+ * server and threaded through every tool factory. Per-capture drafts (and the
+ * secrets they hold) live inside each capture entry, so a capture IS the
+ * session for the shared authoring tools.
  */
 
 import type { ReclaimClient } from '@reclaimprotocol/client'
@@ -15,30 +17,21 @@ 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 { browserTools } from './eval.ts'
-import { findTool } from './find.ts'
+import { listTabsTool } from './eval.ts'
 import { howItWorksTool } from './how-it-works.ts'
-import { proofTool } from './proof.ts'
-import {
-	makeSecretStore,
-	proposeTool,
-	type SecretStore,
-} from './propose.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
-import { replayTool } from './replay.ts'
 import { sessionTools } from './session.ts'
+import { sharedAuthoringTools } from './shared.ts'
 
 export interface AgentState {
 	attach: { current?: AttachState, config: ConfigStore }
 	captures: CaptureStore
-	secrets: SecretStore
 }
 
 function buildAgentState(): AgentState {
 	return {
 		attach: { config: new ConfigStore() },
 		captures: { sessions: new Map() },
-		secrets: makeSecretStore(),
 	}
 }
 
@@ -57,24 +50,23 @@ export function buildAgentTools(
 	// client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
 	tools.push(howItWorksTool(!client))
 	tools.push(attachTool(state.attach))
+	tools.push(listTabsTool(state.attach))
 	for(const t of captureTools(state.attach, state.captures)) {
 		tools.push(t)
 	}
 
-	tools.push(findTool(state.captures))
-	for(const t of browserTools(state.attach)) {
+	for(const t of sessionTools(state.attach, state.captures)) {
 		tools.push(t)
 	}
 
-	for(const t of sessionTools(state.attach, state.captures, state.secrets)) {
+	tools.push(analyzeTool(state.captures))
+	// navigate / eval_in_page / wait_for_page / get_cookies / list_requests /
+	// find_requests_containing / propose_provider / replay_request / run_proof —
+	// shared with the cloud loop, bound to each capture's local backend.
+	for(const t of sharedAuthoringTools(state.captures)) {
 		tools.push(t)
 	}
 
-	tools.push(analyzeTool(state.captures))
-	tools.push(proposeTool(state.captures, state.secrets))
-	tools.push(replayTool(state.secrets))
-	tools.push(proofTool(state.secrets))
-
 	if(client) {
 		tools.push(createVersionFromCaptureTool(client))
 	}