@reclaimprotocol/agent 0.1.0-dev.1

package/src/old/to-register.ts

@@ -0,0 +1,234 @@
+import type { ReclaimProvider } from '../provider/schema.ts'
+import type {
+	RegisterProviderBody,
+	UpdateProviderConfigBody,
+} from './client.ts'
+
+/**
+ * Translate a drafted `ReclaimProvider` (from `propose_provider`) into the
+ * OLD devtools backend shapes. Deliberately a SEPARATE module from
+ * `provider/to-version.ts` (the builder translator) — the two backends have
+ * structurally different bodies:
+ *
+ *   - builder NESTS each redaction into its match's `extract`;
+ *   - old devtools keeps `responseMatches` and `responseRedactions` as
+ *     PARALLEL arrays on each `requestData` entry.
+ *
+ * Old-devtools limit we enforce here (a clear error beats a confusing
+ * server-side 400): only `GET` / `POST` methods. OPRF redactions are passed
+ * through unchanged — the backend's `hash` field accepts them.
+ */
+
+export interface OldProviderOpts {
+	initialUrl: string
+	description?: string
+	geoLocation?: string
+	providerType?: 'PRIVATE' | 'PUBLIC'
+}
+
+interface OldResponseMatch {
+	value: string
+	type: string
+	isOptional: boolean
+	order: number
+}
+
+interface OldResponseRedaction {
+	xPath?: string
+	jsonPath?: string
+	regex?: string
+	/** OPRF mode (`oprf` / `oprf-raw` / `oprf-mpc`) — the backend stores it as
+	 *  a free-form string and the attestor interprets it at verification. */
+	hash?: string
+	order: number
+}
+
+interface OldRequestData {
+	url: string
+	urlType: 'CONSTANT' | 'TEMPLATE'
+	method: 'GET' | 'POST'
+	responseMatches: OldResponseMatch[]
+	responseRedactions: OldResponseRedaction[]
+	credentials: 'include'
+	bodySniff?: { enabled: boolean, template: string }
+}
+
+/** Build the single `requestData` entry shared by register + update. */
+function requestDataFromProvider(provider: ReclaimProvider): OldRequestData {
+	const method = String(provider.method).toUpperCase()
+	if(method !== 'GET' && method !== 'POST') {
+		throw new Error(
+			'Old devtools supports only GET/POST requests; got ' +
+			`"${provider.method}". Re-capture against a GET/POST endpoint.`,
+		)
+	}
+
+	const responseMatches: OldResponseMatch[] = provider.responseMatches.map(
+		(m, i) => ({
+			value: m.value,
+			type: m.type ?? 'contains',
+			isOptional: false,
+			order: i,
+		}),
+	)
+
+	const responseRedactions: OldResponseRedaction[] = (
+		provider.responseRedactions ?? []
+	).map((r, i) => {
+		const out: OldResponseRedaction = { order: i }
+		if(r.xPath !== undefined) {
+			out.xPath = r.xPath
+		}
+
+		if(r.jsonPath !== undefined) {
+			out.jsonPath = r.jsonPath
+		}
+
+		if(r.regex !== undefined) {
+			out.regex = r.regex
+		}
+
+		// OPRF redactions are supported — pass the mode through unchanged.
+		if(r.hash !== undefined) {
+			out.hash = r.hash
+		}
+
+		return out
+	})
+
+	const requestData: OldRequestData = {
+		url: provider.url,
+		// `{{param}}` placeholders → TEMPLATE so the backend templates them;
+		// otherwise a fixed CONSTANT url. (REGEX is never drafted.)
+		urlType: provider.url.includes('{{') ? 'TEMPLATE' : 'CONSTANT',
+		method: method,
+		responseMatches,
+		responseRedactions,
+		// The verification client re-supplies cookies/auth at runtime; secrets
+		// are never persisted (propose_provider already stripped them).
+		credentials: 'include',
+	}
+	if(provider.body !== undefined) {
+		requestData.bodySniff = { enabled: true, template: provider.body }
+	}
+
+	// NOTE: `responseVariables` is intentionally omitted — the old backend
+	// auto-extracts it from `{{var}}` placeholders in responseMatches. Sending
+	// it ourselves would risk drifting from the server's own extraction.
+	return requestData
+}
+
+/** Body for `POST /api/providers/register` — new provider + v1.0.0. */
+export function providerToRegisterBody(
+	provider: ReclaimProvider,
+	opts: OldProviderOpts,
+): RegisterProviderBody {
+	const body: RegisterProviderBody = {
+		name: provider.name,
+		loginUrl: opts.initialUrl,
+		providerType: opts.providerType ?? 'PRIVATE',
+		requestData: [requestDataFromProvider(provider)],
+	}
+	if(opts.description !== undefined) {
+		body.description = opts.description
+	}
+
+	if(opts.geoLocation !== undefined) {
+		body.geoLocation = opts.geoLocation
+	}
+
+	return body
+}
+
+/** Body for `POST /api/providers/:providerId/config` — adds a new version to
+ *  an EXISTING provider. `version` must not already exist; `versionInfo` is
+ *  required and must be ≥10 chars (enforced by the backend). */
+export function providerToConfigBody(
+	provider: ReclaimProvider,
+	opts: OldProviderOpts,
+	version: string,
+	versionInfo: string,
+): UpdateProviderConfigBody {
+	const providerConfig: Record<string, unknown> = {
+		loginUrl: opts.initialUrl,
+		requestData: [requestDataFromProvider(provider)],
+	}
+	if(opts.geoLocation !== undefined) {
+		providerConfig.geoLocation = opts.geoLocation
+	}
+
+	return { providerConfig, version, versionInfo }
+}
+
+/** Minimal version triplet as the old backend stores it. */
+export interface SemverTriplet {
+	major: number
+	minor: number
+	patch: number
+}
+
+/**
+ * Pull `{major,minor,patch}` triplets out of a `/versions` response, tolerant
+ * of the exact envelope (array, `{ providerVersions: [...] }`, `{ items }`,
+ * etc.). Each entry's `version` is the triplet.
+ */
+export function extractVersions(resp: unknown): SemverTriplet[] {
+	const list = pickArray(resp)
+	const out: SemverTriplet[] = []
+	for(const item of list) {
+		const v = (item as { version?: unknown }).version ?? item
+		if(
+			v && typeof v === 'object' &&
+			typeof (v as SemverTriplet).major === 'number' &&
+			typeof (v as SemverTriplet).minor === 'number' &&
+			typeof (v as SemverTriplet).patch === 'number'
+		) {
+			const t = v as SemverTriplet
+			out.push({ major: t.major, minor: t.minor, patch: t.patch })
+		}
+	}
+
+	return out
+}
+
+/**
+ * Next version string for an update: the highest existing triplet with its
+ * patch bumped, as `"major.minor.patch"`. Falls back to `"1.0.1"` when no
+ * versions are found (a provider being updated always has ≥1, but stay safe
+ * rather than collide with the guaranteed 1.0.0).
+ */
+export function bumpPatchString(versions: SemverTriplet[]): string {
+	if(versions.length === 0) {
+		return '1.0.1'
+	}
+
+	let hi = versions[0]
+	for(const v of versions) {
+		if(
+			v.major > hi.major ||
+			(v.major === hi.major && v.minor > hi.minor) ||
+			(v.major === hi.major && v.minor === hi.minor && v.patch > hi.patch)
+		) {
+			hi = v
+		}
+	}
+
+	return `${hi.major}.${hi.minor}.${hi.patch + 1}`
+}
+
+function pickArray(resp: unknown): unknown[] {
+	if(Array.isArray(resp)) {
+		return resp
+	}
+
+	if(resp && typeof resp === 'object') {
+		const obj = resp as Record<string, unknown>
+		for(const key of ['providerVersions', 'versions', 'items', 'data']) {
+			if(Array.isArray(obj[key])) {
+				return obj[key] as unknown[]
+			}
+		}
+	}
+
+	return []
+}

