@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.1

package/lib/mcp/tools/authenticate/resolve-owner-key.js

@@ -0,0 +1,53 @@
+import { join } from 'node:path';
+import { findProjectRoot } from "../../../paths.js";
+import { defineTool } from "../../server.js";
+import { ENV_FILE, resolveEthKey } from "./eth-key.js";
+/**
+ * Decide which eth proof-owner key `run_proof` should sign with, BEFORE
+ * calling it. The key is a raw 0x-hex Ethereum private key, resolved (no
+ * `~/.reclaim` cache) from:
+ *   1. `RECLAIM_PRIVATE_KEY` in the MCP env
+ *   2. a `RECLAIM_PRIVATE_KEY=0x…` line in the project `.env`
+ *   3. a file at `RECLAIM_PRIVATE_KEY_FILE` holding the raw hex
+ *   4. none → ask the dev to generate (issue_credentials) or provide one
+ *      (import_credentials), then call again.
+ * Never returns the private key — only the derived address.
+ */
+export function resolveOwnerKeyTool() {
+    return defineTool({
+        name: 'resolve_owner_key',
+        description: 'Resolve which eth proof-owner key run_proof should sign with — ' +
+            'call this BEFORE run_proof. Checks, in order: RECLAIM_PRIVATE_KEY ' +
+            'in the MCP env, a RECLAIM_PRIVATE_KEY=0x… line in the project .env, ' +
+            'then a file at RECLAIM_PRIVATE_KEY_FILE holding the raw hex. ' +
+            'Returns { ready: true, address, source } when one is ' +
+            'available — pass `address` to run_proof as `ownerAddress`. ' +
+            'Returns { ready: false } ' +
+            'when none exists: then ask the dev to generate one ' +
+            '(issue_credentials) or import one they already hold ' +
+            '(import_credentials, accepts 0x-hex or a key-file path), and call ' +
+            'resolve_owner_key again. Never exposes the private key.',
+        inputSchema: { type: 'object', properties: {} },
+    }, async () => {
+        const projectDir = findProjectRoot(process.cwd());
+        const resolved = resolveEthKey(projectDir);
+        if (resolved) {
+            return {
+                ready: true,
+                address: resolved.address,
+                source: resolved.source,
+                ...(resolved.path ? { path: resolved.path } : {}),
+            };
+        }
+        return {
+            ready: false,
+            message: 'No eth proof-owner key available — no RECLAIM_PRIVATE_KEY in the ' +
+                `env, no RECLAIM_PRIVATE_KEY in ${join(projectDir, ENV_FILE)}, and ` +
+                'no RECLAIM_PRIVATE_KEY_FILE. Ask the dev to generate one via ' +
+                'issue_credentials, or import one they already hold via ' +
+                'import_credentials (0x-hex or a key-file path). Then call ' +
+                'resolve_owner_key again and pass its address to run_proof as ' +
+                'ownerAddress.',
+        };
+    });
+}

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

@@ -0,0 +1,10 @@
+import { type CaptureSession } from '../../cdp/capture.ts';
+import { type RegisteredTool } from '../server.ts';
+import type { AttachState } from './attach.ts';
+export interface CaptureStore {
+    sessions: Map<string, CaptureSession>;
+    activeTab?: string;
+}
+export declare function captureTools(attachRef: {
+    current?: AttachState;
+}, captures: CaptureStore): RegisteredTool[];

package/lib/mcp/tools/capture.js

