@reclaimprotocol/agent 0.1.5 → 0.1.7

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

@@ -1,9 +1,22 @@
+import { type DraftStore, makeDraftStore } from '../../../authoring/index.ts'
 import { type CaptureSession, startCapture } from '../../../cdp/capture.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { AttachState } from './attach.ts'
 
+/**
+ * One capture == a session (network requests) + the tab CDP client it runs on +
+ * a draft store. Bundling the tab client is what lets the shared authoring
+ * tools treat a `captureId` as a full session (drive the browser AND read
+ * capture AND hold drafts) behind one id.
+ */
+export interface CaptureEntry {
+	session: CaptureSession
+	tabClient: Awaited<ReturnType<AttachState['handles']['attachToTab']>>
+	drafts: DraftStore
+}
+
 export interface CaptureStore {
-	sessions: Map<string, CaptureSession>
+	sessions: Map<string, CaptureEntry>
 	activeTab?: string
 }
 
@@ -23,8 +36,9 @@ export function captureTools(
 		{
 			name: 'start_capture',
 			description:
-				'Begin recording network requests on the specified tab. ' +
-				'Returns a captureId.',
+				'Begin recording network requests on the specified tab. '
+				+ 'Returns a captureId — the session handle the authoring tools '
+				+ '(navigate, propose_provider, run_proof, …) all take.',
 			inputSchema: {
 				type: 'object',
 				properties: { tabId: { type: 'string' } },
@@ -35,7 +49,9 @@ export function captureTools(
 			const attached = requireAttached()
 			const tabClient = await attached.handles.attachToTab(tabId)
 			const session = await startCapture(tabClient)
-			captures.sessions.set(session.captureId, session)
+			captures.sessions.set(session.captureId, {
+				session, tabClient, drafts: makeDraftStore(),
+			})
 			captures.activeTab = tabId
 			return { captureId: session.captureId }
 		},
@@ -45,8 +61,8 @@ export function captureTools(
 		{
 			name: 'stop_capture',
 			description:
-				'Stop recording on the given capture. ' +
-				'Captured data remains queryable until reset_session.',
+				'Stop recording on the given capture. '
+				+ 'Captured data remains queryable until reset_session.',
 			inputSchema: {
 				type: 'object',
 				properties: { captureId: { type: 'string' } },
@@ -54,104 +70,13 @@ export function captureTools(
 			},
 		},
 		async({ captureId }) => {
-			const session = captures.sessions.get(captureId)
-			if(!session) {
+			const entry = captures.sessions.get(captureId)
+			if(!entry) {
 				throw new Error(`no capture ${captureId}`)
 			}
 
-			await session.stop()
-			return { stopped: true, requestCount: session.requests.size }
-		},
-	)
-
-	const listTool = defineTool<{
-		captureId: string
-		filter?: {
-			method?: string
-			urlGlob?: string
-			statusMin?: number
-			statusMax?: number
-			contentType?: string
-			graphqlOp?: string
-		}
-	}>(
-		{
-			name: 'list_requests',
-			description:
-				'List metadata for captured requests. ' +
-				'Filter by method, URL glob, status, content-type, ' +
-				'or graphqlOp. Returns only metadata, never bodies — ' +
-				'use get_request for those.',
-			inputSchema: {
-				type: 'object',
-				properties: {
-					captureId: { type: 'string' },
-					filter: {
-						type: 'object',
-						properties: {
-							method: { type: 'string' },
-							urlGlob: { type: 'string' },
-							statusMin: { type: 'number' },
-							statusMax: { type: 'number' },
-							contentType: { type: 'string' },
-							graphqlOp: { type: 'string' },
-						},
-					},
-				},
-				required: ['captureId'],
-			},
-		},
-		async({ captureId, filter }) => {
-			const session = captures.sessions.get(captureId)
-			if(!session) {
-				throw new Error(`no capture ${captureId}`)
-			}
-
-			const out = []
-			for(const r of session.requests.values()) {
-				if(filter?.method && r.method !== filter.method.toUpperCase()) {
-					continue
-				}
-
-				if(filter?.urlGlob && !globMatch(filter.urlGlob, r.url)) {
-					continue
-				}
-
-				if(filter?.statusMin !== undefined && r.status < filter.statusMin) {
-					continue
-				}
-
-				if(filter?.statusMax !== undefined && r.status > filter.statusMax) {
-					continue
-				}
-
-				if(
-					filter?.contentType &&
-					!r.contentType.includes(filter.contentType)
-				) {
-					continue
-				}
-
-				if(filter?.graphqlOp && r.graphqlOp !== filter.graphqlOp) {
-					continue
-				}
-
-				const item: Record<string, unknown> = {
-					requestId: r.requestId,
-					method: r.method,
-					url: r.url,
-					status: r.status,
-					contentType: r.contentType,
-					size: r.size,
-				}
-				if(r.graphqlOp !== undefined) {
-					item.graphqlOp = r.graphqlOp
-				}
-
-				out.push(item)
-			}
-
-			return { requests: out }
+			await entry.session.stop()
+			return { stopped: true, requestCount: entry.session.requests.size }
 		},
 	)
 
@@ -170,17 +95,17 @@ export function captureTools(
 			},
 		},
 		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}`)
 			}
 
-			const body = session.bodies.get(requestId)
+			const body = entry.session.bodies.get(requestId)
 			if(!body.available) {
 				return { ...r, bodyAvailable: false, reason: body.reason }
 			}
@@ -189,14 +114,5 @@ export function captureTools(
 		},
 	)
 
-	return [startTool, stopTool, listTool, getTool]
-}
-
-function globMatch(pattern: string, str: string): boolean {
-	const re = new RegExp(
-		'^' +
-			pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') +
-			'$',
-	)
-	return re.test(str)
+	return [startTool, stopTool, getTool]
 }

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

@@ -2,160 +2,24 @@ import { listTabs } from '../../../cdp/tabs.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { AttachState } from './attach.ts'
 
-export function browserTools(attachRef: {
+/** The one browser tool that isn't session-bound: enumerate tabs so the caller
+ *  can pick one to `start_capture` on. Navigate/eval/wait are the shared
+ *  authoring tools (keyed by captureId — see `shared.ts`). */
+export function listTabsTool(attachRef: {
 	current?: AttachState
-}): RegisteredTool[] {
-	const requireAttached = (): AttachState => {
-		if(!attachRef.current) {
-			throw new Error('Not attached. Call attach_chrome first.')
-		}
-
-		return attachRef.current
-	}
-
-	return [
-		defineTool<Record<string, never>>(
-			{
-				name: 'list_tabs',
-				description: 'List open Chrome tabs.',
-				inputSchema: { type: 'object', properties: {} },
-			},
-			async() => {
-				const attached = requireAttached()
-				return { tabs: await listTabs(attached.port) }
-			},
-		),
-		defineTool<{ tabId: string, expression: string }>(
-			{
-				name: 'eval_in_page',
-				description:
-					'Run a JS expression in a tab via Runtime.evaluate ' +
-					'and return the result. ' +
-					'Useful for reading visible values from the DOM.',
-				inputSchema: {
-					type: 'object',
-					properties: {
-						tabId: { type: 'string' },
-						expression: { type: 'string' },
-					},
-					required: ['tabId', 'expression'],
-				},
-			},
-			async({ tabId, expression }) => {
-				const attached = requireAttached()
-				const { Runtime } = await attached.handles.attachToTab(tabId)
-				const result = await Runtime.evaluate({
-					expression,
-					returnByValue: true,
-				})
-				if(result.exceptionDetails) {
-					return { error: result.exceptionDetails.text }
-				}
-
-				return { value: result.result.value }
-			},
-		),
-		defineTool<{ tabId: string, url: string, timeoutMs?: number }>(
-			{
-				name: 'navigate',
-				description:
-					'Navigate a tab to a URL via Page.navigate, ' +
-					'waiting for the load event. ' +
-					'Use this to drive the browser yourself ' +
-					'instead of asking the developer to navigate. ' +
-					'Returns the final URL after navigation ' +
-					'(which may differ from the requested URL due to redirects).',
-				inputSchema: {
-					type: 'object',
-					properties: {
-						tabId: { type: 'string' },
-						url: { type: 'string' },
-						timeoutMs: { type: 'number' },
-					},
-					required: ['tabId', 'url'],
-				},
-			},
-			async({ tabId, url, timeoutMs }) => {
-				const attached = requireAttached()
-				const { Page, Runtime } = await attached.handles.attachToTab(tabId)
-
-				await Page.enable()
-				const loadPromise = new Promise<void>((resolve) => {
-					Page.loadEventFired(() => resolve())
-				})
-				const nav = await Page.navigate({ url })
-				if(nav.errorText) {
-					return { ok: false, error: nav.errorText }
-				}
-
-				const t = timeoutMs ?? 30_000
-				const raced = await Promise.race([
-					loadPromise.then(() => 'loaded' as const),
-					new Promise<'timeout'>(
-						(resolve) => setTimeout(() => resolve('timeout'), t),
-					),
-				])
-				const final = await Runtime.evaluate({
-					expression: 'location.href',
-					returnByValue: true,
-				})
-				return {
-					ok: true,
-					loadStatus: raced,
-					finalUrl: final.result.value,
-				}
-			},
-		),
-		defineTool<{
-			tabId: string
-			expression: string
-			timeoutMs?: number
-			pollMs?: number
-		}>(
-			{
-				name: 'wait_for_page',
-				description:
-					'Poll a JS expression in a tab until it ' +
-					'returns truthy (or timeout). ' +
-					'Use this for steps that require the ' +
-					'developer to do something in the browser — ' +
-					'most commonly waiting for them to finish logging in. ' +
-					'Pass an expression that ' +
-					'evaluates true once the desired state is reached, e.g. ' +
-					'`!!document.querySelector' +
-					'(\'summary[aria-label*="View profile"]\')`' +
-					' for GitHub post-login.',
-				inputSchema: {
-					type: 'object',
-					properties: {
-						tabId: { type: 'string' },
-						expression: { type: 'string' },
-						timeoutMs: { type: 'number' },
-						pollMs: { type: 'number' },
-					},
-					required: ['tabId', 'expression'],
-				},
-			},
-			async({ tabId, expression, timeoutMs, pollMs }) => {
-				const attached = requireAttached()
-				const { Runtime } = await attached.handles.attachToTab(tabId)
-				const deadline = Date.now() + (timeoutMs ?? 120_000)
-				const interval = pollMs ?? 1000
-				while(Date.now() < deadline) {
-					const r = await Runtime.evaluate({ expression, returnByValue: true })
-					if(r.exceptionDetails) {
-						return { matched: false, error: r.exceptionDetails.text }
-					}
-
-					if(r.result.value) {
-						return { matched: true, value: r.result.value }
-					}
-
-					await new Promise((resolve) => setTimeout(resolve, interval))
-				}
-
-				return { matched: false, reason: 'timeout' }
-			},
-		),
-	]
+}): RegisteredTool {
+	return defineTool<Record<string, never>>(
+		{
+			name: 'list_tabs',
+			description: 'List open Chrome tabs.',
+			inputSchema: { type: 'object', properties: {} },
+		},
+		async() => {
+			if(!attachRef.current) {
+				throw new Error('Not attached. Call attach_chrome first.')
+			}
+
+			return { tabs: await listTabs(attachRef.current.port) }
+		},
+	)
 }

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

