@reclaimprotocol/agent 0.1.0 → 0.1.1

package/lib/mcp/tools/proof.js

@@ -0,0 +1,214 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { reclaimHomeDirPath } from "../../paths.js";
+import { runAttestorProof, tailLogs, warnsAndErrors, } from "../../proof/attestor.js";
+import { defineTool } from "../server.js";
+function claimsDir() {
+    return join(reclaimHomeDirPath(), 'claims');
+}
+function proofRunsDir() {
+    return join(reclaimHomeDirPath(), 'proof-runs');
+}
+/** Persist everything we know about this proof attempt — input provider,
+ *  sentParams the SDK saw, full captured logs, and the final result — to
+ *  a file the dev can `cat` directly. This is the source of truth when
+ *  the LLM's summary disagrees with reality. */
+function writeProofRunDump(payload) {
+    try {
+        mkdirSync(proofRunsDir(), { recursive: true });
+        const path = join(proofRunsDir(), `${Date.now()}.json`);
+        writeFileSync(path, JSON.stringify(payload, null, 2), 'utf8');
+        return path;
+    }
+    catch {
+        // Persistence is best-effort; never fail the proof for it.
+        return undefined;
+    }
+}
+/**
+ * Walk a claim object for display:
+ *   - drop any `request` field at any depth (it's huge and only useful
+ *     for low-level debugging — the on-disk claim still has it)
+ *   - convert byte-like values (Uint8Array, or arrays where every entry
+ *     is a number in [0,255]) to base64 strings so they render as
+ *     readable text instead of `{"0":12,"1":34,...}`
+ *
+ * The on-disk file at claimPath is the raw, unprettified claim — this
+ * function only affects what we return in the MCP tool response.
+ */
+function prettifyClaim(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return Buffer.from(value).toString('base64');
+    }
+    if (Array.isArray(value)) {
+        if (isLikelyByteArray(value)) {
+            return Buffer.from(value).toString('base64');
+        }
+        return value.map(prettifyClaim);
+    }
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (k === 'request') {
+                continue;
+            }
+            out[k] = prettifyClaim(v);
+        }
+        return out;
+    }
+    return value;
+}
+function isLikelyByteArray(v) {
+    if (v.length === 0) {
+        return false;
+    }
+    for (const x of v) {
+        if (typeof x !== 'number' || !Number.isInteger(x) || x < 0 || x > 255) {
+            return false;
+        }
+    }
+    return true;
+}
+export function proofTool(secrets) {
+    return defineTool({
+        name: 'run_proof',
+        description: 'Run a full zkTLS proof through the Reclaim attestor SDK. ' +
+            'Use only after replay_request ' +
+            'returns matchesOriginal=true — attestor calls are expensive. ' +
+            'Writes the full claim to ' +
+            '~/.reclaim/claims/<timestamp>.json and ' +
+            'returns identifier + extractedParameters + ' +
+            'claimPath + a prettified `claim` field ' +
+            '(request dropped, byte arrays as base64) suitable ' +
+            'for displaying directly to the dev. ' +
+            'When the MCP server is started with ' +
+            '`RECLAIM_AGENT_TRACE=1`, ALSO writes ' +
+            'a per-call diagnostic dump (input provider, ' +
+            'sentParams the SDK saw post-substitution, ' +
+            'FULL attestor log stream, result) to ' +
+            '~/.reclaim/proof-runs/<timestamp>.json and ' +
+            'returns the path as `runLogPath`. ' +
+            '`attestorUrl` overrides the default attestor URL only when the dev ' +
+            'supplies a specific ' +
+            'alternative — do NOT invent backup URLs ' +
+            '(there is one live public attestor right now; ' +
+            'surface real errors to the dev instead of guessing). ' +
+            '`ownerAddress` (the credential to sign with) is REQUIRED — ' +
+            'call resolve_owner_key first to obtain it, then pass it here. ' +
+            'errorKind="missing-owner-key" means that address has no known ' +
+            'private key; re-run resolve_owner_key or issue/import a credential.',
+        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' },
+                ownerAddress: {
+                    type: 'string',
+                    pattern: '^0x[0-9a-fA-F]{40}$',
+                    description: 'ETH address of the credential to sign the claim with. ' +
+                        'Get it from resolve_owner_key first. The private key is ' +
+                        'resolved locally (cache / env / .env) — never passed here.',
+                },
+            },
+            required: ['provider', 'ownerAddress'],
+        },
+    }, async ({ provider, secretParamsRef, attestorUrl, ownerAddress }) => {
+        let resolved = {};
+        if (secretParamsRef !== undefined) {
+            const r = secrets.resolve(secretParamsRef);
+            if (!r) {
+                throw new Error(`unknown secretParamsRef "${secretParamsRef}" — ` +
+                    'the MCP server has restarted or reset_session was called. ' +
+                    'Re-run propose_provider to mint a fresh ref.');
+            }
+            resolved = r;
+        }
+        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) {
+            try {
+                mkdirSync(claimsDir(), { recursive: true });
+                claimPath = join(claimsDir(), `${Date.now()}.json`);
+                writeFileSync(claimPath, JSON.stringify(result.proof, null, 2), 'utf8');
+            }
+            catch {
+                // Persistence is best-effort; don't fail the proof for it.
+                claimPath = undefined;
+            }
+        }
+        const out = {
+            verified: result.verified,
+            extractedValue: result.extractedValue,
+            extractedParameters: result.extractedParameters,
+        };
+        if (result.identifier !== undefined) {
+            out.identifier = result.identifier;
+        }
+        if (result.owner !== undefined) {
+            out.owner = result.owner;
+        }
+        if (claimPath !== undefined) {
+            out.claimPath = claimPath;
+        }
+        if (result.proof !== undefined && result.proof !== null) {
+            out.claim = prettifyClaim(result.proof);
+        }
+        if (result.error !== undefined) {
+            out.error = result.error;
+        }
+        if (result.errorKind !== undefined) {
+            out.errorKind = result.errorKind;
+        }
+        // Trim the LLM-visible logs — full stream goes to runLogPath.
+        if (result.attestorLogs !== undefined && result.attestorLogs.length > 0) {
+            out.attestorLogs = result.verified
+                ? warnsAndErrors(result.attestorLogs)
+                : tailLogs(result.attestorLogs);
+            if (out.attestorLogs.length === 0) {
+                delete out.attestorLogs;
+            }
+        }
+        if (result.sentParams !== undefined) {
+            out.sentParams = result.sentParams;
+        }
+        // Persist a diagnostic dump for forensics — gated behind
+        // RECLAIM_AGENT_TRACE=1 (matches the attestor logger capture).
+        // Off by default since happy-path runs don't need it; turn on
+        // when investigating proof failures and the file at runLogPath
+        // will carry the input provider, sentParams, full attestor log
+        // stream, and result.
+        if (process.env['RECLAIM_AGENT_TRACE'] === '1') {
+            const runLogPath = writeProofRunDump({
+                provider,
+                hasSecretParamsRef: secretParamsRef !== undefined,
+                attestorUrl,
+                result: {
+                    verified: result.verified,
+                    error: result.error,
+                    errorKind: result.errorKind,
+                    extractedValue: result.extractedValue,
+                    extractedParameters: result.extractedParameters,
+                    identifier: result.identifier,
+                    owner: result.owner,
+                    sentParams: result.sentParams,
+                    attestorLogs: result.attestorLogs,
+                    claimPath,
+                },
+            });
+            if (runLogPath !== undefined) {
+                out.runLogPath = runLogPath;
+            }
+        }
+        return out;
+    });
+}

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

