@reclaimprotocol/agent 0.1.40 → 0.1.42

package/lib/telemetry/tool-call.js

@@ -0,0 +1,102 @@
+import { isProblemError } from '@reclaimprotocol/client/api';
+import { currentTelemetry } from "./index.js";
+const GOAL_MAX = 300;
+const USER_REQUEST_MAX = 500;
+const DOMAIN_MAX = 200;
+const DATA_POINTS_MAX = 20;
+const DATA_POINT_MAX = 200;
+/**
+ * Times a tool call and records it. Call `end()` once when the call
+ * finishes. It never throws, so it can't change the outcome of the call.
+ */
+export function startToolCall(tool, args) {
+    const startedAt = Date.now();
+    return {
+        end(err) {
+            try {
+                const telemetry = currentTelemetry();
+                if (!telemetry) {
+                    return;
+                }
+                const input = allowlistedInput(tool, args);
+                telemetry.track('tool_call', {
+                    tool,
+                    ok: err === undefined,
+                    ...(err === undefined ? {} : { errorCode: errorCode(err) }),
+                    durationMs: Date.now() - startedAt,
+                    mode: telemetry.mode,
+                    ...(input ? { input } : {}),
+                });
+            }
+            catch {
+                // Telemetry must never affect a tool call.
+            }
+        },
+    };
+}
+/**
+ * A category for the error, such as `http_401`. It's never the message,
+ * because messages can contain URLs, tokens, or file paths.
+ */
+export function errorCode(err) {
+    if (isProblemError(err)) {
+        return `http_${err.output.statusCode}`;
+    }
+    if (isRecord(err) && err.isBoom === true && isRecord(err.output)) {
+        return `http_${String(err.output.statusCode)}`;
+    }
+    if (err instanceof Error) {
+        if (err.name === 'ZodError') {
+            return 'invalid_input';
+        }
+        if (err.name === 'TimeoutError' || err.name === 'AbortError') {
+            return 'timeout';
+        }
+    }
+    return 'error';
+}
+/**
+ * The only arguments Reclaim records, and only for these tools. They are the
+ * developer's own description of what they want to build, which tells us
+ * which providers to add. Every other argument is dropped here, so a new tool
+ * records nothing until you add it to this list on purpose.
+ */
+export function allowlistedInput(tool, args) {
+    if (!isRecord(args)) {
+        return undefined;
+    }
+    switch (tool) {
+        case 'start_integration':
+            return compact({
+                goal: cut(args.goal, GOAL_MAX),
+                userRequest: cut(args.userRequest, USER_REQUEST_MAX),
+            });
+        case 'propose_provider':
+            return compact({ userRequest: cut(args.userRequest, USER_REQUEST_MAX) });
+        case 'discover_resolve': {
+            const query = isRecord(args.query) ? args.query : {};
+            const dataPoints = Array.isArray(query.dataPoints)
+                ? query.dataPoints
+                    .slice(0, DATA_POINTS_MAX)
+                    .map((p) => cut(p, DATA_POINT_MAX))
+                    .filter((p) => p !== undefined)
+                : undefined;
+            return compact({
+                domain: cut(query.domain, DOMAIN_MAX),
+                dataPoints: dataPoints?.length ? dataPoints : undefined,
+            });
+        }
+        default:
+            return undefined;
+    }
+}
+function cut(value, max) {
+    return typeof value === 'string' && value ? value.slice(0, max) : undefined;
+}
+/** Returns the object, or undefined when every field is undefined. */
+function compact(obj) {
+    return Object.values(obj).some((v) => v !== undefined) ? obj : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.40",
+	"version": "0.1.42",
 	"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.40",
+		"@reclaimprotocol/client": "0.1.42",
 		"@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`.
 

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/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/config/store.ts

@@ -27,6 +27,9 @@ export interface ReclaimAgentConfig {
  *   - `old_devtools`  — externally-supplied identity for OLD-devtools mode
  *                       (USE_OLD_DEVTOOLS); independent of `session`'s
  *                       builder token. Deletable with the rest of `src/old/`.
+ *   - `analytics`     — the random, anonymous client ID the usage data is
+ *                       sent under (see telemetry/telemetry.ts); holds no
+ *                       personal data
  *   - `org_keys`      — organization API keys saved by `issue_org_token`, so
  *                       the org-key tools work without the key in a transcript
  * Sections are persisted independently via `ConfigStore.write`, which
@@ -43,6 +46,7 @@ export interface ReclaimConfig {
 	session?: CachedSession
 	old_devtools?: OldIdentity
 	org_keys?: SavedOrgKeys
+	analytics?: { clientId: string, createdAt: string }
 }
 
 /** Organization API keys (`rorg_…`) saved by `issue_org_token`. */

package/src/consts.ts

@@ -143,6 +143,17 @@ export function agentDisabled(): boolean {
 	return process.env.RECLAIM_AGENT_DISABLED === '1'
 }
 
+/**
+ * Whether the server may send anonymous usage data. Off when you set
+ * `RECLAIM_TELEMETRY=0` or the cross-tool `DO_NOT_TRACK=1` convention.
+ */
+export function telemetryEnabled(): boolean {
+	const doNotTrack = process.env.DO_NOT_TRACK?.toLowerCase()
+	return process.env.RECLAIM_TELEMETRY !== '0'
+		&& doNotTrack !== '1'
+		&& doNotTrack !== 'true'
+}
+
 /** Old-devtools backend base URL. */
 export function oldApiUrl(): string {
 	return process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL

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:ecdb0ee6d82e).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:c3421d6bcf76).
 // 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.
@@ -123,7 +123,11 @@ export const MCP_TOOLS = {
 							"enum": [
 								"providers",
 								"revenue",
-								"usage"
+								"usage",
+								"goals",
+								"tools",
+								"agents",
+								"funnel"
 							]
 						}
 					}

