@reclaimprotocol/agent 0.1.23 → 0.1.24

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

@@ -6,6 +6,7 @@ import {
 	connectCdp,
 	connectCdpUrl,
 } from '../../../cdp/client.ts'
+import { suggestCountryFromIp } from '../../../cdp/geo.ts'
 import {
 	defaultProfileDir,
 	launchChrome,
@@ -24,6 +25,13 @@ 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
 	disposeRemote?: () => Promise<void>
 }
 
@@ -40,6 +48,99 @@ 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
+}
+
+/**
+ * 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.
+ *
+ * `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.
+ */
+const BROWSER_OPTIONS = [
+	{
+		mode: 'dedicated',
+		label: 'Local Chrome, launched for you',
+		detail:
+			'Launches Chrome with a dedicated profile under '
+			+ '~/.reclaim/chrome-profile. Easiest local option; nothing to set up.',
+		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.',
+	},
+	{
+		mode: 'attach',
+		label: 'Local Chrome the developer is already running',
+		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.',
+		requires: ['port (default 9222)'],
+		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.',
+	},
+	{
+		mode: 'builder',
+		label: 'Remote Builder browser (Popcorn), with a shareable live view',
+		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.',
+		requires: [
+			'Builder authentication',
+			'orgId (auto-resolved when you have only one)',
+		],
+		liveView:
+			'Included — this call returns a hosted liveViewUrl straight from '
+			+ 'Popcorn. Nothing to start, and share_browser_view does not apply.',
+	},
+	{
+		mode: 'custom',
+		label: 'A CDP endpoint the developer supplies',
+		detail:
+			'Connects to any ws:// or wss:// CDP websocket. The URL is treated as '
+			+ 'a credential — it is never logged, persisted, or returned.',
+		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.',
+	},
+] as const
+
+/** Flatten {@link BROWSER_OPTIONS} into the tool description. */
+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(' ')
 }
 
 interface AttachDependencies {
@@ -55,28 +156,27 @@ const DEFAULT_DEPENDENCIES: AttachDependencies = {
 export function attachTool(
 	state: AttachRef,
 	builderClient?: ReclaimClient,
-	name: 'attach_browser' | 'attach_chrome' = 'attach_browser',
 	beforeReplace?: () => Promise<void>,
 	dependencies: AttachDependencies = DEFAULT_DEPENDENCIES,
 ): RegisteredTool {
 	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. 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. '
+				+ 'OPTIONS — ' + renderBrowserOptions() + ' '
+				+ 'Builder and custom CDP credentials are held in memory and are '
+				+ 'never returned. '
+				+ 'More: how_it_works({ topic: "browser" }).',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -93,21 +193,45 @@ export function attachTool(
 					orgId: { type: 'string', format: 'uuid' },
 					cdpUrl: { type: 'string', maxLength: 4000 },
 					liveViewUrl: { type: 'string', format: 'uri', maxLength: 4000 },
+					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 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.',
+					options: BROWSER_OPTIONS,
+					...(persisted?.attachMode
+						? { previouslyUsed: persisted.attachMode }
+						: {}),
 					configPath: defaultConfigPath(),
 				}
 			}
@@ -146,6 +270,49 @@ 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,
 			)
@@ -172,6 +339,7 @@ export function attachTool(
 					? { browserSessionId: next.browserSessionId }
 					: {}),
 				...(next.liveViewUrl ? { liveViewUrl: next.liveViewUrl } : {}),
+				...(next.countryCode ? { countryCode: next.countryCode } : {}),
 			}
 		},
 	)
@@ -197,8 +365,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 +389,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: {

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

@@ -19,6 +19,8 @@ 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 { sharedAuthoringTools } from './shared.ts'
@@ -26,26 +28,31 @@ 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.captures, state.liveShare)) {
+		tools.push(t)
+	}
+
+	for(const t of podProofTools(state.attach, state.captures)) {
 		tools.push(t)
 	}
 

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),

