@reclaimprotocol/agent 0.1.31 → 0.1.32

package/lib/mcp/api/operations.gen.js

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:9ba46b5cbd7c).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:099a5bcf4fba).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
@@ -2098,6 +2098,21 @@ export const MCP_TOOLS = {
                                 "others"
                             ]
                         },
+                        "providerId": {
+                            "type": "string",
+                            "format": "uuid"
+                        },
+                        "client": {
+                            "type": "string",
+                            "enum": [
+                                "auto",
+                                "portals",
+                                "verifier-app",
+                                "reclaim-browser-extension",
+                                "builder",
+                                "inapp-sdk"
+                            ]
+                        },
                         "from": {
                             "type": "string",
                             "maxLength": 40,
@@ -2110,10 +2125,6 @@ export const MCP_TOOLS = {
                             "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$",
                             "description": "One end of a date window: either a calendar date (`2026-09-01`, read as UTC midnight) or a full ISO date-time. The date-only form is what a native `<input type=\"date\">` submits, so `format: date-time` alone would reject every filter the dashboard's own form sends."
                         },
-                        "providerId": {
-                            "type": "string",
-                            "format": "uuid"
-                        },
                         "verificationClientId": {
                             "type": "string",
                             "minLength": 1,

package/lib/mcp/instructions.js

@@ -67,7 +67,7 @@ const TOPIC_SUMMARIES = {
     'discover': 'Finding providers, resolving them, and creating a verification '
         + 'session.',
     'integration': 'Set up a Builder token, callback, frontend and backend '
-        + 'with @reclaimprotocol/client; direct `api=2` API and result '
+        + 'over the HTTP session API; direct `api=2` API and result '
         + 'verification.',
     'user-script': 'Authoring jsUserScripts / customInjection to drive '
         + 'login-gated pages.',

package/lib/old/tools/get-provider-info.js

@@ -34,7 +34,9 @@ export function getProviderInfoTool(client) {
         description: 'Read a PUBLISHED provider from the public production SDK backend ' +
             '(api.reclaimprotocol.org — what the verification SDK/attestor ' +
             'itself fetches at runtime), for ANY provider, no auth required. ' +
-            'This is the provider-read tool for old-devtools mode. \n\n' +
+            'This is the provider-read tool for old-devtools mode. A ' +
+            'published provider is usable as-is: don\'t re-verify it ' +
+            '(capture/replay/proof) unless the user asks to test it.\n\n' +
             'Returns two complementary reads for the given version (latest ' +
             'when `versionNumber` is omitted): `provider` (the FULL provider ' +
             '+ providerConfig — `customInjection`, `userAgent`, ' +

package/package.json

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

package/skill/SKILL.builder.md

@@ -367,7 +367,10 @@ 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.
+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).
 
 **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
@@ -391,9 +394,17 @@ use, run the same flow the Discover UI does:
 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. `create_verification_session({ providers: [{ providerId }, …], context,
+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.
+   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.

package/skill/SKILL.old.md

@@ -318,8 +318,10 @@ applies them.
   would fetch. Reads the public production SDK backend directly, no auth.
 
 There's no create-then-version step and no org / public-review workflow here.
-When done, tell the developer the version is live and that they can integrate
-using the `providerId`.
+When done, tell the developer the version is live, then ask once how they want
+to use it — try it now, 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).
 
 **If the response includes `_notes` for an attached browser, follow them for an
 optional authenticated-state retest.** Only when its profile is still signed in,

package/skill/builder-mode.md

@@ -6,12 +6,37 @@ authoring tools.
 
 ## Claimant-facing Builder sessions
 
-This integration is separate from provider authoring. When asked to set up an
-app, read `how_it_works({ topic: "integration" })`, then configure the
-organization with generated tools (`list_orgs`, `create_org`,
-`create_org_callback_subscription`, and owner-only `issue_org_token`) and edit
-the app's frontend and backend with the coding agent's file tools. The guide
-covers the `@reclaimprotocol/client` workflow, exact `api=2` boundary, result
+This integration is separate from provider authoring.
+
+**Using a provider.** A provider found with `providers`, `discover_resolve`, or
+another lookup is published and usable as-is. Don't capture, `replay_request`,
+or `run_proof` against it unless the developer asks you to check or test it.
+Before using a provider, found or just created, ask once whether they just want
+to try it or want it in an app (skip this if they already said):
+
+> Want to (1) just try it right now, (2) integrate it into an existing backend
+> or frontend (this directory or another path), or (3) create a new app for it?
+
+- **Just try it:** no app, callback, or client package. Create the session the
+  HTTP way (`create_verification_session`, i.e. `POST /verifications/sessions`
+  with the org secret as `Authorization: Bearer`; `issue_org_token` if there is
+  none), give the developer `verificationUrl` to open, then check the session
+  yourself (`get_verification_session`) until it is terminal and report the
+  outcome with `get_verification_result`.
+- **Integrate, or new app:** follow the setup below in the path they named.
+
+**Prefer the HTTP API over `@reclaimprotocol/client`** for every option:
+create sessions with `POST /verifications/sessions`, open `verificationUrl`,
+poll `GET /verifications/sessions/{sessionId}`, and take the result on the
+callback. Use the client package only when the developer asks for it — the one
+exception is `results.receive`, to verify the result on your callback.
+
+When integrating into an app, read `how_it_works({ topic: "integration" })`,
+then configure the organization with generated tools (`list_orgs`,
+`create_org`, `create_org_callback_subscription`, and owner-only
+`issue_org_token`) and edit the app's frontend and backend with the coding
+agent's file tools. The guide
+covers the HTTP session workflow, exact `api=2` boundary, result
 verification, request-proof contract, and optional TEE binding. A URL without
 `api=2` stays on its existing legacy path.
 
@@ -21,15 +46,15 @@ else:
 
 > This project uses `@reclaimprotocol/js-sdk`. Keep it (I switch this MCP
 > server to legacy devtools mode), or migrate to the Builder integration
-> (`@reclaimprotocol/client`)?
+> (Builder HTTP API)?
 
 - **Keep js-sdk:** call `set_devtools_mode({ mode: "old" })`, then tell them to
   restart or reconnect the MCP server; the switch applies on the next start. An
   explicit `USE_OLD_DEVTOOLS` env var overrides it. After the restart, read
   `get_js_sdk_integration_guide`.
 - **Migrate:** stay in Builder mode. Follow `how_it_works({ topic:
-  "integration" })` to replace `@reclaimprotocol/js-sdk` with
-  `@reclaimprotocol/client` and update the app's code.
+  "integration" })` to replace `@reclaimprotocol/js-sdk` with the Builder
+  HTTP session flow and update the app's code.
 
 **A `provider` is a recipe for extracting a data point from a site. A
 `verification` is an end-user session that proves a data point using one. Never

package/skill/old-mode.md

@@ -55,6 +55,18 @@ existing provider instead; you can only version a provider you own. For a
 multi-request provider pass `providers: [draftA, draftB, …]` so each becomes a
 parallel `requestData` entry on the one version.
 
+**Using a provider.** A provider found with `get_me_providers` or
+`get_provider_info` is published and usable as-is. Don't capture,
+`replay_request`, or `run_proof` against it unless the developer asks you to
+check or test it. Before using a provider, found or just created, ask once how
+they want to use it (skip this if they already said):
+
+> Want to (1) try it right now here, (2) integrate it into an existing backend
+> or frontend (this directory or another path), or (3) create a new app for it?
+
+Try it now → `scaffold_reclaim_demo_server` with its `providerId`. Integrate,
+or new app → `get_js_sdk_integration_guide`, then work in the path they named.
+
 **Two independent auth systems — don't confuse them.** `reclaim_authenticate`
 authorizes everything in this mode; its Firebase token is short-lived (~1h), so
 an auth error on publish or `get_me_providers` means re-run it.

package/skill/verification-client-integration.md

@@ -9,7 +9,7 @@ configure Builder resources; the coding agent's file tools edit the app.
 
 If the app depends on `@reclaimprotocol/js-sdk`, ask the developer first:
 keep it (call `set_devtools_mode({ mode: "old" })` and have them restart the MCP
-server), or migrate to `@reclaimprotocol/client` with the steps below. When
+server), or migrate to the Builder session flow below. When
 migrating, remove `@reclaimprotocol/js-sdk` and replace its
 `ReclaimProofRequest` and `verifyProof` calls with the session flow below.
 
@@ -26,14 +26,17 @@ migrating, remove `@reclaimprotocol/js-sdk` and replace its
    `RECLAIM_ORG_SECRET`; keep it out of frontend bundles, logs, source control,
    and the final response. Reuse an already configured secret when available;
    issue a new token when setup needs one.
-4. Install `@reclaimprotocol/client` in the backend. Use
-   `ReclaimVerification.create({ orgSecret })` to create sessions, save each
-   returned session ID alongside the app's own user or order, and return only
-   `verificationUrl` to the frontend. The frontend opens that URL and asks its
-   backend for the final status; a browser redirect alone is not proof of
-   success.
-5. Add a backend callback endpoint. Persist each delivery idempotently, load
-   the expected session ID and org ID from app storage, and call
+4. Prefer plain HTTP from the backend. Create sessions with
+   `POST /verifications/sessions` (`Authorization: Bearer <orgSecret>`), save
+   each returned session ID alongside the app's own user or order, and return
+   only `verificationUrl` to the frontend. The frontend opens that URL and asks
+   its backend for the final status (`GET /verifications/sessions/{sessionId}`);
+   a browser redirect alone is not proof of success. Use
+   `@reclaimprotocol/client` (`ReclaimVerification.create({ orgSecret })`,
+   `sessions.create`) only when the developer asks for it.
+5. Add a backend callback endpoint. Persist each delivery idempotently and load
+   the expected session ID and org ID from app storage. To verify the result on
+   your callback, install `@reclaimprotocol/client` in the backend and call
    `reclaim.results.receive(body, { reclaimSessionId, expectedAud,
    orgEthPrivateKey })`. Use the verified proof data to update app state.
    Handle callback retries and terminal failure outcomes.

package/src/mcp/api/operations.gen.ts

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:9ba46b5cbd7c).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:099a5bcf4fba).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
@@ -2162,6 +2162,21 @@ export const MCP_TOOLS = {
 								"others"
 							]
 						},
