@reclaimprotocol/agent 0.1.23 → 0.1.25

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

@@ -6,6 +6,12 @@ import {
 	connectCdp,
 	connectCdpUrl,
 } from '../../../cdp/client.ts'
+import {
+	dockerAvailable,
+	dockerMissingMessage,
+	startContainer,
+} from '../../../cdp/container.ts'
+import { suggestCountryFromIp } from '../../../cdp/geo.ts'
 import {
 	defaultProfileDir,
 	launchChrome,
@@ -15,7 +21,22 @@ import type { ConfigStore } from '../../../config/store.ts'
 import { defaultConfigPath } from '../../../config/store.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 
-export type BrowserMode = 'dedicated' | 'attach' | 'builder' | 'custom'
+export type BrowserMode =
+	| 'dedicated'
+	| 'attach'
+	| 'builder'
+	| 'custom'
+	| 'container'
+
+/**
+ * Modes with a live view that `share_browser_view` can put behind a public URL.
+ *
+ * Only `container`: it runs the Reclaim browser runtime, whose viewer already
+ * serves on loopback, so sharing is a tunnel in front of it. `builder` gives a
+ * hosted `liveViewUrl` instead, and a plain local browser has nothing to
+ * show — one on this machine is watched by looking at it.
+ */
+export const SHAREABLE_MODES = new Set<BrowserMode>(['container'])
 
 export interface AttachState {
 	handles: CdpHandles
@@ -24,6 +45,20 @@ export interface AttachState {
 	liveViewUrl?: string
 	browserSessionId?: string
 	orgId?: string
+	/** The Popcorn pod's own TEE api base (builder mode only) — lets
+	 *  `run_proof_via_pod` prove through the SAME enclave that holds the
+	 *  browser's TLS session (and its country-routed egress), instead of the
+	 *  local in-process attestor SDK. */
+	apiUrl?: string
+	/** The exit country this remote browser was allocated with, if any. */
+	countryCode?: string
+	/** Docker's name for a `container`-mode browser, for diagnostics. */
+	containerName?: string
+	/** Loopback port the container's own live viewer serves on, which is what
+	 *  `share_browser_view` tunnels. Never the CDP port. */
+	viewerPort?: number
+	/** Whether the runtime image had to be downloaded on this attach. */
+	imagePulled?: boolean
 	disposeRemote?: () => Promise<void>
 }
 
@@ -40,49 +75,204 @@ interface AttachArgs {
 	orgId?: string
 	cdpUrl?: string
 	liveViewUrl?: string
+	/** Builder mode: the country the remote browser should browse from. */
+	countryCode?: string
+	/** Builder mode: allocate without geo-routing, skipping the country
+	 *  prompt. Geolocation is optional — this is how the caller says so. */
+	skipCountry?: boolean
+	/** Container mode: loopback port for the live viewer. */
+	viewerPort?: number
+}
+
+/**
+ * The browser sources, written once and used twice: rendered into this tool's
+ * DESCRIPTION (so an agent can put the choice to the developer straight from
+ * the tool list, without a discovery round-trip) and returned verbatim as
+ * structured `options` when the tool is called without a `mode` anyway.
+ *
+ * Being the single source for both is the point — an option list that a model
+ * reads in the description but that disagrees with what the tool returns is
+ * worse than either alone.
+ *
+ * Ordered and labelled BY USE CASE, because that is the question a developer
+ * can actually answer. "Which CDP transport?" is not; "does anyone else need to
+ * get into this browser?" is, and it decides two of the four. `useCase` is the
+ * grouping key, so the rendered list reads as two pairs rather than four
+ * unrelated transports.
+ */
+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
+
+/**
+ * The options as prose, grouped by use case.
+ *
+ * The grouping is the useful part: it turns "pick one of five transports" into
+ * "answer one question, then pick one of two".
+ */
+function renderBrowserOptions(): string {
+	const seen = new Set<string>()
+	const lines: string[] = []
+	for(const option of BROWSER_OPTIONS) {
+		if(!seen.has(option.useCase)) {
+			seen.add(option.useCase)
+			lines.push(`— ${option.useCase.toUpperCase()} —`)
+		}
+
+		const needs = option.requires.length
+			? ` Needs: ${option.requires.join('; ')}.`
+			: ''
+		lines.push(
+			`(${option.mode}) ${option.label}. ${option.detail}${needs}`
+			+ ` Live view: ${option.liveView}`,
+		)
+	}
+
+	return lines.join(' ')
 }
 
 interface AttachDependencies {
 	connectLocal: typeof connectCdp
 	connectRemote: typeof connectCdpUrl
+	/** Injected so container mode is testable without Docker installed. */
+	dockerAvailable: typeof dockerAvailable
+	startContainer: typeof startContainer
 }
 
 const DEFAULT_DEPENDENCIES: AttachDependencies = {
 	connectLocal: connectCdp,
 	connectRemote: connectCdpUrl,
+	dockerAvailable,
+	startContainer,
 }
 
 export function attachTool(
 	state: AttachRef,
 	builderClient?: ReclaimClient,
-	name: 'attach_browser' | 'attach_chrome' = 'attach_browser',
 	beforeReplace?: () => Promise<void>,
-	dependencies: AttachDependencies = DEFAULT_DEPENDENCIES,
+	// Partial so a caller can stub one thing without restating the rest — the
+	// tests only ever care about a couple of these at a time.
+	dependencies: Partial<AttachDependencies> = {},
 ): RegisteredTool {
+	const deps: AttachDependencies = {
+		...DEFAULT_DEPENDENCIES, ...dependencies,
+	}
 	return defineTool<AttachArgs>(
 		{
-			name,
+			name: 'attach_browser',
 			description:
-				name === 'attach_chrome'
-					? 'Backward-compatible alias for attach_browser.'
-					: 'Connect the provider-authoring tools to a browser. Choose '
-						+ 'dedicated (launch local Chrome), attach (existing local CDP '
-						+ 'port), builder (quota-accounted Popcorn browser with a '
-						+ 'shareable live view), or custom (caller-supplied CDP '
-						+ 'websocket). '
-						+ 'For builder mode, orgId may be omitted: it auto-resolves to '
-						+ 'the account\'s only organization, or — if there is more '
-						+ 'than one — returns needsChoice with the full list so the '
-						+ 'caller can ask the developer which to use and re-call with '
-						+ 'that orgId. '
-						+ 'Builder and custom CDP credentials are held in memory and never '
-						+ 'returned.',
+				'Connect the provider-authoring tools to a browser. Never choose '
+				+ 'for them, never assume a previous session\'s choice still '
+				+ 'applies, and call this ONCE with the `mode` they pick. '
+				+ 'ASK THIS FIRST, before listing anything: "Will you be doing this '
+				+ 'yourself, or does someone else need to sign in — for example the '
+				+ 'person whose account it is?" That answer decides half the list, '
+				+ 'and a developer can answer it without knowing what CDP is. '
+				+ 'THEMSELVES → offer `dedicated` or `attach`. SOMEONE ELSE, or the '
+				+ 'site only works on a phone → offer `container` or `builder`, '
+				+ 'which are the only two that produce a link another person can '
+				+ 'open. Say which of those two costs money: `container` is free '
+				+ 'but needs Docker, `builder` needs no install but is billed '
+				+ 'against the org\'s quota. '
+				+ 'Then relay the matching options with their live-view lines. You '
+				+ 'do not need a discovery call — the full list is here, and calling '
+				+ 'with no `mode` returns it as structured `options` if you would '
+				+ 'rather read it back verbatim. '
+				+ 'OPTIONS — ' + renderBrowserOptions() + ' '
+				+ 'A `container` browser returns a local `viewerUrl`; relay it. When '
+				+ 'someone remote needs in, call share_browser_view and relay the '
+				+ 'FULL public url verbatim, on its own line. `builder` returns a '
+				+ 'hosted `liveViewUrl` — relay that the same way. `dedicated`, '
+				+ '`attach` and `custom` cannot be shared at all: if they ask for a '
+				+ 'link after picking one, say so and offer to re-attach with '
+				+ '`container`. '
+				+ 'Builder and custom CDP credentials are held in memory and are '
+				+ 'never returned. '
+				+ 'More: how_it_works({ topic: "browser" }).',
 			inputSchema: {
 				type: 'object',
 				properties: {
 					mode: {
 						type: 'string',
-						enum: ['dedicated', 'attach', 'builder', 'custom'],
+						enum: [
+							'dedicated', 'attach', 'container', 'builder', 'custom',
+						],
 					},
 					attachMode: {
 						type: 'string',
@@ -93,21 +283,59 @@ export function attachTool(
 					orgId: { type: 'string', format: 'uuid' },
 					cdpUrl: { type: 'string', maxLength: 4000 },
 					liveViewUrl: { type: 'string', format: 'uri', maxLength: 4000 },
+					viewerPort: {
+						type: 'number',
+						minimum: 1024,
+						maximum: 60000,
+						description:
+							'`container` mode only. Loopback port for the built-in live '
+							+ 'viewer. Change it only to avoid a clash; the CDP port and '
+							+ 'the container name are derived from it.',
+					},
+					countryCode: {
+						type: 'string',
+						pattern: '^[A-Za-z]{2}$',
+						description:
+							'Builder mode only. ISO 3166-1 alpha-2 country the remote '
+							+ 'browser browses from, fixed for the whole session. Omit to '
+							+ 'get a suggested country back (needsChoice) instead of '
+							+ 'allocating a browser.',
+					},
+					skipCountry: {
+						type: 'boolean',
+						description:
+							'Builder mode only. Allocate without geo-routing, skipping '
+							+ 'the country prompt. Pass this once the developer has said '
+							+ 'they don\'t need a specific country.',
+					},
 				},
 			},
 		},
 		async(parsed) => {
 			const persisted = state.config.read()?.browser_agent
-			const mode = parsed.mode ?? parsed.attachMode ?? persisted?.attachMode
+			// 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:
-						'Choose a browser mode and call attach_browser again: '
-						+ '"dedicated" launches a local dedicated Chrome profile; '
-						+ '"attach" connects to a local Chrome debugging port; '
-						+ '"builder" creates a quota-accounted remote browser and '
-						+ 'requires orgId; "custom" requires a CDP websocket URL.',
+						'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(),
 				}
 			}
@@ -146,8 +374,51 @@ export function attachTool(
 				orgId = orgs[0].id
 			}
 
+			// A remote browser's exit country is fixed for the whole session —
+			// Popcorn applies it at allocation and it can't be changed later. So
+			// confirm it with the developer BEFORE spending a quota-accounted
+			// browser on the wrong one, the same way orgId is confirmed above.
+			// Geo-routing is OPTIONAL though, so this asks rather than demands:
+			// `skipCountry` is the "no particular country" answer, and it must be
+			// as reachable as naming one.
+			if(mode === 'builder' && !parsed.countryCode && !parsed.skipCountry) {
+				const suggestion = await suggestCountryFromIp()
+				return {
+					needsChoice: true,
+					message:
+						'Ask the developer which country this browser should browse '
+						+ 'from — its egress is routed through that country for the '
+						+ 'whole session and cannot be changed afterwards. Geolocation '
+						+ 'is optional; offer all three answers below. Nothing has been '
+						+ 'allocated yet, so this costs nothing.',
+					choices: [
+						{
+							answer: 'The suggested country',
+							howToCall: `attach_browser({ mode: "builder", countryCode: "${
+								suggestion.countryCode}" })`,
+						},
+						{
+							answer: 'A specific country the site must be seen from',
+							howToCall:
+								'attach_browser({ mode: "builder", countryCode: "<ISO '
+								+ '3166-1 alpha-2>" })',
+						},
+						{
+							answer: 'No particular country',
+							howToCall:
+								'attach_browser({ mode: "builder", skipCountry: true })',
+						},
+					],
+					suggestedCountryCode: suggestion.countryCode,
+					suggestionSource: 'caller-ip',
+					...(suggestion.country ? { country: suggestion.country } : {}),
+					...(suggestion.region ? { region: suggestion.region } : {}),
+					...(suggestion.city ? { city: suggestion.city } : {}),
+				}
+			}
+
 			const next = await connect(
-				mode, { ...parsed, orgId }, persisted, builderClient, dependencies,
+				mode, { ...parsed, orgId }, persisted, builderClient, deps,
 			)
 			try {
 				await beforeReplace?.()
@@ -164,6 +435,11 @@ export function attachTool(
 				})
 			}
 
+			// How the developer watches this browser differs per mode, and none of
+			// it is guessable, so every mode says its own piece here.
+			const localView = mode === 'container'
+			const hostedView = Boolean(next.liveViewUrl) && !localView
+			const canShare = SHAREABLE_MODES.has(mode)
 			return {
 				attached: true,
 				mode,
@@ -172,6 +448,38 @@ export function attachTool(
 					? { browserSessionId: next.browserSessionId }
 					: {}),
 				...(next.liveViewUrl ? { liveViewUrl: next.liveViewUrl } : {}),
+				...(next.countryCode ? { countryCode: next.countryCode } : {}),
+				...(next.containerName ? { containerName: next.containerName } : {}),
+				...(canShare ? { liveViewAvailable: true } : {}),
+				_notes: [
+					...(next.imagePulled
+						? ['The browser runtime image was downloaded just now (about '
+							+ '432 MB, about 1.3 GB on disk). Mention it — later attaches '
+							+ 'reuse it. RECLAIM_BROWSER_RUNTIME_IMAGE points at a '
+							+ 'different or locally built image.']
+						: []),
+					...(localView
+						? ['This browser has its own live view, already running on this '
+							+ 'machine: relay `liveViewUrl` to the developer verbatim, on '
+							+ 'its own line, so they can watch and drive it. It is '
+							+ 'loopback-only, so only they can reach it. If someone ELSE '
+							+ 'needs to — a login only they can complete — call '
+							+ 'share_browser_view to put that same viewer behind a public '
+							+ 'URL.']
+						: []),
+					...(hostedView
+						? ['This browser has a hosted live view already. Relay '
+							+ '`liveViewUrl` to the developer verbatim, on its own line, '
+							+ 'so they can watch the run — share_browser_view does not '
+							+ 'apply here.']
+						: []),
+					...(!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.']
+						: []),
+				],
 			}
 		},
 	)
@@ -197,8 +505,10 @@ async function connect(
 	if(mode === 'builder') {
 		assert(builderClient, badRequest('Builder browser service is unavailable'))
 		assert(parsed.orgId, badRequest('orgId is required for builder mode'))
+		const countryCode = parsed.countryCode?.trim().toUpperCase()
 		const { data } = await builderClient.call('CreateAgentBrowserSession', {
 			params: { orgId: parsed.orgId },
+			body: countryCode ? { countryCode } : {},
 		})
 		let handles: CdpHandles
 		try {
@@ -219,6 +529,8 @@ async function connect(
 			liveViewUrl: data.liveViewUrl,
 			browserSessionId: data.id,
 			orgId: parsed.orgId,
+			...(data.apiUrl ? { apiUrl: data.apiUrl } : {}),
+			...(countryCode ? { countryCode } : {}),
 			disposeRemote: async() => {
 				await builderClient.call('DisposeAgentBrowserSession', {
 					params: {
@@ -244,6 +556,35 @@ async function connect(
 		}
 	}
 
+	if(mode === 'container') {
+		assert(await dependencies.dockerAvailable(),
+			badRequest(dockerMissingMessage()))
+		// Ports are allocated per session unless the caller names one. A fixed
+		// default would give two concurrent sessions the SAME container — the
+		// name derives from the viewer port — so session two would silently
+		// drive session one's browser.
+		const container = await dependencies.startContainer({
+			...(parsed.viewerPort ? { viewerPort: parsed.viewerPort } : {}),
+			image: process.env.RECLAIM_BROWSER_RUNTIME_IMAGE?.trim() || undefined,
+		})
+		try {
+			return {
+				handles: await dependencies.connectRemote(container.cdpUrl),
+				mode,
+				liveViewUrl: container.viewerUrl,
+				containerName: container.name,
+				viewerPort: container.viewerPort,
+				imagePulled: container.pulled,
+				disposeRemote: container.stop,
+			}
+		} catch(err) {
+			// Never leave a 1.3 GB container running for a browser we could not
+			// talk to.
+			await container.stop().catch(() => {})
+			throw err
+		}
+	}
+
 	const port = parsed.port ?? persisted?.port ?? 9222
 	if(mode === 'dedicated') {
 		try {

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

@@ -19,33 +19,40 @@ import { type AttachState, attachTool } from './attach.ts'
 import { type CaptureStore, captureTools, resetCaptures } from './capture.ts'
 import { listTabsTool } from './eval.ts'
 import { howItWorksTool } from './how-it-works.ts'
+import { type LiveShareRef, liveViewTools } from './live-view.ts'
+import { podProofTools } from './pod-proof.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
-import { sessionTools } from './session.ts'
+import { resetAll, sessionTools } from './session.ts'
 import { sharedAuthoringTools } from './shared.ts'
 
 export interface AgentState {
 	attach: { current?: AttachState, config: ConfigStore }
 	captures: CaptureStore
+	/** The one public live view, when `share_browser_view` has opened it. */
+	liveShare: LiveShareRef
 }
 
-/** Exported so a mode (e.g. old-devtools) that supplies its own publish tool
- *  can build the attach/capture state up front and share the SAME instance
- *  with `buildAgentTools` — letting that publish tool see the live attach
- *  state (e.g. to remind the caller about a still-open browser session). */
+/** Exported so a mode (for example, old-devtools) that supplies its own
+ *  publish tool can build the attach/capture state up front and share the SAME
+ *  instance with `buildAgentTools` — letting that publish tool see the live
+ *  attach state (for example, to remind the caller about a still-open browser
+ *  session). */
 export function buildAgentState(): AgentState {
 	return {
 		attach: { config: new ConfigStore() },
 		captures: { sessions: new Map() },
+		liveShare: {},
 	}
 }
 
 /** Build the flat list of `RegisteredTool` entries, ready for
  *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
- *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
- *  capture/proof tools — old mode supplies its own publish tool.
- *  Pass `externalState` to share attach/capture state with tools registered
- *  elsewhere (e.g. old mode's publish tool) instead of building a fresh one. */
+ *  omit it (for example, OLD-devtools mode) to register only the
+ *  backend-independent capture/proof tools — old mode supplies its own publish
+ *  tool. Pass `externalState` to share attach/capture state with tools
+ *  registered elsewhere (for example, old mode's publish tool) instead of
+ *  building a fresh one. */
 export function buildAgentTools(
 	client?: ReclaimClient,
 	builderClient: ReclaimClient | undefined = client,
@@ -58,18 +65,22 @@ export function buildAgentTools(
 	// client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
 	tools.push(howItWorksTool(!client))
 	const beforeReplace = () => resetCaptures(state.captures)
-	tools.push(attachTool(
-		state.attach, builderClient, 'attach_browser', beforeReplace,
-	))
-	tools.push(attachTool(
-		state.attach, builderClient, 'attach_chrome', beforeReplace,
-	))
+	tools.push(attachTool(state.attach, builderClient, beforeReplace))
 	tools.push(listTabsTool(state.attach))
 	for(const t of captureTools(state.attach, state.captures)) {
 		tools.push(t)
 	}
 
-	for(const t of sessionTools(state.attach, state.captures)) {
+	for(const t of sessionTools(state.attach, state.captures, state.liveShare)) {
+		tools.push(t)
+	}
+
+	// Local-CDP only: a builder-mode browser already has a hosted live view.
+	for(const t of liveViewTools(state.attach, state.liveShare)) {
+		tools.push(t)
+	}
+
+	for(const t of podProofTools(state.attach, state.captures)) {
 		tools.push(t)
 	}
 
@@ -87,3 +98,11 @@ export function buildAgentTools(
 
 	return tools
 }
+
+/**
+ * Tear down an agent state on the way out. Safe to call more than once, and
+ * safe when nothing was ever attached.
+ */
+export async function disposeAgentState(state: AgentState): Promise<void> {
+	await resetAll(state.attach, state.captures, state.liveShare)
+}

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

@@ -93,7 +93,11 @@ export function captureTools(
 		{
 			name: 'get_request',
 			description:
-				'Return full headers + bodies for a specific captured request.',
+				'Return the full headers and bodies of one captured request. Use it '
+				+ 'to inspect a candidate that find_requests_containing ranked. '
+				+ 'Unlike every other tool here, the headers are RAW — cookie and '
+				+ 'authorization values are visible. Read them; never repeat them to '
+				+ 'the developer or write them to a file.',
 			inputSchema: {
 				type: 'object',
 				properties: {

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

@@ -10,7 +10,10 @@ export function listTabsTool(attachRef: {
 	return defineTool<Record<string, never>>(
 		{
 			name: 'list_tabs',
-			description: 'List open Chrome tabs.',
+			description:
+				'List the open tabs in the attached browser, with their tabId, title '
+				+ 'and URL. Call it after attach_browser to pick the tabId to pass to '
+				+ 'start_capture.',
 			inputSchema: { type: 'object', properties: {} },
 		},
 		async() => {

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

@@ -22,9 +22,10 @@ export function findTool(resolveBackend: ResolveBackend): RegisteredTool {
 				+ '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. Also finds SPLIT matches: when '
-				+ '`value` is multi-word (e.g. a full name), a response that carries '
-				+ 'every word SEPARATELY (a JSON profile API with first/last name in '
-				+ 'distinct fields) is returned with `splitMatch:true` — prove those '
+				+ '`value` is multi-word (for example, a full name), a response '
+				+ 'that carries every word SEPARATELY (a JSON profile API with '
+				+ 'first and last name in distinct fields) is returned with '
+				+ '`splitMatch:true` — prove those '
 				+ 'per-field (a redaction per part) rather than as one string. '
 				+ 'Server-side; bodies stay here.',
 			inputSchema: objectSchema(
@@ -77,8 +78,8 @@ export function findTool(resolveBackend: ResolveBackend): RegisteredTool {
 					continue
 				}
 
-				// Split match: every word present separately (e.g. first/last name
-				// in distinct JSON fields). Requires ≥2 tokens so it's specific.
+				// Split match: every word present separately (for example, first/last
+				// name in distinct JSON fields). Requires ≥2 tokens so it's specific.
 				if(tokens.length >= 2 && tokens.every((t) => body.includes(t))) {
 					ranked.push({
 						...publicRequest(r),