@reclaimprotocol/agent 0.1.40 → 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.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: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.
@@ -117,7 +117,11 @@ export const MCP_TOOLS = {
                             "enum": [
                                 "providers",
                                 "revenue",
-                                "usage"
+                                "usage",
+                                "goals",
+                                "tools",
+                                "agents",
+                                "funnel"
                             ]
                         }
                     }

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/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/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/telemetry/index.d.ts

@@ -0,0 +1,9 @@
+import type { Telemetry } from './telemetry.ts';
+export { startToolCall } from './tool-call.ts';
+export { Telemetry } from './telemetry.ts';
+/**
+ * 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 declare function installTelemetry(telemetry: Telemetry | undefined): void;
+export declare function currentTelemetry(): Telemetry | undefined;

package/lib/telemetry/index.js

@@ -0,0 +1,13 @@
+export { startToolCall } from "./tool-call.js";
+export { Telemetry } from "./telemetry.js";
+let current;
+/**
+ * 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) {
+    current = telemetry;
+}
+export function currentTelemetry() {
+    return current;
+}

package/lib/telemetry/telemetry.d.ts

@@ -0,0 +1,54 @@
+import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import type { IOperationArgs } from '@reclaimprotocol/client/openapi';
+import { ConfigStore } from '../config/store.ts';
+type TrackArgs = IOperationArgs<'TrackAnalyticsEvents'>;
+type Batch = TrackArgs['body'];
+type Event = Batch['events'][number];
+/** Backend mode, as the analytics API names it. */
+export type TelemetryMode = 'builder' | 'devtools';
+export interface TelemetryOptions {
+    client: ReclaimClient;
+    mode: TelemetryMode;
+    store?: ConfigStore;
+    /** How long to wait after the first queued event before sending. */
+    flushIntervalMs?: number;
+}
+/**
+ * Sends anonymous usage events to Builder. It never throws and never blocks
+ * a tool call: `track()` only queues, and a timer that doesn't keep the
+ * process alive sends the queue in the background. Failed batches are
+ * dropped, because usage data isn't worth retry loops in a tool server.
+ *
+ * Nothing is written to stdout. Stdio is the MCP transport.
+ */
+export declare class Telemetry {
+    #private;
+    readonly mode: TelemetryMode;
+    readonly clientId: string;
+    readonly sessionId: string;
+    constructor({ client, mode, store, flushIntervalMs, }: TelemetryOptions);
+    /** Records the MCP client (for example, Claude Code) that connected. */
+    setAgent(info: {
+        name: string;
+        version?: string;
+    } | undefined): void;
+    /** Queues an event. Synchronous, cheap, and safe to call anywhere. */
+    track<N extends Event['name']>(name: N, properties: Extract<Event, {
+        name: N;
+    }>['properties']): void;
+    /** Sends everything queued. Never rejects. */
+    flush(): Promise<void>;
+    /**
+     * Links this client's earlier anonymous events to the signed-in user.
+     * Needs a bearer token, so call it after sign-in.
+     */
+    identify(): Promise<void>;
+    /**
+     * Call when sign-in finishes. Sends the `login` event first so that
+     * `identify()` can attribute it to the user.
+     */
+    signedIn(): Promise<void>;
+    /** Sends what's left, waiting at most two seconds. */
+    close(): Promise<void>;
+}
+export {};

package/lib/telemetry/telemetry.js

