@reclaimprotocol/agent 0.1.39 → 0.1.41

package/skill/start-integration.md

@@ -4,7 +4,7 @@ Follow this plan end to end. Mark each step done as you go. Do not ask the devel
 
 **Order.** Do the steps that need the developer first: sign in to Builder, attach the browser, capture, and prove the provider (step 2). These need the developer at the browser, and they show early whether a proof is possible on this site. Write app code (step 3) after the proof works, or while you wait on the developer. Never spend a long stretch on app code before the developer has signed in and the browser is attached.
 
-**Asking the developer.** When you need an answer or an action from the developer before you can continue, end your turn with the question. Don't use background or asynchronous question tools for blocking questions: the developer may never see them. Put every link the developer needs, such as a sign-in or verification URL, in that same message.
+**Asking the developer.** When you need an answer or an action, end your turn with the question. Don't use background or asynchronous question tools: the developer may never see them. Put every link they need in that same message. Ask each question once.
 
 ## 1. Sign in and pick the organization
 
@@ -15,6 +15,7 @@ Follow this plan end to end. Mark each step done as you go. Do not ask the devel
 <!-- ifnot:orgId -->
 - [ ] Call `list_orgs`. Use the only organization, or ask the developer which one when there are several.
 <!-- endif -->
+- [ ] Call `get_org_keypair`. If the org has a key pair (any `canEncryptResult`), the app's callback must pass `orgEthPrivateKey` to `results.receive`: it decrypts encrypted results and verifies TEE-bound proofs. In the same message as any other step 1 question, ask the developer to choose one: reuse the existing key (they put its private key in the app's server env file as `RECLAIM_ORG_ETH_PRIVATE_KEY` themselves, never in chat), or rotate it (`issue_org_keypair` with `replace: true`; other apps holding the old key stop working with new results). If `canEncryptResult` is true, they can also turn encryption off with `update_org_keypair({ orgId, canEncryptResult: false })`, which keeps the key. Name the exact action in your question. Act on the answer in step 3.
 
 ## 2. Get the provider and prove it
 
@@ -39,7 +40,7 @@ Build a new organization-private provider for exactly "{{goal}}". Do not search
 - [ ] Call `replay_request`, then `replay_request` with `withoutSecrets: true` to confirm the request is auth-bound.
 - [ ] Call `run_proof`. It creates a local test signing key if none exists; tell the developer once afterwards.
 - [ ] Call `create_provider_version_from_capture`. It publishes the kept script as `jsUserScripts`. Follow its `_notes`, then publish the version.
-- [ ] Call `dispose_browser` after asking the developer.
+- [ ] Don't ask whether to close the browser. Mention once in your final summary that it stays open for provider changes and you can close it on request. Call `dispose_browser` only when the developer says so.
 <!-- endif -->
 
 ## 3. Set up the app
@@ -65,21 +66,23 @@ Do this yourself, not in a subagent.
 
 - [ ] Call `create_example_app` with the workspace root you were started in as `projectDir`. It writes the example there and sets its backend to the latest `@reclaimprotocol/client`. Don't clone the repository or create a subdirectory: commands you run inside a clone count as running external code, and permission checks may block them.
 - [ ] Call `issue_org_token` with the same `projectDir` and `envFile: "packages/backend/.env"`.
