@reclaimprotocol/agent 0.1.41 → 0.1.43

package/lib/authoring/tools.js

@@ -394,7 +394,10 @@ export function authoringTools(resolveBackend) {
                 + 'of the site, not a bug in the draft. HTTP 403/406/429/503 or a '
                 + 'challenge page from the attestor while the replay succeeded '
                 + 'means the site blocks non-browser clients: copying headers or '
-                + 'cookies will not help, so try a different endpoint or stop.',
+                + 'cookies will not help. Try one other endpoint; if that is '
+                + 'blocked too, publish the version from the capture and have '
+                + 'the developer try a real verification '
+                + '(how_it_works({ topic: "prove" })). Do not keep retrying.',
             inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
             annotations: { openWorldHint: true, destructiveHint: false },
         }, 

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

@@ -212,8 +212,10 @@ export function diagnoseBlockedClient(result, lastReplay, geoLocation) {
             + 'published version goes out from there too. Otherwise, try a '
             + 'different endpoint that returns the value, such as a JSON API the '
             + 'page calls (find_requests_containing), then propose and prove '
-            + 'that. If none works, stop and report to the developer that this '
-            + 'site blocks the attestor. Do not tweak headers.',
+            + 'that. If none works, stop retrying: publish the version from the '
+            + 'capture, unproven, and ask the developer to try a real '
+            + 'verification (how_it_works({ topic: "prove" })). Do not tweak '
+            + 'headers.',
     };
 }
 /** True when an attestor error embeds a response element (base64, from a

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

@@ -168,7 +168,10 @@ const BROWSER_REQUEST_ACTION_SCHEMA = {
 export function createVersionFromCaptureTool(client, attachRef, kept) {
     return defineTool({
         name: 'create_provider_version_from_capture',
-        description: 'Creates a new immutable provider version after `run_proof` succeeds. '
+        description: 'Creates a new immutable provider version after `run_proof` succeeds, '
+            + 'or from the captured draft when the site keeps answering replay or '
+            + 'proof with 403 past the retry budget in '
+            + 'how_it_works({ topic: "prove" }). '
             + 'Publishes the navigation script kept by `test_user_script` as '
             + '`jsUserScripts` unless `jsUserScripts` is passed. Pass exactly '
             + 'one `provider` or `providers` value returned by '

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

@@ -18,7 +18,9 @@ export function replayTool(resolveBackend) {
             + 'no cookies or auth headers, like an anonymous visitor. If the '
             + 'values still extract (`valid: true`), the endpoint is public and '
             + 'the proof would not bind to the user: choose an auth-bound '
-            + 'request instead.',
+            + 'request instead. A 403 that survives one retry and one '
+            + 'correction is a site defense, not a recipe bug: stop retrying '
+            + 'and publish from the capture (how_it_works({ topic: "prove" })).',
         inputSchema: objectSchema({
             draftId: { type: 'string' },
             withoutSecrets: { type: 'boolean' },

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.41",
+	"version": "0.1.43",
 	"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",
@@ -84,7 +84,7 @@
 		"@noble/hashes": "^2.2.0",
 		"@puppeteer/browsers": "3.2.4",
 		"@reclaimprotocol/attestor-core": "^5.1.6",
-		"@reclaimprotocol/client": "0.1.41",
+		"@reclaimprotocol/client": "0.1.43",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/skill/SKILL.builder.md

@@ -46,6 +46,11 @@ or asynchronous question tool for a blocking question.
       `webSettings.jsUserScripts`) → `publish_provider_version` or
       `submit_provider_version_for_review`. → topic `publish`
 
+Replay or proof blocked with 403 after one retry and one correction? Stop
+retrying and go straight to step 11: publish the draft unproven from the
+captured request, then ask the developer to try a real verification. → topic
+`prove`, "publish from the capture".
+
 Data points on different requests? Run steps 7-10 once per request, then
 publish every proven draft in one call. See topic `publish`.
 
@@ -439,7 +444,14 @@ one, or doesn't know what a site supports. Otherwise build a new provider.
    question; don't guess.
 5. To try them: `create_verification_session({ providers: [{ providerId }, …],
    context, verificationClientUrl })` with EVERY resolved provider id and the
-   collected context. Topic `integration` ("Try a provider without an app")
+   collected context. A session opens only in the client it was created for:
+   for an in-app SDK or add-to-app host, pass
+   `https://build.reclaimprotocol.org/share/inapp-sdk`; omitted, it is a
+   Portal session. For a native app, read the README of the
+   [iOS SDK](https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk#readme)
+   or the
+   [Android SDK](https://github.com/reclaimprotocol/reclaim-inapp-android-sdk#readme)
+   before writing app code. Topic `integration` ("Try a provider without an app")
    covers the callback and polling, and the integration steps.
 
 `merge.mergeable` only signals the set *could* collapse into one provider. Pass

package/skill/SKILL.common.md

@@ -409,9 +409,37 @@ supplies are context params.
     often after `replay_request` succeeded): the site blocks clients that
     aren't a real browser (bot protection or TLS fingerprint). Copying
     headers or cookies won't help, and `run_proof_via_pod` doesn't change the
-    TLS fingerprint. Try a different endpoint that returns the value (a JSON
-    API the page calls), or stop and report. Run `check_matchers` first so a
-    recipe bug isn't mistaken for blocking.
+    TLS fingerprint. Run `check_matchers` first so a recipe bug isn't
+    mistaken for blocking, then try ONE other endpoint that returns the value
+    (a JSON API the page calls). Blocked there too → publish from the
+    capture, below.
+
+    **Replay or proof keeps returning 403 (or another block): publish from
+    the capture.** A 403 from `replay_request` or `run_proof` says the site
+    defends against the authoring path. It does not say the recipe is wrong,
+    and a real verification runs inside the end user's own browser session,
+    which those defenses usually let through. Retry budget: one retry of the
+    same call, one correction (another endpoint, a `geoLocation` pin, or a
+    matcher fix via `check_matchers`), and one retry after the correction.
+    Past that, STOP. Don't re-capture, re-propose, or re-prove the same
+    request, and don't wait for the developer to tell you to stop. Instead:
+
+    1. Say plainly that replay/proof is blocked and that you are publishing
+       the version UNPROVEN, from the request you intercepted. Never say it
+       was proven.
+    2. Publish the draft as topic `publish` says
+       (`create_provider_version_from_capture`, then go live). The draft
+       holds the intercepted request, selectors, and params; that is all the
+       version needs.
+    3. Ask the developer to try it with a real verification. Builder mode:
+       `create_verification_session` and put its URL in the message. Legacy
+       devtools mode: the "try it" option in topic `publish`. End your turn
+       there.
+    4. When they return, check the session the usual way
+       (`get_verification_session` / `list_verification_events`, or the
+       devtools equivalent). Passed → done; it was only the authoring path
+       that was blocked. Failed with the same block → the site blocks
+       verification too; say so and look for a different endpoint.
 
     **Do not auto-retry with a different `attestorUrl`.** There is one live
     public attestor; backup hostnames (`attestor-2.*`, and so on) **do not
@@ -431,6 +459,9 @@ supplies are context params.
   never repeat them.
 - Never call `run_proof` before `replay_request` succeeds. Attestor calls are
   expensive.
+- Never loop a blocked replay or proof. A 403 that survives the retry budget
+  in `prove` means publish from the capture, unproven, and hand the developer
+  a real verification to try.
 - Never pretend a proof succeeded when `verified: false`. Show the error and
   iterate.
 - Never write a literal value into `responseMatches.value` — that bakes the

package/skill/SKILL.old.md

@@ -28,6 +28,11 @@ topic before a step you aren't already fluent in.
       → topics `prove`, `credentials`
 - [ ] 10. `create_provider_version_from_capture`. → topic `publish`
 
+Replay or proof blocked with 403 after one retry and one correction? Stop
+retrying and go straight to step 10: publish the draft unproven from the
+captured request, then ask the developer to try a real verification. → topic
+`prove`, "publish from the capture".
+
 Multi-request provider? Run steps 6–9 once per request, then publish every
 proven draft in one call. See topic `publish`.
 

package/skill/builder-mode.md

@@ -16,6 +16,7 @@ Provider-authoring and verification tools for the Builder backend.
 - Call `attach_browser()` with no arguments. Don't ask which browser to use.
 - Propose only the data points the claim needs.
 - Provider versions are immutable: every change creates a new version.
+- A 403 (or similar block) from `replay_request` or `run_proof` that survives one retry and one correction is not a reason to keep retrying. Publish the version from the captured request, say it is unproven, and ask the developer to try a real verification (topic `prove`).
 
 ## Asking the developer
 

package/skill/old-mode.md

@@ -9,6 +9,7 @@ Provider-authoring tools for the old devtools backend. The tool surface is reduc
 - A provider found with `get_me_providers` or `get_provider_info` is published and usable as-is. Don't capture, replay, or prove it unless the developer asks.
 - Before using a provider, found or just created, ask once how they want to use it (try it, integrate it, or build a new app), unless they already said. Topic `publish` has the options.
 - Call `attach_browser()` with no arguments. Don't ask which browser to use.
+- A 403 (or similar block) from `replay_request` or `run_proof` that survives one retry and one correction is not a reason to keep retrying. Publish the version from the captured request, say it is unproven, and ask the developer to try it (topic `prove`).
 
 ## Asking the developer
 

package/skill/verification-client-integration.md

@@ -98,6 +98,18 @@ legacy devtools mode), or migrate to the Builder HTTP API?"
    from `VerificationClient` in the SDK. Do not send an unregistered URL or
    call a legacy backend for an `api=2` session.
 
+   A session only works in the client it was created for: Builder fixes the
+   client at creation, and any other client gets
+   `403 x-reclaim-vc-id does not match this session`. For a mobile app using
+   the in-app SDK or the add-to-app module, create every session with
+   `verificationClientUrl` set to
+   `https://build.reclaimprotocol.org/share/inapp-sdk`
+   (`VerificationClient.inAppSdk`); the default Portal link won't open there.
+   For native iOS or Android apps, follow the
+   [iOS SDK README](https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk#readme)
+   or the
+   [Android SDK README](https://github.com/reclaimprotocol/reclaim-inapp-android-sdk#readme).
+
    The hosted verification page streams the target site as an image, so text
    and DOM checks of that page come back empty. Check a session's progress
    with `list_verification_events` and `get_verification_session` instead.
@@ -164,6 +176,60 @@ curl -X POST https://build.reclaimprotocol.org/verifications/sessions \
   }'
 ```
 
+For an in-app SDK or add-to-app host, add the in-app SDK's client URL and pass
+the returned `verificationUrl` to the app's `startVerificationFromUrl`:
+
+```bash
+curl -X POST https://build.reclaimprotocol.org/verifications/sessions \
+  -H "authorization: Bearer $RECLAIM_ORG_SECRET" \
+  -H "content-type: application/json" \
+  -d '{
+    "providers": [
+      {
+        "providerId": "<your-provider-id>"
+      }
+    ],
+    "context": {
+      "userId": "abc"
+    },
+    "verificationClientUrl": "https://build.reclaimprotocol.org/share/inapp-sdk"
+  }'
+```
+
+With `@reclaimprotocol/client`:
+
+```js
+import { ReclaimVerification, VerificationClient } from '@reclaimprotocol/client'
+
+const reclaim = ReclaimVerification.create({
+  orgSecret: process.env.RECLAIM_ORG_SECRET,
+})
+
+const session = await reclaim.sessions.create({
+  providers: [{ providerId: '<your-provider-id>' }],
+  context: { userId: 'abc' },
+  // Required for the in-app SDK and add-to-app module. Omitted, Builder
+  // selects the Portal, and the app's requests get 403.
+  verificationClientUrl: VerificationClient.inAppSdk,
+})
+// Store session.id; hand session.verificationUrl to the app.
+```
+
+The app opens it with `startVerificationFromUrl(verificationUrl)`. If the
+backend returns fields instead of a link, it calls
+`startVerificationFromJson({ "api": "2", "sessionId": session.id })` with the
+same result. Add `"diag": "1"` only when `verificationUrl` contains `diag=1`;
+other keys are ignored.
+
+For a native app, read the SDK's README before writing app code. Each README
+has a Builder mode section covering installation, starting from a URL or
+JSON, and handling the result:
+
+- iOS (Swift):
+  [reclaim-inapp-ios-sdk](https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk#readme)
+- Android (Kotlin/Java):
+  [reclaim-inapp-android-sdk](https://github.com/reclaimprotocol/reclaim-inapp-android-sdk#readme)
+
 Receive and verify the result on the callback route. This is the one place the
 client package is needed:
 

package/src/authoring/tools.ts

@@ -521,7 +521,10 @@ export function authoringTools(
 					+ 'of the site, not a bug in the draft. HTTP 403/406/429/503 or a '
 					+ 'challenge page from the attestor while the replay succeeded '
 					+ 'means the site blocks non-browser clients: copying headers or '
-					+ 'cookies will not help, so try a different endpoint or stop.',
+					+ 'cookies will not help. Try one other endpoint; if that is '
+					+ 'blocked too, publish the version from the capture and have '
+					+ 'the developer try a real verification '
+					+ '(how_it_works({ topic: "prove" })). Do not keep retrying.',
 				inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
 				annotations: { openWorldHint: true, destructiveHint: false },
 			},

package/src/mcp/tools/agent/proof.ts

@@ -286,8 +286,10 @@ export function diagnoseBlockedClient(
 			+ 'published version goes out from there too. Otherwise, try a '
 			+ 'different endpoint that returns the value, such as a JSON API the '
 			+ 'page calls (find_requests_containing), then propose and prove '
-			+ 'that. If none works, stop and report to the developer that this '
-			+ 'site blocks the attestor. Do not tweak headers.',
+			+ 'that. If none works, stop retrying: publish the version from the '
+			+ 'capture, unproven, and ask the developer to try a real '
+			+ 'verification (how_it_works({ topic: "prove" })). Do not tweak '
+			+ 'headers.',
 	}
 }
 

package/src/mcp/tools/agent/publish.ts

@@ -239,7 +239,10 @@ export function createVersionFromCaptureTool(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Creates a new immutable provider version after `run_proof` succeeds. '
+				'Creates a new immutable provider version after `run_proof` succeeds, '
+				+ 'or from the captured draft when the site keeps answering replay or '
+				+ 'proof with 403 past the retry budget in '
+				+ 'how_it_works({ topic: "prove" }). '
 				+ 'Publishes the navigation script kept by `test_user_script` as '
 				+ '`jsUserScripts` unless `jsUserScripts` is passed. Pass exactly '
 				+ 'one `provider` or `providers` value returned by '

package/src/mcp/tools/agent/replay.ts

@@ -21,7 +21,9 @@ export function replayTool(resolveBackend: ResolveBackend): RegisteredTool {
 				+ 'no cookies or auth headers, like an anonymous visitor. If the '
 				+ 'values still extract (`valid: true`), the endpoint is public and '
 				+ 'the proof would not bind to the user: choose an auth-bound '
-				+ 'request instead.',
+				+ 'request instead. A 403 that survives one retry and one '
+				+ 'correction is a site defense, not a recipe bug: stop retrying '
+				+ 'and publish from the capture (how_it_works({ topic: "prove" })).',
 			inputSchema: objectSchema(
 				{
 					draftId: { type: 'string' },