@reclaimprotocol/agent 0.1.18 → 0.1.21

package/lib/mcp/credentials/poll.js

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

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

@@ -1,18 +0,0 @@
-import type { EthKeypair } from '@reclaimprotocol/client';
-import { type CachedCredential } from './cache.ts';
-import { type EnvWriteResult } from './env-file.ts';
-/** Shape returned by `persistCredentialLocally` — the fields both
- *  `issue_credentials` and `import_credentials` expose in their MCP
- *  responses. The env-file fields are present only when the credential
- *  was persisted to `.env` (`writeEnv: true`); a memory-only credential
- *  lives in the cache and omits them. */
-export type PersistedCredential = Pick<CachedCredential, 'address' | 'label'> & Partial<EnvWriteResult> & {
-    wroteEnv: boolean;
-};
-/** Local persistence step shared by `issue_credentials` and
- *  `import_credentials`. Always upserts the credentials cache; when
- *  `writeEnv` is true (default) it also writes `RECLAIM_PRIVATE_KEY` to
- *  the project `.env` (0600) and appends `.env` to `.gitignore`. Pass
- *  `writeEnv: false` to keep the credential in the cache (memory) only,
- *  without touching the project's `.env`. */
-export declare function persistCredentialLocally(keypair: EthKeypair, label: string | undefined, projectDir: string, writeEnv?: boolean): PersistedCredential;

package/lib/mcp/credentials/register.js

@@ -1,30 +0,0 @@
-import { upsertCredential } from "./cache.js";
-import { writeAppCredentialsToEnv } from "./env-file.js";
-/** Local persistence step shared by `issue_credentials` and
- *  `import_credentials`. Always upserts the credentials cache; when
- *  `writeEnv` is true (default) it also writes `RECLAIM_PRIVATE_KEY` to
- *  the project `.env` (0600) and appends `.env` to `.gitignore`. Pass
- *  `writeEnv: false` to keep the credential in the cache (memory) only,
- *  without touching the project's `.env`. */
-export function persistCredentialLocally(keypair, label, projectDir, writeEnv = true) {
-    const cached = upsertCredential({
-        address: keypair.address,
-        privateKey: keypair.privateKey,
-        label,
-        createdAt: new Date().toISOString(),
-        createdIn: projectDir,
-        projectDirs: [projectDir],
-    });
-    if (!writeEnv) {
-        return { address: cached.address, label: cached.label, wroteEnv: false };
-    }
-    const env = writeAppCredentialsToEnv(projectDir, keypair.privateKey);
-    return {
-        address: cached.address,
-        label: cached.label,
-        wroteEnv: true,
-        envPath: env.envPath,
-        gitignorePath: env.gitignorePath,
-        gitignoreAppended: env.gitignoreAppended,
-    };
-}

package/lib/mcp/credentials/resolve-owner-key.d.ts

@@ -1,12 +0,0 @@
-import { type RegisteredTool } from '../server.ts';
-/**
- * Decide which app credential `run_proof` should sign with, BEFORE
- * calling it. `run_proof` requires an `ownerAddress` and does no
- * 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 declare function resolveOwnerKeyTool(): RegisteredTool;

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[];