@reclaimprotocol/agent 0.1.33 → 0.1.34

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 '
+    '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, frontend and '
+        + 'backend over the HTTP session API; `api=2` and result '
         + 'verification.',
-    'user-script': 'Authoring jsUserScripts / customInjection to drive '
-        + 'login-gated pages.',
+    '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/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

@@ -21,6 +21,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
@@ -71,7 +72,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/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

@@ -21,13 +21,15 @@ 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 to get the local viewer URL and the `cloudflared` '
+                + 'command for the developer to run. Step 2: after cloudflared '
+                + 'prints its `https://*.trycloudflare.com` URL, call again with it '
+                + '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 +41,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.'));

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 '

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

@@ -14,9 +14,9 @@ export function proposeTool(resolveBackend) {
     return defineTool({
         name: 'propose_provider',
         description: 'Drafts a provider from one authenticated captured request and '
-            + 'keeps captured secrets server-side. Use `targets` for every value '
-            + 'available in the same response; the result contains a `draftId` '
-            + 'and secret-free recipe. Set `shortenNames: false` to preserve an '
+            + 'keeps captured secrets server-side. Use `targets` for the data '
+            + 'points the claim needs from that response; returns a `draftId` '
+            + 'and a secret-free recipe. Set `shortenNames: false` to preserve an '
             + 'explicit parameter name, including a hidden `REQ_` or `URL_` '
             + 'prefix. For matching and naming guidance, call '
             + 'how_it_works({ topic: "draft" }) and topic `params`.',
@@ -54,6 +54,7 @@ export function proposeTool(resolveBackend) {
             target: { type: 'string' },
             hash: { type: 'string', enum: ['oprf-raw', 'oprf', 'oprf-mpc'] },
         }, ['requestId', 'name']),
+        annotations: { openWorldHint: false, destructiveHint: false },
     }, async (args) => {
         const backend = resolveBackend(args);
         const requestId = String(args.requestId);

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

@@ -1,6 +1,7 @@
 import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import type { KeptScriptRef } from '../../../authoring/index.ts';
 import { type RegisteredTool } from '../../server.ts';
 import type { AttachState } from './attach.ts';
 export declare function createVersionFromCaptureTool(client: ReclaimClient, attachRef?: {
     current?: AttachState;
-}): RegisteredTool;
+}, kept?: KeptScriptRef): RegisteredTool;

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

@@ -165,11 +165,13 @@ const BROWSER_REQUEST_ACTION_SCHEMA = {
     },
     required: ['id', 'origin', 'path', 'method'],
 };
