@reclaimprotocol/agent 0.1.0 → 0.1.1

package/lib/mcp/credentials/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve the Reclaim cache directory (`~/.reclaim`). Honours the
+ * `RECLAIM_HOME` env var as an override so tests can sandbox writes.
+ */
+export declare function reclaimHome(): string;
+export declare function credentialsCachePath(): string;
+/**
+ * Walk up from `start` until we find a directory containing one of
+ * the project-root markers, then return that directory. Falls back
+ * to `start` if no marker is found within 8 levels.
+ */
+export declare function findProjectRoot(start?: string): string;

package/lib/mcp/credentials/paths.js

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * Resolve the Reclaim cache directory (`~/.reclaim`). Honours the
+ * `RECLAIM_HOME` env var as an override so tests can sandbox writes.
+ */
+export function reclaimHome() {
+    return process.env.RECLAIM_HOME || join(homedir(), '.reclaim');
+}
+export function credentialsCachePath() {
+    return join(reclaimHome(), 'credentials.json');
+}
+/**
+ * Walk up from `start` until we find a directory containing one of
+ * the project-root markers, then return that directory. Falls back
+ * to `start` if no marker is found within 8 levels.
+ */
+export function findProjectRoot(start = process.cwd()) {
+    const markers = ['.git', 'package.json', 'pyproject.toml', 'Cargo.toml'];
+    let dir = resolve(start);
+    for (let i = 0; i < 8; i++) {
+        for (const m of markers) {
+            if (existsSync(join(dir, m))) {
+                return dir;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return start;
+}

package/lib/mcp/credentials/poll.d.ts

@@ -0,0 +1,27 @@
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import type { components } from '../../types/openapi.gen.ts';
+type Session = components['schemas']['CredentialAttachSession'];
+type PollResult = {
+    outcome: 'linked';
+    token?: string;
+    orgId?: string;
+} | {
+    outcome: 'expired';
+} | {
+    outcome: 'timeout';
+    elapsed: number;
+    attachUrl: string;
+} | {
+    outcome: 'error';
+    message: string;
+};
+/**
+ * Poll GET /credentials/attach/sessions/{code} until the session is
+ * LINKED or we give up, whichever comes first.
+ *
+ * Errors inside the loop are surfaced immediately after MAX_CONSECUTIVE_ERRORS
+ * rather than being silently swallowed — this is what tells the agent that
+ * e.g. the confirmation POST failed or the server restarted.
+ */
+export declare function pollUntilLinked(client: ReclaimClient, session: Pick<Session, 'code' | 'attachUrl' | 'expiresAt'>, onToken?: (token: string) => void): Promise<PollResult>;
+export {};

package/lib/mcp/credentials/poll.js

@@ -0,0 +1,61 @@
+// How long to poll before giving up and telling the user what to do.
+// Shorter than the 15-min server TTL on purpose — agents can't block long.
+const POLL_TIMEOUT_MS = 3 * 60_000; // 3 minutes
+const POLL_INTERVAL_MS = 5_000; // 5 seconds
+const MAX_CONSECUTIVE_ERRORS = 5;
+/**
+ * Poll GET /credentials/attach/sessions/{code} until the session is
+ * LINKED or we give up, whichever comes first.
+ *
+ * Errors inside the loop are surfaced immediately after MAX_CONSECUTIVE_ERRORS
+ * rather than being silently swallowed — this is what tells the agent that
+ * e.g. the confirmation POST failed or the server restarted.
+ */
+export async function pollUntilLinked(client, session, onToken) {
+    const sessionExpiry = new Date(session.expiresAt).getTime();
+    const deadline = Math.min(sessionExpiry, Date.now() + POLL_TIMEOUT_MS);
+    const startedAt = Date.now();
+    let consecutiveErrors = 0;
+    while (Date.now() < deadline) {
+        await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+        let polled;
+        try {
+            polled = await client.call('GetAttachSession', {
+                params: { code: session.code },
+                query: {}, body: {},
+            });
+            consecutiveErrors = 0;
+        }
+        catch (err) {
+            consecutiveErrors++;
+            if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+                return {
+                    outcome: 'error',
+                    message: `Polling failed ${consecutiveErrors} times in a row: `
+                        + err.message
+                        + '. The session confirmation may have failed — try opening '
+                        + session.attachUrl
+                        + ' again and confirming, then retry.',
+                };
+            }
+            continue; // transient error, retry
+        }
+        if (polled.status === 'LINKED') {
+            const token = polled.token?.trim();
+            if (token) {
+                onToken?.(token);
+            }
+            return {
+                outcome: 'linked',
+                token,
+                orgId: polled.linkedOrgId,
+            };
+        }
+        if (polled.status === 'EXPIRED') {
+            return { outcome: 'expired' };
+        }
+        // status === 'PENDING' → keep polling
+    }
+    const elapsed = Math.round((Date.now() - startedAt) / 60_000);
+    return { outcome: 'timeout', elapsed, attachUrl: session.attachUrl };
+}

package/lib/mcp/{tools/credentials → credentials}/resolve-owner-key.d.ts

@@ -1,4 +1,4 @@
-import { type RegisteredTool } from '../../server.ts';
+import { type RegisteredTool } from '../server.ts';
 /**
  * Decide which app credential `run_proof` should sign with, BEFORE
  * calling it. `run_proof` requires an `ownerAddress` and does no

package/lib/mcp/{tools/credentials → credentials}/resolve-owner-key.js

@@ -1,6 +1,6 @@
 import { deriveFromPrivateKey } from '@reclaimprotocol/client';
-import { findProjectRoot } from "../../../paths.js";
-import { defineTool } from "../../server.js";
+import { findProjectRoot } from "../../paths.js";
+import { defineTool } from "../server.js";
 import { suggestCredentialForDir } from "./cache.js";
 import { readPrivateKeyFromEnvFile } from "./env-file.js";
 /**

package/lib/mcp/credentials/session-cache.d.ts

@@ -0,0 +1,14 @@
+export type CachedSession = {
+    token: string;
+    /** ISO timestamp when the token expires (2 days from issue). */
+    expiresAt: string;
+    /** Email of the user who authorized (if available). */
+    email?: string;
+};
+/** Persist a session token to ~/.reclaim/session.json (0600). */
+export declare function writeSession(session: CachedSession): void;
+/**
+ * Read the cached session, returning it only if the token is still
+ * valid (not yet expired). Returns undefined on any error.
+ */
+export declare function readSession(): CachedSession | undefined;

package/lib/mcp/credentials/session-cache.js

@@ -0,0 +1,42 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { reclaimHomeDirPath } from "../../paths.js";
+// Separate from credentials.json — sessions expire, credentials don't.
+function sessionCachePath() {
+    return join(reclaimHomeDirPath(), 'session.json');
+}
+/** Persist a session token to ~/.reclaim/session.json (0600). */
+export function writeSession(session) {
+    const dir = reclaimHomeDirPath();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    chmodSync(dir, 0o700);
+    const path = sessionCachePath();
+    writeFileSync(path, JSON.stringify(session, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+/**
+ * Read the cached session, returning it only if the token is still
+ * valid (not yet expired). Returns undefined on any error.
+ */
+export function readSession() {
+    const path = sessionCachePath();
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const s = JSON.parse(raw);
+        if (!s.token || !s.expiresAt) {
+            return undefined;
+        }
+        if (new Date(s.expiresAt) <= new Date()) {
+            return undefined; // expired
+        }
+        return s;
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/mcp/{tools/credentials → credentials}/status.d.ts

@@ -1,3 +1,3 @@
 import { type ReclaimClient } from '@reclaimprotocol/client';
-import { type RegisteredTool } from '../../server.ts';
+import { type RegisteredTool } from '../server.ts';
 export declare function statusTool(client: ReclaimClient): RegisteredTool;

package/lib/mcp/credentials/status.js

@@ -0,0 +1,76 @@
+import { deriveFromPrivateKey, } from '@reclaimprotocol/client';
+import { findProjectRoot } from "../../paths.js";
+import { defineTool } from "../server.js";
+import { findCached, suggestCredentialForDir } from "./cache.js";
+export function statusTool(client) {
+    return defineTool({
+        name: 'reclaim_status',
+        description: 'Report the live mode (SANDBOX | PRODUCTION | REVOKED) ' +
+            'of a Reclaim app credential. Pass `address` — or omit it ' +
+            'to derive the address from RECLAIM_PRIVATE_KEY, falling ' +
+            'back to the best cached credential for this directory. ' +
+            'Useful to confirm a credential is linked to an org ' +
+            'with billing before running a production flow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                address: {
+                    type: 'string',
+                    pattern: '^0x[0-9a-fA-F]{40}$',
+                    description: 'Lowercase ETH address. Defaults to the address ' +
+                        'derived from RECLAIM_PRIVATE_KEY, then the cached ' +
+                        'credential suggested for the current directory.',
+                },
+            },
+        },
+    }, async (args) => {
+        let address = args.address?.toLowerCase();
+        if (!address && process.env.RECLAIM_PRIVATE_KEY) {
+            address = deriveFromPrivateKey(process.env.RECLAIM_PRIVATE_KEY).address;
+        }
+        if (!address) {
+            address = suggestCredentialForDir(findProjectRoot(process.cwd()))
+                ?.credential.address;
+        }
+        if (!address) {
+            throw new Error('No address given, RECLAIM_PRIVATE_KEY is not set, and the ' +
+                'cache is empty. Run issue_credentials or import_credentials ' +
+                'first.');
+        }
+        try {
+            const credResult = (await client.call('GetCredentialByAddress', {
+                params: { address },
+            }));
+            const cred = credResult.data;
+            return {
+                address: cred.address,
+                mode: cred.mode,
+                orgId: cred.orgId,
+                label: cred.label,
+                revokedAt: cred.revokedAt,
+                lastUsedAt: cred.lastUsedAt,
+            };
+        }
+        catch (err) {
+            // Anonymous credentials are not registered server-side, so a
+            // 404 just means "local-only" — which is SANDBOX. Report what
+            // the local cache knows. Other errors propagate. The client
+            // throws a Boom-style ProblemError, so the status lives on
+            // `output.statusCode` / `problem.status`, not `status`.
+            const e = err;
+            const code = e.status ?? e.output?.statusCode ?? e.problem?.status;
+            if (code !== 404) {
+                throw err;
+            }
+            const cached = findCached(address);
+            return {
+                address,
+                mode: 'SANDBOX',
+                ...(cached?.label ? { label: cached.label } : {}),
+                note: 'Local-only credential — not registered with the server. ' +
+                    'It operates in SANDBOX. Link it to an org with billing ' +
+                    '(via link_credential) to reach PRODUCTION.',
+            };
+        }
+    });
+}

package/lib/mcp/instructions.d.ts

@@ -0,0 +1 @@
+export declare const BUILDER_MODE_INSTRUCTIONS: string;

package/lib/mcp/instructions.js

@@ -0,0 +1,11 @@
+/**
+ * MCP server instructions shown to the LLM when running in BUILDER mode
+ * (`USE_OLD_DEVTOOLS=false`). The prose lives in `skill/builder-mode.md`
+ * (published via the `files` array) so it can be edited as markdown without
+ * touching code. The path resolves identically from `src/mcp` (dev) and
+ * `lib/mcp` (published) — both are two levels below the package root.
+ * Old-devtools mode has its own reduced set in `../old/instructions.ts`.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const BUILDER_MODE_INSTRUCTIONS = readFileSync(fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)), 'utf8').trim();

package/lib/mcp/register.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Factory entry-point for embedding the reclaim-agent's MCP tools into
+ * a host MCP server. Two consumers:
+ *
+ *   - The agent's own standalone `src/index.ts` (uses `ReclaimMcpServer`,
+ *     the low-level wrapper around `@modelcontextprotocol/sdk`'s Server).
+ *   - `@reclaimprotocol/client`'s MCP server (uses `McpServer`, the
+ *     high-level SDK wrapper). Calls `registerAgentTools` to fold the
+ *     agent's 16 tools alongside its auto-generated API tools.
+ *
+ * Shared state — Chrome attach state, capture store, secret store — is
+ * built once per server and threaded through every tool factory.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ReclaimClient } from '@reclaimprotocol/client';
+import { ConfigStore } from '../config/store.ts';
+import { type AttachState } from './tools/attach.ts';
+import { type CaptureStore } from './tools/capture.ts';
+import { type SecretStore } from './tools/propose.ts';
+import { type RegisteredTool } from './server.ts';
+export interface AgentState {
+    attach: {
+        current?: AttachState;
+        config: ConfigStore;
+    };
+    captures: CaptureStore;
+    secrets: SecretStore;
+}
+export declare function buildAgentState(): AgentState;
+/** Build the flat list of `RegisteredTool` entries. Useful when the host
+ *  uses our internal `ReclaimMcpServer` interface (`.register(tool)`).
+ *  Pass `client` to include `create_provider_version_from_capture`. */
+export declare function buildAgentTools(state: AgentState, client?: ReclaimClient): RegisteredTool[];
+/** Register agent tools on `@reclaimprotocol/client`'s McpServer. Mirrors
+ *  the same shape as builder's auto-generated `registerTools(server, client)`
+ *  in `mcp/api/tools.ts`.
+ *  Pass `client` to include `create_provider_version_from_capture`. */
+export declare function registerAgentTools(server: McpServer, state?: AgentState, client?: ReclaimClient): void;

package/lib/mcp/register.js

@@ -0,0 +1,80 @@
+/**
+ * Factory entry-point for embedding the reclaim-agent's MCP tools into
+ * a host MCP server. Two consumers:
+ *
+ *   - The agent's own standalone `src/index.ts` (uses `ReclaimMcpServer`,
+ *     the low-level wrapper around `@modelcontextprotocol/sdk`'s Server).
+ *   - `@reclaimprotocol/client`'s MCP server (uses `McpServer`, the
+ *     high-level SDK wrapper). Calls `registerAgentTools` to fold the
+ *     agent's 16 tools alongside its auto-generated API tools.
+ *
+ * Shared state — Chrome attach state, capture store, secret store — is
+ * built once per server and threaded through every tool factory.
+ */
+import { setCryptoImplementation } from '@reclaimprotocol/tls';
+import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto';
+import { ConfigStore } from "../config/store.js";
+import { analyzeTool } from "./tools/analyze.js";
+import { attachTool } from "./tools/attach.js";
+import { captureTools } from "./tools/capture.js";
+import { browserTools } from "./tools/eval.js";
+import { findTool } from "./tools/find.js";
+import { proofTool } from "./tools/proof.js";
+import { makeSecretStore, proposeTool, } from "./tools/propose.js";
+import { createVersionFromCaptureTool } from "./tools/publish.js";
+import { replayTool } from "./tools/replay.js";
+import { sessionTools } from "./tools/session.js";
+import { registerToolList } from "./server.js";
+let cryptoInitialized = false;
+/** One-time crypto backend init for @reclaimprotocol/tls. The package
+ *  ships with an empty `crypto = {}` and defers backend choice to the
+ *  caller; without this, the first proof call dies inside the SDK with
+ *  `crypto.randomBytes is not a function`. */
+function ensureCryptoInit() {
+    if (cryptoInitialized) {
+        return;
+    }
+    setCryptoImplementation(webcryptoCrypto);
+    cryptoInitialized = true;
+}
+export function buildAgentState() {
+    return {
+        attach: { config: new ConfigStore() },
+        captures: { sessions: new Map() },
+        secrets: makeSecretStore(),
+    };
+}
+/** Build the flat list of `RegisteredTool` entries. Useful when the host
+ *  uses our internal `ReclaimMcpServer` interface (`.register(tool)`).
+ *  Pass `client` to include `create_provider_version_from_capture`. */
+export function buildAgentTools(state, client) {
+    ensureCryptoInit();
+    const tools = [];
+    tools.push(attachTool(state.attach));
+    for (const t of captureTools(state.attach, state.captures)) {
+        tools.push(t);
+    }
+    tools.push(findTool(state.captures));
+    for (const t of browserTools(state.attach)) {
+        tools.push(t);
+    }
+    for (const t of sessionTools(state.attach, state.captures, state.secrets)) {
+        tools.push(t);
+    }
+    tools.push(analyzeTool(state.captures));
+    tools.push(proposeTool(state.captures, state.secrets));
+    tools.push(replayTool(state.secrets));
+    tools.push(proofTool(state.secrets));
+    if (client) {
+        tools.push(createVersionFromCaptureTool(client));
+    }
+    return tools;
+}
+/** Register agent tools on `@reclaimprotocol/client`'s McpServer. Mirrors
+ *  the same shape as builder's auto-generated `registerTools(server, client)`
+ *  in `mcp/api/tools.ts`.
+ *  Pass `client` to include `create_provider_version_from_capture`. */
+export function registerAgentTools(server, state, client) {
+    const s = state ?? buildAgentState();
+    registerToolList(server, buildAgentTools(s, client));
+}

package/lib/mcp/server.d.ts

@@ -1,9 +1,9 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type JSONSchema } from 'zod-from-json-schema';
+import type { JSONSchema } from 'zod/v4/core';
 export interface ToolDefinition {
     name: string;
     description: string;
-    inputSchema: JSONSchema;
+    inputSchema: JSONSchema.ObjectSchema;
 }
 export interface RegisteredTool {
     definition: ToolDefinition;

package/lib/mcp/server.js

@@ -1,7 +1,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { convertJsonSchemaToZod } from 'zod-from-json-schema';
+import { toZod } from "./api/to-zod.js";
 import { remapErrorAsResponse } from "./remap_errors.js";
 /**
  * Define a tool with a single inputSchema (JSON Schema) used as the
@@ -11,7 +11,7 @@ import { remapErrorAsResponse } from "./remap_errors.js";
  * to inbound args cannot drift.
  */
 export function defineTool(definition, handler) {
-    const schema = convertJsonSchemaToZod(definition.inputSchema);
+    const schema = toZod(definition.inputSchema);
     return {
         definition,
         handler: async (raw) => {
@@ -29,7 +29,7 @@ export function registerToolList(server, tools) {
     for (const tool of tools) {
         server.registerTool(tool.definition.name, {
             description: tool.definition.description,
-            inputSchema: convertJsonSchemaToZod(tool.definition.inputSchema),
+            inputSchema: toZod(tool.definition.inputSchema),
         }, async (args) => {
             try {
                 return {

package/lib/mcp/start.js

@@ -8,13 +8,16 @@ import { OLD_MODE_INSTRUCTIONS } from "../old/instructions.js";
 import { buildOldBackendTools } from "../old/tools/build.js";
 import { NAME, VERSION } from "../pkg.js";
 import { registerTools } from "./api/tools.js";
-import { buildAgentTools } from "./tools/agent/build.js";
-import { buildCredentialTools, buildLocalCredentialTools, } from "./tools/credentials/build.js";
-import { readSession } from "./tools/credentials/session-cache.js";
+import { buildAgentTools, buildCredentialTools, buildLocalCredentialTools, 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();
-    const server = new McpServer({ name: NAME, version: VERSION }, oldMode ? { instructions: OLD_MODE_INSTRUCTIONS } : undefined);
+    const server = new McpServer({ name: NAME, version: VERSION }, {
+        instructions: oldMode
+            ? OLD_MODE_INSTRUCTIONS
+            : BUILDER_MODE_INSTRUCTIONS,
+    });
     // Agent tools (Chrome CDP capture, provider synthesis, replay, proof) are
     // backend-independent and registered in both modes. Skipped in hosted
     // deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
@@ -51,6 +54,9 @@ export async function startMcpServer() {
         // collision instead of one tool silently shadowing the other.
         // Register credential tools for ETH credential management.
         registerToolList(server, buildCredentialTools(client));
+        // Higher-level verification orchestrations (e.g. fetch + decrypt result).
+        // Authenticates with RECLAIM_ORG_SECRET, not the session client.
+        registerToolList(server, buildVerificationTools());
         // Add auto-generated tools with snake_case wrappers
         // for every MCP-tagged operation.
         registerTools(server, client);

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

@@ -11,9 +11,8 @@
  * Shared state — Chrome attach state, capture store, secret store — is
  * built once per server and threaded through every tool factory.
  */
-import { setCryptoImplementation } from '@reclaimprotocol/tls';
-import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto';
 import { ConfigStore } from "../../../config/store.js";
+import { ensureAttestorCrypto } from "../../../proof/proof-core.js";
 import { analyzeTool } from "./analyze.js";
 import { attachTool } from "./attach.js";
 import { captureTools } from "./capture.js";
@@ -24,18 +23,6 @@ import { makeSecretStore, proposeTool, } from "./propose.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { replayTool } from "./replay.js";
 import { sessionTools } from "./session.js";
-let cryptoInitialized = false;
-/** One-time crypto backend init for @reclaimprotocol/tls. The package
- *  ships with an empty `crypto = {}` and defers backend choice to the
- *  caller; without this, the first proof call dies inside the SDK with
- *  `crypto.randomBytes is not a function`. */
-function ensureCryptoInit() {
-    if (cryptoInitialized) {
-        return;
-    }
-    setCryptoImplementation(webcryptoCrypto);
-    cryptoInitialized = true;
-}
 function buildAgentState() {
     return {
         attach: { config: new ConfigStore() },
@@ -50,7 +37,7 @@ function buildAgentState() {
  *  capture/proof tools — old mode supplies its own publish tool. */
 export function buildAgentTools(client) {
     const state = buildAgentState();
-    ensureCryptoInit();
+    ensureAttestorCrypto();
     const tools = [];
     tools.push(attachTool(state.attach));
     for (const t of captureTools(state.attach, state.captures)) {

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

@@ -0,0 +1,2 @@
+export { buildAgentTools } from './build.ts';
+export type { AgentState } from './build.ts';

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

@@ -0,0 +1,3 @@
+// Barrel for the agent tool group (Chrome CDP capture, provider synthesis,
+// replay, zkTLS proof). Import from here, not the individual files.
+export { buildAgentTools } from "./build.js";

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

@@ -103,11 +103,6 @@ export function proofTool(secrets) {
         inputSchema: {
             type: 'object',
             properties: {
-                // `type: 'object'` is required so MCP clients (the LLM)
-                // serialize the value as an object, not a JSON-stringified
-                // string. `properties: {}` is required so zod-from-json-schema
-                // compiles to a passthrough instead of strict-strip — leaving
-                // it off makes the server receive `{}`.
                 provider: { type: 'object', properties: {} },
                 secretParamsRef: { type: 'string' },
                 attestorUrl: { type: 'string' },
@@ -132,7 +127,7 @@ export function proofTool(secrets) {
             }
             resolved = r;
         }
-        const result = await runAttestorProof(provider, resolved, attestorUrl, ownerAddress);
+        const result = await runAttestorProof(provider, resolved, { attestorUrl, ownerAddress });
         // Persist the full claim to disk for the dev to inspect/share.
         let claimPath;
         if (result.proof !== undefined && result.proof !== null) {

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

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { draftProvider } from "../../../provider/draft.js";
 import { OPRF_MAX_BYTES } from "../../../provider/matcher.js";
+import { verificationWarnings } from "../../../provider/verification-checks.js";
 import { defineTool } from "../../server.js";
 export function makeSecretStore() {
     const map = new Map();
@@ -27,7 +28,11 @@ export function proposeTool(captures, secrets) {
             'cleartext. Skill should ask the dev first. `oprf-raw` ' +
             'is the only variant that runs ' +
             'without external deps; `oprf` needs gnark (Linux/macOS), ' +
-            '`oprf-mpc` needs a TEE attestor.',
+            '`oprf-mpc` needs a TEE attestor. ' +
+            'The response may include `verificationWarnings` — advisory ' +
+            'author-only decisions (e.g. a user-specific URL part needing ' +
+            'the {{context.<name>}}-vs-bare call). Surface each to the ' +
+            'dev verbatim and resolve before publishing.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -70,6 +75,12 @@ export function proposeTool(captures, secrets) {
             }
         }
         const secretParamsRef = secrets.put(realSecrets);
-        return { provider, secretRefs, secretParamsRef };
+        const warnings = verificationWarnings(provider);
+        return {
+            provider,
+            secretRefs,
+            secretParamsRef,
+            ...(warnings.length ? { verificationWarnings: warnings } : {}),
+        };
     });
 }

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

@@ -10,8 +10,16 @@ export function createVersionFromCaptureTool(client) {
             'hand-construct that shape or call create_provider_version directly. ' +
             'Omit `version` to have the tool auto-select the next available ' +
             'version (it lists existing versions and bumps past the highest). ' +
-            'For PRIVATE verifications the version goes live immediately; ' +
-            'for PUBLIC ones call submit_provider_version_for_review afterwards.',
+            'The version lands on the draft branch — to go live, call ' +
+            '`publish_provider_version` (PRIVATE) or ' +
+            '`submit_provider_version_for_review` (PUBLIC) afterwards. ' +
+            '`requiredContext` is derived from any {{context.<name>}} ' +
+            'placeholders and returned on the created version — when ' +
+            'present, tell the dev verbatim which context fields consumers ' +
+            'MUST send when creating sessions (verification matches those ' +
+            'values exactly; a missing field is a 400 at session create). ' +
+            'Refine types/descriptions via `update_provider_version` while ' +
+            'still on draft.',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -11,11 +11,6 @@ export function replayTool(secrets) {
         inputSchema: {
             type: 'object',
             properties: {
-                // `type: 'object'` is required so MCP clients (the LLM)
-                // serialize the value as an object, not a JSON-stringified
-                // string. `properties: {}` is required so zod-from-json-schema
-                // compiles to a passthrough instead of strict-strip — leaving
-                // it off makes the server receive `{}`.
                 provider: { type: 'object', properties: {} },
                 secretParamsRef: { type: 'string' },
             },

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

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../server.ts';
+import type { CaptureStore } from './capture.ts';
+export declare function analyzeTool(captures: CaptureStore): RegisteredTool;