@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

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

@@ -1,19 +1,14 @@
 /**
  * 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.
+ * a host MCP server via `registerToolList` (server.ts) on the high-level
+ * `@modelcontextprotocol/sdk` `McpServer`. Folds the agent's tools
+ * alongside the 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 { ensureAttestorCrypto } from "../../../proof/proof-core.js";
 import { analyzeTool } from "./analyze.js";
 import { attachTool } from "./attach.js";
 import { captureTools } from "./capture.js";
@@ -24,18 +19,6 @@ import { makeSecretStore, proposeTool, } from "./propose.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { replayTool } from "./replay.js";
 import { sessionTools } from "./session.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;
-}
 function buildAgentState() {
     return {
         attach: { config: new ConfigStore() },
@@ -43,14 +26,14 @@ function buildAgentState() {
         secrets: makeSecretStore(),
     };
 }
-/** Build the flat list of `RegisteredTool` entries. Useful when the host
- *  uses our internal `ReclaimMcpServer` interface (`.register(tool)`).
+/** Build the flat list of `RegisteredTool` entries, ready for
+ *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
  *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
  *  capture/proof tools — old mode supplies its own publish tool. */
 export function buildAgentTools(client) {
     const state = buildAgentState();
-    ensureCryptoInit();
+    ensureAttestorCrypto();
     const tools = [];
     tools.push(attachTool(state.attach));
     for (const t of captureTools(state.attach, state.captures)) {

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

@@ -0,0 +1,2 @@
+export { buildAgentTools } from './build.ts';
+export type { AgentState } from './build.ts';

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

@@ -0,0 +1,3 @@
+// Barrel for the agent tool group (Chrome CDP capture, provider synthesis,
+// replay, zkTLS proof). Import from here, not the individual files.
+export { buildAgentTools } from "./build.js";

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

@@ -1,5 +1,6 @@
 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";
@@ -103,11 +104,6 @@ export function proofTool(secrets) {
         inputSchema: {
             type: 'object',
             properties: {
-                // `type: 'object'` is required so MCP clients (the LLM)
-                // serialize the value as an object, not a JSON-stringified
-                // string. `properties: {}` is required so zod-from-json-schema
-                // compiles to a passthrough instead of strict-strip — leaving
-                // it off makes the server receive `{}`.
                 provider: { type: 'object', properties: {} },
                 secretParamsRef: { type: 'string' },
                 attestorUrl: { type: 'string' },
@@ -132,7 +128,7 @@ export function proofTool(secrets) {
             }
             resolved = r;
         }
-        const result = await runAttestorProof(provider, resolved, attestorUrl, ownerAddress);
+        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) {
@@ -187,7 +183,7 @@ export function proofTool(secrets) {
         // when investigating proof failures and the file at runLogPath
         // will carry the input provider, sentParams, full attestor log
         // stream, and result.
-        if (process.env['RECLAIM_AGENT_TRACE'] === '1') {
+        if (agentTraceEnabled()) {
             const runLogPath = writeProofRunDump({
                 provider,
                 hasSecretParamsRef: secretParamsRef !== undefined,

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

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { draftProvider } from "../../../provider/draft.js";
 import { OPRF_MAX_BYTES } from "../../../provider/matcher.js";
+import { verificationWarnings } from "../../../provider/verification-checks.js";
 import { defineTool } from "../../server.js";
 export function makeSecretStore() {
     const map = new Map();
@@ -27,7 +28,11 @@ export function proposeTool(captures, secrets) {
             'cleartext. Skill should ask the dev first. `oprf-raw` ' +
             'is the only variant that runs ' +
             'without external deps; `oprf` needs gnark (Linux/macOS), ' +
-            '`oprf-mpc` needs a TEE attestor.',
+            '`oprf-mpc` needs a TEE attestor. ' +
+            'The response may include `verificationWarnings` — advisory ' +
+            'author-only decisions (e.g. a user-specific URL part needing ' +
+            'the {{context.<name>}}-vs-bare call). Surface each to the ' +
+            'dev verbatim and resolve before publishing.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -70,6 +75,12 @@ export function proposeTool(captures, secrets) {
             }
         }
         const secretParamsRef = secrets.put(realSecrets);
-        return { provider, secretRefs, secretParamsRef };
+        const warnings = verificationWarnings(provider);
+        return {
+            provider,
+            secretRefs,
+            secretParamsRef,
+            ...(warnings.length ? { verificationWarnings: warnings } : {}),
+        };
     });
 }

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

@@ -1,17 +1,120 @@
+import { INJECTION_GUIDE } from "../../../provider/injection-doc.js";
+import { countsFor, matchRedactionWarnings, } from "../../../provider/match-redaction-warning.js";
 import { nextVersion, providerToCreateVersionRequest, } from "../../../provider/to-version.js";
 import { defineTool } from "../../server.js";
+/** Schemas shared by the top-level `provider`/`providers` and the lighter
+ *  `allowedJsRequests` drafts — keeps the request shape from drifting between
+ *  them. */
+const RESPONSE_MATCHES_SCHEMA = {
+    type: 'array',
+    description: 'What the attestor checks on the revealed response slice.',
+    items: {
+        type: 'object',
+        properties: {
+            type: { type: 'string', enum: ['regex', 'contains'] },
+            value: { type: 'string' },
+        },
+        required: ['type', 'value'],
+    },
+};
+const RESPONSE_REDACTIONS_SCHEMA = {
+    type: 'array',
+    description: 'Which portions of the response the prover reveals ' +
+        '(xPath / jsonPath / regex; hash to OPRF the value). Paired with ' +
+        'responseMatches by index — keep them aligned 1-to-1. If you list more ' +
+        'redactions than matches, the tool pads matches with no-op optional ' +
+        'entries so older index-paired claim creators stay happy.',
+    items: {
+        type: 'object',
+        properties: {
+            xPath: { type: 'string' },
+            jsonPath: { type: 'string' },
+            regex: { type: 'string' },
+            hash: { type: 'string', enum: ['oprf', 'oprf-mpc', 'oprf-raw'] },
+        },
+    },
+};
+/** Properties every drafted request shares (top-level providers and the
+ *  injected `allowedJsRequests`). */
+const REQUEST_DRAFT_PROPERTIES = {
+    url: {
+        type: 'string',
+        description: 'Exact API URL the attestor replays, with {{param}} placeholders ' +
+            'for any templated values.',
+    },
+    method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH'] },
+    body: { type: 'string', description: 'Request body template, if any.' },
+    responseMatches: RESPONSE_MATCHES_SCHEMA,
+    responseRedactions: RESPONSE_REDACTIONS_SCHEMA,
+};
+/** A full provider draft (from propose_provider), passed through verbatim. */
+const PROVIDER_SCHEMA = {
+    type: 'object',
+    description: 'A `provider` object from propose_provider, passed through verbatim — ' +
+        'the tool builds the version body (the requests[] entry etc.) for you.',
+    properties: {
+        name: { type: 'string', description: 'Verification name.' },
+        ...REQUEST_DRAFT_PROPERTIES,
+        headers: {
+            type: 'object',
+            description: 'Request headers from the capture. Secret headers are stripped ' +
+                'before persistence; the client re-supplies them at runtime.',
+        },
+        paramValues: {
+            type: 'object',
+            description: 'Real values for the {{param}} placeholders, e.g. ' +
+                '{ "username": "Syed" }.',
+        },
+    },
+    required: ['name', 'url', 'method', 'responseMatches'],
+};
+/** One `allowedJsRequests` template: a request the injection script may fire,
+ *  plus pagination/optionality flags. */
+const ALLOWED_JS_REQUEST_SCHEMA = {
+    type: 'object',
+    properties: {
+        ...REQUEST_DRAFT_PROPERTIES,
+        multiple: {
+            type: 'boolean',
+            description: 'Allow the template to match many requests (e.g. pagination). ' +
+                'Default true.',
+        },
+        required: {
+            type: 'boolean',
+            description: 'Fail validation if no request matches this template. Default true.',
+        },
+    },
+    required: ['url', 'method'],
+};
 export function createVersionFromCaptureTool(client) {
     return defineTool({
         name: 'create_provider_version_from_capture',
-        description: 'Persist a drafted ReclaimProvider as a verification version. ' +
-            'Call this after run_proof succeeds, passing the `provider` object ' +
-            'from propose_provider VERBATIM. This tool builds the full version ' +
+        description: 'Persist drafted ReclaimProvider(s) as a verification version. ' +
+            'Call this after run_proof succeeds, passing the `provider` ' +
+            'object(s) from propose_provider VERBATIM. This tool builds the ' +
             'body (the requests[] array, webSettings, etc.) for you — do NOT ' +
             'hand-construct that shape or call create_provider_version directly. ' +
+            'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
+            'proven draft) — every entry becomes one request in the version, and ' +
+            'all are required at verification time. Pass a single `provider` ' +
+            'for the one-request case (exactly one of `provider`/`providers`). ' +
+            'For data gated behind login/navigation, supply `jsUserScripts` (a ' +
+            'page-injection script that drives the page to where the request ' +
+            'fires) and/or `allowedJsRequests` (extra requests the script may ' +
+            'fire, e.g. pagination). ' +
             'Omit `version` to have the tool auto-select the next available ' +
             'version (it lists existing versions and bumps past the highest). ' +
-            'For PRIVATE verifications the version goes live immediately; ' +
-            'for PUBLIC ones call submit_provider_version_for_review afterwards.',
+            'The version lands on the draft branch — to go live, call ' +
+            '`publish_provider_version` (PRIVATE) or ' +
+            '`submit_provider_version_for_review` (PUBLIC) afterwards. ' +
+            '`requiredContext` is derived from any {{context.<name>}} ' +
+            'placeholders across ALL requests (plus injected requests / script) ' +
+            'and returned on the created version — when present, tell the dev ' +
+            'verbatim which context fields consumers MUST send when creating ' +
+            'sessions (verification matches those values exactly; a missing ' +
+            'field is a 400 at session create). ' +
+            'Refine types/descriptions via `update_provider_version` while ' +
+            'still on draft.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -19,71 +122,14 @@ export function createVersionFromCaptureTool(client) {
                     type: 'string',
                     description: 'UUID of the verification to publish the version on.',
                 },
-                provider: {
-                    type: 'object',
-                    description: 'The `provider` object from propose_provider, passed ' +
-                        'through verbatim — the tool builds the version body ' +
-                        '(the requests[] array etc.) for you.',
-                    properties: {
-                        name: { type: 'string', description: 'Verification name.' },
-                        url: {
-                            type: 'string',
-                            description: 'Exact API URL the attestor replays, with {{param}} ' +
-                                'placeholders for any templated values.',
-                        },
-                        method: {
-                            type: 'string',
-                            enum: ['GET', 'POST', 'PUT', 'PATCH'],
-                        },
-                        headers: {
-                            type: 'object',
-                            description: 'Request headers from the capture. Secret headers are ' +
-                                'stripped before persistence; the client re-supplies them ' +
-                                'at runtime.',
-                        },
-                        body: {
-                            type: 'string',
-                            description: 'Request body template, if any.',
-                        },
-                        responseMatches: {
-                            type: 'array',
-                            description: 'What the attestor checks on the revealed response slice.',
-                            items: {
-                                type: 'object',
-                                properties: {
-                                    type: { type: 'string', enum: ['regex', 'contains'] },
-                                    value: { type: 'string' },
-                                },
-                                required: ['type', 'value'],
-                            },
-                        },
-                        responseRedactions: {
-                            type: 'array',
-                            description: 'Which portions of the response the prover reveals ' +
-                                '(xPath / jsonPath / regex; hash to OPRF the value). ' +
-                                'Paired with responseMatches by index — the tool folds ' +
-                                'each one into the matching entry\'s `extract` in the ' +
-                                'persisted version, so keep them aligned 1-to-1.',
-                            items: {
-                                type: 'object',
-                                properties: {
-                                    xPath: { type: 'string' },
-                                    jsonPath: { type: 'string' },
-                                    regex: { type: 'string' },
-                                    hash: {
-                                        type: 'string',
-                                        enum: ['oprf', 'oprf-mpc', 'oprf-raw'],
-                                    },
-                                },
-                            },
-                        },
-                        paramValues: {
-                            type: 'object',
-                            description: 'Real values for the {{param}} placeholders, ' +
-                                'e.g. { "username": "Syed" }.',
-                        },
-                    },
-                    required: ['name', 'url', 'method', 'responseMatches'],
+                provider: PROVIDER_SCHEMA,
+                providers: {
+                    type: 'array',
+                    description: 'Multiple proven drafts → one multi-request version. Each ' +
+                        'entry has the same shape as `provider`. Pass this OR ' +
+                        '`provider`, not both.',
+                    items: PROVIDER_SCHEMA,
+                    minItems: 1,
                 },
                 initialUrl: {
                     type: 'string',
@@ -106,17 +152,68 @@ export function createVersionFromCaptureTool(client) {
                     },
                     required: ['major', 'minor', 'patch'],
                 },
+                jsUserScripts: {
+                    type: 'string',
+                    description: 'Plain JavaScript injected into the provider page before every ' +
+                        'page load (stored as webSettings.jsUserScripts). Use standard ' +
+                        'browser APIs (window.location, element.click(), forms) to ' +
+                        'drive login/navigation so the target request fires — the ' +
+                        'client already intercepts page requests, and window.Reclaim ' +
+                        'is only for rare edge cases, not navigation. The Builder ' +
+                        'verification client installs this to run before every page ' +
+                        'load (before navigating to initialUrl), matching old-devtool ' +
+                        'customInjection; window.Reclaim itself is not yet exposed ' +
+                        'there, so prefer plain browser JS. Guide:\n\n' +
+                        INJECTION_GUIDE,
+                },
+                allowedJsRequests: {
+                    type: 'array',
+                    description: 'Extra requests the injection script is allowed to fire ' +
+                        '(e.g. paginated API calls), as RequestSelectionTemplates. ' +
+                        '`multiple`/`required` default to true.',
+                    items: ALLOWED_JS_REQUEST_SCHEMA,
+                },
             },
-            required: ['providerId', 'provider', 'initialUrl'],
+            required: ['providerId', 'initialUrl'],
         },
     }, async (args) => {
+        // Exactly one of `provider` / `providers` — normalize to an array.
+        const hasMany = Array.isArray(args.providers) && args.providers.length > 0;
+        const hasOne = !!args.provider;
+        if (hasMany === hasOne) {
+            throw new Error('Pass exactly one of `provider` (a single draft) or ' +
+                '`providers` (an array of 1+ drafts).');
+        }
+        const providers = hasMany ? args.providers : [args.provider];
         // Auto-pick the next version if not explicit
         const ver = args.version ?? (await nextVersion(client, args.providerId));
-        const body = providerToCreateVersionRequest(args.provider, args.initialUrl, args.notes, ver);
-        const result = (await client.call('CreateProviderVersion', {
+        const body = providerToCreateVersionRequest(providers, args.initialUrl, {
+            notes: args.notes,
+            version: ver,
+            jsUserScripts: args.jsUserScripts,
+            allowedJsRequests: args.allowedJsRequests,
+        });
+        const result = await client.call('CreateProviderVersion', {
             params: { providerId: args.providerId },
             body,
-        }));
-        return result.data;
+        });
+        const created = result.data;
+        // Aggregate non-blocking advisories for the dev — nothing here blocks
+        // or alters what was published; the author keeps full control.
+        const notes = [];
+        // Match/redaction advisory across every request (+ injected requests).
+        const requestCounts = [
+            ...providers.map((p, i) => countsFor(`Request ${i + 1}`, p)),
+            ...(args.allowedJsRequests ?? []).map((r, i) => countsFor(`Injected request ${i + 1}`, r)),
+        ];
+        notes.push(...matchRedactionWarnings(requestCounts));
+        // Let the dev know how/when the script runs (and the window.Reclaim gap).
+        if (args.jsUserScripts?.trim()) {
+            notes.push('jsUserScripts will run in the Builder verification client before ' +
+                'every page load (before navigating to initialUrl), matching ' +
+                'old-devtool customInjection. window.Reclaim is not yet exposed ' +
+                'there, so prefer plain browser JS for navigation/interaction.');
+        }
+        return notes.length ? { ...created, _notes: notes } : created;
     });
 }

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

@@ -11,11 +11,6 @@ export function replayTool(secrets) {
         inputSchema: {
             type: 'object',
             properties: {
-                // `type: 'object'` is required so MCP clients (the LLM)
-                // serialize the value as an object, not a JSON-stringified
-                // string. `properties: {}` is required so zod-from-json-schema
-                // compiles to a passthrough instead of strict-strip — leaving
-                // it off makes the server receive `{}`.
                 provider: { type: 'object', properties: {} },
                 secretParamsRef: { type: 'string' },
             },

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

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

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

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

@@ -0,0 +1,72 @@
+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/authenticate/authenticate.js

@@ -0,0 +1,107 @@
+import { defineTool } from "../../server.js";
+import { writeSession } from "./session-cache.js";
+export function authenticateTool(client) {
+    return defineTool({
+        name: 'reclaim_authenticate',
+        description: 'Authorize the CLI / MCP to make authenticated API calls by having ' +
+            'the user sign in on the dashboard. Two steps:\n\n' +
+            'Step 1 — call with no arguments. Returns a `code` and `attachUrl`. ' +
+            'Tell the user to open the URL, sign in, and authorize.\n\n' +
+            'Step 2 — once the user says they have authorized, call again ' +
+            'with the same `code` from step 1 to check if confirmed. ' +
+            'Returns `LINKED` with a 2-day bearer token when confirmed, ' +
+            '`PENDING` if not yet, or `EXPIRED` if too long has passed.\n\n' +
+            'The token is cached in ~/.reclaim/config.json automatically.\n\n' +
+            'This bearer token authenticates dashboard/org-management calls ' +
+            '(e.g. list_orgs, issuing an org secret). Programmatic verification ' +
+            'calls use a separate org secret (rorg_…, set as RECLAIM_ORG_SECRET).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                code: {
+                    type: 'string',
+                    pattern: '^[A-HJ-NP-Z2-9]{5}$',
+                    description: '5-character code from a previous step-1 call. ' +
+                        'When provided, checks whether the user has ' +
+                        'confirmed that session instead of opening a new one.',
+                },
+            },
+        },
+    }, async (args) => {
+        // Step 2: check an existing session
+        if (args.code) {
+            return checkSession(client, args.code);
+        }
+        // Step 1: open a new auth-only session
+        const sessionResult = (await client.call('CreateAttachSession'));
+        const session = sessionResult.data;
+        return {
+            status: 'PENDING',
+            code: session.code,
+            attachUrl: session.attachUrl,
+            expiresAt: session.expiresAt,
+            instructions: `Open ${session.attachUrl} in your browser, sign in, and click ` +
+                '"Authorize this device". ' +
+                'Once done, call authenticate again with code: ' +
+                `"${session.code}" to confirm.`,
+        };
+    });
+}
+async function checkSession(client, code) {
+    let session;
+    try {
+        const sessionResult = (await client.call('GetAttachSession', {
+            params: { code }
+        }));
+        session = sessionResult.data;
+    }
+    catch (err) {
+        const status = err.status;
+        if (status === 404) {
+            return {
+                status: 'NOT_FOUND',
+                hint: 'Session not found — it may have expired (15-min window). ' +
+                    'Call authenticate without a code to start a new session.',
+            };
+        }
+        throw new Error(`Failed to check session: ${err.message}`);
+    }
+    if (session.status === 'LINKED') {
+        const token = session.token?.trim();
+        if (token) {
+            writeSession({
+                token,
+                expiresAt: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString(),
+            });
+            client.setToken(token);
+            return {
+                status: 'LINKED',
+                token,
+                note: 'Token cached in ~/.reclaim/config.json and active now.',
+            };
+        }
+        return {
+            status: 'LINKED_NO_TOKEN',
+            hint: 'Session confirmed but no token issued. ' +
+                'Restart the backend (npm run dev) and try again.',
+        };
+    }
+    if (session.status === 'EXPIRED') {
+        return {
+            status: 'EXPIRED',
+            hint: 'Session expired (15-min window passed). ' +
+                'Call authenticate without a code to start a new session.',
+        };
+    }
+    // Still PENDING
+    return {
+        status: 'PENDING',
+        code: session.code,
+        attachUrl: session.attachUrl,
+        hint: 'Session is still waiting. ' +
+            `Make sure you opened ${session.attachUrl}, ` +
+            'signed in, and clicked "Authorize this device". ' +
+            `Call authenticate again with code: "${session.code}"` +
+            ' once you have done so.',
+    };
+}