-- [ ] Only when the developer asks for session binding or encrypted results: call `issue_org_keypair` with the same `projectDir` and `envFile` (add `encryptResults: true` for encrypted results). It writes `RECLAIM_ORG_ETH_PRIVATE_KEY` and registers the public key. Then pass `orgEthPrivateKey: process.env.RECLAIM_ORG_ETH_PRIVATE_KEY` to `reclaim.sessions.create` in `packages/backend/src/routes/verifications.ts` (binding) and to `reclaim.results.receive` in `packages/backend/src/routes/callback.ts` (decryption and TEE proof checks), and add an empty `RECLAIM_ORG_ETH_PRIVATE_KEY=` line to `packages/backend/example.env`.
-- [ ] From the workspace root, run `npm install`, then `npm run dev`. The backend listens on port 3000; the app opens at <http://localhost:5173>. If a permission check blocks either command, don't work around it: end your turn, say which command was blocked and that it installs and runs the Reclaim example app, and ask the developer to approve it.
-- [ ] Call `proxy_callback_events({ port: 3000, path: "/reclaim/callback" })`.
-- [ ] Skip the rest of this step. In step 4, the provider goes in `packages/backend/config.json`: replace the example entry with `{ "id": "<provider ID>", "name": "<what it proves>" }`, then restart the backend, because it reads the file at startup.
+- [ ] Key pair, by the step 1 answer. No key pair on the org and the developer wants none: skip. Reuse: the developer has put the key in `packages/backend/.env`. Rotate, or no key pair and the developer asks for binding or encrypted results: call `issue_org_keypair` with the same `projectDir` and `envFile` (`encryptResults: true` for encrypted results, `replace: true` to rotate). It writes `RECLAIM_ORG_ETH_PRIVATE_KEY` and backs up a replaced key to `<envFile>.backup`; tell the developer that path (never the key). Turn encryption off with `update_org_keypair`. The example's callback (`packages/backend/src/routes/callback.ts`) passes `RECLAIM_ORG_ETH_PRIVATE_KEY` to `reclaim.results.receive`; if it doesn't, add `orgEthPrivateKey: process.env.RECLAIM_ORG_ETH_PRIVATE_KEY` there. For session binding, also pass it to `reclaim.sessions.create` in `packages/backend/src/routes/verifications.ts`.
+- [ ] From the workspace root, run `npm install`. Then follow the `next` array that `create_example_app` returned for the dev command, ports, log location, notes, and the `proxy_callback_events` call. Don't assume default ports.
+- [ ] Run the dev server in the background with its output redirected to a log file, and read that file for backend output. Don't depend on the shell's own output.
+- [ ] After you restart the backend, its in-memory store is empty. Ask the developer for a new verification; don't retry the old session.
+- [ ] If a permission check blocks a command, follow "Permission blocks" in the server instructions.
+- [ ] Skip the rest of this step. In step 4, the provider goes in `packages/backend/config.json`: replace the example entry with `{ "id": "<provider ID>", "name": "<what it proves>" }`, then restart the backend, because it reads the file at startup. Then ask for a new verification.
 
 **Existing app.** Add verification to it:
 
 - [ ] 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`.
+- [ ] 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; it backs up a replaced value to `<envFile>.backup`, so tell the developer that path. 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.
-- [ ] Only when the developer asks for session binding or encrypted results: call `issue_org_keypair` with the server env file (`encryptResults: true` for encrypted results), and pass `orgEthPrivateKey` from that env variable to `sessions.create` and `results.receive`.
+- [ ] Key pair, by the step 1 answer. Reuse: the developer has put the key in the server env file. Rotate, or no key pair and the developer asks for binding or encrypted results: call `issue_org_keypair` with the server env file (`encryptResults: true` for encrypted results, `replace: true` to rotate). It backs up a replaced key to `<envFile>.backup`; tell the developer that path (never the key). Turn encryption off with `update_org_keypair`. Whenever the org has a key pair, pass `orgEthPrivateKey` from `RECLAIM_ORG_ETH_PRIVATE_KEY` to `sessions.create` and `results.receive`.
 - [ ] 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.
+- [ ] Start the app in the background with output redirected to a log file. 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.
 
 ## 4. Wire the provider and test end to end
 

package/skill/verification-client-integration.md

@@ -22,26 +22,44 @@ configuration, and callback conventions. Complete the integration in its codebas
 relevant checks. The MCP tools configure Builder resources; your file tools
 edit the app.
 
-If the app depends on `@reclaimprotocol/js-sdk`, ask the developer first:
-keep it (`set_devtools_mode({ mode: "old" })`, then they restart the MCP
-server), or migrate to the session flow below. When migrating, remove
-`@reclaimprotocol/js-sdk` and replace its `ReclaimProofRequest` and
-`verifyProof` calls.
+If `package.json` depends on `@reclaimprotocol/js-sdk`, ask first: "This
+project uses `@reclaimprotocol/js-sdk`. Keep it (I switch this MCP server to
+legacy devtools mode), or migrate to the Builder HTTP API?"
+
+- **Keep:** `set_devtools_mode({ mode: "old" })`, then tell them to restart or
+  reconnect the MCP server. An explicit `USE_OLD_DEVTOOLS` env var overrides
+  it. After the restart, read `get_js_sdk_integration_guide`.
+- **Migrate:** stay in Builder mode, remove `@reclaimprotocol/js-sdk`, and
+  replace its `ReclaimProofRequest` and `verifyProof` calls with the session
+  flow below.
 
 1. `get_devtools_mode` confirms Builder mode. `get_me` or `authenticate` signs
    in the developer. Find the organization with `list_orgs`; call `create_org`
    only when they want a new one.
 2. Receive callbacks. Local development: call
    `proxy_callback_events({ port, path })` to forward the org's events to the
-   app's callback route on localhost; no public URL. Deployed app (required for
-   production): register a
+   app's callback route on localhost; no public URL. 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. Deployed app (required
+   for production): register a
    public callback URL with `create_org_callback_subscription`, including
    all five session-ending events. If the
    app needs encrypted results or session binding, call `issue_org_keypair`
    (`encryptResults: true` for encrypted results). It writes the private key to
    the backend's env file and registers only the public key. It returns 409
-   when the org already has a different key: ask the developer for that key
-   rather than replacing it.
+   when the org already has a different key. Check `get_org_keypair` first;
+   when the org has a key pair, the app must pass `orgEthPrivateKey` to
+   `results.receive`, with or without encryption: it decrypts results and
+   verifies TEE-bound proofs. Ask the developer to choose: reuse the key (they
+   put its private key in the backend's server env file as
+   `RECLAIM_ORG_ETH_PRIVATE_KEY` themselves, never in chat), rotate it with
+   `issue_org_keypair` and `replace: true` (apps holding the old key stop
+   working with new results; the old key is saved to `<envFile>.backup`, so
+   tell the developer that path), or turn encryption off with
+   `update_org_keypair({ orgId, canEncryptResult: false })`, which keeps the
+   key. Name the exact action when you ask.
 3. Org key: reuse the `RECLAIM_ORG_SECRET` the app already has. Otherwise an
    organization owner calls `issue_org_token`. It writes the key to the
    project's env file (default `.env`, variable `RECLAIM_ORG_SECRET`) and
@@ -254,6 +272,18 @@ Builder snapshots the organization's most recently updated active theme. A
 localized consent block tells supported clients to show consent before the
 first provider. Branding and theme data don't affect proof trust.
 
+## Try a provider without an app
+
+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. Call `read_callback_events`.
+2. `create_verification_session`, then give the developer `verificationUrl`.
+3. Poll `get_verification_session` until it is terminal.
+   `list_verification_events` shows progress.
+4. Call `read_callback_events({ sessionId })` for the verified result.
+
 ## Call the direct Builder API
 
 In `api=2` mode, send the registered client UUID in `x-reclaim-vc-id` on every

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:96339e8dff91).
+// 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"
 							]
 						}
 					}
@@ -5116,7 +5120,7 @@ export const MCP_TOOLS = {
 		annotations: {"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
 	},
 	"DeleteOrgKeypair": {
-		description: "Clear the organization's encryption keypair\n\nRemoves the organization's result encryption public key. Results are then delivered unencrypted until you set a new key. Run it only when the developer asks.",
+		description: "Clear the organization's encryption keypair\n\nRemoves the organization's result encryption public key. Results are then delivered unencrypted until you set a new key. Run it only when the developer asks. To rotate the key, use `issue_org_keypair` with `replace: true` instead of deleting first.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -6700,7 +6704,7 @@ export const MCP_TOOLS = {
 		annotations: {"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
 	},
 	"SetOrgKeypair": {
-		description: "Set (or rotate) the organization's encryption keypair\n\nRegisters the organization's result encryption public key and turns on encrypted result delivery. Send only the public key; the private key stays with the developer. If the organization already has a different key, the call returns 409 unless you pass replace: true. Pass it only when the developer asked to rotate the key, because results encrypted to the old key can no longer be decrypted. Setting the same key again succeeds.",
+		description: "Set (or rotate) the organization's encryption keypair\n\nRegisters the organization's result encryption public key and turns on encrypted result delivery. Send only the public key; the private key stays with the developer. If the organization already has a different key, the call returns 409 unless you pass replace: true. Pass it only when the developer asked to rotate the key, because results encrypted to the old key can no longer be decrypted. Setting the same key again succeeds. To generate and store the private key in the project, use `issue_org_keypair` instead.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -6985,6 +6989,54 @@ export const MCP_TOOLS = {
 		}),
 		annotations: {"openWorldHint":false},
 	},
+	"UpdateOrgKeypair": {
+		description: "Turn result encryption on or off\n\nTurns result encryption on or off for the organization's existing key pair without changing the key. Use it when the developer asks to turn encryption on or off. When on, the app's callback needs `orgEthPrivateKey` to decrypt results. Returns 404 when the organization has no key pair; create one with `issue_org_keypair`.",
+		inputSchema: toZod({
+			"type": "object",
+			"properties": {
+				"params": {
+					"type": "object",
+					"properties": {
+						"orgId": {
+							"type": "string",
+							"format": "uuid"
+						}
+					},
+					"required": [
+						"orgId"
+					],
+					"additionalProperties": false
+				},
+				"query": {
+					"type": "object",
+					"properties": {
+
+					}
+				},
+				"body": {
+					"type": "object",
+					"additionalProperties": false,
+					"description": "Body for `PATCH /orgs/{orgId}/keypair`.",
+					"required": [
+						"canEncryptResult"
+					],
+					"properties": {
+						"canEncryptResult": {
+							"type": "boolean",
+							"description": "Set to true to encrypt results to the organization's public key. Set to false to deliver results as plaintext."
+						}
+					}
+				}
+			},
+			"required": [
+				"params",
+				"query",
+				"body"
+			],
+			"additionalProperties": false
+		}),
+		annotations: {"openWorldHint":false},
+	},
 	"UpdateProvider": {
 		description: "Update a provider\n\nUpdates a provider's metadata, such as title, description, or tags. Partial update — pass only the fields to change. Requires active membership. To change the recipe (initialUrl or requests), cut a new version with create_provider_version instead.",
 		inputSchema: toZod({

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

@@ -59,7 +59,8 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 	'overview': 'Terminology, your stance, and the authoring checklist.',
 	'contributions': 'Contributing a public provider as a volunteer: the '
 		+ 'candidate-and-review workflow and the extra rules it adds.',
-	'auth': 'Signing in to the backend, and which token authorizes what.',
+	'auth': 'Signing in to the backend, which token authorizes what, and '
+		+ 'the backend mode (Builder or legacy devtools).',
 	'devtools-migration': 'Importing a public legacy provider with the same '
 		+ 'UUID.',
 	'browser': 'The default local browser, the opt-in modes (attach, the '
@@ -71,15 +72,16 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 		+ 'drafted shape.',
 	'params': 'Extracted vs consumer-supplied vs secret params, the URL '
 		+ 'character budget, and runtime resolution.',
-	'prove': 'replay_request, the mandatory auth-bound check, run_proof, and '
-		+ 'diagnosing failures.',
+	'prove': 'replay_request, the mandatory auth-bound check, run_proof '
+		+ '(including the egress country), and diagnosing failures.',
 	'publish': 'Creating a provider, provider versions, multi-request '
 		+ 'providers, and going live.',
-	'discover': 'Reusing existing providers: finding, resolving, and '
-		+ 'creating a verification session.',
-	'integration': 'After start_integration: org key, callback (local '
-		+ 'proxy_callback_events or deployed webhook), frontend and backend '
-		+ 'over the HTTP session API; `api=2` and result verification.',
+	'discover': 'Reusing existing providers: finding, resolving, copying one '
+		+ 'that needs changes, and creating a verification session.',
+	'integration': 'After start_integration: org key and keypair, callback '
+		+ '(local proxy_callback_events or deployed webhook), frontend and '
+		+ 'backend over the HTTP session API, js-sdk projects, trying a '
+		+ 'session without an app; `api=2` and result verification.',
 	'user-script': 'The navigation script (jsUserScripts): sign-in redirect, '
 		+ 'multi-page walk, test_user_script with keep.',
 	'interception': 'injectionType / interceptorType, live interception, the '

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/example-app.ts

@@ -10,10 +10,12 @@
 import { badGateway, badRequest, conflict } from '@hapi/boom'
 import assert from 'node:assert'
 import { createHash } from 'node:crypto'
-import { existsSync, lstatSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { mkdir, realpath, rm, writeFile } from 'node:fs/promises'
+import { connect } from 'node:net'
 import { isAbsolute, join, relative, sep } from 'node:path'
 import { defineTool, type RegisteredTool } from '../../server.ts'
+import { assertNoSymlinks, upsertEnvVar } from '../authenticate/eth-key.ts'
 
 const REPO = 'reclaimprotocol/builder-example'
 /** GitHub tree paths are always `/`-separated, on every OS. */
@@ -22,8 +24,20 @@ const CLIENT_PACKAGE = '@reclaimprotocol/client'
 /** The example is ~50 small files; anything far past that isn't it. */
 const MAX_FILES = 500
 const MAX_BYTES = 10_000_000
+const BACKEND_ENV_FILE = 'packages/backend/.env'
+const DEFAULT_BACKEND_PORT = 3000
+/** Ports probed for the backend: 3000, then 3001 through 3020. */
+const BACKEND_PORT_TRIES = 21
+const LOOPBACK_HOSTS = ['127.0.0.1', '::1']
+const PROBE_TIMEOUT_MS = 500
+/** Files a workspace may already have. An existing copy is kept, not a
+ *  conflict. The env-file tools add their own entries to `.gitignore`. */
+const KEEP_EXISTING = new Set(['AGENTS.md', '.gitignore'])
 
-export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
+export function exampleAppTool(
+	fetchFn: typeof fetch = fetch,
+	isPortFree: (port: number) => Promise<boolean> = isLoopbackPortFree,
+): RegisteredTool {
 	return defineTool<{ projectDir: string }>(
 		{
 			name: 'create_example_app',
@@ -32,12 +46,14 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 				+ 'a Fastify backend and a Vite frontend that create sessions, '
 				+ 'verify callbacks, and render every verification state) into '
 				+ '`projectDir`, and sets its backend to the latest '
-				+ '`@reclaimprotocol/client`. Use it when the workspace has no app '
+				+ '`@reclaimprotocol/client`. It picks a free backend port (3000, else '
+				+ 'the next free one, written to `packages/backend/.env`). Use it '
+				+ 'when the workspace has no app '
 				+ 'yet, with the workspace root you were started in as '
 				+ '`projectDir`; don\'t clone the repository yourself. Refuses '
 				+ 'when a file it would write already exists with different '
-				+ 'content. Returns the commit, file count, client version, and '
-				+ 'next steps.',
+				+ 'content. Returns the commit, file count, client version, '
+				+ '`backendPort`, and next steps.',
 			inputSchema: {
 				type: 'object',
 				required: ['projectDir'],
@@ -69,11 +85,17 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 						: bytes,
 				}
 			}))
-			for(const { path } of staged) {
+			for(const path of [...staged.map((f) => f.path), BACKEND_ENV_FILE]) {
 				assertNoSymlinks(projectDir, path)
 			}
 
-			const conflicts = staged
+			const kept = staged
+				.filter(({ path }) => {
+					return KEEP_EXISTING.has(path) && existsSync(join(projectDir, path))
+				})
+				.map(({ path }) => path)
+			const toWrite = staged.filter(({ path }) => !kept.includes(path))
+			const conflicts = toWrite
 				.filter(({ path, bytes }) => {
 					const dest = join(projectDir, path)
 					return existsSync(dest) && !readFileSync(dest).equals(bytes)
@@ -88,31 +110,72 @@ export function exampleAppTool(fetchFn: typeof fetch = fetch): RegisteredTool {
 				),
 			)
 
-			for(const { path, bytes } of staged) {
+			for(const { path, bytes } of toWrite) {
 				await installFile(projectDir, path, bytes)
 			}
 
+			const backendPort = await findBackendPort()
+			// Always written, so a re-run never leaves a stale port behind.
+			upsertEnvVar(projectDir, BACKEND_ENV_FILE, 'PORT', String(backendPort))
+
+			const dev = backendPort === DEFAULT_BACKEND_PORT
+				? 'npm run dev'
+				: `API_URL=http://localhost:${backendPort} npm run dev`
+
 			return {
 				projectDir,
 				repository: `https://github.com/${REPO}`,
 				commit,
-				files: staged.length,
+				files: toWrite.length,
+				kept,
 				clientVersion,
+				backendPort,
 				next: [
 					'Call issue_org_token with this projectDir and envFile '
 					+ '"packages/backend/.env".',
-					'Run `npm install`, then `npm run dev`, from projectDir. The '
-					+ 'backend listens on port 3000; the app opens at '
-					+ 'http://localhost:5173.',
-					'Call proxy_callback_events({ port: 3000, path: '
+					'Run `npm install` from projectDir, then start the dev '
+					+ `server with \`${dev}\`. The backend listens on port `
+					+ `${backendPort}`
+					+ (backendPort === DEFAULT_BACKEND_PORT
+						? '.'
+						: ` (port ${DEFAULT_BACKEND_PORT} is in use; the frontend `
+						+ 'proxy needs `API_URL`).'),
+					'Run the dev server in the background and send its output to a '
+					+ 'log file in projectDir, for example `npm run dev > '
+					+ 'reclaim-dev.log 2>&1`, so callback errors stay readable even '
+					+ 'when a shell output filter buffers output.',
+					'Give the developer the frontend URL Vite prints in that log. '
+					+ 'Don\'t assume port 5173: Vite moves to the next free port '
+					+ 'when it is taken.',
+					`Call proxy_callback_events({ port: ${backendPort}, path: `
 					+ '"/reclaim/callback" }).',
+					'If get_org_keypair shows `canEncryptResult: true`, the '
+					+ 'callback needs `orgEthPrivateKey`; see the plan.',
 					'Put the provider in packages/backend/config.json and restart '
 					+ 'the backend.',
+					'The backend stores verifications in memory: restarting it '
+					+ 'drops sessions in progress, so start a new verification '
+					+ 'after any restart.',
 				],
 			}
 		},
 	)
 