package/src/mcp/api/tools.ts

@@ -7,6 +7,7 @@ import type {
 } from '@reclaimprotocol/client/openapi'
 import assert from 'node:assert'
 import { orgSecret } from '../../consts.ts'
+import { startToolCall } from '../../telemetry/index.ts'
 import { remapErrorAsResponse } from '../remap_errors.ts'
 import { successResponse } from '../success-response.ts'
 import { savedOrgKey } from '../tools/authenticate/org-key-store.ts'
@@ -68,6 +69,7 @@ export function registerTools(
 			toSnakeCase(opId),
 			shape,
 			async(input: unknown) => {
+				const call = startToolCall(toSnakeCase(opId), input)
 				try {
 					if(!isRecord(input)) {
 						throw new Error(`Invalid generated MCP arguments for ${opId}`)
@@ -85,8 +87,10 @@ export function registerTools(
 						opId,
 						args,
 					)
+					call.end()
 					return successResponse(result.data)
 				} catch(err) {
+					call.end(err)
 					return remapErrorAsResponse(err)
 				}
 			},

package/src/mcp/server.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { startToolCall } from '../telemetry/index.ts'
 import { type RegisteredTool } from '../tools/registry.ts'
 import { toZod } from './api/to-zod.ts'
 import { remapErrorAsResponse } from './remap_errors.ts'
@@ -31,9 +32,13 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 					: {}),
 			},
 			async(args) => {
+				const call = startToolCall(tool.definition.name, args)
 				try {
-					return successResponse(await tool.handler(args))
+					const result = successResponse(await tool.handler(args))
+					call.end()
+					return result
 				} catch(err) {
+					call.end(err)
 					return remapErrorAsResponse(err)
 				}
 			},

package/src/mcp/start.ts

@@ -10,6 +10,7 @@ import {
 	oldLogsUrl,
 	resolveOldMode,
 	sdkApiUrl,
+	telemetryEnabled,
 } from '../consts.ts'
 import { LOGGER } from '../logger.ts'
 import { ReclaimOldClient } from '../old/client.ts'
@@ -19,6 +20,11 @@ import { ReclaimSdkClient } from '../old/sdk-client.ts'
 import { buildOldBackendTools } from '../old/tools/build.ts'
 import { NAME, VERSION } from '../pkg.ts'
 import { startZkFilesDownload } from '../proof/zk-files.ts'
+import {
+	currentTelemetry,
+	installTelemetry,
+	Telemetry
+} from '../telemetry/index.ts'
 import { registerTools } from './api/tools.ts'
 import {
 	type AgentState,
@@ -78,6 +84,13 @@ export async function startMcpServer() {
 			}),
 		headers: { 'User-Agent': `${NAME}/${VERSION}` },
 	})
+	// Anonymous usage data. Installed before any tool registers so every tool
+	// call is covered. When the developer opts out, nothing is created.
+	const mode = oldMode ? 'devtools' : 'builder'
+	if(telemetryEnabled()) {
+		installTelemetry(new Telemetry({ client: builderClient, mode }))
+	}
+
 	// Backend-mode toggle — available in both modes and regardless of whether
 	// the agent tools are enabled, so a user can always switch either direction.
 	registerToolList(server, buildModeTools(config, oldMode))
@@ -151,6 +164,19 @@ export async function startMcpServer() {
 		installShutdownHooks(() => agentState)
 	}
 
+	// The client's name and version arrive in the `initialize` handshake, so
+	// the session starts only after it completes.
+	server.server.oninitialized = () => {
+		const telemetry = currentTelemetry()
+		telemetry?.setAgent(server.server.getClientVersion())
+		telemetry?.track('session_start', {
+			mode,
+			agentTools: agentToolsEnabled,
+			os: knownOs(process.platform),
+			nodeVersion: process.versions.node,
+		})
+	}
+
 	const transport = new StdioServerTransport()
 	await server.connect(transport)
 
@@ -192,6 +218,7 @@ function installShutdownHooks(state: () => AgentState | undefined): void {
 		void Promise.all([
 			stopAllForwarders(),
 			releaseAllListeners(),
+			currentTelemetry()?.close(),
 			current && disposeAgentState(current),
 		])
 			.catch((err: unknown) => {
@@ -209,3 +236,10 @@ function installShutdownHooks(state: () => AgentState | undefined): void {
 	process.stdin.once('end', () => shutdown('stdin ended'))
 	process.stdin.once('close', () => shutdown('stdin closed'))
 }
+
+/** Maps the platform to the values the analytics API accepts. */
+function knownOs(platform: NodeJS.Platform) {
+	return platform === 'darwin' || platform === 'linux' || platform === 'win32'
+		? platform
+		: 'other'
+}

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/propose.ts

@@ -28,6 +28,14 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 				{
 					requestId: { type: 'string' },
 					name: { type: 'string' },
+					userRequest: {
+						type: 'string',
+						maxLength: 500,
+						description:
+							'The developer\'s request in their own words, as they wrote it. '
+							+ 'Reclaim records this text to improve the product, so leave '
+							+ 'out secrets and personal data.',
+					},
 					shortenNames: {
 						type: 'boolean',
 						description:

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' },

package/src/mcp/tools/agent/start-integration.ts

@@ -4,6 +4,8 @@ import { defineTool, type RegisteredTool } from '../../server.ts'
 
 interface StartIntegrationArgs {
 	goal: string
+	/** Recorded by telemetry only; the plan ignores it. */
+	userRequest?: string
 	orgId?: string
 	providerIds?: string[]
 }
@@ -40,6 +42,14 @@ export function startIntegrationTool(): RegisteredTool {
 							'What the developer\'s users prove, for example, "they have '
 							+ 'a GitHub account with 100 followers".',
 					},
+					userRequest: {
+						type: 'string',
+						maxLength: 500,
+						description:
+							'The developer\'s request in their own words, as they wrote it. '
+							+ 'Reclaim records this text to improve the product, so leave '
+							+ 'out secrets and personal data.',
+					},
 					orgId: {
 						type: 'string',
 						format: 'uuid',

package/src/mcp/tools/authenticate/authenticate.ts

@@ -2,6 +2,7 @@ import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import { spawn } from 'node:child_process'
 import { createServer } from 'node:http'
 import * as oauth from 'openid-client'
+import { currentTelemetry } from '../../../telemetry/index.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import {
 	authBaseFor,
@@ -257,6 +258,8 @@ async function beginSignIn(
 			})
 			writeSession(session)
 			client.setToken(session.token)
+			// Link this machine's earlier anonymous usage to the new account.
+			void currentTelemetry()?.signedIn()
 			return { status: 'AUTHENTICATED', expiresAt: session.expiresAt }
 		} catch(err) {
 			return { status: 'FAILED', reason: failureReason(err) }

package/src/telemetry/index.ts

@@ -0,0 +1,18 @@
+import type { Telemetry } from './telemetry.ts'
+
+export { startToolCall } from './tool-call.ts'
+export { Telemetry } from './telemetry.ts'
+
+let current: Telemetry | undefined
+
+/**
+ * Makes `telemetry` the instance the hooks report to. Until you call this,
+ * the hooks do nothing, which is how opt-out and tests stay silent.
+ */
+export function installTelemetry(telemetry: Telemetry | undefined) {
+	current = telemetry
+}
+
+export function currentTelemetry(): Telemetry | undefined {
+	return current
+}