@reclaimprotocol/agent 0.1.4 → 0.1.6

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

@@ -1,5 +1,8 @@
 import { type RegisteredTool } from '../../server.ts';
 import type { AttachState } from './attach.ts';
-export declare function browserTools(attachRef: {
+/** The one browser tool that isn't session-bound: enumerate tabs so the caller
+ *  can pick one to `start_capture` on. Navigate/eval/wait are the shared
+ *  authoring tools (keyed by captureId — see `shared.ts`). */
+export declare function listTabsTool(attachRef: {
     current?: AttachState;
-}): RegisteredTool[];
+}): RegisteredTool;

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

@@ -1,127 +1,17 @@
 import { listTabs } from "../../../cdp/tabs.js";
 import { defineTool } from "../../server.js";
-export function browserTools(attachRef) {
-    const requireAttached = () => {
+/** The one browser tool that isn't session-bound: enumerate tabs so the caller
+ *  can pick one to `start_capture` on. Navigate/eval/wait are the shared
+ *  authoring tools (keyed by captureId — see `shared.ts`). */
+export function listTabsTool(attachRef) {
+    return defineTool({
+        name: 'list_tabs',
+        description: 'List open Chrome tabs.',
+        inputSchema: { type: 'object', properties: {} },
+    }, async () => {
         if (!attachRef.current) {
             throw new Error('Not attached. Call attach_chrome first.');
         }
-        return attachRef.current;
-    };
-    return [
-        defineTool({
-            name: 'list_tabs',
-            description: 'List open Chrome tabs.',
-            inputSchema: { type: 'object', properties: {} },
-        }, async () => {
-            const attached = requireAttached();
-            return { tabs: await listTabs(attached.port) };
-        }),
-        defineTool({
-            name: 'eval_in_page',
-            description: 'Run a JS expression in a tab via Runtime.evaluate ' +
-                'and return the result. ' +
-                'Useful for reading visible values from the DOM.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    tabId: { type: 'string' },
-                    expression: { type: 'string' },
-                },
-                required: ['tabId', 'expression'],
-            },
-        }, async ({ tabId, expression }) => {
-            const attached = requireAttached();
-            const { Runtime } = await attached.handles.attachToTab(tabId);
-            const result = await Runtime.evaluate({
-                expression,
-                returnByValue: true,
-            });
-            if (result.exceptionDetails) {
-                return { error: result.exceptionDetails.text };
-            }
-            return { value: result.result.value };
-        }),
-        defineTool({
-            name: 'navigate',
-            description: 'Navigate a tab to a URL via Page.navigate, ' +
-                'waiting for the load event. ' +
-                'Use this to drive the browser yourself ' +
-                'instead of asking the developer to navigate. ' +
-                'Returns the final URL after navigation ' +
-                '(which may differ from the requested URL due to redirects).',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    tabId: { type: 'string' },
-                    url: { type: 'string' },
-                    timeoutMs: { type: 'number' },
-                },
-                required: ['tabId', 'url'],
-            },
-        }, async ({ tabId, url, timeoutMs }) => {
-            const attached = requireAttached();
-            const { Page, Runtime } = await attached.handles.attachToTab(tabId);
-            await Page.enable();
-            const loadPromise = new Promise((resolve) => {
-                Page.loadEventFired(() => resolve());
-            });
-            const nav = await Page.navigate({ url });
-            if (nav.errorText) {
-                return { ok: false, error: nav.errorText };
-            }
-            const t = timeoutMs ?? 30_000;
-            const raced = await Promise.race([
-                loadPromise.then(() => 'loaded'),
-                new Promise((resolve) => setTimeout(() => resolve('timeout'), t)),
-            ]);
-            const final = await Runtime.evaluate({
-                expression: 'location.href',
-                returnByValue: true,
-            });
-            return {
-                ok: true,
-                loadStatus: raced,
-                finalUrl: final.result.value,
-            };
-        }),
-        defineTool({
-            name: 'wait_for_page',
-            description: 'Poll a JS expression in a tab until it ' +
-                'returns truthy (or timeout). ' +
-                'Use this for steps that require the ' +
-                'developer to do something in the browser — ' +
-                'most commonly waiting for them to finish logging in. ' +
-                'Pass an expression that ' +
-                'evaluates true once the desired state is reached, e.g. ' +
-                '`!!document.querySelector' +
-                '(\'summary[aria-label*="View profile"]\')`' +
-                ' for GitHub post-login.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    tabId: { type: 'string' },
-                    expression: { type: 'string' },
-                    timeoutMs: { type: 'number' },
-                    pollMs: { type: 'number' },
-                },
-                required: ['tabId', 'expression'],
-            },
-        }, async ({ tabId, expression, timeoutMs, pollMs }) => {
-            const attached = requireAttached();
-            const { Runtime } = await attached.handles.attachToTab(tabId);
-            const deadline = Date.now() + (timeoutMs ?? 120_000);
-            const interval = pollMs ?? 1000;
-            while (Date.now() < deadline) {
-                const r = await Runtime.evaluate({ expression, returnByValue: true });
-                if (r.exceptionDetails) {
-                    return { matched: false, error: r.exceptionDetails.text };
-                }
-                if (r.result.value) {
-                    return { matched: true, value: r.result.value };
-                }
-                await new Promise((resolve) => setTimeout(resolve, interval));
-            }
-            return { matched: false, reason: 'timeout' };
-        }),
-    ];
+        return { tabs: await listTabs(attachRef.current.port) };
+    });
 }

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