@@ -1,36 +1,37 @@
+/**
+ * `find_requests_containing` — search captured responses for any encoding of a
+ * value and rank the requests that return it. Authored once as a plain
+ * {@link RegisteredTool}; the MCP and cloud loop each pass their own backend
+ * resolver (see authoring/tools.ts / shared.ts). Server-side: response bodies
+ * stay here, only metadata + a short snippet leave.
+ */
+import {
+	objectSchema,
+	publicRequest,
+	type ResolveBackend,
+} from '../../../authoring/util.ts'
 import { normalizeCandidates } from '../../../provider/normalize.ts'
-import { defineTool, type RegisteredTool } from '../../server.ts'
-import type { CaptureStore } from './capture.ts'
+import { defineTool, type RegisteredTool } from '../../../tools/registry.ts'
 
-export function findTool(captures: CaptureStore): RegisteredTool {
-	return defineTool<{ captureId: string, value: string, limit?: number }>(
+export function findTool(resolveBackend: ResolveBackend): RegisteredTool {
+	return defineTool<Record<string, unknown>>(
 		{
 			name: 'find_requests_containing',
 			description:
-				'Search captured responses for any encoding of `value`.' +
-				'Returns a ranked candidate list ' +
-				'with the JSON path (when applicable), score, and a short snippet.' +
-				'Server-side; bodies stay here.',
-			inputSchema: {
-				type: 'object',
-				properties: {
-					captureId: { type: 'string' },
-					value: { type: 'string' },
-					limit: { type: 'number' },
-				},
-				required: ['captureId', 'value'],
-			},
+				'Search captured responses for any encoding of `value` (raw, '
+				+ 'URL/JSON/HTML-escaped, …). Returns a ranked candidate list with '
+				+ 'the matched variant, score, and a short snippet — used to locate '
+				+ 'the request that returns a target. Server-side; bodies stay here.',
+			inputSchema: objectSchema(
+				{ value: { type: 'string' }, limit: { type: 'number' } },
+				['value'],
+			),
 		},
-		async({ captureId, value, limit }) => {
-			const session = captures.sessions.get(captureId)
-			if(!session) {
-				throw new Error(`no capture ${captureId}`)
-			}
-
-			const variants = normalizeCandidates(value)
-
+		async(args) => {
+			const backend = resolveBackend(args)
+			const variants = normalizeCandidates(String(args.value))
 			const ranked = []
-			for(const r of session.requests.values()) {
+			for(const r of backend.capture.requests.values()) {
 				if(!r.responseBody) {
 					continue
 				}
@@ -50,16 +51,11 @@ export function findTool(captures: CaptureStore): RegisteredTool {
 					continue
 				}
 
-				// Score: prefer JSON responses + smaller bodies (likely API endpoints).
-				const score =
-					(r.contentType.includes('json') ? 10 : 0) +
-					Math.max(0, 5 - Math.log10(Math.max(r.size, 1)))
+				// Prefer JSON responses + smaller bodies (likely API endpoints).
+				const score = (r.contentType.includes('json') ? 10 : 0)
+					+ Math.max(0, 5 - Math.log10(Math.max(r.size, 1)))
 				ranked.push({
-					requestId: r.requestId,
-					url: r.url,
-					method: r.method,
-					status: r.status,
-					contentType: r.contentType,
+					...publicRequest(r),
 					matchedVariant: hit.variant,
 					snippet: hit.snippet,
 					score,
@@ -67,7 +63,8 @@ export function findTool(captures: CaptureStore): RegisteredTool {
 			}
 
 			ranked.sort((a, b) => b.score - a.score)
-			return { candidates: ranked.slice(0, limit ?? 10) }
+			const limit = Number(args.limit) || 10
+			return { candidates: ranked.slice(0, limit) }
 		},
 	)
 }