@@ -0,0 +1,9 @@
+import { type RegisteredTool } from '../server.ts';
+import type { CaptureStore } from './capture.ts';
+export interface SecretStore {
+    put: (values: Record<string, string>) => string;
+    resolve: (ref: string) => Record<string, string> | undefined;
+    clear: () => void;
+}
+export declare function makeSecretStore(): SecretStore;
+export declare function proposeTool(captures: CaptureStore, secrets: SecretStore): RegisteredTool;

package/lib/mcp/tools/propose.js

@@ -0,0 +1,75 @@
+import { randomUUID } from 'node:crypto';
+import { draftProvider } from "../../provider/draft.js";
+import { OPRF_MAX_BYTES } from "../../provider/matcher.js";
+import { defineTool } from "../server.js";
+export function makeSecretStore() {
+    const map = new Map();
+    return {
+        put: (values) => {
+            const id = `sref_${randomUUID()}`;
+            map.set(id, values);
+            return id;
+        },
+        resolve: (ref) => map.get(ref),
+        clear: () => map.clear(),
+    };
+}
+export function proposeTool(captures, secrets) {
+    return defineTool({
+        name: 'propose_provider',
+        description: 'Draft a Reclaim provider JSON from a captured request + ' +
+            'a target value. ' +
+            'Secret header values are stored server-side and replaced with an ' +
+            'opaque secretParamsRef ' +
+            'in the response — raw secret values never appear in tool output. ' +
+            "`hash` is opt-in: when set, the captured value is OPRF'd so " +
+            'the attestor never sees ' +
+            '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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                captureId: { type: 'string' },
+                requestId: { type: 'string' },
+                target: { type: 'string' },
+                name: { type: 'string' },
+                hash: { type: 'string', enum: ['oprf-raw', 'oprf', 'oprf-mpc'] },
+            },
+            required: ['captureId', 'requestId', 'target', 'name'],
+        },
+    }, async ({ captureId, requestId, target, name, hash }) => {
+        if (hash !== undefined && target.length > OPRF_MAX_BYTES) {
+            throw new Error(`OPRF caps hashed values at ${OPRF_MAX_BYTES} bytes; ` +
+                `got ${target.length}-byte target ` +
+                `"${target}". Try a tighter target ` +
+                '(e.g. just the relevant substring) or call ' +
+                'propose_provider without `hash`.');
+        }
+        const session = captures.sessions.get(captureId);
+        if (!session) {
+            throw new Error(`no capture ${captureId}`);
+        }
+        const r = session.requests.get(requestId);
+        if (!r) {
+            throw new Error(`no request ${requestId}`);
+        }
+        const body = session.bodies.get(requestId);
+        if (!body.available) {
+            throw new Error(`request body unavailable: ${body.reason}`);
+        }
+        const reqWithBody = { ...r, responseBody: body.body };
+        const { provider, secretRefs } = draftProvider(reqWithBody, target, name, hash);
+        // Stash real secret values for later replay/proof.
+        const realSecrets = {};
+        for (const ref of secretRefs) {
+            const real = r.requestHeaders[ref.name];
+            if (real !== undefined) {
+                realSecrets[ref.name] = real;
+            }
+        }
+        const secretParamsRef = secrets.put(realSecrets);
+        return { provider, secretRefs, secretParamsRef };
+    });
+}

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

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

