@reclaimprotocol/agent 0.1.4 → 0.1.6

package/src/authoring/backend.ts

@@ -0,0 +1,98 @@
+/**
+ * Backend seam for the authoring tools. The tool LOGIC (drive the browser →
+ * capture → propose → replay → prove) is written once against this interface;
+ * each environment supplies a backend:
+ *   - local (MCP): a Chrome tab over CDP + the in-process attestor SDK.
+ *   - remote (cloud): the user's Popcorn browser over CDP + the TEE prover.
+ *
+ * One backend instance == one live session (a page + its capture). Multi
+ * session falls out of instancing: the MCP resolves a backend per tab/capture,
+ * the cloud one per run — so the shared tools never carry a session id and hold
+ * no cross-session state.
+ */
+import { randomUUID } from 'node:crypto'
+import type { CaptureSession } from '../cdp/capture-engine.ts'
+import type { Extraction } from '../provider/draft.ts'
+import type { ReclaimProvider, SecretParamRef } from '../provider/schema.ts'
+
+/** Secret request params (cookie/auth headers), materialized only for the
+ *  replay/prove call — never surfaced in tool output. */
+export interface SecretParams {
+	headers: Record<string, string>
+}
+
+/** A drafted recipe held server-side so the model only handles an opaque
+ *  `draftId` — the provider is secret-free but the captured secrets never enter
+ *  the transcript. Shared by propose → replay → run_proof. */
+export interface Draft {
+	provider: ReclaimProvider
+	secretRefs: SecretParamRef[]
+	/** Real secret header values (cookie/auth) for replay/prove — never returned
+	 *  to the model. */
+	secrets: Record<string, string>
+	/** The captured request this draft was proposed from. */
+	requestId: string
+	/** One entry per extracted value (value + its redaction), so replay can
+	 *  validate each against its own selector. */
+	extractions: Extraction[]
+}
+
+/** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id. */
+export interface DraftStore {
+	put(draft: Draft): string
+	get(id: string): Draft | undefined
+}
+
+export function makeDraftStore(): DraftStore {
+	const map = new Map<string, Draft>()
+	return {
+		put: (draft) => {
+			const id = `draft_${randomUUID()}`
+			map.set(id, draft)
+			return id
+		},
+		get: (id) => map.get(id),
+	}
+}
+
+/** Options for a proof run. `ownerAddress` selects the local signing credential
+ *  and `attestorUrl` overrides the attestor endpoint (both MCP-only); the
+ *  remote TEE backend ignores them (it signs in-enclave, own attestor). */
+export interface ProveOptions {
+	ownerAddress?: string
+	attestorUrl?: string
+}
+
+/**
+ * Everything the shared authoring tools need from one live session. Browser ops
+ * go through `sendCdp` (+ `waitForEvent` for load-style waits); capture reads
+ * use `capture`; proof/replay are whole operations because they genuinely
+ * differ (local attestor + live re-fetch vs remote TEE) — each backend shapes
+ * its own result, passed straight through as the tool's output.
+ */
+export interface AuthoringBackend {
+	/** Send a raw CDP command scoped to this session's page. */
+	sendCdp(method: string, params?: Record<string, unknown>): Promise<unknown>
+	/** Resolve once `method` (a CDP event) fires on this session's page, or
+	 *  after `timeoutMs`. Used for `Page.loadEventFired`-style waits. */
+	waitForEvent(method: string, timeoutMs: number): Promise<'fired' | 'timeout'>
+	/** This session's captured requests (the shared capture engine). */
+	readonly capture: CaptureSession
+	/** This session's drafts (propose → replay/run_proof). */
+	readonly drafts: DraftStore
+	/** Prove a drafted recipe. Local: attestor SDK (rich claim view). Remote: TEE
+	 *  `/reclaim/prove` (lean, secret-free summary). Returns the environment's
+	 *  display shape. A backend may record the proven recipe internally (e.g.
+	 *  the cloud publish step) — that side effect is the backend's, not ours. */
+	prove(draft: Draft, opts?: ProveOptions): Promise<unknown>
+	/**
+	 * Validate/replay a drafted recipe before proving. With `withoutSecrets` it
+	 * is the AUTH-BOUND check: re-issue the request stripped of the captured
+	 * secrets (local: a Node re-fetch without them; remote: an anonymous `fetch`
+	 * in the Popcorn page, `credentials: 'omit'`) and report whether the values
+	 * are STILL extractable — i.e. the endpoint is public. Without it, validate
+	 * extraction for the authenticated request. The shape is environment-specific
+	 * and passed straight through as the tool's result.
+	 */
+	replay(draft: Draft, opts?: { withoutSecrets?: boolean }): Promise<unknown>
+}

package/src/authoring/index.ts

@@ -0,0 +1,20 @@
+// Shared authoring tools, backend-injectable. Consumed by the MCP server
+// (local Chrome + attestor backend) and the cloud loop (Popcorn + TEE backend).
+export type {
+	AuthoringBackend,
+	Draft,
+	DraftStore,
+	ProveOptions,
+	SecretParams,
+} from './backend.ts'
+export { makeDraftStore } from './backend.ts'
+export { authoringTools } from './tools.ts'
+// The shared tool primitive — re-exported so consumers (the cloud loop) get the
+// RegisteredTool type/`defineTool`/`extendTool` without importing the MCP
+// subsystem.
+export {
+	defineTool,
+	extendTool,
+	type RegisteredTool,
+	type ToolDefinition,
+} from '../tools/registry.ts'

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/cdp/capture-engine.ts

@@ -75,7 +75,7 @@ export function isStaticAsset(url: string): boolean {
 	try {
 		path = new URL(url).pathname
 	} catch{
-		path = url.split(/[?#]/)[0] ?? url
+		path = url.split(/[?#]/)[0] || url
 	}
 
 	// Extension of the last path segment only, so `/v1.2/data` isn't misread.

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