@reclaimprotocol/agent 0.1.32 → 0.1.34

package/src/mcp/api/tools.ts

@@ -1,11 +1,15 @@
+import { unauthorized } from '@hapi/boom'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { ReclaimClient } from '@reclaimprotocol/client/api'
+import { ReclaimClient } from '@reclaimprotocol/client/api'
 import type {
 	IOperationArgs,
 	IOperationId
 } from '@reclaimprotocol/client/openapi'
+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'
 
 /**
@@ -22,8 +26,34 @@ function toSnakeCase(name: string): string {
 		.toLowerCase()
 }
 
-export function registerTools(server: McpServer, client: ReclaimClient) {
-	for(const [opId, shape] of Object.entries(MCP_TOOLS)) {
+/** The client for a call that presents the organization's API key. */
+export type OrgClientFactory = (orgToken: string) => ReclaimClient
+
+/**
+ * Register a tool per generated operation. Calls go out with the developer's
+ * session token, except operations only an org API key (`rorg_…`) authorizes:
+ * those take an `orgToken` input (else the server's RECLAIM_ORG_SECRET) and go
+ * out through `orgClient` with that key.
+ */
+export function registerTools(
+	server: McpServer,
+	client: ReclaimClient,
+	orgClient: OrgClientFactory = (orgToken) => new ReclaimClient({
+		baseUrl: client.baseUrl,
+		token: orgToken,
+	}),
+) {
+	for(const [opId, tool] of Object.entries(MCP_TOOLS)) {
+		const orgTokenOnly = 'orgTokenOnly' in tool && tool.orgTokenOnly === true
+		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}`,
@@ -37,13 +67,21 @@ export function registerTools(server: McpServer, client: ReclaimClient) {
 		server.registerTool(
 			toSnakeCase(opId),
 			shape,
-			async(args: unknown) => {
+			async(input: unknown) => {
 				try {
+					if(!isRecord(input)) {
+						throw new Error(`Invalid generated MCP arguments for ${opId}`)
+					}
+
+					const { orgToken, ...args } = input
 					if(!isOperationArgs(opId, args)) {
 						throw new Error(`Invalid generated MCP arguments for ${opId}`)
 					}
 
-					const result = await client.call(
+					const caller = orgTokenOnly
+						? orgClient(orgTokenFor(toSnakeCase(opId), orgToken, args))
+						: client
+					const result = await caller.call(
 						opId,
 						args,
 					)
@@ -79,3 +117,30 @@ function isOperationArgs<T extends IOperationId>(
 ): value is IOperationArgs<T> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	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, 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. 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 '
+	'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/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

@@ -116,7 +116,12 @@ export async function startMcpServer() {
 
 		// Add auto-generated tools with snake_case wrappers
 		// for every MCP-tagged operation.
-		registerTools(server, client)
+		// Org-key-only operations go out with the call's `orgToken` instead.
+		registerTools(server, client, (orgToken) => new ReclaimClient({
+			baseUrl: apiUrl(),
+			token: orgToken,
+			headers: { 'User-Agent': `${NAME}/${VERSION}` },
+		}))
 
 		if(agentToolsEnabled) {
 			agentState = buildAgentState()

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

@@ -24,6 +24,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 }
@@ -90,7 +91,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/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

@@ -27,13 +27,15 @@ 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 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',
@@ -45,6 +47,7 @@ export function liveViewTools(
 						},
 					},
 				},
+				annotations: { openWorldHint: true, idempotentHint: true },
 			},
 			async(parsed) => {
 				const attached = attachRef.current

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

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

@@ -18,9 +18,9 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 			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`.',
@@ -63,6 +63,7 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 				},
 				['requestId', 'name'],
 			),
+			annotations: { openWorldHint: false, destructiveHint: false },
 		},
 		async(args) => {
 			const backend = resolveBackend(args)

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

@@ -5,6 +5,7 @@ import type {
 } from '@reclaimprotocol/client/openapi'
 import assert from 'node:assert'
 import type { JSONSchema } from 'zod/v4/core'
+import type { KeptScriptRef } from '../../../authoring/index.ts'
 import {
 	ALLOWED_REQUESTS_HINT,
 	COOKIE_ATTACHMENT_HINT,
@@ -232,13 +233,16 @@ interface PublishArgs {
 export function createVersionFromCaptureTool(
 	client: ReclaimClient,
 	attachRef?: { current?: AttachState },
+	kept?: KeptScriptRef,
 ): RegisteredTool {
 	return defineTool<PublishArgs>(
 		{
 			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 '
@@ -306,6 +310,8 @@ export function createVersionFromCaptureTool(
 					jsUserScripts: {
 						type: 'string',
 						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 ' +
@@ -369,8 +375,10 @@ export function createVersionFromCaptureTool(
 				},
 				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
@@ -396,7 +404,7 @@ export function createVersionFromCaptureTool(
 				notes: args.notes,
 				version: ver,
 				requiredContext: args.requiredContext,
-				jsUserScripts: args.jsUserScripts,
+				jsUserScripts,
 				allowedJsRequests: args.allowedJsRequests,
 				browserRequestActions: args.browserRequestActions,
 				interceptorOptions: args.interceptorOptions,
@@ -428,12 +436,12 @@ export function createVersionFromCaptureTool(
 			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 ' +

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

@@ -13,13 +13,15 @@ export function replayTool(resolveBackend: ResolveBackend): RegisteredTool {
 		{
 			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.',
+				'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' },
@@ -27,6 +29,7 @@ export function replayTool(resolveBackend: ResolveBackend): RegisteredTool {
 				},
 				['draftId'],
 			),
+			annotations: { readOnlyHint: true, openWorldHint: true },
 		},
 		async(args) => {
 			const backend = resolveBackend(args)