@reclaimprotocol/agent 0.1.0-dev.1

package/src/cdp/capture.ts

@@ -0,0 +1,215 @@
+import type CDP from 'chrome-remote-interface'
+import type { Protocol } from 'devtools-protocol'
+import { randomUUID } from 'node:crypto'
+import { extractGraphqlOp } from '../provider/graphql.ts'
+import type { CapturedRequest } from '../provider/schema.ts'
+import { BodyStore } from './eviction.ts'
+
+/** Drop HTTP/2 pseudo-headers (`:authority`, `:method`, `:path`, `:scheme`,
+ *  `:status`) from a CDP header map. Chrome emits them on HTTP/2 requests,
+ *  but they're a transport-layer abstraction with no place in our domain:
+ *  the URL already carries authority/path/scheme, the request object carries
+ *  method, and Node's `fetch` (undici) throws on any header starting with
+ *  `:`. Stripping at capture time keeps every downstream consumer
+ *  (`get_request`, draft, replay, proof) clean by construction. */
+export function stripPseudoHeaders(
+	headers: Protocol.Network.Headers,
+): Record<string, string> {
+	const out: Record<string, string> = {}
+	for(const [k, v] of Object.entries(headers)) {
+		if(!k.startsWith(':')) {
+			out[k] = v
+		}
+	}
+
+	return out
+}
+
+export interface CaptureSession {
+	captureId: string
+	requests: Map<string, CapturedRequest>
+	bodies: BodyStore
+	stop: () => Promise<void>
+}
+
+interface InFlight {
+	requestId: string
+	method: string
+	url: string
+	requestHeaders: Record<string, string>
+	requestBody?: string
+	startedAt: number
+}
+
+export interface StartCaptureOptions {
+	maxBodyBytes?: number
+}
+
+export async function startCapture(
+	tab: CDP.Client,
+	opts: StartCaptureOptions = {},
+): Promise<CaptureSession> {
+	const captureId = randomUUID()
+	const requests = new Map<string, CapturedRequest>()
+	const inFlight = new Map<string, InFlight>()
+	const bodies = new BodyStore({
+		maxBytes: opts.maxBodyBytes ?? 200 * 1024 * 1024,
+	})
+	// CDP doesn't guarantee `requestWillBeSent` arrives before
+	// `requestWillBeSentExtraInfo` (same for the response pair). When extra
+	// info lands first, buffer it here and drain on the matching primary
+	// event. Without this, headers (Cookie, Authorization, …) get silently
+	// dropped for any request whose events race in the unlucky order.
+	const pendingRequestExtra = new Map<string, Record<string, string>>()
+	const pendingResponseExtra = new Map<string, Record<string, string>>()
+
+	const { Network } = tab
+	await Network.enable()
+
+	/** Merge extra headers from the ...ExtraInfo events into either the
+	 *  in-flight entry or the finalized captured request, whichever has
+	 *  arrived. If neither exists yet (extra-info-first race), buffer the
+	 *  headers and drain on the matching primary event. */
+	function mergeRequestHeaders(
+		requestId: string,
+		extra: Protocol.Network.Headers,
+	) {
+		const clean = stripPseudoHeaders(extra)
+		const f = inFlight.get(requestId)
+		if(f) {
+			f.requestHeaders = { ...f.requestHeaders, ...clean }
+			return
+		}
+
+		const r = requests.get(requestId)
+		if(r) {
+			r.requestHeaders = { ...r.requestHeaders, ...clean }
+			return
+		}
+
+		const buffered = pendingRequestExtra.get(requestId) ?? {}
+		pendingRequestExtra.set(requestId, { ...buffered, ...clean })
+	}
+
+	function mergeResponseHeaders(
+		requestId: string,
+		extra: Protocol.Network.Headers,
+	) {
+		const clean = stripPseudoHeaders(extra)
+		const r = requests.get(requestId)
+		if(r) {
+			r.responseHeaders = { ...r.responseHeaders, ...clean }
+			return
+		}
+
+		const buffered = pendingResponseExtra.get(requestId) ?? {}
+		pendingResponseExtra.set(requestId, { ...buffered, ...clean })
+	}
+
+	Network.requestWillBeSent(({ requestId, request }) => {
+		const f: InFlight = {
+			requestId,
+			method: request.method,
+			url: request.url,
+			requestHeaders: stripPseudoHeaders(request.headers),
+			startedAt: Date.now(),
+		}
+		if(request.postData !== undefined) {
+			f.requestBody = request.postData
+		}
+
+		// Drain any extra-info that arrived before us.
+		const buffered = pendingRequestExtra.get(requestId)
+		if(buffered) {
+			f.requestHeaders = { ...f.requestHeaders, ...buffered }
+			pendingRequestExtra.delete(requestId)
+		}
+
+		inFlight.set(requestId, f)
+	})
+
+	// CDP intentionally omits `Cookie` (and other browser-injected headers)
+	// from `requestWillBeSent.request.headers` for privacy. The real
+	// outgoing headers — including Cookie — arrive on the matching
+	// `requestWillBeSentExtraInfo` event.
+	Network.requestWillBeSentExtraInfo(({ requestId, headers }) => {
+		mergeRequestHeaders(requestId, headers)
+	})
+
+	Network.responseReceived(({ requestId, response }) => {
+		const f = inFlight.get(requestId)
+		if(!f) {
+			return
+		}
+
+		const captured: CapturedRequest = {
+			requestId,
+			method: f.method,
+			url: f.url,
+			status: response.status,
+			contentType: response.mimeType,
+			size: response.encodedDataLength,
+			requestHeaders: f.requestHeaders,
+			responseHeaders: stripPseudoHeaders(response.headers),
+			finishedAt: 0,
+		}
+
+		// Drain any response extra-info that arrived before us.
+		const bufferedResp = pendingResponseExtra.get(requestId)
+		if(bufferedResp) {
+			captured.responseHeaders = {
+				...captured.responseHeaders,
+				...bufferedResp,
+			}
+			pendingResponseExtra.delete(requestId)
+		}
+
+		if(f.requestBody !== undefined) {
+			captured.requestBody = f.requestBody
+		}
+
+		const op = extractGraphqlOp(f.requestBody)
+		if(op !== undefined) {
+			captured.graphqlOp = op
+		}
+
+		requests.set(requestId, captured)
+	})
+
+	// Same privacy carve-out applies to `Set-Cookie` and other browser-
+	// visible response headers; they arrive on responseReceivedExtraInfo.
+	Network.responseReceivedExtraInfo(({ requestId, headers }) => {
+		mergeResponseHeaders(requestId, headers)
+	})
+
+	Network.loadingFinished(async({ requestId }) => {
+		const r = requests.get(requestId)
+		if(!r) {
+			return
+		}
+
+		try {
+			const { body, base64Encoded } = await Network.getResponseBody({
+				requestId,
+			})
+			const text = base64Encoded
+				? Buffer.from(body, 'base64').toString('utf8')
+				: body
+			bodies.set(requestId, text)
+			r.responseBody = text
+			r.finishedAt = Date.now()
+		} catch{
+			// Body might be unavailable for
+			// some content-types (e.g. websocket). Skip.
+		}
+	})
+
+	return {
+		captureId,
+		requests,
+		bodies,
+		stop: async() => {
+			await Network.disable()
+		},
+	}
+}

