@reclaimprotocol/agent 0.1.24 → 0.1.25

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

@@ -6,6 +6,11 @@ import {
 	connectCdp,
 	connectCdpUrl,
 } from '../../../cdp/client.ts'
+import {
+	dockerAvailable,
+	dockerMissingMessage,
+	startContainer,
+} from '../../../cdp/container.ts'
 import { suggestCountryFromIp } from '../../../cdp/geo.ts'
 import {
 	defaultProfileDir,
@@ -16,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
@@ -32,6 +52,13 @@ export interface AttachState {
 	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>
 }
 
@@ -53,6 +80,8 @@ interface AttachArgs {
 	/** 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
 }
 
 /**
@@ -65,115 +94,174 @@ interface AttachArgs {
  * reads in the description but that disagrees with what the tool returns is
  * worse than either alone.
  *
- * `liveView` is here for the same reason. How a developer watches the browser
- * differs per mode — Popcorn hands back a hosted URL, a local Chrome needs
- * `share_browser_view` to tunnel one — and nobody discovers that by guessing.
- * Advertising it alongside the mode is the only place it lands BEFORE the
- * choice is made.
+ * 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. Easiest local option; nothing to set up.',
+			+ '~/.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:
-			'On this machine only, until you share it: share_browser_view puts the '
-			+ 'tab behind a public URL (needs cloudflared) so someone elsewhere can '
-			+ 'watch, and by default click and type.',
+		liveView: 'None, and none needed — the browser is on your screen.',
 	},
 	{
 		mode: 'attach',
-		label: 'Local Chrome the developer is already running',
+		useCase: 'Working on your own machine',
+		label: 'The Chrome you already have open',
 		detail:
-			'Connects to an existing Chrome debugging port. 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.',
+			'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:
-			'On this machine only, until you share it: share_browser_view puts the '
-			+ 'tab behind a public URL (needs cloudflared) so someone elsewhere can '
-			+ 'watch, and by default click and type.',
+			'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',
-		label: 'Remote Builder browser (Popcorn), with a shareable live view',
+		useCase: 'Someone else has to sign in, or you need a phone',
+		label: 'Remote browser, hosted by Reclaim — CHARGEABLE',
 		detail:
-			'Quota-accounted remote browser; returns a liveViewUrl the developer '
-			+ 'can open or share. 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.',
+			'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 straight from '
-			+ 'Popcorn. Nothing to start, and share_browser_view does not apply.',
+			'Included. This call returns a hosted liveViewUrl to pass on; '
+			+ 'share_browser_view does not apply.',
 	},
 	{
 		mode: 'custom',
-		label: 'A CDP endpoint the developer supplies',
+		useCase: 'Advanced',
+		label: 'A CDP endpoint you supply',
 		detail:
-			'Connects to any ws:// or wss:// CDP websocket. The URL is treated as '
-			+ 'a credential — it is never logged, persisted, or returned.',
+			'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:
-			'Shareable on request: share_browser_view puts the tab behind a public '
-			+ 'URL (needs cloudflared). The developer\'s own cdpUrl is never '
-			+ 'exposed by it.',
+			'None, unless you pass your own liveViewUrl alongside the cdpUrl.',
 	},
 ] as const
 
-/** Flatten {@link BROWSER_OPTIONS} into the tool description. */
+/**
+ * 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 {
-	return BROWSER_OPTIONS
-		.map((option) => {
-			const needs = option.requires.length
-				? ` Needs: ${option.requires.join('; ')}.`
-				: ''
-			return `(${option.mode}) ${option.label}. ${option.detail}${needs}`
-				+ ` Live view: ${option.liveView}`
-		})
-		.join(' ')
+	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,
 	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: 'attach_browser',
 			description:
-				'Connect the provider-authoring tools to a browser. ASK THE '
-				+ 'DEVELOPER which of the four options below they want, then call '
-				+ 'this ONCE with their chosen `mode` — never choose for them, and '
-				+ 'never assume a previous session\'s choice still applies. You do '
-				+ 'not need a discovery call: the options are listed here. '
-				+ '(Calling with no `mode` returns the same list as structured '
-				+ '`options`, if you\'d rather relay it verbatim.) '
-				+ 'When you put the choice to them, INCLUDE each option\'s live-view '
-				+ 'line: how they watch the browser differs per mode, and nobody '
-				+ 'discovers share_browser_view on their own. '
+				'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" }).',
@@ -182,7 +270,9 @@ export function attachTool(
 				properties: {
 					mode: {
 						type: 'string',
-						enum: ['dedicated', 'attach', 'builder', 'custom'],
+						enum: [
+							'dedicated', 'attach', 'container', 'builder', 'custom',
+						],
 					},
 					attachMode: {
 						type: 'string',
@@ -193,6 +283,15 @@ 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}$',
@@ -225,9 +324,14 @@ export function attachTool(
 				return {
 					needsChoice: true,
 					message:
-						'Ask the developer which browser to use, then call '
-						+ 'attach_browser again with their chosen `mode`. Present all '
-						+ 'the options below — do not pick one for them.',
+						'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 }
@@ -314,7 +418,7 @@ export function attachTool(
 			}
 
 			const next = await connect(
-				mode, { ...parsed, orgId }, persisted, builderClient, dependencies,
+				mode, { ...parsed, orgId }, persisted, builderClient, deps,
 			)
 			try {
 				await beforeReplace?.()
@@ -331,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,
@@ -340,6 +449,37 @@ export function attachTool(
 					: {}),
 				...(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.']
+						: []),
+				],
 			}
 		},
 	)
@@ -416,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

@@ -22,7 +22,7 @@ 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 {
@@ -76,7 +76,7 @@ export function buildAgentTools(
 	}
 
 	// Local-CDP only: a builder-mode browser already has a hosted live view.
-	for(const t of liveViewTools(state.attach, state.captures, state.liveShare)) {
+	for(const t of liveViewTools(state.attach, state.liveShare)) {
 		tools.push(t)
 	}
 
@@ -98,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/index.ts

@@ -1,4 +1,8 @@
 // Barrel for the agent tool group (Chrome CDP capture, provider synthesis,
 // replay, zkTLS proof). Import from here, not the individual files.
-export { buildAgentState, buildAgentTools } from './build.ts'
-export type { AgentState } from './build.ts'
+export {
+	type AgentState,
+	buildAgentState,
+	buildAgentTools,
+	disposeAgentState,
+} from './build.ts'