package/lib/mcp/tools/publish.js

@@ -0,0 +1,59 @@
+import { nextVersion, providerToCreateVersionRequest, } from "../../provider/to-version.js";
+import { defineTool } from "../server.js";
+export function createVersionFromCaptureTool(client) {
+    return defineTool({
+        name: 'create_provider_version_from_capture',
+        description: 'Translate a drafted ReclaimProvider (from propose_provider) into a ' +
+            'verification version and persist it via create_provider_version. ' +
+            'Call this after run_proof succeeds. ' +
+            '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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                providerId: {
+                    type: 'string',
+                    description: 'UUID of the verification to publish the version on.',
+                },
+                provider: {
+                    type: 'object',
+                    description: 'The ReclaimProvider JSON from propose_provider ' +
+                        '(with URL parameterisation applied).',
+                },
+                initialUrl: {
+                    type: 'string',
+                    description: 'The website URL the user landed on to trigger the request ' +
+                        '(e.g. https://github.com/Syed). The URL the verification ' +
+                        'flow opens for end-users — NOT the API URL inside the provider.',
+                },
+                notes: {
+                    type: 'string',
+                    description: 'Short change note (e.g. "Initial draft from browser capture").',
+                },
+                version: {
+                    type: 'object',
+                    description: 'Semver to publish as. Omit to auto-pick the next ' +
+                        'version above the highest existing one.',
+                    properties: {
+                        major: { type: 'number', minimum: 0 },
+                        minor: { type: 'number', minimum: 0 },
+                        patch: { type: 'number', minimum: 0 },
+                    },
+                    required: ['major', 'minor', 'patch'],
+                },
+            },
+            required: ['providerId', 'provider', 'initialUrl'],
+        },
+    }, async (args) => {
+        // Auto-pick the next version if not explicit
+        const ver = args.version ?? (await nextVersion(client, args.providerId));
+        const body = providerToCreateVersionRequest(args.provider, args.initialUrl, args.notes, ver);
+        const result = (await client.call('CreateProviderVersion', {
+            params: { providerId: args.providerId },
+            body,
+        }));
+        return result.data;
+    });
+}

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

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../server.ts';
+import type { SecretStore } from './propose.ts';
+export declare function replayTool(secrets: SecretStore): RegisteredTool;