package/src/cdp/client.ts

@@ -0,0 +1,20 @@
+import CDP from 'chrome-remote-interface'
+
+export interface CdpHandles {
+	/** Browser-level connection (target list, attach). */
+	browser: CDP.Client
+	/** Returns a per-target session bound to a tab. */
+	attachToTab: (targetId: string) => Promise<CDP.Client>
+	close: () => Promise<void>
+}
+
+export async function connectCdp(port: number): Promise<CdpHandles> {
+	const browser = await CDP({ port })
+	return {
+		browser,
+		attachToTab: (targetId) => CDP({ port, target: targetId }),
+		close: async() => {
+			await browser.close()
+		},
+	}
+}

package/src/cdp/eviction.ts

@@ -0,0 +1,52 @@
+export type BodyLookup =
+	| { available: true, body: string }
+	| { available: false, reason: string }
+
+export interface BodyStoreOptions {
+	maxBytes: number
+}
+
+export class BodyStore {
+	#store = new Map<string, string>() // insertion order = LRU order
+	#bytes = 0
+	#opts: BodyStoreOptions
+
+	constructor(opts: BodyStoreOptions) {
+		this.#opts = opts
+	}
+
+	set(requestId: string, body: string) {
+		if(this.#store.has(requestId)) {
+			this.#bytes -= byteLen(this.#store.get(requestId)!)
+			this.#store.delete(requestId)
+		}
+
+		this.#store.set(requestId, body)
+		this.#bytes += byteLen(body)
+		while(this.#bytes > this.#opts.maxBytes && this.#store.size > 0) {
+			const oldestKey = this.#store.keys().next().value!
+			const oldestVal = this.#store.get(oldestKey)!
+			this.#bytes -= byteLen(oldestVal)
+			this.#store.delete(oldestKey)
+		}
+	}
+
+	get(requestId: string): BodyLookup {
+		const body = this.#store.get(requestId)
+		if(body === undefined) {
+			return {
+				available: false,
+				reason: 'evicted from in-memory LRU body store',
+			}
+		}
+
+		// Refresh LRU position by re-inserting.
+		this.#store.delete(requestId)
+		this.#store.set(requestId, body)
+		return { available: true, body }
+	}
+}
+
+function byteLen(s: string): number {
+	return Buffer.byteLength(s, 'utf8')
+}

