@reclaimprotocol/agent 0.1.32 → 0.1.34

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

@@ -3,6 +3,7 @@ import assert from 'node:assert';
 import { apiUrl, orgSecret } from "../../../consts.js";
 import { defineTool } from "../../server.js";
 import { resolveDecryptionKey } from "../authenticate/decrypt-key.js";
+import { savedOrgKey } from "../authenticate/org-key-store.js";
 /** Statuses that can carry a Builder-managed terminal result. */
 const TERMINAL = new Set([
     'success',
@@ -11,16 +12,24 @@ const TERMINAL = new Set([
     'cancelled',
     'expired',
 ]);
+/** Events whose delivery is a signed result; the rest are plaintext event
+ *  notifications. Mirrors `verification_result_events()`. */
+const RESULT_EVENTS = new Set([
+    'verification_success',
+    'verification_rejected',
+    'verification_error',
+    'verification_cancelled',
+]);
 /**
  * Resolve the org secret used to authenticate verification reads. Auth is a
- * single per-org bearer secret (`rorg_…`), not an eth signature — read it from
- * `RECLAIM_ORG_SECRET`.
+ * single per-org bearer secret (`rorg_…`), not an eth signature: the call's
+ * `orgToken`, else `RECLAIM_ORG_SECRET`.
  */
-function resolveOrgSecret() {
-    const secret = orgSecret()?.trim();
-    assert(secret, new Error('RECLAIM_ORG_SECRET is not set. Verification reads authenticate with ' +
-        'the org secret (rorg_…) — issue one from the dashboard ' +
-        '(POST /orgs/{orgId}/token) and export it as RECLAIM_ORG_SECRET.'));
+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, '
+        + 'or export RECLAIM_ORG_SECRET for the MCP server.'));
     return secret;
 }
 /**
@@ -36,8 +45,12 @@ function resolveOrgSecret() {
 export function verificationResultTool() {
     return defineTool({
         name: 'get_verification_result',
-        description: 'Fetches and verifies a terminal Builder result for one session. '
-            + 'Requires `RECLAIM_ORG_SECRET`; encrypted deliveries also require '
+        description: 'Fetches and verifies a terminal Builder result for one session, '
+            + 'while Builder still holds it: until its callback is delivered, or '
+            + '7 days undelivered. The callback is the normal way to get results. '
+            + 'Authenticates with the org API key: `orgToken`, else '
+            + '`RECLAIM_ORG_SECRET`, else the key saved by `issue_org_token`. '
+            + 'Encrypted deliveries also require '
             + 'the matching ETH decryption key. Returns `ready: false` until a '
             + 'payload is available. Invalid results fail verification and are not '
             + 'returned. Use `list_verification_events` to diagnose '
@@ -50,10 +63,21 @@ export function verificationResultTool() {
                     type: 'string',
                     description: 'The verification session id from create_verification_session.',
                 },
+                orgToken: {
+                    type: 'string',
+                    pattern: '^rorg_',
+                    maxLength: 200,
+                    description: 'The organization API key (`rorg_…`): from '
+                        + '`issue_org_token`, or the app\'s RECLAIM_ORG_SECRET. '
+                        + 'Defaults to the MCP server\'s RECLAIM_ORG_SECRET, then the '
+                        + 'key saved by `issue_org_token`. Never echo it back to the '
+                        + 'user.',
+                },
             },
         },
+        annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {
-        const secret = resolveOrgSecret();
+        const secret = resolveOrgSecret(args.orgToken);
         // Optional eth decryption key — absent ⇒ plaintext-only.
         const decryptionKey = await resolveDecryptionKey();
         const reclaim = ReclaimVerification.create({
@@ -70,13 +94,29 @@ export function verificationResultTool() {
         const resultRes = await reclaim.api('GetVerificationResult', {
             params: { sessionId: args.reclaimSessionId },
         });
-        const { items } = resultRes.data;
+        const signed = resultRes.data.items
+            .filter((item) => RESULT_EVENTS.has(item.event));
+        if (!signed.length) {
+            return {
+                reclaimSessionId: args.reclaimSessionId,
+                status,
+                ready: false,
+                note: 'Session is terminal but no result is stored: none submitted '
+                    + 'yet, or no callback subscription covers its ending event.',
+            };
+        }
+        // Builder keeps a result (which can carry proofs) only until its
+        // callback is delivered, or 7 days undelivered.
+        const items = signed.flatMap((item) => (item.payload === null ? [] : [{ ...item, payload: item.payload }]));
         if (!items.length) {
             return {
                 reclaimSessionId: args.reclaimSessionId,
                 status,
                 ready: false,
-                note: 'Session is terminal but no result has been submitted yet.',
+                delivered: signed.some((item) => (item.deliveryStatus === 'delivered')),
+                note: 'Builder no longer holds this result: it was delivered to '
+                    + 'the callback (read it there), or went undelivered for 7 days. '
+                    + 'See list_verification_deliveries.',
             };
         }
         // Each item's `payload` is an ECIES ciphertext encrypted to the org's

package/lib/tools/registry.d.ts

@@ -1,8 +1,20 @@
 import type { JSONSchema } from 'zod/v4/core';
+/** MCP tool hints that let a client decide when to ask for approval. */
+export interface ToolAnnotations {
+    /** The tool never changes state. */
+    readOnlyHint?: boolean;
+    /** The tool can delete or overwrite state. */
+    destructiveHint?: boolean;
+    /** Repeating a call with the same input has no further effect. */
+    idempotentHint?: boolean;
+    /** The tool reaches systems outside this machine. */
+    openWorldHint?: boolean;
+}
 export interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: JSONSchema.ObjectSchema;
