@reclaimprotocol/agent 0.1.39 → 0.1.41

package/lib/mcp/tools/authenticate/eth-key.js

@@ -15,10 +15,11 @@
  * signing key only — unrelated to org auth (the org secret) or encryption
  * (the eth decrypt key).
  */
+import { badRequest } from '@hapi/boom';
 import { deriveFromPrivateKey, generateKeypair } from '@reclaimprotocol/client';
 import assert from 'node:assert';
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { closeSync, constants, existsSync, fchmodSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { privateKey, privateKeyFile } from "../../../consts.js";
 import { findProjectRoot } from "../../../paths.js";
 const ENV_VAR = 'RECLAIM_PRIVATE_KEY';
@@ -111,7 +112,7 @@ export function ensureGitignored(projectDir, entry) {
         return;
     }
     const prefix = current && !current.endsWith('\n') ? '\n' : '';
-    writeFileSync(path, current + prefix + entry + '\n');
+    writeInside(projectDir, path, current + prefix + entry + '\n');
 }
 /**
  * Set `name=value` in a dotenv file, replacing an existing line or appending
@@ -132,12 +133,41 @@ export function upsertEnvVar(projectDir, envFile, name, value) {
         const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
         next = existing + prefix + line + '\n';
     }
-    mkdirSync(dirname(envPath), { recursive: true });
-    writeFileSync(envPath, next, { mode: 0o600 });
-    chmodSync(envPath, 0o600);
+    writeInside(projectDir, envPath, next, { secret: true });
     ensureGitignored(projectDir, relative(projectDir, envPath));
     return envPath;
 }
+/** Remove the `name=` line from a dotenv file, if there is one. */
+export function removeEnvVar(projectDir, envFile, name) {
+    const envPath = resolve(projectDir, envFile);
+    if (!existsSync(envPath)) {
+        return;
+    }
+    const existing = readFileSync(envPath, 'utf8');
+    const re = new RegExp(`^\\s*${name}\\s*=.*(\\n|$)`, 'm');
+    writeInside(projectDir, envPath, existing.replace(re, ''), { secret: true });
+}
+/**
+ * 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 function backupEnvVar(projectDir, envFile, name, reason) {
+    const envPath = resolve(projectDir, envFile);
+    assertNoSymlinks(projectDir, relative(projectDir, envPath));
+    const value = readDotenvKey(envPath, name);
+    if (!value) {
+        return undefined;
+    }
+    const backupPath = `${envPath}.backup`;
+    const stamp = new Date().toISOString();
+    writeInside(projectDir, backupPath, `# ${stamp} ${reason}\n${name}=${value}\n`, { secret: true, append: true });
+    ensureGitignored(projectDir, relative(projectDir, backupPath));
+    return backupPath;
+}
 /**
  * Persist a raw eth private key to the project `.env` as
  * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
@@ -149,3 +179,39 @@ export function writeEthKey(privateKeyHex, projectDir = findProjectRoot(process.
     const path = upsertEnvVar(projectDir, ENV_FILE, ENV_VAR, hex);
     return { path, address: deriveFromPrivateKey(hex).address };
 }
+/** 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 function assertNoSymlinks(root, path) {
+    assert(path && !path.startsWith('..') && !isAbsolute(path), badRequest(`${path} is not inside ${root}`));
+    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; Reclaim tools only write to real files `
+            + 'and directories inside the project'));
+    }
+}
+/**
+ * Write `data` to `path` inside `projectDir` without following a symlink: the
+ * file and its parents must be real, and the open uses `O_NOFOLLOW`, so a
+ * symlink that appears after the check still fails. `secret` writes with
+ * mode 0600; `append` adds to the file instead of replacing it.
+ */
+function writeInside(projectDir, path, data, { secret = false, append = false } = {}) {
+    const rel = relative(projectDir, path);
+    assertNoSymlinks(projectDir, rel);
+    mkdirSync(dirname(path), { recursive: true });
+    assertNoSymlinks(projectDir, rel);
+    const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW
+        | (append ? constants.O_APPEND : constants.O_TRUNC), secret ? 0o600 : 0o666);
+    try {
+        if (secret) {
+            fchmodSync(fd, 0o600);
+        }
+        writeFileSync(fd, data);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/lib/mcp/tools/authenticate/issue-org-keypair.d.ts

@@ -1,10 +1,11 @@
-import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import { type ReclaimClient } from '@reclaimprotocol/client/api';
 import { type RegisteredTool } from '../../server.ts';
 /**
  * Creates the organization's eth key pair for session binding and encrypted
  * results: writes the private key to the app's server env file and registers
  * only the public key with Builder, so the private key never passes through
  * the agent's transcript. Reuses a key the env file already holds, so a
- * repeat call (for example, to turn on encryption) keeps the same key.
+ * repeat call (for example, to turn on encryption) keeps the same key. With
+ * `replace`, always generates a fresh key and rotates the org's key to it.
  */
 export declare function issueOrgKeypairTool(client: ReclaimClient): RegisteredTool;

package/lib/mcp/tools/authenticate/issue-org-keypair.js

@@ -1,14 +1,17 @@
+import { conflict } from '@hapi/boom';
 import { deriveFromPrivateKey, generateKeypair } from '@reclaimprotocol/client';
+import { isProblemError } from '@reclaimprotocol/client/api';
 import assert from 'node:assert';
 import { isAbsolute, relative, resolve } from 'node:path';
 import { defineTool } from "../../server.js";
-import { normalizeEthHex, readDotenvKey, upsertEnvVar } from "./eth-key.js";
+import { backupEnvVar, normalizeEthHex, readDotenvKey, removeEnvVar, upsertEnvVar, } from "./eth-key.js";
 /**
  * Creates the organization's eth key pair for session binding and encrypted
  * results: writes the private key to the app's server env file and registers
  * only the public key with Builder, so the private key never passes through
  * the agent's transcript. Reuses a key the env file already holds, so a
- * repeat call (for example, to turn on encryption) keeps the same key.
+ * repeat call (for example, to turn on encryption) keeps the same key. With
+ * `replace`, always generates a fresh key and rotates the org's key to it.
  */
 export function issueOrgKeypairTool(client) {
     return defineTool({
@@ -20,8 +23,12 @@ export function issueOrgKeypairTool(client) {
             + 'private key to a server env file in the project (reusing a key '
             + 'already there) and registers only the public key. Returns the '
             + 'address, file, and variable; never the key. Returns 409 when the '
-            + 'org already has a different key: ask the developer for that key '
-            + 'rather than replacing it.',
+            + 'org already has a different key. Set `replace: true` only when '
+            + 'the developer asked to rotate or replace the key: it generates '
+            + 'a new key and swaps it in one step, and apps holding the old '
+            + 'key can no longer decrypt new results. The old key is first '
+            + 'appended to `<envFile>.backup` (gitignored); tell the developer '
+            + 'its path.',
         inputSchema: {
             type: 'object',
             required: ['orgId', 'projectDir'],
@@ -42,11 +49,17 @@ export function issueOrgKeypairTool(client) {
                 },
                 encryptResults: {
                     type: 'boolean',
-                    description: 'Encrypt delivered results to this key. Default false.',
+                    description: 'Encrypt delivered results to this key. Default false, or the '
+                        + 'org\'s current setting with `replace`.',
+                },
+                replace: {
+                    type: 'boolean',
+                    description: 'Rotate: generate a new key and replace the org\'s current '
+                        + 'one. Default false.',
                 },
             },
         },
-        annotations: { openWorldHint: true, destructiveHint: false },
+        annotations: { openWorldHint: true, destructiveHint: true },
     }, async (args) => {
         assert(isAbsolute(args.projectDir), new Error('`projectDir` must be an absolute path.'));
         const envFile = args.envFile || '.env';
@@ -54,22 +67,53 @@ export function issueOrgKeypairTool(client) {
         const envPath = resolve(args.projectDir, envFile);
         const inside = relative(args.projectDir, envPath);
         assert(inside && !inside.startsWith('..') && !isAbsolute(inside), new Error('`envFile` must be inside `projectDir`.'));
-        const existing = readDotenvKey(envPath, envVar);
+        const replace = args.replace ?? false;
+        // Rotation always generates a fresh key: the env file's key may or
+        // may not be the one the org holds, and reuse would be a no-op.
+        const existing = replace ? undefined : readDotenvKey(envPath, envVar);
         const keypair = existing
             ? deriveFromPrivateKey(normalizeEthHex(existing))
             : generateKeypair();
-        // Register first: a 409 (the org has another key) must not leave a
-        // key Builder doesn't know in the env file.
-        const canEncryptResult = args.encryptResults ?? false;
-        await client.call('SetOrgKeypair', {
-            params: { orgId: args.orgId },
-            body: {
-                publicKey: keypair.publicKey,
-                canEncryptResult,
-                replace: false,
-            },
-        });
+        // A rotation keeps the org's current setting unless the caller sets it.
+        const canEncryptResult = args.encryptResults
+            ?? (replace && await currentCanEncryptResult());
+        // Back up and save the key before the org switches to it, so a
+        // failed write can't leave the org on a key no app holds. A failed
+        // registration (for example, a 409) puts the env file back.
+        const old = readDotenvKey(envPath, envVar);
+        const backupFile = old && !existing
+            ? backupEnvVar(args.projectDir, envFile, envVar, 'replaced by issue_org_keypair')
+            : undefined;
         const path = upsertEnvVar(args.projectDir, envFile, envVar, keypair.privateKey);
+        try {
+            await client.call('SetOrgKeypair', {
+                params: { orgId: args.orgId },
+                body: {
+                    publicKey: keypair.publicKey,
+                    canEncryptResult,
+                    replace,
+                },
+            });
+        }
+        catch (err) {
+            if (old) {
+                upsertEnvVar(args.projectDir, envFile, envVar, old);
+            }
+            else {
+                removeEnvVar(args.projectDir, envFile, envVar);
+            }
+            if (!replace && isProblemError(err) && err.output.statusCode === 409) {
+                throw conflict('The org already has a different key. Ask the developer to '
+                    + 'choose: (a) reuse it: they paste its private key into '
+                    + `\`${envFile}\` as \`${envVar}\` themselves, never into the `
+                    + 'chat; (b) rotate it: call `issue_org_keypair` again with '
+                    + '`replace: true`, after which apps holding the old key can no '
+                    + 'longer decrypt new results; (c) turn off result encryption: '
+                    + 'call `update_org_keypair` with `canEncryptResult: false`, '
+                    + 'which keeps the key.');
+            }
+            throw err;
+        }
         return {
             orgId: args.orgId,
             address: keypair.address,
@@ -77,6 +121,27 @@ export function issueOrgKeypairTool(client) {
             envFile: path,
             envVar,
             reused: Boolean(existing),
+            backupFile: backupFile ?? null,
+            ...(replace && !backupFile && !old
+                ? {
+                    note: 'Nothing was backed up: the old private key is not in '
+                        + 'this file. Another app may hold it.',
+                }
+                : {}),
         };
+        async function currentCanEncryptResult() {
+            try {
+                const { data } = await client.call('GetOrgKeypair', {
+                    params: { orgId: args.orgId },
+                });
+                return data.canEncryptResult;
+            }
+            catch (err) {
+                if (isProblemError(err) && err.output.statusCode === 404) {
+                    return false;
+                }
+                throw err;
+            }
+        }
     });
 }

package/lib/mcp/tools/authenticate/issue-org-token.js

@@ -1,7 +1,7 @@
 import assert from 'node:assert';
 import { isAbsolute, relative, resolve } from 'node:path';
 import { defineTool } from "../../server.js";
-import { upsertEnvVar } from "./eth-key.js";
+import { backupEnvVar, readDotenvKey, upsertEnvVar } from "./eth-key.js";
 import { saveOrgKey } from "./org-key-store.js";
 /**
  * Issues an organization API key and stores it on disk, so the key never
@@ -15,7 +15,9 @@ export function issueOrgTokenTool(client) {
             + 'server env file in the project, so the app can read it at runtime. '
             + 'Also saves it on this machine for the org-key tools. Returns the '
             + 'org, file, variable, and last four characters; never the key. '
-            + 'Replaces an existing variable of the same name in the file. '
+            + 'Replaces an existing variable of the same name in the file, first '
+            + 'appending the old value to `<envFile>.backup` (gitignored); tell '
+            + 'the developer its path. '
             + 'Adds the file to .gitignore. Use when the app needs a key, or '
             + 'before `create_verification_session`.',
         inputSchema: {
@@ -48,6 +50,10 @@ export function issueOrgTokenTool(client) {
         const { data } = await client.call('IssueOrgToken', {
             params: { orgId: args.orgId },
         });
+        const old = readDotenvKey(resolve(args.projectDir, envFile), envVar);
+        const backupFile = old && old !== data.orgSecret
+            ? backupEnvVar(args.projectDir, envFile, envVar, 'replaced by issue_org_token')
+            : undefined;
         const path = upsertEnvVar(args.projectDir, envFile, envVar, data.orgSecret);
         saveOrgKey(args.orgId, data.orgSecret);
         return {
@@ -55,6 +61,7 @@ export function issueOrgTokenTool(client) {
             envFile: path,
             envVar,
             last4: data.last4,
+            backupFile: backupFile ?? null,
         };
     });
 }

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;