@reclaimprotocol/agent 0.1.17 → 0.1.20

package/lib/mcp/credentials/resolve-owner-key.js

@@ -1,68 +0,0 @@
-import { deriveFromPrivateKey } from '@reclaimprotocol/client';
-import { findProjectRoot } from "../../paths.js";
-import { defineTool } from "../server.js";
-import { suggestCredentialForDir } from "./cache.js";
-import { readPrivateKeyFromEnvFile } from "./env-file.js";
-/**
- * Decide which app credential `run_proof` should sign with, BEFORE
- * calling it. `run_proof` requires an `ownerAddress` and does no
- * resolution of its own — this is the single place that "checks memory,
- * env, etc and offers options".
- *
- * Checks, in order: `RECLAIM_PRIVATE_KEY` in the MCP env → the project
- * `.env` → the best cached credential for this directory. Never returns
- * the private key — only the address to pass through as `ownerAddress`.
- */
-export function resolveOwnerKeyTool() {
-    return defineTool({
-        name: 'resolve_owner_key',
-        description: 'Resolve which app credential run_proof should sign with — ' +
-            'call this BEFORE run_proof. Checks, in order: ' +
-            'RECLAIM_PRIVATE_KEY in the MCP env, RECLAIM_PRIVATE_KEY in the ' +
-            'project .env, then the best cached credential for this ' +
-            'directory. 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 ' +
-            'provide a private key (import_credentials) or create one ' +
-            '(issue_credentials) — optionally with writeEnv:false to keep ' +
-            'it in the local cache (memory) only — and call resolve_owner_key ' +
-            'again. Never exposes the private key.',
-        inputSchema: { type: 'object', properties: {} },
-    }, async () => {
-        const dir = findProjectRoot(process.cwd());
-        const envKey = process.env.RECLAIM_PRIVATE_KEY;
-        if (envKey) {
-            return {
-                ready: true,
-                address: deriveFromPrivateKey(envKey).address,
-                source: 'env',
-            };
-        }
-        const dotenvKey = readPrivateKeyFromEnvFile(dir);
-        if (dotenvKey) {
-            return {
-                ready: true,
-                address: deriveFromPrivateKey(dotenvKey).address,
-                source: 'dotenv',
-            };
-        }
-        const suggestion = suggestCredentialForDir(dir);
-        if (suggestion) {
-            return {
-                ready: true,
-                address: suggestion.credential.address,
-                source: 'cache',
-                reason: suggestion.reason,
-            };
-        }
-        return {
-            ready: false,
-            message: 'No app credential available (no RECLAIM_PRIVATE_KEY in env ' +
-                'or .env, and the cache is empty). Ask the dev to provide ' +
-                'their private key via import_credentials, or create one via ' +
-                'issue_credentials (pass writeEnv:false to keep it out of ' +
-                '.env). Then call resolve_owner_key again and pass its ' +
-                'address to run_proof as ownerAddress.',
-        };
-    });
-}

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

@@ -1,14 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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/credentials/status.d.ts

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

package/lib/mcp/credentials/status.js

@@ -1,76 +0,0 @@
-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/register.d.ts

@@ -1,38 +0,0 @@
-/**
- * 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

@@ -1,80 +0,0 @@
-/**
- * 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/tools/analyze.d.ts

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

package/lib/mcp/tools/analyze.js

@@ -1,26 +0,0 @@
-import { detectConcerns } from "../../provider/constraints.js";
-import { defineTool } from "../server.js";
-export function analyzeTool(captures) {
-    return defineTool({
-        name: 'analyze_request_constraints',
-        description: 'Flag potential provider-authoring concerns for a 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}`);
-        }
-        return { concerns: detectConcerns(r) };
-    });
-}

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

@@ -1,11 +0,0 @@
-import { type CdpHandles } from '../../cdp/client.ts';
-import type { ConfigStore } from '../../config/store.ts';
-import { type RegisteredTool } from '../server.ts';
-export interface AttachState {
-    handles: CdpHandles;
-    port: number;
-}
-export declare function attachTool(state: {
-    current?: AttachState;
-    config: ConfigStore;
-}): RegisteredTool;

package/lib/mcp/tools/attach.js

@@ -1,72 +0,0 @@
-import { connectCdp } from "../../cdp/client.js";
-import { defaultProfileDir, launchChrome, waitForCdpReady, } from "../../cdp/launcher.js";
-import { defaultConfigPath } from "../../config/store.js";
-import { defineTool } from "../server.js";
-export function attachTool(state) {
-    return defineTool({
-        name: 'attach_chrome',
-        description: 'Attach to a Chrome instance via CDP. ' +
-            'Auto-launches a dedicated-profile Chrome ' +
-            'on first call if no attachMode is persisted. ' +
-            'Persists the chosen mode in ~/.reclaim/config.json.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                attachMode: { type: 'string', enum: ['dedicated', 'attach'] },
-                port: { type: 'number' },
-            },
-        },
-    }, async (parsed) => {
-        let cfg = state.config.read();
-        if (parsed.attachMode || parsed.port) {
-            cfg = {
-                attachMode: parsed.attachMode ?? cfg?.attachMode ?? 'dedicated',
-                port: parsed.port ?? cfg?.port ?? 9222,
-            };
-            state.config.write(cfg);
-        }
-        if (!cfg) {
-            return {
-                needsChoice: true,
-                message: 'First-run: choose attach mode. ' +
-                    'Call attach_chrome again with attachMode="dedicated" ' +
-                    '(auto-launch a Chrome profile under ~/.reclaim/chrome-profile) ' +
-                    'or attachMode="attach" ' +
-                    '(connect to a Chrome you launched yourself with ' +
-                    'BOTH --remote-debugging-port=9222 AND ' +
-                    '--user-data-dir=<some-non-default-path>; ' +
-                    'since Chrome 136 the debug-port flag is silently ' +
-                    'ignored if the default profile is in use).',
-                configPath: defaultConfigPath(),
-            };
-        }
-        if (cfg.attachMode === 'dedicated') {
-            try {
-                await waitForCdpReady(cfg.port, 500);
-            }
-            catch {
-                launchChrome({ port: cfg.port, profileDir: defaultProfileDir() });
-                await waitForCdpReady(cfg.port, 10_000);
-            }
-        }
-        else {
-            await waitForCdpReady(cfg.port, 2_000).catch(() => {
-                throw new Error(`attach mode: nothing answering CDP on port ${cfg.port}. ` +
-                    'Chrome must be launched with BOTH ' +
-                    `--remote-debugging-port=${cfg.port} AND ` +
-                    '--user-data-dir=<some-non-default-path>. ' +
-                    'Since Chrome 136 (May 2025), the debug-port flag is ' +
-                    'silently ignored when the default ' +
-                    "user profile is in use — that's why nothing opens the port. " +
-                    'Either re-launch Chrome with ' +
-                    'a custom --user-data-dir, or switch to attachMode="dedicated".');
-            });
-        }
-        if (state.current) {
-            await state.current.handles.close().catch(() => { });
-        }
-        const handles = await connectCdp(cfg.port);
-        state.current = { handles, port: cfg.port };
-        return { attached: true, port: cfg.port, mode: cfg.attachMode };
-    });
-}

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

@@ -1,10 +0,0 @@
-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

@@ -1,142 +0,0 @@
-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

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