@reclaimprotocol/agent 0.1.14 → 0.1.17

package/lib/mcp/remap_errors.js

@@ -1,27 +1,20 @@
 import { isBoom } from '@hapi/boom';
-// Remap all errors here if we return different response based on error.
-// Doing this so we can reuse tool error handler that returns same response
-// across different tools or error.
-// For every other error, let them get thrown so the main try-catch
-// handles them in tool registration.
+import { errorAsToolText } from "../tools/registry.js";
+// One error shape for every MCP tool. The text comes from errorAsToolText
+// (shared with the cloud loop); Boom problems also attach structuredContent.
 export const remapErrorAsResponse = (err) => {
+    const text = errorAsToolText(err);
     // The client throws a Boom-style ProblemError, so the status lives on
     // `output.statusCode` / `problem.status`, not `status`.
     if (!isBoom(err) || !err.output?.statusCode) {
         return {
             isError: true,
-            content: [{ type: 'text', text: err.message }],
+            content: [{ type: 'text', text }],
         };
     }
-    const problemError = err;
     return {
         isError: true,
-        structuredContent: problemError.data,
-        content: [
-            {
-                type: 'text',
-                text: `${problemError.message}: ${problemError.data?.detail}`
-            }
-        ],
+        structuredContent: err.data,
+        content: [{ type: 'text', text }],
     };
 };

package/lib/mcp/start.js

@@ -1,7 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ReclaimClient } from '@reclaimprotocol/client';
-import { agentDisabled, apiToken, apiUrl, oldApiUrl, oldLogsUrl, sdkApiUrl, useOldDevtools, } from "../consts.js";
+import { ConfigStore } from "../config/store.js";
+import { agentDisabled, apiToken, apiUrl, oldApiUrl, oldLogsUrl, resolveOldMode, sdkApiUrl, } from "../consts.js";
 import { ReclaimOldClient } from "../old/client.js";
 import { resolveInitialIdentity } from "../old/identity.js";
 import { OLD_MODE_INSTRUCTIONS } from "../old/instructions.js";