package/src/old/tools/authenticate.ts

@@ -0,0 +1,152 @@
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { OldIdentity, ReclaimOldClient } from '../client.ts'
+import { persistIdentity, toEthUid } from '../identity.ts'
+import { captureFirebaseTokenViaCdp } from '../login-cdp.ts'
+
+/**
+ * OLD-devtools authenticate. The default, zero-arg flow drives Chrome via CDP:
+ * it opens the devtools dashboard, waits for the developer to sign in, reads
+ * the Firebase ID token straight from page storage, then closes the tab (or
+ * the browser, if it launched one just for this). Two manual overrides remain:
+ *
+ *   - `token`: paste a Firebase ID token yourself (skips the browser).
+ *   - `ethAddress`: an `eth:<addr>`/`0x…` uid for an already-provisioned eth
+ *     user (header carries no signature, so the uid must already exist).
+ *
+ * The chosen identity is attached to the shared client and persisted to
+ * `~/.reclaim/config.json` so later calls and future restarts reuse it. A
+ * zero-arg call reuses a still-valid stored identity before falling back to
+ * the browser flow.
+ */
+export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
+	/** Validate an identity against the backend (throws on failure). */
+	const validate = async(identity: OldIdentity): Promise<void> => {
+		client.setIdentity(identity)
+		if(identity.kind === 'bearer') {
+			await client.loginWithToken()
+		} else {
+			await client.getMyProviders({ pageSize: 1 })
+		}
+	}
+
+	return defineTool<{
+		token?: string
+		ethAddress?: string
+		loginUrl?: string
+		timeoutMs?: number
+		useBrowser?: boolean
+	}>(
+		{
+			name: 'reclaim_authenticate',
+			description:
+				'Authenticate against the OLD Reclaim devtools backend. \n\n' +
+				'Default (no args): opens the devtools dashboard in Chrome via CDP, ' +
+				'waits for you to sign in, grabs the Firebase token automatically, ' +
+				'and closes the tab. A previously stored identity that is still ' +
+				'valid is reused first (pass `useBrowser: true` to force a fresh ' +
+				'login). \n\n' +
+				'Manual overrides:\n' +
+				'- `token`: paste a Firebase ID token (skips the browser).\n' +
+				'- `ethAddress`: an `eth:0x…` / `0x…` uid for an already-provisioned ' +
+				'eth user (returns 401 "ETH user not found" if unknown).\n\n' +
+				'The identity is cached locally for subsequent publish / ' +
+				'get_me_providers calls. Firebase tokens are short-lived (~1h) — ' +
+				're-run this when calls start returning 401.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					token: {
+						type: 'string',
+						description: 'Firebase ID token (skips the browser flow).',
+					},
+					ethAddress: {
+						type: 'string',
+						description: 'eth uid (`eth:0x…`) or bare `0x…` address.',
+					},
+					loginUrl: {
+						type: 'string',
+						description:
+							'Dashboard URL to open for the browser flow ' +
+							'(default https://dev.reclaimprotocol.org).',
+					},
+					timeoutMs: {
+						type: 'number',
+						description:
+							'How long to wait for sign-in, in ms (default 180000).',
+					},
+					useBrowser: {
+						type: 'boolean',
+						description:
+							'Force the browser login even if a stored identity exists.',
+					},
+				},
+			},
+		},
+		async({ token, ethAddress, loginUrl, timeoutMs, useBrowser }) => {
+			if(token && ethAddress) {
+				throw new Error(
+					'Provide only ONE of `token` or `ethAddress`, not both.',
+				)
+			}
+
+			// Explicit credential paths skip the browser entirely.
+			if(token || ethAddress) {
+				const identity: OldIdentity = token
+					? { kind: 'bearer', token: token.trim() }
+					: toEthUid(ethAddress!)
+				await validate(identity)
+				persistIdentity(identity)
+				return {
+					authenticated: true,
+					method: identity.kind === 'bearer' ? 'token' : 'eth',
+					identity:
+						identity.kind === 'bearer'
+							? { kind: 'bearer' }
+							: { kind: 'eth', uid: identity.uid },
+				}
+			}
+
+			// Reuse a still-valid stored/env identity before opening a browser.
+			if(!useBrowser) {
+				const existing = client.getIdentity()
+				if(existing) {
+					try {
+						await validate(existing)
+						persistIdentity(existing)
+						return {
+							authenticated: true,
+							method: 'reused',
+							identity:
+								existing.kind === 'bearer'
+									? { kind: 'bearer' }
+									: { kind: 'eth', uid: existing.uid },
+						}
+					} catch{
+						// Stale/expired — fall through to the browser flow.
+					}
+				}
+			}
+
+			// CDP browser login (the default headline flow).
+			if(process.env.RECLAIM_AGENT_DISABLED === '1') {
+				throw new Error(
+					'Browser login is unavailable (RECLAIM_AGENT_DISABLED=1). Pass a ' +
+					'`token` (Firebase ID token) or `ethAddress` instead.',
+				)
+			}
+
+			const result = await captureFirebaseTokenViaCdp({ loginUrl, timeoutMs })
+			const identity: OldIdentity = { kind: 'bearer', token: result.token }
+			await validate(identity)
+			persistIdentity(identity)
+			return {
+				authenticated: true,
+				method: 'browser',
+				closedBrowser: result.closedBrowser,
+				note:
+					'Signed in via the dashboard; Firebase token captured and cached. ' +
+					'Tokens expire (~1h) — re-run reclaim_authenticate on 401.',
+			}
+		},
+	)
+}