+	async function findBackendPort() {
+		for(let i = 0; i < BACKEND_PORT_TRIES; i++) {
+			const port = DEFAULT_BACKEND_PORT + i
+			if(await isPortFree(port)) {
+				return port
+			}
+		}
+
+		throw conflict(
+			`No free port from ${DEFAULT_BACKEND_PORT} to `
+			+ `${DEFAULT_BACKEND_PORT + BACKEND_PORT_TRIES - 1}. Ask the developer `
+			+ 'to stop another dev server.',
+		)
+	}
+
 	async function latestCommit() {
 		const res = await fetchFn(
 			`https://api.github.com/repos/${REPO}/commits/main`,
@@ -239,23 +302,6 @@ function isEexist(err: unknown) {
 	return err instanceof Error && 'code' in err && err.code === 'EEXIST'
 }
 
-/** Throws when `path`, or any of its existing parents under `root`, is a
- *  symlink: writing through one would land outside the workspace. */
-function assertNoSymlinks(root: string, path: string) {
-	let current = root
-	for(const part of path.split(/[\\/]/)) {
-		current += sep + part
-		const stat = lstatSync(current, { throwIfNoEntry: false })
-		assert(
-			!stat?.isSymbolicLink(),
-			badRequest(
-				`${current} is a symlink; the example app is only written to `
-				+ 'real directories inside the workspace',
-			),
-		)
-	}
-}
-
 /** The backend's package.json with the client range set to `^version`. */
 function withClientVersion(bytes: Buffer, version: string) {
 	const text = bytes.toString('utf8')
@@ -277,3 +323,24 @@ function gitBlobSha(bytes: Buffer) {
 		.update(bytes)
 		.digest('hex')
 }
+
+/** True when nothing accepts connections on `port` at 127.0.0.1 or ::1.
+ *  Connecting, rather than binding, also catches servers bound to `0.0.0.0`:
+ *  macOS lets a loopback bind succeed alongside them. Exported for tests. */
+export async function isLoopbackPortFree(port: number) {
+	const results = await Promise.all(LOOPBACK_HOSTS.map((host) => {
+		return new Promise<boolean>((resolve) => {
+			const socket = connect({ port, host, timeout: PROBE_TIMEOUT_MS })
+			socket.once('connect', () => {
+				socket.destroy()
+				resolve(false)
+			})
+			socket.once('timeout', () => {
+				socket.destroy()
+				resolve(true)
+			})
+			socket.once('error', () => resolve(true))
+		})
+	}))
+	return results.every(Boolean)
+}

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: