@reclaimprotocol/agent 0.1.34 → 0.1.35

package/lib/mcp/tools/verification/result.d.ts

@@ -1,4 +1,10 @@
 import { type RegisteredTool } from '../../server.ts';
+/**
+ * Resolve the org secret used to authenticate verification reads. Auth is a
+ * single per-org bearer secret (`rorg_…`), not an eth signature: the call's
+ * `orgToken`, else `RECLAIM_ORG_SECRET`.
+ */
+export declare function resolveOrgSecret(orgToken?: string): string;
 /**
  * `get_verification_result` — check a session's status and, once a result has
  * been submitted, pull the stored payload(s) and verify locally. Auth is the

package/lib/mcp/tools/verification/result.js

@@ -25,7 +25,7 @@ const RESULT_EVENTS = new Set([
  * single per-org bearer secret (`rorg_…`), not an eth signature: the call's
  * `orgToken`, else `RECLAIM_ORG_SECRET`.
  */
-function resolveOrgSecret(orgToken) {
+export function resolveOrgSecret(orgToken) {
     const secret = orgToken?.trim() || orgSecret()?.trim() || savedOrgKey();
     assert(secret, new Error('No organization API key. Verification reads authenticate with the org '
         + 'secret (rorg_…): run issue_org_token to save a key, pass orgToken, '

package/lib/proof/check-attestor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Attestor reachability check. Proves a public request with a throwaway owner
+ * key to show whether the attestor works from this machine, independent of any
+ * developer provider or site.
+ */
+import { createClaimOnAttestor } from '@reclaimprotocol/attestor-core';
+import './patch-domhandler.ts';
+/**
+ * Default time budget for one check. A live run takes about 8 s; a longer
+ * budget risks the MCP client's own tool-call timeout.
+ */
+export declare const CHECK_ATTESTOR_TIMEOUT_MS = 45000;
+/**
+ * Request params for the check: the public CoinGecko price request from the
+ * attestor-core examples. Source:
+ * https://raw.githubusercontent.com/reclaimprotocol/attestor-core/refs/heads/main/example/coin-gecko.json
+ */
+export declare const COIN_GECKO_PARAMS: {
+    url: string;
+    method: "GET";
+    body: string;
+    headers: {
+        'User-Agent': string;
+        'Sec-Fetch-Mode': string;
+        'Sec-Fetch-Site': string;
+    };
+    responseMatches: {
+        invert: boolean;
+        type: "regex";
+        value: string;
+    }[];
+    responseRedactions: {
+        jsonPath: string;
+        regex: string;
+        xPath: string;
+    }[];
+    additionalClientOptions: {};
+};
+export type AttestorCheckErrorKind = 
+/** Socket, connection, DNS, TLS, or timeout failure. */
+'attestor-unreachable'
+/** The attestor answered and rejected or failed the claim. */
+ | 'attestor-error'
+/** Local setup (ZK files) failed before the attestor was contacted. */
+ | 'setup-failed';
+export interface AttestorCheckResult {
+    ok: boolean;
+    attestorUrl: string;
+    durationMs: number;
+    extractedParameters?: Record<string, string>;
+    error?: string;
+    errorKind?: AttestorCheckErrorKind;
+}
+/** Creates the claim on the attestor (`createClaimOnAttestor` by default). */
+export type CreateClaim = (args: Parameters<typeof createClaimOnAttestor>[0]) => Promise<unknown>;
+export interface CheckAttestorOptions {
+    attestorUrl?: string;
+    timeoutMs?: number;
+    /** Replaces the network call in tests. */
+    createClaim?: CreateClaim;
+    /** Replaces the ZK file download in tests. */
+    prepare?: () => Promise<void>;
+}
+/** True when `message` looks like a network failure rather than a rejection. */
+export declare function isNetworkError(message: string | undefined): boolean;
+/** Prove the public CoinGecko request once and classify the outcome. */
+export declare function checkAttestor(opts?: CheckAttestorOptions): Promise<AttestorCheckResult>;

package/lib/proof/check-attestor.js

@@ -0,0 +1,156 @@
+/**
+ * Attestor reachability check. Proves a public request with a throwaway owner
+ * key to show whether the attestor works from this machine, independent of any
+ * developer provider or site.
+ */
+import { createClaimOnAttestor } from '@reclaimprotocol/attestor-core';
+import { generateKeypair } from '@reclaimprotocol/client';
+import "./patch-domhandler.js";
+import { claimRejection, ensureAttestorCrypto, parseClaim, resolveAttestorUrl, } from "./proof-core.js";
+import { ensureZkFiles } from "./zk-files.js";
+/**
+ * Default time budget for one check. A live run takes about 8 s; a longer
+ * budget risks the MCP client's own tool-call timeout.
+ */
+export const CHECK_ATTESTOR_TIMEOUT_MS = 45000;
+/* eslint-disable @stylistic/max-len -- the source URL cannot wrap. */
+/**
+ * Request params for the check: the public CoinGecko price request from the
+ * attestor-core examples. Source:
+ * https://raw.githubusercontent.com/reclaimprotocol/attestor-core/refs/heads/main/example/coin-gecko.json
+ */
+/* eslint-enable @stylistic/max-len */
+export const COIN_GECKO_PARAMS = {
+    url: 'https://api.coingecko.com/api/v3/simple/price'
+        + '?ids=cardano,solana&vs_currencies=usd',
+    method: 'GET',
+    body: '',
+    headers: {
+        'User-Agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) '
+            + 'AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 Safari/604.1',
+        'Sec-Fetch-Mode': 'same-origin',
+        'Sec-Fetch-Site': 'same-origin',
+    },
+    responseMatches: [
+        {
+            invert: false,
+            type: 'regex',
+            value: 'cardano":{"usd":(?<cardanoPrice>\\d*\\.*\\d*)}',
+        },
+        {
+            invert: false,
+            type: 'regex',
+            value: 'solana":{"usd":(?<solanaPrice>\\d*\\.*\\d*)}',
+        },
+    ],
+    responseRedactions: [
+        { jsonPath: '$.cardano', regex: 'cardano":{"usd":(.*?)}', xPath: '' },
+        { jsonPath: '$.solana', regex: 'solana":{"usd":(.*?)}', xPath: '' },
+    ],
+    additionalClientOptions: {},
+};
+/** The only secret in the example request. */
+const COIN_GECKO_SECRET_HEADERS = {
+    Referer: 'https://www.coingecko.com/en/nft',
+};
+/** Prefix of the error raised when the check exceeds its time budget. */
+const CHECK_TIMEOUT_MESSAGE = 'attestor check timed out';
+/**
+ * Signals that the attestor connection failed. Bare "timeout", "timed out",
+ * and "websocket" are left out: a target site's errors contain them too.
+ */
+const NETWORK_ERROR_PATTERN = new RegExp([
+    'connection closed',
+    'ERROR_NETWORK_ERROR',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ETIMEDOUT',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'socket hang up',
+    'websocket (connection|error|closed|failed)',
+    '(failed|unable|could not) to connect',
+    CHECK_TIMEOUT_MESSAGE,
+].join('|'), 'i');
+/** True when `message` looks like a network failure rather than a rejection. */
+export function isNetworkError(message) {
+    return message !== undefined && NETWORK_ERROR_PATTERN.test(message);
+}
+/** Prove the public CoinGecko request once and classify the outcome. */
+export async function checkAttestor(opts = {}) {
+    const attestorUrl = resolveAttestorUrl(opts.attestorUrl);
+    const timeoutMs = opts.timeoutMs ?? CHECK_ATTESTOR_TIMEOUT_MS;
+    const createClaim = opts.createClaim ?? createClaimOnAttestor;
+    const prepare = opts.prepare ?? (async () => {
+        ensureAttestorCrypto();
+        await ensureZkFiles();
+    });
+    const startedAt = Date.now();
+    const finish = (outcome) => {
+        return { ...outcome, attestorUrl, durationMs: Date.now() - startedAt };
+    };
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`${CHECK_TIMEOUT_MESSAGE} after ${timeoutMs} ms`));
+        }, timeoutMs);
+    });
+    try {
+        try {
+            await Promise.race([prepare(), timeout]);
+        }
+        catch (err) {
+            const error = messageOf(err);
+            return finish({
+                ok: false,
+                error,
+                errorKind: error.startsWith(CHECK_TIMEOUT_MESSAGE)
+                    ? 'attestor-unreachable'
+                    : 'setup-failed',
+            });
+        }
+        const claim = await Promise.race([
+            createClaim({
+                name: 'http',
+                params: COIN_GECKO_PARAMS,
+                secretParams: { headers: COIN_GECKO_SECRET_HEADERS },
+                ownerPrivateKey: generateKeypair().privateKey,
+                client: { url: attestorUrl },
+                zkEngine: 'stwo',
+            }),
+            timeout,
+        ]);
+        const rejection = claimRejection(claim);
+        if (rejection !== undefined) {
+            return finish({
+                ok: false,
+                error: rejection,
+                errorKind: isNetworkError(rejection)
+                    ? 'attestor-unreachable'
+                    : 'attestor-error',
+            });
+        }
+        return finish({
+            ok: true,
+            extractedParameters: parseClaim(claim).extractedParameters,
+        });
+    }
+    catch (err) {
+        const error = messageOf(err);
+        return finish({
+            ok: false,
+            error,
+            errorKind: isNetworkError(error)
+                ? 'attestor-unreachable'
+                : 'attestor-error',
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.34",
+	"version": "0.1.35",
 	"description": "Reclaim Protocol tools for AI coding agents. Reclaim lets your app verify data points about its users, such as a follower count, an account balance, or an order history. This package is the Reclaim MCP server: it gives your agent the tools to find, build, test, and fix data verification providers by capturing and replaying browser requests, drafting provider recipes, running zkTLS proofs, and publishing provider versions.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -83,7 +83,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.1.5",
-		"@reclaimprotocol/client": "0.1.34",
+		"@reclaimprotocol/client": "0.1.35",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/skill/SKILL.builder.md

@@ -315,6 +315,11 @@ provider JSON. That's the final result.
 developer what's happening and drive the bootstrap yourself — see topic
 `credentials`. No restart needed, and the existing `draftId` stays valid.
 
+**Network error from `run_proof`.** Read its `diagnosis`. Attestor reachable
+→ the target site likely blocks the attestor's network; call
+`run_proof_via_pod`. Attestor unreachable → `check_attestor` confirms it; the
+fix is on the developer's network. Don't loop retries.
+
 <!-- common: prove-tail -->
 
 <!-- topic: publish -->
@@ -456,6 +461,7 @@ or omit `interceptorOptions`). If that fixes the provider, keep interception
 off and replace intercepted claims with `window.Reclaim.requestClaim`. Full
 checklist and remedies: topic `interception`.
 
-**Proof failures / attestor errors** → topic `prove`.
+**Proof failures / attestor errors** → topic `prove`. For a network error,
+read `run_proof`'s `diagnosis`, then `check_attestor` or `run_proof_via_pod`.
 **Browser won't launch or attach** → topic `browser`.
 **Missing signing key** → topic `credentials`.

package/skill/SKILL.common.md

@@ -112,13 +112,18 @@ Ask plainly:
 
 If they say yes:
 
-1. Call `share_browser_view` with no arguments. It returns the viewer `port` and
-   the `command` (`cloudflared tunnel --url http://localhost:<port>`). The MCP
-   server does not run cloudflared.
-2. Run `command` yourself in the background. If `cloudflared` is not installed,
-   ask the developer to install it; do not install it without their approval.
-3. Read its output for the `https://<words>.trycloudflare.com` URL. Never guess
-   or reconstruct the hostname.
+1. Call `share_browser_view` with no arguments. It returns the viewer `port`
+   and the `command` (`cloudflared tunnel --url http://localhost:<port>`). The
+   MCP server does not run cloudflared.
+2. Ask the developer to choose, and start no tunnel until they answer:
+   - **They run it (recommended).** They run `! <command>` in this session and
+     paste the `https://<words>.trycloudflare.com` URL. The tunnel then lives
+     in their shell, and they decide when it closes.
+   - **You run it.** They approve you running `command` in the background. If
+     `cloudflared` is not installed, ask them to install it; do not install it
+     without their approval.
+3. When you run it, read its output for the URL. Never guess or reconstruct the
+   hostname.
 4. Call `share_browser_view({ publicUrl })` with that URL. **Relay the returned
    `url` verbatim, on its own line.** It includes `liveview.html?magnify=1`.
 
@@ -138,8 +143,8 @@ If they say yes:
 - **Opening it on a phone lays the page out for that phone**, with touch,
   pinch-zoom and the soft keyboard. That is the reason to reach for `container`
   when a site only works on mobile.
-- **Stop the cloudflared process you started as soon as they're done.** The
-  browser keeps running. `dispose_browser` and `reset_session` stop the
+- **Stop a cloudflared process you started as soon as they're done.** If they
+  started it, tell them to stop it. The browser keeps running. `dispose_browser` and `reset_session` stop the
   container itself, but not your cloudflared process.
 - **Expose only the viewer port** that `share_browser_view` returns, never the
   browser's CDP port.
@@ -381,6 +386,13 @@ supplies are context params.
     `result.attestorLogs` and dumps `~/.reclaim/proof-runs/<timestamp>.json`
     (`runLogPath`). Off by default — suggest it for a recurring failure.
 
+    **Network errors** ("connection closed", `ERROR_NETWORK_ERROR`, timeouts):
+    read the result's `diagnosis`. It says whether the attestor is reachable
+    from this machine. If it is, the target site likely blocks the attestor's
+    network; in builder mode, run `run_proof_via_pod`. If it is not, call
+    `check_attestor` after the developer fixes their network. Do not loop
+    retries; one `run_proof` per change.
+
     **Do not auto-retry with a different `attestorUrl`.** There is one live
     public attestor; backup hostnames (`attestor-2.*`, and so on) **do not
     exist**. `attestorUrl` is only for a developer-supplied private/staging URL.

package/skill/builder-mode.md

@@ -42,19 +42,17 @@ or `run_proof` against it unless the developer asks.
 
 ### Try a provider without an app
 
-Use the production API the app will use. Session creation returns 409 while the
-org has no callback subscription, and results are stored only for subscriptions
-to the event the session ends with.
+Session creation returns 409 while the org has no callback subscription.
+`read_callback_events` creates the org's pull listener, which satisfies that
+check and holds results for you to read. No tunnel or public URL is needed.
 
-1. If the org has none, register a temporary subscription for all five ending
-   events with `create_org_callback_subscription` (for example, a tunnel to a
-   local listener that saves the body it receives).
+1. Call `read_callback_events`.
 2. `create_verification_session`, then give the developer `verificationUrl`.
-3. Poll `get_verification_session` until it is terminal. Report the outcome
-   from the listener's body, or with `get_verification_result` (works only
-   until the callback is delivered).
-4. `delete_org_callback_subscription` only after that. Deleting it also
-   deletes its stored results.
+3. Poll `get_verification_session` until it is terminal.
+4. Call `read_callback_events({ sessionId })` for the verified result.
+
+When you set up a new provider build, call `check_attestor` once. If it fails,
+tell the developer before they spend time on the build.
 
 ## Secrets
 
@@ -77,11 +75,18 @@ TEE binding. Edit the app with your file tools. Use the HTTP API
 `@reclaimprotocol/client`. The only exception is `results.receive` on the
 callback, or when the developer asks for the client package.
 
+For local development, call `proxy_callback_events({ port, path })` to forward
+events to the app's callback route on localhost. The local listener works only
+while this MCP server runs. Production needs a webhook:
+`create_org_callback_subscription` with the deployed app's public URL. Without
+one, session creation returns 409.
+
 Management tools (`list_orgs`, `create_org_callback_subscription`,
 `issue_org_token`) use the developer's sign-in. Session tools
 (`create_verification_session`, `get_verification_session`,
 `list_verification_events`, `list_verification_deliveries`,
-`retry_verification_callback`) are the production API and use the org key.
+`retry_verification_callback`, `read_callback_events`,
+`proxy_callback_events`) are the production API and use the org key.
 
 **Existing `@reclaimprotocol/js-sdk` projects.** If `package.json` depends on
 `@reclaimprotocol/js-sdk`, ask first:

package/skill/start-integration.md

@@ -12,11 +12,38 @@ Follow this plan end to end. Mark each step done as you go. Do not ask the devel
 - [ ] Call `list_orgs`. Use the only organization, or ask the developer which one when there are several.
 <!-- endif -->
 
-## 2. Get a provider
+## 2. Set up the app
+
+Setup does not need the provider, so it runs in parallel with step 3 or before it.
+
+**Delegation.** If you can run subagents, hand this step to one subagent and start step 3 now: step 3 needs the developer at the browser, step 2 does not. Give the subagent a self-contained brief:
+
+```
+Goal: let this app's users prove "{{goal}}" with Reclaim.
+Repository: <absolute path>. Organization: <org ID>.
+Task: do step 2 of the plan below and report the file paths you changed, the
+callback route URL, and the env variable that holds the provider ID.
+Do not build the provider. Never print or commit the org key.
+<paste the step 2 checklist>
+```
+
+Without subagents, do step 2 first.
+
+- [ ] Detect the app's framework and package manager from the repository, and use them. Read `how_it_works({ topic: "integration" })`.
+- [ ] Call `issue_org_token` with the organization, this project's absolute path, and the server env file. It writes the key to that file and never returns it. Never print or commit the key. Confirm the env file is in `.gitignore`.
+- [ ] Add a backend route that creates a verification session (`POST /verifications/sessions`) and returns `verificationUrl`. Read the provider ID from server config (an env variable such as `RECLAIM_PROVIDER_ID`), so the route works before the provider exists.
+- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points.
+- [ ] Add a frontend Verify button that opens `verificationUrl`, and shows the stored result when it arrives.
+- [ ] Start the app. Call `proxy_callback_events({ port, path })` with the callback route's port and path. It forwards the org's verification events to that route on localhost, with no public URL.
+<!-- ifnot:providerIds -->
+- [ ] Call `check_attestor` once. If it fails, tell the developer before they spend time on the provider build: this machine cannot reach the attestor.
+<!-- endif -->
+
+## 3. Get the provider
 
 <!-- if:providerIds -->
 - [ ] Use these existing providers: {{providerIds}}. Read each with `get_provider` and keep only the data points "{{goal}}" needs. Show the developer and use only those; ignore the rest.