package/lib/mcp/tools/replay.js

@@ -0,0 +1,46 @@
+import { replayProvider } from "../../proof/replay.js";
+import { defineTool } from "../server.js";
+export function replayTool(secrets) {
+    return defineTool({
+        name: 'replay_request',
+        description: 'Replay a drafted provider against the live endpoint ' +
+            'using Node fetch (no attestor). ' +
+            'Pre-flight gate before run_proof — ' +
+            'diagnoses CSRF / token-rotation / matcher-too-tight ' +
+            'issues with richer hints than the attestor would produce.',
+        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' },
+            },
+            required: ['provider'],
+        },
+    }, async ({ provider, secretParamsRef }) => {
+        let resolved = {};
+        if (secretParamsRef !== undefined) {
+            const r = secrets.resolve(secretParamsRef);
+            if (!r) {
+                throw new Error(`unknown secretParamsRef "${secretParamsRef}" — ` +
+                    'the MCP server has restarted or reset_session was called. ' +
+                    'Re-run propose_provider to mint a fresh ref.');
+            }
+            resolved = r;
+        }
+        const result = await replayProvider(provider, resolved);
+        const out = {
+            status: result.status,
+            matchesOriginal: result.matchesOriginal,
+            bodySnippet: result.body.slice(0, 256),
+        };
+        if (result.hints !== undefined) {
+            out.hints = result.hints;
+        }
+        return out;
+    });
+}

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

@@ -0,0 +1,10 @@
+import type { ConfigStore } from '../../config/store.ts';
+import { type RegisteredTool } from '../server.ts';
+import type { AttachState } from './attach.ts';
+import type { CaptureStore } from './capture.ts';
+export declare function sessionTools(attachRef: {
+    current?: AttachState;
+    config: ConfigStore;
+}, captures: CaptureStore, secrets: {
+    clear: () => void;
+}): RegisteredTool[];

package/lib/mcp/tools/session.js