package/src/old/tools/build.ts

@@ -0,0 +1,21 @@
+import type { RegisteredTool } from '../../mcp/server.ts'
+import type { ReclaimOldClient } from '../client.ts'
+import { authenticateTool } from './authenticate.ts'
+import { getMeProvidersTool } from './me-providers.ts'
+import { createVersionFromCaptureTool } from './publish.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.
+ */
+export function buildOldBackendTools(
+	client: ReclaimOldClient,
+): RegisteredTool[] {
+	return [
+		authenticateTool(client),
+		createVersionFromCaptureTool(client),
+		getMeProvidersTool(client),
+	]
+}

package/src/old/tools/me-providers.ts

@@ -0,0 +1,42 @@
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { ReclaimOldClient } from '../client.ts'
+
+/**
+ * List the authenticated user's OWN providers on the old devtools backend
+ * (`GET /api/providers/user/paginated`, filtered server-side to the caller's
+ * uid). This exists ONLY in old mode: the generated provider-listing tools
+ * are disabled there, so this is the way to discover a `providerId` to pass
+ * back into `create_provider_version_from_capture` for a version update.
+ */
+export function getMeProvidersTool(client: ReclaimOldClient): RegisteredTool {
+	return defineTool<{
+		pageKey?: number
+		pageSize?: number
+		searchQuery?: string
+	}>(
+		{
+			name: 'get_me_providers',
+			description:
+				'List the providers YOU own on the old devtools backend (newest ' +
+				'first). Returns provider metadata including each `providerId` — ' +
+				'pass one back to create_provider_version_from_capture to publish a ' +
+				'new version of that provider instead of creating a duplicate. ' +
+				'Requires reclaim_authenticate first.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					pageKey: { type: 'number', description: 'Page index (default 0).' },
+					pageSize: {
+						type: 'number',
+						description: 'Page size (default 20).',
+					},
+					searchQuery: {
+						type: 'string',
+						description: 'Filter by name or providerId.',
+					},
+				},
+			},
+		},
+		async(args) => client.getMyProviders(args),
+	)
+}