@@ -0,0 +1,142 @@
+import { startCapture } from "../../cdp/capture.js";
+import { defineTool } from "../server.js";
+export function captureTools(attachRef, captures) {
+    const requireAttached = () => {
+        if (!attachRef.current) {
+            throw new Error('Not attached. Call attach_chrome first.');
+        }
+        return attachRef.current;
+    };
+    const startTool = defineTool({
+        name: 'start_capture',
+        description: 'Begin recording network requests on the specified tab. ' +
+            'Returns a captureId.',
+        inputSchema: {
+            type: 'object',
+            properties: { tabId: { type: 'string' } },
+            required: ['tabId'],
+        },
+    }, async ({ tabId }) => {
+        const attached = requireAttached();
+        const tabClient = await attached.handles.attachToTab(tabId);
+        const session = await startCapture(tabClient);
+        captures.sessions.set(session.captureId, session);
+        captures.activeTab = tabId;
+        return { captureId: session.captureId };
+    });
+    const stopTool = defineTool({
+        name: 'stop_capture',
+        description: 'Stop recording on the given capture. ' +
+            'Captured data remains queryable until reset_session.',
+        inputSchema: {
+            type: 'object',
+            properties: { captureId: { type: 'string' } },
+            required: ['captureId'],
+        },
+    }, async ({ captureId }) => {
+        const session = captures.sessions.get(captureId);
+        if (!session) {
+            throw new Error(`no capture ${captureId}`);
+        }
+        await session.stop();
+        return { stopped: true, requestCount: session.requests.size };
+    });
+    const listTool = defineTool({
+        name: 'list_requests',
+        description: 'List metadata for captured requests. ' +
+            'Filter by method, URL glob, status, content-type, ' +
+            'or graphqlOp. Returns only metadata, never bodies — ' +
+            'use get_request for those.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                captureId: { type: 'string' },
+                filter: {
+                    type: 'object',
+                    properties: {
+                        method: { type: 'string' },
+                        urlGlob: { type: 'string' },
+                        statusMin: { type: 'number' },
+                        statusMax: { type: 'number' },
+                        contentType: { type: 'string' },
+                        graphqlOp: { type: 'string' },
+                    },
+                },
+            },
+            required: ['captureId'],
+        },
+    }, async ({ captureId, filter }) => {
+        const session = captures.sessions.get(captureId);
+        if (!session) {
+            throw new Error(`no capture ${captureId}`);
+        }
+        const out = [];
+        for (const r of session.requests.values()) {
+            if (filter?.method && r.method !== filter.method.toUpperCase()) {
+                continue;
+            }
+            if (filter?.urlGlob && !globMatch(filter.urlGlob, r.url)) {
+                continue;
+            }
+            if (filter?.statusMin !== undefined && r.status < filter.statusMin) {
+                continue;
+            }
+            if (filter?.statusMax !== undefined && r.status > filter.statusMax) {
+                continue;
+            }
+            if (filter?.contentType &&
+                !r.contentType.includes(filter.contentType)) {
+                continue;
+            }
+            if (filter?.graphqlOp && r.graphqlOp !== filter.graphqlOp) {
+                continue;
+            }
+            const item = {
+                requestId: r.requestId,
+                method: r.method,
+                url: r.url,
+                status: r.status,
+                contentType: r.contentType,
+                size: r.size,
+            };
+            if (r.graphqlOp !== undefined) {
+                item.graphqlOp = r.graphqlOp;
+            }
+            out.push(item);
+        }
+        return { requests: out };
+    });
+    const getTool = defineTool({
+        name: 'get_request',
+        description: 'Return full headers + bodies for a specific captured request.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                captureId: { type: 'string' },
+                requestId: { type: 'string' },
+            },
+            required: ['captureId', 'requestId'],
+        },
+    }, async ({ captureId, requestId }) => {
+        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} in capture ${captureId}`);
+        }
+        const body = session.bodies.get(requestId);
+        if (!body.available) {
+            return { ...r, bodyAvailable: false, reason: body.reason };
+        }
+        return { ...r, responseBody: body.body, bodyAvailable: true };
+    });
+    return [startTool, stopTool, listTool, getTool];
+}
+function globMatch(pattern, str) {
+    const re = new RegExp('^' +
+        pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') +
+        '$');
+    return re.test(str);
+}

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

@@ -0,0 +1,5 @@
+import { type RegisteredTool } from '../server.ts';
+import type { AttachState } from './attach.ts';
+export declare function browserTools(attachRef: {
+    current?: AttachState;
+}): RegisteredTool[];

package/lib/mcp/tools/eval.js

@@ -0,0 +1,127 @@
+import { listTabs } from "../../cdp/tabs.js";
+import { defineTool } from "../server.js";
+export function browserTools(attachRef) {
+    const requireAttached = () => {
+        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' };
+        }),
+    ];
+}

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

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

package/lib/mcp/tools/find.js

@@ -0,0 +1,60 @@
+import { normalizeCandidates } from "../../provider/normalize.js";
+import { defineTool } from "../server.js";
+export function findTool(captures) {
+    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);
+        const ranked = [];
+        for (const r of session.requests.values()) {
+            if (!r.responseBody) {
+                continue;
+            }
+            let hit;
+            for (const v of variants) {
+                const idx = r.responseBody.indexOf(v);
+                if (idx >= 0) {
+                    const start = Math.max(0, idx - 40);
+                    const end = Math.min(r.responseBody.length, idx + v.length + 40);
+                    hit = { snippet: r.responseBody.slice(start, end), variant: v };
+                    break;
+                }
+            }
+            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)));
+            ranked.push({
+                requestId: r.requestId,
+                url: r.url,
+                method: r.method,
+                status: r.status,
+                contentType: r.contentType,
+                matchedVariant: hit.variant,
+                snippet: hit.snippet,
+                score,
+            });
+        }
+        ranked.sort((a, b) => b.score - a.score);
+        return { candidates: ranked.slice(0, limit ?? 10) };
+    });
+}

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

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

package/lib/mcp/tools/index.js

@@ -0,0 +1,6 @@
+// Top-level barrel for every MCP tool group. The MCP server (start.ts) and the
+// package entry (src/index.ts) import tool builders from here, never from the
+// individual tool files.
+export * from "./agent/index.js";
+export * from "./authenticate/index.js";
+export * from "./verification/index.js";

package/lib/mcp/tools/owner-key.d.ts

@@ -0,0 +1,2 @@
+import { type RegisteredTool } from '../server.ts';
+export declare function ownerKeyTool(): RegisteredTool;

package/lib/mcp/tools/owner-key.js

@@ -0,0 +1,63 @@
+import { generateOwnerKey, ownerKeyEnvOverrideActive, ownerKeyPath, readOwnerKey, } from "../credentials/owner-key.js";
+import { defineTool } from "../server.js";
+export function ownerKeyTool() {
+    return defineTool({
+        name: 'generate_owner_key',
+        description: 'Generate the owner private key that `run_proof` needs '
+            + '(RECLAIM_AGENT_OWNER_PRIVATE_KEY) and save it to '
+            + '~/.reclaim/owner-key.json (mode 0600). `run_proof` reads it '
+            + 'from there automatically — no env var and no server restart '
+            + 'needed. Call this when `run_proof` reports the owner key is '
+            + 'missing. If a key already exists it is reused; pass '
+            + '`force: true` to replace it (this changes the claim owner '
+            + 'identity for future proofs). An explicit '
+            + 'RECLAIM_AGENT_OWNER_PRIVATE_KEY env var always takes '
+            + 'precedence over the saved file. The private key is never '
+            + 'returned in the response — the saved file is the only copy.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                force: {
+                    type: 'boolean',
+                    description: 'Replace an existing saved owner key with a new one. '
+                        + 'Default false (reuse the existing key).',
+                },
+            },
+        },
+    }, async (args) => {
+        const envActive = ownerKeyEnvOverrideActive();
+        const existing = readOwnerKey();
+        if (existing && !args.force) {
+            return {
+                created: false,
+                address: existing.address,
+                publicKey: existing.publicKey,
+                path: ownerKeyPath(),
+                envOverrideActive: envActive,
+                note: 'An owner key already exists and was reused. run_proof '
+                    + 'will use it automatically. Pass force:true to replace it.'
+                    + (envActive
+                        ? ' NOTE: RECLAIM_AGENT_OWNER_PRIVATE_KEY is set in the '
+                            + 'environment and takes precedence over this file.'
+                        : ''),
+            };
+        }
+        const key = generateOwnerKey();
+        return {
+            created: true,
+            replaced: Boolean(existing),
+            address: key.address,
+            publicKey: key.publicKey,
+            path: ownerKeyPath(),
+            envOverrideActive: envActive,
+            note: 'Owner key saved to ~/.reclaim/owner-key.json (0600). '
+                + 'run_proof will use it automatically — no restart needed. '
+                + 'The private key is intentionally omitted from this response.'
+                + (envActive
+                    ? ' NOTE: RECLAIM_AGENT_OWNER_PRIVATE_KEY is set in the '
+                        + 'environment and takes precedence over this file, so the '
+                        + 'saved key will not be used until that env var is unset.'
+                    : ''),
+        };
+    });
+}

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

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