+    annotations?: ToolAnnotations;
 }
 export interface RegisteredTool {
     definition: ToolDefinition;

package/lib/tools/registry.js

@@ -75,6 +75,7 @@ export function extendTool(tool, extra) {
             name: base.name,
             description: extra.description ?? base.description,
             inputSchema,
+            ...(base.annotations ? { annotations: base.annotations } : {}),
         },
         handler: tool.handler,
     };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.32",
+	"version": "0.1.34",
 	"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.32",
+		"@reclaimprotocol/client": "0.1.34",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/skill/SKILL.builder.md

@@ -11,32 +11,38 @@ Builder.
 
 ## The loop, at a glance
 
-Copy this checklist and check off each step as you finish it. Read the linked
-topic before a step you aren't already fluent in.
-
-- [ ] 1. `attach_browser` — pick a browser source with the developer.
-      → topic `browser`
-- [ ] 2. `list_tabs` → `start_capture(tabId)` ⇒ **`captureId`**, your handle for
-      everything below. → topic `capture`
-- [ ] 3. Drive the page: `navigate`, `wait_for_page`, `eval_in_page`,
-      `get_cookies`. Detect login, land on the page showing the value, trigger
-      the request. → topic `capture`
-- [ ] 4. `find_requests_containing` → `analyze_request_constraints` → pick an
-      **authenticated** request. → topic `capture`
-- [ ] 5. `propose_provider(captureId, requestId, …)` ⇒ **`draftId`** (recipe +
-      captured secrets, held server-side — secrets never enter the transcript).
-      → topic `draft`
-- [ ] 6. Parameterize user-specific URL segments; mark secrets. → topic `params`
-- [ ] 7. `replay_request(captureId, draftId)`, then again with
+Build a new org-private provider for the claim the developer described. Ask
+one question if the site, account, or value is ambiguous. Copy this checklist
+and check off each step. Read the linked topic before a step you don't know.
+
+- [ ] 1. Name the data points: only the values the claim must prove, usually
+      one or two. No identity or profile fields.
+- [ ] 2. `attach_browser`, then `list_tabs` → `start_capture(tabId)` ⇒
+      **`captureId`**. → topics `browser`, `capture`
+- [ ] 3. Open the sign-in page and wait for the developer to sign in
+      (`wait_for_page`). → topic `capture`
+- [ ] 4. Write the navigation script: sign-in redirect, then each data
+      point's page in order. → topic `user-script`
+- [ ] 5. `test_user_script({ script, keep: true })`. Fix and retest until it
+      reaches every page, also after a reload.
+- [ ] 6. Capture by letting the script navigate: `find_requests_containing` →
+      `analyze_request_constraints` → pick an **authenticated** request per
+      data point. → topic `capture`
+- [ ] 7. `propose_provider(captureId, requestId, …)` ⇒ **`draftId`**
+      (`targets` = the data points). → topic `draft`
+- [ ] 8. Parameterize user-specific URL segments; mark secrets.
+      → topic `params`
+- [ ] 9. `replay_request(captureId, draftId)`, then again with
       `withoutSecrets: true`. → topic `prove`
-- [ ] 8. `run_proof(captureId, draftId, ownerAddress)`.
+- [ ] 10. `run_proof(captureId, draftId, ownerAddress)`.
       → topics `prove`, `credentials`
-- [ ] 9. Resolve a `providerId` (**reuse before create**) →
-      `create_provider_version_from_capture` → `publish_provider_version` or
+- [ ] 11. `create_provider` (or a new version of a provider your org owns) →
+      `create_provider_version_from_capture` (publishes the kept script as
+      `webSettings.jsUserScripts`) → `publish_provider_version` or
       `submit_provider_version_for_review`. → topic `publish`
 
-Multi-request provider? Run steps 5–8 once per request, then publish every
-proven draft in one call. See topic `publish`.
+Data points on different requests? Run steps 7-10 once per request, then
+publish every proven draft in one call. See topic `publish`.
 
 <!-- topic: contributions -->
 
