@reclaimprotocol/agent 0.1.33 → 0.1.35

package/src/mcp/api/tools.ts

@@ -9,6 +9,7 @@ import assert from 'node:assert'
 import { orgSecret } from '../../consts.ts'
 import { remapErrorAsResponse } from '../remap_errors.ts'
 import { successResponse } from '../success-response.ts'
+import { savedOrgKey } from '../tools/authenticate/org-key-store.ts'
 import { MCP_TOOLS } from './operations.gen.ts'
 
 /**
@@ -47,6 +48,11 @@ export function registerTools(
 		const shape = {
 			description: tool.description,
 			inputSchema: tool.inputSchema,
+			// Generated entries gain `annotations` when the spec marks them; read
+			// it defensively so an older generated file still registers.
+			...('annotations' in tool && tool.annotations
+				? { annotations: tool.annotations }
+				: {}),
 		}
 		if(!isOperationId(opId)) {
 			throw new Error(
@@ -73,7 +79,7 @@ export function registerTools(
 					}
 
 					const caller = orgTokenOnly
-						? orgClient(orgTokenFor(toSnakeCase(opId), orgToken))
+						? orgClient(orgTokenFor(toSnakeCase(opId), orgToken, args))
 						: client
 					const result = await caller.call(
 						opId,
@@ -117,16 +123,23 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 /** The org API key a call authenticates with: its `orgToken`, else the
- *  server's RECLAIM_ORG_SECRET. The session token (the developer's sign-in)
- *  can't stand in, since these routes accept only an org key. */
-function orgTokenFor(tool: string, orgToken: unknown) {
-	const token = (typeof orgToken === 'string' && orgToken) || orgSecret()
+ *  server's RECLAIM_ORG_SECRET, else the key `issue_org_token` saved (for the
+ *  call's `orgId` when it has one, otherwise the most recent). The session
+ *  token (the developer's sign-in) can't stand in, since these routes accept
+ *  only an org key. */
+function orgTokenFor(tool: string, orgToken: unknown, args: unknown) {
+	const orgId = isRecord(args) && isRecord(args.params)
+		? args.params.orgId
+		: undefined
+	const token = (typeof orgToken === 'string' && orgToken)
+		|| orgSecret()
+		|| savedOrgKey(typeof orgId === 'string' ? orgId : undefined)
 	assert(
 		token,
 		unauthorized(
-			`${tool} authenticates with the organization's API key. Pass `
-			+ 'orgToken: one from issue_org_token, or the app\'s '
-			+ 'RECLAIM_ORG_SECRET. Or set RECLAIM_ORG_SECRET for the MCP server.',
+			`${tool} authenticates with the organization's API key. Run `
+			+ 'issue_org_token to save one, or pass orgToken, or set '
+			+ 'RECLAIM_ORG_SECRET for the MCP server.',
 		),
 	)
 	return token

package/src/mcp/instructions.ts

@@ -56,7 +56,7 @@ const BUILDER_TOPIC_FILES: Record<string, string> = {
  *  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.',
+	'overview': 'Terminology, your stance, and the authoring checklist.',
 	'contributions': 'Contributing a public provider as a volunteer: the '
 		+ 'candidate-and-review workflow and the extra rules it adds.',
 	'auth': 'Signing in to the backend, and which token authorizes what.',
@@ -65,23 +65,23 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 	'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
 		+ 'Docker, a remote Builder browser, or a custom CDP endpoint), '
 		+ 'geolocation, live view, and launch troubleshooting.',
-	'capture': 'Tabs, login detection, driving the page, and picking an '
-		+ 'authenticated request to prove.',
+	'capture': 'Tabs, sign-in detection, capturing through the navigation '
+		+ 'script, 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 providers, resolving them, and creating a verification '
-		+ 'session.',
-	'integration': 'Set up a Builder token, callback, frontend and backend '
-		+ 'over the HTTP session API; direct `api=2` API and result '
-		+ 'verification.',
-	'user-script': 'Authoring jsUserScripts / customInjection to drive '
-		+ 'login-gated pages.',
+	'publish': 'Creating a provider, provider versions, multi-request '
+		+ 'providers, and going live.',
+	'discover': 'Reusing existing providers: finding, resolving, and '
+		+ 'creating a verification session.',
+	'integration': 'After start_integration: org key, callback (local '
+		+ 'proxy_callback_events or deployed webhook), frontend and backend '
+		+ 'over the HTTP session API; `api=2` and result verification.',
+	'user-script': 'The navigation script (jsUserScripts): sign-in redirect, '
+		+ 'multi-page walk, test_user_script with keep.',
 	'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.',

package/src/mcp/server.ts

@@ -10,6 +10,7 @@ import { successResponse } from './success-response.ts'
 export {
 	defineTool,
 	type RegisteredTool,
+	type ToolAnnotations,
 	type ToolDefinition,
 } from '../tools/registry.ts'
 
@@ -25,6 +26,9 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 			{
 				description: tool.definition.description,
 				inputSchema: toZod(tool.definition.inputSchema),
+				...(tool.definition.annotations
+					? { annotations: tool.definition.annotations }
+					: {}),
 			},
 			async(args) => {
 				try {

package/src/mcp/start.ts

@@ -31,6 +31,8 @@ import {
 	buildVerificationTools,
 	disposeAgentState,
 	readSession,
+	releaseAllListeners,
+	stopAllForwarders,
 } from './tools/index.ts'
 import { BUILDER_MODE_INSTRUCTIONS } from './instructions.ts'
 import { registerToolList } from './server.ts'
@@ -133,7 +135,7 @@ export async function startMcpServer() {
 	// the session can end without a single tool call: the developer closes their
 	// agent, the client kills the server, stdin drops. Nothing ran here before,
 	// which left a container up after the session that made it was gone.
-	if(agentToolsEnabled) {
+	if(agentToolsEnabled || !oldMode) {
 		installShutdownHooks(() => agentState)
 	}
 
@@ -160,11 +162,7 @@ function installShutdownHooks(state: () => AgentState | undefined): void {
 
 		shuttingDown = true
 		const current = state()
-		if(!current) {
-			process.exit(0)
-		}
-
-		LOGGER.info({ reason }, 'releasing the browser before exit')
+		LOGGER.info({ reason }, 'releasing resources before exit')
 		// Bounded: a wedged `docker stop` must not keep the process alive, but
 		// nor should we skip cleanup that would have finished in a second.
 		const timer = setTimeout(() => {
@@ -172,7 +170,11 @@ function installShutdownHooks(state: () => AgentState | undefined): void {
 			process.exit(0)
 		}, SHUTDOWN_GRACE_MS)
 		timer.unref()
-		void disposeAgentState(current)
+		void Promise.all([
+			stopAllForwarders(),
+			releaseAllListeners(),
+			current && disposeAgentState(current),
+		])
 			.catch((err: unknown) => {
 				LOGGER.warn({ err }, 'teardown failed')
 			})

package/src/mcp/success-response.ts

@@ -8,7 +8,11 @@ export function successResponse(value: unknown): CallToolResult {
 		structuredContent: structured(value),
 		content: [{
 			type: 'text',
-			text: JSON.stringify(value, null, 2) ?? 'null',
+			// A string result is text written for the agent (a plan, a guide):
+			// JSON-quoting it would escape every newline.
+			text: typeof value === 'string'
+				? value
+				: JSON.stringify(value, null, 2) ?? 'null',
 		}],
 	}
 }

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

@@ -7,10 +7,10 @@ export function analyzeTool(captures: CaptureStore): RegisteredTool {
 		{
 			name: 'analyze_request_constraints',
 			description:
-				'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 '
+				'Returns provider-authoring concerns for one captured request: '
+				+ 'signed request, CSRF dependency, bot challenge, short-lived '
+				+ 'token, or GraphQL. Call it on each top candidate from '
+				+ '`find_requests_containing` before drafting, and relay the '
 				+ '`concerns` to the developer verbatim.',
 			inputSchema: {
 				type: 'object',
@@ -20,6 +20,7 @@ export function analyzeTool(captures: CaptureStore): RegisteredTool {
 				},
 				required: ['captureId', 'requestId'],
 			},
+			annotations: { readOnlyHint: true, openWorldHint: false },
 		},
 		async({ captureId, requestId }) => {
 			const entry = captures.sessions.get(captureId)

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

@@ -197,13 +197,16 @@ export function attachTool(
 		{
 			name: 'attach_browser',
 			description:
-				'Connects provider-authoring tools to a browser. Call without '
-				+ '`mode` to receive the current options, then ask the developer to '
-				+ 'choose; `builder` consumes quota and only `container` and `builder` '
-				+ 'support a shareable live view. Call again once with the chosen '
-				+ 'mode. Relay returned live-view URLs verbatim. For selection, '
-				+ 'geolocation, and lifecycle guidance, call '
-				+ 'how_it_works({ topic: "browser" }).',
+				'Connects the authoring tools to a browser that loads the '
+				+ 'developer\'s sign-in page and target site. `builder` and '
+				+ '`container` run the browser remotely or in Docker, away from the '
+				+ 'developer\'s own profile; `dedicated`, `attach`, and `custom` use a '
+				+ 'local or supplied Chrome. Call without `mode` to receive the '
+				+ 'options, ask the developer to choose, then call again once with '
+				+ 'the chosen mode. `builder` consumes quota. Only `container` and '
+				+ '`builder` support a shareable live view. Relay returned live-view '
+				+ 'URLs verbatim. See how_it_works({ topic: "browser" }) for '
+				+ 'selection, geolocation, and lifecycle.',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -249,6 +252,7 @@ export function attachTool(
 					},
 				},
 			},
+			annotations: { openWorldHint: true, destructiveHint: false },
 		},
 		async(parsed) => {
 			const persisted = state.config.read()?.browser_agent

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

@@ -17,6 +17,7 @@ import { type RegisteredTool } from '../../server.ts'
 import { analyzeTool } from './analyze.ts'
 import { type AttachState, attachTool } from './attach.ts'
 import { type CaptureStore, captureTools, resetCaptures } from './capture.ts'
+import { checkAttestorTool } from './check-attestor.ts'
 import { listTabsTool } from './eval.ts'
 import { howItWorksTool } from './how-it-works.ts'
 import { liveViewTools } from './live-view.ts'
@@ -24,6 +25,7 @@ import { podProofTools } from './pod-proof.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
 import { resetAll, sessionTools } from './session.ts'
 import { sharedAuthoringTools } from './shared.ts'
+import { startIntegrationTool } from './start-integration.ts'
 
 export interface AgentState {
 	attach: { current?: AttachState, config: ConfigStore }
@@ -82,6 +84,7 @@ export function buildAgentTools(
 	}
 
 	tools.push(analyzeTool(state.captures))
+	tools.push(checkAttestorTool())
 	// navigate / eval_in_page / wait_for_page / get_cookies / list_requests /
 	// find_requests_containing / propose_provider / replay_request / run_proof —
 	// shared with the cloud loop, bound to each capture's local backend.
@@ -90,7 +93,10 @@ export function buildAgentTools(
 	}
 
 	if(client) {
-		tools.push(createVersionFromCaptureTool(client, state.attach))
+		tools.push(startIntegrationTool())
+		tools.push(createVersionFromCaptureTool(
+			client, state.attach, state.captures,
+		))
 	}
 
 	return tools

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

@@ -1,4 +1,8 @@
-import { type DraftStore, makeDraftStore } from '../../../authoring/index.ts'
+import {
+	type DraftStore,
+	type KeptScriptRef,
+	makeDraftStore,
+} from '../../../authoring/index.ts'
 import { type CaptureSession, startCapture } from '../../../cdp/capture.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { AttachState } from './attach.ts'
@@ -15,7 +19,7 @@ export interface CaptureEntry {
 	drafts: DraftStore
 }
 
-export interface CaptureStore {
+export interface CaptureStore extends KeptScriptRef {
 	sessions: Map<string, CaptureEntry>
 	activeTab?: string
 }
@@ -27,6 +31,7 @@ export async function resetCaptures(captures: CaptureStore) {
 
 	captures.sessions.clear()
 	delete captures.activeTab
+	delete captures.keptScript
 }
 
 export function captureTools(
@@ -45,14 +50,15 @@ export function captureTools(
 		{
 			name: 'start_capture',
 			description:
-				'Begin recording network requests on the specified tab. '
-				+ 'Returns a captureId — the session handle the authoring tools '
-				+ '(navigate, propose_provider, run_proof, …) all take.',
+				'Starts recording network requests on a tab. Returns a captureId, '
+				+ 'the session handle that the authoring tools (`navigate`, '
+				+ '`propose_provider`, `run_proof`) take.',
 			inputSchema: {
 				type: 'object',
 				properties: { tabId: { type: 'string' } },
 				required: ['tabId'],
 			},
+			annotations: { openWorldHint: true },
 		},
 		async({ tabId }) => {
 			const attached = requireAttached()
@@ -70,13 +76,14 @@ export function captureTools(
 		{
 			name: 'stop_capture',
 			description:
-				'Stop recording on the given capture. '
-				+ 'Captured data remains queryable until reset_session.',
+				'Stops recording on a capture. Captured requests stay queryable '
+				+ 'until `reset_session`.',
 			inputSchema: {
 				type: 'object',
 				properties: { captureId: { type: 'string' } },
 				required: ['captureId'],
 			},
+			annotations: { openWorldHint: false, idempotentHint: true },
 		},
 		async({ captureId }) => {
 			const entry = captures.sessions.get(captureId)
@@ -93,11 +100,11 @@ export function captureTools(
 		{
 			name: 'get_request',
 			description:
-				'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.',
+				'Returns the full headers and bodies of one captured request, to '
+				+ 'inspect a candidate that `find_requests_containing` ranked. Unlike '
+				+ 'the other tools, headers are raw: cookie and authorization values '
+				+ 'are visible. Read them for diagnosis; do not repeat them to the '
+				+ 'developer or write them to a file.',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -106,6 +113,7 @@ export function captureTools(
 				},
 				required: ['captureId', 'requestId'],
 			},
+			annotations: { readOnlyHint: true, openWorldHint: false },
 		},
 		async({ captureId, requestId }) => {
 			const entry = captures.sessions.get(captureId)

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

@@ -0,0 +1,49 @@
+import {
+	checkAttestor,
+	type CheckAttestorOptions,
+} from '../../../proof/check-attestor.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+
+/** `check_attestor`: proves a public request to show whether the attestor
+ *  works from this machine. `check` is injectable so tests need no network. */
+export function checkAttestorTool(
+	check: (opts: CheckAttestorOptions) => ReturnType<typeof checkAttestor>
+		= checkAttestor,
+): RegisteredTool {
+	return defineTool<{ attestorUrl?: string }>(
+		{
+			name: 'check_attestor',
+			description:
+				'Checks that the Reclaim attestor works from this machine by proving '
+				+ 'a public CoinGecko price request with a throwaway key. It uses no '
+				+ 'credential, provider, or logged-in site, and takes up to 45 '
+				+ 'seconds (about 8 when healthy). Call it once when you set up a '
+				+ 'new provider build, and after `run_proof` fails with a network '
+				+ 'error. Returns `{ ok, attestorUrl, durationMs, '
+				+ 'extractedParameters, error, errorKind }`. If `ok` is true, the '
+				+ 'attestor is fine and a failing proof points to the target site. '
+				+ 'If `errorKind` is `attestor-unreachable`, this machine cannot '
+				+ 'reach the attestor (network, VPN, firewall, or proxy): tell the '
+				+ 'developer. If it is `setup-failed`, the ZK file download failed '
+				+ 'before the attestor was contacted: tell the developer to check '
+				+ 'network access to the circuit download. If it is '
+				+ '`attestor-error`, the attestor rejected the claim: report '
+				+ '`error`.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					attestorUrl: {
+						type: 'string',
+						description:
+							'Attestor websocket URL. Set it only if the developer '
+							+ 'supplied one; the default is the public attestor.',
+					},
+				},
+			},
+			annotations: { openWorldHint: true, readOnlyHint: true },
+		},
+		async({ attestorUrl }) => {
+			return check(attestorUrl ? { attestorUrl } : {})
+		},
+	)
+}

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

@@ -11,10 +11,11 @@ export function listTabsTool(attachRef: {
 		{
 			name: 'list_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.',
+				'Returns the open tabs of the attached browser, each with its tabId, '
+				+ 'title, and URL. Call it after `attach_browser` to pick the tabId '
+				+ 'for `start_capture`.',
 			inputSchema: { type: 'object', properties: {} },
+			annotations: { readOnlyHint: true, openWorldHint: true },
 		},
 		async() => {
 			if(!attachRef.current) {

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

@@ -18,20 +18,19 @@ export function findTool(resolveBackend: ResolveBackend): RegisteredTool {
 		{
 			name: 'find_requests_containing',
 			description:
-				'Search captured responses for any encoding of `value` (raw, '
-				+ '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 (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.',
+				'Searches captured responses for any encoding of `value` (raw, '
+				+ 'URL-, JSON-, or HTML-escaped). Returns ranked candidates with the '
+				+ 'matched variant, score, and a short snippet, to locate the '
+				+ 'request that returns a data point. Also finds split matches: when '
+				+ '`value` has several words (for example, a full name) and a '
+				+ 'response carries each word in a separate field, the candidate has '
+				+ '`splitMatch: true`; prove those per field (one redaction per '
+				+ 'part). Response bodies stay server-side.',
 			inputSchema: objectSchema(
 				{ value: { type: 'string' }, limit: { type: 'number' } },
 				['value'],
 			),
+			annotations: { readOnlyHint: true, openWorldHint: false },
 		},
 		async(args) => {
 			const backend = resolveBackend(args)

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

@@ -20,6 +20,7 @@ export function howItWorksTool(oldMode: boolean): RegisteredTool {
 				+ 'backend. Call without a topic for the overview and index. Before an '
 				+ 'unfamiliar or sensitive step, request that topic. Prefer one topic; '
 				+ '`all` returns the much larger complete guide.',
+			annotations: { readOnlyHint: true, openWorldHint: false },
 			inputSchema: {
 				type: 'object',
 				properties: {

package/src/mcp/tools/agent/live-view.ts

@@ -3,9 +3,10 @@
  * attached container browser's built-in viewer behind a public URL, so someone
  * who is not at this machine can watch it and optionally drive it.
  *
- * The server never runs, downloads or resolves cloudflared: the agent runs it
- * itself and passes the resulting `trycloudflare.com` URL back to get the link
- * to hand out.
+ * The server never runs, downloads or resolves cloudflared. The developer
+ * chooses who runs it: they run it themselves (recommended) or approve the
+ * agent running it. Either way the `trycloudflare.com` URL it prints comes
+ * back as `publicUrl` to get the link to hand out.
  *
  * Scoped to `container` mode on purpose. A `builder`-mode browser already has
  * a hosted live view at `attach_browser`'s `liveViewUrl`.
@@ -27,13 +28,19 @@ export function liveViewTools(
 			{
 				name: 'share_browser_view',
 				description:
-					'Shares an attached `container` browser with someone who is not at '
-					+ 'this machine. Step 1: call with no arguments to get the local '
-					+ 'viewer URL and the `cloudflared` command to run yourself (this '
-					+ 'server does not run it). Step 2: after cloudflared prints its '
-					+ '`https://*.trycloudflare.com` URL, call again with it as '
-					+ '`publicUrl` to get the link to relay. Treat the link as a '
-					+ 'credential. For `builder`, use the `liveViewUrl` from '
+					'Returns a link that lets someone who is not at this machine watch '
+					+ 'and drive the attached `container` browser, for example to sign '
+					+ 'in. This server opens no tunnel itself. Step 1: call with no '
+					+ 'arguments. It returns the local viewer URL, the `cloudflared` '
+					+ 'command, and two `choices`. Ask the developer to pick one before '
+					+ 'any tunnel runs: (a, recommended) they run `! cloudflared tunnel '
+					+ '--url http://localhost:<port>` themselves and paste the printed '
+					+ '`https://*.trycloudflare.com` URL; (b) they explicitly approve '
+					+ 'you running the command in the background. Never install '
+					+ '`cloudflared` without approval. Step 2: call again with the URL '
+					+ 'as `publicUrl` to get the link to relay. The link grants access '
+					+ 'to that browser session only, so share it only with the person '
+					+ 'who needs it. For `builder`, use the `liveViewUrl` from '
 					+ '`attach_browser`.',
 				inputSchema: {
 					type: 'object',
@@ -45,6 +52,7 @@ export function liveViewTools(
 						},
 					},
 				},
+				annotations: { openWorldHint: true, idempotentHint: true },
 			},
 			async(parsed) => {
 				const attached = attachRef.current
@@ -87,28 +95,47 @@ export function liveViewTools(
 							+ 'separate window is visible too.',
 							'Opening it on a phone lays the page out for that phone, with '
 							+ 'touch, pinch-zoom and the soft keyboard.',
-							'When they are done, stop the cloudflared process you started. '
-							+ 'The browser keeps running until `dispose_browser`.',
+							'When they are done, stop the cloudflared process: yourself if '
+							+ 'you started it, otherwise ask the developer. The browser '
+							+ 'keeps running until `dispose_browser`.',
 						],
 					}
 				}
 
 				const localUrl = `http://localhost:${viewerPort}`
+				const command = `cloudflared tunnel --url ${localUrl}`
 				return {
 					localViewerUrl: ensureLiveViewUrl(localUrl),
 					port: viewerPort,
-					command: `cloudflared tunnel --url ${localUrl}`,
+					command,
+					choices: [
+						{
+							id: 'developer-runs',
+							recommended: true,
+							action: `Run \`! ${command}\` in the prompt, then paste the `
+								+ 'https://*.trycloudflare.com URL it prints.',
+						},
+						{
+							id: 'agent-runs',
+							recommended: false,
+							action: 'Approve the agent to run the command in the '
+								+ 'background and read the URL from its output.',
+						},
+					],
 					_notes: [
-						'Run `command` yourself in a background process. If `cloudflared` '
-						+ 'is not installed, tell the developer and ask them to install '
-						+ 'it (https://developers.cloudflare.com/cloudflare-one/'
-						+ 'connections/connect-networks/downloads/) — do not install it '
+						'Ask the developer to choose before any tunnel runs. Do not run '
+						+ '`command` until they pick `agent-runs`.',
+						'If they pick `developer-runs`, wait for the pasted URL. If they '
+						+ 'pick `agent-runs`, run `command` in a background process and '
+						+ 'read its output for a line containing '
+						+ '`https://<words>.trycloudflare.com`.',
+						'If `cloudflared` is not installed, tell the developer and ask '
+						+ 'them to install it '
+						+ '(https://developers.cloudflare.com/cloudflare-one/'
+						+ 'connections/connect-networks/downloads/). Never install it '
 						+ 'without their approval.',
-						'Read its output for a line containing '
-						+ '`https://<words>.trycloudflare.com`. That is the public URL.',
-						'Call share_browser_view again with that value as `publicUrl` '
-						+ 'to get the link to relay. Never guess or reconstruct the '
-						+ 'hostname.',
+						'Call share_browser_view again with the URL as `publicUrl` to get '
+						+ 'the link to relay. Never guess or reconstruct the hostname.',
 						'Expose only this port. Never tunnel the browser\'s CDP port.',
 					],
 				}

package/src/mcp/tools/agent/pod-proof.ts

@@ -31,17 +31,12 @@ export function podProofTools(
 		{
 			name: 'run_proof_via_pod',
 			description:
-				'Prove the drafted recipe through the Popcorn pod\'s own TEE '
-				+ '(/reclaim/prove) instead of the local attestor SDK — this is '
-				+ 'the remote browser session\'s own api for creating a proof '
-				+ 'from that same session. Use this instead of run_proof '
-				+ 'whenever this capture\'s '
-				+ 'attach mode is "builder": the pod is the same enclave that '
-				+ 'held the browser\'s TLS session (and its country-routed egress, '
-				+ 'if any), so '
-				+ 'the proof reaches the target from the browser\'s own exit IP. '
-				+ 'No ownerAddress needed — the pod signs with the attestor\'s '
-				+ 'own TEE key, not a local credential.',
+				'Proves the drafted recipe through the remote browser pod\'s own '
+				+ 'TEE (/reclaim/prove) instead of the local attestor SDK. Use it '
+				+ 'instead of `run_proof` when the attach mode is "builder": the '
+				+ 'proof then reaches the target from the browser\'s own exit IP and '
+				+ 'country. Needs no `ownerAddress`; the pod signs with its own TEE '
+				+ 'key.',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -50,6 +45,7 @@ export function podProofTools(
 				},
 				required: ['captureId', 'draftId'],
 			},
+			annotations: { openWorldHint: true, destructiveHint: false },
 		},
 		async({ captureId, draftId }) => {
 			const apiUrl = attachRef.current?.apiUrl