package/src/old/tools/publish.ts

@@ -0,0 +1,135 @@
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { ReclaimProvider } from '../../provider/schema.ts'
+import type { ReclaimOldClient } from '../client.ts'
+import {
+	bumpPatchString,
+	extractVersions,
+	type OldProviderOpts,
+	providerToConfigBody,
+	providerToRegisterBody,
+} from '../to-register.ts'
+
+const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture'
+
+/**
+ * Publish a drafted provider to the OLD devtools backend. Keeps the builder
+ * tool NAME (`create_provider_version_from_capture`) so the skill flow is
+ * unchanged, but the behaviour differs:
+ *
+ *   - WITHOUT `providerId` → `POST /api/providers/register`: creates a
+ *     brand-new provider + version 1.0.0. Re-running creates a DUPLICATE.
+ *   - WITH `providerId` → `POST /api/providers/:providerId/config`: adds a
+ *     new version to an existing provider (auto-bumps the patch above the
+ *     highest existing version).
+ *
+ * Get a `providerId` from `get_me_providers`.
+ */
+export function createVersionFromCaptureTool(
+	client: ReclaimOldClient,
+): RegisteredTool {
+	return defineTool<{
+		provider: ReclaimProvider
+		initialUrl: string
+		providerId?: string
+		description?: string
+		geoLocation?: string
+		providerType?: 'PRIVATE' | 'PUBLIC'
+		notes?: string
+	}>(
+		{
+			name: 'create_provider_version_from_capture',
+			description:
+				'Publish a drafted ReclaimProvider to the OLD devtools backend. ' +
+				'Pass the `provider` object from propose_provider VERBATIM and the ' +
+				'`initialUrl` the user landed on (the login/landing page, NOT the ' +
+				'API url). \n\n' +
+				'Omit `providerId` to REGISTER A NEW provider (creates it + version ' +
+				'1.0.0; re-running creates a duplicate). Pass `providerId` (from ' +
+				'get_me_providers) to add a NEW VERSION to that existing provider ' +
+				'(the patch is auto-bumped). \n\n' +
+				'Captured requests must be GET/POST. OPRF redactions are supported.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					provider: {
+						type: 'object',
+						description:
+							'The `provider` object from propose_provider, verbatim.',
+						properties: {
+							name: { type: 'string' },
+							url: { type: 'string' },
+							method: { type: 'string' },
+							headers: { type: 'object' },
+							body: { type: 'string' },
+							responseMatches: { type: 'array' },
+							responseRedactions: { type: 'array' },
+							paramValues: { type: 'object' },
+						},
+						required: ['name', 'url', 'method', 'responseMatches'],
+					},
+					initialUrl: {
+						type: 'string',
+						description:
+							'The website URL the user landed on to trigger the request ' +
+							'(maps to the provider `loginUrl`).',
+					},
+					providerId: {
+						type: 'string',
+						description:
+							'Existing provider to add a new version to. Omit to register ' +
+							'a brand-new provider.',
+					},
+					description: {
+						type: 'string',
+						description: 'Provider description (new-provider register only).',
+					},
+					geoLocation: { type: 'string' },
+					providerType: { type: 'string', enum: ['PRIVATE', 'PUBLIC'] },
+					notes: {
+						type: 'string',
+						description:
+							'Change note for the new version (update only; must be ≥10 ' +
+							'chars or a default is used).',
+					},
+				},
+				required: ['provider', 'initialUrl'],
+			},
+		},
+		async(args) => {
+			const opts: OldProviderOpts = { initialUrl: args.initialUrl }
+			if(args.description !== undefined) {
+				opts.description = args.description
+			}
+
+			if(args.geoLocation !== undefined) {
+				opts.geoLocation = args.geoLocation
+			}
+
+			if(args.providerType !== undefined) {
+				opts.providerType = args.providerType
+			}
+
+			// New provider.
+			if(!args.providerId) {
+				const body = providerToRegisterBody(args.provider, opts)
+				return client.registerProvider(body)
+			}
+
+			// New version of an existing provider — pick the next patch above
+			// the highest existing version.
+			const versionsResp = await client.listVersions(args.providerId)
+			const version = bumpPatchString(extractVersions(versionsResp))
+			const versionInfo =
+				args.notes && args.notes.trim().length >= 10
+					? args.notes.trim()
+					: DEFAULT_VERSION_INFO
+			const body = providerToConfigBody(
+				args.provider,
+				opts,
+				version,
+				versionInfo,
+			)
+			return client.updateProviderConfig(args.providerId, body)
+		},
+	)
+}