@@ -1,3 +1,10 @@
-import { type RegisteredTool } from '../../server.ts';
-import type { CaptureStore } from './capture.ts';
-export declare function findTool(captures: CaptureStore): RegisteredTool;
+/**
+ * `find_requests_containing` — search captured responses for any encoding of a
+ * value and rank the requests that return it. Authored once as a plain
+ * {@link RegisteredTool}; the MCP and cloud loop each pass their own backend
+ * resolver (see authoring/tools.ts / shared.ts). Server-side: response bodies
+ * stay here, only metadata + a short snippet leave.
+ */
+import { type ResolveBackend } from '../../../authoring/util.ts';
+import { type RegisteredTool } from '../../../tools/registry.ts';
+export declare function findTool(resolveBackend: ResolveBackend): RegisteredTool;

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

@@ -1,29 +1,26 @@
+/**
+ * `find_requests_containing` — search captured responses for any encoding of a
+ * value and rank the requests that return it. Authored once as a plain
+ * {@link RegisteredTool}; the MCP and cloud loop each pass their own backend
+ * resolver (see authoring/tools.ts / shared.ts). Server-side: response bodies
+ * stay here, only metadata + a short snippet leave.
+ */
+import { objectSchema, publicRequest, } from "../../../authoring/util.js";
 import { normalizeCandidates } from "../../../provider/normalize.js";