package/src/cdp/launcher.ts

@@ -0,0 +1,133 @@
+import { type ChildProcess, spawn } from 'node:child_process'
+import { existsSync, mkdirSync } from 'node:fs'
+import { homedir, platform } from 'node:os'
+import { join } from 'node:path'
+import { reclaimHomeDirPath } from '../paths.ts'
+
+export interface LaunchOptions {
+	/** Port for --remote-debugging-port. */
+	port: number
+	/** Path to user-data-dir. Created if missing. */
+	profileDir: string
+	/** If true, launch without a visible window (--headless=new). Useful
+	 *  for tests and CI; user-driven flows want it false. */
+	headless?: boolean
+}
+
+/**
+ * Build the platform-specific list of Chromium-family binaries to probe.
+ * Order matters: Chrome first, then Chromium, then Edge (Edge is
+ * Chromium-based, supports CDP, and is preinstalled on Win 10/11 — a
+ * useful fallback when Chrome itself isn't installed).
+ *
+ * On Windows we also probe the per-user Chrome install under
+ * %LOCALAPPDATA%, which is what you get when Chrome was installed
+ * without admin rights ("Install for me only"). Skipping this was the
+ * #1 first-run failure observed in the field.
+ */
+function browserCandidates(): string[] {
+	switch (platform()) {
+	case 'darwin':
+		return [
+			'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+			join(
+				homedir(),
+				'Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+			),
+			'/Applications/Chromium.app/Contents/MacOS/Chromium',
+			'/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+		]
+	case 'win32': {
+		const localAppData =
+				process.env['LOCALAPPDATA'] ?? join(homedir(), 'AppData', 'Local')
+		return [
+			// System-wide Chrome
+			'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+			'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+			// Per-user Chrome ("Install for me only")
+			join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+			// Edge — Chromium-based, preinstalled on Win 10/11
+			'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+			'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+		]
+	}
+
+	case 'linux':
+		return [
+			'/usr/bin/google-chrome',
+			'/usr/bin/google-chrome-stable',
+			'/usr/bin/chromium',
+			'/usr/bin/chromium-browser',
+			'/snap/bin/chromium',
+			'/usr/bin/microsoft-edge',
+		]
+	default:
+		return []
+	}
+}
+
+export function defaultProfileDir(): string {
+	return join(reclaimHomeDirPath(), 'chrome-profile')
+}
+
+export function findChromeBinary(): string {
+	const candidates = browserCandidates()
+	for(const c of candidates) {
+		if(existsSync(c)) {
+			return c
+		}
+	}
+
+	throw new Error(
+		`No Chromium-family browser found on ${platform()}. Tried:\n  ` +
+			candidates.join('\n  ') +
+		'\nSet RECLAIM_AGENT_CHROME_PATH to point at ' +
+		'your chrome.exe / msedge.exe / chromium binary.',
+	)
+}
+
+export function launchChrome(opts: LaunchOptions): ChildProcess {
+	const binary = process.env.RECLAIM_AGENT_CHROME_PATH ?? findChromeBinary()
+	if(!existsSync(opts.profileDir)) {
+		mkdirSync(opts.profileDir, { recursive: true })
+	}
+
+	const args = [
+		`--remote-debugging-port=${opts.port}`,
+		`--user-data-dir=${opts.profileDir}`,
+		'--no-first-run',
+		'--no-default-browser-check',
+	]
+	if(opts.headless) {
+		args.push('--headless=new', '--disable-gpu')
+	}
+
+	const child = spawn(binary, args, {
+		stdio: 'ignore',
+		detached: false,
+	})
+	return child
+}
+
+export async function waitForCdpReady(
+	port: number,
+	timeoutMs = 10_000,
+): Promise<void> {
+	const deadline = Date.now() + timeoutMs
+	while(Date.now() < deadline) {
+		try {
+			const res = await fetch(`http://127.0.0.1:${port}/json/version`)
+			if(res.ok) {
+				return
+			}
+		} catch{
+			// retry
+		}
+
+		await new Promise<void>((r) => setTimeout(r, 150))
+	}
+
+	throw new Error(
+		`Chrome CDP did not become ready on port ${port} within ${timeoutMs}ms`,
+	)
+}

package/src/cdp/tabs.ts

@@ -0,0 +1,22 @@
+export interface TabInfo {
+	tabId: string
+	url: string
+	title: string
+}
+
+export async function listTabs(port: number): Promise<TabInfo[]> {
+	const res = await fetch(`http://127.0.0.1:${port}/json/list`)
+	if(!res.ok) {
+		throw new Error(`CDP /json/list returned ${res.status}`)
+	}
+
+	const targets = (await res.json()) as Array<{
+		type: string
+		id: string
+		url: string
+		title: string
+	}>
+	return targets
+		.filter((t) => t.type === 'page')
+		.map((t) => ({ tabId: t.id, url: t.url, title: t.title }))
+}

package/src/cli/args.ts

@@ -0,0 +1,20 @@
+import { parseArgs as nodeParseArgs } from 'node:util'
+
+// Placeholder. Final shape decided once the backend openapi stabilises and
+// the CLI surface is fleshed out (see AGENTS.md → "CLI").
+export function parseCliArgs(argv: string[]) {
+	return nodeParseArgs({
+		args: argv,
+		options: {
+			'base-url': { type: 'string' },
+			token: { type: 'string' },
+			param: { type: 'string', multiple: true },
+			query: { type: 'string', multiple: true },
+			body: { type: 'string' },
+			help: { type: 'boolean', short: 'h' },
+			version: { type: 'boolean', short: 'v' },
+		},
+		allowPositionals: true,
+		strict: false,
+	})
+}

package/src/cli/commands.ts

@@ -0,0 +1,27 @@
+import { notImplemented } from '@hapi/boom'
+import { DESCRIPTION, NAME, VERSION } from '../pkg.ts'
+import { parseCliArgs } from './args.ts'
+
+// Entry point for the `reclaim` bin. Placeholder until backend openapi
+// finalises — `--version` and `--help` work; everything else throws.
+export async function run(argv: string[]) {
+	const parsed = parseCliArgs(argv)
+
+	if(parsed.values['version']) {
+		process.stdout.write(`${NAME} ${VERSION}\n`)
+		return
+	}
+
+	if(parsed.values['help']) {
+		process.stdout.write(
+			`${NAME} ${VERSION}\n${DESCRIPTION}\n\n` +
+			'Usage: reclaim call <OperationId> ' +
+			'[--param k=v] [--query k=v] [--body <json>]\n',
+		)
+		return
+	}
+
+	throw notImplemented(
+		'reclaim CLI: pending @reclaimprotocol/app spec finalisation',
+	)
+}

package/src/cli.ts

@@ -0,0 +1,7 @@
+import { run } from './cli/commands.ts'
+import { LOGGER } from './logger.ts'
+
+run(process.argv.slice(2)).catch((err) => {
+	LOGGER.error({ err }, 'cli failed')
+	process.exitCode = 1
+})

package/src/config/store.ts

@@ -0,0 +1,86 @@
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { CachedCredential } from '../mcp/tools/credentials/cache.ts'
+import type { CachedSession } from '../mcp/tools/credentials/session-cache.ts'
+import type { OldIdentity } from '../old/client.ts'
+import { reclaimHomeDirPath } from '../paths.ts'
+
+export interface ReclaimAgentConfig {
+	attachMode: 'dedicated' | 'attach'
+	port: number
+}
+
+/**
+ * The single on-disk document at `~/.reclaim/config.json`. Each top-level
+ * key is an independent section owned by a different subsystem:
+ *   - `browser_agent` — Chrome attach mode/port (the agent tools)
+ *   - `credentials`   — cached app key-pairs (the credential tools)
+ *   - `session`       — the auth bearer token (authenticate)
+ *   - `old_devtools`  — externally-supplied identity for OLD-devtools mode
+ *                       (USE_OLD_DEVTOOLS); independent of `session`'s
+ *                       builder token. Deletable with the rest of `src/old/`.
+ * Sections are persisted independently via `ConfigStore.write`, which
+ * merges rather than replaces, so one subsystem never clobbers another's.
+ */
+export interface ReclaimConfig {
+	version: 1
+	browser_agent?: ReclaimAgentConfig
+	credentials?: CachedCredential[]
+	session?: CachedSession
+	old_devtools?: OldIdentity
+}
+
+/**
+ * Read/write the unified Reclaim config document. The file holds secrets
+ * (a bearer token and private keys), so it is always locked to `0600` and
+ * its directory to `0700` — the `~/.ssh` posture. `read()` returns
+ * `undefined` when the file is missing or unparseable; callers layer their
+ * own validation (token expiry, credential shape) on top.
+ */
+export class ConfigStore {
+	#path: string
+
+	constructor(path: string = defaultConfigPath()) {
+		this.#path = path
+	}
+
+	read(): ReclaimConfig | undefined {
+		if(!existsSync(this.#path)) {
+			return undefined
+		}
+
+		try {
+			return JSON.parse(readFileSync(this.#path, 'utf8')) as ReclaimConfig
+		} catch{
+			return undefined
+		}
+	}
+
+	/**
+	 * Shallow-merge `patch` over the current document and persist the
+	 * result, preserving every section not named in `patch` so concurrent
+	 * subsystems don't overwrite each other's keys.
+	 */
+	write(patch: Partial<ReclaimConfig>): ReclaimConfig {
+		const next: ReclaimConfig = { ...this.read(), ...patch, version: 1 }
+
+		const dir = dirname(this.#path)
+		mkdirSync(dir, { recursive: true, mode: 0o700 })
+		chmodSync(dir, 0o700)
+		writeFileSync(this.#path, JSON.stringify(next, null, 2) + '\n', {
+			mode: 0o600,
+		})
+		chmodSync(this.#path, 0o600)
+		return next
+	}
+}
+
+export function defaultConfigPath(): string {
+	return join(reclaimHomeDirPath(), 'config.json')
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// Package entry — SDK re-exports + agent public API.
+// The CLI lives at ./cli.ts, the MCP server bin at ./mcp-bin.ts.
+
+// SDK — re-export everything from @reclaimprotocol/client so consumers
+// only need one package for both the typed HTTP client and the agent tools.
+export * from '@reclaimprotocol/client'
+
+// Agent — Chrome CDP capture, provider synthesis, replay, proof.
+export {
+	buildAgentTools,
+} from './mcp/tools/agent/build.ts'
+export type { AgentState } from './mcp/tools/agent/build.ts'

package/src/logger.ts

@@ -0,0 +1,8 @@
+import pino, { stdTimeFunctions } from 'pino'
+
+export const LOGGER = pino({
+	name: '@reclaimprotocol/agent',
+	timestamp: stdTimeFunctions.isoTime,
+	base: { hostname: undefined, pid: undefined },
+})
+LOGGER.level = process.env.LOG_LEVEL || 'info'