package/src/paths.ts

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * Resolve the Reclaim cache directory (`~/.reclaim`). Honours the
+ * `RECLAIM_HOME` env var as an override so tests can sandbox writes.
+ */
+export function reclaimHomeDirPath() {
+	return process.env.RECLAIM_HOME || join(homedir(), '.reclaim')
+}
+
+/**
+ * Walk up from `start` until we find a directory containing one of
+ * the project-root markers, then return that directory. Falls back
+ * to `start` if no marker is found within 8 levels.
+ */
+export function findProjectRoot(start: string = process.cwd()) {
+	const markers = ['.git', 'package.json', 'pyproject.toml', 'Cargo.toml']
+	let dir = resolve(start)
+	for(let i = 0; i < 8; i++) {
+		for(const m of markers) {
+			if(existsSync(join(dir, m))) {
+				return dir
+			}
+		}
+
+		const parent = dirname(dir)
+		if(parent === dir) {
+			break
+		}
+
+		dir = parent
+	}
+
+	return start
+}

package/src/pkg.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// package.json lives outside `rootDir: src`, so we can't `import` it
+// directly without widening rootDir and corrupting the build output
+// tree. Read it at runtime instead — relative to this module's URL so
+// the path resolves identically in dev (src/pkg.ts) and after build
+// (build/pkg.js), both one level below the package root.
+const PKG_PATH = join(
+	dirname(fileURLToPath(import.meta.url)),
+	'..',
+	'package.json',
+)
+
+const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8')) as {
+	name: string
+	version: string
+	description?: string
+}
+
+export const NAME = pkg.name
+export const VERSION = pkg.version
+export const DESCRIPTION = pkg.description || ''