@@ -0,0 +1,29 @@
+import { defineTool } from "../server.js";
+export function sessionTools(attachRef, captures, secrets) {
+    return [
+        defineTool({
+            name: 'get_session',
+            description: 'Return current attach state, active captures, and persisted config.',
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => ({
+            config: attachRef.config.read(),
+            attached: Boolean(attachRef.current),
+            port: attachRef.current?.port,
+            captures: [...captures.sessions.keys()],
+            activeTab: captures.activeTab,
+        })),
+        defineTool({
+            name: 'reset_session',
+            description: 'Stop all captures, drop in-memory secrets, and clear capture state.',
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => {
+            for (const s of captures.sessions.values()) {
+                await s.stop().catch(() => { });
+            }
+            captures.sessions.clear();
+            delete captures.activeTab;
+            secrets.clear();
+            return { reset: true };
+        }),
+    ];
+}

package/lib/mcp/tools/verification/build.d.ts

@@ -0,0 +1,12 @@
+import type { RegisteredTool } from '../../server.ts';
+/**
+ * Builder-mode verification tools: higher-level orchestrations over the
+ * generated API surface. `get_verification_result` authenticates with the org
+ * token, checks status, pulls the stored payload, and decrypts it locally with
+ * the optional X25519 key — a flow the generated raw-API tools can't express
+ * (the decryption key never leaves the consumer). Diagnosis is left to the
+ * agent over the generated tools (`get_verification_session`,
+ * `list_verification_events`, `list_verification_deliveries`), whose
+ * descriptions carry the lifecycle and delivery semantics.
+ */
+export declare function buildVerificationTools(): RegisteredTool[];

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

@@ -0,0 +1,14 @@
+import { verificationResultTool } from "./result.js";
+/**
+ * Builder-mode verification tools: higher-level orchestrations over the
+ * generated API surface. `get_verification_result` authenticates with the org
+ * token, checks status, pulls the stored payload, and decrypts it locally with
+ * the optional X25519 key — a flow the generated raw-API tools can't express
+ * (the decryption key never leaves the consumer). Diagnosis is left to the
+ * agent over the generated tools (`get_verification_session`,
+ * `list_verification_events`, `list_verification_deliveries`), whose
+ * descriptions carry the lifecycle and delivery semantics.
+ */
+export function buildVerificationTools() {
+    return [verificationResultTool()];
+}

package/lib/mcp/tools/verification/diagnose.d.ts

@@ -0,0 +1,11 @@
+import { type ReclaimClient } from '@reclaimprotocol/client';
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * `diagnose_verification_session` — one call that answers "what's wrong
+ * with this session?". Pulls the session, its full event log, and its
+ * callback-delivery diagnostics, then derives findings (where the flow
+ * stalled or failed) and concrete suggestions (what to check or do next).
+ * Read-only; authenticates with the active eth credential like
+ * `get_verification_result`.
+ */
+export declare function verificationDiagnoseTool(client: ReclaimClient): RegisteredTool;

package/lib/mcp/tools/verification/diagnose.js

@@ -0,0 +1,132 @@
+import { buildAuthHeaders } from '@reclaimprotocol/client';
+import { defineTool } from "../../server.js";
+import { resolveActivePrivateKey } from "./result.js";
+const TERMINAL = new Set(['success', 'rejected', 'error']);
+/**
+ * `diagnose_verification_session` — one call that answers "what's wrong
+ * with this session?". Pulls the session, its full event log, and its
+ * callback-delivery diagnostics, then derives findings (where the flow
+ * stalled or failed) and concrete suggestions (what to check or do next).
+ * Read-only; authenticates with the active eth credential like
+ * `get_verification_result`.
+ */
+export function verificationDiagnoseTool(client) {
+    return defineTool({
+        name: 'diagnose_verification_session',
+        description: 'Diagnose a verification session: fetches its status, event ' +
+            'timeline, and callback-delivery state, then reports findings ' +
+            '(where the flow stalled or failed — link never opened, proof ' +
+            'failed, callback endpoint erroring, dead-lettered delivery, ' +
+            'expiry) and suggested next steps. Read-only. Use ' +
+            'get_verification_result to fetch and decrypt the actual result.',
+        inputSchema: {
+            type: 'object',
+            required: ['sessionId'],
+            properties: {
+                sessionId: {
+                    type: 'string',
+                    description: 'The verification session id to diagnose.',
+                },
+            },
+        },
+    }, async (args) => {
+        const privateKey = resolveActivePrivateKey();
+        const auth = () => buildAuthHeaders(privateKey, 'VerificationAuth');
+        const params = { sessionId: args.sessionId };
+        const [session, events, deliveries] = await Promise.all([
+            client.call('GetVerificationSession', { params, headers: auth() })
+                .then((r) => r.data),
+            client.call('ListVerificationEvents', { params, headers: auth() })
+                .then((r) => r.data.items),
+            client.call('ListVerificationDeliveries', { params, headers: auth() })
+                .then((r) => r.data.items),
+        ]);
+        const seen = new Set(events.map((e) => e.event));
+        const last = events[events.length - 1];
+        const findings = [];
+        const suggestions = [];
+        // Where did the flow get to?
+        if (session.status === 'pending') {
+            if (new Date(session.expiresAt).getTime() < Date.now()) {
+                findings.push('Session is past expiresAt — it will flip to expired on the ' +
+                    'next sweep; the end-user can no longer complete it.');
+                suggestions.push('Create a new session and share a fresh link.');
+            }
+            else if (!seen.has('verification_client_opened')) {
+                findings.push('The end-user has not opened the verification link yet.');
+                suggestions.push(`Re-share the link (${session.verificationUrl}) before ` +
+                    `it expires at ${session.expiresAt}.`);
+            }
+            else if (!seen.has('request_matched')) {
+                findings.push('The page was opened but the target request was never ' +
+                    'captured — the end-user likely has not completed the ' +
+                    'login/journey on the provider site.');
+            }
+            else {
+                findings.push('Proof flow is in progress — the target request was ' +
+                    'captured and the run has not reached a terminal event.');
+            }
+        }
+        if (session.status === 'expired') {
+            findings.push(seen.has('verification_client_opened')
+                ? 'Session expired mid-flow — the end-user started but did ' +
+                    'not finish before expiresAt.'
+                : 'Session expired without the link ever being opened.');
+            suggestions.push('Create a new session and share a fresh link.');
+        }
+        // Surface failure detail from the event log.
+        for (const e of events) {
+            if (e.event === 'request_claim_failed' ||
+                e.event === 'request_claim_rejected' ||
+                e.event === 'verification_error' ||
+                e.event === 'verification_rejected') {
+                findings.push(`${e.event} at ${e.createdAt}` +
+                    (e.eventData ? `: ${JSON.stringify(e.eventData)}` : ''));
+            }
+        }
+        // Callback delivery health (only meaningful after a terminal event).
+        for (const d of deliveries) {
+            if (d.deliveryStatus === 'delivered') {
+                continue;
+            }
+            findings.push(`Callback to ${d.callbackUrl} is ${d.deliveryStatus} after ` +
+                `${d.attempts} attempt(s)` +
+                (d.lastError ? ` — last error: ${d.lastError}` : '') +
+                (d.deadLettered ? ' (dead-lettered; retries exhausted)' : ''));
+            suggestions.push(`Check that ${d.callbackUrl} is reachable and answers 2xx.`);
+            if (d.deadLettered) {
+                suggestions.push('Once the endpoint is fixed, re-deliver via ' +
+                    'POST /verifications/sessions/{sessionId}/retry-callback ' +
+                    '(or ask an admin to retry it from the Callback DLQ).');
+            }
+        }
+        if (TERMINAL.has(session.status) &&
+            deliveries.every((d) => d.deliveryStatus === 'delivered')) {
+            suggestions.push('Result delivered. Use get_verification_result to fetch and ' +
+                'decrypt it locally.');
+        }
+        if (!findings.length) {
+            findings.push('No problems detected.');
+        }
+        return {
+            sessionId: session.id,
+            status: session.status,
+            callbackDeliveryStatus: session.callbackDeliveryStatus,
+            mode: session.mode,
+            createdAt: session.createdAt,
+            expiresAt: session.expiresAt,
+            completedAt: session.completedAt,
+            lastEvent: last
+                ? { event: last.event, at: last.createdAt }
+                : undefined,
+            events: events.map((e) => ({
+                event: e.event,
+                at: e.createdAt,
+                ...(e.eventData ? { data: e.eventData } : {}),
+            })),
+            deliveries,
+            findings,
+            suggestions,
+        };
+    });
+}

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

@@ -0,0 +1 @@
+export { buildVerificationTools } from './build.ts';

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

@@ -0,0 +1,2 @@
+// Barrel for the verification tool group (result retrieval + decryption).
+export { buildVerificationTools } from "./build.js";

package/lib/mcp/tools/verification/result.d.ts

@@ -0,0 +1,12 @@
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * `get_verification_result` — check a session's status and, once a result has
+ * been submitted, pull the stored payload(s) and verify locally. Auth is the
+ * org token; delivery is org-scoped. Each stored payload is either the
+ * plaintext signed JWS (when the org has no encryption credential) or a compact
+ * JWE (RFC 7516, ECDH-ES+A256GCM over X25519) that we decrypt here with the
+ * optional X25519 key (the `reclaim-decrypt.pem` PEM in the project). The
+ * Builder only ever relays the payload — decryption, when needed, happens
+ * here.
+ */
+export declare function verificationResultTool(): RegisteredTool;