@reclaimprotocol/agent 0.1.39 → 0.1.41

package/README.md

@@ -70,6 +70,38 @@ Defaults target the Builder backend, so **no env is needed for the common case**
 
 See [Backends](#backends) for the full env-var list.
 
+### Usage data
+
+The MCP server sends anonymous usage data to Builder so that Reclaim can see which tools developers use and where they get stuck.
+
+**What the server records**
+
+- When a session starts: the mode (Builder or devtools), whether the browser tools are on, your operating system family, your Node.js version, and the name and version of your MCP client, such as Claude Code.
+- For each tool call: the tool name, whether it succeeded, how long it took, and an error category such as `http_401`.
+- When you sign in.
+- For three tools only, the text you give them. `start_integration` records `goal` and `userRequest`. `propose_provider` records `userRequest`. `discover_resolve` records the domain and data points you search for. Don't put secrets or personal data in these fields.
+- A random client ID that the server saves in `~/.reclaim/config.json`. It isn't derived from your machine or account. After you sign in, Builder links earlier events from this client ID to your account.
+
+**What the server never records**
+
+- Any other tool argument.
+- Tool output, captured requests or responses, or file contents.
+- Error messages, tokens, keys, or cookies.
+
+**Where the data goes**
+
+Builder stores the events in its database. Builder forwards only a short list of event names and counts to Google Analytics, and never the text you typed.
+
+**Turn it off**
+
+Set `RECLAIM_TELEMETRY=0`, or set `DO_NOT_TRACK=1`, in the `env` block of your MCP client configuration. With either set, the server doesn't create a client ID and makes no analytics requests.
+
+```json
+"env": {
+  "RECLAIM_TELEMETRY": "0"
+}
+```
+
 ### Provider-authoring guide
 
 The MCP server is all you need — it ships a `how_it_works` tool that serves the capture → prove → publish guide **one topic at a time** (`overview`, `auth`, `browser`, `capture`, `draft`, `params`, `prove`, `publish`, `discover`, `user-script`, `interception`, `hash-validation`, `credentials`, `never-do`, `troubleshooting`). Call it with no arguments for the overview plus the topic index; every response repeats that index, so an agent that guessed wrong self-corrects without a second round-trip. Any MCP client can call it on demand; there's nothing extra to install.

package/lib/config/store.d.ts

@@ -16,6 +16,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
@@ -32,6 +35,10 @@ 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`. */
 export interface SavedOrgKeys {

package/lib/consts.d.ts

@@ -59,6 +59,11 @@ export declare function chromePath(): string | undefined;
  *  deployments by setting `RECLAIM_AGENT_DISABLED=1`. Shared by mcp/start and
  *  the old-mode authenticate tool. */
 export declare function agentDisabled(): boolean;
+/**
+ * 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 declare function telemetryEnabled(): boolean;
 /** Old-devtools backend base URL. */
 export declare function oldApiUrl(): string;
 /** Old-devtools analytics-logs service base URL (separate host). */

package/lib/consts.js

@@ -111,6 +111,16 @@ export function chromePath() {
 export function agentDisabled() {
     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() {
+    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() {
     return process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL;

package/lib/mcp/api/operations.gen.d.ts

@@ -444,6 +444,13 @@ export declare const MCP_TOOLS: {
             openWorldHint: boolean;
         };
     };
+    UpdateOrgKeypair: {
+        description: string;
+        inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+        annotations: {
+            openWorldHint: boolean;
+        };
+    };
     UpdateProvider: {
         description: string;
         inputSchema: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;

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: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.
@@ -117,7 +117,11 @@ export const MCP_TOOLS = {
                             "enum": [
                                 "providers",
                                 "revenue",
-                                "usage"
+                                "usage",
+                                "goals",
+                                "tools",
+                                "agents",
+                                "funnel"
                             ]
                         }
                     }
@@ -5058,7 +5062,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": {
@@ -6578,7 +6582,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": {
@@ -6855,6 +6859,52 @@ 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/lib/mcp/api/tools.js

@@ -2,6 +2,7 @@ import { unauthorized } from '@hapi/boom';
 import { ReclaimClient } from '@reclaimprotocol/client/api';
 import assert from 'node:assert';
 import { orgSecret } from "../../consts.js";
+import { startToolCall } from "../../telemetry/index.js";
 import { remapErrorAsResponse } from "../remap_errors.js";
 import { successResponse } from "../success-response.js";
 import { savedOrgKey } from "../tools/authenticate/org-key-store.js";
@@ -48,6 +49,7 @@ export function registerTools(server, client, orgClient = (orgToken) => new Recl
         // and generated names must stay disjoint (see start.ts), so a clash is a
         // bug to surface, not silently shadow.
         server.registerTool(toSnakeCase(opId), shape, async (input) => {
+            const call = startToolCall(toSnakeCase(opId), input);
             try {
                 if (!isRecord(input)) {
                     throw new Error(`Invalid generated MCP arguments for ${opId}`);
@@ -60,9 +62,11 @@ export function registerTools(server, client, orgClient = (orgToken) => new Recl
                     ? orgClient(orgTokenFor(toSnakeCase(opId), orgToken, args))
                     : client;
                 const result = await caller.call(opId, args);
+                call.end();
                 return successResponse(result.data);
             }
             catch (err) {
+                call.end(err);
                 return remapErrorAsResponse(err);
             }
         });

package/lib/mcp/instructions.js

@@ -48,7 +48,8 @@ const TOPIC_SUMMARIES = {
     '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 '
@@ -60,15 +61,16 @@ const TOPIC_SUMMARIES = {
         + '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/lib/mcp/server.js

@@ -1,3 +1,4 @@
+import { startToolCall } from "../telemetry/index.js";
 import { toZod } from "./api/to-zod.js";
 import { remapErrorAsResponse } from "./remap_errors.js";
 import { successResponse } from "./success-response.js";
@@ -19,10 +20,14 @@ export function registerToolList(server, tools) {
                 ? { annotations: tool.definition.annotations }
                 : {}),
         }, 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/lib/mcp/start.js

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ReclaimClient } from '@reclaimprotocol/client/api';
 import { ConfigStore } from "../config/store.js";
-import { agentDisabled, apiToken, apiUrl, oldApiUrl, oldLogsUrl, resolveOldMode, sdkApiUrl, } from "../consts.js";
+import { agentDisabled, apiToken, apiUrl, oldApiUrl, oldLogsUrl, resolveOldMode, sdkApiUrl, telemetryEnabled, } from "../consts.js";
 import { LOGGER } from "../logger.js";
 import { ReclaimOldClient } from "../old/client.js";
 import { resolveInitialIdentity } from "../old/identity.js";
@@ -11,6 +11,7 @@ import { ReclaimSdkClient } from "../old/sdk-client.js";
 import { buildOldBackendTools } from "../old/tools/build.js";
 import { NAME, VERSION } from "../pkg.js";
 import { startZkFilesDownload } from "../proof/zk-files.js";
+import { currentTelemetry, installTelemetry, Telemetry } from "../telemetry/index.js";
 import { registerTools } from "./api/tools.js";
 import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, releaseAllListeners, sessionRefreshingFetch, stopAllForwarders, } from "./tools/index.js";
 import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
@@ -47,6 +48,12 @@ 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));
@@ -106,6 +113,18 @@ export async function startMcpServer() {
     if (agentToolsEnabled || !oldMode) {
         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);
     // Fetch the proof files in the background so the first proof doesn't wait
@@ -143,6 +162,7 @@ function installShutdownHooks(state) {
         void Promise.all([
             stopAllForwarders(),
             releaseAllListeners(),
+            currentTelemetry()?.close(),
             current && disposeAgentState(current),
         ])
             .catch((err) => {
@@ -159,3 +179,9 @@ function installShutdownHooks(state) {
     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) {
+    return platform === 'darwin' || platform === 'linux' || platform === 'win32'
+        ? platform
+        : 'other';
+}

package/lib/mcp/tools/agent/example-app.d.ts

@@ -1,2 +1,6 @@
 import { type RegisteredTool } from '../../server.ts';
-export declare function exampleAppTool(fetchFn?: typeof fetch): RegisteredTool;
+export declare function exampleAppTool(fetchFn?: typeof fetch, isPortFree?: (port: number) => Promise<boolean>): RegisteredTool;
+/** 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 declare function isLoopbackPortFree(port: number): Promise<boolean>;

package/lib/mcp/tools/agent/example-app.js

@@ -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 } from "../../server.js";
+import { assertNoSymlinks, upsertEnvVar } from "../authenticate/eth-key.js";
 const REPO = 'reclaimprotocol/builder-example';
 /** GitHub tree paths are always `/`-separated, on every OS. */
 const BACKEND_PACKAGE = 'packages/backend/package.json';
@@ -21,19 +23,30 @@ 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 = 10000000;
-export function exampleAppTool(fetchFn = fetch) {
+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 = fetch, isPortFree = isLoopbackPortFree) {
     return defineTool({
         name: 'create_example_app',
         description: 'Writes the Reclaim example app (reclaimprotocol/builder-example: '
             + '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'],
@@ -60,10 +73,16 @@ export function exampleAppTool(fetchFn = fetch) {
                     : 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);
@@ -72,28 +91,63 @@ export function exampleAppTool(fetchFn = fetch) {
         assert(!conflicts.length, conflict('These files already exist with different content: '
             + `${conflicts.join(', ')}. Ask the developer whether to use `
             + 'another directory or move them.'));
-        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`, { headers: { Accept: 'application/vnd.github.sha' } });
         assert(res.ok, badGateway(`${REPO} commit lookup: HTTP ${res.status}`));