-- [ ] If a provider needs any change (a missing data point, inputs the developer didn't ask for, a different value), make your own copy as the server instructions describe ("Choose the provider"). Otherwise skip to step 3.
+- [ ] If a provider needs any change (a missing data point, inputs the developer didn't ask for, a different value), make your own copy as the server instructions describe ("Choose the provider"). Otherwise skip to step 4.
 <!-- endif -->
 <!-- ifnot:providerIds -->
 Build a new organization-private provider for exactly "{{goal}}". Do not search published providers first.
@@ -37,13 +64,11 @@ Build a new organization-private provider for exactly "{{goal}}". Do not search
 - [ ] Call `dispose_browser` after asking the developer.
 <!-- endif -->
 
-## 3. Integrate into this codebase
+## 4. Wire the provider and test end to end
 
-- [ ] Read `how_it_works({ topic: "integration" })`.
-- [ ] Detect the app's framework and package manager from the repository, and use them.
-- [ ] Call `issue_org_token` with the organization, this project's absolute path, and the server env file. It writes the key to that file and never returns it. Never print or commit the key. Confirm the env file is in `.gitignore`.
-- [ ] Add a backend route that creates a verification session (`POST /verifications/sessions`) for the provider and returns `verificationUrl`.
-- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points.
-- [ ] Call `create_org_callback_subscription` for the result events, pointing at the callback route. Use a tunnel for local development.
-- [ ] Add a frontend Verify button that opens `verificationUrl`, and shows the stored result when it arrives.
-- [ ] Run the app, then tell the developer exactly how to test end to end: open the app, click Verify, sign in, and see the stored result.
+- [ ] Set the provider ID in the app's server config.
+- [ ] Confirm the callback route is forwarding: `proxy_callback_events` with no `stop` returns its status.
+- [ ] Tell the developer exactly how to test: open the app, click Verify, sign in, and see the stored result.
+- [ ] After they click Verify, read the delivered events from `proxy_callback_events` status (`recent`) or `read_callback_events`. If the result did not arrive, call `list_verification_deliveries` and fix the cause. Repeat until the app shows the stored result.
+- [ ] Ask the developer to set up the production callback. The local listener works only while this coding agent's MCP server runs; once it stops, the deployed app receives no results. Call `create_org_callback_subscription` with the deployed app's public callback route URL for all five session-ending events: `verification_success`, `verification_rejected`, `verification_error`, `verification_cancelled`, and `session_expired`.
+- [ ] If they have no deployed URL yet, tell them: "When you deploy, ask me to run `create_org_callback_subscription` with your public callback URL, or results will not reach the app."

package/skill/verification-client-integration.md

@@ -21,12 +21,16 @@ server), or migrate to the session flow below. When migrating, remove
 1. `get_devtools_mode` confirms Builder mode. `get_me` or `authenticate` signs
    in the developer. Find the organization with `list_orgs`; call `create_org`
    only when they want a new one.
-2. Register a callback URL owned by the app's backend with
-   `create_org_callback_subscription`. Include terminal success, rejection,
-   error, cancellation, and expiry events. If the app needs encrypted results,
-   register its public key with `set_org_keypair`; keep the private key only in
-   the backend. `set_org_keypair` refuses to replace an existing key unless you
-   pass `replace: true`; pass it only when the developer asks.
+2. Receive callbacks. Local development: call
+   `proxy_callback_events({ port, path })` to forward the org's events to the
+   app's callback route on localhost; no public URL. Deployed app (required for
+   production): register a
+   public callback URL with `create_org_callback_subscription`, including
+   all five session-ending events. If the
+   app needs encrypted results, register its public key with `set_org_keypair`;
+   keep the private key only in the backend. `set_org_keypair` refuses to
+   replace an existing key unless you pass `replace: true`; pass it only when
+   the developer asks.
 3. Org key: reuse the `RECLAIM_ORG_SECRET` the app already has. Otherwise an
    organization owner calls `issue_org_token`. It writes the key to the
    project's env file (default `.env`, variable `RECLAIM_ORG_SECRET`) and
@@ -75,10 +79,12 @@ Use the API base URL the developer's Builder runs at (production:
 `https://build.reclaimprotocol.org`). Every call authenticates with
 `authorization: Bearer $RECLAIM_ORG_SECRET`.
 
-Subscribe a callback once (or use `create_org_callback_subscription`). Session
-creation returns 409 while the org has none, and a result is only delivered to
+Deployed apps subscribe a callback once (or use
+`create_org_callback_subscription`); local development uses
+`proxy_callback_events` instead. Session creation returns 409 while the org has
+no subscription, and a result is only delivered to
 subscriptions that include the event the session ends with, so subscribe to all
-five:
+five session-ending events:
 
 ```bash
 curl -X POST https://build.reclaimprotocol.org/verifications/callback-subscriptions \