@reclaimprotocol/agent 0.1.34 → 0.1.36

package/lib/mcp/tools/verification/read-callback-events.js

@@ -0,0 +1,135 @@
+import { decryptCallback, ReclaimVerification } from '@reclaimprotocol/client';
+import { apiUrl } from "../../../consts.js";
+import { defineTool } from "../../server.js";
+import { resolveDecryptionKey } from "../authenticate/decrypt-key.js";
+import { ensureListener, orgClient, } from "./callback-listener.js";
+import { resolveOrgSecret } from "./result.js";
+/** Events whose `data` is the signed result (encrypted or plaintext JWS). */
+const RESULT_EVENTS = new Set([
+    'verification_success',
+    'verification_rejected',
+    'verification_error',
+    'verification_cancelled',
+]);
+export function readCallbackEventsTool(deps = {}) {
+    return defineTool({
+        name: 'read_callback_events',
+        description: 'Reads the events Reclaim sent to the organization\'s pull '
+            + 'listener, and decodes them: each result event is decrypted and '
+            + 'signature-verified into `result`, and each lifecycle event '
+            + 'returns its `eventData`. Call it to try a provider without an '
+            + 'app or to check what Reclaim sent for a session. Creates the '
+            + 'listener on first use, so it is not read-only. Filter with '
+            + '`sessionId`, or pass the previous `next` as `after` to read on. '
+            + 'Items with a lower sequence can appear late, so for a complete '
+            + 'read use `pending: true`. Returns `{ listener, items, next }`. '
+            + 'Encrypted results need the `RECLAIM_DECRYPT_KEY` that matches '
+            + 'the org keypair. To deliver events to your app\'s callback '
+            + 'route, call `proxy_callback_events`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: {
+                    type: 'string',
+                    format: 'uuid',
+                    description: 'Only events of this verification session.',
+                },
+                after: {
+                    type: 'string',
+                    pattern: '^[0-9]{1,19}$',
+                    description: 'The `next` value of a previous call.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 100,
+                    description: 'Events to return. Defaults to 50.',
+                },
+                pending: {
+                    type: 'boolean',
+                    description: 'Only events not yet acknowledged. `proxy_callback_events` '
+                        + 'acknowledges the events it delivers.',
+                },
+                orgToken: {
+                    type: 'string',
+                    pattern: '^rorg_',
+                    maxLength: 200,
+                    description: 'The organization API key (`rorg_…`). Defaults to '
+                        + 'the server\'s `RECLAIM_ORG_SECRET`, then the key saved by '
+                        + '`issue_org_token`. Never echo it back to the user.',
+                },
+            },
+        },
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const secret = resolveOrgSecret(args.orgToken);
+        const client = orgClient(secret, deps);
+        const listener = await ensureListener(secret, deps);
+        const { data } = await client.call('ListCallbackEvents', {
+            query: {
+                after: args.after,
+                limit: args.limit,
+                sessionId: args.sessionId,
+                pending: args.pending,
+            },
+        });
+        const hasResults = data.items.some((e) => RESULT_EVENTS.has(e.event));
+        const key = hasResults ? await resolveDecryptionKey() : undefined;
+        const reclaim = ReclaimVerification.create({
+            baseUrl: apiUrl(),
+            orgSecret: secret,
+            fetch: deps.fetch,
+        });
+        const items = [];
+        for (const item of data.items) {
+            items.push(await decode(item));
+        }
+        return {
+            listener,
+            items,
+            next: data.next,
+            ...(listener.created
+                ? {
+                    _notes: 'Created the pull listener; only sessions created from '
+                        + 'now on are recorded. It works only while this MCP server '
+                        + 'runs.',
+                }
+                : {}),
+        };
+        async function decode(item) {
+            const base = {
+                id: item.id,
+                sessionId: item.sessionId,
+                event: item.event,
+                deliveryStatus: item.deliveryStatus,
+                createdAt: item.createdAt,
+            };
+            try {
+                if (!RESULT_EVENTS.has(item.event)) {
+                    const received = await reclaim.results.receive(item.envelope);
+                    return received.kind === 'event'
+                        ? { ...base, eventData: received.eventData }
+                        : base;
+                }
+                const jws = await decryptCallback(key, item.envelope);
+                const outcome = await reclaim.results.verify(jws, {
+                    reclaimSessionId: item.sessionId,
+                });
+                return {
+                    ...base,
+                    result: { payload: outcome.payload, proofs: outcome.proofs },
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return RESULT_EVENTS.has(item.event)
+                    ? { ...base, resultError: message }
+                    : { ...base, eventError: message };
+            }
+        }
+    });
+}

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.36",
 	"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.36",
 		"@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,26 @@ 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.
 
+The app's frontend renders every state and every failure, never only a
+spinner. Follow "UI states" in `how_it_works({ topic: "integration" })`. The
+callback route responds `error.retryable ? 503 : 200` for a thrown
+`ResultVerificationError`; a result that failed verification gets 2xx.
+
+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. It keeps events in order per session and retries
+a session the app rejects with backoff, so other sessions keep flowing. When
+its status lists `blocked` sessions, read that session's callback route
+response and logs, and fix the app. 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,39 @@ 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. Store every failure on the verification session record and log it server-side: a failure event (`verification_rejected`, `verification_error`, `verification_cancelled`, `session_expired`), or a thrown `ResultVerificationError` (`error.reason` plus each failing proof's `reason`). Respond `error.retryable ? 503 : 200`. A result that failed verification gets 2xx, because retrying can't fix it. Read the exact pattern in `how_it_works({ topic: "integration" })`.
+- [ ] Add a status route the frontend polls. It returns the stored status, data points, and failure reason. While the app has no result, it also reads `GET /verifications/sessions/{sessionId}`, so a session that ended in Builder never stays pending.
+- [ ] Add a frontend Verify button that opens `verificationUrl`, and render every state in "UI states" in `how_it_works({ topic: "integration" })`: idle, waiting in the other tab, verifying, verified (with the data points), failed (plain-language reason and **Try again**), and expired or cancelled (**Try again**). Never leave a spinner as the only feedback.
+- [ ] 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 +65,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. If `blocked` is not empty, the app rejected that session's event: read the callback route's response and logs, fix the app, and check again.
+- [ ] Tell the developer exactly how to test: open the app, click Verify, sign in, and see the stored result. Also test one failure, such as cancelling in the verification tab, and confirm the app shows the failed state with **Try again**.
+- [ ] After they click Verify, read the delivered events from `proxy_callback_events` status (`recent`) or `read_callback_events`. If the result did not arrive, or the app shows an unexpected failure, 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."