@@ -0,0 +1,175 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Telemetry_instances, _Telemetry_client, _Telemetry_flushIntervalMs, _Telemetry_queue, _Telemetry_timer, _Telemetry_agent, _Telemetry_sending, _Telemetry_schedule, _Telemetry_send;
+import { randomUUID } from 'node:crypto';
+import { ConfigStore } from "../config/store.js";
+import { LOGGER } from "../logger.js";
+import { VERSION } from "../pkg.js";
+/** The API accepts up to 50 events per request. */
+const MAX_BATCH = 50;
+/** Bounds memory while the backend is unreachable. Oldest events go first. */
+const MAX_QUEUE = 500;
+/** How long `close()` waits, so a slow network can't hold up exit. */
+const CLOSE_LIMIT_MS = 2000;
+/**
+ * Sends anonymous usage events to Builder. It never throws and never blocks
+ * a tool call: `track()` only queues, and a timer that doesn't keep the
+ * process alive sends the queue in the background. Failed batches are
+ * dropped, because usage data isn't worth retry loops in a tool server.
+ *
+ * Nothing is written to stdout. Stdio is the MCP transport.
+ */
+export class Telemetry {
+    constructor({ client, mode, store = new ConfigStore(), flushIntervalMs = 5000, }) {
+        _Telemetry_instances.add(this);
+        this.sessionId = String(Math.floor(Date.now() / 1000));
+        _Telemetry_client.set(this, void 0);
+        _Telemetry_flushIntervalMs.set(this, void 0);
+        _Telemetry_queue.set(this, []);
+        _Telemetry_timer.set(this, void 0);
+        _Telemetry_agent.set(this, void 0);
+        /** Serializes sends so batches go out in order. */
+        _Telemetry_sending.set(this, Promise.resolve());
+        __classPrivateFieldSet(this, _Telemetry_client, client, "f");
+        this.mode = mode;
+        __classPrivateFieldSet(this, _Telemetry_flushIntervalMs, flushIntervalMs, "f");
+        this.clientId = loadClientId(store);
+    }
+    /** Records the MCP client (for example, Claude Code) that connected. */
+    setAgent(info) {
+        if (info?.name) {
+            __classPrivateFieldSet(this, _Telemetry_agent, { name: info.name, version: info.version }, "f");
+        }
+    }
+    /** Queues an event. Synchronous, cheap, and safe to call anywhere. */
+    track(name, properties) {
+        try {
+            // The union is keyed by `name`; TypeScript can't correlate the two
+            // generic parameters, so build the event through the union type.
+            const event = {
+                id: randomUUID(),
+                name,
+                timestamp: new Date().toISOString(),
+                properties,
+            };
+            __classPrivateFieldGet(this, _Telemetry_queue, "f").push(event);
+            if (__classPrivateFieldGet(this, _Telemetry_queue, "f").length > MAX_QUEUE) {
+                __classPrivateFieldGet(this, _Telemetry_queue, "f").splice(0, __classPrivateFieldGet(this, _Telemetry_queue, "f").length - MAX_QUEUE);
+            }
+            __classPrivateFieldGet(this, _Telemetry_instances, "m", _Telemetry_schedule).call(this);
+        }
+        catch (err) {
+            LOGGER.debug({ err }, 'telemetry: track failed');
+        }
+    }
+    /** Sends everything queued. Never rejects. */
+    flush() {
+        clearTimeout(__classPrivateFieldGet(this, _Telemetry_timer, "f"));
+        __classPrivateFieldSet(this, _Telemetry_timer, undefined, "f");
+        const events = __classPrivateFieldGet(this, _Telemetry_queue, "f").splice(0);
+        if (!events.length) {
+            return __classPrivateFieldGet(this, _Telemetry_sending, "f");
+        }
+        __classPrivateFieldSet(this, _Telemetry_sending, __classPrivateFieldGet(this, _Telemetry_sending, "f").then(() => __classPrivateFieldGet(this, _Telemetry_instances, "m", _Telemetry_send).call(this, events)), "f");
+        return __classPrivateFieldGet(this, _Telemetry_sending, "f");
+    }
+    /**
+     * Links this client's earlier anonymous events to the signed-in user.
+     * Needs a bearer token, so call it after sign-in.
+     */
+    async identify() {
+        try {
+            await __classPrivateFieldGet(this, _Telemetry_client, "f").call('IdentifyAnalyticsClient', {
+                body: { clientId: this.clientId },
+            });
+        }
+        catch (err) {
+            LOGGER.debug({ err }, 'telemetry: identify failed');
+        }
+    }
+    /**
+     * Call when sign-in finishes. Sends the `login` event first so that
+     * `identify()` can attribute it to the user.
+     */
+    async signedIn() {
+        this.track('login', { method: 'oauth' });
+        await this.flush();
+        await this.identify();
+    }
+    /** Sends what's left, waiting at most two seconds. */
+    async close() {
+        let timer;
+        const limit = new Promise((resolve) => {
+            timer = setTimeout(resolve, CLOSE_LIMIT_MS);
+            timer.unref();
+        });
+        await Promise.race([this.flush(), limit]);
+        clearTimeout(timer);
+    }
+}
+_Telemetry_client = new WeakMap(), _Telemetry_flushIntervalMs = new WeakMap(), _Telemetry_queue = new WeakMap(), _Telemetry_timer = new WeakMap(), _Telemetry_agent = new WeakMap(), _Telemetry_sending = new WeakMap(), _Telemetry_instances = new WeakSet(), _Telemetry_schedule = function _Telemetry_schedule() {
+    if (__classPrivateFieldGet(this, _Telemetry_timer, "f")) {
+        return;
+    }
+    // Unref'd so a pending flush never keeps the process alive.
+    __classPrivateFieldSet(this, _Telemetry_timer, setTimeout(() => {
+        __classPrivateFieldSet(this, _Telemetry_timer, undefined, "f");
+        void this.flush();
+    }, __classPrivateFieldGet(this, _Telemetry_flushIntervalMs, "f")), "f");
+    __classPrivateFieldGet(this, _Telemetry_timer, "f").unref();
+}, _Telemetry_send = async function _Telemetry_send(events) {
+    for (let i = 0; i < events.length; i += MAX_BATCH) {
+        try {
+            await __classPrivateFieldGet(this, _Telemetry_client, "f").call('TrackAnalyticsEvents', {
+                body: {
+                    clientId: this.clientId,
+                    source: 'mcp',
+                    context: {
+                        sessionId: this.sessionId,
+                        ...(__classPrivateFieldGet(this, _Telemetry_agent, "f") ? { agent: __classPrivateFieldGet(this, _Telemetry_agent, "f") } : {}),
+                        app: { version: VERSION },
+                    },
+                    events: events.slice(i, i + MAX_BATCH),
+                },
+            });
+        }
+        catch (err) {
+            LOGGER.debug({ err }, 'telemetry: send failed; dropping batch');
+        }
+    }
+};
+/**
+ * Reads the anonymous client ID from the config file, or creates it. The ID
+ * is random and carries no information about the developer. The first time
+ * the server creates it, it tells the developer how to opt out.
+ */
+function loadClientId(store) {
+    try {
+        const existing = store.read()?.analytics?.clientId;
+        if (existing) {
+            return existing;
+        }
+        const clientId = randomUUID();
+        store.write({
+            analytics: { clientId, createdAt: new Date().toISOString() },
+        });
+        LOGGER.info('Reclaim records anonymous usage data to improve the product. '
+            + 'To turn it off, set RECLAIM_TELEMETRY=0 or DO_NOT_TRACK=1.');
+        return clientId;
+    }
+    catch (err) {
+        // An unwritable config file shouldn't disable the server. Use an ID
+        // that lasts for this process only.
+        LOGGER.debug({ err }, 'telemetry: could not persist client ID');
+        return randomUUID();
+    }
+}