-import { defineTool } from "../../server.js";
-export function findTool(captures) {
+import { defineTool } from "../../../tools/registry.js";
+export function findTool(resolveBackend) {
     return defineTool({
         name: 'find_requests_containing',
-        description: 'Search captured responses for any encoding of `value`.' +
-            'Returns a ranked candidate list ' +
-            'with the JSON path (when applicable), score, and a short snippet.' +
-            'Server-side; bodies stay here.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                captureId: { type: 'string' },
-                value: { type: 'string' },
-                limit: { type: 'number' },
-            },
-            required: ['captureId', 'value'],
-        },
-    }, async ({ captureId, value, limit }) => {
-        const session = captures.sessions.get(captureId);
-        if (!session) {
-            throw new Error(`no capture ${captureId}`);
-        }
-        const variants = normalizeCandidates(value);
+        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. Server-side; bodies stay here.',
+        inputSchema: objectSchema({ value: { type: 'string' }, limit: { type: 'number' } }, ['value']),
+    }, async (args) => {
+        const backend = resolveBackend(args);
+        const variants = normalizeCandidates(String(args.value));
         const ranked = [];
-        for (const r of session.requests.values()) {
+        for (const r of backend.capture.requests.values()) {
             if (!r.responseBody) {
                 continue;
             }
@@ -40,21 +37,18 @@ export function findTool(captures) {
             if (!hit) {
                 continue;
             }
-            // Score: prefer JSON responses + smaller bodies (likely API endpoints).
-            const score = (r.contentType.includes('json') ? 10 : 0) +
-                Math.max(0, 5 - Math.log10(Math.max(r.size, 1)));
+            // Prefer JSON responses + smaller bodies (likely API endpoints).
+            const score = (r.contentType.includes('json') ? 10 : 0)
+                + Math.max(0, 5 - Math.log10(Math.max(r.size, 1)));
             ranked.push({
-                requestId: r.requestId,
-                url: r.url,
-                method: r.method,
-                status: r.status,
-                contentType: r.contentType,
+                ...publicRequest(r),
                 matchedVariant: hit.variant,
                 snippet: hit.snippet,
                 score,
             });
         }
         ranked.sort((a, b) => b.score - a.score);
-        return { candidates: ranked.slice(0, limit ?? 10) };
+        const limit = Number(args.limit) || 10;
+        return { candidates: ranked.slice(0, limit) };
     });
 }

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

@@ -1,3 +1,13 @@
-import { type RegisteredTool } from '../../server.ts';
-import type { SecretStore } from './propose.ts';
-export declare function proofTool(secrets: SecretStore): RegisteredTool;
+import { type ProofResult } from '../../../proof/attestor.ts';
+/**
+ * The MCP's rich `run_proof` view: persist the full claim to disk, return
+ * identifier + extractedParameters + a prettified claim (request dropped, byte
+ * arrays as base64) + trimmed logs, and — under `RECLAIM_AGENT_TRACE=1` — a
+ * forensic run dump. This is the developer-facing shape; the cloud backend
+ * projects the same {@link ProofResult} to a lean summary instead.
+ */
+export declare function shapeRichProofResult(result: ProofResult, opts: {
+    provider: unknown;
+    hasSecrets: boolean;
+    attestorUrl?: string;
+}): Record<string, unknown>;

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

@@ -2,8 +2,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { agentTraceEnabled } from "../../../consts.js";
 import { reclaimHomeDirPath } from "../../../paths.js";
-import { runAttestorProof, tailLogs, warnsAndErrors, } from "../../../proof/attestor.js";
-import { defineTool } from "../../server.js";
+import { tailLogs, warnsAndErrors, } from "../../../proof/attestor.js";
 function claimsDir() {
     return join(reclaimHomeDirPath(), 'claims');
 }
@@ -73,138 +72,88 @@ function isLikelyByteArray(v) {
     }
     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: {
-                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;
+/**
+ * The MCP's rich `run_proof` view: persist the full claim to disk, return
+ * identifier + extractedParameters + a prettified claim (request dropped, byte
+ * arrays as base64) + trimmed logs, and — under `RECLAIM_AGENT_TRACE=1` — a
+ * forensic run dump. This is the developer-facing shape; the cloud backend
+ * projects the same {@link ProofResult} to a lean summary instead.
+ */
+export function shapeRichProofResult(result, opts) {
+    // 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');
         }
-        // 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;
-            }
+        catch {
+            // Persistence is best-effort; don't fail the proof for it.
+            claimPath = undefined;
         }
-        if (result.sentParams !== undefined) {
-            out.sentParams = result.sentParams;
+    }
+    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;
         }
-        // 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 (agentTraceEnabled()) {
-            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;
-            }
+    }
+    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 (agentTraceEnabled()) {
+        const runLogPath = writeProofRunDump({
+            provider: opts.provider,
+            hasSecretParamsRef: opts.hasSecrets,
+            attestorUrl: opts.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;
-    });
+    }
+    return out;
 }

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

@@ -1,9 +1,10 @@
-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;
+/**
+ * `propose_provider` — draft a provider (recipe + captured secrets) from ONE
+ * captured request, one match + redaction per target value. Authored once as a
+ * plain {@link RegisteredTool}; hosts pass their own backend resolver. The
+ * draft (recipe + real secret header values) is held server-side under an
+ * opaque `draftId`; the result carries only the secret-free provider.
+ */
+import { type ResolveBackend } from '../../../authoring/util.ts';
+import { type RegisteredTool } from '../../../tools/registry.ts';
+export declare function proposeTool(resolveBackend: ResolveBackend): RegisteredTool;