-export function createVersionFromCaptureTool(client, attachRef) {
+export function createVersionFromCaptureTool(client, attachRef, kept) {
     return defineTool({
         name: 'create_provider_version_from_capture',
         description: 'Creates a new immutable provider version after `run_proof` succeeds. '
-            + 'Pass exactly one `provider` or `providers` value returned by '
+            + 'Publishes the navigation script kept by `test_user_script` as '
+            + '`jsUserScripts` unless `jsUserScripts` is passed. Pass exactly '
+            + 'one `provider` or `providers` value returned by '
             + '`propose_provider`; do not rebuild the recipe. The default is a '
             + 'patch bump, or use `bump` or an explicitly requested higher '
             + '`version`. The new version remains a draft until published or '
@@ -230,7 +232,9 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 },
                 jsUserScripts: {
                     type: 'string',
-                    description: USER_SCRIPT_HINT +
+                    description: 'Defaults to the script kept by `test_user_script` with ' +
+                        '`keep: true`; pass it only to override. ' +
+                        USER_SCRIPT_HINT +
                         ' Stored as webSettings.jsUserScripts; the Builder ' +
                         'verification client runs it before every page load ' +
                         '(including before navigating to initialUrl), matching ' +
@@ -288,7 +292,9 @@ export function createVersionFromCaptureTool(client, attachRef) {
             },
             required: ['providerId', 'initialUrl'],
         },
+        annotations: { openWorldHint: true, destructiveHint: false },
     }, async (args) => {
+        const jsUserScripts = args.jsUserScripts ?? kept?.keptScript?.script;
         // Exactly one of `provider` / `providers` — normalize to an array.
         const hasMany = Array.isArray(args.providers) && args.providers.length > 0;
         const hasOne = !!args.provider;
@@ -306,7 +312,7 @@ export function createVersionFromCaptureTool(client, attachRef) {
             notes: args.notes,
             version: ver,
             requiredContext: args.requiredContext,
-            jsUserScripts: args.jsUserScripts,
+            jsUserScripts,
             allowedJsRequests: args.allowedJsRequests,
             browserRequestActions: args.browserRequestActions,
             interceptorOptions: args.interceptorOptions,
@@ -332,11 +338,11 @@ export function createVersionFromCaptureTool(client, attachRef) {
         const attached = attachRef?.current;
         notes.push(...postPublishBrowserNotes(attached, {
             initialUrl: args.initialUrl,
-            hasUserScript: !!args.jsUserScripts?.trim(),
+            hasUserScript: !!jsUserScripts?.trim(),
             hasInterceptor: !!args.interceptorOptions,
         }));
         // Let the developer know how and when the script runs.
-        if (args.jsUserScripts?.trim()) {
+        if (jsUserScripts?.trim()) {
             notes.push('jsUserScripts will run in the Builder verification client before ' +
                 'every page load (before navigating to initialUrl), matching ' +
                 'old-devtool customInjection. window.Reclaim is available for ' +

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

@@ -10,17 +10,20 @@ import { defineTool } from "../../../tools/registry.js";
 export function replayTool(resolveBackend) {
     return defineTool({
         name: 'replay_request',
-        description: 'Validate the drafted recipe before proving — confirm its selectors '
-            + 'extract the target value. Returns diagnostics; run before '
-            + 'proving. Set `withoutSecrets: true` for the AUTH-BOUND check: it '
-            + 're-issues the request with NO secrets/cookies (an anonymous '
-            + 'visitor). If the values still extract (valid:true), the endpoint '
-            + 'is PUBLIC and the proof would not bind to the user — reject it '
-            + 'and find an auth-bound request instead.',
+        description: 'Re-sends the drafted request from inside the attached authoring '
+            + 'browser (not from this machine) and checks that its selectors '
+            + 'extract the target data points. Captured secrets stay server-side '
+            + 'and are not returned. Returns diagnostics. Run it before '
+            + '`run_proof`. With `withoutSecrets: true`, sends the request with '
+            + 'no cookies or auth headers, like an anonymous visitor. If the '
+            + 'values still extract (`valid: true`), the endpoint is public and '
+            + 'the proof would not bind to the user: choose an auth-bound '
+            + 'request instead.',
         inputSchema: objectSchema({
             draftId: { type: 'string' },
             withoutSecrets: { type: 'boolean' },
         }, ['draftId']),
+        annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {
         const backend = resolveBackend(args);
         const draft = backend.drafts.get(String(args.draftId));

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

@@ -5,10 +5,13 @@ export function sessionTools(attachRef, captures) {
     return [
         defineTool({
             name: 'get_session',
-            description: 'Report the current attach state, the live captureIds, and the '
-                + 'persisted browser config. Call it to check whether a browser is '
-                + 'still attached before reattaching, or to recover a captureId.',
+            description: 'Returns the current attach state, the live captureIds, the '
+                + 'persisted browser config, and the navigation script kept by '
+                + '`test_user_script`. Call it to check whether a browser is still '
+                + 'attached before reattaching, or to recover a captureId or the '
+                + 'kept script.',
             inputSchema: { type: 'object', properties: {} },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, async () => ({
             config: attachRef.config.read()?.browser_agent,
             attached: Boolean(attachRef.current),
@@ -19,22 +22,27 @@ export function sessionTools(attachRef, captures) {
             orgId: attachRef.current?.orgId,
             captures: [...captures.sessions.keys()],
             activeTab: captures.activeTab,
+            keptUserScript: captures.keptScript?.script,
         })),
         defineTool({
             name: 'dispose_browser',
-            description: 'Stop captures, disconnect the current browser, and immediately '
-                + 'delete a Builder-hosted Popcorn session. Custom CDP sessions '
-                + 'are disconnected but never deleted by Reclaim.',
+            description: 'Stops captures, disconnects the current browser, and deletes a '
+                + 'Builder-hosted browser session at once. Clears the kept '
+                + 'navigation script. Reclaim disconnects a custom CDP browser but '
+                + 'never deletes it.',
             inputSchema: { type: 'object', properties: {} },
+            annotations: { destructiveHint: true, openWorldHint: true },
         }, async () => {
             await resetAll(attachRef, captures);
             return { disposed: true };
         }),
         defineTool({
             name: 'reset_session',
-            description: 'Stop all captures and clear capture state — drops every '
-                + 'session\'s drafts and their in-memory secrets.',
+            description: 'Stops all captures and clears capture state, dropping every '
+                + 'draft and its in-memory secrets. Also disconnects the browser '
+                + 'and clears the kept navigation script.',
             inputSchema: { type: 'object', properties: {} },
+            annotations: { destructiveHint: true, openWorldHint: true },
         }, async () => {
             await resetAll(attachRef, captures);
             return { reset: true };

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

@@ -32,12 +32,13 @@ function withLocalOprfMode(provider) {
 /** The local backend for one capture: drive its tab over CDP, read its
  *  captured requests, prove via the in-process attestor, replay by re-fetching
  *  FROM INSIDE the tab (real cookies/session — see proof/page-replay.ts). */
-function localBackend(entry) {
+function localBackend(entry, kept) {
     const { tabClient, session, drafts } = entry;
     const sendCdp = (method, params) => {
         return tabClient.send(method, params ?? {});
     };
     return {
+        kept,
         capture: session,
         drafts,
         sendCdp,
@@ -131,7 +132,7 @@ export function sharedAuthoringTools(captures) {
             throw new Error(`no capture ${captureId} — call start_capture first `
                 + '(it has been reset or never started).');
         }
-        return localBackend(entry);
+        return localBackend(entry, captures);
     };
     return authoringTools(resolveBackend).map((tool) => {
         if (tool.definition.name === 'run_proof') {