@@ -9,11 +10,14 @@ 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 { buildAgentTools, buildCredentialTools, buildLocalCredentialTools, buildVerificationTools, readSession, } from "./tools/index.js";
+import { buildAgentTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, readSession, } from "./tools/index.js";
 import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
 import { registerToolList } from "./server.js";
 export async function startMcpServer() {
-    const oldMode = useOldDevtools();
+    // Mode precedence: explicit USE_OLD_DEVTOOLS env → persisted config → old.
+    // The same store instance backs the set_devtools_mode toggle below.
+    const config = new ConfigStore();
+    const oldMode = resolveOldMode(config.read()?.mode);
     const server = new McpServer({ name: NAME, version: VERSION }, {
         instructions: oldMode
             ? OLD_MODE_INSTRUCTIONS
@@ -24,6 +28,9 @@ export async function startMcpServer() {
     // deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
     // surface.
     const agentToolsEnabled = !agentDisabled();
+    // Backend-mode toggle — available in both modes and regardless of whether
+    // the agent tools are enabled, so a user can always switch either direction.
+    registerToolList(server, buildModeTools(config, oldMode));
     if (oldMode) {
         // OLD-devtools mode (the default): the legacy backend is still in
         // production while builder is built. All auto-generated builder tools

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

@@ -118,11 +118,11 @@ export function shapeRichProofResult(result, opts) {
     }
     // Trim the LLM-visible logs — full stream goes to runLogPath.
     if (result.attestorLogs !== undefined && result.attestorLogs.length > 0) {
-        out.attestorLogs = result.verified
+        const logs = result.verified
             ? warnsAndErrors(result.attestorLogs)
             : tailLogs(result.attestorLogs);
-        if (out.attestorLogs.length === 0) {
-            delete out.attestorLogs;
+        if (logs.length > 0) {
+            out.attestorLogs = logs;
         }
     }
     if (result.sentParams !== undefined) {

package/lib/mcp/tools/authenticate/authenticate.js

@@ -1,107 +1,192 @@
+import assert from 'node:assert';
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
 import { defineTool } from "../../server.js";
 import { writeSession } from "./session-cache.js";
+const SCOPE = 'openid profile email';
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000;
 export function authenticateTool(client) {
     return defineTool({
         name: 'reclaim_authenticate',
-        description: 'Authorize the CLI / MCP to make authenticated API calls by having ' +
-            'the user sign in on the dashboard. Two steps:\n\n' +
-            'Step 1 — call with no arguments. Returns a `code` and `attachUrl`. ' +
-            'Tell the user to open the URL, sign in, and authorize.\n\n' +
-            'Step 2 — once the user says they have authorized, call again ' +
-            'with the same `code` from step 1 to check if confirmed. ' +
-            'Returns `LINKED` with a 2-day bearer token when confirmed, ' +
-            '`PENDING` if not yet, or `EXPIRED` if too long has passed.\n\n' +
-            'The token is cached in ~/.reclaim/config.json automatically.\n\n' +
-            'This bearer token authenticates dashboard/org-management calls ' +
-            '(e.g. list_orgs, issuing an org secret). Programmatic verification ' +
-            'calls use a separate org secret (rorg_…, set as RECLAIM_ORG_SECRET).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                code: {
-                    type: 'string',
-                    pattern: '^[A-HJ-NP-Z2-9]{5}$',
-                    description: '5-character code from a previous step-1 call. ' +
-                        'When provided, checks whether the user has ' +
-                        'confirmed that session instead of opening a new one.',
-                },
-            },
-        },
-    }, async (args) => {
-        // Step 2: check an existing session
-        if (args.code) {
-            return checkSession(client, args.code);
-        }
-        // Step 1: open a new auth-only session
-        const sessionResult = (await client.call('CreateAttachSession'));
-        const session = sessionResult.data;
-        return {
-            status: 'PENDING',
-            code: session.code,
-            attachUrl: session.attachUrl,
-            expiresAt: session.expiresAt,
-            instructions: `Open ${session.attachUrl} in your browser, sign in, and click ` +
-                '"Authorize this device". ' +
-                'Once done, call authenticate again with code: ' +
-                `"${session.code}" to confirm.`,
-        };
-    });
+        description: 'Authorize the CLI / MCP to make authenticated API calls. Opens the ' +
+            'browser to the builder sign-in page (standard OAuth 2.0 ' +
+            'authorization-code + PKCE with a localhost redirect) and waits for ' +
+            'the user to sign in and approve. On success the access token is ' +
+            'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
+            'Call with no arguments. This bearer token authenticates ' +
+            'dashboard/org-management calls (e.g. list_orgs, issuing an org ' +
+            'secret). Programmatic verification calls use a separate org secret ' +
+            '(rorg_…, set as RECLAIM_ORG_SECRET).',
+        inputSchema: { type: 'object', properties: {} },
+    }, async () => runOAuthLoopback(client));
 }
-async function checkSession(client, code) {
-    let session;
+async function runOAuthLoopback(client) {
+    const authBase = `${client.baseUrl}/auth`;
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash('sha256').update(verifier).digest());
+    const state = base64url(randomBytes(16));
+    // Bind the callback port first: the client is registered for this exact
+    // loopback redirect, and the same client_id has to be presented again at the
+    // token endpoint (public clients authenticate by client_id alone).
+    const callback = await listenForCallback(state);
+    let token;
     try {
-        const sessionResult = (await client.call('GetAttachSession', {
-            params: { code }
+        const clientId = await registerClient(authBase, callback.redirectUri);
+        openBrowser(authorizeUrl(authBase, {
+            clientId,
+            redirectUri: callback.redirectUri,
+            challenge,
+            state,
         }));
-        session = sessionResult.data;
+        const code = await callback.code;
+        token = await exchangeCode(authBase, {
+            code,
+            verifier,
+            redirectUri: callback.redirectUri,
+            clientId,
+        });
     }
-    catch (err) {
-        const status = err.status;
-        if (status === 404) {
-            return {
-                status: 'NOT_FOUND',
-                hint: 'Session not found — it may have expired (15-min window). ' +
-                    'Call authenticate without a code to start a new session.',
-            };
-        }
-        throw new Error(`Failed to check session: ${err.message}`);
+    finally {
+        callback.close();
     }
-    if (session.status === 'LINKED') {
-        const token = session.token?.trim();
-        if (token) {
-            writeSession({
-                token,
-                expiresAt: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString(),
-            });
-            client.setToken(token);
-            return {
-                status: 'LINKED',
-                token,
-                note: 'Token cached in ~/.reclaim/config.json and active now.',
-            };
+    const expiresAt = new Date(Date.now() + token.expires_in * 1000).toISOString();
+    writeSession({ token: token.access_token, expiresAt });
+    client.setToken(token.access_token);
+    return {
+        status: 'AUTHENTICATED',
+        note: 'Access token cached in ~/.reclaim/config.json and active now.',
+        expiresAt,
+    };
+}
+/**
+ * Bind an ephemeral loopback port and start listening for the provider's
+ * redirect. Resolves as soon as the port is known — the `code` promise settles
+ * later, when the browser hits `/callback` — so the caller can register a
+ * client for this exact redirect URI before sending the user off to authorize.
+ * The ephemeral port lets any number of CLIs run concurrently. Defined below
+ * its caller per repo convention.
+ */
+async function listenForCallback(state) {
+    let resolveCode;
+    let rejectCode;
+    const code = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+    });
+    const server = createServer();
+    const timer = setTimeout(() => rejectCode(new Error('Timed out waiting for sign-in (5 min).')), CALLBACK_TIMEOUT_MS);
+    server.on('request', (req, res) => {
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        if (url.pathname !== '/callback') {
+            res.writeHead(404).end();
+            return;
         }
-        return {
-            status: 'LINKED_NO_TOKEN',
-            hint: 'Session confirmed but no token issued. ' +
-                'Restart the backend (npm run dev) and try again.',
-        };
-    }
-    if (session.status === 'EXPIRED') {
-        return {
-            status: 'EXPIRED',
-            hint: 'Session expired (15-min window passed). ' +
-                'Call authenticate without a code to start a new session.',
-        };
-    }
-    // Still PENDING
+        res.writeHead(200, { 'content-type': 'text/html' });
+        res.end('<!doctype html><meta charset=utf-8><body style="font:16px '
+            + 'system-ui;padding:3rem;text-align:center">Signed in. You can '
+            + 'close this tab and return to your terminal.</body>');
+        const authCode = url.searchParams.get('code');
+        if (!authCode || url.searchParams.get('state') !== state) {
+            // A denied or failed authorization comes back as `error`/
+            // `error_description` (RFC 6749 §4.1.2.1) — surface it verbatim.
+            const err = url.searchParams.get('error_description')
+                ?? url.searchParams.get('error');
+            rejectCode(new Error(err ?? 'Sign-in failed or was cancelled.'));
+            return;
+        }
+        resolveCode(authCode);
+    });
+    const port = await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            if (!addr || typeof addr === 'string') {
+                reject(new Error('Could not bind a local callback port.'));
+                return;
+            }
+            resolve(addr.port);
+        });
+    });
+    // Past bind, a socket error fails the pending wait rather than throwing.
+    server.on('error', (err) => rejectCode(err));
     return {
-        status: 'PENDING',
-        code: session.code,
-        attachUrl: session.attachUrl,
-        hint: 'Session is still waiting. ' +
-            `Make sure you opened ${session.attachUrl}, ` +
-            'signed in, and clicked "Authorize this device". ' +
-            `Call authenticate again with code: "${session.code}"` +
-            ' once you have done so.',
+        redirectUri: `http://127.0.0.1:${port}/callback`,
+        code,
+        close: () => {
+            clearTimeout(timer);
+            server.close();
+        },
     };
 }
+function authorizeUrl(authBase, opts) {
+    return `${authBase}/oauth2/authorize?`
+        + new URLSearchParams({
+            response_type: 'code',
+            client_id: opts.clientId,
+            redirect_uri: opts.redirectUri,
+            scope: SCOPE,
+            state: opts.state,
+            code_challenge: opts.challenge,
+            code_challenge_method: 'S256',
+        }).toString();
+}
+/** Dynamic client registration (RFC 7591) for a public PKCE client. */
+async function registerClient(authBase, redirectUri) {
+    const res = await fetch(`${authBase}/oauth2/register`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            client_name: 'Reclaim CLI',
+            redirect_uris: [redirectUri],
+            token_endpoint_auth_method: 'none',
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            scope: SCOPE,
+        }),
+    });
+    assert(res.ok, new Error(`Client registration failed (${res.status}).`));
+    const json = (await res.json());
+    assert(json.client_id, new Error('Client registration returned no client_id.'));
+    return json.client_id;
+}
+async function exchangeCode(authBase, opts) {
+    const res = await fetch(`${authBase}/oauth2/token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            code: opts.code,
+            redirect_uri: opts.redirectUri,
+            code_verifier: opts.verifier,
+            // Required even though this is a public client with no secret: it's
+            // how the token endpoint identifies the client (RFC 6749 §4.1.3).
+            client_id: opts.clientId,
+        }).toString(),
+    });
+    assert(res.ok, new Error(`Token exchange failed (${res.status}): ${await res.text()}`));
+    const json = (await res.json());
+    assert(json.access_token, new Error('Token exchange returned no access_token.'));
+    return {
+        access_token: json.access_token,
+        expires_in: json.expires_in ?? 3600,
+    };
+}
+function base64url(buf) {
+    return buf.toString('base64url');
+}
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'cmd'
+            : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        // Non-fatal: the URL is still logged for the user to open manually.
+    }
+    process.stderr.write(`\nOpen this URL to sign in:\n${url}\n\n`);
+}

package/lib/mcp/tools/authenticate/eth-key.js

@@ -15,6 +15,7 @@
  * (the eth decrypt key).
  */
 import { deriveFromPrivateKey } from '@reclaimprotocol/client';
+import assert from 'node:assert';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { privateKey, privateKeyFile } from "../../../consts.js";
@@ -25,9 +26,7 @@ export const ENV_FILE = '.env';
 /** Validate + normalize a raw Ethereum private key to lowercase 0x-hex. */
 export function normalizeEthHex(value) {
     const v = value.trim().replace(/^['"]|['"]$/g, '');
-    if (!/^(0x)?[0-9a-fA-F]{64}$/.test(v)) {
-        throw new Error('not a valid Ethereum private key (expected a 32-byte / 64-hex scalar)');
-    }
+    assert(/^(0x)?[0-9a-fA-F]{64}$/.test(v), new Error('not a valid Ethereum private key (expected a 32-byte / 64-hex scalar)'));
     return '0x' + v.replace(/^0x/, '').toLowerCase();
 }
 /** Read `RECLAIM_PRIVATE_KEY` from a dotenv file (simple KEY=VALUE parse). */

package/lib/mcp/tools/index.d.ts

@@ -1,3 +1,4 @@
 export * from './agent/index.ts';
 export * from './authenticate/index.ts';
+export * from './mode/index.ts';
 export * from './verification/index.ts';

package/lib/mcp/tools/index.js

@@ -3,4 +3,5 @@
 // individual tool files.
 export * from "./agent/index.js";
 export * from "./authenticate/index.js";
+export * from "./mode/index.js";
 export * from "./verification/index.js";

package/lib/mcp/tools/mode/index.d.ts

@@ -0,0 +1 @@
+export { buildModeTools } from './mode.ts';

package/lib/mcp/tools/mode/index.js

@@ -0,0 +1,3 @@
+// Barrel for the mode tool group (backend mode toggle). Import from here, not
+// the individual files.
+export { buildModeTools } from "./mode.js";

package/lib/mcp/tools/mode/mode.d.ts

@@ -0,0 +1,16 @@
+import type { ConfigStore } from '../../../config/store.ts';
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * The `set_devtools_mode` tool: persist which backend the MCP server targets
+ * (legacy `old` devtools vs the new `builder`). The choice is written to
+ * `~/.reclaim/config.json` and applied the NEXT time the server starts —
+ * the registered tool set, server instructions, and backend client are all
+ * fixed at connect time, so the switch requires a restart/reconnect. Follows
+ * the `attach_chrome` persist-through-config pattern.
+ *
+ * Registered in BOTH modes (so the user can switch either direction) and
+ * outside `buildAgentTools` (so it survives `RECLAIM_AGENT_DISABLED=1`). An
+ * explicit `USE_OLD_DEVTOOLS` env var still overrides the persisted value —
+ * see `resolveOldMode` in consts.ts.
+ */
+export declare function buildModeTools(config: ConfigStore, currentOldMode: boolean): RegisteredTool[];

package/lib/mcp/tools/mode/mode.js

@@ -0,0 +1,49 @@
+import { defaultConfigPath } from "../../../config/store.js";
+import { defineTool } from "../../server.js";
+/**
+ * The `set_devtools_mode` tool: persist which backend the MCP server targets
+ * (legacy `old` devtools vs the new `builder`). The choice is written to
+ * `~/.reclaim/config.json` and applied the NEXT time the server starts —
+ * the registered tool set, server instructions, and backend client are all
+ * fixed at connect time, so the switch requires a restart/reconnect. Follows
+ * the `attach_chrome` persist-through-config pattern.
+ *
+ * Registered in BOTH modes (so the user can switch either direction) and
+ * outside `buildAgentTools` (so it survives `RECLAIM_AGENT_DISABLED=1`). An
+ * explicit `USE_OLD_DEVTOOLS` env var still overrides the persisted value —
+ * see `resolveOldMode` in consts.ts.
+ */
+export function buildModeTools(config, currentOldMode) {
+    const current = currentOldMode ? 'old' : 'builder';
+    return [
+        defineTool({
+            name: 'set_devtools_mode',
+            description: 'Choose which backend the MCP server targets: "old" (legacy '
+                + 'Reclaim devtools) or "builder" (the new builder backend). '
+                + 'Persists the choice to ~/.reclaim/config.json; it takes effect '
+                + 'the next time the MCP server starts, so restart/reconnect after '
+                + 'switching. An explicit USE_OLD_DEVTOOLS env var overrides this.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    mode: { type: 'string', enum: ['old', 'builder'] },
+                },
+                required: ['mode'],
+            },
+        }, async (parsed) => {
+            config.write({ mode: parsed.mode });
+            const restartRequired = parsed.mode !== current;
+            return {
+                saved: true,
+                mode: parsed.mode,
+                effectiveNow: current,
+                restartRequired,
+                configPath: defaultConfigPath(),
+                message: restartRequired
+                    ? 'Saved. Restart / reconnect the MCP server for '
+                        + `"${parsed.mode}" mode to take effect.`
+                    : `Already running in "${parsed.mode}" mode; nothing to restart.`,
+            };
+        }),
+    ];
+}

package/lib/old/tools/publish.js

@@ -189,15 +189,86 @@ export function createVersionFromCaptureTool(client) {
                     description: 'Extra requests the customInjection script is allowed to ' +
                         'fire (e.g. pagination) — add-version ONLY, the register ' +
                         'endpoint ignores this. Each item has the same shape as ' +
-                        '`provider`, plus `multiple`/`required` (default true).',
+                        '`provider`, plus `multiple`/`required` (default true). ' +
+                        'IMPORTANT whenever a claim\'s request HAS a body: set `body` ' +
+                        'here (see its own description below) — if only a small part ' +
+                        'of the real body varies per user/run (e.g. one id field, not ' +
+                        'the whole payload), template just that part with ' +
+                        '`{{paramName}}` and keep the rest as fixed literal text; see ' +
+                        'the "bodySniff" section of the customInjection field\'s guide ' +
+                        'for the exact mechanics and a worked example.',
                     items: {
                         type: 'object',
                         properties: {
                             url: { type: 'string' },
                             method: { type: 'string' },
-                            body: { type: 'string' },
-                            responseMatches: { type: 'array' },
-                            responseRedactions: { type: 'array' },
+                            body: {
+                                type: 'string',
+                                description: 'Becomes `bodySniff: { enabled: true, template: <this ' +
+                                    'string> }` — set this whenever the request has a ' +
+                                    'body at all (skip only for a genuinely bodyless ' +
+                                    'request, typically GET). If the real body is FIXED ' +
+                                    '(identical for every user/run), put that literal body ' +
+                                    'text here verbatim. If only PART of it varies (e.g. ' +
+                                    '`{"request":1,"type":"user_info","id":"12345"}` where ' +
+                                    'only `id` differs per user), template ONLY that part: ' +
+                                    '`{"request":1,"type":"user_info",' +
+                                    '"id":"{{REQ_BODY_USER_ID}}"}` — keep everything else ' +
+                                    'as fixed literal text rather than templating the whole ' +
+                                    'body. Confirmed directly against attestor-core\'s ' +
+                                    '`hashProviderParams`: the hash embeds this string ' +
+                                    'LITERALLY, unresolved braces and all, never the real ' +
+                                    'substituted body, so a claim built with the SAME ' +
+                                    'literal template (plus a witness/extracted param per ' +
+                                    'placeholder, supplying the real value for ' +
+                                    'verification) hashes identically regardless of what ' +
+                                    'those real values are. This is the OPPOSITE of ' +
+                                    '`templateParams`\' `${var}` syntax below, which ' +
+                                    'genuinely IS substituted before hashing — do not ' +
+                                    'confuse `{{param}}` (body, never resolved) with ' +
+                                    '`${var}` (responseMatches/responseRedactions, resolved ' +
+                                    'at verify time). Before publishing, hand-verify that ' +
+                                    'substituting real sample values into this template ' +
+                                    'reproduces the real captured request body ' +
+                                    'byte-for-byte. Fallback if per-field templating keeps ' +
+                                    'mismatching (more fields vary than expected, unstable ' +
+                                    'key order, etc.) and you can\'t pin down every ' +
+                                    'variable field: template the WHOLE body as one ' +
+                                    'placeholder instead, `{{REQ_BODY_GRD}}` — the `GRD` ' +
+                                    'suffix makes it a greedy match (captures everything) ' +
+                                    'rather than the default non-greedy match, which is ' +
+                                    'needed when nothing fixed follows the placeholder. ' +
+                                    'This pins down nothing about body structure, so prefer ' +
+                                    'minimal per-field placeholders whenever you can ' +
+                                    'actually identify which fields vary.',
+                            },
+                            responseMatches: {
+                                type: 'array',
+                                description: 'Each item: `{ value: string, type?: "contains" | ' +
+                                    '"regex", invert?: boolean, isOptional?: boolean }`. ' +
+                                    '`value` must literally appear (or match, if `regex`) ' +
+                                    'somewhere in the response body for the claim to be ' +
+                                    'accepted; it commonly embeds one or more ' +
+                                    '`{{paramName}}` extraction placeholders (e.g. ' +
+                                    '`"name":"{{name_0}}"`) whose real value is redacted ' +
+                                    'out and supplied separately as a witness/extracted ' +
+                                    'param. Use `${var}` (not `{{var}}`) inside this string ' +
+                                    'only if you also declare that name in this entry\'s ' +
+                                    'own `templateParams` below — that\'s a DIFFERENT, ' +
+                                    'verify-time-substituted placeholder, resolved from the ' +
+                                    'submitted proof before hashing (unlike a body ' +
+                                    '`{{param}}`, which never resolves — see `body` above).',
+                            },
+                            responseRedactions: {
+                                type: 'array',
+                                description: 'Each item: `{ jsonPath?: string, xPath?: string, ' +
+                                    'regex?: string, hash?: string }`. Identifies WHICH ' +
+                                    'part of the response the matching `{{paramName}}` in ' +
+                                    '`responseMatches` actually redacts/extracts — e.g. ' +
+                                    '`jsonPath: "$.data.items[0].name"` for a JSON response. ' +
+                                    'Order/count should line up with `responseMatches`\' ' +
+                                    'placeholders one-to-one for a typical claim.',
+                            },
                             multiple: {
                                 type: 'boolean',
                                 description: 'Allow matching many requests. Default true.',

package/lib/provider/to-version.js

@@ -102,6 +102,10 @@ export function providerToCreateVersionRequest(providers, initialUrl, opts = {})
         ...providerToRequestSelection(req),
         multiple: req.multiple ?? true,
         required: req.required ?? true,
+        templateParamsMode: req.templateParamsMode ?? 'separate',
+        ...(req.templateParams?.length
+            ? { templateParams: req.templateParams }
+            : {}),
     }));
     const script = jsUserScripts?.trim();
     return {

package/lib/tools/registry.d.ts

@@ -1,16 +1,3 @@
-/**
- * The ONE tool primitive for the agent. A tool is authored once with
- * {@link defineTool} — `{ definition, handler }`, where the handler receives
- * args already parsed + validated against the definition's JSON Schema (via
- * zod), so the schema shown to the model and the validation applied to inbound
- * args cannot drift.
- *
- * This lives outside `mcp/` on purpose: it depends only on zod (NOT the MCP
- * SDK), so non-MCP consumers — the cloud authoring loop — can author and run
- * these tools without pulling in `@modelcontextprotocol/sdk`. The MCP-specific
- * glue (`registerToolList` onto an `McpServer`) stays in `mcp/server.ts`, which
- * re-exports this primitive for the MCP-side tool files.
- */
 import type { JSONSchema } from 'zod/v4/core';
 export interface ToolDefinition {
     name: string;
@@ -34,6 +21,12 @@ export interface RegisteredTool {
  * and the validation applied to inbound args cannot drift.
  */
 export declare function defineTool<TArgs>(definition: ToolDefinition, handler: (args: TArgs) => Promise<unknown>): RegisteredTool;
+/**
+ * Render a tool-handler error as the text every host shows the LLM.
+ * Boom errors carrying an RFC 9457 problem include its `detail`; anything
+ * else falls back to the plain message.
+ */
+export declare function errorAsToolText(err: unknown): string;
 /**
  * Adapt a tool to a host by WIDENING its input schema — add properties, mark
  * some required, optionally override the description — without touching the