@reclaimprotocol/agent 0.1.22 → 0.1.24

package/src/mcp/instructions.ts

@@ -1,66 +1,139 @@
 /**
- * MCP server instructions shown to the LLM when running in BUILDER mode
- * (`USE_OLD_DEVTOOLS=false`). The prose lives in `skill/builder-mode.md`
- * (published via the `files` array) so it can be edited as markdown without
- * touching code. The path resolves identically from `src/mcp` (dev) and
- * `lib/mcp` (published) — both are two levels below the package root.
- * Old-devtools mode has its own reduced set in `../old/instructions.ts`.
+ * The authoring documentation, assembled from `skill/*.md` at module load.
+ *
+ * Two things are served from here:
+ *  - the always-on MCP server `instructions` (one file per backend mode) —
+ *    deliberately small, since every client pays for them on every turn;
+ *  - the deep authoring guide, split into TOPICS and served on demand by the
+ *    `how_it_works` tool. Nothing here is inlined into a tool schema: a doc
+ *    embedded in an input-schema description is paid for on every request
+ *    whether or not it's ever relevant.
+ *
+ * The prose lives in markdown (published via package.json's `files`) so it
+ * can be edited without touching code. Paths resolve identically from
+ * `src/mcp` (dev) and `lib/mcp` (published) — both are two levels below the
+ * package root.
+ *
+ * Assembly has three steps:
+ *  1. `<!-- common: name -->` splices a shared block out of `SKILL.common.md`
+ *     (delimited there by `<!-- section: name -->`), so the two mode guides
+ *     don't drift on the ~60% of prose that is identical.
+ *  2. `%CTX%` expands to the mode's consumer-param namespace — `context.` on
+ *     the builder, `context_` on old-devtools. That is the only textual
+ *     difference across most shared blocks, so tokenizing it keeps them
+ *     shared.
+ *  3. `<!-- topic: name -->` splits the result into the units `how_it_works`
+ *     serves. Backend-independent topics come from their own files instead.
  */
 import assert from 'node:assert'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-export const BUILDER_MODE_INSTRUCTIONS = readFileSync(
-	fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)),
-	'utf8',
-).trim()
+function readSkill(file: string): string {
+	const url = new URL(`../../skill/${file}`, import.meta.url)
+	return readFileSync(fileURLToPath(url), 'utf8')
+		// Strip any leading frontmatter defensively.
+		.replace(/^---\n[\s\S]*?\n---\n/, '')
+		.trim()
+}
 
-/**
- * `SKILL.builder.md` and `SKILL.old.md` share a lot of prose (steps that are
- * identical regardless of backend, "never do" rules, common troubleshooting).
- * That shared text lives once in `skill/SKILL.common.md`, split into named
- * `<!-- section: name -->`-delimited blocks; each mode file splices a block
- * back in at `<!-- common: name -->`. Parsed once at module load.
- */
-const COMMON_SECTIONS = parseCommonSections(
-	readFileSync(
-		fileURLToPath(new URL('../../skill/SKILL.common.md', import.meta.url)),
-		'utf8',
-	),
-)
+export const BUILDER_MODE_INSTRUCTIONS = readSkill('builder-mode.md')
+export const OLD_MODE_INSTRUCTIONS = readSkill('old-mode.md')
 