@@ -84,7 +90,7 @@ integration. Prefer Builder for new integrations.
 2. **Pick a tab and start the capture.** `list_tabs`, then
    `start_capture(tabId)` ⇒ a **`captureId`**: the session handle every browser
    and inspect tool takes as its first argument (`navigate`, `eval_in_page`,
-   `wait_for_page`, `get_cookies`, `list_requests`, `find_requests_containing`,
+   `wait_for_page`, `list_requests`, `find_requests_containing`,
    `propose_provider`). If a tab is already on the right origin use it,
    otherwise the first is usually fine. Capturing from the start is harmless —
    it also records the login navigation. Then `navigate(captureId, url)` to
@@ -93,13 +99,18 @@ integration. Prefer Builder for new integrations.
 
 3. <!-- common: login-detect -->
 
-4. **Navigate to the page that displays the value.** Construct the URL from what
-   you know about the site; eval for anything you need (for example, GitHub's
-   `meta[name="user-login"]`'s `content`), then `navigate(captureId, url)`.
+4. **Write and keep the navigation script** (topic `user-script`) as soon as
+   the developer is signed in, or the sign-in URL is known. Test it with
+   `test_user_script` and `keep: true`. The script visits each data point's
+   page; build its URLs from what you know about the site and read page state
+   with `eval_in_page` when needed (for example, GitHub's
+   `meta[name="user-login"]`'s `content`).
 
-5. **Trigger the request.** Capture has been live since step 2, so make the
-   call fire: `eval_in_page(captureId, "location.reload()")`, or click an
-   element / hit a SPA route programmatically. Don't ask the developer to click.
+5. **Trigger the requests by letting the script navigate.** Capture has been
+   live since step 2. Reload the page (`eval_in_page(captureId,
+   "location.reload()")`) so the kept script runs from the start. Don't click
+   by hand or ask the developer to; if a request needs an interaction, add it
+   to the script.
 
 6. <!-- common: identify-value -->
 
@@ -126,8 +137,9 @@ integration. Prefer Builder for new integrations.
 under that `draftId`; the secrets never enter the transcript, so you carry the
 `draftId`, not the provider JSON, into replay/prove.
 
-**Extracting more than one value?** Prefer a **single request whose response
-contains all of them** and draft them together — one `responseMatches` +
+**Extracting more than one value?** Add a value only when the claim needs it.
+Prefer a **single request whose response contains all of them** and draft them
+together — one `responseMatches` +
 `responseRedactions` pair per value. Find that request by running
 `find_requests_containing` for each value and picking a `requestId` common to
 all. Then pass a `targets` array, each entry with its `value` (exactly as it
@@ -136,7 +148,7 @@ appears) and a distinct `name`:
 ```
 propose_provider(captureId, requestId, name, targets: [
   { value: "Scratch-net", name: "username" },
-  { value: "Alex",        name: "name" },
+  { value: "2019",        name: "member_since_year" },
 ])
 ```
 
@@ -313,16 +325,13 @@ parameterization applied. `initialUrl` is the page where the user logs in / the
 value is displayed (for example, `https://github.com/Syed`) — **not** the API
 endpoint URL inside the provider.
 
-**1. Reuse before create — this is how duplicates happen.**
-`create_provider_version_from_capture` requires a `providerId`. Before minting a
-new one, search your existing providers with `providers` (by domain / data
-point) — a site you've already built is there. Match → pass its
-`providerId` and the capture lands as a NEW VERSION on it. Only call
-`create_provider(orgId, domain, slug, title, description)` when none exists
-(`orgId` from `list_orgs`; `domain` such as `github.com`, `slug` such as
-`github-username`, `title` such as "GitHub Username"). It starts PRIVATE with an
-empty seed version. Routing every run through `create_provider` is what stacks
-duplicates in "My providers".
+**1. Resolve the `providerId`.** For a new claim, call
+`create_provider(orgId, domain, slug, title, description)` (`orgId` from
+`list_orgs`; `domain` such as `github.com`, `slug` such as `github-username`,
+`title` such as "GitHub Username"). It starts PRIVATE with an empty seed
+version. Use an existing `providerId` only when your org owns the provider and
+you are revising it: the capture lands as a NEW VERSION on it. For another
+org's provider that almost fits, create your own provider and version.
 
 **2. Persist the version.**
 `create_provider_version_from_capture(providerId, provider, initialUrl, notes)`
@@ -339,12 +348,13 @@ or archive an existing version to apply provider changes.
   required at verification time. This proves that every request matched; it
   does not automatically bind a value extracted from one response to another
   request.
-- **Login/navigation-gated data:** supply `jsUserScripts` (plain page JS that
-  drives login/waits/navigation so the target request fires), or
-  `allowedJsRequests` (extra requests the script may fire, for example,
-  pagination). → topic `user-script`. Before populating `allowedJsRequests` for
-  a `verifyRequestProof({ providerId })` use case, read topic `hash-validation` — a
-  session-unique URL there makes verifyRequestProof reject every real proof.
+- **Navigation script:** the script kept with `test_user_script` (`keep: true`)
+  is published as `webSettings.jsUserScripts`. Pass `jsUserScripts` only to
+  override it. → topic `user-script`. For extra requests the script may fire
+  (for example, pagination), pass `allowedJsRequests`. Before populating it for
+  a `verifyRequestProof({ providerId })` use case, read topic
+  `hash-validation`: a session-unique URL there makes `verifyRequestProof`
+  reject every real proof.
 
 **3. `requiredContext` is derived for you.** The publish tool scans the recipe's
 url/body for `{{context.<name>}}` placeholders and emits a JSON Schema requiring
@@ -367,10 +377,8 @@ developer it's awaiting admin review.
 context params — for example, `context: { "username": "…" }` in
 `create_verification_session`. Quote the `requiredContext` from the created
 version verbatim — a session missing those fields gets a 400, and verification
-matches the supplied values exactly. Then ask once how they want to use it —
-try it now here, integrate it into an existing backend or frontend, or create a
-new app — unless they already said (see "Using a provider" in the server
-instructions).
+matches the supplied values exactly. Then continue as the server
+instructions say under "What the developer wants".
 
 **6. If the response includes `_notes` for an attached browser, follow them for
 an optional authenticated-state retest.** Only when its profile is still signed
@@ -383,34 +391,30 @@ the session for further edits; call `dispose_browser` only after they confirm.
 A `builder` session is quota-accounted, so don't leave it idle.
 
 <!-- topic: discover -->
-## Discover and resolve providers for the developer's app
+## Discover and resolve existing providers
 
-When a developer wants to add verification but doesn't know which providers to
-use, run the same flow the Discover UI does:
+Use this flow only when the developer asks to reuse existing providers or
+doesn't know what a site supports. Otherwise build a new provider (server
+instructions, "Choose the provider").
 
 1. Ask which website their users prove data from.
 2. `discover_data_points({ domain })` → what's verifiable there. Confirm the
    data points with the developer.
 3. `discover_resolve({ domain, dataPoints })` → the smallest provider set
    (`providers`, greedy combine), the `requiredContext` inputs to collect, and
-   any `uncovered` points (author those with the flow above, then re-resolve).
-4. Resolved providers are published and usable as-is: don't capture, replay,
-   or prove them unless the developer asks you to check or test one. Ask once
-   whether they just want to try them or want them in an app — just try it
-   now, integrate into an existing backend or frontend (this directory or
-   another path), or create a new app — unless they already said.
-5. Just try it (no app, callback, or client package) →
-   `create_verification_session({ providers: [{ providerId }, …], context,
-   verificationClientUrl })` with EVERY resolved provider id and the collected
-   context, give them `verificationUrl`, poll `get_verification_session` until
-   it is terminal, and report the outcome with `get_verification_result`.
-   Integrate or new app → topic `integration`.
-
-`merge.mergeable` only signals the set *could* collapse into one provider — you
-still pass them all; the Builder runs them in one session.
-
-For client integration, result verification, or TEE binding, read topic
-`integration`.
+   any `uncovered` points (author those with the checklist in topic
+   `overview`, then re-resolve).
+4. Use only the data points the developer confirmed: show and read only those
+   and ignore the rest. A provider that needs any change gets your own copy
+   (server instructions, "Choose the provider"). Otherwise it's usable as-is;
+   don't capture, replay, or prove it unless the developer asks.
+5. To try them: `create_verification_session({ providers: [{ providerId }, …],
+   context, verificationClientUrl })` with EVERY resolved provider id and the
+   collected context. The server instructions ("Try a provider without an
+   app") cover the callback and polling. To integrate: topic `integration`.
+
+`merge.mergeable` only signals the set *could* collapse into one provider. Pass
+them all; the Builder runs them in one session.
 
 <!-- topic: integration -->
 

package/skill/SKILL.common.md

@@ -424,7 +424,8 @@ conversation.
 1. **`resolve_owner_key`** returns only the derived address.
    - `{ ready: true, address }` → call `run_proof` with it. No prompts.
    - `{ ready: false }` → ask the developer once: **their own key** →
-     `import_credentials({ privateKey: "0x…" })` (a `keyFile` path also works),
+     `import_credentials({ keyFile })` (a path to a file holding the key; never
+     ask them to paste it),
      or **a fresh one** → `issue_credentials({})` (a fine default for test
      proofs — owner identity doesn't matter). Either writes to the project
      `.env` (mode 0600, added to `.gitignore`), never to `~/.reclaim`. Then