package/lib/telemetry/tool-call.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare function startToolCall(tool: string, args: unknown): {
+    end(err?: unknown): void;
+};
+/**
+ * A category for the error, such as `http_401`. It's never the message,
+ * because messages can contain URLs, tokens, or file paths.
+ */
+export declare function errorCode(err: unknown): string;
+/**
+ * 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 declare function allowlistedInput(tool: string, args: unknown): {
+    userRequest: string | undefined;
+} | {
+    domain: string | undefined;
+    dataPoints: string[] | undefined;
+} | undefined;

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.41",
 	"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.41",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

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/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/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
+}

package/src/telemetry/telemetry.ts

@@ -0,0 +1,206 @@
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
+import type { IOperationArgs } from '@reclaimprotocol/client/openapi'
+import { randomUUID } from 'node:crypto'
+import { ConfigStore } from '../config/store.ts'
+import { LOGGER } from '../logger.ts'
+import { VERSION } from '../pkg.ts'
+
+type TrackArgs = IOperationArgs<'TrackAnalyticsEvents'>
+type Batch = TrackArgs['body']
+type Event = Batch['events'][number]
+type Agent = NonNullable<NonNullable<Batch['context']>['agent']>
+
+/** Backend mode, as the analytics API names it. */
+export type TelemetryMode = 'builder' | 'devtools'
+
+export interface TelemetryOptions {
+	client: ReclaimClient
+	mode: TelemetryMode
+	store?: ConfigStore
+	/** How long to wait after the first queued event before sending. */
+	flushIntervalMs?: number
+}
+
+/** The API accepts up to 50 events per request. */
+const MAX_BATCH = 50
+/** Bounds memory while the backend is unreachable. Oldest events go first. */
+const MAX_QUEUE = 500
+/** How long `close()` waits, so a slow network can't hold up exit. */
+const CLOSE_LIMIT_MS = 2000
+
+/**
+ * Sends anonymous usage events to Builder. It never throws and never blocks
+ * a tool call: `track()` only queues, and a timer that doesn't keep the
+ * process alive sends the queue in the background. Failed batches are
+ * dropped, because usage data isn't worth retry loops in a tool server.
+ *
+ * Nothing is written to stdout. Stdio is the MCP transport.
+ */
+export class Telemetry {
+	readonly mode: TelemetryMode
+	readonly clientId: string
+	readonly sessionId = String(Math.floor(Date.now() / 1000))
+
+	#client: ReclaimClient
+	#flushIntervalMs: number
+	#queue: Event[] = []
+	#timer: NodeJS.Timeout | undefined
+	#agent: Agent | undefined
+	/** Serializes sends so batches go out in order. */
+	#sending: Promise<void> = Promise.resolve()
+
+	constructor({
+		client,
+		mode,
+		store = new ConfigStore(),
+		flushIntervalMs = 5000,
+	}: TelemetryOptions) {
+		this.#client = client
+		this.mode = mode
+		this.#flushIntervalMs = flushIntervalMs
+		this.clientId = loadClientId(store)
+	}
+
+	/** Records the MCP client (for example, Claude Code) that connected. */
+	setAgent(info: { name: string, version?: string } | undefined) {
+		if(info?.name) {
+			this.#agent = { name: info.name, version: info.version }
+		}
+	}
+
+	/** Queues an event. Synchronous, cheap, and safe to call anywhere. */
+	track<N extends Event['name']>(
+		name: N,
+		properties: Extract<Event, { name: N }>['properties'],
+	) {
+		try {
+			// The union is keyed by `name`; TypeScript can't correlate the two
+			// generic parameters, so build the event through the union type.
+			const event = {
+				id: randomUUID(),
+				name,
+				timestamp: new Date().toISOString(),
+				properties,
+			} as Event
+			this.#queue.push(event)
+			if(this.#queue.length > MAX_QUEUE) {
+				this.#queue.splice(0, this.#queue.length - MAX_QUEUE)
+			}
+
+			this.#schedule()
+		} catch(err) {
+			LOGGER.debug({ err }, 'telemetry: track failed')
+		}
+	}
+
+	/** Sends everything queued. Never rejects. */
+	flush(): Promise<void> {
+		clearTimeout(this.#timer)
+		this.#timer = undefined
+		const events = this.#queue.splice(0)
+		if(!events.length) {
+			return this.#sending
+		}
+
+		this.#sending = this.#sending.then(() => this.#send(events))
+		return this.#sending
+	}
+
+	/**
+	 * Links this client's earlier anonymous events to the signed-in user.
+	 * Needs a bearer token, so call it after sign-in.
+	 */
+	async identify() {
+		try {
+			await this.#client.call('IdentifyAnalyticsClient', {
+				body: { clientId: this.clientId },
+			})
+		} catch(err) {
+			LOGGER.debug({ err }, 'telemetry: identify failed')
+		}
+	}
+
+	/**
+	 * Call when sign-in finishes. Sends the `login` event first so that
+	 * `identify()` can attribute it to the user.
+	 */
+	async signedIn() {
+		this.track('login', { method: 'oauth' })
+		await this.flush()
+		await this.identify()
+	}
+
+	/** Sends what's left, waiting at most two seconds. */
+	async close() {
+		let timer: NodeJS.Timeout | undefined
+		const limit = new Promise<void>((resolve) => {
+			timer = setTimeout(resolve, CLOSE_LIMIT_MS)
+			timer.unref()
+		})
+		await Promise.race([this.flush(), limit])
+		clearTimeout(timer)
+	}
+
+	#schedule() {
+		if(this.#timer) {
+			return
+		}
+
+		// Unref'd so a pending flush never keeps the process alive.
+		this.#timer = setTimeout(() => {
+			this.#timer = undefined
+			void this.flush()
+		}, this.#flushIntervalMs)
+		this.#timer.unref()
+	}
+
+	async #send(events: Event[]) {
+		for(let i = 0; i < events.length; i += MAX_BATCH) {
+			try {
+				await this.#client.call('TrackAnalyticsEvents', {
+					body: {
+						clientId: this.clientId,
+						source: 'mcp',
+						context: {
+							sessionId: this.sessionId,
+							...(this.#agent ? { agent: this.#agent } : {}),
+							app: { version: VERSION },
+						},
+						events: events.slice(i, i + MAX_BATCH),
+					},
+				})
+			} catch(err) {
+				LOGGER.debug({ err }, 'telemetry: send failed; dropping batch')
+			}
+		}
+	}
+}
+
+/**
+ * Reads the anonymous client ID from the config file, or creates it. The ID
+ * is random and carries no information about the developer. The first time
+ * the server creates it, it tells the developer how to opt out.
+ */
+function loadClientId(store: ConfigStore): string {
+	try {
+		const existing = store.read()?.analytics?.clientId
+		if(existing) {
+			return existing
+		}
+
+		const clientId = randomUUID()
+		store.write({
+			analytics: { clientId, createdAt: new Date().toISOString() },
+		})
+		LOGGER.info(
+			'Reclaim records anonymous usage data to improve the product. '
+			+ 'To turn it off, set RECLAIM_TELEMETRY=0 or DO_NOT_TRACK=1.',
+		)
+		return clientId
+	} catch(err) {
+		// An unwritable config file shouldn't disable the server. Use an ID
+		// that lasts for this process only.
+		LOGGER.debug({ err }, 'telemetry: could not persist client ID')
+		return randomUUID()
+	}
+}

package/src/telemetry/tool-call.ts

@@ -0,0 +1,115 @@
+import { isProblemError } from '@reclaimprotocol/client/api'
+import { currentTelemetry } from './index.ts'
+
+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: string, args: unknown) {
+	const startedAt = Date.now()
+	return {
+		end(err?: unknown) {
+			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: unknown): string {
+	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: string, args: unknown) {
+	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: unknown, max: number): string | undefined {
+	return typeof value === 'string' && value ? value.slice(0, max) : undefined
+}
+
+/** Returns the object, or undefined when every field is undefined. */
+function compact<T extends object>(obj: T): T | undefined {
+	return Object.values(obj).some((v) => v !== undefined) ? obj : undefined
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}