@@ -184,17 +238,6 @@ async function installFile(root, path, bytes) {
 function isEexist(err) {
     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, path) {
-    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, version) {
     const text = bytes.toString('utf8');
@@ -209,3 +252,23 @@ function gitBlobSha(bytes) {
         .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) {
+    const results = await Promise.all(LOOPBACK_HOSTS.map((host) => {
+        return new Promise((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/lib/mcp/tools/agent/propose.js

@@ -23,6 +23,13 @@ export function proposeTool(resolveBackend) {
         inputSchema: objectSchema({
             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: 'Default true: shorten each target `name` to its last '

package/lib/mcp/tools/agent/start-integration.d.ts

@@ -1,6 +1,8 @@
 import { type RegisteredTool } from '../../server.ts';
 interface StartIntegrationArgs {
     goal: string;
+    /** Recorded by telemetry only; the plan ignores it. */
+    userRequest?: string;
     orgId?: string;
     providerIds?: string[];
 }

package/lib/mcp/tools/agent/start-integration.js

@@ -30,6 +30,13 @@ export function startIntegrationTool() {
                     description: '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/lib/mcp/tools/authenticate/authenticate.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { createServer } from 'node:http';
 import * as oauth from 'openid-client';
+import { currentTelemetry } from "../../../telemetry/index.js";
 import { defineTool } from "../../server.js";
 import { authBaseFor, oauthRequestOptions, SCOPE, sessionFromTokens, } from "./oauth-config.js";
 import { readSession, writeSession } from "./session-cache.js";
@@ -181,6 +182,8 @@ async function beginSignIn(client, openBrowserFn) {
             });
             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) {

package/lib/mcp/tools/authenticate/eth-key.d.ts

@@ -38,6 +38,17 @@ export declare function ensureGitignored(projectDir: string, entry: string): voi
  * `envFile` is relative to `projectDir`.
  */
 export declare function upsertEnvVar(projectDir: string, envFile: string, name: string, value: string): string;
+/** Remove the `name=` line from a dotenv file, if there is one. */
+export declare function removeEnvVar(projectDir: string, envFile: string, name: string): void;
+/**
+ * Before `name` is overwritten, append its current value to
+ * `<envFile>.backup` (same directory) as a timestamped comment plus the
+ * `NAME=value` line. Appends, so repeated rotations keep history. Writes with
+ * mode 0600 and adds the backup to `.gitignore`. Returns the backup's absolute
+ * path, or `undefined` when the env file holds no value for `name`. Never
+ * returns or logs the value.
+ */
+export declare function backupEnvVar(projectDir: string, envFile: string, name: string, reason: string): string | undefined;
 /**
  * Persist a raw eth private key to the project `.env` as
  * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
@@ -48,3 +59,7 @@ export declare function writeEthKey(privateKeyHex: string, projectDir?: string):
     path: string;
     address: string;
 };
+/** Throws when `path` (relative to `root`), or any of its existing parents
+ *  under `root`, is a symlink: writing through one could land outside the
+ *  project. */
+export declare function assertNoSymlinks(root: string, path: string): void;