@reclaimprotocol/agent 0.1.33 → 0.1.35

package/lib/mcp/api/tools.js

@@ -4,6 +4,7 @@ import assert from 'node:assert';
 import { orgSecret } from "../../consts.js";
 import { remapErrorAsResponse } from "../remap_errors.js";
 import { successResponse } from "../success-response.js";
+import { savedOrgKey } from "../tools/authenticate/org-key-store.js";
 import { MCP_TOOLS } from "./operations.gen.js";
 /**
  * The generated `MCP_TOOLS` are keyed by OpenAPI `operationId` (PascalCase,
@@ -33,6 +34,11 @@ export function registerTools(server, client, orgClient = (orgToken) => new Recl
         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(`Generated MCP operation is not in the API client: ${opId}`);
@@ -51,7 +57,7 @@ export function registerTools(server, client, orgClient = (orgToken) => new Recl
                     throw new Error(`Invalid generated MCP arguments for ${opId}`);
                 }
                 const caller = orgTokenOnly
-                    ? orgClient(orgTokenFor(toSnakeCase(opId), orgToken))
+                    ? orgClient(orgTokenFor(toSnakeCase(opId), orgToken, args))
                     : client;
                 const result = await caller.call(opId, args);
                 return successResponse(result.data);
@@ -85,12 +91,19 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 /** 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, orgToken) {
-    const token = (typeof orgToken === 'string' && orgToken) || orgSecret();
-    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.'));
+ *  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, orgToken, args) {
+    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. Run `
+        + 'issue_org_token to save one, or pass orgToken, or set '
+        + 'RECLAIM_ORG_SECRET for the MCP server.'));
     return token;
 }

package/lib/mcp/instructions.js

@@ -45,7 +45,7 @@ const BUILDER_TOPIC_FILES = {
  *  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 = {
-    '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.',
@@ -54,23 +54,23 @@ const TOPIC_SUMMARIES = {
     '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/lib/mcp/server.d.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type RegisteredTool } from '../tools/registry.ts';
-export { defineTool, type RegisteredTool, type ToolDefinition, } from '../tools/registry.ts';
+export { defineTool, type RegisteredTool, type ToolAnnotations, type ToolDefinition, } from '../tools/registry.ts';
 /**
  * Registers a list of RegisteredTool entries on a high-level McpServer.
  * Converts JSON Schema definitions to Zod and provides consistent

package/lib/mcp/server.js

@@ -15,6 +15,9 @@ export function registerToolList(server, tools) {
         server.registerTool(tool.definition.name, {
             description: tool.definition.description,
             inputSchema: toZod(tool.definition.inputSchema),
+            ...(tool.definition.annotations
+                ? { annotations: tool.definition.annotations }
+                : {}),
         }, async (args) => {
             try {
                 return successResponse(await tool.handler(args));

package/lib/mcp/start.js

@@ -11,7 +11,7 @@ import { ReclaimSdkClient } from "../old/sdk-client.js";
 import { buildOldBackendTools } from "../old/tools/build.js";
 import { NAME, VERSION } from "../pkg.js";
 import { registerTools } from "./api/tools.js";
-import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, } from "./tools/index.js";
+import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, releaseAllListeners, stopAllForwarders, } from "./tools/index.js";
 import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
 import { registerToolList } from "./server.js";
 export async function startMcpServer() {
@@ -94,7 +94,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);
     }
     const transport = new StdioServerTransport();
@@ -117,10 +117,7 @@ function installShutdownHooks(state) {
         }
         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(() => {
@@ -128,7 +125,11 @@ function installShutdownHooks(state) {
             process.exit(0);
         }, SHUTDOWN_GRACE_MS);
         timer.unref();
-        void disposeAgentState(current)
+        void Promise.all([
+            stopAllForwarders(),
+            releaseAllListeners(),
+            current && disposeAgentState(current),
+        ])
             .catch((err) => {
             LOGGER.warn({ err }, 'teardown failed');
         })

package/lib/mcp/success-response.js

@@ -6,7 +6,11 @@ export function successResponse(value) {
         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/lib/mcp/tools/agent/analyze.js

@@ -3,10 +3,10 @@ import { defineTool } from "../../server.js";
 export function analyzeTool(captures) {
     return defineTool({
         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 '
+        description: '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',
@@ -16,6 +16,7 @@ export function analyzeTool(captures) {
             },
             required: ['captureId', 'requestId'],
         },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ captureId, requestId }) => {
         const entry = captures.sessions.get(captureId);
         if (!entry) {

package/lib/mcp/tools/agent/attach.js

@@ -104,13 +104,16 @@ dependencies = {}) {
     };
     return defineTool({
         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" }).',
+        description: '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: {
@@ -153,6 +156,7 @@ dependencies = {}) {
                 },
             },
         },
+        annotations: { openWorldHint: true, destructiveHint: false },
     }, async (parsed) => {
         const persisted = state.config.read()?.browser_agent;
         // Deliberately NOT falling back to the persisted mode: which browser

package/lib/mcp/tools/agent/build.js

@@ -14,6 +14,7 @@ import { ensureAttestorCrypto } from "../../../proof/proof-core.js";
 import { analyzeTool } from "./analyze.js";
 import { attachTool } from "./attach.js";
 import { captureTools, resetCaptures } from "./capture.js";
+import { checkAttestorTool } from "./check-attestor.js";
 import { listTabsTool } from "./eval.js";
 import { howItWorksTool } from "./how-it-works.js";
 import { liveViewTools } from "./live-view.js";
@@ -21,6 +22,7 @@ import { podProofTools } from "./pod-proof.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { resetAll, sessionTools } from "./session.js";
 import { sharedAuthoringTools } from "./shared.js";
+import { startIntegrationTool } from "./start-integration.js";
 /** 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
@@ -64,6 +66,7 @@ export function buildAgentTools(client, builderClient = client, externalState) {
         tools.push(t);
     }
     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.
@@ -71,7 +74,8 @@ export function buildAgentTools(client, builderClient = client, externalState) {
         tools.push(t);
     }
     if (client) {
-        tools.push(createVersionFromCaptureTool(client, state.attach));
+        tools.push(startIntegrationTool());
+        tools.push(createVersionFromCaptureTool(client, state.attach, state.captures));
     }
     return tools;
 }

package/lib/mcp/tools/agent/capture.d.ts

@@ -1,4 +1,4 @@
-import { type DraftStore } from '../../../authoring/index.ts';
+import { type DraftStore, type KeptScriptRef } from '../../../authoring/index.ts';
 import { type CaptureSession } from '../../../cdp/capture.ts';
 import { type RegisteredTool } from '../../server.ts';
 import type { AttachState } from './attach.ts';
@@ -13,7 +13,7 @@ export interface CaptureEntry {
     tabClient: Awaited<ReturnType<AttachState['handles']['attachToTab']>>;
     drafts: DraftStore;
 }
-export interface CaptureStore {
+export interface CaptureStore extends KeptScriptRef {
     sessions: Map<string, CaptureEntry>;
     activeTab?: string;
 }

package/lib/mcp/tools/agent/capture.js

@@ -1,4 +1,4 @@
-import { makeDraftStore } from "../../../authoring/index.js";
+import { makeDraftStore, } from "../../../authoring/index.js";
 import { startCapture } from "../../../cdp/capture.js";
 import { defineTool } from "../../server.js";
 export async function resetCaptures(captures) {
@@ -7,6 +7,7 @@ export async function resetCaptures(captures) {
     }
     captures.sessions.clear();
     delete captures.activeTab;
+    delete captures.keptScript;
 }
 export function captureTools(attachRef, captures) {
     const requireAttached = () => {
@@ -17,14 +18,15 @@ export function captureTools(attachRef, captures) {
     };
     const startTool = defineTool({
         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.',
+        description: '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();
         const tabClient = await attached.handles.attachToTab(tabId);
@@ -37,13 +39,14 @@ export function captureTools(attachRef, captures) {
     });
     const stopTool = defineTool({
         name: 'stop_capture',
-        description: 'Stop recording on the given capture. '
-            + 'Captured data remains queryable until reset_session.',
+        description: '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);
         if (!entry) {
@@ -54,11 +57,11 @@ export function captureTools(attachRef, captures) {
     });
     const getTool = defineTool({
         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.',
+        description: '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: {
@@ -67,6 +70,7 @@ export function captureTools(attachRef, captures) {
             },
             required: ['captureId', 'requestId'],
         },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ captureId, requestId }) => {
         const entry = captures.sessions.get(captureId);
         if (!entry) {

package/lib/mcp/tools/agent/check-attestor.d.ts

@@ -0,0 +1,5 @@
+import { checkAttestor, type CheckAttestorOptions } from '../../../proof/check-attestor.ts';
+import { 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 declare function checkAttestorTool(check?: (opts: CheckAttestorOptions) => ReturnType<typeof checkAttestor>): RegisteredTool;

package/lib/mcp/tools/agent/check-attestor.js

@@ -0,0 +1,37 @@
+import { checkAttestor, } from "../../../proof/check-attestor.js";
+import { defineTool } from "../../server.js";
+/** `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 = checkAttestor) {
+    return defineTool({
+        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/lib/mcp/tools/agent/eval.js

@@ -5,10 +5,11 @@ import { defineTool } from "../../server.js";
 export function listTabsTool(attachRef) {
     return defineTool({
         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.',
+        description: '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) {
             throw new Error('Not attached. Call attach_browser first.');

package/lib/mcp/tools/agent/find.js

@@ -11,17 +11,16 @@ import { defineTool } from "../../../tools/registry.js";
 export function findTool(resolveBackend) {
     return defineTool({
         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.',
+        description: '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);
         const value = String(args.value);

package/lib/mcp/tools/agent/how-it-works.js

@@ -16,6 +16,7 @@ export function howItWorksTool(oldMode) {
             + '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/lib/mcp/tools/agent/live-view.js

@@ -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`.
@@ -21,13 +22,19 @@ export function liveViewTools(attachRef) {
     return [
         defineTool({
             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 '
+            description: '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',
@@ -39,6 +46,7 @@ export function liveViewTools(attachRef) {
                     },
                 },
             },
+            annotations: { openWorldHint: true, idempotentHint: true },
         }, async (parsed) => {
             const attached = attachRef.current;
             assert(attached, badRequest('No browser attached. Call attach_browser first.'));
@@ -72,27 +80,46 @@ export function liveViewTools(attachRef) {
                             + '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/lib/mcp/tools/agent/pod-proof.js

@@ -22,17 +22,12 @@ import { shapeRichProofResult } from "./proof.js";
 export function podProofTools(attachRef, captures) {
     const tool = defineTool({
         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.',
+        description: '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: {
@@ -41,6 +36,7 @@ export function podProofTools(attachRef, captures) {
             },
             required: ['captureId', 'draftId'],
         },
+        annotations: { openWorldHint: true, destructiveHint: false },
     }, async ({ captureId, draftId }) => {
         const apiUrl = attachRef.current?.apiUrl;
         assert(apiUrl, badRequest('No pod api available for this attach — run_proof_via_pod needs '