@reclaimprotocol/agent 0.1.3 → 0.1.5

package/src/mcp/instructions.ts

@@ -13,3 +13,21 @@ export const BUILDER_MODE_INSTRUCTIONS = readFileSync(
 	fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)),
 	'utf8',
 ).trim()
+
+/**
+ * The full provider-authoring guide — the deep capture→prove→publish workflow,
+ * decision frameworks, and troubleshooting. Served on demand by the
+ * `how_it_works` MCP tool so every client (not just Claude Code, which
+ * auto-loads skills) can pull it. There's a guide PER MODE so an agent is never
+ * shown auth/publish tools that don't exist in its backend: the server picks
+ * one by `oldMode` (see `mcp/start.ts`). Same `../../skill/` path resolution as
+ * the instructions above; any leading frontmatter is stripped defensively.
+ */
+function readGuide(file: string): string {
+	return readFileSync(fileURLToPath(new URL(file, import.meta.url)), 'utf8')
+		.replace(/^---\n[\s\S]*?\n---\n/, '')
+		.trim()
+}
+
+export const PROVIDER_GUIDE_BUILDER = readGuide('../../skill/SKILL.builder.md')
+export const PROVIDER_GUIDE_OLD = readGuide('../../skill/SKILL.old.md')

package/src/mcp/server.ts

@@ -9,16 +9,35 @@ export interface ToolDefinition {
 	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) => Promise<unknown>
+	handler: (args: unknown, ctx?: ToolContext) => Promise<unknown>
 }
 
 /**
@@ -30,14 +49,14 @@ export interface RegisteredTool {
  */
 export function defineTool<TArgs>(
 	definition: ToolDefinition,
-	handler: (args: TArgs) => Promise<unknown>,
+	handler: (args: TArgs, ctx: ToolContext) => Promise<unknown>,
 ): RegisteredTool {
 	const schema = toZod(definition.inputSchema)
 	return {
 		definition,
-		handler: async(raw) => {
+		handler: async(raw, ctx = NOOP_CONTEXT) => {
 			const args = schema.parse(raw) as TArgs
-			return await handler(args)
+			return await handler(args, ctx)
 		},
 	}
 }
@@ -55,13 +74,31 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 				description: tool.definition.description,
 				inputSchema: toZod(tool.definition.inputSchema),
 			},
-			async(args) => {
+			async(args, extra) => {
 				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), null, 2),
+								text: JSON.stringify(
+									await tool.handler(args, ctx), null, 2,
+								),
 							},
 						],
 					}

package/src/mcp/start.ts

@@ -6,6 +6,7 @@ import {
 	apiToken,
 	apiUrl,
 	oldApiUrl,
+	oldLogsUrl,
 	useOldDevtools,
 } from '../consts.ts'
 import { ReclaimOldClient } from '../old/client.ts'