-function parseCommonSections(text: string): Record<string, string> {
-	const sections: Record<string, string> = {}
-	const re = /<!-- section: (\S+) -->\n([\s\S]*?)(?=\n<!-- section: |$)/g
+/** Split `<!-- marker: name -->`-delimited blocks, keeping document order. */
+function splitBlocks(text: string, marker: string): Map<string, string> {
+	const blocks = new Map<string, string>()
+	const re = new RegExp(
+		`<!-- ${marker}: (\\S+) -->\\n([\\s\\S]*?)(?=\\n<!-- ${marker}: |$)`,
+		'g',
+	)
 	for(const match of text.matchAll(re)) {
-		// Trim blank LINES only, not inline indentation — some sections are
+		// Trim blank LINES only, not inline indentation — some blocks are
 		// list-continuation text that's intentionally indented on its first line.
-		sections[match[1]] = match[2].replace(/^\n+/, '').replace(/\n+$/, '')
+		blocks.set(match[1], match[2].replace(/^\n+/, '').replace(/\n+$/, ''))
 	}
 
-	return sections
+	return blocks
 }
 
-/**
- * The full provider-authoring guide — the deep capture→prove→publish workflow,
- * decision frameworks, and troubleshooting. Served on demand by the
- * `how_it_works` MCP tool so every client (not just Claude Code, which
- * auto-loads skills) can pull it. There's a guide PER MODE so an agent is never
- * shown auth/publish tools that don't exist in its backend: the server picks
- * one by `oldMode` (see `mcp/start.ts`). Same `../../skill/` path resolution as
- * the instructions above; any leading frontmatter is stripped defensively.
- */
-function readGuide(file: string): string {
-	const url = new URL(file, import.meta.url)
-	const raw = readFileSync(fileURLToPath(url), 'utf8')
-	const stripped = raw.replace(/^---\n[\s\S]*?\n---\n/, '').trim()
+const COMMON_SECTIONS = splitBlocks(readSkill('SKILL.common.md'), 'section')
+
+/** Topics that read the same on both backends, each its own file. */
+const SHARED_TOPIC_FILES: Record<string, string> = {
+	'user-script': 'user-script.md',
+	'interception': 'interception.md',
+	'hash-validation': 'hash-validation.md',
+}
+
+/** One line per topic, shown in the `how_it_works` index so a caller can pick
+ *  the right one without fetching several. Keyed across both modes; only the
+ *  topics a mode actually has are listed back to it. */
+const TOPIC_SUMMARIES: Record<string, string> = {
+	'overview': 'Terminology, your stance, and the whole loop at a glance.',
+	'auth': 'Signing in to the backend, and which token authorizes what.',
+	'browser': 'Choosing a browser source (local / remote / custom CDP), '
+		+ 'geolocation, live view, and launch troubleshooting.',
+	'capture': 'Tabs, login detection, driving the page, and picking an '
+		+ 'authenticated request to prove.',
+	'draft': 'The OPRF/privacy decision, propose_provider, and the canonical '
+		+ 'drafted shape.',
+	'params': 'Extracted vs consumer-supplied vs secret params, the URL '
+		+ 'character budget, and runtime resolution.',
+	'prove': 'replay_request, the mandatory auth-bound check, run_proof, and '
+		+ 'diagnosing failures.',
+	'publish': 'Creating/reusing a provider, versions, multi-request providers, '
+		+ 'and going live.',
+	'discover': 'Finding the right providers for a dev\'s app and creating a '
+		+ 'verification session.',
+	'user-script': 'Authoring jsUserScripts / customInjection to drive '
+		+ 'login-gated pages.',
+	'interception': 'injectionType / interceptorType, live interception, the '
+		+ 'document-replay flag, and what to do when a site won\'t load or '
+		+ 'won\'t let the user sign in.',
+	'hash-validation': 'bodySniff, and how verifyProof({ providerId }) gates on '
+		+ 'the declared spec hash.',
+	'credentials': 'The eth proof-owner key run_proof signs with.',
+	'never-do': 'The short list of things that always break a provider.',
+	'troubleshooting': 'Expired drafts, browser problems, and where to look '
+		+ 'next.',
+}
 
-	return stripped.replace(/<!-- common: (\S+) -->/g, (whole, name: string) => {
-		const section = COMMON_SECTIONS[name]
-		assert(section, `${file}: no SKILL.common.md section named "${name}"`)
-		return section
+export interface Guide {
+	/** Topic name → its markdown, in document order. */
+	topics: Map<string, string>
+	/** `{ topic, summary }` for every topic this mode has. */
+	index: Array<{ topic: string, summary: string }>
+	/** Every topic concatenated — the whole guide, as it used to be served. */
+	full: string
+}
+
+function buildGuide(file: string, ctxPrefix: string): Guide {
+	const raw = readSkill(file)
+		.replace(/<!-- common: (\S+) -->/g, (_whole, name: string) => {
+			const section = COMMON_SECTIONS.get(name)
+			assert(section, `${file}: no SKILL.common.md section named "${name}"`)
+			return section
+		})
+		.replaceAll('%CTX%', ctxPrefix)
+
+	const topics = splitBlocks(raw, 'topic')
+	assert(topics.size, `${file}: no <!-- topic: … --> sections found`)
+	for(const [name, path] of Object.entries(SHARED_TOPIC_FILES)) {
+		topics.set(name, readSkill(path))
+	}
+
+	const index = [...topics.keys()].map((topic) => {
+		const summary = TOPIC_SUMMARIES[topic]
+		assert(summary, `${file}: no TOPIC_SUMMARIES entry for "${topic}"`)
+		return { topic, summary }
 	})
+
+	return { topics, index, full: [...topics.values()].join('\n\n') }
 }
 
-export const PROVIDER_GUIDE_BUILDER = readGuide('../../skill/SKILL.builder.md')
-export const PROVIDER_GUIDE_OLD = readGuide('../../skill/SKILL.old.md')
+export const GUIDE_BUILDER = buildGuide('SKILL.builder.md', 'context.')
+export const GUIDE_OLD = buildGuide('SKILL.old.md', 'context_')
+
+export function guideFor(oldMode: boolean): Guide {
+	return oldMode ? GUIDE_OLD : GUIDE_BUILDER
+}

package/src/mcp/start.ts

@@ -75,7 +75,8 @@ export async function startMcpServer() {
 		})
 		const sdkClient = new ReclaimSdkClient({ baseUrl: sdkApiUrl() })
 		// Shared with buildAgentTools below so the old-mode publish tool can see
-		// the live attach state (e.g. to flag a still-open browser session).
+		// the live attach state (for example, to flag a still-open browser
+		// session).
 		const agentState = buildAgentState()
 
 		registerToolList(server, buildBuilderAuthenticationTools(builderClient))
@@ -105,8 +106,8 @@ export async function startMcpServer() {
 		// Register credential tools for ETH credential management.
 		registerToolList(server, buildCredentialTools(client))
 
-		// Higher-level verification orchestrations (e.g. fetch + decrypt result).
-		// Authenticates with RECLAIM_ORG_SECRET, not the session client.
+		// Higher-level verification orchestrations (for example, fetch + decrypt
+		// result). Authenticates with RECLAIM_ORG_SECRET, not the session client.
 		registerToolList(server, buildVerificationTools())
 
 		// Add auto-generated tools with snake_case wrappers

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

@@ -7,7 +7,11 @@ export function analyzeTool(captures: CaptureStore): RegisteredTool {
 		{
 			name: 'analyze_request_constraints',
 			description:
-				'Flag potential provider-authoring concerns for a captured request.',
+				'Flag provider-authoring concerns for one captured request — signed '
+				+ 'request, CSRF dependency, bot challenge, short-lived token, '
+				+ 'GraphQL. Call it on each top candidate from '
+				+ 'find_requests_containing before drafting, and relay the returned '
+				+ '`concerns` to the developer verbatim.',
 			inputSchema: {
 				type: 'object',
 				properties: {

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