package/src/mcp/tools/agent/how-it-works.ts

@@ -1,32 +1,73 @@
-import {
-	PROVIDER_GUIDE_BUILDER,
-	PROVIDER_GUIDE_OLD,
-} from '../../instructions.ts'
+import { guideFor } from '../../instructions.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 
 /**
- * Serves the full provider-authoring guide on demand. The MCP server's
- * always-on `instructions` are a terse tool-flow reference; this tool returns
- * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
- * so any MCP client — not just Claude Code, which alone auto-loads skills — can
- * pull it. `oldMode` selects the backend-specific guide so the agent is never
- * told to call auth/publish tools that aren't registered in its mode.
- * Stateless: callable before `attach_browser`.
+ * Serves the provider-authoring guide on demand, ONE TOPIC AT A TIME. The
+ * server's always-on `instructions` are a terse tool-flow reference; this tool
+ * is the deep version, so any MCP client — not just Claude Code, which alone
+ * auto-loads skills — can pull it.
+ *
+ * Topic-scoped rather than all-at-once because the full guide is ~7k tokens:
+ * paying that to answer "how do I mark a header secret?" crowds out the actual
+ * task, which is exactly what makes an agent slow and prone to inventing
+ * details. Every response carries the topic index, so a caller that guessed
+ * wrong (or called with no topic at all) always learns what else is available
+ * without a second round-trip.
+ *
+ * `oldMode` selects the backend-specific guide, so the agent is never told to
+ * call auth/publish tools that aren't registered in its mode. Stateless:
+ * callable before `attach_browser`.
  */
 export function howItWorksTool(oldMode: boolean): RegisteredTool {
-	const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER
-	return defineTool<Record<string, never>>(
+	const guide = guideFor(oldMode)
+	const names = [...guide.topics.keys()]
+
+	return defineTool<{ topic?: string }>(
 		{
 			name: 'how_it_works',
 			description:
-				'Return the full Reclaim provider-authoring guide for THIS server: '
-				+ 'the capture → draft → replay → prove → publish workflow, decision '
-				+ 'frameworks (login detection, OPRF privacy, context vs bare params), '
-				+ 'multi-request handling, troubleshooting, and what never to do. '
-				+ 'Call this BEFORE building a provider unless you are already '
-				+ 'fluent in the flow.',
-			inputSchema: { type: 'object', properties: {} },
+				'Reclaim provider-authoring guide for THIS server, by topic. Call it '
+				+ 'with no arguments for the overview plus the topic index, then again '
+				+ 'for whichever topic you need. Topics: '
+				+ names.join(', ')
+				+ '. Use `all` for the entire guide at once (large — prefer a topic). '
+				+ 'Read the relevant topic BEFORE acting unless you are already fluent '
+				+ 'in that part of the flow.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					topic: {
+						type: 'string',
+						// Deliberately NOT an `enum`: schema validation runs before the
+						// handler, so an enum turns a mistyped topic into a validation
+						// error instead of a response carrying the real topic list. A
+						// plain string lets the tool answer the mistake usefully.
+						description:
+							'Which section to return: ' + names.join(', ')
+							+ ', or `all`. Omit for the overview + topic index. An '
+							+ 'unrecognized value comes back with the list, not an error.',
+					},
+				},
+			},
+		},
+		async({ topic }) => {
+			if(topic === 'all') {
+				return { topic: 'all', topics: guide.index, guide: guide.full }
+			}
+
+			const requested = topic ?? 'overview'
+			const section = guide.topics.get(requested)
+			if(!section) {
+				// Not an error: hand back the index so the caller self-corrects in
+				// the same turn rather than retrying blind.
+				return {
+					error: `Unknown topic "${requested}".`,
+					topics: guide.index,
+					guide: guide.topics.get('overview'),
+				}
+			}
+
+			return { topic: requested, topics: guide.index, guide: section }
 		},
-		async() => ({ guide }),
 	)
 }