+						"providerId": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"client": {
+							"type": "string",
+							"enum": [
+								"auto",
+								"portals",
+								"verifier-app",
+								"reclaim-browser-extension",
+								"builder",
+								"inapp-sdk"
+							]
+						},
 						"from": {
 							"type": "string",
 							"maxLength": 40,
@@ -2174,10 +2189,6 @@ export const MCP_TOOLS = {
 							"pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?)?$",
 							"description": "One end of a date window: either a calendar date (`2026-09-01`, read as UTC midnight) or a full ISO date-time. The date-only form is what a native `<input type=\"date\">` submits, so `format: date-time` alone would reject every filter the dashboard's own form sends."
 						},
-						"providerId": {
-							"type": "string",
-							"format": "uuid"
-						},
 						"verificationClientId": {
 							"type": "string",
 							"minLength": 1,

package/src/mcp/instructions.ts

@@ -78,7 +78,7 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 	'discover': 'Finding providers, resolving them, and creating a verification '
 		+ 'session.',
 	'integration': 'Set up a Builder token, callback, frontend and backend '
-		+ 'with @reclaimprotocol/client; direct `api=2` API and result '
+		+ 'over the HTTP session API; direct `api=2` API and result '
 		+ 'verification.',
 	'user-script': 'Authoring jsUserScripts / customInjection to drive '
 		+ 'login-gated pages.',

package/src/old/tools/get-provider-info.ts

@@ -41,7 +41,9 @@ export function getProviderInfoTool(client: ReclaimSdkClient): RegisteredTool {
 				'Read a PUBLISHED provider from the public production SDK backend ' +
 				'(api.reclaimprotocol.org — what the verification SDK/attestor ' +
 				'itself fetches at runtime), for ANY provider, no auth required. ' +
-				'This is the provider-read tool for old-devtools mode. \n\n' +
+				'This is the provider-read tool for old-devtools mode. A ' +
+				'published provider is usable as-is: don\'t re-verify it ' +
+				'(capture/replay/proof) unless the user asks to test it.\n\n' +
 				'Returns two complementary reads for the given version (latest ' +
 				'when `versionNumber` is omitted): `provider` (the FULL provider ' +
 				'+ providerConfig — `customInjection`, `userAgent`, ' +