@@ -49,6 +50,7 @@ export async function startMcpServer() {
 		// get_me_providers instead.
 		const oldClient = new ReclaimOldClient({
 			baseUrl: oldApiUrl(),
+			logsBaseUrl: oldLogsUrl(),
 			identity: resolveInitialIdentity(),
 		})
 

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

@@ -17,6 +17,7 @@ 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 { howItWorksTool } from './how-it-works.ts'
 import { proofTool } from './proof.ts'
 import {
 	makeSecretStore,
@@ -52,6 +53,9 @@ export function buildAgentTools(
 	const state = buildAgentState()
 	ensureAttestorCrypto()
 	const tools: RegisteredTool[] = []
+	// Stateless docs tool — serve the mode-specific authoring guide to any
+	// client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
+	tools.push(howItWorksTool(!client))
 	tools.push(attachTool(state.attach))
 	for(const t of captureTools(state.attach, state.captures)) {
 		tools.push(t)

package/src/mcp/tools/agent/how-it-works.ts

@@ -0,0 +1,32 @@
+import {
+	PROVIDER_GUIDE_BUILDER,
+	PROVIDER_GUIDE_OLD,
+} from '../../instructions.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+
+/**
+ * Serves the full provider-authoring guide on demand. The MCP server's
+ * always-on `instructions` are a terse tool-flow reference; this tool returns
+ * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
+ * so any MCP client — not just Claude Code, which alone auto-loads skills — can
+ * pull it. `oldMode` selects the backend-specific guide so the agent is never
+ * told to call auth/publish tools that aren't registered in its mode.
+ * Stateless: callable before `attach_chrome`.
+ */
+export function howItWorksTool(oldMode: boolean): RegisteredTool {
+	const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER
+	return defineTool<Record<string, never>>(
+		{
+			name: 'how_it_works',
+			description:
+				'Return the full Reclaim provider-authoring guide for THIS server: '
+				+ 'the capture → draft → replay → prove → publish workflow, decision '
+				+ 'frameworks (login detection, OPRF privacy, context vs bare params), '
+				+ 'multi-request handling, troubleshooting, and what never to do. '
+				+ 'Call this BEFORE building a provider unless you are already '
+				+ 'fluent in the flow.',
+			inputSchema: { type: 'object', properties: {} },
+		},
+		async() => ({ guide }),
+	)
+}

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

@@ -129,7 +129,7 @@ export function createVersionFromCaptureTool(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Persist drafted ReclaimProvider(s) as a verification version. ' +
+				'Persist drafted ReclaimProvider(s) as a provider version. ' +
 				'Call this after run_proof succeeds, passing the `provider` ' +
 				'object(s) from propose_provider VERBATIM. This tool builds the ' +
 				'body (the requests[] array, webSettings, etc.) for you — do NOT ' +
@@ -160,7 +160,7 @@ export function createVersionFromCaptureTool(
 				properties: {
 					providerId: {
 						type: 'string',
-						description: 'UUID of the verification to publish the version on.',
+						description: 'UUID of the provider to publish the version on.',
 					},
 					provider: PROVIDER_SCHEMA,
 					providers: {

package/src/old/client.ts

@@ -6,6 +6,10 @@ import { NAME, VERSION } from '../pkg.ts'
  *  `RECLAIM_OLD_API_URL`. */
 export const DEFAULT_OLD_API_URL = 'https://devapi.reclaimprotocol.org'
 
+/** Default origin of the OLD-devtools analytics-logs service — a SEPARATE host
+ *  from the devtools API. Override with `RECLAIM_OLD_LOGS_URL`. */
+export const DEFAULT_OLD_LOGS_URL = 'https://logs.reclaimprotocol.org'
+
 /**
  * Externally-supplied caller identity. We do NOT mint these — the dev
  * provides one:
@@ -63,15 +67,19 @@ interface RequestOpts {
  */
 export class ReclaimOldClient {
 	readonly baseUrl: string
+	readonly logsBaseUrl: string
 	#identity?: OldIdentity
 	#fetch: typeof fetch
 
 	constructor(opts: {
 		baseUrl?: string
+		logsBaseUrl?: string
 		identity?: OldIdentity
 		fetch?: typeof fetch
 	} = {}) {
 		this.baseUrl = (opts.baseUrl || DEFAULT_OLD_API_URL).replace(/\/+$/, '')
+		this.logsBaseUrl = (opts.logsBaseUrl || DEFAULT_OLD_LOGS_URL)
+			.replace(/\/+$/, '')
 		this.#identity = opts.identity
 		this.#fetch = opts.fetch ?? fetch
 	}
@@ -113,6 +121,30 @@ export class ReclaimOldClient {
 		)
 	}
 
+	/** Analytics logs for a verification session, from the logs service (a
+	 *  DIFFERENT host than the devtools API — hence its own fetch, not
+	 *  `#request`). Attaches the caller identity when one is set; queried
+	 *  anonymously otherwise. */
+	async getSessionAnalyticsLogs(sessionId: string): Promise<unknown> {
+		const url = `${this.logsBaseUrl}/api/analytics-logs/session/`
+			+ encodeURIComponent(sessionId)
+		const headers: Record<string, string> = {
+			Accept: 'application/json',
+			'User-Agent': `${NAME}/${VERSION}`,
+		}
+		if(this.#identity) {
+			headers[this.#authHeaderName()] = this.#authHeaderValue()
+		}
+
+		const res = await this.#fetch(url, { method: 'GET', headers })
+		const json = await this.#parseBody(res)
+		if(!res.ok) {
+			throw this.#asBoom(res, json)
+		}
+
+		return json
+	}
+
 	getMyProviders(query: MyProvidersQuery = {}): Promise<unknown> {
 		// Every one of these query params is REQUIRED by the backend
 		// validator (missing/invalid → 400), so default them all here.

package/src/old/login-cdp.ts

@@ -79,11 +79,18 @@ export async function captureFirebaseTokenViaCdp(opts: {
 	loginUrl?: string
 	timeoutMs?: number
 	pollMs?: number
+	/** Called every ~10s while waiting for the human to finish signing in, so
+	 *  MCP clients that track progress on this call can reset their own
+	 *  request timeout instead of giving up on a login that's still in
+	 *  flight (see `ToolContext` in `mcp/server.ts`). */
+	onProgress?: (message: string) => Promise<void>
 }): Promise<CdpLoginResult> {
 	const loginUrl =
 		opts.loginUrl || oldLoginUrl() || DEFAULT_LOGIN_URL
 	const timeoutMs = opts.timeoutMs ?? 180_000
 	const pollMs = opts.pollMs ?? 1000
+	const onProgress = opts.onProgress ?? (async() => {})
+	const progressIntervalMs = 10_000
 
 	const cfg = new ConfigStore().read()?.browser_agent
 	const mode = cfg?.attachMode ?? 'dedicated'
@@ -114,7 +121,9 @@ export async function captureFirebaseTokenViaCdp(opts: {
 	try {
 		const session = await handles.attachToTab(targetId)
 		const { Runtime } = session
-		const deadline = Date.now() + timeoutMs
+		const startedAt = Date.now()
+		const deadline = startedAt + timeoutMs
+		let lastProgressAt = startedAt
 		while(Date.now() < deadline) {
 			const r = await Runtime.evaluate({
 				expression: EXTRACT_TOKEN_JS,
@@ -126,6 +135,16 @@ export async function captureFirebaseTokenViaCdp(opts: {
 				return { token: value, closedBrowser: launchedByUs }
 			}
 
+			const now = Date.now()
+			if(now - lastProgressAt >= progressIntervalMs) {
+				lastProgressAt = now
+				const remainingSec = Math.round((deadline - now) / 1000)
+				await onProgress(
+					`Still waiting for sign-in at ${loginUrl} ` +
+					`(${remainingSec}s left before this call times out).`,
+				)
+			}
+
 			await new Promise((resolve) => setTimeout(resolve, pollMs))
 		}
 

package/src/old/tools/authenticate.ts

@@ -1,5 +1,9 @@
 import { agentDisabled } from '../../consts.ts'
-import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import {
+	defineTool,
+	type RegisteredTool,
+	type ToolContext,
+} from '../../mcp/server.ts'
 import type { OldIdentity, ReclaimOldClient } from '../client.ts'
 import { persistIdentity, toEthUid } from '../identity.ts'
 import { captureFirebaseTokenViaCdp } from '../login-cdp.ts'
@@ -83,7 +87,7 @@ export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
 				},
 			},
 		},
-		async({ token, ethAddress, loginUrl, timeoutMs, useBrowser }) => {
+		async({ token, ethAddress, loginUrl, timeoutMs, useBrowser }, ctx: ToolContext) => {
 			if(token && ethAddress) {
 				throw new Error(
 					'Provide only ONE of `token` or `ethAddress`, not both.',
@@ -136,7 +140,11 @@ export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
 				)
 			}
 
-			const result = await captureFirebaseTokenViaCdp({ loginUrl, timeoutMs })
+			const result = await captureFirebaseTokenViaCdp({
+				loginUrl,
+				timeoutMs,
+				onProgress: ctx.reportProgress,
+			})
 			const identity: OldIdentity = { kind: 'bearer', token: result.token }
 			await validate(identity)
 			persistIdentity(identity)

package/src/old/tools/build.ts

@@ -3,12 +3,13 @@ import type { ReclaimOldClient } from '../client.ts'
 import { authenticateTool } from './authenticate.ts'
 import { getMeProvidersTool } from './me-providers.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
+import { sessionAnalyticsLogsTool } from './session-analytics-logs.ts'
 
 /**
  * The backend-facing tools for OLD-devtools mode. Mirrors
  * `buildCredentialTools` / `buildAgentTools`: returns a flat `RegisteredTool`
- * list for `registerToolList`. These three replace the builder credential +
- * publish tools and the (disabled) generated provider tools.
+ * list for `registerToolList`. These replace the builder credential + publish
+ * tools and the (disabled) generated provider tools.
  */
 export function buildOldBackendTools(
 	client: ReclaimOldClient,
@@ -17,5 +18,6 @@ export function buildOldBackendTools(
 		authenticateTool(client),
 		createVersionFromCaptureTool(client),
 		getMeProvidersTool(client),
+		sessionAnalyticsLogsTool(client),
 	]
 }

package/src/old/tools/session-analytics-logs.ts

@@ -0,0 +1,33 @@
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { ReclaimOldClient } from '../client.ts'
+
+/**
+ * Fetch analytics logs for a verification session from the OLD-devtools logs
+ * service (`GET https://logs.reclaimprotocol.org/api/analytics-logs/session/
+ * :sessionId`). Old mode only — useful for diagnosing why a session failed or
+ * stalled. The logs service is a separate host from the devtools API.
+ */
+export function sessionAnalyticsLogsTool(
+	client: ReclaimOldClient,
+): RegisteredTool {
+	return defineTool<{ sessionId: string }>(
+		{
+			name: 'session_analytics_logs',
+			description:
+				'Fetch analytics logs for a verification session by id from the '
+				+ 'old-devtools logs service — use to diagnose what happened in a '
+				+ 'session (matches, claims, failures). Pass the `sessionId`.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					sessionId: {
+						type: 'string',
+						description: 'The verification session id to fetch logs for.',
+					},
+				},
+				required: ['sessionId'],
+			},
+		},
+		async(args) => client.getSessionAnalyticsLogs(args.sessionId),
+	)
+}

package/src/proof/proof-core.ts

@@ -38,7 +38,7 @@ export function resolveAttestorUrl(override?: string): string {
 	)
 }
 
-/** Map a verification's provider recipe straight to the attestor's HTTP
+/** Map a provider's recipe straight to the attestor's HTTP
  *  params — never synthesized from captured traffic. */
 export function buildHttpParams(
 	provider: ReclaimProvider,