Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

add privacy-safe agent analytics (#521)

kta18809e00ea3
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 491582a358..f7100b579a 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,7 @@
## [Unreleased]
+- Added privacy-safe pseudonymous product analytics for onboarding, command use, execution modes, run outcomes, TTFT, latency, usage, tools, retries, and compactions, with disclosure and opt-out controls ([ENG-4682](https://linear.app/primeintellect/issue/ENG-4682/add-privacy-safe-posthog-analytics-to-prime-agent)).
- Changed sent agent messages in the IPython cell UI to show only the message text with a `╰─` gutter when expanded, matching received messages, and hid the raw `agent_message.send` receipt dictionary.
- Fixed Homebrew installs attempting to self-update their versioned Cellar keg instead of directing users to `brew upgrade prime-agent` ([#844](https://github.com/PrimeIntellect-ai/prime-agent/issues/844))
diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index a6d811b534..565e7f742e 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -674,6 +674,9 @@ prime-agent --thinking high "Solve this complex problem"
| `PI_PACKAGE_DIR` | Override package directory (useful for Nix/Guix where store paths tokenize poorly) |
| `PI_OFFLINE` | Disable startup network operations, including update checks and package update checks |
| `PI_SKIP_VERSION_CHECK` | Skip the Prime Agent version update check at startup. This prevents the release manifest request |
+| `PRIME_AGENT_TELEMETRY` | Override pseudonymous aggregate usage analytics with `1`/`true`/`yes` or `0`/`false`/`no` |
+| `PRIME_AGENT_TELEMETRY_ENDPOINT` | Override the aggregate analytics ingestion endpoint |
+| `DO_NOT_TRACK` | Disable aggregate usage analytics when set to `1`/`true`/`yes` |
| `PRIME_AGENT_DOWNLOAD_BASE_URL` | Override the Prime Agent release manifest and tarball base URL |
| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h) |
| `PRIME_API_KEY` | Prime Inference API key; also used for trace sharing if it has `agent_traces` scope |
diff --git a/packages/coding-agent/docs/settings.md b/packages/coding-agent/docs/settings.md
index c1308b6a1e..fcfcef9aeb 100644
--- a/packages/coding-agent/docs/settings.md
+++ b/packages/coding-agent/docs/settings.md
@@ -64,6 +64,36 @@ The stable `latest.json` and beta `beta.json` manifests use the same JSON shape:
`version` is required. `package` is optional and may also be named `packageName`; it defaults to the current package name. `tarball` is optional; when present, Prime Agent installs that tarball instead of the package name. Relative tarball paths resolve against `PRIME_AGENT_DOWNLOAD_BASE_URL`.
+### Pseudonymous usage analytics
+
+Prime Agent sends pseudonymous, aggregate usage and performance events to Prime Intellect. These events include version and operating-system category, onboarding outcome and duration, execution mode (`interactive`, `print`, `json`, `rpc`, or `acp`), run outcomes, TTFT and latency, prompt and turn counts, token usage, tool success counts, retries, and compactions.
+
+Prime Agent does not send prompts, responses, thinking, tool arguments or results, command text, filenames, paths, repository information, environment variables, credentials, raw error messages, hostnames, usernames, emails, or hardware identifiers. A random installation ID is stored as `telemetry.json` in the configured agent directory (normally `~/.prime/agent/`).
+
+Telemetry can be disabled globally or for an individual project. Project settings can only further restrict telemetry: they cannot re-enable a global opt-out or suppress the global one-time disclosure.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `telemetry.enabled` | boolean | `true` | Send pseudonymous aggregate usage and performance events |
+
+Disable analytics with any of:
+
+```json
+{
+ "telemetry": {
+ "enabled": false
+ }
+}
+```
+
+```bash
+PRIME_AGENT_TELEMETRY=0 prime-agent
+DO_NOT_TRACK=1 prime-agent
+prime-agent --offline
+```
+
+`PRIME_AGENT_TELEMETRY_ENDPOINT` overrides the ingestion endpoint for development and self-hosted deployments.
+
### Warnings
| Setting | Type | Default | Description |
diff --git a/packages/coding-agent/src/core/agent-session-config.ts b/packages/coding-agent/src/core/agent-session-config.ts
index 8cf90917b1..79d8370149 100644
--- a/packages/coding-agent/src/core/agent-session-config.ts
+++ b/packages/coding-agent/src/core/agent-session-config.ts
@@ -1,6 +1,8 @@
import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
import type { AgentAutonomousConfig } from "./autonomous.js";
+export type AgentExecutionMode = "interactive" | "print" | "json" | "rpc" | "acp";
+
export interface AgentSessionRuntimeConfig {
cwd?: string;
agentDir?: string;
@@ -33,6 +35,10 @@ export interface AgentSessionRuntimeConfig {
* so it survives the appMode="daemon" context switch.
*/
serializedRefine?: boolean;
+ /** User-facing client mode that created this session. The daemon is transport, not an execution mode. */
+ executionMode?: AgentExecutionMode;
+ /** Opt-out-only policy carried across daemon process boundaries. */
+ telemetryDisabled?: true;
/**
* Initial goal to seed when creating a new top-level session (rlmDepth 0).
* Ignored for subagent sessions and when the branch already has a persisted
@@ -77,6 +83,8 @@ export function mergeAgentSessionRuntimeConfig(
? { ...(base.extensionFlagValues ?? {}), ...(override.extensionFlagValues ?? {}) }
: undefined,
serializedRefine: override.serializedRefine ?? base.serializedRefine,
+ executionMode: override.executionMode ?? base.executionMode,
+ telemetryDisabled: base.telemetryDisabled || override.telemetryDisabled ? true : undefined,
initialGoal: override.initialGoal ?? base.initialGoal,
};
}
@@ -94,6 +102,8 @@ function cloneAgentSessionRuntimeConfig(config: AgentSessionRuntimeConfig): Agen
autonomous: mergeAutonomousConfig(undefined, config.autonomous),
extensionFlagValues: config.extensionFlagValues ? { ...config.extensionFlagValues } : undefined,
serializedRefine: config.serializedRefine,
+ executionMode: config.executionMode,
+ telemetryDisabled: config.telemetryDisabled,
initialGoal: config.initialGoal ? { ...config.initialGoal } : undefined,
};
}
diff --git a/packages/coding-agent/src/core/agent-session-services.ts b/packages/coding-agent/src/core/agent-session-services.ts
index 346bc9fbb2..1e9df16b20 100644
--- a/packages/coding-agent/src/core/agent-session-services.ts
+++ b/packages/coding-agent/src/core/agent-session-services.ts
@@ -4,6 +4,7 @@ import type { Model, ServiceTier } from "@earendil-works/pi-ai";
import { getAgentDir } from "../config.js";
import type { AgentSessionMessageController } from "./agent-messages.js";
import type { AgentObserveController } from "./agent-observe.js";
+import type { AgentExecutionMode } from "./agent-session-config.js";
import { installAgentTraceUpload } from "./agent-traces.js";
import { AuthStorage } from "./auth-storage.js";
import type { AgentAutonomousConfig } from "./autonomous.js";
@@ -17,6 +18,7 @@ import type { SubagentRuntimeHost } from "./rlm-runtime.js";
import { type CreateAgentSessionResult, createAgentSession } from "./sdk.js";
import type { SessionManager } from "./session-manager.js";
import { SettingsManager } from "./settings-manager.js";
+import { installAgentTelemetry, isTelemetryEnabled } from "./telemetry.js";
/**
* Non-fatal issues collected while creating services or sessions.
@@ -52,6 +54,8 @@ export interface CreateAgentSessionServicesOptions {
* would release the pane while the parent is still running.
*/
noBuiltinHerdrReporter?: boolean;
+ /** Explicit daemon-carried opt-out; cannot enable telemetry. */
+ telemetryDisabled?: true;
}
export interface AgentSessionCreationOptions {
@@ -80,6 +84,10 @@ export interface AgentSessionCreationOptions {
autonomous?: AgentAutonomousConfig;
/** Serialized refine mode for print/headless autonomous runs. */
serializedRefine?: boolean;
+ /** User-facing client mode that created the top-level session. */
+ executionMode?: AgentExecutionMode;
+ /** Explicit daemon-carried opt-out; cannot enable telemetry. */
+ telemetryDisabled?: true;
/** Initial goal to seed at session creation (rlmDepth 0 only, idempotent). */
initialGoal?: { objective: string; tokenBudget?: number };
}
@@ -207,6 +215,18 @@ export async function createAgentSessionServices(
await resourceLoader.reload();
const diagnostics: AgentSessionRuntimeDiagnostic[] = [];
+ if (
+ !options.telemetryDisabled &&
+ isTelemetryEnabled(settingsManager) &&
+ !settingsManager.getTelemetryNoticeShown()
+ ) {
+ diagnostics.push({
+ type: "info",
+ message:
+ "Prime Agent sends pseudonymous usage and performance metrics without prompts, responses, tool content, file paths, or repository data. Disable this with telemetry.enabled=false, PRIME_AGENT_TELEMETRY=0, DO_NOT_TRACK=1, or offline mode.",
+ });
+ settingsManager.setTelemetryNoticeShown(true);
+ }
const extensionsResult = resourceLoader.getExtensions();
for (const { name, config, extensionPath } of extensionsResult.runtime.pendingProviderRegistrations) {
try {
@@ -248,7 +268,7 @@ export async function createAgentSessionFromServices(
authStorage: options.services.authStorage,
settingsManager: options.services.settingsManager,
});
- return createAgentSession({
+ const result = await createAgentSession({
cwd: options.services.cwd,
agentDir: options.services.agentDir,
authStorage: options.services.authStorage,
@@ -283,4 +303,12 @@ export async function createAgentSessionFromServices(
serializedRefine: options.serializedRefine,
initialGoal: options.initialGoal,
});
+ if (result.session.rlmDepth === 0 && !options.telemetryDisabled) {
+ installAgentTelemetry(result.session, {
+ agentDir: options.services.agentDir,
+ settingsManager: options.services.settingsManager,
+ executionMode: options.executionMode,
+ });
+ }
+ return result;
}
diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts
index 1699088f9a..e99462eabb 100644
--- a/packages/coding-agent/src/core/agent-session.ts
+++ b/packages/coding-agent/src/core/agent-session.ts
@@ -1189,7 +1189,8 @@ export class AgentSession {
private _extensionErrorListener?: ExtensionErrorListener;
private _extensionErrorUnsubscriber?: () => void;
private _disposed = false;
- private readonly _disposeCallbacks = new Set<() => void>();
+ private readonly _disposeCallbacks = new Set<() => void | Promise<void>>();
+ private _disposeCallbacksPromise?: Promise<void>;
// Set at the start of async teardown so a child finishing mid-disposeAsync doesn't
// re-populate the retained map after it's been cleared.
private _disposing = false;
@@ -3769,7 +3770,7 @@ export class AgentSession {
*/
async disposeAsync(): Promise<void> {
if (this._disposed) {
- return;
+ return this._disposeCallbacksPromise;
}
// Concurrent callers await the same in-flight teardown so none resolves before
// the kernel snapshot flush finishes.
@@ -3781,7 +3782,7 @@ export class AgentSession {
// agent_end completes instead of being aborted by dispose().
await this._drainPendingRefinementForDisposal();
if (this._disposed) {
- return;
+ return this._disposeCallbacksPromise;
}
this._disposing = true;
this._sessionActionCommitDisposeAbortController.abort();
@@ -3945,6 +3946,27 @@ export class AgentSession {
// a failed kernel startup already cleaned up after itself
}
this.dispose();
+ await this._disposeCallbacksPromise;
+ }
+
+ private _startDisposeCallbacks(): Promise<void> {
+ if (this._disposeCallbacksPromise) {
+ return this._disposeCallbacksPromise;
+ }
+ const pending: Promise<void>[] = [];
+ for (const callback of this._disposeCallbacks) {
+ try {
+ const result = callback();
+ if (result) {
+ pending.push(result.catch(() => undefined));
+ }
+ } catch {
+ // Disposal remains best-effort; one owner must not block the rest.
+ }
+ }
+ this._disposeCallbacks.clear();
+ this._disposeCallbacksPromise = Promise.all(pending).then(() => undefined);
+ return this._disposeCallbacksPromise;
}
dispose(): void {
@@ -3995,20 +4017,18 @@ export class AgentSession {
this._eventListeners = [];
cleanupSessionResources(this.sessionId);
} finally {
- for (const callback of this._disposeCallbacks) {
- try {
- callback();
- } catch {
- // Disposal remains best-effort; one owner must not block the rest.
- }
- }
- this._disposeCallbacks.clear();
+ void this._startDisposeCallbacks();
}
}
- registerDisposeCallback(callback: () => void): void {
+ registerDisposeCallback(callback: () => void | Promise<void>): void {
if (this._disposed) {
- callback();
+ try {
+ const result = callback();
+ if (result) void result.catch(() => undefined);
+ } catch {
+ // Late registration follows the same best-effort disposal contract.
+ }
return;
}
this._disposeCallbacks.add(callback);
diff --git a/packages/coding-agent/src/core/settings-manager.ts b/packages/coding-agent/src/core/settings-manager.ts
index 0647fc3b63..ab42f5e93f 100644
--- a/packages/coding-agent/src/core/settings-manager.ts
+++ b/packages/coding-agent/src/core/settings-manager.ts
@@ -136,6 +136,7 @@ export interface Settings {
compaction?: CompactionSettings;
autoRefine?: AutoRefineSettings;
agentTraces?: AgentTracesSettings;
+ telemetry?: TelemetrySettings;
branchSummary?: BranchSummarySettings;
retry?: RetrySettings;
hideThinkingBlock?: boolean;
@@ -169,6 +170,11 @@ export interface AgentTracesSettings {
enabled?: boolean;
}
+export interface TelemetrySettings {
+ enabled?: boolean;
+ noticeShown?: boolean;
+}
+
/** Deep merge settings: project/overrides take precedence, nested objects merge recursively */
function deepMergeSettings(base: Settings, overrides: Settings): Settings {
const result: Settings = { ...base };
@@ -300,6 +306,7 @@ export class SettingsManager {
private globalSettings: Settings;
private projectSettings: Settings;
private settings: Settings;
+ private runtimeOverrides: Settings = {};
private modifiedFields = new Set<keyof Settings>(); // Track global fields modified during session
private modifiedNestedFields = new Map<keyof Settings, Set<string>>(); // Track global nested field modifications
private modifiedProjectFields = new Set<keyof Settings>(); // Track project fields modified during session
@@ -446,6 +453,15 @@ export class SettingsManager {
delete retrySettings.maxDelayMs;
}
+ if (typeof settings.telemetry === "boolean") {
+ settings.telemetry = { enabled: settings.telemetry };
+ } else if (
+ settings.telemetry !== undefined &&
+ (typeof settings.telemetry !== "object" || settings.telemetry === null || Array.isArray(settings.telemetry))
+ ) {
+ delete settings.telemetry;
+ }
+
return settings as Settings;
}
@@ -487,6 +503,7 @@ export class SettingsManager {
/** Apply additional overrides on top of current settings */
applyOverrides(overrides: Partial<Settings>): void {
+ this.runtimeOverrides = deepMergeSettings(this.runtimeOverrides, overrides);
this.settings = deepMergeSettings(this.settings, overrides);
}
@@ -812,6 +829,37 @@ export class SettingsManager {
this.save();
}
+ getTelemetryEnabled(): boolean {
+ const globalEnabled = this.globalSettings.telemetry?.enabled ?? true;
+ const projectEnabled = this.projectSettings.telemetry?.enabled ?? true;
+ const runtimeEnabled = this.runtimeOverrides.telemetry?.enabled ?? true;
+ return globalEnabled && projectEnabled && runtimeEnabled;
+ }
+
+ private getOrCreateGlobalTelemetrySettings(): TelemetrySettings {
+ const telemetry = this.globalSettings.telemetry;
+ if (typeof telemetry !== "object" || telemetry === null || Array.isArray(telemetry)) {
+ this.globalSettings.telemetry = {};
+ }
+ return this.globalSettings.telemetry!;
+ }
+
+ setTelemetryEnabled(enabled: boolean): void {
+ this.getOrCreateGlobalTelemetrySettings().enabled = enabled;
+ this.markModified("telemetry", "enabled");
+ this.save();
+ }
+
+ getTelemetryNoticeShown(): boolean {
+ return this.runtimeOverrides.telemetry?.noticeShown ?? this.globalSettings.telemetry?.noticeShown ?? false;
+ }
+
+ setTelemetryNoticeShown(shown: boolean): void {
+ this.getOrCreateGlobalTelemetrySettings().noticeShown = shown;
+ this.markModified("telemetry", "noticeShown");
+ this.save();
+ }
+
getCompactionReserveTokens(): number {
return this.settings.compaction?.reserveTokens ?? 16384;
}
diff --git a/packages/coding-agent/src/core/telemetry.ts b/packages/coding-agent/src/core/telemetry.ts
new file mode 100644
index 0000000000..de8eb860fe
--- /dev/null
+++ b/packages/coding-agent/src/core/telemetry.ts
@@ -0,0 +1,797 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { arch, platform } from "node:os";
+import { join } from "node:path";
+import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
+import { detectInstallMethod, VERSION } from "../config.js";
+import type { AgentSession, AgentSessionEvent } from "./agent-session.js";
+import type { AgentExecutionMode } from "./agent-session-config.js";
+import type { AuthCredential, AuthStatus } from "./auth-storage.js";
+import type { SettingsManager } from "./settings-manager.js";
+import { isBuiltinSlashCommandName, resolveBuiltinSlashCommandName } from "./slash-commands.js";
+
+const DEFAULT_TELEMETRY_ENDPOINT = "https://api.primeintellect.ai/api/v1/agent-analytics/events";
+const TELEMETRY_STATE_FILE = "telemetry.json";
+const TELEMETRY_STATE_VERSION = 1;
+const DEFAULT_BATCH_SIZE = 10;
+const DEFAULT_FLUSH_INTERVAL_MS = 10_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 1_500;
+
+type TelemetryPrimitive = string | number | boolean | null;
+type TelemetryProperties = Record<string, TelemetryPrimitive>;
+
+export type TelemetryEventName =
+ | "agent started"
+ | "onboarding completed"
+ | "agent command used"
+ | "agent run completed"
+ | "agent session ended";
+
+export type TelemetryExecutionMode = AgentExecutionMode | "unknown";
+export type TelemetryOnboardingOutcome = "success" | "error" | "aborted";
+export type TelemetryAuthCategory =
+ | "oauth"
+ | "api_key"
+ | "runtime_api_key"
+ | "environment"
+ | "prime_cli"
+ | "models_json"
+ | "fallback"
+ | "stale"
+ | "stored"
+ | "none";
+
+export interface TelemetryEvent {
+ id: string;
+ name: TelemetryEventName;
+ timestamp: string;
+ properties: TelemetryProperties;
+}
+
+export interface TelemetryBatch {
+ installation_id: string;
+ events: TelemetryEvent[];
+}
+
+export interface TelemetrySink {
+ capture(name: TelemetryEventName, properties: TelemetryProperties): void;
+ flush(): Promise<void>;
+}
+
+interface TelemetryState {
+ version: number;
+ installationId: string;
+}
+
+interface TelemetryClientOptions {
+ agentDir: string;
+ endpoint?: string;
+ fetch?: typeof fetch;
+ now?: () => number;
+ randomId?: () => string;
+ batchSize?: number;
+ flushIntervalMs?: number;
+ requestTimeoutMs?: number;
+}
+
+interface InstallAgentTelemetryOptions {
+ agentDir: string;
+ settingsManager: SettingsManager;
+ executionMode?: AgentExecutionMode;
+ sink?: TelemetrySink;
+ now?: () => number;
+ randomId?: () => string;
+}
+
+export interface CaptureOnboardingCompletedOptions {
+ agentDir: string;
+ settingsManager: SettingsManager;
+ durationMs: number;
+ outcome: TelemetryOnboardingOutcome;
+ provider?: string;
+ authSource?: AuthStatus["source"];
+ storedCredentialType?: AuthCredential["type"];
+ sink?: TelemetrySink;
+ now?: () => number;
+ randomId?: () => string;
+}
+
+export interface CaptureAgentCommandUsedOptions {
+ agentDir: string;
+ settingsManager: SettingsManager;
+ commandName: string;
+ sink?: TelemetrySink;
+ now?: () => number;
+ randomId?: () => string;
+}
+
+interface UsageTotals extends Usage {
+ modelCallCount: number;
+}
+
+interface ActiveRun {
+ startedAt: number;
+ agentEnded: boolean;
+ firstTurnStartedAt?: number;
+ firstModelEventMs?: number;
+ visibleTtftMs?: number;
+ currentTurnStartedAt?: number;
+ modelLatencyMs: number;
+ maxModelLatencyMs: number;
+ turnCount: number;
+ toolCallCount: number;
+ toolErrorCount: number;
+ compactionCount: number;
+ retryCount: number;
+ usage: UsageTotals;
+ lastAssistant?: AssistantMessage;
+}
+
+interface SessionTotals {
+ startedAt: number;
+ runCount: number;
+ successfulRunCount: number;
+ failedRunCount: number;
+ abortedRunCount: number;
+ promptCount: number;
+ toolCallCount: number;
+ compactionCount: number;
+ usage: UsageTotals;
+}
+
+const EMPTY_USAGE_TOTALS: UsageTotals = {
+ input: 0,
+ output: 0,
+ cacheRead: 0,
+ cacheWrite: 0,
+ totalTokens: 0,
+ cost: {
+ input: 0,
+ output: 0,
+ cacheRead: 0,
+ cacheWrite: 0,
+ total: 0,
+ },
+ modelCallCount: 0,
+};
+
+function newUsageTotals(): UsageTotals {
+ return structuredClone(EMPTY_USAGE_TOTALS);
+}
+
+function addUsage(target: UsageTotals, usage: Usage): void {
+ target.input += usage.input;
+ target.output += usage.output;
+ target.cacheRead += usage.cacheRead;
+ target.cacheWrite += usage.cacheWrite;
+ target.totalTokens += usage.totalTokens;
+ target.cost.input += usage.cost.input;
+ target.cost.output += usage.cost.output;
+ target.cost.cacheRead += usage.cost.cacheRead;
+ target.cost.cacheWrite += usage.cost.cacheWrite;
+ target.cost.total += usage.cost.total;
+ target.modelCallCount++;
+}
+
+function mergeUsage(target: UsageTotals, usage: UsageTotals): void {
+ target.input += usage.input;
+ target.output += usage.output;
+ target.cacheRead += usage.cacheRead;
+ target.cacheWrite += usage.cacheWrite;
+ target.totalTokens += usage.totalTokens;
+ target.cost.input += usage.cost.input;
+ target.cost.output += usage.cost.output;
+ target.cost.cacheRead += usage.cost.cacheRead;
+ target.cost.cacheWrite += usage.cost.cacheWrite;
+ target.cost.total += usage.cost.total;
+ target.modelCallCount += usage.modelCallCount;
+}
+
+function parseBooleanOverride(value: string | undefined): boolean | undefined {
+ if (value === undefined) {
+ return undefined;
+ }
+ const normalized = value.trim().toLowerCase();
+ if (["1", "true", "yes", "on"].includes(normalized)) {
+ return true;
+ }
+ if (["0", "false", "no", "off"].includes(normalized)) {
+ return false;
+ }
+ return undefined;
+}
+
+export function isTelemetryEnabled(settingsManager: SettingsManager): boolean {
+ if (parseBooleanOverride(process.env.PI_OFFLINE) === true) {
+ return false;
+ }
+ if (parseBooleanOverride(process.env.DO_NOT_TRACK) === true) {
+ return false;
+ }
+ const override = parseBooleanOverride(process.env.PRIME_AGENT_TELEMETRY);
+ if (override !== undefined) {
+ return override;
+ }
+ if (process.env.NODE_ENV === "test") {
+ return false;
+ }
+ return settingsManager.getTelemetryEnabled();
+}
+
+function isInstallationId(value: unknown): value is string {
+ return (
+ typeof value === "string" &&
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+ );
+}
+
+function readInstallationId(path: string): string | undefined {
+ try {
+ const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<TelemetryState>;
+ return parsed.version === TELEMETRY_STATE_VERSION && isInstallationId(parsed.installationId)
+ ? parsed.installationId
+ : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+function writeTelemetryStateAtomically(path: string, state: TelemetryState): void {
+ const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+ try {
+ writeFileSync(temporaryPath, JSON.stringify(state, null, 2), {
+ encoding: "utf8",
+ flag: "wx",
+ mode: 0o600,
+ });
+ renameSync(temporaryPath, path);
+ } finally {
+ try {
+ unlinkSync(temporaryPath);
+ } catch {
+ // The rename succeeded or the temporary file was never created.
+ }
+ }
+}
+
+export function getOrCreateTelemetryInstallationId(agentDir: string, randomId: () => string = randomUUID): string {
+ const path = join(agentDir, TELEMETRY_STATE_FILE);
+ let replaceInvalidState = false;
+ try {
+ const stats = lstatSync(path);
+ if (!stats.isFile()) {
+ throw new Error("Telemetry state path must be a regular file");
+ }
+ const existing = readInstallationId(path);
+ if (existing) {
+ return existing;
+ }
+ replaceInvalidState = true;
+ } catch (error) {
+ const code =
+ typeof error === "object" && error !== null && "code" in error
+ ? String((error as { code?: unknown }).code)
+ : undefined;
+ if (code !== "ENOENT") {
+ throw error;
+ }
+ }
+
+ const installationId = randomId();
+ if (!isInstallationId(installationId)) {
+ throw new Error("Telemetry installation ID generator returned an invalid UUID");
+ }
+ mkdirSync(agentDir, { recursive: true });
+ const state: TelemetryState = {
+ version: TELEMETRY_STATE_VERSION,
+ installationId,
+ };
+ try {
+ if (replaceInvalidState) {
+ writeTelemetryStateAtomically(path, state);
+ } else {
+ writeFileSync(path, JSON.stringify(state, null, 2), {
+ encoding: "utf8",
+ flag: "wx",
+ mode: 0o600,
+ });
+ }
+ return installationId;
+ } catch (error) {
+ const code =
+ typeof error === "object" && error !== null && "code" in error
+ ? String((error as { code?: unknown }).code)
+ : undefined;
+ if (code !== "EEXIST") {
+ throw error;
+ }
+ return readInstallationId(path) ?? installationId;
+ }
+}
+
+export class TelemetryClient implements TelemetrySink {
+ private readonly endpoint: string;
+ private readonly fetchImpl: typeof fetch;
+ private readonly now: () => number;
+ private readonly randomId: () => string;
+ private readonly batchSize: number;
+ private readonly flushIntervalMs: number;
+ private readonly requestTimeoutMs: number;
+ private installationId?: string;
+ private queue: TelemetryEvent[] = [];
+ private flushTimer?: ReturnType<typeof setTimeout>;
+ private flushInFlight?: Promise<void>;
+ private disabled = false;
+
+ constructor(private readonly options: TelemetryClientOptions) {
+ this.endpoint = options.endpoint ?? process.env.PRIME_AGENT_TELEMETRY_ENDPOINT ?? DEFAULT_TELEMETRY_ENDPOINT;
+ this.fetchImpl = options.fetch ?? fetch;
+ this.now = options.now ?? Date.now;
+ this.randomId = options.randomId ?? randomUUID;
+ this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+ this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+ this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+ }
+
+ capture(name: TelemetryEventName, properties: TelemetryProperties): void {
+ if (this.disabled) {
+ return;
+ }
+ try {
+ this.installationId ??= getOrCreateTelemetryInstallationId(this.options.agentDir, this.randomId);
+ this.queue.push({
+ id: this.randomId(),
+ name,
+ timestamp: new Date(this.now()).toISOString(),
+ properties,
+ });
+ } catch {
+ this.disabled = true;
+ this.queue = [];
+ return;
+ }
+ if (this.queue.length >= this.batchSize) {
+ void this.flush();
+ return;
+ }
+ this.scheduleFlush();
+ }
+
+ private scheduleFlush(): void {
+ if (this.flushTimer) {
+ return;
+ }
+ this.flushTimer = setTimeout(() => {
+ this.flushTimer = undefined;
+ void this.flush();
+ }, this.flushIntervalMs);
+ this.flushTimer.unref?.();
+ }
+
+ async flush(): Promise<void> {
+ if (this.flushTimer) {
+ clearTimeout(this.flushTimer);
+ this.flushTimer = undefined;
+ }
+ if (this.flushInFlight) {
+ await this.flushInFlight;
+ if (this.queue.length > 0) {
+ await this.flush();
+ }
+ return;
+ }
+ if (this.queue.length === 0 || !this.installationId) {
+ return;
+ }
+
+ const drain = this.drainQueue();
+ this.flushInFlight = drain;
+ try {
+ await drain;
+ } finally {
+ if (this.flushInFlight === drain) {
+ this.flushInFlight = undefined;
+ }
+ }
+ if (this.queue.length > 0) {
+ await this.flush();
+ }
+ }
+
+ private async drainQueue(): Promise<void> {
+ while (this.queue.length > 0 && this.installationId) {
+ const events = this.queue.splice(0, this.batchSize);
+ const batch: TelemetryBatch = {
+ installation_id: this.installationId,
+ events,
+ };
+ await this.send(batch);
+ }
+ }
+
+ private async send(batch: TelemetryBatch): Promise<void> {
+ try {
+ await this.fetchImpl(this.endpoint, {
+ method: "POST",
+ headers: {
+ "content-type": "application/json",
+ "user-agent": `prime-agent/${VERSION}`,
+ },
+ body: JSON.stringify(batch),
+ signal: AbortSignal.timeout(this.requestTimeoutMs),
+ });
+ } catch {
+ // Product analytics is best-effort and must never affect the agent.
+ }
+ }
+}
+
+function modelCategory(model: string): string {
+ const normalized = model.toLowerCase();
+ const categories = [
+ "claude",
+ "gpt",
+ "o1",
+ "o3",
+ "o4",
+ "gemini",
+ "glm",
+ "kimi",
+ "qwen",
+ "deepseek",
+ "llama",
+ "mistral",
+ ];
+ return categories.find((category) => normalized.includes(category)) ?? "custom";
+}
+
+export function telemetryProviderCategory(provider: string | undefined): string {
+ if (!provider) {
+ return "unknown";
+ }
+ const normalized = provider.toLowerCase();
+ const categories = [
+ "anthropic",
+ "openai",
+ "google",
+ "prime",
+ "openrouter",
+ "bedrock",
+ "vertex",
+ "mistral",
+ "groq",
+ "xai",
+ ];
+ return categories.find((category) => normalized.includes(category)) ?? "custom";
+}
+
+export function telemetryAuthCategory(
+ source: AuthStatus["source"],
+ storedCredentialType?: AuthCredential["type"],
+): TelemetryAuthCategory {
+ switch (source) {
+ case "stored":
+ return storedCredentialType ?? "stored";
+ case "runtime":
+ return "runtime_api_key";
+ case "environment":
+ return "environment";
+ case "prime_cli":
+ return "prime_cli";
+ case "models_json_key":
+ case "models_json_command":
+ return "models_json";
+ case "fallback":
+ return "fallback";
+ case "stale":
+ return "stale";
+ default:
+ return "none";
+ }
+}
+
+function baseProperties(executionMode: TelemetryExecutionMode): TelemetryProperties {
+ return {
+ version: VERSION,
+ os_family: platform(),
+ architecture: arch(),
+ install_method: detectInstallMethod(),
+ execution_mode: executionMode,
+ };
+}
+
+export async function captureOnboardingCompleted(options: CaptureOnboardingCompletedOptions): Promise<void> {
+ if (!isTelemetryEnabled(options.settingsManager)) {
+ return;
+ }
+
+ const now = options.now ?? Date.now;
+ const randomId = options.randomId ?? randomUUID;
+ const sink =
+ options.sink ??
+ new TelemetryClient({
+ agentDir: options.agentDir,
+ now,
+ randomId,
+ });
+ sink.capture("onboarding completed", {
+ ...baseProperties("interactive"),
+ duration_ms: Math.max(0, options.durationMs),
+ outcome: options.outcome,
+ auth_category: telemetryAuthCategory(options.authSource, options.storedCredentialType),
+ provider_category: telemetryProviderCategory(options.provider),
+ });
+ await sink.flush();
+}
+
+export async function captureAgentCommandUsed(options: CaptureAgentCommandUsedOptions): Promise<void> {
+ if (!isBuiltinSlashCommandName(options.commandName) || !isTelemetryEnabled(options.settingsManager)) {
+ return;
+ }
+ const commandName = resolveBuiltinSlashCommandName(options.commandName);
+
+ const now = options.now ?? Date.now;
+ const randomId = options.randomId ?? randomUUID;
+ const sink =
+ options.sink ??
+ new TelemetryClient({
+ agentDir: options.agentDir,
+ now,
+ randomId,
+ });
+ sink.capture("agent command used", {
+ ...baseProperties("interactive"),
+ command_name: commandName,
+ });
+ await sink.flush();
+}
+
+function errorCategory(message: AssistantMessage | undefined): string | null {
+ if (!message || message.stopReason !== "error") {
+ return null;
+ }
+ const error = message.errorMessage?.toLowerCase() ?? "";
+ if (/\b401\b|\b403\b|auth|api.?key|credential|unauthori[sz]ed|forbidden/.test(error)) {
+ return "authentication";
+ }
+ if (/\b429\b|rate.?limit|quota/.test(error)) {
+ return "rate_limit";
+ }
+ if (/timeout|timed out/.test(error)) {
+ return "timeout";
+ }
+ if (/context|token.*limit|too long|maximum.*length/.test(error)) {
+ return "context_limit";
+ }
+ if (/network|socket|connection|fetch/.test(error)) {
+ return "network";
+ }
+ if (/\b5\d\d\b|overload|unavailable/.test(error)) {
+ return "provider_unavailable";
+ }
+ return "other";
+}
+
+function runOutcome(message: AssistantMessage | undefined): "success" | "error" | "aborted" {
+ if (message?.stopReason === "aborted") {
+ return "aborted";
+ }
+ if (!message || message.stopReason === "error") {
+ return "error";
+ }
+ return "success";
+}
+
+function assistantMessage(event: AgentSessionEvent): AssistantMessage | undefined {
+ if (event.type !== "message_end" || event.message.role !== "assistant") {
+ return undefined;
+ }
+ return event.message;
+}
+
+function createActiveRun(now: () => number): ActiveRun {
+ return {
+ startedAt: now(),
+ agentEnded: false,
+ modelLatencyMs: 0,
+ maxModelLatencyMs: 0,
+ turnCount: 0,
+ toolCallCount: 0,
+ toolErrorCount: 0,
+ compactionCount: 0,
+ retryCount: 0,
+ usage: newUsageTotals(),
+ };
+}
+
+export function installAgentTelemetry(session: AgentSession, options: InstallAgentTelemetryOptions): void {
+ if (!isTelemetryEnabled(options.settingsManager)) {
+ return;
+ }
+
+ const now = options.now ?? Date.now;
+ const randomId = options.randomId ?? randomUUID;
+ const sink =
+ options.sink ??
+ new TelemetryClient({
+ agentDir: options.agentDir,
+ now,
+ randomId,
+ });
+ const sessionId = randomId();
+ const sessionTotals: SessionTotals = {
+ startedAt: now(),
+ runCount: 0,
+ successfulRunCount: 0,
+ failedRunCount: 0,
+ abortedRunCount: 0,
+ promptCount: 0,
+ toolCallCount: 0,
+ compactionCount: 0,
+ usage: newUsageTotals(),
+ };
+ let activeRun: ActiveRun | undefined;
+ let turnActionActive = false;
+
+ const commonProperties = (): TelemetryProperties => ({
+ ...baseProperties(options.executionMode ?? "unknown"),
+ session_id: sessionId,
+ });
+
+ const finalizeRun = (): void => {
+ const run = activeRun;
+ if (!run) {
+ return;
+ }
+ activeRun = undefined;
+ const outcome = runOutcome(run.lastAssistant);
+ sessionTotals.runCount++;
+ sessionTotals.toolCallCount += run.toolCallCount;
+ sessionTotals.compactionCount += run.compactionCount;
+ if (outcome === "success") {
+ sessionTotals.successfulRunCount++;
+ } else if (outcome === "aborted") {
+ sessionTotals.abortedRunCount++;
+ } else {
+ sessionTotals.failedRunCount++;
+ }
+ mergeUsage(sessionTotals.usage, run.usage);
+ const lastAssistant = run.lastAssistant;
+ sink.capture("agent run completed", {
+ ...commonProperties(),
+ outcome,
+ duration_ms: Math.max(0, now() - run.startedAt),
+ visible_ttft_ms: run.visibleTtftMs ?? null,
+ first_model_event_ms: run.firstModelEventMs ?? null,
+ model_latency_ms: run.modelLatencyMs,
+ max_model_latency_ms: run.maxModelLatencyMs,
+ model_call_count: run.usage.modelCallCount,
+ turn_count: run.turnCount,
+ tool_call_count: run.toolCallCount,
+ tool_error_count: run.toolErrorCount,
+ input_tokens: run.usage.input,
+ output_tokens: run.usage.output,
+ cache_read_tokens: run.usage.cacheRead,
+ cache_write_tokens: run.usage.cacheWrite,
+ total_tokens: run.usage.totalTokens,
+ compaction_count: run.compactionCount,
+ retry_count: run.retryCount,
+ provider_category: telemetryProviderCategory(lastAssistant?.provider),
+ model_category: lastAssistant ? modelCategory(lastAssistant.model) : "unknown",
+ error_category: errorCategory(lastAssistant),
+ });
+ };
+
+ sink.capture("agent started", commonProperties());
+
+ const unsubscribe = session.subscribe((event) => {
+ switch (event.type) {
+ case "session_action_update":
+ turnActionActive = event.actions.active?.kind === "turn";
+ if (!turnActionActive && activeRun?.agentEnded) {
+ finalizeRun();
+ }
+ break;
+ case "agent_start":
+ if (activeRun?.agentEnded && !turnActionActive) {
+ finalizeRun();
+ }
+ activeRun ??= createActiveRun(now);
+ activeRun.agentEnded = false;
+ break;
+ case "message_start":
+ if (event.message.role === "user") {
+ sessionTotals.promptCount++;
+ }
+ break;
+ case "turn_start":
+ if (activeRun) {
+ activeRun.currentTurnStartedAt = now();
+ activeRun.firstTurnStartedAt ??= activeRun.currentTurnStartedAt;
+ activeRun.turnCount++;
+ }
+ break;
+ case "message_update":
+ if (!activeRun) {
+ break;
+ }
+ if (activeRun.firstModelEventMs === undefined && activeRun.firstTurnStartedAt !== undefined) {
+ activeRun.firstModelEventMs = Math.max(0, now() - activeRun.firstTurnStartedAt);
+ }
+ if (
+ activeRun.visibleTtftMs === undefined &&
+ activeRun.firstTurnStartedAt !== undefined &&
+ event.assistantMessageEvent.type === "text_delta" &&
+ event.assistantMessageEvent.delta.length > 0
+ ) {
+ activeRun.visibleTtftMs = Math.max(0, now() - activeRun.firstTurnStartedAt);
+ }
+ break;
+ case "message_end": {
+ const message = assistantMessage(event);
+ if (!activeRun || !message) {
+ break;
+ }
+ activeRun.lastAssistant = message;
+ addUsage(activeRun.usage, message.usage);
+ if (activeRun.currentTurnStartedAt !== undefined) {
+ const latency = Math.max(0, now() - activeRun.currentTurnStartedAt);
+ activeRun.modelLatencyMs += latency;
+ activeRun.maxModelLatencyMs = Math.max(activeRun.maxModelLatencyMs, latency);
+ activeRun.currentTurnStartedAt = undefined;
+ }
+ break;
+ }
+ case "tool_execution_end":
+ if (activeRun) {
+ activeRun.toolCallCount++;
+ if (event.isError) {
+ activeRun.toolErrorCount++;
+ }
+ }
+ break;
+ case "compaction_end":
+ if (activeRun && event.result && !event.aborted) {
+ activeRun.compactionCount++;
+ }
+ break;
+ case "auto_retry_start":
+ if (activeRun) {
+ activeRun.retryCount++;
+ }
+ break;
+ case "agent_end":
+ if (!activeRun) {
+ break;
+ }
+ activeRun.agentEnded = true;
+ if (!turnActionActive) {
+ finalizeRun();
+ }
+ break;
+ }
+ });
+
+ session.registerDisposeCallback(async () => {
+ unsubscribe();
+ finalizeRun();
+ sink.capture("agent session ended", {
+ ...commonProperties(),
+ duration_ms: Math.max(0, now() - sessionTotals.startedAt),
+ prompt_count: sessionTotals.promptCount,
+ run_count: sessionTotals.runCount,
+ successful_run_count: sessionTotals.successfulRunCount,
+ failed_run_count: sessionTotals.failedRunCount,
+ aborted_run_count: sessionTotals.abortedRunCount,
+ tool_call_count: sessionTotals.toolCallCount,
+ compaction_count: sessionTotals.compactionCount,
+ model_call_count: sessionTotals.usage.modelCallCount,
+ input_tokens: sessionTotals.usage.input,
+ output_tokens: sessionTotals.usage.output,
+ cache_read_tokens: sessionTotals.usage.cacheRead,
+ cache_write_tokens: sessionTotals.usage.cacheWrite,
+ total_tokens: sessionTotals.usage.totalTokens,
+ });
+ await sink.flush();
+ });
+}
diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index 04b9bb3a9f..6315d0ad7e 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -35,6 +35,7 @@ import {
} from "./cli/session-resolver.js";
import { APP_NAME, expandTildePath, getAgentDir, getSessionDirEnvOverride, VERSION } from "./config.js";
import {
+ type AgentExecutionMode,
type AgentSessionRuntimeConfig,
mergeAgentSessionRuntimeConfig,
mergeAutonomousConfig,
@@ -69,6 +70,7 @@ import {
import { canonicalSessionPath, SessionAlreadyActiveError } from "./core/session-lease.js";
import { SessionManager } from "./core/session-manager.js";
import { SettingsManager } from "./core/settings-manager.js";
+import { isTelemetryEnabled } from "./core/telemetry.js";
import { printTimings, resetTimings, time } from "./core/timings.js";
import { runMigrations, showDeprecationWarnings } from "./migrations.js";
import { isDaemonCatalogProcess, runDaemonCatalogProcess } from "./modes/daemon/daemon-catalog-process.js";
@@ -156,7 +158,7 @@ function isTruthyEnvFlag(value: string | undefined): boolean {
return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
}
-export type ClientMode = "interactive" | "print" | "json" | "rpc" | "acp";
+export type ClientMode = AgentExecutionMode;
/** Compatibility view of the CLI's internal daemon process entrypoint. */
export type AppMode = ClientMode | "daemon";
@@ -632,6 +634,7 @@ function runtimeConfigFromArgs(
agentDir: string,
sessionDir: string | undefined,
appMode: AppMode,
+ telemetryDisabled?: true,
): AgentSessionRuntimeConfig {
return {
cwd,
@@ -658,6 +661,8 @@ function runtimeConfigFromArgs(
noContextFiles: parsed.noContextFiles,
autonomous: runtimeAutonomousConfigFromArgs(parsed),
extensionFlagValues: parsed.unknownFlags.size > 0 ? Object.fromEntries(parsed.unknownFlags.entries()) : undefined,
+ executionMode: appMode === "daemon" ? undefined : appMode,
+ telemetryDisabled,
// Serialized refine for print/json/rpc: the client's appMode is NOT
// "daemon" here — it's "print", "json", or "rpc". The daemon worker
// receives this flag via AgentSessionRuntimeConfig and uses it
@@ -732,6 +737,7 @@ async function prepareRuntimeServices(options: {
// Subagents share the parent's Herdr pane; their own reporter would race
// the parent's and a subagent quit would release the still-active pane.
noBuiltinHerdrReporter: (options.sessionOptionsOverride?.rlmDepth ?? 0) > 0,
+ telemetryDisabled: config.telemetryDisabled,
resourceLoaderOptions: {
additionalExtensionPaths: config.extensions,
additionalSkillPaths: config.skills,
@@ -956,6 +962,7 @@ async function createDaemonClientConnection(options: {
ownedSession: options.clientOwned,
supportsExtensionUi: options.supportsExtensionUi,
recoverDaemon: () => ensureInteractiveDaemonRunning(options.socketPath),
+ telemetryDisabled: options.config.telemetryDisabled,
});
return { connection, summary };
};
@@ -1064,7 +1071,7 @@ export async function main(args: string[], options?: MainOptions) {
}
}
time("parseArgs");
- let appMode = resolveAppMode(parsed, process.stdin.isTTY);
+ const appMode = resolveAppMode(parsed, process.stdin.isTTY);
if (shouldRejectNonInteractiveAttach(publicCommand.attachAgent, appMode)) {
console.error(chalk.red("Error: attach requires an interactive terminal"));
@@ -1235,7 +1242,19 @@ export async function main(args: string[], options?: MainOptions) {
}
time("createSessionManager");
- const defaultSessionConfig = runtimeConfigFromArgs(parsed, sessionManager.getCwd(), agentDir, sessionDir, appMode);
+ const telemetrySettingsManager =
+ sessionManager.getCwd() === cwd
+ ? startupSettingsManager
+ : SettingsManager.create(sessionManager.getCwd(), agentDir);
+ const telemetryDisabled = isTelemetryEnabled(telemetrySettingsManager) ? undefined : true;
+ const defaultSessionConfig = runtimeConfigFromArgs(
+ parsed,
+ sessionManager.getCwd(),
+ agentDir,
+ sessionDir,
+ appMode,
+ telemetryDisabled,
+ );
// Verifier/headless clients pass initialGoal in each create request. The long-lived
// daemon fallback must not seed that goal into unrelated future sessions.
const daemonDefaultSessionConfig = daemonServerDefaultSessionConfig(defaultSessionConfig);
@@ -1272,6 +1291,8 @@ export async function main(args: string[], options?: MainOptions) {
// from the JSON/print client through AgentSessionRuntimeConfig)
// so it survives the daemon worker's appMode="daemon" context.
serializedRefine: config.serializedRefine ?? false,
+ executionMode: config.executionMode,
+ telemetryDisabled: config.telemetryDisabled,
// Only seed initial goal for top-level sessions (rlmDepth 0).
initialGoal: (runtimeSessionOptions?.rlmDepth ?? 0) === 0 ? config.initialGoal : undefined,
});
@@ -1324,12 +1345,7 @@ export async function main(args: string[], options?: MainOptions) {
const startupModel = await resolvePreparedStartupModel({ prepared, sessionManager });
- // ACP holds stdin open as a long-lived NDJSON request stream, so reading
- // piped stdin here would block until EOF and never return.
- let stdinContent: string | undefined;
- if (appMode !== "acp") {
- stdinContent = await readPipedStdin();
- }
+ const stdinContent = await readPipedStdin();
time("readPipedStdin");
const { initialMessage, initialImages } = await prepareInitialMessage(
@@ -1587,9 +1603,6 @@ export async function main(args: string[], options?: MainOptions) {
let stdinContent: string | undefined;
if (appMode !== "rpc" && appMode !== "acp" && appMode !== "daemon") {
stdinContent = await readPipedStdin();
- if (stdinContent !== undefined && appMode === "interactive") {
- appMode = "print";
- }
}
time("readPipedStdin");
diff --git a/packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.ts b/packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.ts
index 84f1a7db19..f5805785ec 100644
--- a/packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.ts
+++ b/packages/coding-agent/src/modes/agent-connection/daemon-agent-connection.ts
@@ -167,6 +167,8 @@ export interface DaemonAgentConnectionOptions {
supportsExtensionUi?: boolean;
/** Dispose the connection by stopping its hidden worker instead of detaching. */
ownedSession?: boolean;
+ /** Require the target worker to have been created with telemetry disabled. */
+ telemetryDisabled?: true;
}
/**
@@ -307,6 +309,7 @@ export class DaemonAgentConnection implements AgentConnection {
],
env: this.options.sendClientEnv ? collectDaemonClientEnv() : undefined,
launchEnv: this.options.ownedSession ? collectDaemonLaunchEnv() : undefined,
+ telemetryDisabled: this.options.telemetryDisabled,
resumeCursor:
this.lastEventCursor === undefined
? undefined
@@ -1139,6 +1142,7 @@ export class DaemonAgentConnection implements AgentConnection {
],
env: this.options.sendClientEnv ? collectDaemonClientEnv() : undefined,
launchEnv: this.options.ownedSession ? collectDaemonLaunchEnv() : undefined,
+ telemetryDisabled: this.options.telemetryDisabled,
});
reattached = true;
this.activeSessionId = result.activeSessionId;
diff --git a/packages/coding-agent/src/modes/agents-view/agents-view-mode.ts b/packages/coding-agent/src/modes/agents-view/agents-view-mode.ts
index 47fee3ad6a..a7e700400a 100644
--- a/packages/coding-agent/src/modes/agents-view/agents-view-mode.ts
+++ b/packages/coding-agent/src/modes/agents-view/agents-view-mode.ts
@@ -332,6 +332,7 @@ async function openAgentsViewSession(
closeClientOnDispose: true,
recoverDaemon: options.recoverDaemon,
reconnectTimeoutMs: options.reconnectTimeoutMs,
+ telemetryDisabled: options.config.telemetryDisabled,
});
return { connection, summary };
} catch (error) {
@@ -354,6 +355,7 @@ async function openAgentsViewSession(
closeClientOnDispose: true,
recoverDaemon: options.recoverDaemon,
reconnectTimeoutMs: options.reconnectTimeoutMs,
+ telemetryDisabled: options.config.telemetryDisabled,
});
return { connection, summary: resumed.summary, cwdFallbackNotice: resumed.cwdFallbackNotice };
} catch (error) {
@@ -2091,6 +2093,22 @@ export class AgentsViewMode implements Component, Focusable {
message: string,
streamingBehavior?: "steer" | "followUp",
): Promise<void> {
+ if (this.options.config.telemetryDisabled) {
+ const client = await this.connectDedicatedClient();
+ const connection = await DaemonAgentConnection.attach(client, activeSessionId, {
+ closeClientOnDispose: true,
+ supportsExtensionUi: false,
+ recoverDaemon: this.options.recoverDaemon,
+ reconnectTimeoutMs: this.options.reconnectTimeoutMs,
+ telemetryDisabled: true,
+ });
+ try {
+ await connection.prompt(message, streamingBehavior === undefined ? undefined : { streamingBehavior });
+ } finally {
+ await connection.dispose();
+ }
+ return;
+ }
const command: PromptCommand = { type: "prompt", activeSessionId, message };
if (streamingBehavior) command.streamingBehavior = streamingBehavior;
const response = await this.requireClient().request(command);
diff --git a/packages/coding-agent/src/modes/daemon/daemon-protocol.ts b/packages/coding-agent/src/modes/daemon/daemon-protocol.ts
index f9f41d47aa..02b1ad5e4d 100644
--- a/packages/coding-agent/src/modes/daemon/daemon-protocol.ts
+++ b/packages/coding-agent/src/modes/daemon/daemon-protocol.ts
@@ -56,8 +56,9 @@ export const DAEMON_COMMAND_ENVELOPE_MIN_PROTOCOL_VERSION = 7;
// Revision 11 adds immediate get/set commands for active-session RLM max depth.
// Revision 12 publishes idle-residency metadata on session summary rows.
// Revision 13 narrows agent-origin reach and roster wire shapes to the nuclear family.
-export const DAEMON_SCHEMA_REVISION = 13;
-export const DAEMON_SCHEMA_ID = "protocol-7-schema-13-816309b1cd50";
+// Revision 14 carries the client's monotonic telemetry opt-out on attach and reattach.
+export const DAEMON_SCHEMA_REVISION = 14;
+export const DAEMON_SCHEMA_ID = "protocol-7-schema-14-816309b1cd50";
export type DaemonProtocolName = typeof DAEMON_PROTOCOL_NAME;
export type DaemonProtocolVersion = number;
@@ -150,6 +151,8 @@ export interface DaemonAttachClientMetadata {
clientId?: DaemonClientId;
capabilities?: readonly DaemonClientCapability[];
resumeCursor?: DaemonResumeCursor;
+ /** Opt-out-only policy. A telemetry-enabled worker must reject this attach. */
+ telemetryDisabled?: true;
}
/**
@@ -631,6 +634,7 @@ const DELETE_RLM_SUBAGENT_COMMAND = {
capability: "delete_rlm_subagent",
} as const;
const FLAT_SESSION_TREE_COMMAND = { minProtocol: 7 } as const;
+const TELEMETRY_POLICY_COMMAND = { minProtocol: 7, minSchemaRevision: 14 } as const;
export const DAEMON_COMMAND_COMPATIBILITY = {
ack_result: LEGACY_DAEMON_COMMAND,
@@ -734,6 +738,12 @@ export const DAEMON_COMMAND_COMPATIBILITY = {
export function getDaemonCommandCompatibilities(command: DaemonCommand): readonly DaemonCommandCompatibility[] {
const compatibility = DAEMON_COMMAND_COMPATIBILITY[command.type];
+ const carriesTelemetryPolicy =
+ ((command.type === "attach" || command.type === "reattach") && command.telemetryDisabled !== undefined) ||
+ (command.type === "create" && command.config?.telemetryDisabled !== undefined);
+ if (carriesTelemetryPolicy) {
+ return [TELEMETRY_POLICY_COMMAND, compatibility];
+ }
if ((command.type === "prompt" || command.type === "prompt_and_wait") && command.admissionId !== undefined) {
return [PROMPT_ADMISSION_CANCELLATION_COMMAND, compatibility];
}
diff --git a/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts b/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
index bc74217cae..b22701bbcb 100644
--- a/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
+++ b/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
@@ -3263,6 +3263,7 @@ export class DaemonSupervisor {
if (ownedWorker.descriptor.ownerClientId !== this.protocolClientId(client)) {
throw new Error(`Unknown active session: ${command.activeSessionId}`);
}
+ this.assertTelemetryAttachAllowed(ownedWorker, command.telemetryDisabled);
ownedWorker.launchEnv = command.launchEnv ?? ownedWorker.launchEnv;
if (!ownedWorker.client || ownedWorker.descriptor.lifecycle !== "ready") {
if (!ownedWorker.launchEnv) {
@@ -3278,6 +3279,7 @@ export class DaemonSupervisor {
}
}
const match = await this.findWorkerForClient(client, command.activeSessionId);
+ this.assertTelemetryAttachAllowed(match.worker, command.telemetryDisabled);
const activeSessionId = match.summary.activeSessionId ?? match.summary.id;
const duplicateValidation = this.currentSnapshotGeneration(match.worker, activeSessionId)?.validation;
if (duplicateValidation) {
@@ -3424,6 +3426,14 @@ export class DaemonSupervisor {
}
}
+ private assertTelemetryAttachAllowed(worker: ResidentWorker, telemetryDisabled: true | undefined): void {
+ if (telemetryDisabled && worker.descriptor.createCommand.config?.telemetryDisabled !== true) {
+ throw new Error(
+ "Cannot attach to this active agent while telemetry is disabled for the current invocation. Stop the agent and retry so it can restart without telemetry.",
+ );
+ }
+ }
+
private cacheLoadedSnapshot(
worker: ResidentWorker,
activeSessionId: string,
diff --git a/packages/coding-agent/src/modes/interactive/interactive-mode.ts b/packages/coding-agent/src/modes/interactive/interactive-mode.ts
index ccfef6a4d5..0ec1d8bcd7 100644
--- a/packages/coding-agent/src/modes/interactive/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive/interactive-mode.ts
@@ -124,6 +124,11 @@ import {
parseSlashCommand,
resolveBuiltinSlashCommandName,
} from "../../core/slash-commands.js";
+import {
+ captureAgentCommandUsed,
+ captureOnboardingCompleted,
+ type TelemetryOnboardingOutcome,
+} from "../../core/telemetry.js";
import { type TruncationResult, truncateTail } from "../../core/tools/truncate.js";
import { PRIME_BUTTERFLY_LOGO } from "../../themes/prime-logo.js";
import { getChangelogPath, parseChangelog } from "../../utils/changelog.js";
@@ -232,7 +237,12 @@ import type {
InteractiveModeLocalToolRendererDefinition,
InteractiveModeUiServices,
} from "./interactive-mode-services.js";
-import { type OnboardingStartupState, shouldRunOnboarding, shouldRunPrimeCliOnboardingSplash } from "./onboarding.js";
+import {
+ isOnboardingModelReady,
+ type OnboardingStartupState,
+ shouldRunOnboarding,
+ shouldRunPrimeCliOnboardingSplash,
+} from "./onboarding.js";
import type { ClientPromptStashStore, PromptStash, PromptStashState } from "./prompt-stash-state.js";
import { formatResumeHint } from "./resume-hint.js";
import {
@@ -1708,11 +1718,32 @@ export class InteractiveMode {
return false;
}
+ const startedAt = Date.now();
const showPrimeCliSplash = this.shouldRunPrimeCliOnboardingSplash();
- this.markOnboardingShown();
- await this.settingsManager.flush();
- await this.runOnboardingFlow(showPrimeCliSplash);
- return true;
+ let outcome: TelemetryOnboardingOutcome = "aborted";
+ try {
+ this.markOnboardingShown();
+ await this.settingsManager.flush();
+ await this.runOnboardingFlow(showPrimeCliSplash);
+ outcome = isOnboardingModelReady(this.getOnboardingState()) ? "success" : "aborted";
+ return true;
+ } catch (error) {
+ outcome = "error";
+ throw error;
+ } finally {
+ const model = this.getCurrentModel();
+ const authStatus = model ? this.modelRegistry.getProviderAuthStatus(model.provider) : undefined;
+ const storedCredential = model ? this.modelRegistry.authStorage.get(model.provider) : undefined;
+ void captureOnboardingCompleted({
+ agentDir: getAgentDir(),
+ settingsManager: this.settingsManager,
+ durationMs: Date.now() - startedAt,
+ outcome,
+ provider: model?.provider,
+ authSource: authStatus?.source,
+ storedCredentialType: storedCredential?.type,
+ }).catch(() => {});
+ }
}
private async showOnboardingModelSelection(splash: OnboardingSplashHandle): Promise<void> {
@@ -4586,6 +4617,13 @@ export class InteractiveMode {
this.ui.requestRender();
return;
}
+ if (commandName) {
+ void captureAgentCommandUsed({
+ agentDir: getAgentDir(),
+ settingsManager: this.settingsManager,
+ commandName,
+ }).catch(() => {});
+ }
// Handle commands
if (commandName === "btw") {
diff --git a/packages/coding-agent/test/agent-connection-daemon.test.ts b/packages/coding-agent/test/agent-connection-daemon.test.ts
index a4da5b6dbe..7ff21e88c4 100644
--- a/packages/coding-agent/test/agent-connection-daemon.test.ts
+++ b/packages/coding-agent/test/agent-connection-daemon.test.ts
@@ -696,6 +696,21 @@ function emitSequencedQueueUpdate(client: FakeDaemonClient, activeSessionId: str
}
describe("DaemonAgentConnection", () => {
+ it("carries an opt-out-only telemetry policy on attach", async () => {
+ const fakeClient = new FakeDaemonClient();
+ const connection = new DaemonAgentConnection(asDaemonClient(fakeClient), "active-1", {
+ telemetryDisabled: true,
+ });
+
+ await connection.attach();
+
+ expect(fakeClient.requests[0]).toMatchObject({
+ type: "attach",
+ activeSessionId: "active-1",
+ telemetryDisabled: true,
+ });
+ });
+
it("forwards queueIfBusy for prompt admission", async () => {
const fakeClient = new FakeDaemonClient();
const connection = new DaemonAgentConnection(asDaemonClient(fakeClient), "active-1");
diff --git a/packages/coding-agent/test/agent-session-concurrent.test.ts b/packages/coding-agent/test/agent-session-concurrent.test.ts
index c26fb84eab..3321b7c35f 100644
--- a/packages/coding-agent/test/agent-session-concurrent.test.ts
+++ b/packages/coding-agent/test/agent-session-concurrent.test.ts
@@ -15,7 +15,7 @@ import {
type TextContent,
} from "@earendil-works/pi-ai";
import { Type } from "typebox";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { AgentSession } from "../src/core/agent-session.js";
import { AuthStorage } from "../src/core/auth-storage.js";
import { ModelRegistry } from "../src/core/model-registry.js";
@@ -127,6 +127,71 @@ describe("AgentSession concurrent prompt guard", () => {
return session;
}
+ it("awaits asynchronous dispose callbacks during graceful disposal", async () => {
+ createSession();
+ let releaseCallback: () => void = () => {};
+ const callbackGate = new Promise<void>((resolve) => {
+ releaseCallback = resolve;
+ });
+ let callbackStarted = false;
+ session.registerDisposeCallback(async () => {
+ callbackStarted = true;
+ await callbackGate;
+ });
+
+ let disposed = false;
+ const disposal = session.disposeAsync().then(() => {
+ disposed = true;
+ });
+ await new Promise<void>((resolve) => setTimeout(resolve, 0));
+ expect(callbackStarted).toBe(true);
+ expect(disposed).toBe(false);
+ releaseCallback();
+ await disposal;
+ expect(disposed).toBe(true);
+ });
+
+ it("awaits dispose callbacks when synchronous disposal wins during the refinement drain", async () => {
+ createSession();
+ let releaseDrain: () => void = () => {};
+ const drainGate = new Promise<void>((resolve) => {
+ releaseDrain = resolve;
+ });
+ let drainStarted = false;
+ const internals = session as unknown as {
+ _drainPendingRefinementForDisposal: () => Promise<void>;
+ };
+ vi.spyOn(internals, "_drainPendingRefinementForDisposal").mockImplementation(async () => {
+ drainStarted = true;
+ await drainGate;
+ });
+
+ let releaseCallback: () => void = () => {};
+ const callbackGate = new Promise<void>((resolve) => {
+ releaseCallback = resolve;
+ });
+ let callbackStarted = false;
+ session.registerDisposeCallback(async () => {
+ callbackStarted = true;
+ await callbackGate;
+ });
+
+ let disposed = false;
+ const disposal = session.disposeAsync().then(() => {
+ disposed = true;
+ });
+ await vi.waitFor(() => expect(drainStarted).toBe(true));
+ session.dispose();
+ expect(callbackStarted).toBe(true);
+
+ releaseDrain();
+ await new Promise<void>((resolve) => setTimeout(resolve, 0));
+ expect(disposed).toBe(false);
+ releaseCallback();
+ await disposal;
+ expect(disposed).toBe(true);
+ });
+
it("should throw when prompt() called while streaming", async () => {
createSession();
diff --git a/packages/coding-agent/test/agent-session-config.test.ts b/packages/coding-agent/test/agent-session-config.test.ts
index 5825482411..272fe5a342 100644
--- a/packages/coding-agent/test/agent-session-config.test.ts
+++ b/packages/coding-agent/test/agent-session-config.test.ts
@@ -151,4 +151,21 @@ describe("mergeAgentSessionRuntimeConfig", () => {
base.initialGoal!.objective = "mutated";
expect(merged.initialGoal?.objective).toBe("base goal");
});
+
+ it("preserves and overrides the user-facing execution mode across daemon config merges", () => {
+ const base: AgentSessionRuntimeConfig = {
+ cwd: "/repo",
+ executionMode: "interactive",
+ };
+
+ expect(mergeAgentSessionRuntimeConfig(base, { model: "openai/gpt-4o" }).executionMode).toBe("interactive");
+ expect(mergeAgentSessionRuntimeConfig(base, { executionMode: "rpc" }).executionMode).toBe("rpc");
+ expect(mergeAgentSessionRuntimeConfig(base).executionMode).toBe("interactive");
+ });
+
+ it("keeps the daemon telemetry opt-out monotonic across config merges", () => {
+ expect(mergeAgentSessionRuntimeConfig({ telemetryDisabled: true }, {}).telemetryDisabled).toBe(true);
+ expect(mergeAgentSessionRuntimeConfig({}, { telemetryDisabled: true }).telemetryDisabled).toBe(true);
+ expect(mergeAgentSessionRuntimeConfig({}, {}).telemetryDisabled).toBeUndefined();
+ });
});
diff --git a/packages/coding-agent/test/agent-session-services.test.ts b/packages/coding-agent/test/agent-session-services.test.ts
index 8123325114..ae0ad66221 100644
--- a/packages/coding-agent/test/agent-session-services.test.ts
+++ b/packages/coding-agent/test/agent-session-services.test.ts
@@ -2,12 +2,13 @@ import { existsSync, mkdirSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { registerFauxProvider } from "@earendil-works/pi-ai";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
import { AGENT_MESSAGE_SKILL_NAME, type AgentSessionMessageController } from "../src/core/agent-messages.js";
import { AGENT_OBSERVE_SKILL_NAME, type AgentObserveController } from "../src/core/agent-observe.js";
import { createAgentSessionFromServices, createAgentSessionServices } from "../src/core/agent-session-services.js";
import { AuthStorage } from "../src/core/auth-storage.js";
import { SessionManager } from "../src/core/session-manager.js";
+import { SettingsManager } from "../src/core/settings-manager.js";
import { createSyntheticSourceInfo } from "../src/core/source-info.js";
describe("createAgentSessionFromServices", () => {
@@ -15,6 +16,7 @@ describe("createAgentSessionFromServices", () => {
const unregisters: Array<() => void> = [];
afterEach(() => {
+ vi.unstubAllEnvs();
while (unregisters.length > 0) {
unregisters.pop()?.();
}
@@ -26,6 +28,81 @@ describe("createAgentSessionFromServices", () => {
}
});
+ it("shows the telemetry disclosure independently of the Herdr reporter", async () => {
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ const tempDir = join(tmpdir(), `pi-session-telemetry-notice-${Date.now()}`);
+ mkdirSync(tempDir, { recursive: true });
+ cleanupPaths.push(tempDir);
+ const settingsManager = SettingsManager.inMemory();
+
+ const services = await createAgentSessionServices({
+ cwd: tempDir,
+ agentDir: tempDir,
+ settingsManager,
+ noBuiltinHerdrReporter: true,
+ resourceLoaderOptions: { noPromptTemplates: true, noThemes: true },
+ });
+
+ expect(services.diagnostics).toContainEqual(
+ expect.objectContaining({ type: "info", message: expect.stringContaining("pseudonymous usage") }),
+ );
+ expect(settingsManager.getTelemetryNoticeShown()).toBe(true);
+ });
+
+ it("honors an explicit daemon-carried telemetry opt-out", async () => {
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ const tempDir = join(tmpdir(), `pi-session-daemon-telemetry-opt-out-${Date.now()}`);
+ mkdirSync(tempDir, { recursive: true });
+ cleanupPaths.push(tempDir);
+ const settingsManager = SettingsManager.inMemory();
+ const services = await createAgentSessionServices({
+ cwd: tempDir,
+ agentDir: tempDir,
+ settingsManager,
+ telemetryDisabled: true,
+ resourceLoaderOptions: { noPromptTemplates: true, noThemes: true },
+ });
+
+ expect(services.diagnostics).not.toContainEqual(
+ expect.objectContaining({ message: expect.stringContaining("pseudonymous usage") }),
+ );
+ expect(settingsManager.getTelemetryNoticeShown()).toBe(false);
+
+ const { session } = await createAgentSessionFromServices({
+ services,
+ sessionManager: SessionManager.create(tempDir, join(tempDir, "sessions")),
+ telemetryDisabled: true,
+ });
+ try {
+ expect(existsSync(join(tempDir, "telemetry.json"))).toBe(false);
+ } finally {
+ session.dispose();
+ }
+ });
+
+ it("does not install top-level telemetry for a resumed child session", async () => {
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ const tempDir = join(tmpdir(), `pi-session-child-telemetry-${Date.now()}`);
+ mkdirSync(tempDir, { recursive: true });
+ cleanupPaths.push(tempDir);
+ const services = await createAgentSessionServices({
+ cwd: tempDir,
+ agentDir: tempDir,
+ settingsManager: SettingsManager.inMemory({ telemetry: { noticeShown: true } }),
+ resourceLoaderOptions: { noPromptTemplates: true, noThemes: true },
+ });
+ const sessionManager = SessionManager.create(tempDir, join(tempDir, "sessions"));
+ sessionManager.newSession({ rlmDepth: 1 });
+
+ const { session } = await createAgentSessionFromServices({ services, sessionManager });
+ try {
+ expect(session.rlmDepth).toBe(1);
+ expect(existsSync(join(tempDir, "telemetry.json"))).toBe(false);
+ } finally {
+ session.dispose();
+ }
+ });
+
it("forwards daemon-backed agent message controllers into AgentSession", async () => {
const tempDir = join(tmpdir(), `pi-session-services-${Date.now()}-${Math.random().toString(36).slice(2)}`);
mkdirSync(tempDir, { recursive: true });
diff --git a/packages/coding-agent/test/agents-view-mode.test.ts b/packages/coding-agent/test/agents-view-mode.test.ts
index cbe3fc2356..b565937521 100644
--- a/packages/coding-agent/test/agents-view-mode.test.ts
+++ b/packages/coding-agent/test/agents-view-mode.test.ts
@@ -3,6 +3,7 @@ import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vite
import { KeybindingsManager } from "../src/core/keybindings.js";
import type { ModelRegistry } from "../src/core/model-registry.js";
import { SettingsManager } from "../src/core/settings-manager.js";
+import { DaemonAgentConnection } from "../src/modes/agent-connection/daemon-agent-connection.js";
import type { AgentConnectionSavedSessionInfo } from "../src/modes/agent-connection/types.js";
import {
AgentsViewMode,
@@ -20,6 +21,7 @@ const modeMocks = vi.hoisted(() => ({
interactiveRun: vi.fn<() => Promise<never>>(),
teardownSessionUi: vi.fn(async () => undefined),
dispose: vi.fn(async () => undefined),
+ connectionPrompt: vi.fn(async () => undefined),
clientRequest: vi.fn<() => Promise<unknown>>(),
}));
@@ -39,7 +41,7 @@ vi.mock("../src/modes/daemon/daemon-client.js", () => ({
vi.mock("../src/modes/agent-connection/daemon-agent-connection.js", () => ({
DaemonAgentConnection: Object.assign(function DaemonAgentConnection() {}, {
- attach: vi.fn(async () => ({ dispose: modeMocks.dispose })),
+ attach: vi.fn(async () => ({ prompt: modeMocks.connectionPrompt, dispose: modeMocks.dispose })),
}),
}));
@@ -229,6 +231,52 @@ describe("AgentsViewMode", () => {
});
});
+ it("checks telemetry policy before replying from an opted-out agents view", async () => {
+ const client = { close: vi.fn() };
+ const connectDedicatedClient = vi.fn(async () => client);
+ const self = {
+ options: {
+ config: { telemetryDisabled: true },
+ recoverDaemon: vi.fn(async () => undefined),
+ reconnectTimeoutMs: 1234,
+ },
+ connectDedicatedClient,
+ };
+
+ await invoke("sendPrompt", self, "active-1", "private prompt", "followUp");
+
+ expect(connectDedicatedClient).toHaveBeenCalledOnce();
+ expect(DaemonAgentConnection.attach).toHaveBeenCalledWith(client, "active-1", {
+ closeClientOnDispose: true,
+ supportsExtensionUi: false,
+ recoverDaemon: self.options.recoverDaemon,
+ reconnectTimeoutMs: 1234,
+ telemetryDisabled: true,
+ });
+ expect(modeMocks.connectionPrompt).toHaveBeenCalledWith("private prompt", {
+ streamingBehavior: "followUp",
+ });
+ expect(modeMocks.dispose).toHaveBeenCalledOnce();
+ });
+
+ it("keeps direct agents-view replies when telemetry is enabled", async () => {
+ const request = vi.fn(async () => ({ success: true as const, data: undefined }));
+ const self = {
+ options: { config: {} },
+ requireClient: () => ({ request }),
+ };
+
+ await invoke("sendPrompt", self, "active-1", "private prompt", "steer");
+
+ expect(request).toHaveBeenCalledWith({
+ type: "prompt",
+ activeSessionId: "active-1",
+ message: "private prompt",
+ streamingBehavior: "steer",
+ });
+ expect(DaemonAgentConnection.attach).not.toHaveBeenCalled();
+ });
+
it("uses the opened session as the crash-path back target", async () => {
const opened = summary({ sessionName: "opened" });
const previous = summary({ id: "previous", activeSessionId: "previous", sessionId: "previous" });
@@ -244,7 +292,7 @@ describe("AgentsViewMode", () => {
await runAgentsViewMode({
socketPath: "/tmp/fake-daemon.sock",
- config: { cwd: "/tmp" } as never,
+ config: { cwd: "/tmp", telemetryDisabled: true } as never,
initialSession: previous,
uiServices: {
settingsManager: settingsManager as never,
@@ -257,6 +305,11 @@ describe("AgentsViewMode", () => {
expect(modeMocks.teardownSessionUi).toHaveBeenCalledWith({ preserveAltScreen: true });
expect(modeMocks.dispose).toHaveBeenCalledOnce();
+ expect(DaemonAgentConnection.attach).toHaveBeenCalledWith(
+ expect.anything(),
+ opened.activeSessionId,
+ expect.objectContaining({ telemetryDisabled: true }),
+ );
runView.mockRestore();
});
diff --git a/packages/coding-agent/test/daemon-protocol.test.ts b/packages/coding-agent/test/daemon-protocol.test.ts
index 4843eb7ffd..4cf1e4c186 100644
--- a/packages/coding-agent/test/daemon-protocol.test.ts
+++ b/packages/coding-agent/test/daemon-protocol.test.ts
@@ -16,6 +16,7 @@ import {
DAEMON_SCHEMA_REVISION,
type DaemonCommand,
type DaemonOutbound,
+ getDaemonCommandCompatibilities,
isDaemonCommandEnvelope,
isDaemonMutatingCommand,
salvageDaemonCommandId,
@@ -88,6 +89,29 @@ describe("daemon protocol helpers", () => {
expect(DAEMON_COMMAND_COMPATIBILITY.set_rlm_max_depth).toEqual({ minProtocol: 7, minSchemaRevision: 11 });
});
+ it("schema-gates session commands that carry the telemetry policy", () => {
+ expect(getDaemonCommandCompatibilities({ type: "create", config: { cwd: "/tmp" } })).toEqual([
+ { minProtocol: 7 },
+ ]);
+ expect(
+ getDaemonCommandCompatibilities({ type: "create", config: { cwd: "/tmp", telemetryDisabled: true } }),
+ ).toEqual([{ minProtocol: 7, minSchemaRevision: 14 }, { minProtocol: 7 }]);
+ expect(getDaemonCommandCompatibilities({ type: "attach", activeSessionId: "active-1" })).toEqual([
+ { minProtocol: 7 },
+ ]);
+ expect(
+ getDaemonCommandCompatibilities({ type: "attach", activeSessionId: "active-1", telemetryDisabled: true }),
+ ).toEqual([{ minProtocol: 7, minSchemaRevision: 14 }, { minProtocol: 7 }]);
+ expect(
+ getDaemonCommandCompatibilities({
+ type: "reattach",
+ activeSessionId: "active-1",
+ targetActiveSessionId: "active-2",
+ telemetryDisabled: true,
+ }),
+ ).toEqual([{ minProtocol: 7, minSchemaRevision: 14 }, { minProtocol: 7 }]);
+ });
+
it("version- and capability-gates prompt admission cancellation", () => {
expect(DAEMON_COMMAND_COMPATIBILITY.cancel_prompt_admission).toEqual({
minProtocol: 7,
diff --git a/packages/coding-agent/test/daemon-supervisor-monitor.test.ts b/packages/coding-agent/test/daemon-supervisor-monitor.test.ts
index 2b74a15eb8..1814acbf7e 100644
--- a/packages/coding-agent/test/daemon-supervisor-monitor.test.ts
+++ b/packages/coding-agent/test/daemon-supervisor-monitor.test.ts
@@ -1639,6 +1639,87 @@ describe("daemon worker supervisor monitoring", () => {
expect(seed).toHaveBeenCalledWith(activeSessionId, streamingMessage);
});
+ it("rejects an opted-out attach to a telemetry-enabled worker", async () => {
+ const activeSessionId = "active-telemetry-enabled";
+ const summary = {
+ id: activeSessionId,
+ activeSessionId,
+ lifecycle: "live",
+ activity: "idle",
+ isSessionActive: false,
+ sessionId: "session-telemetry-enabled",
+ cwd: "/tmp/project",
+ isStreaming: false,
+ isCompacting: false,
+ attachedClients: 0,
+ messageCount: 0,
+ sessionActions: { queuedCount: 0, steering: [], followUps: [] },
+ } satisfies SessionSummary;
+ const worker = {
+ descriptor: {
+ workerId: "worker-telemetry-enabled",
+ lifecycle: "ready",
+ pid: 1234,
+ createCommand: { type: "create", config: {} },
+ },
+ summaries: new Map([[activeSessionId, summary]]),
+ };
+ const client = {
+ id: "client-1",
+ capabilities: new Set<string>(),
+ supportsExtensionUi: false,
+ attachedActiveSessionIds: new Set<string>(),
+ };
+ const supervisor = Object.assign(Object.create(DaemonSupervisor.prototype), {
+ workers: new Map([[worker.descriptor.workerId, worker]]),
+ clients: new Set([client]),
+ }) as {
+ attachClient(
+ attachClient: typeof client,
+ command: { type: "attach"; activeSessionId: string; telemetryDisabled?: true },
+ ): Promise<unknown>;
+ };
+
+ await expect(
+ supervisor.attachClient(client, { type: "attach", activeSessionId, telemetryDisabled: true }),
+ ).rejects.toThrow("Cannot attach to this active agent while telemetry is disabled");
+ expect(client.attachedActiveSessionIds).toEqual(new Set());
+ });
+
+ it("does not reveal an owned session's telemetry policy to another client", async () => {
+ const activeSessionId = "private-owned-active";
+ const worker = {
+ descriptor: {
+ workerId: "private-owned-worker",
+ ownerClientId: "owner-client",
+ rootActiveSessionId: activeSessionId,
+ lifecycle: "ready",
+ pid: 1234,
+ createCommand: { type: "create", config: {} },
+ },
+ };
+ const client = {
+ id: "other-client",
+ capabilities: new Set<string>(),
+ supportsExtensionUi: false,
+ attachedActiveSessionIds: new Set<string>(),
+ };
+ const supervisor = Object.assign(Object.create(DaemonSupervisor.prototype), {
+ workers: new Map([[worker.descriptor.workerId, worker]]),
+ clients: new Set([client]),
+ protocolClientIds: new Map(),
+ }) as {
+ attachClient(
+ attachClient: typeof client,
+ command: { type: "attach"; activeSessionId: string; telemetryDisabled?: true },
+ ): Promise<unknown>;
+ };
+
+ await expect(
+ supervisor.attachClient(client, { type: "attach", activeSessionId, telemetryDisabled: true }),
+ ).rejects.toThrow(`Unknown active session: ${activeSessionId}`);
+ });
+
it("catches up only after worker events are skipped behind a backpressured write", async () => {
const activeSessionId = "active-backpressure";
const writes: string[] = [];
diff --git a/packages/coding-agent/test/interactive-mode-prompt-stash.test.ts b/packages/coding-agent/test/interactive-mode-prompt-stash.test.ts
index b77c85ee6e..4ca90388aa 100644
--- a/packages/coding-agent/test/interactive-mode-prompt-stash.test.ts
+++ b/packages/coding-agent/test/interactive-mode-prompt-stash.test.ts
@@ -81,6 +81,7 @@ type ResetHarness = PromptStashLiveMarkerHarness & {
type SubmitHarness = PromptStashHarness & {
defaultEditor: { onSubmit?: (text: string) => void | Promise<void> };
+ uiServices: { settingsManager: { getTelemetryEnabled: Mock<() => boolean> } };
sideQuestionContainer: { clear: Mock };
isAgentCompacting: () => boolean;
isAgentStreaming: () => boolean;
@@ -186,6 +187,7 @@ function createSubmitHarness(
const mode: SubmitHarness = {
...createPromptStashHarness(options),
defaultEditor: {},
+ uiServices: { settingsManager: { getTelemetryEnabled: vi.fn(() => false) } },
sideQuestionContainer: { clear: vi.fn() },
isAgentCompacting: () => false,
isAgentStreaming: () => false,
diff --git a/packages/coding-agent/test/interactive-mode-status.test.ts b/packages/coding-agent/test/interactive-mode-status.test.ts
index 56abec3127..7098e2f08a 100644
--- a/packages/coding-agent/test/interactive-mode-status.test.ts
+++ b/packages/coding-agent/test/interactive-mode-status.test.ts
@@ -2944,6 +2944,7 @@ describe("InteractiveMode Prime CLI onboarding", () => {
};
uiServices: {
modelRegistry: {
+ authStorage: Pick<AuthStorage, "get">;
refresh: () => void;
hasConfiguredAuth: (model: unknown) => boolean;
getProviderAuthStatus: (provider: string) => AuthStatus;
@@ -3616,6 +3617,7 @@ describe("InteractiveMode Prime CLI onboarding", () => {
};
fakeThis.uiServices = {
modelRegistry: {
+ authStorage: AuthStorage.inMemory(),
refresh: vi.fn(),
hasConfiguredAuth: vi.fn(() => true),
getProviderAuthStatus: vi.fn(
diff --git a/packages/coding-agent/test/settings-manager.test.ts b/packages/coding-agent/test/settings-manager.test.ts
index bb07a2650a..9a0955d867 100644
--- a/packages/coding-agent/test/settings-manager.test.ts
+++ b/packages/coding-agent/test/settings-manager.test.ts
@@ -526,4 +526,56 @@ describe("SettingsManager", () => {
expect(JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf8")).idleEvictionMinutes).toBe("off");
});
});
+
+ describe("telemetry privacy controls", () => {
+ it("does not let project settings override a global opt-out or disclosure state", () => {
+ writeFileSync(
+ join(agentDir, "settings.json"),
+ JSON.stringify({ telemetry: { enabled: false, noticeShown: false } }),
+ );
+ writeFileSync(
+ join(projectDir, ".prime", "agent", "settings.json"),
+ JSON.stringify({ telemetry: { enabled: true, noticeShown: true } }),
+ );
+
+ const manager = SettingsManager.create(projectDir, agentDir);
+
+ expect(manager.getTelemetryEnabled()).toBe(false);
+ expect(manager.getTelemetryNoticeShown()).toBe(false);
+ });
+
+ it("allows project settings to further disable globally enabled telemetry", () => {
+ writeFileSync(join(agentDir, "settings.json"), JSON.stringify({ telemetry: { enabled: true } }));
+ writeFileSync(
+ join(projectDir, ".prime", "agent", "settings.json"),
+ JSON.stringify({ telemetry: { enabled: false } }),
+ );
+
+ const manager = SettingsManager.create(projectDir, agentDir);
+
+ expect(manager.getTelemetryEnabled()).toBe(false);
+ });
+
+ it("allows runtime overrides to further disable telemetry and control disclosure", () => {
+ writeFileSync(
+ join(agentDir, "settings.json"),
+ JSON.stringify({ telemetry: { enabled: true, noticeShown: true } }),
+ );
+ const manager = SettingsManager.create(projectDir, agentDir);
+
+ manager.applyOverrides({ telemetry: { enabled: false, noticeShown: false } });
+
+ expect(manager.getTelemetryEnabled()).toBe(false);
+ expect(manager.getTelemetryNoticeShown()).toBe(false);
+ });
+
+ it("does not let a runtime override re-enable a global opt-out", () => {
+ writeFileSync(join(agentDir, "settings.json"), JSON.stringify({ telemetry: { enabled: false } }));
+ const manager = SettingsManager.create(projectDir, agentDir);
+
+ manager.applyOverrides({ telemetry: { enabled: true } });
+
+ expect(manager.getTelemetryEnabled()).toBe(false);
+ });
+ });
});
diff --git a/packages/coding-agent/test/suite/regressions/4509-side-questions.test.ts b/packages/coding-agent/test/suite/regressions/4509-side-questions.test.ts
index 1679c2addf..bf8de05144 100644
--- a/packages/coding-agent/test/suite/regressions/4509-side-questions.test.ts
+++ b/packages/coding-agent/test/suite/regressions/4509-side-questions.test.ts
@@ -407,6 +407,7 @@ describe("ENG-4509 side questions", () => {
const fakeThis = Object.assign(Object.create(InteractiveMode.prototype), {
defaultEditor,
editor: { getText: () => "", setText: vi.fn(), addToHistory },
+ uiServices: { settingsManager: { getTelemetryEnabled: vi.fn(() => false) } },
promptStashState: { stash: undefined },
clearShortcutGuide: vi.fn(),
sideQuestionComponent: {},
diff --git a/packages/coding-agent/test/telemetry.test.ts b/packages/coding-agent/test/telemetry.test.ts
new file mode 100644
index 0000000000..12b4e17c50
--- /dev/null
+++ b/packages/coding-agent/test/telemetry.test.ts
@@ -0,0 +1,528 @@
+import { lstatSync, mkdtempSync, readFileSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AgentSession, AgentSessionEvent } from "../src/core/agent-session.js";
+import { SettingsManager } from "../src/core/settings-manager.js";
+import {
+ captureAgentCommandUsed,
+ captureOnboardingCompleted,
+ getOrCreateTelemetryInstallationId,
+ installAgentTelemetry,
+ isTelemetryEnabled,
+ TelemetryClient,
+ type TelemetryEvent,
+ type TelemetryEventName,
+ type TelemetrySink,
+ telemetryAuthCategory,
+} from "../src/core/telemetry.js";
+
+function uuidGenerator(): () => string {
+ let counter = 0;
+ return () => {
+ counter++;
+ return `00000000-0000-4000-8000-${String(counter).padStart(12, "0")}`;
+ };
+}
+
+function assistantMessage(overrides: Partial<AssistantMessage> = {}): AssistantMessage {
+ return {
+ role: "assistant",
+ content: [{ type: "text", text: "private response" }],
+ api: "openai-responses",
+ provider: "openai",
+ model: "gpt-5",
+ usage: {
+ input: 100,
+ output: 20,
+ cacheRead: 50,
+ cacheWrite: 0,
+ totalTokens: 170,
+ cost: {
+ input: 0.001,
+ output: 0.002,
+ cacheRead: 0.0001,
+ cacheWrite: 0,
+ total: 0.0031,
+ },
+ },
+ stopReason: "stop",
+ timestamp: 1,
+ ...overrides,
+ };
+}
+
+class FakeTelemetrySink implements TelemetrySink {
+ readonly events: Array<{ name: TelemetryEventName; properties: Record<string, string | number | boolean | null> }> =
+ [];
+ flushCount = 0;
+
+ capture(name: TelemetryEventName, properties: Record<string, string | number | boolean | null>): void {
+ this.events.push({ name, properties });
+ }
+
+ async flush(): Promise<void> {
+ this.flushCount++;
+ }
+}
+
+class FakeAgentSession {
+ private listener?: (event: AgentSessionEvent) => void;
+ private disposeCallback?: () => void | Promise<void>;
+
+ subscribe(listener: (event: AgentSessionEvent) => void): () => void {
+ this.listener = listener;
+ return () => {
+ this.listener = undefined;
+ };
+ }
+
+ registerDisposeCallback(callback: () => void | Promise<void>): void {
+ this.disposeCallback = callback;
+ }
+
+ emit(event: AgentSessionEvent): void {
+ this.listener?.(event);
+ }
+
+ dispose(): void {
+ void this.disposeCallback?.();
+ }
+
+ async disposeAsync(): Promise<void> {
+ await this.disposeCallback?.();
+ }
+}
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+});
+
+describe("telemetry identity and transport", () => {
+ it("creates a private stable installation ID", () => {
+ const agentDir = mkdtempSync(join(tmpdir(), "prime-agent-telemetry-"));
+ const randomId = uuidGenerator();
+
+ const first = getOrCreateTelemetryInstallationId(agentDir, randomId);
+ const second = getOrCreateTelemetryInstallationId(agentDir, randomId);
+
+ expect(second).toBe(first);
+ const path = join(agentDir, "telemetry.json");
+ expect(JSON.parse(readFileSync(path, "utf8"))).toEqual({
+ version: 1,
+ installationId: first,
+ });
+ expect(statSync(path).mode & 0o777).toBe(0o600);
+ });
+
+ it("replaces invalid persisted installation state", () => {
+ const agentDir = mkdtempSync(join(tmpdir(), "prime-agent-telemetry-"));
+ const path = join(agentDir, "telemetry.json");
+ writeFileSync(path, "not-json");
+ const randomId = uuidGenerator();
+
+ const installationId = getOrCreateTelemetryInstallationId(agentDir, randomId);
+
+ expect(JSON.parse(readFileSync(path, "utf8"))).toEqual({
+ version: 1,
+ installationId,
+ });
+ expect(getOrCreateTelemetryInstallationId(agentDir, randomId)).toBe(installationId);
+ });
+
+ it("does not follow a telemetry state symlink", async () => {
+ const agentDir = mkdtempSync(join(tmpdir(), "prime-agent-telemetry-"));
+ const targetPath = join(agentDir, "target.json");
+ const telemetryPath = join(agentDir, "telemetry.json");
+ writeFileSync(targetPath, "do not overwrite");
+ symlinkSync(targetPath, telemetryPath);
+ const client = new TelemetryClient({ agentDir, randomId: uuidGenerator() });
+
+ expect(() => client.capture("agent started", {})).not.toThrow();
+ await expect(client.flush()).resolves.toBeUndefined();
+
+ expect(readFileSync(targetPath, "utf8")).toBe("do not overwrite");
+ expect(lstatSync(telemetryPath).isSymbolicLink()).toBe(true);
+ });
+
+ it("batches events through the configured Prime endpoint", async () => {
+ const agentDir = mkdtempSync(join(tmpdir(), "prime-agent-telemetry-"));
+ const requests: Array<{ url: string; init: RequestInit }> = [];
+ const fetchMock: typeof fetch = async (input, init) => {
+ requests.push({ url: String(input), init: init ?? {} });
+ return new Response(null, { status: 204 });
+ };
+ const client = new TelemetryClient({
+ agentDir,
+ endpoint: "https://api.example.test/api/v1/agent-analytics/events",
+ fetch: fetchMock,
+ randomId: uuidGenerator(),
+ now: () => Date.UTC(2026, 6, 23),
+ });
+
+ client.capture("agent started", {
+ version: "1.2.3",
+ os_family: "darwin",
+ });
+ await client.flush();
+
+ expect(requests).toHaveLength(1);
+ expect(requests[0].url).toBe("https://api.example.test/api/v1/agent-analytics/events");
+ const body = JSON.parse(String(requests[0].init.body)) as {
+ installation_id: string;
+ events: TelemetryEvent[];
+ };
+ expect(body.installation_id).toMatch(/^[0-9a-f-]{36}$/);
+ expect(body.events).toEqual([
+ expect.objectContaining({
+ name: "agent started",
+ timestamp: "2026-07-23T00:00:00.000Z",
+ properties: {
+ version: "1.2.3",
+ os_family: "darwin",
+ },
+ }),
+ ]);
+ });
+
+ it("never throws when the analytics endpoint fails", async () => {
+ const client = new TelemetryClient({
+ agentDir: mkdtempSync(join(tmpdir(), "prime-agent-telemetry-")),
+ fetch: async () => {
+ throw new Error("network failed");
+ },
+ randomId: uuidGenerator(),
+ });
+
+ client.capture("agent started", {});
+ await expect(client.flush()).resolves.toBeUndefined();
+ });
+
+ it("drains every queued batch before flush resolves", async () => {
+ const batchSizes: number[] = [];
+ const client = new TelemetryClient({
+ agentDir: mkdtempSync(join(tmpdir(), "prime-agent-telemetry-")),
+ fetch: async (_input, init) => {
+ const body = JSON.parse(String(init?.body)) as { events: TelemetryEvent[] };
+ batchSizes.push(body.events.length);
+ return new Response(null, { status: 204 });
+ },
+ randomId: uuidGenerator(),
+ batchSize: 2,
+ });
+
+ for (let index = 0; index < 5; index++) {
+ client.capture("agent started", { index });
+ }
+ await client.flush();
+
+ expect(batchSizes.reduce((total, size) => total + size, 0)).toBe(5);
+ expect(batchSizes.every((size) => size <= 2)).toBe(true);
+ });
+
+ it("never throws when the local telemetry state cannot be written", async () => {
+ const parent = mkdtempSync(join(tmpdir(), "prime-agent-telemetry-"));
+ const agentDir = join(parent, "not-a-directory");
+ writeFileSync(agentDir, "occupied");
+ const client = new TelemetryClient({ agentDir, randomId: uuidGenerator() });
+
+ expect(() => client.capture("agent started", {})).not.toThrow();
+ await expect(client.flush()).resolves.toBeUndefined();
+ });
+});
+
+describe("telemetry controls", () => {
+ it("honors settings and environment opt-outs", () => {
+ const settings = SettingsManager.inMemory({ telemetry: { enabled: true } });
+
+ vi.stubEnv("NODE_ENV", "production");
+ expect(isTelemetryEnabled(settings)).toBe(true);
+
+ vi.stubEnv("DO_NOT_TRACK", "1");
+ expect(isTelemetryEnabled(settings)).toBe(false);
+
+ vi.stubEnv("DO_NOT_TRACK", "0");
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "0");
+ expect(isTelemetryEnabled(settings)).toBe(false);
+
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ vi.stubEnv("PI_OFFLINE", "true");
+ expect(isTelemetryEnabled(settings)).toBe(false);
+ });
+
+ it("is disabled by default in tests unless explicitly enabled", () => {
+ const settings = SettingsManager.inMemory({ telemetry: { enabled: true } });
+ vi.stubEnv("NODE_ENV", "test");
+ expect(isTelemetryEnabled(settings)).toBe(false);
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ expect(isTelemetryEnabled(settings)).toBe(true);
+ });
+
+ it("normalizes malformed telemetry settings before updating them", async () => {
+ const settings = SettingsManager.inMemory({ telemetry: true as never });
+ const disabledSettings = SettingsManager.inMemory({ telemetry: false as never });
+
+ expect(disabledSettings.getTelemetryEnabled()).toBe(false);
+ expect(() => settings.setTelemetryNoticeShown(true)).not.toThrow();
+ expect(() => settings.setTelemetryEnabled(false)).not.toThrow();
+ await settings.flush();
+
+ expect(settings.getGlobalSettings().telemetry).toEqual({
+ noticeShown: true,
+ enabled: false,
+ });
+ });
+});
+
+describe("agent telemetry aggregation", () => {
+ it("captures only allowlisted built-in command names", async () => {
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ const sink = new FakeTelemetrySink();
+
+ await captureAgentCommandUsed({
+ agentDir: "/not-used",
+ settingsManager: SettingsManager.inMemory(),
+ commandName: "model",
+ sink,
+ });
+ await captureAgentCommandUsed({
+ agentDir: "/not-used",
+ settingsManager: SettingsManager.inMemory(),
+ commandName: "private-extension-command",
+ sink,
+ });
+
+ expect(sink.events).toContainEqual({
+ name: "agent command used",
+ properties: expect.objectContaining({
+ execution_mode: "interactive",
+ command_name: "model",
+ }),
+ });
+ expect(sink.events).toHaveLength(1);
+ });
+
+ it("captures onboarding completion with categorized auth and provider data", async () => {
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ const sink = new FakeTelemetrySink();
+
+ await captureOnboardingCompleted({
+ agentDir: "/not-used",
+ settingsManager: SettingsManager.inMemory(),
+ durationMs: 250,
+ outcome: "success",
+ provider: "prime",
+ authSource: "stored",
+ storedCredentialType: "oauth",
+ sink,
+ });
+
+ expect(sink.events).toContainEqual({
+ name: "onboarding completed",
+ properties: expect.objectContaining({
+ execution_mode: "interactive",
+ duration_ms: 250,
+ outcome: "success",
+ auth_category: "oauth",
+ provider_category: "prime",
+ }),
+ });
+ expect(sink.flushCount).toBe(1);
+ expect(telemetryAuthCategory("models_json_command")).toBe("models_json");
+ });
+
+ it("emits aggregate metrics without message or tool content", () => {
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ let timestamp = 1_000;
+ const now = () => timestamp;
+ const randomId = uuidGenerator();
+ const sink = new FakeTelemetrySink();
+ const fakeSession = new FakeAgentSession();
+
+ installAgentTelemetry(fakeSession as unknown as AgentSession, {
+ agentDir: "/not-used",
+ settingsManager: SettingsManager.inMemory(),
+ executionMode: "interactive",
+ sink,
+ now,
+ randomId,
+ });
+
+ const assistant = assistantMessage();
+ fakeSession.emit({
+ type: "session_action_update",
+ actions: { queuedCount: 0, steering: [], followUps: [], active: { kind: "turn", phase: "running" } },
+ });
+ fakeSession.emit({ type: "agent_start" });
+ fakeSession.emit({
+ type: "message_start",
+ message: {
+ role: "user",
+ content: "private prompt",
+ timestamp,
+ },
+ });
+ timestamp = 1_010;
+ fakeSession.emit({ type: "turn_start" });
+ timestamp = 1_035;
+ fakeSession.emit({
+ type: "message_update",
+ message: assistant,
+ assistantMessageEvent: {
+ type: "text_delta",
+ contentIndex: 0,
+ delta: "private streamed text",
+ partial: assistant,
+ },
+ });
+ timestamp = 1_050;
+ fakeSession.emit({
+ type: "tool_execution_end",
+ toolCallId: "private-tool-id",
+ toolName: "bash",
+ result: { private: "tool output" },
+ isError: false,
+ });
+ timestamp = 1_100;
+ fakeSession.emit({ type: "message_end", message: assistant });
+ fakeSession.emit({ type: "turn_end", message: assistant, toolResults: [] });
+ timestamp = 1_125;
+ fakeSession.emit({ type: "agent_end", messages: [assistant] });
+ fakeSession.emit({ type: "session_action_update", actions: { queuedCount: 0, steering: [], followUps: [] } });
+
+ const run = sink.events.find((event) => event.name === "agent run completed");
+ expect(run?.properties).toMatchObject({
+ execution_mode: "interactive",
+ outcome: "success",
+ duration_ms: 125,
+ visible_ttft_ms: 25,
+ first_model_event_ms: 25,
+ model_latency_ms: 90,
+ turn_count: 1,
+ tool_call_count: 1,
+ tool_error_count: 0,
+ input_tokens: 100,
+ output_tokens: 20,
+ cache_read_tokens: 50,
+ total_tokens: 170,
+ retry_count: 0,
+ provider_category: "openai",
+ model_category: "gpt",
+ });
+ expect(JSON.stringify(run)).not.toContain("private");
+
+ timestamp = 1_200;
+ fakeSession.dispose();
+ const ended = sink.events.find((event) => event.name === "agent session ended");
+ expect(ended?.properties).toMatchObject({
+ duration_ms: 200,
+ prompt_count: 1,
+ run_count: 1,
+ successful_run_count: 1,
+ total_tokens: 170,
+ });
+ expect(sink.flushCount).toBe(1);
+ });
+
+ it("waits for post-run compaction before finalizing run metrics", () => {
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ const sink = new FakeTelemetrySink();
+ const fakeSession = new FakeAgentSession();
+
+ installAgentTelemetry(fakeSession as unknown as AgentSession, {
+ agentDir: "/not-used",
+ settingsManager: SettingsManager.inMemory(),
+ sink,
+ });
+
+ const assistant = assistantMessage();
+ fakeSession.emit({
+ type: "session_action_update",
+ actions: { queuedCount: 0, steering: [], followUps: [], active: { kind: "turn", phase: "running" } },
+ });
+ fakeSession.emit({ type: "agent_start" });
+ fakeSession.emit({ type: "message_end", message: assistant });
+ fakeSession.emit({ type: "agent_end", messages: [assistant] });
+ expect(sink.events.find((event) => event.name === "agent run completed")).toBeUndefined();
+
+ fakeSession.emit({
+ type: "compaction_end",
+ reason: "threshold",
+ result: { summary: "private", firstKeptEntryId: "private", tokensBefore: 100 },
+ aborted: false,
+ willRetry: false,
+ });
+ fakeSession.emit({ type: "session_action_update", actions: { queuedCount: 0, steering: [], followUps: [] } });
+
+ expect(sink.events.find((event) => event.name === "agent run completed")?.properties.compaction_count).toBe(1);
+ });
+
+ it("keeps automatic retries in one completed run", () => {
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ const sink = new FakeTelemetrySink();
+ const fakeSession = new FakeAgentSession();
+
+ installAgentTelemetry(fakeSession as unknown as AgentSession, {
+ agentDir: "/not-used",
+ settingsManager: SettingsManager.inMemory(),
+ sink,
+ });
+
+ const failed = assistantMessage({ stopReason: "error", errorMessage: "rate limit" });
+ const succeeded = assistantMessage();
+ fakeSession.emit({
+ type: "session_action_update",
+ actions: { queuedCount: 0, steering: [], followUps: [], active: { kind: "turn", phase: "running" } },
+ });
+ fakeSession.emit({ type: "agent_start" });
+ fakeSession.emit({ type: "message_end", message: failed });
+ fakeSession.emit({ type: "agent_end", messages: [failed] });
+ fakeSession.emit({
+ type: "auto_retry_start",
+ attempt: 1,
+ maxAttempts: 3,
+ delayMs: 100,
+ errorMessage: "rate limit",
+ });
+ fakeSession.emit({ type: "agent_start" });
+ fakeSession.emit({ type: "message_end", message: succeeded });
+ fakeSession.emit({ type: "agent_end", messages: [succeeded] });
+ fakeSession.emit({ type: "session_action_update", actions: { queuedCount: 0, steering: [], followUps: [] } });
+
+ const runs = sink.events.filter((event) => event.name === "agent run completed");
+ expect(runs).toHaveLength(1);
+ expect(runs[0].properties).toMatchObject({ outcome: "success", retry_count: 1, model_call_count: 2 });
+ });
+
+ it("awaits the final telemetry flush during async session disposal", async () => {
+ vi.stubEnv("PRIME_AGENT_TELEMETRY", "1");
+ const sink = new FakeTelemetrySink();
+ const fakeSession = new FakeAgentSession();
+ let releaseFlush: () => void = () => {};
+ const flushGate = new Promise<void>((resolve) => {
+ releaseFlush = resolve;
+ });
+ let flushStarted = false;
+ vi.spyOn(sink, "flush").mockImplementation(async () => {
+ flushStarted = true;
+ await flushGate;
+ });
+
+ installAgentTelemetry(fakeSession as unknown as AgentSession, {
+ agentDir: "/not-used",
+ settingsManager: SettingsManager.inMemory(),
+ sink,
+ });
+
+ let disposed = false;
+ const disposal = fakeSession.disposeAsync().then(() => {
+ disposed = true;
+ });
+ await vi.waitFor(() => expect(flushStarted).toBe(true));
+ expect(disposed).toBe(false);
+ releaseFlush();
+ await disposal;
+ expect(disposed).toBe(true);
+ });
+});