@reclaimprotocol/agent 0.1.36 → 0.1.38

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

@@ -14,11 +14,11 @@ import {
 import { suggestCountryFromIp } from '../../../cdp/geo.ts'
 import {
 	defaultProfileDir,
-	launchChrome,
+	launchLocalBrowser,
+	type LocalBrowser,
 	waitForCdpReady,
 } from '../../../cdp/launcher.ts'
 import type { ConfigStore } from '../../../config/store.ts'
-import { defaultConfigPath } from '../../../config/store.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { ensureLiveViewUrl } from './live-view-url.ts'
 
@@ -60,6 +60,8 @@ export interface AttachState {
 	viewerPort?: number
 	/** Whether the runtime image had to be downloaded on this attach. */
 	imagePulled?: boolean
+	/** `dedicated` mode: the browser this attach launched, if it launched one. */
+	launched?: Omit<LocalBrowser, 'process'>
 	disposeRemote?: () => Promise<void>
 }
 
@@ -85,94 +87,15 @@ interface AttachArgs {
 	viewerPort?: number
 }
 
-/** Browser sources returned when the caller omits `mode`. Keep selection detail
- * here instead of repeating it in the always-loaded tool description. */
-const BROWSER_OPTIONS = [
-	{
-		mode: 'dedicated',
-		useCase: 'Working on your own machine',
-		label: 'Local Chrome, launched for you',
-		detail:
-			'Launches Chrome with a dedicated profile under '
-			+ '~/.reclaim/chrome-profile. Nothing to set up, and the profile '
-			+ 'persists, so a site you sign in to stays signed in. The easiest '
-			+ 'choice when you are doing the work yourself.',
-		requires: [],
-		liveView: 'None, and none needed — the browser is on your screen.',
-	},
-	{
-		mode: 'attach',
-		useCase: 'Working on your own machine',
-		label: 'The Chrome you already have open',
-		detail:
-			'Connects to a Chrome you started yourself, keeping the tabs, '
-			+ 'extensions and logins already in it. That Chrome must have been '
-			+ 'started with BOTH --remote-debugging-port AND a non-default '
-			+ '--user-data-dir: since Chrome 136 the debug flag is silently '
-			+ 'ignored on the default profile.',
-		requires: ['port (default 9222)'],
-		liveView: 'None, and none needed — the browser is on your screen.',
-	},
-	{
-		mode: 'container',
-		useCase: 'Someone else has to sign in, or you need a phone',
-		label: 'Reclaim runtime in Docker — free, runs on your machine',
-		detail:
-			'Runs the Reclaim browser runtime (the same image the remote browser '
-			+ 'uses) as a container on this machine, and gives you a link you can '
-			+ 'send to whoever holds the account. They open it in any browser, '
-			+ 'including a phone, and can see and click in it. Free — it is your '
-			+ 'Docker and your bandwidth. Costs a 432 MB first-run download and '
-			+ 'about 2 GB of RAM. The image is amd64, so Apple Silicon runs it '
-			+ 'translated. OrbStack handles that itself; Docker Desktop needs '
-			+ 'Rosetta enabled.',
-		requires: ['Docker running'],
-		liveView:
-			'Built in. This call returns a local `viewerUrl`, and '
-			+ 'share_browser_view turns that into a public link for the person '
-			+ 'helping you.',
-	},
-	{
-		mode: 'builder',
-		useCase: 'Someone else has to sign in, or you need a phone',
-		label: 'Remote browser, hosted by Reclaim — CHARGEABLE',
-		detail:
-			'A browser allocated in Reclaim\'s cloud, billed against the '
-			+ 'organization\'s quota. Nothing to install, and the shareable link '
-			+ 'comes back immediately. It is also the only way to browse a site '
-			+ 'from a SPECIFIC COUNTRY — its whole egress is routed there. '
-			+ 'Geolocation is optional: omit countryCode to be offered a '
-			+ 'suggestion, or pass skipCountry to allocate without geo-routing.',
-		requires: [
-			'Builder authentication',
-			'orgId (auto-resolved when you have only one)',
-			'quota — this one costs money',
-		],
-		liveView:
-			'Included. This call returns a hosted liveViewUrl to pass on; '
-			+ 'share_browser_view does not apply.',
-	},
-	{
-		mode: 'custom',
-		useCase: 'Advanced',
-		label: 'A CDP endpoint you supply',
-		detail:
-			'Connects to any ws:// or wss:// CDP websocket — a browser you run '
-			+ 'elsewhere, or another tool\'s. The URL is treated as a credential: '
-			+ 'never logged, persisted, or returned. Only pick this if you were '
-			+ 'given an endpoint and know why.',
-		requires: ['cdpUrl'],
-		liveView:
-			'None, unless you pass your own liveViewUrl alongside the cdpUrl.',
-	},
-] as const
-
 interface AttachDependencies {
 	connectLocal: typeof connectCdp
 	connectRemote: typeof connectCdpUrl
 	/** Injected so container mode is testable without Docker installed. */
 	dockerAvailable: typeof dockerAvailable
 	startContainer: typeof startContainer
+	/** Injected so the default launch is testable without a real browser. */
+	launchLocal: typeof launchLocalBrowser
+	waitForCdp: typeof waitForCdpReady
 }
 
 const DEFAULT_DEPENDENCIES: AttachDependencies = {
@@ -180,6 +103,8 @@ const DEFAULT_DEPENDENCIES: AttachDependencies = {
 	connectRemote: connectCdpUrl,
 	dockerAvailable,
 	startContainer,
+	launchLocal: launchLocalBrowser,
+	waitForCdp: waitForCdpReady,
 }
 
 export function attachTool(
@@ -197,16 +122,15 @@ export function attachTool(
 		{
 			name: 'attach_browser',
 			description:
-				'Connects the authoring tools to a browser that loads the '
-				+ 'developer\'s sign-in page and target site. `builder` and '
-				+ '`container` run the browser remotely or in Docker, away from the '
-				+ 'developer\'s own profile; `dedicated`, `attach`, and `custom` use a '
-				+ 'local or supplied Chrome. Call without `mode` to receive the '
-				+ 'options, ask the developer to choose, then call again once with '
-				+ 'the chosen mode. `builder` consumes quota. Only `container` and '
-				+ '`builder` support a shareable live view. Relay returned live-view '
-				+ 'URLs verbatim. See how_it_works({ topic: "browser" }) for '
-				+ 'selection, geolocation, and lifecycle.',
+				'Opens a visible browser on the developer\'s own machine for '
+				+ 'sign-in and capture. Call it with no arguments and do not ask '
+				+ 'which browser to use: it launches installed Chrome (else '
+				+ 'Chromium, Edge, or a one-time Chrome for Testing download) with '
+				+ 'the persistent Reclaim profile. Pass `mode` only when the '
+				+ 'developer explicitly asks for that mode: `attach` (their running '
+				+ 'Chrome on `port`), `container` (Docker), `custom` (`cdpUrl`), or '
+				+ '`builder` (billed). Never offer or pick those yourself. See '
+				+ 'how_it_works({ topic: "browser" }).',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -215,6 +139,9 @@ export function attachTool(
 						enum: [
 							'dedicated', 'attach', 'container', 'builder', 'custom',
 						],
+						description:
+							'Omit for the default local browser (`dedicated`). Set '
+							+ 'only to a mode the developer explicitly asked for.',
 					},
 					attachMode: {
 						type: 'string',
@@ -256,32 +183,12 @@ export function attachTool(
 		},
 		async(parsed) => {
 			const persisted = state.config.read()?.browser_agent
-			// Deliberately NOT falling back to the persisted mode: which browser
-			// to drive is the developer's call every time (a remote one costs
-			// quota, a local one exposes their own profile), and silently reusing
-			// last session's answer takes that decision away from them. The
-			// persisted choice is offered back as a default to suggest, not
-			// applied.
-			const mode = parsed.mode ?? parsed.attachMode
-			if(!mode) {
-				return {
-					needsChoice: true,
-					message:
-						'Ask FIRST whether they will be doing this themselves or '
-						+ 'someone else has to sign in — that answer decides half the '
-						+ 'list. Themselves: `dedicated` or `attach`. Someone else, or '
-						+ 'a phone-only site: `container` (free, needs Docker) or '
-						+ '`builder` (no install, chargeable) — the only two that give '
-						+ 'you a link to send. Then present the matching options and '
-						+ 'call attach_browser again with the `mode` they pick. Do not '
-						+ 'pick one for them.',
-					options: BROWSER_OPTIONS,
-					...(persisted?.attachMode
-						? { previouslyUsed: persisted.attachMode }
-						: {}),
-					configPath: defaultConfigPath(),
-				}
-			}
+			// The default is a visible browser on the developer's own machine,
+			// with no question first. Every other mode costs something (Docker,
+			// quota, the developer's own profile) and is used only when the
+			// developer asked for it by name, so a persisted choice is never
+			// reapplied either.
+			const mode = parsed.mode ?? parsed.attachMode ?? 'dedicated'
 
 			let orgId = parsed.orgId
 			if(mode === 'builder' && !orgId) {
@@ -397,7 +304,17 @@ export function attachTool(
 				...(next.countryCode ? { countryCode: next.countryCode } : {}),
 				...(next.containerName ? { containerName: next.containerName } : {}),
 				...(canShare ? { liveViewAvailable: true } : {}),
+				...(next.launched ? { browser: next.launched.source } : {}),
 				_notes: [
+					...(next.launched?.source === 'chrome-for-testing'
+						? ['Launched Chrome for Testing'
+							+ (next.launched.downloaded
+								? ', downloaded just now into ~/.reclaim/browsers (later '
+									+ 'launches reuse it)'
+								: ' from ~/.reclaim/browsers')
+							+ `, because: ${next.launched.fallbackReason}. Mention `
+							+ 'this to the developer in one line.']
+						: []),
 					...(next.imagePulled
 						? ['The browser runtime image was downloaded just now (about '
 							+ '432 MB, about 1.3 GB on disk). Mention it — later attaches '
@@ -421,9 +338,12 @@ export function attachTool(
 						: []),
 					...(!localView && !hostedView
 						? ['This browser has no live view: it runs on the developer\'s '
-							+ 'own machine, so they watch it by looking at it. If someone '
-							+ 'ELSE needs to see or drive it, say that `container` mode '
-							+ 'runs a browser with a shareable live view built in.']
+							+ 'own machine, so they watch it by looking at it. Do not '
+							+ 'offer other modes. Tell the developer once, as a side '
+							+ 'note, that if a volunteer is helping them sign in, a '
+							+ 'shareable link can be set up (`container` mode and '
+							+ 'share_browser_view); do not ask or set it up unless they '
+							+ 'ask.']
 						: []),
 				],
 			}
@@ -532,15 +452,27 @@ async function connect(
 	}
 
 	const port = parsed.port ?? persisted?.port ?? 9222
+	let launched: AttachState['launched']
 	if(mode === 'dedicated') {
 		try {
-			await waitForCdpReady(port, 500)
+			// Reuse the browser an earlier attach launched on this port.
+			await dependencies.waitForCdp(port, 500)
 		} catch{
-			launchChrome({ port, profileDir: defaultProfileDir() })
-			await waitForCdpReady(port, 10_000)
+			const browser = await dependencies
+				.launchLocal({ port, profileDir: defaultProfileDir() })
+			// The browser outlives this attach on purpose, so its process handle
+			// is not kept.
+			launched = {
+				binary: browser.binary,
+				source: browser.source,
+				downloaded: browser.downloaded,
+				...(browser.fallbackReason
+					? { fallbackReason: browser.fallbackReason }
+					: {}),
+			}
 		}
 	} else {
-		await waitForCdpReady(port, 2_000).catch(() => {
+		await dependencies.waitForCdp(port, 2_000).catch(() => {
 			throw new Error(
 				`attach mode: nothing answering CDP on port ${port}. Chrome must `
 				+ `be launched with --remote-debugging-port=${port} AND `
@@ -550,7 +482,12 @@ async function connect(
 		})
 	}
 
-	return { handles: await dependencies.connectLocal(port), mode, port }
+	return {
+		handles: await dependencies.connectLocal(port),
+		mode,
+		port,
+		...(launched ? { launched } : {}),
+	}
 }
 
 async function disposeState(state: AttachState) {

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

@@ -18,7 +18,9 @@ import { analyzeTool } from './analyze.ts'
 import { type AttachState, attachTool } from './attach.ts'
 import { type CaptureStore, captureTools, resetCaptures } from './capture.ts'
 import { checkAttestorTool } from './check-attestor.ts'
+import { draftTools } from './draft-tools.ts'
 import { listTabsTool } from './eval.ts'
+import { exampleAppTool } from './example-app.ts'
 import { howItWorksTool } from './how-it-works.ts'
 import { liveViewTools } from './live-view.ts'
 import { podProofTools } from './pod-proof.ts'
@@ -92,8 +94,15 @@ export function buildAgentTools(
 		tools.push(t)
 	}
 
+	// check_matchers / update_draft: offline matcher check + in-place draft
+	// edits, keyed by captureId like run_proof_via_pod.
+	for(const t of draftTools(state.captures)) {
+		tools.push(t)
+	}
+
 	if(client) {
 		tools.push(startIntegrationTool())
+		tools.push(exampleAppTool())
 		tools.push(createVersionFromCaptureTool(
 			client, state.attach, state.captures,
 		))

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

@@ -3,6 +3,12 @@ import {
 	type KeptScriptRef,
 	makeDraftStore,
 } from '../../../authoring/index.ts'
+import {
+	DEFAULT_MAX_CHARS,
+	TEXT_WINDOW_PROPERTIES,
+	textWindow,
+	type TextWindowArgs,
+} from '../../../authoring/util.ts'
 import { type CaptureSession, startCapture } from '../../../cdp/capture.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { AttachState } from './attach.ts'
@@ -19,6 +25,14 @@ export interface CaptureEntry {
 	drafts: DraftStore
 }
 
+interface GetRequestArgs {
+	captureId: string
+	requestId: string
+	maxChars?: number
+	offset?: number
+	full?: boolean
+}
+
 export interface CaptureStore extends KeptScriptRef {
 	sessions: Map<string, CaptureEntry>
 	activeTab?: string
@@ -96,26 +110,32 @@ export function captureTools(
 		},
 	)
 
-	const getTool = defineTool<{ captureId: string, requestId: string }>(
+	const getTool = defineTool<GetRequestArgs>(
 		{
 			name: 'get_request',
 			description:
-				'Returns the full headers and bodies of one captured request, to '
-				+ 'inspect a candidate that `find_requests_containing` ranked. Unlike '
-				+ 'the other tools, headers are raw: cookie and authorization values '
-				+ 'are visible. Read them for diagnosis; do not repeat them to the '
-				+ 'developer or write them to a file.',
+				'Returns the headers and bodies of one captured request, to inspect '
+				+ 'a candidate that `find_requests_containing` ranked. Each body is '
+				+ `cut to ${DEFAULT_MAX_CHARS} characters by default; a cut body `
+				+ 'comes with `requestBodyTruncation` or `responseBodyTruncation` '
+				+ '(total size and `nextOffset`). Page with `offset`, or pass '
+				+ '`maxChars` or `full`. Unlike the other tools, headers are raw: '
+				+ 'cookie and authorization values are visible. Read them for '
+				+ 'diagnosis; do not repeat them to the developer or write them to '
+				+ 'a file.',
 			inputSchema: {
 				type: 'object',
 				properties: {
 					captureId: { type: 'string' },
 					requestId: { type: 'string' },
+					...TEXT_WINDOW_PROPERTIES,
 				},
 				required: ['captureId', 'requestId'],
 			},
 			annotations: { readOnlyHint: true, openWorldHint: false },
 		},
-		async({ captureId, requestId }) => {
+		async(args) => {
+			const { captureId, requestId } = args
 			const entry = captures.sessions.get(captureId)
 			if(!entry) {
 				throw new Error(`no capture ${captureId}`)
@@ -126,14 +146,37 @@ export function captureTools(
 				throw new Error(`no request ${requestId} in capture ${captureId}`)
 			}
 
+			const { requestBody, responseBody, ...meta } = r
 			const body = entry.session.bodies.get(requestId)
-			if(!body.available) {
-				return { ...r, bodyAvailable: false, reason: body.reason }
+			const result = {
+				...meta,
+				...windowed('requestBody', requestBody, args),
+				...windowed(
+					'responseBody', body.available ? body.body : responseBody, args,
+				),
 			}
-
-			return { ...r, responseBody: body.body, bodyAvailable: true }
+			return body.available
+				? { ...result, bodyAvailable: true }
+				: { ...result, bodyAvailable: false, reason: body.reason }
 		},
 	)
 
 	return [startTool, stopTool, getTool]
 }
+
+/** `{ [key]: text window }`, plus `[key]Truncation` when the window cut it. */
+function windowed(
+	key: 'requestBody' | 'responseBody',
+	text: string | undefined,
+	args: TextWindowArgs,
+) {
+	if(text === undefined) {
+		return {}
+	}
+
+	const { text: part, truncation } = textWindow(text, args)
+	return {
+		[key]: part,
+		...(truncation ? { [`${key}Truncation`]: truncation } : {}),
+	}
+}

package/src/mcp/tools/agent/check-attestor.ts

@@ -20,13 +20,21 @@ export function checkAttestorTool(
 				+ 'seconds (about 8 when healthy). Call it once when you set up a '
 				+ 'new provider build, and after `run_proof` fails with a network '
 				+ 'error. Returns `{ ok, attestorUrl, durationMs, '
-				+ 'extractedParameters, error, errorKind }`. If `ok` is true, the '
-				+ 'attestor is fine and a failing proof points to the target site. '
-				+ 'If `errorKind` is `attestor-unreachable`, this machine cannot '
-				+ 'reach the attestor (network, VPN, firewall, or proxy): tell the '
-				+ 'developer. If it is `setup-failed`, the ZK file download failed '
-				+ 'before the attestor was contacted: tell the developer to check '
-				+ 'network access to the circuit download. If it is '
+				+ 'extractedParameters, error, errorKind, proofFiles }`. '
+				+ '`proofFiles` is the proof file download state: `{ status }` is '
+				+ '`idle`, `ready`, `downloading` (with `method`, `elapsedMs`, and '
+				+ '`bytesDownloaded`/`totalBytes` when known), or `failed` (with '
+				+ '`reason`). If `ok` is true, the attestor is fine and a failing '
+				+ 'proof points to the target site. If `errorKind` is '
+				+ '`proof-files-downloading`, the one-time proof file download is '
+				+ 'still running and the attestor was not contacted: call this tool '
+				+ 'again shortly; do not report a network problem. If it is '
+				+ '`proof-files-failed`, the download failed: tell the developer '
+				+ '`error` (usually no access to github.com or '
+				+ 'raw.githubusercontent.com). If it is `attestor-unreachable`, the '
+				+ 'proof files are ready but this machine cannot reach the attestor '
+				+ '(network, VPN, firewall, or proxy): tell the developer. If it is '
+				+ '`setup-failed`, other local setup failed: report `error`. If it is '
 				+ '`attestor-error`, the attestor rejected the claim: report '
 				+ '`error`.',
 			inputSchema: {