Skip to content

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

Rust

send usage telemetry from the rust build (#3288)

kt7f62d76873df
diff --git a/.cargo/config.toml b/.cargo/config.toml
new file mode 100644
index 0000000000..3f81354a6d
--- /dev/null
+++ b/.cargo/config.toml
@@ -0,0 +1,5 @@
+# Every cargo test/run in this repo, any profile and any crate, opts out of
+# product telemetry. Cargo's [env] never overrides a variable that is
+# already set, so a test that needs it can still set its own value.
+[env]
+DO_NOT_TRACK = "1"
diff --git a/Cargo.lock b/Cargo.lock
index 2940a0a989..a86a1dbde4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1371,6 +1371,7 @@ version = "0.9.8"
dependencies = [
"anyhow",
"reqwest",
+ "rustix 1.1.4",
"serde",
"serde_json",
"tempfile",
diff --git a/crates/pa-cli/src/client_settings.rs b/crates/pa-cli/src/client_settings.rs
index ea75bf2c41..6ad93ec760 100644
--- a/crates/pa-cli/src/client_settings.rs
+++ b/crates/pa-cli/src/client_settings.rs
@@ -227,6 +227,33 @@ impl ClientSettings for CliClientSettings {
.wire_name()
.to_string()
}
+
+ fn telemetry_status(&self) -> String {
+ pa_core::session_engine::telemetry::telemetry_status_text(&self.manager(), &self.agent_dir)
+ }
+
+ fn set_telemetry_enabled(&self, enabled: bool) -> Result<String> {
+ pa_core::session_engine::telemetry::set_telemetry_enabled_text(
+ &mut self.manager(),
+ &self.agent_dir,
+ enabled,
+ )
+ }
+
+ fn telemetry_notice_due(&self) -> bool {
+ // TS agent-session-services: telemetry enabled, onboarding
+ // already shown (a first interactive launch belongs to the
+ // onboarding screen; the notice surfaces on the next launch),
+ // and the notice not yet shown.
+ let manager = self.manager();
+ pa_core::session_engine::telemetry::telemetry_switch(&manager).enabled()
+ && manager.get_onboarding_shown()
+ && !manager.get_telemetry_notice_shown()
+ }
+
+ fn set_telemetry_notice_shown(&self) -> Result<()> {
+ self.manager().set_telemetry_notice_shown(true)
+ }
}
#[cfg(test)]
diff --git a/crates/pa-cli/src/command_registry.rs b/crates/pa-cli/src/command_registry.rs
index 6fed799f95..c097c2472e 100644
--- a/crates/pa-cli/src/command_registry.rs
+++ b/crates/pa-cli/src/command_registry.rs
@@ -116,6 +116,14 @@ pub const COMMAND_SPECS: &[CommandSpec] = &[
"status [--json]",
"Show background service status",
),
+ CommandSpec::new(
+ &["telemetry"],
+ "telemetry [status|on|off]",
+ "Show or change usage telemetry",
+ )
+ .description(
+ "Prime Agent sends pseudonymous usage and performance metrics, never prompts, responses, tool content, file paths, or repository data. status (the default) shows whether telemetry is on and why, where it sends, and the installation id; on and off save the choice in settings.",
+ ),
CommandSpec::new(
&["doctor"],
"doctor [--fix] [--json]",
diff --git a/crates/pa-cli/src/interactive_mode.rs b/crates/pa-cli/src/interactive_mode.rs
index ce34b7df0d..7b112418e6 100644
--- a/crates/pa-cli/src/interactive_mode.rs
+++ b/crates/pa-cli/src/interactive_mode.rs
@@ -65,27 +65,11 @@ pub fn run_interactive_mode(options: &RunOptions) -> Result<i32> {
)),
)?;
let configuration_load_ms = configuration_load_started.elapsed().as_millis() as u64;
- // Telemetry disclosure (TS agent-session-services): once per
- // installation, only after onboarding marked itself shown (a first
- // interactive run belongs to the onboarding screen; the notice surfaces
- // on the next launch). Divergence from TS: the TS product renders it as
- // (a session diagnostic in the TUI; the Rust build prints it to stderr
- // before the TUI starts, which keeps the same text visible without a
- // daemon-side diagnostics round-trip).
- if !tui_options.telemetry_disabled.unwrap_or(false) {
- let mut settings = pa_core::settings::SettingsManager::create(
- &options.config.cwd,
- &options.config.agent_dir,
- );
- if settings.get_onboarding_shown() && !settings.get_telemetry_notice_shown() {
- eprintln!(
- "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."
- );
- if let Err(error) = settings.set_telemetry_notice_shown(true) {
- eprintln!("Warning: could not persist the telemetry notice: {error}");
- }
- }
- }
+ // The telemetry disclosure renders inside the TUI (TS
+ // agent-session-services' session diagnostic): the interactive
+ // attach pushes the info row once per installation, deferred behind
+ // onboarding — a pre-TUI stderr print would be hidden by the alt
+ // screen.
let runtime = tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()
@@ -563,8 +547,17 @@ fn build_tui_options(
// gates the completion marker, and the auth handle serves the
// not-ready branch's sign-in steps.
onboarding,
- // Only Some(true) rides the wire (TS `telemetryDisabled`).
- telemetry_disabled: config.telemetry_disabled.then_some(true),
+ // Only Some(true) rides the wire (TS `telemetryDisabled`), and only
+ // for an environment opt-out: a settings opt-out stays the live
+ // switch the session's client re-reads, so `/telemetry on`
+ // resumes the running session instead of waiting for a new one.
+ telemetry_disabled: matches!(
+ pa_core::session_engine::telemetry::telemetry_switch(
+ &pa_core::settings::SettingsManager::create(&config.cwd, &config.agent_dir)
+ ),
+ pa_core::session_engine::telemetry::TelemetrySwitch::Env { enabled: false, .. }
+ )
+ .then_some(true),
// `/mcp login` / `/mcp logout`: the client-side auth flows run in
// this process (the TS interactive client's placement) and persist
// through the shared auth store the daemon's sessions read.
@@ -588,10 +581,10 @@ fn build_tui_options(
// `/login` + `/logout`: the provider auth flows (the API-key store,
// the MCP device flow, the provider catalog).
provider_auth: Some(provider_auth),
- telemetry: Some(std::sync::Arc::new(CliInteractionTelemetry {
- cwd: config.cwd.clone(),
- agent_dir: config.agent_dir.clone(),
- })),
+ telemetry: Some(std::sync::Arc::new(CliInteractionTelemetry::new(
+ config.cwd.clone(),
+ config.agent_dir.clone(),
+ ))),
keybindings,
// The process-wide prompt stash store (TS `ClientPromptStashStore`
// lives in `main.ts`'s invocation scope): one store per process, so
diff --git a/crates/pa-cli/src/interactive_mode/onboarding.rs b/crates/pa-cli/src/interactive_mode/onboarding.rs
index be92c6c359..5f4725c983 100644
--- a/crates/pa-cli/src/interactive_mode/onboarding.rs
+++ b/crates/pa-cli/src/interactive_mode/onboarding.rs
@@ -145,6 +145,54 @@ pub(super) struct SettingsOnboardingSink {
/// The startup-model probe (the completion telemetry's category
/// columns: the resolved startup model and its auth source).
pub(super) probe: StartupModelProbe,
+ /// The success outcome was reported (the completion marker ran).
+ pub(super) completion_reported: std::sync::atomic::AtomicBool,
+}
+
+impl SettingsOnboardingSink {
+ /// The `onboarding completed` properties (TS
+ /// `captureOnboardingCompleted`): the auth and provider categories read
+ /// the resolved startup model (`getCurrentModel` + its auth status).
+ fn completed_properties(&self, outcome: &str, duration_ms: u64) -> pa_telemetry::Properties {
+ let mut properties = pa_telemetry::base_properties("interactive");
+ properties.set("duration_ms", serde_json::Value::from(duration_ms));
+ properties.set("outcome", serde_json::Value::from(outcome));
+ let (auth_category, provider_category) = self.probe.telemetry_categories();
+ properties.set("auth_category", serde_json::Value::from(auth_category));
+ properties.set(
+ "provider_category",
+ serde_json::Value::from(provider_category),
+ );
+ properties.set(
+ "onboarding_id",
+ serde_json::Value::from(self.onboarding_id.as_str()),
+ );
+ properties
+ }
+
+ /// Track `onboarding completed` with an unfinished `outcome` on a fresh
+ /// client and return it, or `None` when nothing is reported.
+ pub(super) fn track_incomplete(&self, outcome: &str) -> Option<pa_telemetry::TelemetryClient> {
+ // A completed flow whose marker failed to persist already reported
+ // its success.
+ if self
+ .completion_reported
+ .load(std::sync::atomic::Ordering::SeqCst)
+ {
+ return None;
+ }
+ let settings = pa_core::settings::SettingsManager::create(&self.cwd, &self.agent_dir);
+ if crate::mode::telemetry_disabled(&settings) {
+ return None;
+ }
+ let client = pa_core::session_engine::telemetry::build_client(&settings, &self.agent_dir);
+ let duration_ms = self.created_at.elapsed().as_millis() as u64;
+ client.track(
+ "onboarding completed",
+ self.completed_properties(outcome, duration_ms),
+ );
+ Some(client)
+ }
}
impl pa_tui::interactive::OnboardingSink for SettingsOnboardingSink {
@@ -166,29 +214,19 @@ impl pa_tui::interactive::OnboardingSink for SettingsOnboardingSink {
fn mark_onboarding_complete(&self) -> Result<()> {
let mut settings = pa_core::settings::SettingsManager::create(&self.cwd, &self.agent_dir);
settings.set_onboarding_shown(true)?;
- // `onboarding completed` (schema v1): the marker writes only on a
- // completed flow, so the outcome is always success; the auth and
- // provider categories read the resolved startup model (TS
- // `captureOnboardingCompleted`'s `getCurrentModel` + auth status
- // columns). Best-effort like all telemetry.
+ // `onboarding completed` (schema v1) with the success outcome: the
+ // marker writes only on a completed flow. Best-effort like all
+ // telemetry.
+ self.completion_reported
+ .store(true, std::sync::atomic::Ordering::SeqCst);
if !crate::mode::telemetry_disabled(&settings) {
let client =
pa_core::session_engine::telemetry::build_client(&settings, &self.agent_dir);
let duration_ms = self.created_at.elapsed().as_millis() as u64;
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("duration_ms", serde_json::Value::from(duration_ms));
- properties.set("outcome", serde_json::Value::from("success"));
- let (auth_category, provider_category) = self.probe.telemetry_categories();
- properties.set("auth_category", serde_json::Value::from(auth_category));
- properties.set(
- "provider_category",
- serde_json::Value::from(provider_category),
- );
- properties.set(
- "onboarding_id",
- serde_json::Value::from(self.onboarding_id.as_str()),
+ client.track(
+ "onboarding completed",
+ self.completed_properties("success", duration_ms),
);
- client.track("onboarding completed", properties);
// The `exit` stage (#2117 `onboarding stage`): the completion
// marker's own stage event, paired by `onboarding_id`. The
// final flush rides the client's drop (the worker drains once
@@ -226,6 +264,21 @@ impl pa_tui::interactive::OnboardingSink for SettingsOnboardingSink {
}
Ok(())
}
+
+ fn onboarding_incomplete(
+ &self,
+ outcome: &'static str,
+ ) -> std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send + '_>> {
+ let client = self.track_incomplete(outcome);
+ Box::pin(async move {
+ // The exit keys quit the app right after: wait out the final
+ // flush (bounded by the sink's request timeout) so the runtime
+ // teardown cannot abort the worker before it delivers.
+ if let Some(client) = client {
+ let _ = client.shutdown().await;
+ }
+ })
+ }
}
/// TS `shouldRunOnboarding`: first launch is defined by the settings flag
@@ -307,6 +360,7 @@ pub(super) fn onboarding_task(
created_at: std::time::Instant::now(),
onboarding_id,
ready_emitted: std::sync::atomic::AtomicBool::new(mount_ready),
+ completion_reported: std::sync::atomic::AtomicBool::new(false),
probe,
}),
model_ready: std::sync::Arc::new(move || readiness_probe.resolve().1),
diff --git a/crates/pa-cli/src/interactive_mode/telemetry.rs b/crates/pa-cli/src/interactive_mode/telemetry.rs
index 87a1fe546a..e1bd908222 100644
--- a/crates/pa-cli/src/interactive_mode/telemetry.rs
+++ b/crates/pa-cli/src/interactive_mode/telemetry.rs
@@ -1,22 +1,51 @@
-//! The interaction-telemetry concern (moved with its concern): the
-//! one-shot client wrapper and the adoption events the pa-tui
-//! interactive loop reports through the `InteractionTelemetry` trait.
+//! The interaction-telemetry concern: the pa-tui interactive loop reports
+//! through the `InteractionTelemetry` trait. Interactions only count into
+//! the session run's counters, which ride its one `tui exit` event. Two
+//! standalone events remain their own (TS parity, plus one upstream
+//! addition): `agent command used`, and `tui ipython bash rendered` —
+//! the settled-shell-cell metric upstream #3307 tracks per render, kept
+//! intact from main.
+
+use std::collections::BTreeMap;
+use std::sync::Mutex;
use super::{Future, PathBuf, Pin};
-/// `tui scroll used` / `tui exit` adoption telemetry: a one-shot client per
-/// event, tracked and flushed at the emission point (the `startup`-event
-/// pattern). Telemetry must never fail the session: opt-out or a broken
-/// install id drops the event.
+/// The interactive client's telemetry: per-session-run adoption counters
+/// flushed with `tui exit`, plus the two standalone events — the TS
+/// `agent command used`, and the upstream #3307 `tui ipython bash
+/// rendered` — each on a one-shot client. Telemetry must never fail the
+/// session: opt-out or a broken install id drops the events.
pub(super) struct CliInteractionTelemetry {
pub(super) cwd: PathBuf,
pub(super) agent_dir: PathBuf,
+ pub(super) counters: Mutex<TuiCounters>,
+}
+
+/// The session run's adoption counters (`tui_*_count`, `feature_*_count`,
+/// `input_*`) and its terminal capability flags.
+#[derive(Default)]
+pub(super) struct TuiCounters {
+ counts: BTreeMap<String, u64>,
+ flags: BTreeMap<&'static str, bool>,
}
impl CliInteractionTelemetry {
+ pub(super) fn new(cwd: PathBuf, agent_dir: PathBuf) -> Self {
+ Self {
+ cwd,
+ agent_dir,
+ counters: Mutex::default(),
+ }
+ }
+
+ fn settings(&self) -> pa_core::settings::SettingsManager {
+ pa_core::settings::SettingsManager::create(&self.cwd, &self.agent_dir)
+ }
+
/// A one-shot client, or `None` when telemetry is opted out.
fn client(&self) -> Option<pa_telemetry::TelemetryClient> {
- let settings = pa_core::settings::SettingsManager::create(&self.cwd, &self.agent_dir);
+ let settings = self.settings();
if crate::mode::telemetry_disabled(&settings) {
return None;
}
@@ -25,6 +54,24 @@ impl CliInteractionTelemetry {
&self.agent_dir,
))
}
+
+ /// Count only while telemetry is on, so turning it on later never
+ /// sends what happened while it was off.
+ fn with(&self, update: impl FnOnce(&mut TuiCounters)) {
+ if crate::mode::telemetry_disabled(&self.settings()) {
+ return;
+ }
+ update(
+ &mut self
+ .counters
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner),
+ );
+ }
+
+ fn count(&self, key: &'static str) {
+ self.with(|counters| *counters.counts.entry(key.to_string()).or_default() += 1);
+ }
}
impl pa_tui::interactive::InteractionTelemetry for CliInteractionTelemetry {
@@ -32,129 +79,79 @@ impl pa_tui::interactive::InteractionTelemetry for CliInteractionTelemetry {
&self,
feature: &'static str,
outcome: &'static str,
- duration_ms: Option<u64>,
+ _duration_ms: Option<u64>,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- pa_telemetry::AgentFeatureOutcome {
- feature_id: uuid::Uuid::new_v4().to_string(),
- feature_name: feature,
- outcome,
- duration_ms,
- configuration_choice: None,
- }
- .track(&client);
- })
+ if let Some(key) = pa_telemetry::feature_outcome_key(feature, outcome) {
+ self.with(|counters| *counters.counts.entry(key).or_default() += 1);
+ }
+ Box::pin(std::future::ready(()))
}
fn input_stage(
&self,
- input_id: String,
+ _input_id: String,
stage: &'static str,
- outcome: &'static str,
+ _outcome: &'static str,
duration_ms: u64,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- pa_telemetry::AgentInputStage {
- input_id,
- stage,
- outcome,
- duration_ms: Some(duration_ms),
- timing_origin: Some("ui_input"),
- }
- .track(&client);
- })
+ if let Some(prefix) = pa_telemetry::input_stage_key(stage) {
+ self.with(|counters| {
+ *counters
+ .counts
+ .entry(format!("{prefix}_count"))
+ .or_default() += 1;
+ let max = counters
+ .counts
+ .entry(format!("{prefix}_max_ms"))
+ .or_default();
+ *max = (*max).max(duration_ms);
+ });
+ }
+ Box::pin(std::future::ready(()))
}
fn bash_shortcut_used(
&self,
- excluded: bool,
- side_conversation: bool,
+ _excluded: bool,
+ _side_conversation: bool,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("excluded", serde_json::Value::from(excluded));
- properties.set(
- "side_conversation",
- serde_json::Value::from(side_conversation),
- );
- client.track("tui bash shortcut used", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_bash_shortcut_count");
+ Box::pin(std::future::ready(()))
}
fn bash_bang_executed(
&self,
- duration_bucket: &'static str,
- exit_class: &'static str,
+ _duration_bucket: &'static str,
+ _exit_class: &'static str,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("duration_bucket", serde_json::Value::from(duration_bucket));
- properties.set("exit_class", serde_json::Value::from(exit_class));
- client.track("tui bash bang executed", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_bash_bang_count");
+ Box::pin(std::future::ready(()))
}
fn prompt_stash(
&self,
- action: &'static str,
- had_images: bool,
+ _action: &'static str,
+ _had_images: bool,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("action", serde_json::Value::from(action));
- properties.set("had_images", serde_json::Value::from(had_images));
- client.track("tui prompt stash", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_prompt_stash_count");
+ Box::pin(std::future::ready(()))
}
fn external_editor_used(
&self,
- outcome: &'static str,
+ _outcome: &'static str,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("outcome", serde_json::Value::from(outcome));
- client.track("tui external editor used", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_external_editor_count");
+ Box::pin(std::future::ready(()))
}
fn scoped_models_used(
&self,
- action: &'static str,
- scoped: bool,
+ _action: &'static str,
+ _scoped: bool,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("action", serde_json::Value::from(action));
- properties.set("scoped", serde_json::Value::from(scoped));
- client.track("tui scoped models used", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_scoped_models_count");
+ Box::pin(std::future::ready(()))
}
fn ipython_bash_rendered(
@@ -178,176 +175,86 @@ impl pa_tui::interactive::InteractionTelemetry for CliInteractionTelemetry {
fn scroll_used(
&self,
- action: &'static str,
- resumed_following: bool,
+ _action: &'static str,
+ _resumed_following: bool,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("action", serde_json::Value::from(action));
- properties.set(
- "resumed_following",
- serde_json::Value::from(resumed_following),
- );
- client.track("tui scroll used", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_scroll_count");
+ Box::pin(std::future::ready(()))
}
- fn selection_used(&self, lines: usize) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("lines", serde_json::Value::from(lines as u64));
- client.track("tui selection used", properties);
- let _ = client.shutdown().await;
- })
+ fn selection_used(&self, _lines: usize) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ self.count("tui_selection_count");
+ Box::pin(std::future::ready(()))
}
- fn click_used(&self, surface: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("surface", serde_json::Value::from(surface));
- client.track("tui click used", properties);
- let _ = client.shutdown().await;
- })
+
+ fn click_used(&self, _surface: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ self.count("tui_click_count");
+ Box::pin(std::future::ready(()))
}
- fn client_exit(
+
+ fn activity_opened(
&self,
- reason: &'static str,
- turn_active: bool,
+ _kind: &'static str,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("exit_reason", serde_json::Value::from(reason));
- properties.set("turn_active", serde_json::Value::from(turn_active));
- client.track("tui exit", properties);
- let _ = client.shutdown().await;
- })
- }
-
- fn activity_opened(&self, kind: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("kind", serde_json::Value::from(kind));
- client.track("tui activity opened", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_activity_open_count");
+ Box::pin(std::future::ready(()))
}
fn menu_opened(
&self,
- menu: &'static str,
- source: &'static str,
+ _menu: &'static str,
+ _source: &'static str,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("menu", serde_json::Value::from(menu));
- properties.set("source", serde_json::Value::from(source));
- client.track("tui menu opened", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_menu_open_count");
+ Box::pin(std::future::ready(()))
}
fn subagents_view_opened(
&self,
- children_total: u64,
+ _children_total: u64,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("children_total", serde_json::Value::from(children_total));
- client.track("tui subagents open", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_subagents_open_count");
+ Box::pin(std::future::ready(()))
}
- fn scoped_agent_created(&self, depth: u32) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("depth", serde_json::Value::from(u64::from(depth)));
- client.track("tui agents new scoped", properties);
- let _ = client.shutdown().await;
- })
+ fn scoped_agent_created(&self, _depth: u32) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ self.count("tui_scoped_agent_count");
+ Box::pin(std::future::ready(()))
}
- fn command_used(&self, command: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- // `agent command used` (TS `captureAgentCommandUsed`): builtin
- // client commands report from the client; session commands report
- // through the session telemetry, so the two seams never double-emit.
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("command_name", serde_json::Value::from(command));
- client.track("agent command used", properties);
- let _ = client.shutdown().await;
- })
+ fn image_pasted(&self, _mime_type: &str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ self.count("tui_image_paste_count");
+ Box::pin(std::future::ready(()))
}
- fn image_pasted(&self, mime_type: &str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- // The returned future borrows only `self`, so the mime type rides
- // inside it by value.
- let mime_type = mime_type.to_string();
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("mime_type", serde_json::Value::from(mime_type));
- client.track("tui image pasted", properties);
- let _ = client.shutdown().await;
- })
+ fn queued_input(
+ &self,
+ _lane: &'static str,
+ _steering_mode: String,
+ ) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ self.count("tui_input_queued_count");
+ Box::pin(std::future::ready(()))
}
- fn queued_input(
+ fn queue_edited(&self, _action: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ self.count("tui_queue_edit_count");
+ Box::pin(std::future::ready(()))
+ }
+
+ fn suspend_used(
&self,
- lane: &'static str,
- steering_mode: String,
+ _outcome: &'static str,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("lane", serde_json::Value::from(lane));
- properties.set("steering_mode", serde_json::Value::from(steering_mode));
- client.track("tui input queued", properties);
- let _ = client.shutdown().await;
- })
+ self.count("tui_suspend_count");
+ Box::pin(std::future::ready(()))
}
- fn queue_edited(&self, action: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("action", serde_json::Value::from(action));
- client.track("tui queue edited", properties);
- let _ = client.shutdown().await;
- })
+ fn agents_view_action(
+ &self,
+ _action: &'static str,
+ ) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ self.count("tui_agents_action_count");
+ Box::pin(std::future::ready(()))
}
fn enhanced_keys(
@@ -355,57 +262,142 @@ impl pa_tui::interactive::InteractionTelemetry for CliInteractionTelemetry {
kitty: bool,
modify_other_keys: bool,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("kitty", serde_json::Value::from(kitty));
- properties.set(
- "modify_other_keys",
- serde_json::Value::from(modify_other_keys),
- );
- client.track("tui enhanced keys", properties);
- let _ = client.shutdown().await;
- })
+ self.with(|counters| {
+ counters.flags.insert("tui_enhanced_keys_kitty", kitty);
+ counters
+ .flags
+ .insert("tui_enhanced_keys_modify_other_keys", modify_other_keys);
+ });
+ Box::pin(std::future::ready(()))
}
fn hyperlinks_active(&self, enabled: bool) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
- Box::pin(async move {
- let Some(client) = self.client() else {
- return;
- };
- let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("enabled", serde_json::Value::from(enabled));
- client.track("tui hyperlinks", properties);
- let _ = client.shutdown().await;
- })
+ self.with(|counters| {
+ counters.flags.insert("tui_hyperlinks_enabled", enabled);
+ });
+ Box::pin(std::future::ready(()))
}
- fn suspend_used(&self, outcome: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ fn client_exit(
+ &self,
+ reason: &'static str,
+ turn_active: bool,
+ ) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
Box::pin(async move {
+ // Every session run of the process shares these counters (the
+ // agents view hands one telemetry handle to each session it
+ // opens), so each `tui exit` takes what its run counted.
+ let counters = std::mem::take(
+ &mut *self
+ .counters
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner),
+ );
let Some(client) = self.client() else {
return;
};
let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("outcome", serde_json::Value::from(outcome));
- client.track("tui suspend used", properties);
+ properties.set("exit_reason", serde_json::Value::from(reason));
+ properties.set("turn_active", serde_json::Value::from(turn_active));
+ for (key, count) in &counters.counts {
+ properties.set(key, serde_json::Value::from(*count));
+ }
+ for (key, flag) in &counters.flags {
+ properties.set(key, serde_json::Value::from(*flag));
+ }
+ client.track("tui exit", properties);
let _ = client.shutdown().await;
})
}
- fn agents_view_action(
- &self,
- action: &'static str,
- ) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ fn command_used(&self, command: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
+ // `agent command used` (TS `captureAgentCommandUsed`): every
+ // submitted builtin reports from the client, session commands
+ // included (the session engine reports none).
Box::pin(async move {
let Some(client) = self.client() else {
return;
};
let mut properties = pa_telemetry::base_properties("interactive");
- properties.set("action", serde_json::Value::from(action));
- client.track("tui agents action", properties);
+ properties.set("command_name", serde_json::Value::from(command));
+ client.track("agent command used", properties);
let _ = client.shutdown().await;
})
}
}
+
+#[cfg(test)]
+mod tests {
+ use pa_tui::interactive::InteractionTelemetry as _;
+
+ use super::CliInteractionTelemetry;
+
+ /// Interactions while telemetry is off never count, so a later
+ /// `/telemetry on` cannot send them with `tui exit`.
+ #[test]
+ fn interactions_while_off_never_count() {
+ crate::mode::tests::with_clean_telemetry_env(|| {
+ futures::executor::block_on(count_interactions_while_off());
+ });
+ }
+
+ async fn count_interactions_while_off() {
+ let dir = tempfile::TempDir::new().unwrap();
+ let agent_dir = dir.path().join("agent");
+ pa_core::settings::SettingsManager::create(dir.path(), &agent_dir)
+ .set_telemetry_enabled(false)
+ .unwrap();
+ let telemetry = CliInteractionTelemetry::new(dir.path().to_path_buf(), agent_dir);
+ telemetry.scroll_used("page", false).await;
+ telemetry
+ .input_stage(String::new(), "received", "ok", 5)
+ .await;
+ telemetry.hyperlinks_active(true).await;
+ {
+ let counters = telemetry.counters.lock().unwrap();
+ assert!(counters.counts.is_empty());
+ assert!(counters.flags.is_empty());
+ }
+ pa_core::settings::SettingsManager::create(dir.path(), dir.path().join("agent"))
+ .set_telemetry_enabled(true)
+ .unwrap();
+ telemetry.scroll_used("page", false).await;
+ let counters = telemetry.counters.lock().unwrap();
+ assert_eq!(counters.counts.get("tui_scroll_count"), Some(&1));
+ }
+
+ /// The agents view shares one telemetry handle across the sessions it
+ /// opens: each `tui exit` reports only its own run's interactions.
+ #[test]
+ fn each_tui_exit_reports_only_its_own_run() {
+ crate::mode::tests::with_clean_telemetry_env(|| {
+ tokio::runtime::Runtime::new()
+ .unwrap()
+ .block_on(report_each_run_once());
+ });
+ }
+
+ async fn report_each_run_once() {
+ let dir = tempfile::TempDir::new().unwrap();
+ let agent_dir = dir.path().join("agent");
+ std::fs::create_dir_all(&agent_dir).unwrap();
+ let telemetry = CliInteractionTelemetry::new(dir.path().to_path_buf(), agent_dir.clone());
+ telemetry.scroll_used("page", false).await;
+ telemetry.hyperlinks_active(true).await;
+ telemetry.client_exit("session_request", false).await;
+ telemetry.client_exit("ctrl_d", false).await;
+ let mirror = std::fs::read_to_string(agent_dir.join("telemetry.jsonl")).unwrap();
+ let exits: Vec<serde_json::Value> = mirror
+ .lines()
+ .map(|line| serde_json::from_str(line).unwrap())
+ .filter(|event: &serde_json::Value| event["name"] == "tui exit")
+ .collect();
+ assert_eq!(exits.len(), 2);
+ assert_eq!(exits[0]["properties"]["tui_scroll_count"], 1);
+ assert_eq!(exits[0]["properties"]["tui_hyperlinks_enabled"], true);
+ assert!(exits[1]["properties"].get("tui_scroll_count").is_none());
+ assert!(exits[1]["properties"]
+ .get("tui_hyperlinks_enabled")
+ .is_none());
+ }
+}
diff --git a/crates/pa-cli/src/interactive_mode/tests.rs b/crates/pa-cli/src/interactive_mode/tests.rs
index 405c6b3ad5..2624ace0e8 100644
--- a/crates/pa-cli/src/interactive_mode/tests.rs
+++ b/crates/pa-cli/src/interactive_mode/tests.rs
@@ -351,6 +351,7 @@ fn settings_sink_completes_a_provisioned_home_without_touching_the_choice() {
created_at: std::time::Instant::now(),
onboarding_id: uuid::Uuid::new_v4().to_string(),
ready_emitted: std::sync::atomic::AtomicBool::new(false),
+ completion_reported: std::sync::atomic::AtomicBool::new(false),
probe: StartupModelProbe {
cwd: dir.path().to_path_buf(),
agent_dir: agent_dir.clone(),
@@ -381,6 +382,58 @@ fn settings_sink_completes_a_provisioned_home_without_touching_the_choice() {
);
}
+/// A flow that ran but did not complete reports `onboarding completed`
+/// with the `aborted` outcome (TS `runStartupOnboarding`'s `finally`), and
+/// a completed flow never reports a second, aborted outcome. Telemetry is
+/// on for this test (the repo's `cargo test` env opts out).
+#[test]
+fn settings_sink_reports_an_aborted_flow_once() {
+ crate::mode::tests::with_clean_telemetry_env(|| {
+ tokio::runtime::Runtime::new()
+ .unwrap()
+ .block_on(report_an_aborted_flow_once());
+ });
+}
+
+async fn report_an_aborted_flow_once() {
+ let dir = tempfile::TempDir::new().expect("temp dir");
+ let agent_dir = dir.path().join("agent");
+ std::fs::create_dir_all(&agent_dir).expect("agent dir");
+ let sink = SettingsOnboardingSink {
+ cwd: dir.path().to_path_buf(),
+ agent_dir: agent_dir.clone(),
+ created_at: std::time::Instant::now(),
+ onboarding_id: uuid::Uuid::new_v4().to_string(),
+ ready_emitted: std::sync::atomic::AtomicBool::new(false),
+ completion_reported: std::sync::atomic::AtomicBool::new(false),
+ probe: StartupModelProbe {
+ cwd: dir.path().to_path_buf(),
+ agent_dir: agent_dir.clone(),
+ cli_provider: None,
+ cli_model: None,
+ models: None,
+ is_continuing: false,
+ api_key: None,
+ },
+ };
+ // The sink's own report resolves only once the event is delivered.
+ pa_tui::interactive::OnboardingSink::onboarding_incomplete(&sink, "aborted").await;
+ let mirror = std::fs::read_to_string(agent_dir.join("telemetry.jsonl")).unwrap();
+ let lines: Vec<&str> = mirror.lines().collect();
+ assert_eq!(lines.len(), 1);
+ let event: serde_json::Value = serde_json::from_str(lines[0]).unwrap();
+ assert_eq!(event["name"], "onboarding completed");
+ assert_eq!(event["properties"]["outcome"], "aborted");
+ assert_eq!(event["properties"]["execution_mode"], "interactive");
+
+ sink.completion_reported
+ .store(true, std::sync::atomic::Ordering::SeqCst);
+ assert!(
+ sink.track_incomplete("aborted").is_none(),
+ "a reported completion never adds an aborted outcome"
+ );
+}
+
/// A fresh home (no choice written) is the one home the question still
/// mounts for — the opt-in moment: the flow's `Share` answer persists
/// beside the completion flag, and both read back through the next
@@ -401,6 +454,7 @@ fn settings_sink_persists_the_fresh_home_answer_with_the_flag() {
created_at: std::time::Instant::now(),
onboarding_id: uuid::Uuid::new_v4().to_string(),
ready_emitted: std::sync::atomic::AtomicBool::new(false),
+ completion_reported: std::sync::atomic::AtomicBool::new(false),
probe: StartupModelProbe {
cwd: dir.path().to_path_buf(),
agent_dir: agent_dir.clone(),
diff --git a/crates/pa-cli/src/lib.rs b/crates/pa-cli/src/lib.rs
index 828ed8e2eb..c79aaf37e3 100644
--- a/crates/pa-cli/src/lib.rs
+++ b/crates/pa-cli/src/lib.rs
@@ -57,6 +57,7 @@ pub(crate) mod self_update;
pub(crate) mod session_export;
pub(crate) mod sessions_table_format;
pub(crate) mod subscription_login;
+pub(crate) mod telemetry_notice;
pub(crate) mod traces_login;
/// The runtime boundary: everything a mode-runner crate implements to plug
@@ -93,6 +94,10 @@ pub fn main_with_runtime(args: &[String], runtime: &dyn mode::Runtime) -> i32 {
fn main_impl(args: &[String], runtime: &dyn mode::Runtime) -> Result<i32, String> {
use std::io::IsTerminal;
+ // Telemetry reports the version `--version` prints: the beta channel
+ // restamps only the packaged manifest, never the compiled-in version.
+ pa_telemetry::set_version(crate::config::version());
+
let offline_mode = args.iter().any(|arg| arg == "--offline")
|| crate::config::is_truthy_env_flag(
std::env::var(crate::config::ENV_OFFLINE).ok().as_deref(),
diff --git a/crates/pa-cli/src/mode.rs b/crates/pa-cli/src/mode.rs
index 979dd8a931..b24e995052 100644
--- a/crates/pa-cli/src/mode.rs
+++ b/crates/pa-cli/src/mode.rs
@@ -207,10 +207,7 @@ impl Runtime for UnavailableRuntime {
/// `PRIME_AGENT_TELEMETRY`), then the settings AND. Returns true when
/// telemetry is disabled for this invocation.
pub fn telemetry_disabled(settings: &pa_core::settings::SettingsManager) -> bool {
- match pa_telemetry::env_telemetry_override() {
- Some(enabled) => !enabled,
- None => !settings.get_telemetry_enabled(),
- }
+ !pa_core::session_engine::telemetry::telemetry_switch(settings).enabled()
}
/// Build the runtime config from parsed args, mirroring `runtimeConfigFromArgs`.
@@ -283,13 +280,18 @@ pub fn runtime_config_from_args(
}
#[cfg(test)]
-mod tests {
+pub(crate) mod tests {
use super::*;
/// Run the body with the three telemetry env overrides held at a known
/// state and restored after (an assertion panic must never leave the
/// process env mutated, and a host-exported opt-out must not bleed in).
- fn with_clean_telemetry_env(body: impl FnOnce() + std::panic::UnwindSafe) {
+ pub(crate) fn with_clean_telemetry_env(body: impl FnOnce() + std::panic::UnwindSafe) {
+ // The env is process-wide: tests that rewrite it take turns.
+ static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+ let _guard = LOCK
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
let vars = ["PRIME_AGENT_TELEMETRY", "DO_NOT_TRACK", "PI_OFFLINE"];
let saved: Vec<(String, Option<String>)> = vars
.iter()
diff --git a/crates/pa-cli/src/print_boundary/tests.rs b/crates/pa-cli/src/print_boundary/tests.rs
index f52f6e4585..b732b33212 100644
--- a/crates/pa-cli/src/print_boundary/tests.rs
+++ b/crates/pa-cli/src/print_boundary/tests.rs
@@ -76,6 +76,7 @@ async fn faux_engine_with_mock_telemetry(
client,
execution_mode: Some("print".to_string()),
now: None,
+ telemetry_enabled: None,
};
let (engine, dir, model) =
faux_engine_with_telemetry(script, settings, None, Some(telemetry)).await;
diff --git a/crates/pa-cli/src/print_runtime.rs b/crates/pa-cli/src/print_runtime.rs
index 9fa75b6d20..1902f22188 100644
--- a/crates/pa-cli/src/print_runtime.rs
+++ b/crates/pa-cli/src/print_runtime.rs
@@ -101,6 +101,11 @@ fn run_acp_mode(options: &RunOptions) -> Result<i32, String> {
}
async fn acp_mode_main(options: &RunOptions) -> Result<i32, String> {
+ // The disclosure prints on the ACP client's stderr before any
+ // transport starts, so a daemon-attached run shows it too (TS pushes
+ // the daemon-created session's diagnostics to the client; the Rust
+ // stderr surface prints it here without that round-trip).
+ crate::telemetry_notice::print_if_due(&options.config);
// TS `shouldUseDaemonClient` is true for the ACP mode: the daemon is
// the preferred transport, and the in-process engine stays the
// fallback when no daemon can be reached or served.
@@ -108,7 +113,7 @@ async fn acp_mode_main(options: &RunOptions) -> Result<i32, String> {
return Ok(exit_code);
}
let config = &options.config;
- let engine = build_headless_engine_parts(options, "print").await?;
+ let engine = build_headless_engine_parts(options, "acp").await?;
let exit_code = pa_daemon::acp::run_acp_mode(pa_daemon::acp::AcpOptions {
engine: std::sync::Arc::new(engine.engine),
actual_cwd: config.cwd.clone(),
@@ -388,7 +393,9 @@ fn run_print_mode(options: &RunOptions) -> Result<i32, String> {
}
async fn print_mode_main(options: &RunOptions) -> Result<i32, String> {
- let headless = build_headless_engine(options, "print").await?;
+ // `print` or `json`: the telemetry execution mode is the app mode (TS
+ // main.ts `executionMode: appMode`).
+ let headless = build_headless_engine(options, options.app_mode.as_str()).await?;
let engine = std::sync::Arc::new(headless.engine);
// The CLI `--goal` seed (TS constructor seeding): a fresh root branch
// starts the goal and queues its continuation context as the first
@@ -444,6 +451,11 @@ async fn build_headless_engine_parts_with_lease(
options: &RunOptions,
execution_mode: &str,
) -> Result<(HeadlessEngine, Option<pa_daemon::lease::SessionLease>), String> {
+ // Every headless mode discloses immediately (TS main: only the
+ // interactive `deferTelemetryNoticeForOnboarding` holds the notice
+ // back behind onboarding; `--list-models` never reaches this
+ // assembly, matching the TS exit before its diagnostics report).
+ crate::telemetry_notice::print_if_due(&options.config);
let (session_manager, lease) = select_session_manager_with_lease(options)?;
if let Ok(script) = std::env::var("PRIME_AGENT_FAUX_SCRIPT") {
let engine =
@@ -549,6 +561,12 @@ async fn build_headless_engine_with(
client: pa_core::session_engine::telemetry::build_client(&settings, &config.agent_dir),
execution_mode: Some(execution_mode.to_string()),
now: None,
+ telemetry_enabled: Some(
+ pa_core::session_engine::telemetry::telemetry_enabled_switch(
+ &config.cwd,
+ &config.agent_dir,
+ ),
+ ),
}
});
// TS `sdk.ts` seeds the Agent's queue modes from the settings manager
diff --git a/crates/pa-cli/src/public_command.rs b/crates/pa-cli/src/public_command.rs
index 1148a1ce7e..6c6f31ef21 100644
--- a/crates/pa-cli/src/public_command.rs
+++ b/crates/pa-cli/src/public_command.rs
@@ -171,6 +171,7 @@ pub fn handle_public_command(args: &[String]) -> PublicCommandResult {
"schedule" => run_nested_agent_command("schedule", "cron", &rest),
"status" => run_status(&rest),
"doctor" => run_doctor(&rest),
+ "telemetry" => run_telemetry(&rest),
"incident" => run_incident_command(&rest),
"shutdown" => run_shutdown(&rest),
"package" => run_package(&rest),
@@ -481,6 +482,39 @@ fn run_doctor(args: &[String]) -> PublicCommandResult {
handled()
}
+/// `prime-agent telemetry [status|on|off]`: the same report and settings
+/// switch as the `/telemetry` slash command, for the current directory's
+/// settings scope.
+fn run_telemetry(args: &[String]) -> PublicCommandResult {
+ let usage = || fail(format!("Usage: {APP_NAME} telemetry [status|on|off]"), None);
+ if args.len() > 1 {
+ return usage();
+ }
+ let cwd = std::env::current_dir().unwrap_or_default();
+ let agent_dir = crate::config::get_agent_dir();
+ let mut settings = pa_core::settings::SettingsManager::create(&cwd, &agent_dir);
+ let report = match args.first().map(String::as_str) {
+ None | Some("status") => Ok(pa_core::session_engine::telemetry::telemetry_status_text(
+ &settings, &agent_dir,
+ )),
+ Some(choice @ ("on" | "off")) => {
+ pa_core::session_engine::telemetry::set_telemetry_enabled_text(
+ &mut settings,
+ &agent_dir,
+ choice == "on",
+ )
+ }
+ Some(_) => return usage(),
+ };
+ match report {
+ Ok(report) => {
+ println!("{report}");
+ handled()
+ }
+ Err(error) => fail(format!("{error:#}"), None),
+ }
+}
+
/// `prime-agent incident` (TS `runIncidentCommand`): parse the options,
/// resolve the window once, and print the timeline.
fn run_incident_command(args: &[String]) -> PublicCommandResult {
diff --git a/crates/pa-cli/src/telemetry_notice.rs b/crates/pa-cli/src/telemetry_notice.rs
new file mode 100644
index 0000000000..2d944d8525
--- /dev/null
+++ b/crates/pa-cli/src/telemetry_notice.rs
@@ -0,0 +1,69 @@
+//! The first-run telemetry disclosure (TS `agent-session-services`) for
+//! the headless modes: once per installation the fixed text prints to
+//! stderr before a mode's output starts (TS
+//! `deferTelemetryNoticeForOnboarding: executionMode === "interactive"`).
+//! The interactive mode renders the same disclosure inside the TUI as a
+//! session info row (pa-tui's attach) — the alt screen hides a pre-TUI
+//! stderr print, so a stderr notice would never be seen there.
+
+use crate::mode::RuntimeConfig;
+
+/// Print the once-per-installation telemetry notice when it is due:
+/// telemetry enabled (env override, then settings — the `RunOptions`
+/// resolution) and not yet shown.
+pub(crate) fn print_if_due(config: &RuntimeConfig) {
+ if config.telemetry_disabled {
+ return;
+ }
+ let mut settings = pa_core::settings::SettingsManager::create(&config.cwd, &config.agent_dir);
+ if settings.get_telemetry_notice_shown() {
+ return;
+ }
+ eprintln!(
+ "Prime Agent sends pseudonymous usage and performance metrics without prompts, responses, tool content, file paths, or repository data. Disable this with /telemetry off, telemetry.enabled=false, PRIME_AGENT_TELEMETRY=0, DO_NOT_TRACK=1, or offline mode."
+ );
+ if let Err(error) = settings.set_telemetry_notice_shown(true) {
+ eprintln!("Warning: could not persist the telemetry notice: {error}");
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::mode::RuntimeConfig;
+
+ fn config_for(dir: &std::path::Path, telemetry_disabled: bool) -> RuntimeConfig {
+ RuntimeConfig {
+ cwd: dir.to_path_buf(),
+ agent_dir: dir.join("agent"),
+ telemetry_disabled,
+ ..Default::default()
+ }
+ }
+
+ fn notice_shown(dir: &std::path::Path) -> bool {
+ pa_core::settings::SettingsManager::create(dir, dir.join("agent"))
+ .get_telemetry_notice_shown()
+ }
+
+ #[test]
+ fn headless_discloses_immediately_and_once() {
+ let dir = tempfile::TempDir::new().expect("temp dir");
+ let config = config_for(dir.path(), false);
+ print_if_due(&config);
+ assert!(notice_shown(dir.path()), "the first headless run discloses");
+ print_if_due(&config);
+ // The once-per-installation gate is the settings flag, so the
+ // second call is a no-op by construction.
+ }
+
+ #[test]
+ fn disabled_never_discloses() {
+ let dir = tempfile::TempDir::new().expect("temp dir");
+ print_if_due(&config_for(dir.path(), true));
+ assert!(
+ !notice_shown(dir.path()),
+ "an opted-out run sends no notice"
+ );
+ }
+}
diff --git a/crates/pa-cli/tests/interactive_daemon_e2e.rs b/crates/pa-cli/tests/interactive_daemon_e2e.rs
index e9856c6c70..93aeac9e4c 100644
--- a/crates/pa-cli/tests/interactive_daemon_e2e.rs
+++ b/crates/pa-cli/tests/interactive_daemon_e2e.rs
@@ -711,6 +711,13 @@ impl pa_tui::interactive::OnboardingSink for FreshHomeOnboardingSink {
pa_core::settings::SettingsManager::create(&self.cwd, &self.agent_dir)
.set_onboarding_shown(true)
}
+
+ fn onboarding_incomplete(
+ &self,
+ _outcome: &'static str,
+ ) -> std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send + '_>> {
+ Box::pin(std::future::ready(()))
+ }
}
/// The product sink whose completion write always fails (the failed
@@ -738,6 +745,13 @@ impl pa_tui::interactive::OnboardingSink for FailingMarkOnboardingSink {
fn mark_onboarding_complete(&self) -> anyhow::Result<()> {
Err(anyhow::anyhow!("settings disk full"))
}
+
+ fn onboarding_incomplete(
+ &self,
+ _outcome: &'static str,
+ ) -> std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send + '_>> {
+ Box::pin(std::future::ready(()))
+ }
}
/// A fresh install asks the trace question exactly once, as the first-run
diff --git a/crates/pa-cli/tests/telemetry_command_e2e.rs b/crates/pa-cli/tests/telemetry_command_e2e.rs
new file mode 100644
index 0000000000..ab4f82731b
--- /dev/null
+++ b/crates/pa-cli/tests/telemetry_command_e2e.rs
@@ -0,0 +1,67 @@
+//! `prime-agent telemetry [status|on|off]` end to end: the binary reports
+//! the switch and why, persists the TS settings key, and names an
+//! environment opt-out that still wins over a saved `on`.
+
+use std::path::Path;
+use std::process::Command;
+
+fn run(sandbox: &Path, args: &[&str], env: &[(&str, &str)]) -> (Option<i32>, String) {
+ let mut command = Command::new(env!("CARGO_BIN_EXE_prime-agent"));
+ command
+ .args(args)
+ .env("PRIME_AGENT_CODING_AGENT_DIR", sandbox.join("agent"))
+ .env("HOME", sandbox)
+ .env_remove("PI_OFFLINE")
+ .env_remove("DO_NOT_TRACK")
+ .env_remove("PRIME_AGENT_TELEMETRY")
+ .current_dir(sandbox);
+ for (key, value) in env {
+ command.env(key, value);
+ }
+ let output = command.output().expect("spawn prime-agent");
+ (
+ output.status.code(),
+ String::from_utf8_lossy(&output.stdout).into_owned(),
+ )
+}
+
+fn saved_switch(sandbox: &Path) -> serde_json::Value {
+ let text = std::fs::read_to_string(sandbox.join("agent").join("settings.json"))
+ .expect("settings.json written");
+ serde_json::from_str::<serde_json::Value>(&text).expect("settings json")["telemetry"]["enabled"]
+ .clone()
+}
+
+#[test]
+fn status_on_and_off_round_trip() {
+ let dir = tempfile::tempdir().unwrap();
+ let sandbox = dir.path();
+
+ let (code, out) = run(sandbox, &["telemetry"], &[]);
+ assert_eq!(code, Some(0), "{out}");
+ assert!(out.contains("Telemetry is on (on by default)."), "{out}");
+ assert!(out.contains("Installation id: not created yet"), "{out}");
+
+ let (code, out) = run(sandbox, &["telemetry", "off"], &[]);
+ assert_eq!(code, Some(0), "{out}");
+ assert!(out.contains("Telemetry turned off."), "{out}");
+ assert_eq!(saved_switch(sandbox), serde_json::json!(false));
+ let (_, out) = run(sandbox, &["telemetry", "status"], &[]);
+ assert!(
+ out.contains("Telemetry is off (turned off in settings)."),
+ "{out}"
+ );
+
+ let (code, out) = run(sandbox, &["telemetry", "on"], &[("DO_NOT_TRACK", "1")]);
+ assert_eq!(code, Some(0), "{out}");
+ assert_eq!(saved_switch(sandbox), serde_json::json!(true));
+ assert!(
+ out.contains(
+ "Saved telemetry on in settings, but it stays off (forced off by DO_NOT_TRACK)."
+ ),
+ "{out}"
+ );
+
+ let (code, _) = run(sandbox, &["telemetry", "maybe"], &[]);
+ assert_eq!(code, Some(1));
+}
diff --git a/crates/pa-core/README.md b/crates/pa-core/README.md
index 5958ebacf0..92d35d0d92 100644
--- a/crates/pa-core/README.md
+++ b/crates/pa-core/README.md
@@ -74,7 +74,7 @@ only: nothing wires it to a user-facing cloud toggle yet.
No provider HTTP (pa-ai), no loop policy (pa-agent), no daemon supervision (pa-daemon), no TUI (pa-tui). No update coordination (the pa-cli coordinator owns the FSM; the update-flow seam here is the daemon-free support layer: `update::version` (semver/channel policy), `update::install` (the managed install-root layout), `update::release` (the channel manifest fetch), `update::download` (sha256-verified archive download + staging)). The package manager installs sources and resolves resource paths only. No workspace snapshot upload, transport, or remote materialization (staging and verification live here; the cloud attach surface owns the transport when it ships).
## Public API
-`SessionEngine` (message in -> events out), `export_html` (the HTML exporter plus its renderer seam: `tools_section`, `pre_render_custom_tools` + `ToolHtmlRenderer`/`RenderedToolHtml`/`RenderedToolResult`, and `ansi_to_html::ansi_lines_to_html`/`tool_render::trim_rendered_result_lines` for renderer implementers), `ToolRegistry`, kernel manager, settings (`SettingsManager`), packages (`packages::PackageManager` + source types), `platform` (process control, file locking, permissions, shell selection - usable by higher crates, e.g. pa-cli's detached spawn), `session_engine::rlm_host::RlmSubagentHost` (implemented by pa-daemon for supervisor-backed children; the default is no children), `mcp::McpManager` (the session's host-side MCP manager, exposed as `SessionEngine.mcp_manager`: auth gating for built-in integrations, the `mcpServers` setting seam, and the `mcp.*` host-request handlers - `mcp.config`/`mcp.refresh`/optional `mcp.begin_login` - the kernel's generic MCP client resolves through), `mcp::McpManager::connection_roster` + `mcp::McpConnectionEntry` (the `/mcp` view's roster: every resolved integration with its connected state, display kind, transport, and generic-listable flag), `mcp::McpManager::service_catalog_views` + `service_catalog_diagnostics` (the `/mcp` view's resolved service-catalog cards and their diagnostics, answered from local state - the TS `buildServiceCatalogViews` parity; the picker never round-trips the kernel), `mcp::McpManager::api_key_credential_views` + `mcp::API_KEY_CREDENTIALS`/`McpCredentialView` (the `/mcp` view's api-key credential rows - the stored keys the surface manages alongside the connections, e.g. the web-search key - configured from the shared auth store), `models` (the registry and resolver, plus `models::order_for_picker`: the picker-catalog order the composition root applies to its snapshot), `session_engine::provider_adapter` (`switchable_stream_fn`/`ProviderTarget`: the live provider-target slot a host swaps on `set_model`; the adapter bridges the loop's abort into pa-ai's `StreamOptions::signal` cancellation token, so a turn abort cancels the in-flight HTTP fetch at the transport — closed by `ModelStream::close` and the stream's drop), `session_engine::ipython_state` (the post-compaction `ipython_state` kernel-persistence notice: the `CompactionKernelProbe` view of the kernel provisioner the engine wiring binds via `AgentSession::set_kernel_state_probe`, and the notice row that rides `CompactRun` for the surfaces to broadcast). `session_engine::session_commands` (the `/compact`/`/refine`/`/goal`/`/autonomous` executor: the durable echo/result rows with their persistence order - the echo ahead of the command so its own work sees it - the compaction/refinement/goal/autonomous arms, and the post-execution live-context rebuild that keeps the rows in the agent state; hosts own the wire surface), `session_engine::auto_refine_trigger` (the compact-trigger auto-refine machine on `AgentSession`: the arm/discard/increment accessors and `consume_compact_auto_refine`, the shared gate/review/stamp sequence every scheduling surface applies - TS `_compactAutoRefinePending`/`_lastAutoRefineReviewAt`/`_assistantTurnsSinceAutoRefine` plus `_maybeAutoRefine`'s compact arm, the serialized checkpoint's compact step, and dispose's serialized drain, with the surface parameter carrying the one behavioral difference between a boundary and a disposal). `session_engine::goal_boundary` (the goal arms of the natural turn end on `SessionEngine`: the `--goal` construction seed with its next-turn context row - TS `_pendingNextTurnMessages` on `AgentSession` - the usage accounting, the budget-limit steer mint, the natural continuation mint with its slot rollback, and the terminal-error finish; the transports - the print driver's in-loop hook, the ACP settle loop, the daemon worker's queue - drive the one goal driver through these methods). `SessionEngine::expand_skill_submission` + `AgentSession`'s prompt-path expansion (the `/skill:<name>` submission seam, TS `_expandSkillCommand`: `skills::expand_skill_command` builds the `<skill ...>` block over the shared `pa_types::skill_blocks` parse, the accepted-turn row and the admitted user message agree on the expanded text, and the `skill used` adoption event reports from the admission). `workspace_snapshot` (`create_workspace_snapshot`: bounded, secret/nested-repo/submodule/symlink-ancestor-excluding capture of a git worktree into an owner-private staging directory, with the caller-chosen `BaselineMode` (HEAD-tree content verified against HEAD's object ids, or explicit external) and a `ConcurrentMutation` error when the worktree changes under the capture; `verify_workspace_snapshot`: offline manifest/blob/baseline integrity check; the `SnapshotManifest`/`WorkspaceSnapshot`/`SnapshotLimits`/`BaselineMode`/`SnapshotError` types). All subsystem internals `pub(crate)`; the engine is the only facade - subsystems must not import each other directly (the package manager consumes the public settings API only).
+`SessionEngine` (message in -> events out), `export_html` (the HTML exporter plus its renderer seam: `tools_section`, `pre_render_custom_tools` + `ToolHtmlRenderer`/`RenderedToolHtml`/`RenderedToolResult`, and `ansi_to_html::ansi_lines_to_html`/`tool_render::trim_rendered_result_lines` for renderer implementers), `ToolRegistry`, kernel manager, settings (`SettingsManager`), packages (`packages::PackageManager` + source types), `platform` (process control, file locking, permissions, shell selection - usable by higher crates, e.g. pa-cli's detached spawn), `session_engine::rlm_host::RlmSubagentHost` (implemented by pa-daemon for supervisor-backed children; the default is no children), `mcp::McpManager` (the session's host-side MCP manager, exposed as `SessionEngine.mcp_manager`: auth gating for built-in integrations, the `mcpServers` setting seam, and the `mcp.*` host-request handlers - `mcp.config`/`mcp.refresh`/optional `mcp.begin_login` - the kernel's generic MCP client resolves through), `mcp::McpManager::connection_roster` + `mcp::McpConnectionEntry` (the `/mcp` view's roster: every resolved integration with its connected state, display kind, transport, and generic-listable flag), `mcp::McpManager::service_catalog_views` + `service_catalog_diagnostics` (the `/mcp` view's resolved service-catalog cards and their diagnostics, answered from local state - the TS `buildServiceCatalogViews` parity; the picker never round-trips the kernel), `mcp::McpManager::api_key_credential_views` + `mcp::API_KEY_CREDENTIALS`/`McpCredentialView` (the `/mcp` view's api-key credential rows - the stored keys the surface manages alongside the connections, e.g. the web-search key - configured from the shared auth store), `models` (the registry and resolver, plus `models::order_for_picker`: the picker-catalog order the composition root applies to its snapshot), `session_engine::provider_adapter` (`switchable_stream_fn`/`ProviderTarget`: the live provider-target slot a host swaps on `set_model`; the adapter bridges the loop's abort into pa-ai's `StreamOptions::signal` cancellation token, so a turn abort cancels the in-flight HTTP fetch at the transport — closed by `ModelStream::close` and the stream's drop), `session_engine::ipython_state` (the post-compaction `ipython_state` kernel-persistence notice: the `CompactionKernelProbe` view of the kernel provisioner the engine wiring binds via `AgentSession::set_kernel_state_probe`, and the notice row that rides `CompactRun` for the surfaces to broadcast). `session_engine::session_commands` (the `/compact`/`/refine`/`/goal`/`/autonomous` executor: the durable echo/result rows with their persistence order - the echo ahead of the command so its own work sees it - the compaction/refinement/goal/autonomous arms, and the post-execution live-context rebuild that keeps the rows in the agent state; hosts own the wire surface), `session_engine::auto_refine_trigger` (the compact-trigger auto-refine machine on `AgentSession`: the arm/discard/increment accessors and `consume_compact_auto_refine`, the shared gate/review/stamp sequence every scheduling surface applies - TS `_compactAutoRefinePending`/`_lastAutoRefineReviewAt`/`_assistantTurnsSinceAutoRefine` plus `_maybeAutoRefine`'s compact arm, the serialized checkpoint's compact step, and dispose's serialized drain, with the surface parameter carrying the one behavioral difference between a boundary and a disposal). `session_engine::goal_boundary` (the goal arms of the natural turn end on `SessionEngine`: the `--goal` construction seed with its next-turn context row - TS `_pendingNextTurnMessages` on `AgentSession` - the usage accounting, the budget-limit steer mint, the natural continuation mint with its slot rollback, and the terminal-error finish; the transports - the print driver's in-loop hook, the ACP settle loop, the daemon worker's queue - drive the one goal driver through these methods). `SessionEngine::expand_skill_submission` + `AgentSession`'s prompt-path expansion (the `/skill:<name>` submission seam, TS `_expandSkillCommand`: `skills::expand_skill_command` builds the `<skill ...>` block over the shared `pa_types::skill_blocks` parse, the accepted-turn row and the admitted user message agree on the expanded text, and the `skill_use_count` session counter counts at the admission). `workspace_snapshot` (`create_workspace_snapshot`: bounded, secret/nested-repo/submodule/symlink-ancestor-excluding capture of a git worktree into an owner-private staging directory, with the caller-chosen `BaselineMode` (HEAD-tree content verified against HEAD's object ids, or explicit external) and a `ConcurrentMutation` error when the worktree changes under the capture; `verify_workspace_snapshot`: offline manifest/blob/baseline integrity check; the `SnapshotManifest`/`WorkspaceSnapshot`/`SnapshotLimits`/`BaselineMode`/`SnapshotError` types). All subsystem internals `pub(crate)`; the engine is the only facade - subsystems must not import each other directly (the package manager consumes the public settings API only).
## Depends on
pa-types, pa-ai, pa-agent (one-way).
diff --git a/crates/pa-core/src/kernel/provisioner.rs b/crates/pa-core/src/kernel/provisioner.rs
index 3d7d31827d..cdca1aea31 100644
--- a/crates/pa-core/src/kernel/provisioner.rs
+++ b/crates/pa-core/src/kernel/provisioner.rs
@@ -97,7 +97,7 @@ pub enum KernelBootstrapOutcome {
Error,
}
-/// What one `kernel bootstrap` telemetry event reports.
+/// One kernel boot's facts for the `kernel_bootstrap_*` session counters.
#[derive(Debug, Clone, Copy)]
pub struct KernelBootstrapStats {
/// No prior namespace snapshot existed to restore (fresh session vs a
@@ -108,7 +108,7 @@ pub struct KernelBootstrapStats {
pub duration_ms: u64,
}
-/// Reports kernel bootstrap results (`kernel bootstrap`, schema v1).
+/// Reports kernel bootstrap results (the `kernel_bootstrap_*` session counters).
pub type KernelBootstrapResultHandler = Arc<dyn Fn(KernelBootstrapStats) + Send + Sync>;
#[derive(Default, Clone)]
@@ -140,7 +140,7 @@ pub struct IpythonKernelProvisionerOptions {
/// session can tell the model before it wastes turns calling them
/// (TS `IpythonToolOptions.onUnavailableSkills`).
pub on_unavailable_skills: Option<UnavailableSkillsCallback>,
- /// Publishes the per-boot result for `kernel bootstrap` telemetry.
+ /// Publishes the per-boot result for the `kernel_bootstrap_*` counters.
/// Telemetry only; kernel behavior never depends on it.
pub on_bootstrap_result: Option<KernelBootstrapResultHandler>,
}
diff --git a/crates/pa-core/src/session_engine/admission.rs b/crates/pa-core/src/session_engine/admission.rs
index ee30b38db6..e489be01f5 100644
--- a/crates/pa-core/src/session_engine/admission.rs
+++ b/crates/pa-core/src/session_engine/admission.rs
@@ -112,28 +112,17 @@ impl AgentSession {
let state = self.agent.state().await;
let busy = state.is_streaming;
- // The `skill used` adoption event reports from the admission seam:
- // an admitted user turn whose text IS a skill block reports once,
- // with how the invocation arrived (a fresh admission, or a queued
- // steering/follow-up submission). A pre-expanded block (the daemon
- // emits the accepted row before admission) reports here too — the
- // block parse carries the skill identity.
- if let Some(skill) = used_skill.or_else(|| {
- pa_types::skill_blocks::parse_skill_block(&normalized)
- .and_then(|block| self.skills.iter().find(|skill| skill.name == block.name))
- }) {
+ // The `skill_use_count` session counter counts at the admission
+ // seam: an admitted user turn whose text IS a skill block counts
+ // once. A pre-expanded block (the daemon emits the accepted row
+ // before admission) counts here too — the block parse carries the
+ // skill identity.
+ let skill_used = used_skill.is_some()
+ || pa_types::skill_blocks::parse_skill_block(&normalized)
+ .is_some_and(|block| self.skills.iter().any(|skill| skill.name == block.name));
+ if skill_used {
if let Some(telemetry) = &self.skill_telemetry {
- let source = if busy {
- match options.streaming_behavior {
- Some(StreamingBehavior::Steer) => "steer",
- // The busy-without-behavior case errors below; the
- // queued label is the honest fallback.
- Some(StreamingBehavior::FollowUp) | None => "follow_up",
- }
- } else {
- "prompt"
- };
- telemetry.note_skill_used(&skill.name, skill.kind_label(), source);
+ telemetry.note_skill_used();
}
}
if busy && options.streaming_behavior.is_none() {
diff --git a/crates/pa-core/src/session_engine/compact_session.rs b/crates/pa-core/src/session_engine/compact_session.rs
index f31848260c..67df9f41af 100644
--- a/crates/pa-core/src/session_engine/compact_session.rs
+++ b/crates/pa-core/src/session_engine/compact_session.rs
@@ -145,8 +145,9 @@ fn context_tokens(entries: &[FileEntry], leaf_id: Option<&str>) -> u64 {
pub struct CompactRun {
pub result: CompactionResult,
pub entry: pa_types::session::CompactionEntry,
- /// The whole compaction's wall duration (the `agent timing` compaction
- /// stage; measured here once, centrally, for every arm).
+ /// The whole compaction's wall duration (the run's
+ /// `compaction_duration_ms`; measured here once, centrally, for every
+ /// arm).
pub duration_ms: u64,
/// The post-compaction `ipython_state` kernel-persistence notice, when a
/// kernel was running (TS `_syncKernelStateAfterCompaction`): the row is
diff --git a/crates/pa-core/src/session_engine/engine.rs b/crates/pa-core/src/session_engine/engine.rs
index cf760a1e12..cd4ff084eb 100644
--- a/crates/pa-core/src/session_engine/engine.rs
+++ b/crates/pa-core/src/session_engine/engine.rs
@@ -15,8 +15,6 @@ use crate::resources::{load_resources, ResourceLoaderOptions};
use crate::session::manager::SessionManager;
use crate::skills::PromptTemplate;
-use pa_telemetry::base_properties;
-
use super::{AgentSession, PromptOptions, PromptOutcome};
/// Everything needed to assemble a session.
@@ -65,7 +63,7 @@ pub struct SessionEngineConfig {
/// The full registry model (input modalities for `model.info`); the
/// engine derives minimal facts from `model` when absent.
pub model_info: Option<pa_types::ai::Model>,
- /// Session telemetry wiring (`PostHog` client + execution mode). `None`
+ /// Session telemetry wiring (the telemetry client + execution mode). `None`
/// (opt-out) installs nothing; non-depth-0 sessions never install.
pub telemetry: Option<super::telemetry::TelemetryWiring>,
/// The embedding's queued-goal-context purge (TS
@@ -321,26 +319,35 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
if let Some(extra) = config.extra_host_handlers.clone() {
handlers.merge(extra);
}
+ // Per-session counters (MCP connector use, kernel boots, skills, RLM
+ // child usage, feature outcomes) ride `agent session ended`; the seams
+ // below count into them instead of emitting their own events.
+ let session_counters = std::sync::Arc::new(super::telemetry::SessionCounters::default());
+ // The counters gate from the very creation: the MCP and kernel setup
+ // below starts counting (prewarm boots, connector use) long before
+ // the first turn installs the session telemetry, so an off switch
+ // must already be live — otherwise the pre-install window records
+ // what a later enable would send.
+ if let Some(telemetry_switch) = config
+ .telemetry
+ .as_ref()
+ .and_then(|telemetry| telemetry.telemetry_enabled.as_ref())
+ {
+ session_counters.set_telemetry_enabled(telemetry_switch.enabled.clone());
+ }
// The `mcp.*` host requests (config/refresh/begin_login) the kernel's
// generic MCP registry sends while listing or calling generic servers.
- // Telemetry reports connector usage (server name + action only) when the
+ // Telemetry counts connector use (never the server name) when the
// session is telemetry-enabled; set before the handlers register so
// their closures capture the reporter.
- {
- let mut manager = mcp_manager.lock().unwrap();
- if let Some(wiring) = &config.telemetry {
- let client = wiring.client.clone();
- let execution_mode = wiring
- .execution_mode
- .clone()
- .unwrap_or_else(|| super::telemetry::EXECUTION_MODE_UNKNOWN.to_string());
- manager.set_usage_report(Some(std::sync::Arc::new(move |action, server| {
- let mut properties = base_properties(&execution_mode);
- properties.set("action", serde_json::Value::from(action));
- properties.set("server_name", serde_json::Value::from(server));
- client.track("mcp connector used", properties);
+ if config.telemetry.is_some() {
+ let counters = std::sync::Arc::clone(&session_counters);
+ mcp_manager
+ .lock()
+ .unwrap()
+ .set_usage_report(Some(std::sync::Arc::new(move |_action, _server| {
+ counters.note_mcp_connector_use();
})));
- }
}
// The `mcp.*` host-request registration takes the shared manager: the
// inventory handlers (list_plugins/search_plugins/list_connections)
@@ -383,27 +390,20 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
if auto_refine_allowed {
turn_boundary.register_refine_handlers(&mut handlers);
}
- // `kernel bootstrap` telemetry: the provisioner reports every actual
- // boot (duration, cold/revived, outcome) through the session's client.
- let on_bootstrap_result = config.telemetry.as_ref().map(|wiring| {
- let client = wiring.client.clone();
- let execution_mode = wiring
- .execution_mode
- .clone()
- .unwrap_or_else(|| super::telemetry::EXECUTION_MODE_UNKNOWN.to_string());
+ // Kernel boots (duration, cold/revived, outcome) count into the
+ // session counters.
+ let on_bootstrap_result = config.telemetry.as_ref().map(|_| {
+ let counters = std::sync::Arc::clone(&session_counters);
std::sync::Arc::new(
move |stats: crate::kernel::provisioner::KernelBootstrapStats| {
- let mut properties = base_properties(&execution_mode);
- properties.set("cold", serde_json::Value::from(stats.cold));
- properties.set(
- "outcome",
- serde_json::Value::from(match stats.outcome {
- crate::kernel::provisioner::KernelBootstrapOutcome::Ready => "success",
- crate::kernel::provisioner::KernelBootstrapOutcome::Error => "error",
- }),
+ counters.note_kernel_bootstrap(
+ stats.cold,
+ matches!(
+ stats.outcome,
+ crate::kernel::provisioner::KernelBootstrapOutcome::Ready
+ ),
+ stats.duration_ms,
);
- properties.set("duration_ms", serde_json::Value::from(stats.duration_ms));
- client.track("kernel bootstrap", properties);
},
) as crate::kernel::provisioner::KernelBootstrapResultHandler
});
@@ -782,6 +782,7 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
&telemetry_agent,
&wiring,
Some(skill_counts),
+ std::sync::Arc::clone(&session_counters),
)
.await?;
Some(std::sync::Arc::new(installed))
@@ -789,13 +790,13 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
_ => None,
};
- // The `skill used` adoption event reports through the session's
+ // The `skill_use_count` session counter counts through the session's
// telemetry handle (installed once the telemetry composition decided
// whether this session reports at all).
if let Some(telemetry) = telemetry.as_ref() {
session.set_skill_telemetry(telemetry.clone());
- // Same lifetime for the `rlm child usage attributed` adoption
- // event: the producer's flush reports through this handle.
+ // Same lifetime for the `rlm_child_*` session counters: the
+ // producer's flush counts through this handle.
wiring.rlm_usage.set_telemetry(telemetry.clone());
}
let goal_driver = wiring.runtime.goal_driver().clone();
@@ -848,8 +849,8 @@ impl SessionEngine {
/// the accepted-turn row (TS `_expandSkillCommand`; the row the daemon
/// emits before admission must match the text the model turn
/// receives). Non-skill inputs pass through unchanged; the admitted
- /// turn's own expansion is idempotent over the block. The `skill used`
- /// adoption event reports from the admission, not here.
+ /// turn's own expansion is idempotent over the block. The
+ /// `skill_use_count` counter counts at the admission, not here.
pub fn expand_skill_submission(&self, text: &str) -> String {
crate::skills::expand_skill_command(text, &self.skills).0
}
diff --git a/crates/pa-core/src/session_engine/error_classify.rs b/crates/pa-core/src/session_engine/error_classify.rs
index 9d3ad53591..aca7f6b75b 100644
--- a/crates/pa-core/src/session_engine/error_classify.rs
+++ b/crates/pa-core/src/session_engine/error_classify.rs
@@ -429,10 +429,6 @@ mod tests {
"The provider ended the response stream without a stop signal."
);
assert!(pa_telemetry::ERROR_SUBTYPES.contains(&classification.subtype));
- assert!(
- pa_telemetry::ERROR_CODES.contains(&classification.code.unwrap()),
- "the code token stays inside the catalog's safe vocabulary"
- );
// The empty-stream variant classifies identically.
let empty = classify(
"Provider dropped the response stream (stream_drop): the stream ended before any response content or stop signal"
diff --git a/crates/pa-core/src/session_engine/mod.rs b/crates/pa-core/src/session_engine/mod.rs
index cc88351ad0..eb8a413162 100644
--- a/crates/pa-core/src/session_engine/mod.rs
+++ b/crates/pa-core/src/session_engine/mod.rs
@@ -185,8 +185,8 @@ pub struct AgentSession {
/// reads `resourceLoader.getSkills()` at expansion time; the engine
/// wiring installs the loaded list once the session is assembled).
skills: Vec<crate::skills::Skill>,
- /// The telemetry handle for the `skill used` adoption event the
- /// prompt path owns (`None` in sessions without telemetry).
+ /// The telemetry handle for the `skill_use_count` counter the prompt
+ /// path owns (`None` in sessions without telemetry).
skill_telemetry: Option<std::sync::Arc<telemetry::SessionTelemetry>>,
/// The image-model routing host seam (`None` keeps the session model on
/// image turns: verification harnesses, and the daemon worker whose
diff --git a/crates/pa-core/src/session_engine/rlm_usage.rs b/crates/pa-core/src/session_engine/rlm_usage.rs
index b06a7e8c2b..a97aa791cc 100644
--- a/crates/pa-core/src/session_engine/rlm_usage.rs
+++ b/crates/pa-core/src/session_engine/rlm_usage.rs
@@ -87,8 +87,8 @@ pub struct RlmChildUsageAttributions {
/// session that runs sequential children must not accumulate their
/// registrations.
children: std::sync::Mutex<HashMap<String, String>>,
- /// The `rlm child usage attributed` adoption event's handle (`None`
- /// in sessions without telemetry — subagents never double-report).
+ /// The `rlm_child_*` session counters' handle (`None` in sessions
+ /// without telemetry — subagents never double-report).
telemetry: std::sync::Mutex<Option<std::sync::Arc<super::telemetry::SessionTelemetry>>>,
/// The producer a rebuild handed observation over to: an in-flight
/// emission that cloned the retired sink still delivers through this
@@ -115,8 +115,8 @@ impl RlmChildUsageAttributions {
}
}
- /// Bind the telemetry handle the `rlm child usage attributed`
- /// adoption event reports through (the engine wiring installs it
+ /// Bind the telemetry handle the `rlm_child_*` session counters count
+ /// through (the engine wiring installs it
/// once the session telemetry is assembled; depth-0 sessions only).
///
/// # Panics
@@ -264,11 +264,6 @@ impl RlmChildUsageAttributions {
.as_ref()
{
telemetry.note_child_usage_attributed(
- match origin {
- ChildUsageOrigin::SpawnTask => "spawn_task",
- ChildUsageOrigin::AgentMessage => "agent_message",
- ChildUsageOrigin::DirectUser => "direct_user",
- },
usage.input,
usage.output,
usage.cache_read,
diff --git a/crates/pa-core/src/session_engine/session_commands.rs b/crates/pa-core/src/session_engine/session_commands.rs
index 6322f94cfc..8bbab23a83 100644
--- a/crates/pa-core/src/session_engine/session_commands.rs
+++ b/crates/pa-core/src/session_engine/session_commands.rs
@@ -198,11 +198,6 @@ pub async fn execute_session_command(
execution.error = Some(error);
return execution;
}
- // Telemetry adoption seam: builtin session commands carry their usage
- // event from the single dispatch point (canonical name only).
- if let Some(telemetry) = &engine.telemetry {
- telemetry.note_command_used(command.name);
- }
let result = match command.name {
"compact" => execute_compact(engine, params, command, &mut execution).await,
"refine" => execute_refine(engine, params, command, &mut execution).await,
@@ -342,8 +337,8 @@ async fn execute_goal(
execution: &mut SessionCommandExecution,
) -> Result<(), String> {
let goal = parse_goal_command(&command.args)?;
- // The goal command's fixed choice for the `agent feature outcome`
- // event (captured before the driver arm moves the command's fields).
+ // The goal command's fixed choice for the feature-outcome seam
+ // (captured before the driver arm moves the command's fields).
let goal_choice = match goal {
GoalCommand::Status => "status",
GoalCommand::Clear => "clear",
@@ -420,10 +415,8 @@ async fn execute_goal(
// turn's primary record (an injected custom row), never an early
// durable row — the loop admission appends it once.
execution.continuation_message = context_message;
- // `agent feature outcome` (v2, #2117): the goal command's observed
- // result at this seam (the driver applied the action). The
- // configuration_choice carries the action for the fixed-choice
- // commands.
+ // The goal command's observed result at this seam (the driver applied
+ // the action), counted as `feature_goal_completed_count`.
if let Some(telemetry) = engine.telemetry.as_ref() {
telemetry.note_feature_outcome("goal", "completed", Some(goal_choice));
}
diff --git a/crates/pa-core/src/session_engine/telemetry.rs b/crates/pa-core/src/session_engine/telemetry.rs
index 7d17689de2..76a3da380b 100644
--- a/crates/pa-core/src/session_engine/telemetry.rs
+++ b/crates/pa-core/src/session_engine/telemetry.rs
@@ -1,11 +1,10 @@
//! Session telemetry: the agent-event state machine behind the session
-//! lifecycle events (`agent started` / `agent run started` /
-//! `agent run completed` / `agent session ended` / `agent command used` /
-//! `tool executed`) and the #2117 v2 vocabulary (`agent error`,
-//! `agent timing`, `agent tool summary`). Behavioral port of the TS
-//! `installAgentTelemetry` subscriber (`packages/coding-agent/src/core/
-//! telemetry.ts`) plus the never-merged #2117 tracking intent, implemented
-//! on the pa-telemetry catalog's typed builders.
+//! events `agent started`, `agent run completed` (one per user turn, every
+//! per-call fact folded into it as aggregates), and `agent session ended`
+//! (with the per-session counters); the TUI client reports `agent command
+//! used`. Behavioral port of the TS `installAgentTelemetry` subscriber
+//! (`packages/coding-agent/src/core/telemetry.ts`) plus the #2117 v2
+//! enrichment.
//!
//! Divergence from the TS state machine, documented: the TS subscriber tracks
//! `turnActionActive` because the TS session loop can span several agent runs
@@ -27,8 +26,7 @@ use std::sync::{Arc, Mutex};
use pa_agent::agent::Subscription;
use pa_agent::types::{AgentEvent, AssistantMessage, StopReason, Usage};
use pa_telemetry::{
- base_properties, AgentError, AgentRunStarted, AgentTiming, AgentToolSummary, ErrorEventKind,
- Properties, RunTrigger, TelemetryClient, TelemetryClientConfig, TimingStage, ToolCategory,
+ base_properties, Properties, RunTrigger, TelemetryClient, TelemetryClientConfig, ToolCategory,
};
use serde_json::Value;
@@ -43,9 +41,9 @@ use super::error_classify::classify_error_message;
// external track_* path stable. ZERO bumps.
mod track;
pub use track::{
- track_catalog_refresh, track_compaction_abort_declared, track_daemon_event,
- track_deleted_child_usage_captured, track_model_refused, track_saved_sessions_usage,
- track_sessions_archived, track_worker_adoption, track_worker_children_closed,
+ track_catalog_refresh, track_compaction_abort_declared, track_daemon_event_summary,
+ track_deleted_child_usage_captured, track_model_refused, track_sessions_archived,
+ track_worker_adoption, track_worker_children_closed,
};
// The outcome/provider/model/error classification family (the TS
@@ -58,7 +56,13 @@ pub use track::{
// private (classify-internal callers).
mod classify;
pub use classify::provider_category;
+
+mod status;
use classify::{error_category, model_category, opt_value, run_outcome};
+pub use status::{
+ set_telemetry_enabled_text, telemetry_endpoint, telemetry_status_text, telemetry_switch,
+ TelemetrySwitch,
+};
// The inline unit battery moved to the child module at the same tree
// position (session_engine::telemetry::tests); its use-super glob keeps
@@ -72,6 +76,27 @@ pub const EXECUTION_MODE_UNKNOWN: &str = "unknown";
/// Telemetry wiring supplied by the composition root (`SessionEngineConfig`).
/// `None` telemetry (opt-out) installs nothing.
+/// A session's live opt-out switch: the enabled answer the recording
+/// The recording seams ask the switch at turn boundaries (run and turn
+/// starts) and cache the answer for the events in between: a mid-turn
+/// opt-out is observed at the next boundary, and the client's flush
+/// drops everything queued while the switch is off.
+#[derive(Clone)]
+pub struct RecordingSwitch {
+ /// Env-then-settings resolution, asked live at the turn boundaries:
+ /// false means telemetry is off right now.
+ pub enabled: Arc<dyn Fn() -> bool + Send + Sync>,
+}
+
+impl RecordingSwitch {
+ /// A plain switch for the seams: recording gates live on `enabled`
+ /// at the turn boundaries.
+ #[must_use]
+ pub fn test(enabled: Arc<dyn Fn() -> bool + Send + Sync>) -> Self {
+ Self { enabled }
+ }
+}
+
pub struct TelemetryWiring {
/// The shared client (base properties are stamped here, per event).
pub client: TelemetryClient,
@@ -80,6 +105,12 @@ pub struct TelemetryWiring {
/// Injectable clock (millis since epoch); defaults to system time.
/// Tests pass a controlled clock to assert duration math.
pub now: Option<Arc<dyn Fn() -> u64 + Send + Sync>>,
+ /// The live opt-out switch the recording seams consult at the turn
+ /// boundaries: while it answers false there, the run state machine
+ /// severs and nothing records until the next boundary, and the
+ /// client drops captures queued while the switch is off. `None` is
+ /// always on (tests and one-shot paths).
+ pub telemetry_enabled: Option<RecordingSwitch>,
}
/// Installed session telemetry: the event subscription plus the in-memory
@@ -89,6 +120,7 @@ pub struct SessionTelemetry {
client: TelemetryClient,
state: Arc<Mutex<TelemetryState>>,
execution_mode: String,
+ counters: Arc<SessionCounters>,
/// `end()` runs exactly once (session close and later kill/shutdown
/// paths may both reach it; only the first emits the ended event).
ended: std::sync::atomic::AtomicBool,
@@ -109,6 +141,7 @@ impl SessionTelemetry {
client,
state,
execution_mode,
+ counters: Arc::default(),
ended: std::sync::atomic::AtomicBool::new(false),
_subscription: None,
}
@@ -124,20 +157,46 @@ pub(crate) struct TelemetryState {
totals: SessionTotals,
active_run: Option<ActiveRun>,
tool_starts: HashMap<String, u64>,
- /// The unresolved error awaiting a recovery observation: its id pairs
- /// the occurrence with the later `recovery_update` (retries re-enter
- /// the loop as new run windows, so the pairing lives here, not on the
- /// run).
- active_error: Option<ActiveError>,
- /// Consecutive failed model calls without an intervening success
- /// (session-scoped like the TS chain; resets on recovery or success).
- consecutive_failure_count: u64,
+ /// The live opt-out switch from the wiring: asked at the turn
+ /// boundaries, never per event.
+ telemetry_enabled: Option<RecordingSwitch>,
+ /// The cached switch answer from the last turn boundary. Recording
+ /// on any other event consults only this flag, so a streaming delta
+ /// never re-reads and re-parses the settings file.
+ recording: bool,
now: Arc<dyn Fn() -> u64 + Send + Sync>,
}
-/// The error awaiting recovery: the occurrence's id.
-struct ActiveError {
- error_id: String,
+/// Is recording on right now? `None` (tests, one-shot paths) is always
+/// on; a set switch answers live. Called from under the state lock, so
+/// the switch itself must never lock the telemetry state.
+fn recording_on(state: &TelemetryState) -> bool {
+ state
+ .telemetry_enabled
+ .as_ref()
+ .is_none_or(|telemetry_switch| (telemetry_switch.enabled)())
+}
+
+/// While telemetry is off, the active run (if any) is severed: dropped
+/// without emitting, together with its in-flight tables. The switch is
+/// asked at the turn boundaries, so a run that spans an opt-out never
+/// completes after the boundary that observes the off period — neither
+/// its facts nor the off window's timing ride a later event.
+fn sever_off_period_run(state: &mut TelemetryState) {
+ state.active_run = None;
+ state.tool_starts.clear();
+}
+
+/// One turn boundary (a run or turn start): ask the live switch, cache
+/// the answer for the events until the next boundary, and cut the run
+/// when the switch says off. Between boundaries nothing re-reads the
+/// settings file — the client's flush drops everything queued while the
+/// switch is off, which covers a mid-turn opt-out.
+fn observe_turn_boundary(state: &mut TelemetryState) {
+ state.recording = recording_on(state);
+ if !state.recording {
+ sever_off_period_run(state);
+ }
}
#[derive(Default)]
@@ -149,6 +208,9 @@ struct SessionTotals {
prompt_count: u64,
tool_call_count: u64,
compaction_count: u64,
+ retry_count: u64,
+ failover_count: u64,
+ model_error_count: u64,
usage: UsageTotals,
}
@@ -182,6 +244,9 @@ impl UsageTotals {
}
}
+// The run's independent lifecycle flags (ended, retry pending, trigger
+// pending, usage complete); an enum would not change the flow.
+#[allow(clippy::struct_excessive_bools)]
struct ActiveRun {
started_at: u64,
/// `AgentEnd` fired but the run is not finalized yet: the post-run
@@ -207,17 +272,20 @@ struct ActiveRun {
failover_count: u64,
usage: UsageTotals,
last_assistant: Option<AssistantMessage>,
+ /// An auto-retry (or provider failover) started after this run's
+ /// failed attempt: the retried attempt's `AgentStart` continues this
+ /// run instead of starting a new one (TS: one run per turn, retries
+ /// counted in `retry_count`).
+ retry_pending: bool,
// v2 (#2117) per-run tracking:
- /// The run's uuid (pairs `agent run started` with `agent run
- /// completed` and the tool summaries).
+ /// The run's uuid.
run_id: String,
- /// 1-based ordinal of this run window in the session.
+ /// 1-based ordinal of this run in the session.
run_index: u64,
- /// `agent run started` fires when the trigger disambiguates (a
- /// prompt-run emits its user `MessageStart` right after `AgentStart`;
- /// a continuation-run goes straight to model events). The timestamp
- /// is always the `AgentStart` moment.
- run_started_pending: bool,
+ /// The trigger is still undecided: a prompt-run emits its user
+ /// `MessageStart` right after `AgentStart`; a continuation-run goes
+ /// straight to model events.
+ trigger_pending: bool,
trigger: RunTrigger,
first_reasoning_ms: Option<u64>,
run_to_first_text_ms: Option<u64>,
@@ -236,20 +304,142 @@ struct ActiveRun {
/// Summed usage cost in USD (estimated; null when incomplete or
/// pricing was unknown - the conservative direction).
cost_usd: f64,
- /// Per-tool-category aggregates for the run's tool summary events.
+ /// Each model call's latency (the p50 on the run event).
+ model_latencies: Vec<u64>,
+ /// Failed model calls in the run (every retried attempt included).
+ model_error_count: u64,
+ /// Failed model calls by TS `error_category`.
+ error_category_counts: std::collections::BTreeMap<&'static str, u64>,
+ /// Summed compaction durations inside the run.
+ compaction_duration_ms: u64,
+ /// Per-tool aggregates, keyed by the fixed tool category (built-in
+ /// tools by name, every MCP and custom tool folded into `mcp` /
+ /// `custom`: no raw tool names leave the machine).
tool_summary: HashMap<ToolCategory, ToolCategoryStats>,
}
-/// One tool category's per-run aggregates (`agent tool summary`).
+/// One tool category's per-run aggregates.
#[derive(Debug, Default)]
struct ToolCategoryStats {
calls: u64,
failures: u64,
duration_ms: u64,
- /// Failures later followed by a successful call of the same category
- /// within the run (the recovered signal).
- recovered: u64,
- last_call_failed: bool,
+ max_duration_ms: u64,
+}
+
+/// Per-session counters for the frequent per-occurrence facts that ride
+/// `agent session ended` instead of their own events (skill invocations,
+/// MCP connector use, kernel boots, RLM child usage, feature outcomes).
+/// Shared with the engine seams that report them.
+#[derive(Default)]
+pub struct SessionCounters {
+ inner: Mutex<CounterValues>,
+ /// The live opt-out switch, installed by the engine at the counters'
+ /// creation, before the MCP and kernel seams that count into them
+ /// capture their handles. While it answers false the counters stop
+ /// recording, so a later enable never sends what happened while
+ /// telemetry was off (the TUI counters' rule). `None` (the default,
+ /// used by tests and one-shot paths) is always on.
+ telemetry_enabled: std::sync::OnceLock<Arc<dyn Fn() -> bool + Send + Sync>>,
+}
+
+#[derive(Default)]
+struct CounterValues {
+ skill_use_count: u64,
+ mcp_connector_use_count: u64,
+ kernel_bootstrap_count: u64,
+ kernel_bootstrap_cold_count: u64,
+ kernel_bootstrap_failed_count: u64,
+ kernel_bootstrap_max_ms: u64,
+ rlm_child_usage_count: u64,
+ rlm_child_input_tokens: u64,
+ rlm_child_output_tokens: u64,
+ rlm_child_cache_read_tokens: u64,
+ rlm_child_cache_write_tokens: u64,
+ rlm_child_cost: f64,
+ /// `feature_<name>_<outcome>_count` over the fixed feature vocabulary.
+ feature_outcomes: std::collections::BTreeMap<String, u64>,
+}
+
+impl SessionCounters {
+ /// Install the live opt-out switch. The engine calls this at the
+ /// counters' creation, ahead of the MCP and kernel counting seams,
+ /// so no event can count before the switch is in place. A second
+ /// call is ignored (the first switch wins).
+ pub fn set_telemetry_enabled(&self, telemetry_enabled: Arc<dyn Fn() -> bool + Send + Sync>) {
+ let _ = self.telemetry_enabled.set(telemetry_enabled);
+ }
+
+ /// Count only while telemetry is on, so turning it on later never
+ /// sends what happened while it was off.
+ fn with(&self, update: impl FnOnce(&mut CounterValues)) {
+ if self
+ .telemetry_enabled
+ .get()
+ .is_some_and(|telemetry_enabled| !telemetry_enabled())
+ {
+ return;
+ }
+ update(
+ &mut self
+ .inner
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner),
+ );
+ }
+
+ /// An MCP connector call (the server name never uploads).
+ pub fn note_mcp_connector_use(&self) {
+ self.with(|values| values.mcp_connector_use_count += 1);
+ }
+
+ /// One kernel boot: cold or revived, its outcome, its duration.
+ pub fn note_kernel_bootstrap(&self, cold: bool, succeeded: bool, duration_ms: u64) {
+ self.with(|values| {
+ values.kernel_bootstrap_count += 1;
+ values.kernel_bootstrap_cold_count += u64::from(cold);
+ values.kernel_bootstrap_failed_count += u64::from(!succeeded);
+ values.kernel_bootstrap_max_ms = values.kernel_bootstrap_max_ms.max(duration_ms);
+ });
+ }
+
+ fn write_into(&self, properties: &mut Properties) {
+ self.with(|values| {
+ for (key, value) in [
+ ("skill_use_count", values.skill_use_count),
+ ("mcp_connector_use_count", values.mcp_connector_use_count),
+ ("kernel_bootstrap_count", values.kernel_bootstrap_count),
+ (
+ "kernel_bootstrap_cold_count",
+ values.kernel_bootstrap_cold_count,
+ ),
+ (
+ "kernel_bootstrap_failed_count",
+ values.kernel_bootstrap_failed_count,
+ ),
+ ("kernel_bootstrap_max_ms", values.kernel_bootstrap_max_ms),
+ ("rlm_child_usage_count", values.rlm_child_usage_count),
+ ("rlm_child_input_tokens", values.rlm_child_input_tokens),
+ ("rlm_child_output_tokens", values.rlm_child_output_tokens),
+ (
+ "rlm_child_cache_read_tokens",
+ values.rlm_child_cache_read_tokens,
+ ),
+ (
+ "rlm_child_cache_write_tokens",
+ values.rlm_child_cache_write_tokens,
+ ),
+ ] {
+ properties.set(key, Value::from(value));
+ }
+ if values.rlm_child_usage_count > 0 {
+ properties.set("rlm_child_cost", Value::from(values.rlm_child_cost));
+ }
+ for (key, count) in &values.feature_outcomes {
+ properties.set(key, Value::from(*count));
+ }
+ });
+ }
}
/// Skills present at session start (adoption counts on `agent started`).
@@ -274,6 +464,7 @@ pub async fn install_session_telemetry(
agent: &Arc<pa_agent::agent::Agent>,
wiring: &TelemetryWiring,
skill_counts: Option<SkillCounts>,
+ counters: Arc<SessionCounters>,
) -> anyhow::Result<SessionTelemetry> {
let execution_mode = wiring
.execution_mode
@@ -287,10 +478,14 @@ pub async fn install_session_telemetry(
totals: SessionTotals::default(),
active_run: None,
tool_starts: HashMap::new(),
- active_error: None,
- consecutive_failure_count: 0,
+ telemetry_enabled: wiring.telemetry_enabled.clone(),
+ recording: true,
now,
}));
+ // The counters arrive already gated: the engine installs the same
+ // live switch on them at creation (the MCP and kernel seams count
+ // long before this install runs), so nothing counts while telemetry
+ // is off in any window.
let subscriber_state = Arc::clone(&state);
let subscriber_client = client.clone();
@@ -324,6 +519,7 @@ pub async fn install_session_telemetry(
client,
state,
execution_mode,
+ counters,
ended: std::sync::atomic::AtomicBool::new(false),
_subscription: Some(subscription),
})
@@ -334,120 +530,83 @@ impl SessionTelemetry {
/// `compaction_end` handling). Counts toward the active run when one
/// exists, exactly like the TS subscriber — compactions outside a run
/// never inflate session totals. The duration (measured centrally by
- /// the compaction executor) also fires the `agent timing` compaction
- /// stage.
+ /// the compaction executor) sums into the run's
+ /// `compaction_duration_ms`.
///
/// # Panics
///
/// Panics if the telemetry state mutex is poisoned.
pub fn note_compaction(&self, duration_ms: Option<u64>) {
let mut state = self.state.lock().expect("telemetry state poisoned");
+ if !state.recording {
+ sever_off_period_run(&mut state);
+ return;
+ }
if let Some(run) = state.active_run.as_mut() {
run.compaction_count += 1;
- }
- if duration_ms.is_some() {
- AgentTiming {
- stage: TimingStage::Compaction,
- duration_ms,
- outcome: Some("success"),
- tool_category: None,
- timing_origin: Some("worker_action"),
- }
- .track(&self.client);
+ run.compaction_duration_ms += duration_ms.unwrap_or(0);
}
}
- /// One auto-retry event from the retry seam (feed from the retry
- /// callback; TS `auto_retry_start`/`auto_retry_end` handling):
+ /// One auto-retry event from the retry seam (TS `auto_retry_start`):
/// `Start` counts the retry (and a backup-provider switch as a
- /// failover) into the active run and measures the retry wait; `End`
- /// resolves the unresolved error's recovery (`recovery_update`).
+ /// failover) into the active run, sums the retry wait, and keeps the
+ /// run open, so the retried attempt continues the same run (one
+ /// `agent run completed` per turn, like TS). `End` closes the retry:
+ /// a retry that never ran (a cancelled wait) leaves the run to
+ /// finalize at the next start instead of absorbing the next turn. The
+ /// final attempt's message decides the outcome.
///
/// # Panics
///
/// Panics if the telemetry state mutex is poisoned.
pub fn note_auto_retry_event(&self, event: &AutoRetryEvent) {
let mut state = self.state.lock().expect("telemetry state poisoned");
+ if !state.recording {
+ // While off nothing counts, and the run severs: an off-period
+ // retry never continues an on-period run across the opt-out.
+ sever_off_period_run(&mut state);
+ return;
+ }
+ let Some(run) = state.active_run.as_mut() else {
+ return;
+ };
match event {
AutoRetryEvent::Start {
delay_ms, reason, ..
} => {
- if let Some(run) = state.active_run.as_mut() {
- run.retry_count += 1;
- run.retry_wait_ms += *delay_ms;
- if matches!(reason, super::auto_retry::RetryStartReason::Backup { .. }) {
- run.failover_count += 1;
- }
- }
- AgentTiming {
- stage: TimingStage::RetryWait,
- duration_ms: Some(*delay_ms),
- outcome: Some("success"),
- tool_category: None,
- timing_origin: Some("worker_action"),
- }
- .track(&self.client);
- }
- AutoRetryEvent::End {
- success, attempt, ..
- } => {
- // A SUCCESSFUL retry resolves the error it was retrying
- // (the active occurrence's id): one `recovery_update`,
- // paired with that occurrence. A FAILED retry adds no
- // recovery update at all - the retried attempt's own
- // failure was recorded as its own new occurrence at its
- // `MessageEnd` (the chain lives via that occurrence), and
- // a mispaired update to the original id would claim the
- // wrong recovery.
- if *success {
- if let Some(active) = state.active_error.take() {
- AgentError {
- error_id: active.error_id,
- kind: Some(ErrorEventKind::RecoveryUpdate),
- subtype: Some("unknown"),
- category: Some("other"),
- component: Some("provider"),
- operation: Some("retry"),
- stage: Some("model_request"),
- retry_attempt: Some(u64::from(*attempt)),
- recovery_action: Some("automatic_retry"),
- recovery_outcome: Some("success"),
- ..Default::default()
- }
- .track(&self.client);
- }
- // The failed model call already counted its own chain
- // link at its `MessageEnd`; the success resets the
- // chain (the give-up never double-counts).
- state.consecutive_failure_count = 0;
+ run.retry_count += 1;
+ run.retry_wait_ms += *delay_ms;
+ run.retry_pending = true;
+ if matches!(reason, super::auto_retry::RetryStartReason::Backup { .. }) {
+ run.failover_count += 1;
}
}
+ AutoRetryEvent::End { .. } => run.retry_pending = false,
}
}
- /// `agent feature outcome` (v2, #2117): a feature attempt's observed
- /// result at a session-engine seam; `configuration_choice` carries
- /// the fixed choice for fixed-choice commands.
+ /// A feature attempt's observed result at a session-engine seam,
+ /// counted as `feature_<name>_<outcome>_count` on `agent session
+ /// ended`. The configuration choice is not reported.
pub fn note_feature_outcome(
&self,
feature_name: &'static str,
outcome: &'static str,
- configuration_choice: Option<&'static str>,
+ _configuration_choice: Option<&'static str>,
) {
- pa_telemetry::AgentFeatureOutcome {
- feature_id: uuid(),
- feature_name,
- outcome,
- duration_ms: None,
- configuration_choice,
+ if let Some(key) = pa_telemetry::feature_outcome_key(feature_name, outcome) {
+ self.counters
+ .with(|values| *values.feature_outcomes.entry(key).or_default() += 1);
}
- .track(&self.client);
}
/// Finalize any active run, emit `agent session ended`, and flush.
/// The host calls this at session close (TUI exit, worker shutdown,
/// kill); the `ended` flag makes a second close path a no-op, matching
- /// the TS single `registerDisposeCallback` firing.
+ /// the TS single `registerDisposeCallback` firing. A run still open
+ /// across an opt-out severs before the finalize, so an off window's
+ /// run never reports after a re-enable.
///
/// # Errors
///
@@ -462,6 +621,13 @@ impl SessionTelemetry {
}
{
let mut state = self.state.lock().expect("telemetry state poisoned");
+ // Session close is the last recording seam: a run still open
+ // when the cached decision says off severs here instead of
+ // finalizing; the client's flush drops whatever the
+ // mid-turn opt-out already queued.
+ if !state.recording {
+ sever_off_period_run(&mut state);
+ }
finalize_run(&self.client, &self.execution_mode, &mut state);
}
let mut properties = self.session_properties();
@@ -496,7 +662,11 @@ impl SessionTelemetry {
// crash never reaches it, and the archive path emits
// `session archived` first.
properties.set("terminal_outcome", Value::from("success"));
+ properties.set("retry_count", Value::from(totals.retry_count));
+ properties.set("failover_count", Value::from(totals.failover_count));
+ properties.set("model_error_count", Value::from(totals.model_error_count));
}
+ self.counters.write_into(&mut properties);
self.client.track("agent session ended", properties);
self.client.flush().await
}
@@ -519,53 +689,35 @@ impl SessionTelemetry {
self.client.track("session archived", properties);
}
- /// `skill used`: a `/skill:<name>` submission expanded into its skill
- /// block. Feed from the `AgentSession::prompt_with_images` expansion
- /// seam; `source` reports how the invocation arrived (`prompt`,
- /// `steer`, `follow_up`).
- pub fn note_skill_used(&self, skill_name: &str, skill_kind: &str, source: &str) {
- let mut properties = self.session_properties();
- properties.set("skill_name", Value::from(skill_name));
- properties.set("skill_kind", Value::from(skill_kind));
- properties.set("source", Value::from(source));
- self.client.track("skill used", properties);
+ /// A `/skill:<name>` submission expanded into its skill block (the
+ /// `AgentSession::prompt_with_images` expansion seam), counted as
+ /// `skill_use_count` on `agent session ended`; the skill name never
+ /// uploads.
+ pub fn note_skill_used(&self) {
+ self.counters.with(|values| values.skill_use_count += 1);
}
- /// `rlm child usage attributed` (schema v1): one durable child-usage
- /// attribution row landed in the parent session (the RLM producer's
- /// flush). Primitives only — the origin label and the batch's token
- /// counts and cost; never prompt, session, or file content.
+ /// One durable child-usage attribution row landed in the parent
+ /// session (the RLM producer's flush), summed into the `rlm_child_*`
+ /// counters on `agent session ended`.
pub fn note_child_usage_attributed(
&self,
- origin: &str,
input_tokens: u64,
output_tokens: u64,
cache_read_tokens: u64,
cache_write_tokens: u64,
cost: f64,
) {
- let mut properties = self.session_properties();
- properties.set("origin", Value::from(origin));
- properties.set("input_tokens", Value::from(input_tokens));
- properties.set("output_tokens", Value::from(output_tokens));
- properties.set("cache_read_tokens", Value::from(cache_read_tokens));
- properties.set("cache_write_tokens", Value::from(cache_write_tokens));
- properties.set(
- "cost",
- Value::from(
- serde_json::Number::from_f64(cost).unwrap_or_else(|| serde_json::Number::from(0)),
- ),
- );
- self.client.track("rlm child usage attributed", properties);
- }
-
- /// `agent command used`: builtin session commands only, canonical name.
- /// Feed from `session_commands::execute_session_command` (TS
- /// `captureAgentCommandUsed`).
- pub fn note_command_used(&self, command_name: &str) {
- let mut properties = self.session_properties();
- properties.set("command_name", Value::from(command_name));
- self.client.track("agent command used", properties);
+ self.counters.with(|values| {
+ values.rlm_child_usage_count += 1;
+ values.rlm_child_input_tokens += input_tokens;
+ values.rlm_child_output_tokens += output_tokens;
+ values.rlm_child_cache_read_tokens += cache_read_tokens;
+ values.rlm_child_cache_write_tokens += cache_write_tokens;
+ if cost.is_finite() && cost > 0.0 {
+ values.rlm_child_cost += cost;
+ }
+ });
}
/// Base properties + `session_id` for per-event properties.
@@ -586,9 +738,36 @@ fn handle_event(
event: AgentEvent,
) {
let mut state = state.lock().expect("telemetry state poisoned");
+ // The switch is asked at the turn boundaries only: a run or turn
+ // start refreshes the cached decision, every other event consults
+ // the cache, and the client's flush drops everything queued while
+ // the switch is off. While recording is off nothing records, and the
+ // run severs: its facts never enter the aggregates, so a later
+ // enable can neither complete it nor merge the next run into it.
+ if matches!(event, AgentEvent::AgentStart | AgentEvent::TurnStart) {
+ observe_turn_boundary(&mut state);
+ if !state.recording {
+ return;
+ }
+ } else if !state.recording {
+ sever_off_period_run(&mut state);
+ return;
+ }
let now = (state.now)();
match event {
AgentEvent::AgentStart => {
+ // A retried attempt continues its turn's run (TS keeps one run
+ // across `auto_retry_start`: `activeRun ??= ...`).
+ if let Some(run) = state.active_run.as_mut().filter(|run| run.retry_pending) {
+ run.retry_pending = false;
+ run.ended = false;
+ run.ended_at = None;
+ // The failed call is behind a retry now: the run's cost
+ // stays reported (with the failed attempts' usage
+ // included) unless the final attempt fails too.
+ run.usage_complete = true;
+ return;
+ }
// The previous run finalizes here (not at AgentEnd): a post-run
// compaction drained between AgentEnd and this start must land in
// that run, exactly like the TS turn-action window. A missing
@@ -613,9 +792,10 @@ fn handle_event(
failover_count: 0,
usage: UsageTotals::default(),
last_assistant: None,
+ retry_pending: false,
run_id: uuid(),
run_index,
- run_started_pending: true,
+ trigger_pending: true,
trigger: RunTrigger::Unknown,
first_reasoning_ms: None,
run_to_first_text_ms: None,
@@ -626,6 +806,10 @@ fn handle_event(
successful_model_call_count: 0,
usage_complete: true,
cost_usd: 0.0,
+ model_latencies: Vec::new(),
+ model_error_count: 0,
+ error_category_counts: std::collections::BTreeMap::new(),
+ compaction_duration_ms: 0,
tool_summary: HashMap::new(),
});
}
@@ -634,7 +818,7 @@ fn handle_event(
state.totals.prompt_count += 1;
// A prompt-run's user message lands right after
// `AgentStart`: the run's trigger is a fresh prompt.
- resolve_run_started(client, &mut state, RunTrigger::Prompt);
+ resolve_trigger(&mut state, RunTrigger::Prompt);
}
}
AgentEvent::TurnStart => {
@@ -654,7 +838,7 @@ fn handle_event(
// A continuation-run's first event is a model event (no
// user message ever lands inside it): the retry/goal
// re-entry disambiguates the trigger.
- resolve_run_started(client, &mut state, RunTrigger::Continuation);
+ resolve_trigger(&mut state, RunTrigger::Continuation);
let Some(run) = state.active_run.as_mut() else {
return;
};
@@ -712,9 +896,16 @@ fn handle_event(
// A continuation-run without stream events (a non-streamed
// response) still disambiguates at its first assistant
// message end.
- resolve_run_started(client, &mut state, RunTrigger::Continuation);
+ resolve_trigger(&mut state, RunTrigger::Continuation);
let is_error = assistant.stop_reason == StopReason::Error;
- let error_message = is_error.then(|| assistant.error_message.clone()).flatten();
+ let category = error_category(Some(&assistant))
+ .as_str()
+ .and_then(|category| {
+ pa_telemetry::ERROR_CATEGORIES
+ .iter()
+ .find(|known| **known == category)
+ .copied()
+ });
let cost_total = assistant.usage.cost.total;
if let Some(run) = state.active_run.as_mut() {
run.usage.add(&assistant.usage);
@@ -723,66 +914,19 @@ fn handle_event(
let latency = now.saturating_sub(turn_started);
run.model_latency_ms += latency;
run.max_model_latency_ms = run.max_model_latency_ms.max(latency);
+ run.model_latencies.push(latency);
}
if is_error {
run.usage_complete = false;
+ run.model_error_count += 1;
+ if let Some(category) = category {
+ *run.error_category_counts.entry(category).or_default() += 1;
+ }
} else {
run.successful_model_call_count += 1;
}
run.cost_usd += cost_total;
}
- if is_error {
- // The error occurrence: classification only, fixed
- // diagnostics; the raw provider text never uploads.
- let run_started = state.active_run.as_ref().map_or(now, |run| run.started_at);
- state.consecutive_failure_count += 1;
- let error_id = uuid();
- let classification =
- classify_error_message(error_message.as_deref().unwrap_or_default());
- let raw_length = error_message
- .as_deref()
- .map_or(0, |message| message.chars().count() as u64);
- let mut agent_error = AgentError {
- error_id: error_id.clone(),
- kind: Some(ErrorEventKind::Occurrence),
- subtype: Some(classification.subtype),
- category: Some(classification.category),
- code: classification.code,
- http_status: classification.http_status,
- classification_source: Some(classification.classification_source),
- diagnostic_message: Some(classification.diagnostic),
- component: Some("provider"),
- operation: Some("stream"),
- stage: Some("model_stream"),
- retryable: Some(classification.retryable),
- consecutive_failure_count: Some(state.consecutive_failure_count),
- error_message_length: Some(raw_length),
- error_message_length_lower_bound: Some(false),
- error_message_truncated: Some(false),
- error_message_redacted: Some(classification.safe_message.is_none()),
- ..Default::default()
- };
- if let Some((source, message)) = classification.safe_message {
- agent_error.error_message = Some(message);
- agent_error.error_message_source = Some(source);
- }
- agent_error.track(client);
- state.active_error = Some(ActiveError { error_id });
- // The `time_to_error` timing stage measures the failed
- // run window to its failure moment.
- AgentTiming {
- stage: TimingStage::TimeToError,
- duration_ms: Some(now.saturating_sub(run_started)),
- outcome: Some("error"),
- tool_category: None,
- timing_origin: Some("worker_run"),
- }
- .track(client);
- } else {
- // A successful model call clears the consecutive-failure
- // chain (the retry evidence on the next occurrence).
- state.consecutive_failure_count = 0;
- }
}
}
AgentEvent::ToolExecutionStart { tool_call_id, .. } => {
@@ -805,56 +949,9 @@ fn handle_event(
run.tool_duration_ms += duration_ms;
let tool_stats = run.tool_summary.entry(category).or_default();
tool_stats.calls += 1;
- if is_error {
- tool_stats.failures += 1;
- tool_stats.last_call_failed = true;
- } else {
- if tool_stats.last_call_failed {
- tool_stats.recovered += 1;
- }
- tool_stats.last_call_failed = false;
- }
+ tool_stats.failures += u64::from(is_error);
tool_stats.duration_ms += duration_ms;
- }
- state.totals.tool_call_count += 1;
- // `tool executed` (v1): tool name + duration + outcome.
- let mut properties = base_properties(execution_mode);
- properties.set("session_id", Value::from(state.session_id.as_str()));
- properties.set("tool_name", Value::from(tool_name.as_str()));
- properties.set("duration_ms", Value::from(duration_ms));
- properties.set("is_error", Value::from(is_error));
- client.track("tool executed", properties);
- // `agent timing` (v2): the tool stage, per execution.
- AgentTiming {
- stage: TimingStage::Tool,
- duration_ms: Some(duration_ms),
- outcome: Some(if is_error { "error" } else { "success" }),
- tool_category: Some(category),
- timing_origin: Some("worker_action"),
- }
- .track(client);
- if is_error {
- // A tool failure is an error occurrence too: component
- // `tools`, operation `execute`, stage `tool_execution`.
- // The tool output never uploads (privacy contract), so the
- // subtype is unknown. Tool failures never touch the
- // model-failure chain (the consecutive counter is the
- // provider chain's own signal).
- AgentError {
- error_id: uuid(),
- kind: Some(ErrorEventKind::Occurrence),
- subtype: Some("unknown"),
- category: Some("other"),
- diagnostic_message: Some(
- "An error occurred; private error details were omitted.",
- ),
- component: Some("tools"),
- operation: Some("execute"),
- stage: Some("tool_execution"),
- retryable: Some(false),
- ..Default::default()
- }
- .track(client);
+ tool_stats.max_duration_ms = tool_stats.max_duration_ms.max(duration_ms);
}
}
AgentEvent::AgentEnd { .. } => {
@@ -865,30 +962,19 @@ fn handle_event(
}
// TurnEnd carries no facts the TS subscriber used (turn_count comes
// from TurnStart); ToolExecutionUpdate is mid-execution progress.
+ // Both are still run-scoped events: while the cached decision is
+ // off they sever (a tool whose execution spans an opt-out observed
+ // at a boundary never counts into a surviving run).
AgentEvent::TurnEnd { .. } | AgentEvent::ToolExecutionUpdate { .. } => {}
}
}
-/// Fire the pending `agent run started` when the trigger disambiguated.
-/// The event's moment is always the run's `AgentStart` (the
-/// `MessageStart`/model-event that names the trigger arrives within the
-/// same run window, microseconds later).
-fn resolve_run_started(client: &TelemetryClient, state: &mut TelemetryState, trigger: RunTrigger) {
- let Some(run) = state.active_run.as_mut() else {
- return;
- };
- if !run.run_started_pending {
- return;
- }
- run.run_started_pending = false;
- run.trigger = trigger;
- AgentRunStarted {
- session_id: state.session_id.clone(),
- run_id: run.run_id.clone(),
- run_index: run.run_index,
- trigger,
+/// Record the run's trigger the first time it disambiguates.
+fn resolve_trigger(state: &mut TelemetryState, trigger: RunTrigger) {
+ if let Some(run) = state.active_run.as_mut().filter(|run| run.trigger_pending) {
+ run.trigger_pending = false;
+ run.trigger = trigger;
}
- .track(client);
}
/// Finalize the active run and emit `agent run completed` (TS
@@ -914,43 +1000,9 @@ fn finalize_run_locked(client: &TelemetryClient, execution_mode: &str, state: &m
}
state.totals.usage.merge(&run.usage);
- // A run window that never disambiguated its trigger (no user message,
- // no model event - an emitter edge) still reports `agent run started`
- // with the unknown trigger; the pair never goes missing.
- if run.run_started_pending {
- run.run_started_pending = false;
- AgentRunStarted {
- session_id: state.session_id.clone(),
- run_id: run.run_id.clone(),
- run_index: run.run_index,
- trigger: RunTrigger::Unknown,
- }
- .track(client);
- }
-
- // `agent tool summary` (v2): one event per tool category the run used.
- for (category, stats) in &run.tool_summary {
- AgentToolSummary {
- session_id: state.session_id.clone(),
- run_id: run.run_id.clone(),
- tool_category: *category,
- call_count: stats.calls,
- failure_count: stats.failures,
- duration_ms: Some(stats.duration_ms),
- recovered_count: Some(stats.recovered),
- }
- .track(client);
- }
-
- // The `stream_gap` timing stage: the run's largest quiet stretch.
- AgentTiming {
- stage: TimingStage::StreamGap,
- duration_ms: run.max_stream_gap_ms,
- outcome: Some("success"),
- tool_category: None,
- timing_origin: Some("worker_run"),
- }
- .track(client);
+ state.totals.retry_count += run.retry_count;
+ state.totals.failover_count += run.failover_count;
+ state.totals.model_error_count += run.model_error_count;
let mut properties = base_properties(execution_mode);
properties.set("session_id", Value::from(state.session_id.as_str()));
@@ -1036,9 +1088,55 @@ fn finalize_run_locked(client: &TelemetryClient, execution_mode: &str, state: &m
properties.set("tool_duration_ms", Value::from(run.tool_duration_ms));
properties.set("retry_wait_ms", Value::from(run.retry_wait_ms));
properties.set("max_stream_gap_ms", opt_value(run.max_stream_gap_ms));
+ properties.set(
+ "compaction_duration_ms",
+ Value::from(run.compaction_duration_ms),
+ );
+ properties.set(
+ "model_latency_p50_ms",
+ opt_value(median(&mut run.model_latencies)),
+ );
+ properties.set("model_error_count", Value::from(run.model_error_count));
+ for (category, count) in &run.error_category_counts {
+ properties.set(&format!("error_{category}_count"), Value::from(*count));
+ }
+ // Per built-in tool by name; every MCP and custom tool folds into the
+ // `mcp_tool_*` / `custom_tool_*` aggregates (no raw tool names).
+ for (category, stats) in &run.tool_summary {
+ let prefix = match category {
+ ToolCategory::Mcp => "mcp_tool".to_string(),
+ ToolCategory::Custom | ToolCategory::Unknown => "custom_tool".to_string(),
+ builtin => format!("tool_{}", builtin.as_str()),
+ };
+ for (suffix, value) in [
+ ("call_count", stats.calls),
+ ("error_count", stats.failures),
+ ("duration_ms", stats.duration_ms),
+ ("max_duration_ms", stats.max_duration_ms),
+ ] {
+ let key = format!("{prefix}_{suffix}");
+ let total = properties.get(&key).and_then(Value::as_u64).unwrap_or(0);
+ let value = if suffix == "max_duration_ms" {
+ total.max(value)
+ } else {
+ total + value
+ };
+ properties.set(&key, Value::from(value));
+ }
+ }
client.track("agent run completed", properties);
}
+/// The median of the run's model-call latencies (the lower middle for an
+/// even count); `None` without calls.
+fn median(values: &mut [u64]) -> Option<u64> {
+ if values.is_empty() {
+ return None;
+ }
+ values.sort_unstable();
+ Some(values[(values.len() - 1) / 2])
+}
+
/// The #2117 `terminal_outcome` vocabulary: the legacy run outcome
/// (`success`/`error`/`aborted`) onto the terminal vocabulary (the legacy
/// `aborted` is the terminal `cancelled`).
@@ -1063,13 +1161,12 @@ fn stop_reason(last_assistant: Option<&AssistantMessage>) -> &'static str {
}
}
-/// Build the product telemetry client from settings (opt-in already
-/// resolved by the caller): `PostHog` sink when endpoint+key are configured
-/// (env `PRIME_AGENT_TELEMETRY_ENDPOINT`/`_API_KEY` override settings
-/// `telemetry.posthog.*`), the no-op sink when they are not (the operator
-/// supplies values at deploy time), plus the local JSONL transparency
-/// mirror (default on, `telemetry.localMirror` disables it). Never fails:
-/// a broken install id falls back to a no-op client (TS parity — capture
+/// Build the product telemetry client from settings: the Prime Intellect
+/// analytics sink (the TS endpoint and wire format; none in debug builds,
+/// see [`telemetry_endpoint`]) plus the local JSONL transparency mirror
+/// (default on, `telemetry.localMirror` disables it), behind the live
+/// [`telemetry_switch`] re-read before every delivery pass. Never fails: a
+/// broken install id falls back to a no-op client (TS parity: capture
/// disables itself when the installation identity cannot be created).
pub fn build_client(
settings: &crate::settings::SettingsManager,
@@ -1081,13 +1178,8 @@ pub fn build_client(
Ok(id) => {
config.install_id = id;
let mut sinks: Vec<Arc<dyn pa_telemetry::TelemetrySink>> = Vec::new();
- let endpoint = posthog_endpoint(settings);
- if let Some(endpoint) = endpoint {
- sinks.push(Arc::new(pa_telemetry::PostHogSink::new(&endpoint)));
- } else {
- // Empty configuration: events queue nowhere (no-op), the
- // same posture an opt-out installs.
- sinks.push(Arc::new(pa_telemetry::NoopSink));
+ if let Some(endpoint) = telemetry_endpoint() {
+ sinks.push(Arc::new(pa_telemetry::AnalyticsSink::new(endpoint)));
}
let local_mirror = settings
.settings()
@@ -1099,6 +1191,12 @@ pub fn build_client(
sinks.push(Arc::new(pa_telemetry::FileSink::new(agent_dir)));
}
config.sinks = sinks;
+ // `/telemetry off` (or a settings edit) applies to running
+ // clients at their next delivery pass, no restart needed.
+ let settings = settings.reopen();
+ config.enabled = Some(Arc::new(move || {
+ telemetry_switch(&settings.reopen()).enabled()
+ }));
}
Err(error) => {
tracing::warn!(error = %error, "telemetry install id unavailable; telemetry disabled");
@@ -1113,19 +1211,20 @@ pub fn build_client(
})
}
-/// Env overrides first, then settings `telemetry.posthog`.
-fn posthog_endpoint(
- settings: &crate::settings::SettingsManager,
-) -> Option<pa_telemetry::PostHogEndpoint> {
- if let Some(endpoint) = pa_telemetry::PostHogEndpoint::from_env() {
- return Some(endpoint);
- }
- let posthog = settings.settings().telemetry.as_ref()?.posthog.as_ref()?;
- let (endpoint, api_key) = (posthog.endpoint.as_deref()?, posthog.api_key.as_deref()?);
- if endpoint.trim().is_empty() || api_key.trim().is_empty() {
- return None;
+/// The recording seams' live opt-out switch: the same env-then-settings
+/// resolution the delivery pass applies ([`telemetry_switch`]), resolved
+/// live at the turn boundaries: an off (or an on) applies to the
+/// recording seams at the next boundary, exactly like the client's
+/// delivery gate applies it at the flush.
+#[must_use]
+pub fn telemetry_enabled_switch(
+ cwd: &std::path::Path,
+ agent_dir: &std::path::Path,
+) -> RecordingSwitch {
+ let settings = crate::settings::SettingsManager::create(cwd, agent_dir);
+ RecordingSwitch {
+ enabled: Arc::new(move || telemetry_switch(&settings.reopen()).enabled()),
}
- Some(pa_telemetry::PostHogEndpoint::new(endpoint, api_key))
}
fn uuid() -> String {
diff --git a/crates/pa-core/src/session_engine/telemetry/status.rs b/crates/pa-core/src/session_engine/telemetry/status.rs
new file mode 100644
index 0000000000..d99e078193
--- /dev/null
+++ b/crates/pa-core/src/session_engine/telemetry/status.rs
@@ -0,0 +1,256 @@
+//! The telemetry on/off switch and its explanation: one resolution shared by
+//! the live client switch, the CLI opt-out check, `/telemetry`, and
+//! `prime-agent telemetry`.
+
+use std::path::Path;
+
+use pa_telemetry::parse_bool_override;
+
+use crate::settings::SettingsManager;
+
+/// What decides whether telemetry is on, in precedence order (TS
+/// `isTelemetryEnabled`): `PI_OFFLINE` / `DO_NOT_TRACK` force off,
+/// `PRIME_AGENT_TELEMETRY` forces either way, then settings
+/// `telemetry.enabled`, then the default (on).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TelemetrySwitch {
+ /// Nothing set: on.
+ Default,
+ /// Settings `telemetry.enabled` (any scope false turns it off).
+ Settings(bool),
+ /// An environment variable decides.
+ Env { var: &'static str, enabled: bool },
+}
+
+impl TelemetrySwitch {
+ #[must_use]
+ pub fn enabled(self) -> bool {
+ match self {
+ Self::Default => true,
+ Self::Settings(enabled) | Self::Env { enabled, .. } => enabled,
+ }
+ }
+
+ /// Why it is on or off, in plain words.
+ #[must_use]
+ pub fn reason(self) -> String {
+ match self {
+ Self::Default => "on by default".to_string(),
+ Self::Settings(true) => "turned on in settings".to_string(),
+ Self::Settings(false) => "turned off in settings".to_string(),
+ Self::Env {
+ var: "PRIME_AGENT_TELEMETRY",
+ enabled,
+ } => format!(
+ "forced {} by PRIME_AGENT_TELEMETRY={}",
+ if enabled { "on" } else { "off" },
+ if enabled { "1" } else { "0" }
+ ),
+ Self::Env { var, .. } => format!("forced off by {var}"),
+ }
+ }
+}
+
+/// Resolve the switch from the environment and `settings`.
+#[must_use]
+pub fn telemetry_switch(settings: &SettingsManager) -> TelemetrySwitch {
+ switch_from(
+ |var| std::env::var(var).ok(),
+ settings.telemetry_enabled_setting(),
+ )
+}
+
+fn switch_from(env: impl Fn(&str) -> Option<String>, setting: Option<bool>) -> TelemetrySwitch {
+ for var in ["PI_OFFLINE", "DO_NOT_TRACK"] {
+ if parse_bool_override(env(var).as_deref()) == Some(true) {
+ return TelemetrySwitch::Env {
+ var,
+ enabled: false,
+ };
+ }
+ }
+ if let Some(enabled) = parse_bool_override(env("PRIME_AGENT_TELEMETRY").as_deref()) {
+ return TelemetrySwitch::Env {
+ var: "PRIME_AGENT_TELEMETRY",
+ enabled,
+ };
+ }
+ setting.map_or(TelemetrySwitch::Default, TelemetrySwitch::Settings)
+}
+
+/// Where events go: the platform endpoint in release builds, nowhere in
+/// debug builds (every `cargo test` and dev run), so tests and local
+/// development never reach production analytics.
+#[must_use]
+pub fn telemetry_endpoint() -> Option<&'static str> {
+ (!cfg!(debug_assertions)).then_some(pa_telemetry::ANALYTICS_ENDPOINT)
+}
+
+/// The `status` report: state and why, the endpoint, the installation id.
+#[must_use]
+pub fn telemetry_status_text(settings: &SettingsManager, agent_dir: &Path) -> String {
+ let switch = telemetry_switch(settings);
+ let state = if switch.enabled() { "on" } else { "off" };
+ let endpoint = telemetry_endpoint().unwrap_or("nowhere (development build)");
+ let installation_id = pa_telemetry::existing_install_id(agent_dir)
+ .unwrap_or_else(|| "not created yet".to_string());
+ format!(
+ "Telemetry is {state} ({}).\nEndpoint: {endpoint}\nInstallation id: {installation_id}",
+ switch.reason()
+ )
+}
+
+/// Persist `telemetry.enabled` (the TS key: global `settings.json`
+/// `{"telemetry": {"enabled": <bool>}}`) and report the result. Running
+/// clients pick the change up at their next delivery pass. When something
+/// else still decides (an environment variable, a project setting), the
+/// report says so instead of claiming the requested state.
+///
+/// # Errors
+///
+/// Returns an error when the global settings file cannot be written, or
+/// when the telemetry-state lock stays contended past its retry window:
+/// the command fails before anything changes (an opt-out whose epoch
+/// cannot move must not report success).
+pub fn set_telemetry_enabled_text(
+ settings: &mut SettingsManager,
+ agent_dir: &Path,
+ enabled: bool,
+) -> anyhow::Result<String> {
+ // The opt-out is the settings write itself and cannot fail on
+ // telemetry state: the recording seams re-check the live switch at
+ // turn boundaries and the client drops every queued event while the
+ // switch is off, which covers the off period without a persisted
+ // epoch — so the command never touches (and never mints) the
+ // install-id state.
+ settings.set_telemetry_enabled(enabled)?;
+ let switch = telemetry_switch(&settings.reopen());
+ let requested = if enabled { "on" } else { "off" };
+ let headline = if switch.enabled() == enabled {
+ if enabled {
+ "Telemetry turned on.".to_string()
+ } else {
+ "Telemetry turned off. Nothing more is sent; unsent events are dropped.".to_string()
+ }
+ } else {
+ format!(
+ "Saved telemetry {requested} in settings, but it stays {} ({}).",
+ if switch.enabled() { "on" } else { "off" },
+ match switch {
+ TelemetrySwitch::Settings(_) => "a project setting overrides it".to_string(),
+ other => other.reason(),
+ }
+ )
+ };
+ Ok(format!(
+ "{headline}\n{}",
+ telemetry_status_text(settings, agent_dir)
+ ))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn env<'a>(pairs: &'a [(&'a str, &'a str)]) -> impl Fn(&str) -> Option<String> + 'a {
+ move |var| {
+ pairs
+ .iter()
+ .find(|(name, _)| *name == var)
+ .map(|(_, value)| (*value).to_string())
+ }
+ }
+
+ #[test]
+ fn the_switch_follows_the_ts_precedence() {
+ assert_eq!(switch_from(env(&[]), None), TelemetrySwitch::Default);
+ assert_eq!(
+ switch_from(env(&[]), Some(false)),
+ TelemetrySwitch::Settings(false)
+ );
+ assert_eq!(
+ switch_from(env(&[("PRIME_AGENT_TELEMETRY", "1")]), Some(false)),
+ TelemetrySwitch::Env {
+ var: "PRIME_AGENT_TELEMETRY",
+ enabled: true
+ }
+ );
+ assert_eq!(
+ switch_from(
+ env(&[("PRIME_AGENT_TELEMETRY", "1"), ("DO_NOT_TRACK", "1")]),
+ None
+ ),
+ TelemetrySwitch::Env {
+ var: "DO_NOT_TRACK",
+ enabled: false
+ }
+ );
+ assert_eq!(
+ switch_from(env(&[("PI_OFFLINE", "true")]), Some(true)).reason(),
+ "forced off by PI_OFFLINE"
+ );
+ assert_eq!(
+ switch_from(env(&[("PRIME_AGENT_TELEMETRY", "0")]), None).reason(),
+ "forced off by PRIME_AGENT_TELEMETRY=0"
+ );
+ // Falsy DO_NOT_TRACK is no override.
+ assert_eq!(
+ switch_from(env(&[("DO_NOT_TRACK", "0")]), None),
+ TelemetrySwitch::Default
+ );
+ }
+
+ #[test]
+ fn on_and_off_round_trip_through_the_ts_settings_key() {
+ let dir = tempfile::tempdir().unwrap();
+ let agent_dir = dir.path().join("agent");
+ let mut settings = SettingsManager::create(dir.path(), &agent_dir);
+ assert_eq!(settings.telemetry_enabled_setting(), None);
+
+ set_telemetry_enabled_text(&mut settings, &agent_dir, false).unwrap();
+ let written: serde_json::Value = serde_json::from_str(
+ &std::fs::read_to_string(agent_dir.join("settings.json")).unwrap(),
+ )
+ .unwrap();
+ assert_eq!(written["telemetry"]["enabled"], false);
+ let reread = SettingsManager::create(dir.path(), &agent_dir);
+ assert_eq!(reread.telemetry_enabled_setting(), Some(false));
+ assert!(!reread.get_telemetry_enabled());
+
+ set_telemetry_enabled_text(&mut settings, &agent_dir, true).unwrap();
+ let reread = SettingsManager::create(dir.path(), &agent_dir);
+ assert_eq!(reread.telemetry_enabled_setting(), Some(true));
+ assert!(reread.get_telemetry_enabled());
+ }
+
+ #[test]
+ fn a_ts_written_switch_reads_back() {
+ let dir = tempfile::tempdir().unwrap();
+ let agent_dir = dir.path().join("agent");
+ std::fs::create_dir_all(&agent_dir).unwrap();
+ std::fs::write(
+ agent_dir.join("settings.json"),
+ r#"{ "telemetry": { "enabled": false, "noticeShown": true } }"#,
+ )
+ .unwrap();
+ let settings = SettingsManager::create(dir.path(), &agent_dir);
+ assert_eq!(settings.telemetry_enabled_setting(), Some(false));
+ }
+
+ #[test]
+ fn status_names_the_endpoint_and_the_installation_id() {
+ let dir = tempfile::tempdir().unwrap();
+ let agent_dir = dir.path().join("agent");
+ let settings = SettingsManager::create(dir.path(), &agent_dir);
+ let before = telemetry_status_text(&settings, &agent_dir);
+ assert!(before.contains("Installation id: not created yet"));
+ assert!(
+ !agent_dir.join("telemetry.json").exists(),
+ "status never creates an id"
+ );
+ let id = pa_telemetry::install_id(&agent_dir).unwrap();
+ let after = telemetry_status_text(&settings, &agent_dir);
+ assert!(after.contains(&format!("Installation id: {id}")));
+ assert!(after.contains("Endpoint: nowhere (development build)"));
+ }
+}
diff --git a/crates/pa-core/src/session_engine/telemetry/tests.rs b/crates/pa-core/src/session_engine/telemetry/tests.rs
index 9e392bb68f..3561b45abf 100644
--- a/crates/pa-core/src/session_engine/telemetry/tests.rs
+++ b/crates/pa-core/src/session_engine/telemetry/tests.rs
@@ -12,6 +12,52 @@ use pa_telemetry::{MockSink, TelemetryClient, TelemetryClientConfig};
use super::*;
+/// Tests that resolve the env-gated switch need the three override vars
+/// cleared (the Cargo test config sets `DO_NOT_TRACK`); restore after.
+/// The env is process-wide, so these tests (and the packages env tests)
+/// serialize through the shared env lock while they hold it.
+const TELEMETRY_ENV_VARS: [&str; 3] = ["DO_NOT_TRACK", "PI_OFFLINE", "PRIME_AGENT_TELEMETRY"];
+
+struct CleanTelemetryEnv {
+ saved: Vec<(&'static str, Option<String>)>,
+ _env_lock: std::sync::MutexGuard<'static, ()>,
+}
+
+impl Default for CleanTelemetryEnv {
+ fn default() -> Self {
+ // Held first: the vars may not be touched while another env test
+ // runs.
+ let env_lock = crate::packages::test_support::ENV_MUTEX
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ let saved = TELEMETRY_ENV_VARS
+ .iter()
+ .map(|var| {
+ let value = std::env::var(var).ok();
+ std::env::remove_var(var);
+ (*var, value)
+ })
+ .collect();
+ Self {
+ saved,
+ _env_lock: env_lock,
+ }
+ }
+}
+
+impl Drop for CleanTelemetryEnv {
+ fn drop(&mut self) {
+ // The manual drop runs before the field drops: the restore lands
+ // while the env lock is still held.
+ for (var, value) in self.saved.drain(..) {
+ match value {
+ Some(value) => std::env::set_var(var, value),
+ None => std::env::remove_var(var),
+ }
+ }
+ }
+}
+
/// Controllable clock: tests move it between emits.
#[derive(Clone, Default)]
struct TestClock {
@@ -61,8 +107,8 @@ fn fixture_with_clock(clock: TestClock) -> Fixture {
totals: SessionTotals::default(),
active_run: None,
tool_starts: HashMap::new(),
- active_error: None,
- consecutive_failure_count: 0,
+ telemetry_enabled: None,
+ recording: true,
now,
}));
Fixture {
@@ -411,106 +457,131 @@ fn provider_and_model_categories() {
assert_eq!(model_category("my-finetune"), "custom");
}
-/// `tool executed` events: tool name + duration + outcome, no arguments
-/// or results, per-execution.
+/// Tool calls fold into the run: built-in tools by name, MCP and custom
+/// tools only as aggregates, and no raw tool name rides any event.
#[tokio::test]
-async fn tool_executed_events_carry_name_duration_outcome() {
+async fn tool_calls_fold_into_run_aggregates() {
let fixture = fixture();
+ let assistant = assistant_message();
emit(&fixture, AgentEvent::AgentStart);
- fixture.clock.set(1_000);
- let (tool_start, tool_end) = tool_execution_event("bash", false);
- emit(&fixture, tool_start);
- fixture.clock.set(1_250);
- emit(&fixture, tool_end);
- let (fail_start, fail_end) = tool_execution_event("edit", true);
- emit(&fixture, fail_start);
- fixture.clock.set(1_300);
- emit(&fixture, fail_end);
-
- let tools = event_properties(&fixture.mock, "tool executed").await;
- assert_eq!(tools.len(), 2);
- assert_eq!(tools[0]["tool_name"], serde_json::json!("bash"));
- assert_eq!(tools[0]["duration_ms"], serde_json::json!(250));
- assert_eq!(tools[0]["is_error"], serde_json::json!(false));
- assert_eq!(tools[1]["tool_name"], serde_json::json!("edit"));
- assert_eq!(tools[1]["is_error"], serde_json::json!(true));
- let all = serde_json::to_string(&fixture.mock.events()).unwrap();
- assert!(!all.contains("private command"));
- assert!(!all.contains("private tool output"));
-}
-
-/// `agent command used` events: canonical command name only.
-#[tokio::test]
-async fn command_used_event_shape() {
- let fixture = fixture();
- let telemetry = SessionTelemetry::detached(
- fixture.client.clone(),
- fixture.state.clone(),
- "interactive".to_string(),
+ emit(
+ &fixture,
+ AgentEvent::MessageStart {
+ message: user_message(),
+ },
);
- telemetry.note_command_used("compact");
- fixture.client.flush().await.unwrap();
- let commands = event_properties(&fixture.mock, "agent command used").await;
- assert_eq!(commands.len(), 1);
- assert_eq!(commands[0]["command_name"], serde_json::json!("compact"));
-}
-
-/// `skill used` events: name, kind, and arrival source; never prompt
-/// content.
-#[tokio::test]
-async fn skill_used_event_shape() {
- let fixture = fixture();
- let telemetry = SessionTelemetry::detached(
- fixture.client.clone(),
- fixture.state.clone(),
- "interactive".to_string(),
+ for (tool, is_error, start, end) in [
+ ("bash", false, 1_000, 1_040),
+ ("bash", true, 1_100, 1_110),
+ ("edit", false, 1_200, 1_205),
+ ("mcp__github__create_issue", false, 1_300, 1_350),
+ ("private-extension-tool", false, 1_400, 1_401),
+ ] {
+ let (tool_start, tool_end) = tool_execution_event(tool, is_error);
+ fixture.clock.set(start);
+ emit(&fixture, tool_start);
+ fixture.clock.set(end);
+ emit(&fixture, tool_end);
+ }
+ emit(&fixture, message_end_event(assistant));
+ emit(
+ &fixture,
+ AgentEvent::AgentEnd {
+ messages: Vec::new(),
+ },
+ );
+ emit(&fixture, AgentEvent::AgentStart);
+ let runs = event_properties(&fixture.mock, "agent run completed").await;
+ let run = &runs[0];
+ assert_eq!(run["tool_call_count"], serde_json::json!(5));
+ assert_eq!(run["tool_error_count"], serde_json::json!(1));
+ assert_eq!(run["tool_bash_call_count"], serde_json::json!(2));
+ assert_eq!(run["tool_bash_error_count"], serde_json::json!(1));
+ assert_eq!(run["tool_bash_duration_ms"], serde_json::json!(50));
+ assert_eq!(run["tool_bash_max_duration_ms"], serde_json::json!(40));
+ assert_eq!(run["tool_edit_call_count"], serde_json::json!(1));
+ assert_eq!(run["mcp_tool_call_count"], serde_json::json!(1));
+ assert_eq!(run["custom_tool_call_count"], serde_json::json!(1));
+ assert!(
+ run.get("tool_read_call_count").is_none(),
+ "unused tools stay absent"
);
- telemetry.note_skill_used("web-search", "markdown", "prompt");
- telemetry.note_skill_used("agent-message", "python", "steer");
- fixture.client.flush().await.unwrap();
- let skills = event_properties(&fixture.mock, "skill used").await;
- assert_eq!(skills.len(), 2);
- assert_eq!(skills[0]["skill_name"], serde_json::json!("web-search"));
- assert_eq!(skills[0]["skill_kind"], serde_json::json!("markdown"));
- assert_eq!(skills[0]["source"], serde_json::json!("prompt"));
- assert_eq!(skills[1]["skill_name"], serde_json::json!("agent-message"));
- assert_eq!(skills[1]["skill_kind"], serde_json::json!("python"));
- assert_eq!(skills[1]["source"], serde_json::json!("steer"));
+ let names: Vec<String> = fixture.mock.event_names();
+ assert_eq!(names, ["agent run completed"], "no per-call events");
let all = serde_json::to_string(&fixture.mock.events()).unwrap();
- assert!(!all.contains("skill content"));
+ assert!(!all.contains("github"));
+ assert!(!all.contains("private-extension-tool"));
}
-/// `rlm child usage attributed`: the origin label and the batch's
-/// primitives; the token counts and cost round-trip, and nothing
-/// else rides.
+/// Skills, RLM child usage, MCP connector use, kernel boots, and feature
+/// outcomes count into `agent session ended` instead of their own events.
#[tokio::test]
-async fn child_usage_attributed_event_shape() {
+async fn session_counters_ride_session_ended() {
let fixture = fixture();
- let telemetry = SessionTelemetry::detached(
+ let counters = Arc::new(SessionCounters::default());
+ let mut telemetry = SessionTelemetry::detached(
fixture.client.clone(),
fixture.state.clone(),
"interactive".to_string(),
);
- telemetry.note_child_usage_attributed("spawn_task", 50_208, 2_929, 0, 0, 0.008_995_7);
- fixture.client.flush().await.unwrap();
- let events = event_properties(&fixture.mock, "rlm child usage attributed").await;
- assert_eq!(events.len(), 1);
- assert_eq!(events[0]["origin"], serde_json::json!("spawn_task"));
- assert_eq!(events[0]["input_tokens"], serde_json::json!(50_208));
- assert_eq!(events[0]["output_tokens"], serde_json::json!(2_929));
- assert_eq!(events[0]["cache_read_tokens"], serde_json::json!(0));
- assert!((events[0]["cost"].as_f64().unwrap() - 0.008_995_7).abs() < 1e-9);
+ telemetry.counters = Arc::clone(&counters);
+ telemetry.note_skill_used();
+ telemetry.note_skill_used();
+ telemetry.note_child_usage_attributed(50_208, 2_929, 0, 0, 0.008_995_7);
+ counters.note_mcp_connector_use();
+ counters.note_kernel_bootstrap(true, true, 1_200);
+ counters.note_kernel_bootstrap(false, false, 300);
+ telemetry.note_feature_outcome("goal", "completed", Some("create"));
+ telemetry.note_feature_outcome("not-a-feature", "completed", None);
+ telemetry.end().await.unwrap();
+ assert_eq!(fixture.mock.event_names(), ["agent session ended"]);
+ let ended = &event_properties(&fixture.mock, "agent session ended").await[0];
+ assert_eq!(ended["skill_use_count"], serde_json::json!(2));
+ assert_eq!(ended["rlm_child_usage_count"], serde_json::json!(1));
+ assert_eq!(ended["rlm_child_input_tokens"], serde_json::json!(50_208));
+ assert_eq!(ended["rlm_child_output_tokens"], serde_json::json!(2_929));
+ assert!((ended["rlm_child_cost"].as_f64().unwrap() - 0.008_995_7).abs() < 1e-9);
+ assert_eq!(ended["mcp_connector_use_count"], serde_json::json!(1));
+ assert_eq!(ended["kernel_bootstrap_count"], serde_json::json!(2));
+ assert_eq!(ended["kernel_bootstrap_cold_count"], serde_json::json!(1));
+ assert_eq!(ended["kernel_bootstrap_failed_count"], serde_json::json!(1));
+ assert_eq!(ended["kernel_bootstrap_max_ms"], serde_json::json!(1_200));
+ assert_eq!(ended["feature_goal_completed_count"], serde_json::json!(1));
}
-/// `build_client`: settings-provided `PostHog` endpoint + the local mirror.
+/// `build_client` reuses the installation id a TS install wrote to
+/// `telemetry.json` (one user across both products) and mirrors events to
+/// the local JSONL file under that id.
#[tokio::test]
-async fn build_client_resolves_settings_posthog_and_mirror() {
+async fn build_client_reuses_the_ts_installation_id_and_mirrors() {
let dir = tempfile::tempdir().unwrap();
- let settings = crate::settings::SettingsManager::create(dir.path(), dir.path().join("agent"));
- // FileSink writes to the agent dir regardless of the PostHog sink.
- let client = build_client(&settings, &dir.path().join("agent"));
- assert!(!client.install_id().is_empty());
- assert_eq!(client.dropped_count(), 0);
+ let agent_dir = dir.path().join("agent");
+ std::fs::create_dir_all(&agent_dir).unwrap();
+ let ts_id = "6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b";
+ std::fs::write(
+ agent_dir.join("telemetry.json"),
+ format!("{{\n \"version\": 1,\n \"installationId\": \"{ts_id}\"\n}}"),
+ )
+ .unwrap();
+ let settings = crate::settings::SettingsManager::create(dir.path(), &agent_dir);
+ let client = build_client(&settings, &agent_dir);
+ assert_eq!(client.install_id(), ts_id);
+ client.track("agent started", base_properties("interactive"));
+ client.flush().await.unwrap();
+ // The live switch gates every sink, the mirror included: the repo's
+ // cargo env (`DO_NOT_TRACK=1`) keeps it off under `cargo test`.
+ let mirror = std::fs::read_to_string(agent_dir.join("telemetry.jsonl")).ok();
+ if telemetry_switch(&settings).enabled() {
+ let mirror = mirror.expect("the mirror recorded the event");
+ let line: serde_json::Value = serde_json::from_str(mirror.lines().next().unwrap()).unwrap();
+ assert_eq!(line["distinct_id"], ts_id);
+ assert_eq!(line["name"], "agent started");
+ } else {
+ assert!(
+ mirror.is_none(),
+ "nothing is recorded while telemetry is off"
+ );
+ }
}
/// Two runs in one session: totals merge, per-run events separate.
@@ -544,7 +615,7 @@ async fn multiple_runs_merge_into_session_totals() {
/// moment, with the prompt trigger when a user message drives the run
/// and a `run_index` that pairs it with the completed event.
#[tokio::test]
-async fn run_started_fires_with_prompt_trigger_and_run_index() {
+async fn the_prompt_trigger_and_run_index_ride_the_completed_run() {
let fixture = fixture();
let assistant = assistant_message();
emit(
@@ -578,18 +649,16 @@ async fn run_started_fires_with_prompt_trigger_and_run_index() {
message: user_message(),
},
);
- let starts = event_properties(&fixture.mock, "agent run started").await;
- assert_eq!(starts.len(), 2, "one per run window");
- assert_eq!(starts[0]["trigger"], serde_json::json!("prompt"));
- assert_eq!(starts[0]["run_index"], serde_json::json!(1));
- assert_eq!(starts[1]["run_index"], serde_json::json!(2));
+ assert!(
+ event_properties(&fixture.mock, "agent run started")
+ .await
+ .is_empty(),
+ "no run-start event: the trigger rides the completed run"
+ );
let runs = event_properties(&fixture.mock, "agent run completed").await;
assert_eq!(runs.len(), 1);
+ assert_eq!(runs[0]["trigger"], serde_json::json!("prompt"));
assert_eq!(runs[0]["run_index"], serde_json::json!(1));
- assert_eq!(
- starts[0]["run_id"], runs[0]["run_id"],
- "the run started/completed pair shares the run id"
- );
}
/// A continuation run (the auto-retry re-entry: no user message inside
@@ -609,185 +678,183 @@ async fn continuation_run_reports_continuation_trigger() {
},
);
emit(&fixture, AgentEvent::AgentStart);
- let starts = event_properties(&fixture.mock, "agent run started").await;
- assert_eq!(starts.len(), 1);
- assert_eq!(starts[0]["trigger"], serde_json::json!("continuation"));
+ let runs = event_properties(&fixture.mock, "agent run completed").await;
+ assert_eq!(runs.len(), 1);
+ assert_eq!(runs[0]["trigger"], serde_json::json!("continuation"));
}
-/// `agent tool summary` (v2): per-category call/failure/recovered
-/// counts and durations at run finalize; a failure later followed by a
-/// success of the same category counts as recovered.
-#[tokio::test]
-async fn tool_summary_per_category_with_recovery() {
- let fixture = fixture();
- emit(&fixture, AgentEvent::AgentStart);
- fixture.clock.set(1_000);
- let (bash_start, bash_end) = tool_execution_event("bash", false);
- emit(&fixture, bash_start);
- fixture.clock.set(1_100);
- emit(&fixture, bash_end);
- let (edit_start, edit_end) = tool_execution_event("edit", true);
- emit(&fixture, edit_start);
- fixture.clock.set(1_200);
- emit(&fixture, edit_end);
- // The recovered call: the same category fails then succeeds.
- let (edit_retry_start, edit_retry_end) = tool_execution_event("edit", false);
- emit(&fixture, edit_retry_start);
- fixture.clock.set(1_250);
- emit(&fixture, edit_retry_end);
+fn retry_start(telemetry: &SessionTelemetry, attempt: u32, delay_ms: u64, backup: bool) {
+ telemetry.note_auto_retry_event(&AutoRetryEvent::Start {
+ attempt,
+ max_attempts: 3,
+ delay_ms,
+ error_message: String::new(),
+ reason: if backup {
+ crate::session_engine::auto_retry::RetryStartReason::Backup {
+ backup_model: "backup/m".to_string(),
+ }
+ } else {
+ crate::session_engine::auto_retry::RetryStartReason::Quick
+ },
+ });
+}
+
+/// One model attempt inside the current run: the attempt's start, the
+/// model call, its end.
+fn attempt(fixture: &Fixture, message: AssistantMessage) {
+ emit(fixture, AgentEvent::AgentStart);
+ emit(fixture, AgentEvent::TurnStart);
+ emit(fixture, message_end_event(message));
emit(
- &fixture,
+ fixture,
AgentEvent::AgentEnd {
messages: Vec::new(),
},
);
- emit(&fixture, AgentEvent::AgentStart);
- let summaries = event_properties(&fixture.mock, "agent tool summary").await;
- assert_eq!(summaries.len(), 2);
- let bash = summaries
- .iter()
- .find(|summary| summary["tool_category"] == serde_json::json!("bash"))
- .expect("bash summary");
- assert_eq!(bash["call_count"], serde_json::json!(1));
- assert_eq!(bash["failure_count"], serde_json::json!(0));
- assert_eq!(bash["duration_ms"], serde_json::json!(100));
- assert_eq!(bash["recovered_count"], serde_json::json!(0));
- let edit = summaries
- .iter()
- .find(|summary| summary["tool_category"] == serde_json::json!("edit"))
- .expect("edit summary");
- assert_eq!(edit["call_count"], serde_json::json!(2));
- assert_eq!(edit["failure_count"], serde_json::json!(1));
- assert_eq!(edit["recovered_count"], serde_json::json!(1));
- assert_eq!(edit["duration_ms"], serde_json::json!(150));
- // The per-execution `agent timing` tool events fired too.
- let timings = event_properties(&fixture.mock, "agent timing").await;
- let tool_timings: Vec<_> = timings
- .iter()
- .filter(|timing| timing["stage"] == serde_json::json!("tool"))
- .collect();
- assert_eq!(tool_timings.len(), 3, "one timing event per execution");
- assert_eq!(tool_timings[0]["duration_ms"], serde_json::json!(100));
- assert_eq!(tool_timings[0]["tool_category"], serde_json::json!("bash"));
- assert_eq!(tool_timings[1]["outcome"], serde_json::json!("error"));
}
-/// `agent error` (v2): a failed model call emits one occurrence with
-/// the classification (fixed diagnostic only - never the raw provider
-/// text), and the retry's success emits the recovery update with the
-/// same error id.
+/// TS one-run-per-turn: a turn that retried twice and then succeeded is
+/// exactly one `agent run completed`, with `retry_count` 2, the success
+/// outcome of the final attempt, and the failed attempts folded into the
+/// error counters.
#[tokio::test]
-async fn error_occurrence_and_recovery_pair_by_error_id() {
+async fn retries_fold_into_one_run_that_succeeds() {
let fixture = fixture();
- let failed = assistant_with_error("API Error: 429 rate limit exceeded with /home/user/secret");
- fixture.clock.set(1_000);
- emit(&fixture, AgentEvent::AgentStart);
- emit(&fixture, AgentEvent::TurnStart);
- fixture.clock.set(1_300);
- emit(&fixture, message_end_event(failed));
- emit(
- &fixture,
- AgentEvent::AgentEnd {
- messages: Vec::new(),
- },
- );
- // The retry seam: the wait, then the recovery.
let telemetry = SessionTelemetry::detached(
fixture.client.clone(),
fixture.state.clone(),
"interactive".to_string(),
);
- telemetry.note_auto_retry_event(&AutoRetryEvent::Start {
- attempt: 1,
- max_attempts: 3,
- delay_ms: 500,
- error_message: String::new(),
- reason: crate::session_engine::auto_retry::RetryStartReason::Quick,
- });
+ let failed = assistant_with_error("API Error: 429 rate limit exceeded with /home/user/secret");
+ emit(
+ &fixture,
+ AgentEvent::MessageStart {
+ message: user_message(),
+ },
+ );
+ attempt(&fixture, failed.clone());
+ retry_start(&telemetry, 1, 500, false);
+ attempt(&fixture, failed);
+ retry_start(&telemetry, 2, 1_000, true);
+ let mut recovered = assistant_message();
+ recovered.usage.cost.total = 0.012;
+ attempt(&fixture, recovered);
telemetry.note_auto_retry_event(&AutoRetryEvent::End {
success: true,
- attempt: 1,
+ attempt: 2,
final_error: None,
restored_model: None,
});
+ telemetry.end().await.unwrap();
- let errors = event_properties(&fixture.mock, "agent error").await;
- assert_eq!(errors.len(), 2, "one occurrence + one recovery update");
- let occurrence = &errors[0];
- assert_eq!(
- occurrence["error_event_kind"],
- serde_json::json!("occurrence")
- );
- assert_eq!(
- occurrence["error_subtype"],
- serde_json::json!("rate_limited")
- );
- assert_eq!(
- occurrence["error_category"],
- serde_json::json!("rate_limit")
- );
- assert_eq!(occurrence["http_status"], serde_json::json!(429));
- assert_eq!(occurrence["component"], serde_json::json!("provider"));
- assert_eq!(occurrence["operation"], serde_json::json!("stream"));
- assert_eq!(occurrence["stage"], serde_json::json!("model_stream"));
- assert_eq!(
- occurrence["consecutive_failure_count"],
- serde_json::json!(1)
- );
+ let runs = event_properties(&fixture.mock, "agent run completed").await;
+ assert_eq!(runs.len(), 1, "one run per turn");
+ let run = &runs[0];
+ assert_eq!(run["outcome"], serde_json::json!("success"));
+ assert_eq!(run["error_category"], serde_json::Value::Null);
+ assert_eq!(run["retry_count"], serde_json::json!(2));
+ assert_eq!(run["failover_count"], serde_json::json!(1));
+ assert_eq!(run["retry_wait_ms"], serde_json::json!(1_500));
+ assert_eq!(run["model_call_count"], serde_json::json!(3));
+ assert_eq!(run["turn_count"], serde_json::json!(3));
+ assert_eq!(run["model_error_count"], serde_json::json!(2));
+ assert_eq!(run["error_rate_limit_count"], serde_json::json!(2));
+ // A recovered failure keeps the turn's cost.
+ assert_eq!(run["usage_complete"], serde_json::json!(true));
+ assert_eq!(run["estimated_cost_usd"], serde_json::json!(0.012));
+ let ended = event_properties(&fixture.mock, "agent session ended").await;
+ assert_eq!(ended[0]["run_count"], serde_json::json!(1));
+ assert_eq!(ended[0]["successful_run_count"], serde_json::json!(1));
+ assert_eq!(ended[0]["failed_run_count"], serde_json::json!(0));
+ assert_eq!(ended[0]["retry_count"], serde_json::json!(2));
// The privacy contract: no raw provider text anywhere.
let all = serde_json::to_string(&fixture.mock.events()).unwrap();
assert!(!all.contains("API Error"));
assert!(!all.contains("/home/user/secret"));
- assert_eq!(
- occurrence["diagnostic_message"],
- serde_json::json!("Provider rate limit exceeded.")
+}
+
+/// A turn whose retries are exhausted is one run with the error outcome
+/// of its final attempt.
+#[tokio::test]
+async fn exhausted_retries_are_one_failed_run() {
+ let fixture = fixture();
+ let telemetry = SessionTelemetry::detached(
+ fixture.client.clone(),
+ fixture.state.clone(),
+ "interactive".to_string(),
);
- assert_eq!(
- occurrence["error_message_redacted"],
- serde_json::json!(true)
+ let failed = assistant_with_error("network connection reset");
+ emit(
+ &fixture,
+ AgentEvent::MessageStart {
+ message: user_message(),
+ },
);
- let recovery = &errors[1];
- assert_eq!(
- recovery["error_event_kind"],
- serde_json::json!("recovery_update")
+ attempt(&fixture, failed.clone());
+ retry_start(&telemetry, 1, 500, false);
+ attempt(&fixture, failed.clone());
+ retry_start(&telemetry, 2, 500, false);
+ attempt(&fixture, failed);
+ telemetry.note_auto_retry_event(&AutoRetryEvent::End {
+ success: false,
+ attempt: 2,
+ final_error: Some("network".to_string()),
+ restored_model: None,
+ });
+ telemetry.end().await.unwrap();
+
+ let runs = event_properties(&fixture.mock, "agent run completed").await;
+ assert_eq!(runs.len(), 1, "one run per turn");
+ assert_eq!(runs[0]["outcome"], serde_json::json!("error"));
+ assert_eq!(runs[0]["error_category"], serde_json::json!("network"));
+ assert_eq!(runs[0]["retry_count"], serde_json::json!(2));
+ assert_eq!(runs[0]["model_error_count"], serde_json::json!(3));
+ assert_eq!(runs[0]["error_network_count"], serde_json::json!(3));
+ assert_eq!(runs[0]["stop_reason"], serde_json::json!("error"));
+ let ended = event_properties(&fixture.mock, "agent session ended").await;
+ assert_eq!(ended[0]["failed_run_count"], serde_json::json!(1));
+ assert_eq!(ended[0]["run_count"], serde_json::json!(1));
+}
+
+/// A retry whose wait is cancelled closes its run: the next user turn is
+/// a run of its own, not a continuation of the abandoned retry.
+#[tokio::test]
+async fn a_cancelled_retry_never_absorbs_the_next_turn() {
+ let fixture = fixture();
+ let telemetry = SessionTelemetry::detached(
+ fixture.client.clone(),
+ fixture.state.clone(),
+ "interactive".to_string(),
);
- assert_eq!(
- recovery["recovery_action"],
- serde_json::json!("automatic_retry")
+ emit(
+ &fixture,
+ AgentEvent::MessageStart {
+ message: user_message(),
+ },
);
- assert_eq!(recovery["recovery_outcome"], serde_json::json!("success"));
- assert_eq!(recovery["retry_attempt"], serde_json::json!(1));
- assert_eq!(
- occurrence["error_id"], recovery["error_id"],
- "the recovery update pairs with its occurrence"
+ attempt(&fixture, assistant_with_error("network connection reset"));
+ retry_start(&telemetry, 1, 500, false);
+ telemetry.note_auto_retry_event(&AutoRetryEvent::End {
+ success: false,
+ attempt: 1,
+ final_error: Some("Retry cancelled".to_string()),
+ restored_model: None,
+ });
+ emit(
+ &fixture,
+ AgentEvent::MessageStart {
+ message: user_message(),
+ },
);
- // The `time_to_error` and `retry_wait` timing stages.
- let timings = event_properties(&fixture.mock, "agent timing").await;
- let time_to_error = timings
- .iter()
- .find(|timing| timing["stage"] == serde_json::json!("time_to_error"))
- .expect("time_to_error timing");
- assert_eq!(time_to_error["duration_ms"], serde_json::json!(300));
- let retry_wait = timings
- .iter()
- .find(|timing| timing["stage"] == serde_json::json!("retry_wait"))
- .expect("retry_wait timing");
- assert_eq!(retry_wait["duration_ms"], serde_json::json!(500));
- // The failed run window reports the retry counts.
- emit(&fixture, AgentEvent::AgentStart);
+ attempt(&fixture, assistant_message());
+ telemetry.end().await.unwrap();
+
let runs = event_properties(&fixture.mock, "agent run completed").await;
- assert_eq!(runs.len(), 1);
+ assert_eq!(runs.len(), 2, "the next turn is its own run");
assert_eq!(runs[0]["outcome"], serde_json::json!("error"));
assert_eq!(runs[0]["retry_count"], serde_json::json!(1));
- assert_eq!(runs[0]["retry_wait_ms"], serde_json::json!(500));
- assert_eq!(runs[0]["error_subtype"], serde_json::json!("rate_limited"));
- assert_eq!(runs[0]["stop_reason"], serde_json::json!("error"));
- assert_eq!(runs[0]["terminal_outcome"], serde_json::json!("error"));
- assert_eq!(runs[0]["usage_complete"], serde_json::json!(false));
- assert!(
- runs[0].get("estimated_cost_usd").is_none(),
- "incomplete usage never reports a cost"
- );
+ assert_eq!(runs[1]["outcome"], serde_json::json!("success"));
+ assert_eq!(runs[1]["retry_count"], serde_json::json!(0));
}
/// The enriched `agent run completed` (v2): the run pair id, the
@@ -830,24 +897,6 @@ async fn run_completed_v2_enrichment() {
assert_eq!(ended[0]["terminal_outcome"], serde_json::json!("success"));
}
-/// A tool failure emits its own error occurrence (component `tools`)
-/// without ever uploading the tool output.
-#[tokio::test]
-async fn tool_failure_emits_tools_error_occurrence() {
- let fixture = fixture();
- emit(&fixture, AgentEvent::AgentStart);
- let (start, end) = tool_execution_event("bash", true);
- emit(&fixture, start);
- emit(&fixture, end);
- let errors = event_properties(&fixture.mock, "agent error").await;
- assert_eq!(errors.len(), 1);
- assert_eq!(errors[0]["component"], serde_json::json!("tools"));
- assert_eq!(errors[0]["operation"], serde_json::json!("execute"));
- assert_eq!(errors[0]["stage"], serde_json::json!("tool_execution"));
- let all = serde_json::to_string(&fixture.mock.events()).unwrap();
- assert!(!all.contains("private tool output"));
-}
-
/// The stream-gap timing: the largest quiet stretch between model
/// events reports on the run's timing stage.
#[tokio::test]
@@ -870,12 +919,6 @@ async fn stream_gap_tracks_the_largest_quiet_stretch() {
},
);
emit(&fixture, AgentEvent::AgentStart);
- let timings = event_properties(&fixture.mock, "agent timing").await;
- let gap = timings
- .iter()
- .find(|timing| timing["stage"] == serde_json::json!("stream_gap"))
- .expect("stream_gap timing");
- assert_eq!(gap["duration_ms"], serde_json::json!(150));
let runs = event_properties(&fixture.mock, "agent run completed").await;
assert_eq!(runs[0]["max_stream_gap_ms"], serde_json::json!(150));
assert_eq!(runs[0]["run_to_first_text_ms"], serde_json::json!(0));
@@ -912,80 +955,538 @@ async fn bot_edges_the_trigger_lands_and_terminal_outcome_maps() {
assert_eq!(runs[0]["terminal_outcome"], serde_json::json!("cancelled"));
}
+/// End to end through the real client and the real analytics sink to a
+/// local stub endpoint: a scripted interactive session (start, one run
+/// with a tool call, end) posts TS-shaped bodies, and every legacy event
+/// carries the full TS property set in the TS vocabulary.
#[tokio::test]
-async fn bot_edges_tool_failure_never_touches_the_model_failure_chain() {
- let fixture = fixture();
+async fn legacy_events_reach_the_analytics_endpoint_in_the_ts_shape() {
+ use std::io::{Read, Write};
+
+ let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+ let url = format!(
+ "http://{}/api/v1/agent-analytics/events",
+ listener.local_addr().unwrap()
+ );
+ let (tx, rx) = std::sync::mpsc::channel::<serde_json::Value>();
+ std::thread::spawn(move || {
+ for stream in listener.incoming() {
+ let mut stream = stream.unwrap();
+ let mut request = Vec::new();
+ let mut buffer = [0u8; 8192];
+ loop {
+ let n = stream.read(&mut buffer).unwrap();
+ request.extend_from_slice(&buffer[..n]);
+ let text = String::from_utf8_lossy(&request);
+ if let Some(end) = text.find("\r\n\r\n") {
+ let length = text[..end]
+ .lines()
+ .find_map(|line| {
+ let (name, value) = line.split_once(':')?;
+ name.eq_ignore_ascii_case("content-length")
+ .then(|| value.trim().parse::<usize>().ok())?
+ })
+ .unwrap_or(0);
+ if request.len() >= end + 4 + length {
+ let body: serde_json::Value =
+ serde_json::from_slice(&request[end + 4..end + 4 + length]).unwrap();
+ let accepted = body["events"].as_array().map_or(0, Vec::len);
+ let reply = format!("{{\"accepted\":{accepted}}}");
+ // Hand the body over before answering: the flush
+ // returns once the reply is read, and the test
+ // collects right after it.
+ let _ = tx.send(body);
+ let _ = write!(
+ stream,
+ "HTTP/1.1 202 Accepted\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{reply}",
+ reply.len()
+ );
+ break;
+ }
+ }
+ if n == 0 {
+ break;
+ }
+ }
+ }
+ });
+
+ let install_id = "6f1c2b3a-4d5e-4f60-8a7b-9c0d1e2f3a4b";
+ let mut config = TelemetryClientConfig::new(install_id);
+ config.flush_interval = Duration::from_mins(10);
+ config.sinks = vec![
+ Arc::new(pa_telemetry::AnalyticsSink::new(url)) as Arc<dyn pa_telemetry::TelemetrySink>
+ ];
+ let client = TelemetryClient::spawn(config).unwrap();
+ let mut fixture = fixture();
+ fixture.client = client.clone();
+
+ let mut started = base_properties("interactive");
+ started.set(
+ "session_id",
+ Value::from("0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1a"),
+ );
+ client.track("agent started", started);
+ let assistant = assistant_message();
emit(&fixture, AgentEvent::AgentStart);
- // The model failure counts chain link 1.
emit(
&fixture,
- message_end_event(assistant_with_error("API Error: 429 rate limit exceeded")),
- );
- // A tool failure between model failures emits its own occurrence but
- // neither increments nor wipes the model chain.
- let (start, end) = tool_execution_event("bash", true);
- emit(&fixture, start);
- emit(&fixture, end);
- // The next model failure still reports chain link 2.
+ AgentEvent::MessageStart {
+ message: user_message(),
+ },
+ );
+ emit(&fixture, AgentEvent::TurnStart);
+ emit(&fixture, text_delta_event(&assistant));
+ let (tool_start, tool_end) = tool_execution_event("bash", false);
+ emit(&fixture, tool_start);
+ emit(&fixture, tool_end);
+ emit(&fixture, message_end_event(assistant));
emit(
&fixture,
- message_end_event(assistant_with_error("API Error: 429 rate limit exceeded")),
+ AgentEvent::AgentEnd {
+ messages: Vec::new(),
+ },
);
- let errors = event_properties(&fixture.mock, "agent error").await;
- let model_occurrences: Vec<_> = errors
+ let telemetry =
+ SessionTelemetry::detached(client, fixture.state.clone(), "interactive".to_string());
+ telemetry.end().await.unwrap();
+
+ let bodies: Vec<serde_json::Value> = rx.try_iter().collect();
+ assert!(!bodies.is_empty(), "the stub received the batches");
+ for body in &bodies {
+ println!("{}", serde_json::to_string_pretty(body).unwrap());
+ let mut keys: Vec<&String> = body.as_object().unwrap().keys().collect();
+ keys.sort();
+ assert_eq!(
+ keys,
+ ["events", "installation_id"],
+ "the TS envelope, nothing else"
+ );
+ assert_eq!(body["installation_id"], install_id);
+ for event in body["events"].as_array().unwrap() {
+ let mut keys: Vec<&String> = event.as_object().unwrap().keys().collect();
+ keys.sort();
+ assert_eq!(keys, ["id", "name", "properties", "timestamp"]);
+ }
+ }
+ let events: Vec<&serde_json::Value> = bodies
.iter()
- .filter(|error| error["component"] == serde_json::json!("provider"))
+ .flat_map(|body| body["events"].as_array().unwrap())
.collect();
+ let base = [
+ "version",
+ "os_family",
+ "architecture",
+ "install_method",
+ "execution_mode",
+ "libc",
+ "libc_version",
+ "cpu_baseline",
+ "os_release",
+ "os_product_version",
+ ];
+ let ts_keys: [(&str, &[&str]); 3] = [
+ ("agent started", &["session_id"]),
+ (
+ "agent run completed",
+ &[
+ "session_id",
+ "outcome",
+ "duration_ms",
+ "visible_ttft_ms",
+ "first_model_event_ms",
+ "model_latency_ms",
+ "max_model_latency_ms",
+ "model_call_count",
+ "turn_count",
+ "tool_call_count",
+ "tool_error_count",
+ "input_tokens",
+ "output_tokens",
+ "cache_read_tokens",
+ "cache_write_tokens",
+ "total_tokens",
+ "compaction_count",
+ "retry_count",
+ "provider_category",
+ "model_category",
+ "error_category",
+ ],
+ ),
+ (
+ "agent session ended",
+ &[
+ "session_id",
+ "duration_ms",
+ "prompt_count",
+ "run_count",
+ "successful_run_count",
+ "failed_run_count",
+ "aborted_run_count",
+ "tool_call_count",
+ "compaction_count",
+ "model_call_count",
+ "input_tokens",
+ "output_tokens",
+ "cache_read_tokens",
+ "cache_write_tokens",
+ "total_tokens",
+ ],
+ ),
+ ];
+ for (name, keys) in ts_keys {
+ let event = events
+ .iter()
+ .find(|event| event["name"] == name)
+ .unwrap_or_else(|| panic!("{name} was sent"));
+ let properties = event["properties"].as_object().unwrap();
+ for key in base.iter().chain(keys.iter()) {
+ assert!(
+ properties.contains_key(*key),
+ "{name} carries the TS key {key}"
+ );
+ }
+ assert_eq!(properties["execution_mode"], "interactive");
+ assert!(["linux", "darwin", "win32", "freebsd", "android"]
+ .contains(&properties["os_family"].as_str().unwrap()));
+ assert!(
+ ["x64", "arm64", "ia32", "arm", "s390x", "ppc64", "riscv64", "loong64"]
+ .contains(&properties["architecture"].as_str().unwrap())
+ );
+ }
+ let run = events
+ .iter()
+ .find(|event| event["name"] == "agent run completed")
+ .unwrap();
+ assert_eq!(run["properties"]["outcome"], "success");
+ assert_eq!(run["properties"]["provider_category"], "openai");
+ assert_eq!(run["properties"]["model_category"], "gpt");
+ assert_eq!(run["properties"]["error_category"], serde_json::Value::Null);
+ // TS sums the session's tool calls from its runs (one call, counted once).
+ let ended = events
+ .iter()
+ .find(|event| event["name"] == "agent session ended")
+ .unwrap();
+ assert_eq!(ended["properties"]["tool_call_count"], 1);
+ std::fs::write(
+ std::env::temp_dir().join("pa-telemetry-e2e-bodies.json"),
+ serde_json::to_string_pretty(&bodies).unwrap(),
+ )
+ .unwrap();
+}
+
+/// A fixture whose recording seams consult a live switch the test flips:
+/// the same shape [`install_session_telemetry`] installs from the wiring
+/// (minus the write-path epoch tracking, which the production switch
+/// registers and the zero-event-flap test exercises separately).
+fn fixture_with_switch(telemetry_enabled: Arc<dyn Fn() -> bool + Send + Sync>) -> Fixture {
+ let mock = std::sync::Arc::new(MockSink::new());
+ let client = client_for(&mock);
+ let clock = TestClock::default();
+ let now: Arc<dyn Fn() -> u64 + Send + Sync> = {
+ let millis = clock.millis.clone();
+ Arc::new(move || millis.load(std::sync::atomic::Ordering::Relaxed))
+ };
+ let state = Arc::new(Mutex::new(TelemetryState {
+ session_id: "0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1a".to_string(),
+ started_at: 1_000,
+ totals: SessionTotals::default(),
+ active_run: None,
+ tool_starts: HashMap::new(),
+ telemetry_enabled: Some(RecordingSwitch::test(telemetry_enabled)),
+ recording: true,
+ now,
+ }));
+ Fixture {
+ client,
+ state,
+ clock,
+ mock,
+ }
+}
+
+/// The TUI counters' rule, ported to the session surface: while telemetry
+/// is off nothing counts, so turning it on later never sends what
+/// happened while it was off.
+#[tokio::test]
+async fn off_period_session_counters_never_count() {
+ let on = Arc::new(std::sync::atomic::AtomicBool::new(false));
+ let switch: Arc<dyn Fn() -> bool + Send + Sync> = {
+ let on = Arc::clone(&on);
+ Arc::new(move || on.load(std::sync::atomic::Ordering::Relaxed))
+ };
+ let fixture = fixture_with_switch(Arc::clone(&switch));
+ let counters = Arc::new(SessionCounters::default());
+ counters.set_telemetry_enabled(Arc::clone(&switch));
+ let mut telemetry = SessionTelemetry::detached(
+ fixture.client.clone(),
+ fixture.state.clone(),
+ "interactive".to_string(),
+ );
+ telemetry.counters = Arc::clone(&counters);
+
+ // Off: a skill use, a connector use, a kernel boot, a feature
+ // outcome, and a child usage row all record nothing — the counters'
+ // switch is the same live gate the engine installs at creation, so
+ // the pre-install MCP/kernel window records nothing either.
+ telemetry.note_skill_used();
+ counters.note_mcp_connector_use();
+ counters.note_kernel_bootstrap(true, true, 1_200);
+ telemetry.note_feature_outcome("goal", "completed", Some("create"));
+ telemetry.note_child_usage_attributed(50_208, 2_929, 0, 0, 0.008_995_7);
+
+ // On: the same seams record again.
+ on.store(true, std::sync::atomic::Ordering::Relaxed);
+ telemetry.note_skill_used();
+ telemetry.note_skill_used();
+
+ telemetry.end().await.unwrap();
+ let ended = &event_properties(&fixture.mock, "agent session ended").await[0];
+ assert_eq!(ended["skill_use_count"], serde_json::json!(2));
assert_eq!(
- model_occurrences[0]["consecutive_failure_count"],
- serde_json::json!(1)
+ ended["mcp_connector_use_count"],
+ serde_json::json!(0),
+ "the off-period connector use never counted"
);
assert_eq!(
- model_occurrences[1]["consecutive_failure_count"],
- serde_json::json!(2),
- "the tool failure in between never reset the chain"
+ ended["rlm_child_usage_count"],
+ serde_json::json!(0),
+ "the off-period child usage never counted"
);
- let tool_occurrence = errors
- .iter()
- .find(|error| error["component"] == serde_json::json!("tools"))
- .expect("the tool occurrence fired");
+ assert_eq!(
+ ended["kernel_bootstrap_count"],
+ serde_json::json!(0),
+ "the off-period kernel boot never counted"
+ );
+ assert_eq!(
+ ended["rlm_child_input_tokens"],
+ serde_json::json!(0),
+ "the off-period child tokens never counted"
+ );
+ let feature_keys: Vec<_> = ended
+ .keys()
+ .filter(|key| key.starts_with("feature_"))
+ .collect();
assert!(
- tool_occurrence.get("consecutive_failure_count").is_none(),
- "tool occurrences never carry the model chain counter"
+ feature_keys.is_empty(),
+ "the off-period feature outcome never counted"
);
}
+/// The run state machine stops recording while telemetry is off: a run
+/// that happened in the off period never reports, and a later enable
+/// sends only what the on period recorded.
#[tokio::test]
-async fn bot_edges_the_give_up_never_double_counts_the_chain() {
- let fixture = fixture();
- let failed = assistant_with_error("API Error: 429 rate limit exceeded");
+async fn off_period_run_facts_never_send() {
+ let on = Arc::new(std::sync::atomic::AtomicBool::new(false));
+ let switch: Arc<dyn Fn() -> bool + Send + Sync> = {
+ let on = Arc::clone(&on);
+ Arc::new(move || on.load(std::sync::atomic::Ordering::Relaxed))
+ };
+ let fixture = fixture_with_switch(switch);
+ let assistant = assistant_message();
+
+ // A whole run while off: start, a turn, a tool call, and its end.
+ fixture.clock.set(1_000);
emit(&fixture, AgentEvent::AgentStart);
- emit(&fixture, message_end_event(failed));
+ emit(&fixture, AgentEvent::TurnStart);
+ let (tool_start, tool_end) = tool_execution_event("bash", false);
+ emit(&fixture, tool_start);
+ emit(&fixture, tool_end);
+ fixture.clock.set(1_100);
+ emit(&fixture, message_end_event(assistant.clone()));
+ emit(
+ &fixture,
+ AgentEvent::AgentEnd {
+ messages: Vec::new(),
+ },
+ );
+
+ // On again: the next run records normally.
+ on.store(true, std::sync::atomic::Ordering::Relaxed);
+ fixture.clock.set(2_000);
+ emit(&fixture, AgentEvent::AgentStart);
+ fixture.clock.set(2_050);
+ emit(&fixture, AgentEvent::TurnStart);
+ fixture.clock.set(2_100);
+ emit(&fixture, message_end_event(assistant.clone()));
+ fixture.clock.set(2_150);
+ emit(
+ &fixture,
+ AgentEvent::AgentEnd {
+ messages: Vec::new(),
+ },
+ );
+
+ fixture.clock.set(2_200);
let telemetry = SessionTelemetry::detached(
fixture.client.clone(),
fixture.state.clone(),
"interactive".to_string(),
);
- // The retry gives up: the failed call already counted its link, and
- // a FAILED retry emits no recovery update at all (the retried
- // attempt's own failure is its own new occurrence when one happens -
- // a mispaired update would claim the wrong recovery).
- telemetry.note_auto_retry_event(&AutoRetryEvent::End {
- success: false,
- attempt: 1,
- final_error: Some("gave up".to_string()),
- restored_model: None,
- });
- let errors = event_properties(&fixture.mock, "agent error").await;
+ telemetry.end().await.unwrap();
+
+ // One run completed: the on-period run. The off-period run never
+ // existed, and its tool call never entered the session totals.
+ let runs = event_properties(&fixture.mock, "agent run completed").await;
+ assert_eq!(runs.len(), 1, "only the on-period run reports");
+ assert_eq!(runs[0]["turn_count"], serde_json::json!(1));
+ assert_eq!(runs[0]["input_tokens"], serde_json::json!(100));
+ let ended = &event_properties(&fixture.mock, "agent session ended").await[0];
+ assert_eq!(ended["run_count"], serde_json::json!(1));
+ assert_eq!(ended["tool_call_count"], serde_json::json!(0));
+}
+
+/// The recording switch resolves live: a fresh invocation reads the
+/// settings as they are now, so the turn-boundary asks (and the
+/// client's flush gate) observe a mid-session opt-out or re-enable the
+/// moment it is saved. The events between boundaries deliberately use
+/// the boundary cache; this proves only the raw switch has no cache of
+/// its own.
+#[test]
+fn recording_switch_flips_immediately_with_the_settings() {
+ let _env = CleanTelemetryEnv::default();
+ let dir = tempfile::tempdir().unwrap();
+ let agent_dir = dir.path().join("agent");
+ let mut settings = crate::settings::SettingsManager::create(dir.path(), &agent_dir);
+ settings.set_telemetry_enabled(true).unwrap();
+ let switch = telemetry_enabled_switch(dir.path(), &agent_dir);
+ assert!((switch.enabled)(), "on in settings records");
+
+ // The off lands without a cache window: nothing the seams ask
+ // after the flip may still see the pre-flip answer.
+ settings.set_telemetry_enabled(false).unwrap();
+ assert!(!(switch.enabled)(), "the off applies immediately");
+
+ // The re-enable lands the same way.
+ settings.set_telemetry_enabled(true).unwrap();
+ assert!((switch.enabled)(), "the on applies immediately too");
+}
+
+/// The opt-out is the settings write itself: no telemetry state can
+/// block it. A squatted (unwritable) install-id state — which used to
+/// fail the command — never holds the disable hostage, and the opt-out
+/// never touches (or mints) the state file.
+#[test]
+fn a_disable_lands_even_when_the_telemetry_state_is_unusable() {
+ let _env = CleanTelemetryEnv::default();
+ let dir = tempfile::tempdir().unwrap();
+ let agent_dir = dir.path().join("agent");
+ let mut settings = crate::settings::SettingsManager::create(dir.path(), &agent_dir);
+ settings.set_telemetry_enabled(true).unwrap();
+ // The state path is unusable: a directory squats it (no create or
+ // rename could ever land there, for any user).
+ std::fs::create_dir_all(agent_dir.join("telemetry.json")).unwrap();
+
+ super::set_telemetry_enabled_text(&mut settings, &agent_dir, false).unwrap();
+ assert!(
+ !crate::settings::SettingsManager::create(dir.path(), &agent_dir).get_telemetry_enabled(),
+ "the disable lands regardless of the telemetry state"
+ );
+ super::set_telemetry_enabled_text(&mut settings, &agent_dir, true).unwrap();
+ assert!(
+ crate::settings::SettingsManager::create(dir.path(), &agent_dir).get_telemetry_enabled(),
+ "the re-enable lands the same way"
+ );
+}
+
+/// Opting out never mints an identity: a fresh installation with no
+/// install-id state disables without creating `telemetry.json`.
+#[test]
+fn a_disable_on_a_fresh_install_never_mints_the_install_id() {
+ let _env = CleanTelemetryEnv::default();
+ let dir = tempfile::tempdir().unwrap();
+ let agent_dir = dir.path().join("agent");
+ std::fs::create_dir_all(&agent_dir).unwrap();
+ let mut settings = crate::settings::SettingsManager::create(dir.path(), &agent_dir);
+
+ super::set_telemetry_enabled_text(&mut settings, &agent_dir, false).unwrap();
+
+ assert!(
+ !crate::settings::SettingsManager::create(dir.path(), &agent_dir).get_telemetry_enabled(),
+ "the opt-out lands"
+ );
+ assert!(
+ !agent_dir.join("telemetry.json").exists(),
+ "the opt-out never creates the install-id state"
+ );
+}
+
+/// A run active when telemetry goes off is severed, not merged: its
+/// `AgentEnd` and the next run's `AgentStart` happen in the off period,
+/// and the next on-period run starts clean with only its own facts.
+#[tokio::test]
+async fn a_run_active_when_telemetry_turns_off_is_severed_not_merged() {
+ let on = Arc::new(std::sync::atomic::AtomicBool::new(true));
+ let switch: Arc<dyn Fn() -> bool + Send + Sync> = {
+ let on = Arc::clone(&on);
+ Arc::new(move || on.load(std::sync::atomic::Ordering::Relaxed))
+ };
+ let fixture = fixture_with_switch(switch);
+ let assistant = assistant_message();
+
+ // Run 1 starts while on: one turn, one tool call in flight.
+ fixture.clock.set(1_000);
+ emit(&fixture, AgentEvent::AgentStart);
+ fixture.clock.set(1_050);
+ emit(&fixture, AgentEvent::TurnStart);
+ let (tool_start, _tool_end) = tool_execution_event("bash", false);
+ emit(&fixture, tool_start);
+ fixture.clock.set(1_100);
+ emit(&fixture, message_end_event(assistant.clone()));
+
+ // Telemetry goes off: run 1's tool end, its end, and the next
+ // run's start all happen in the off period.
+ on.store(false, std::sync::atomic::Ordering::Relaxed);
+ fixture.clock.set(1_200);
+ let (_tool_start2, tool_end) = tool_execution_event("bash", false);
+ emit(&fixture, tool_end);
+ emit(
+ &fixture,
+ AgentEvent::AgentEnd {
+ messages: Vec::new(),
+ },
+ );
+ fixture.clock.set(1_300);
+ emit(&fixture, AgentEvent::AgentStart);
+
+ // Back on: the next run reports only its own window.
+ on.store(true, std::sync::atomic::Ordering::Relaxed);
+ fixture.clock.set(2_000);
+ emit(&fixture, AgentEvent::AgentStart);
+ fixture.clock.set(2_050);
+ emit(&fixture, AgentEvent::TurnStart);
+ fixture.clock.set(2_100);
+ emit(&fixture, message_end_event(assistant.clone()));
+ fixture.clock.set(2_150);
+ emit(
+ &fixture,
+ AgentEvent::AgentEnd {
+ messages: Vec::new(),
+ },
+ );
+
+ fixture.clock.set(2_200);
+ let telemetry = SessionTelemetry::detached(
+ fixture.client.clone(),
+ fixture.state.clone(),
+ "interactive".to_string(),
+ );
+ telemetry.end().await.unwrap();
+
+ let runs = event_properties(&fixture.mock, "agent run completed").await;
+ assert_eq!(runs.len(), 1, "only the on-period run reports");
+ assert_eq!(runs[0]["turn_count"], serde_json::json!(1));
assert_eq!(
- errors.len(),
- 1,
- "the give-up never created a recovery update"
+ runs[0]["duration_ms"],
+ serde_json::json!(150),
+ "the severed run never merges: the duration stays in run 2's window"
);
- let occurrence = &errors[0];
+ let ended = &event_properties(&fixture.mock, "agent session ended").await[0];
+ assert_eq!(ended["run_count"], serde_json::json!(1));
assert_eq!(
- occurrence["consecutive_failure_count"],
- serde_json::json!(1),
- "the give-up never inflated the chain to 2"
+ ended["tool_call_count"],
+ serde_json::json!(0),
+ "the off-period tool end never counts"
);
}
diff --git a/crates/pa-core/src/session_engine/telemetry/track.rs b/crates/pa-core/src/session_engine/telemetry/track.rs
index 3171c3ba23..6d54647b82 100644
--- a/crates/pa-core/src/session_engine/telemetry/track.rs
+++ b/crates/pa-core/src/session_engine/telemetry/track.rs
@@ -5,14 +5,26 @@
//! privacy contract).
use super::{base_properties, model_category, provider_category, TelemetryClient, Value};
-/// Track a supervision-lifecycle event (`daemon event`, schema v1): kinds
-/// and counts only, never session payload. `exit_reason` rides only the
-/// `worker_exited` kind.
-pub fn track_daemon_event(client: &TelemetryClient, kind: &str, exit_reason: Option<&str>) {
+/// Track the supervision summary (`daemon event`, kind `summary`): the
+/// frequent supervision events of one window as `<kind>_count`
+/// properties. Kinds and counts only, never session payload.
+pub fn track_daemon_event_summary(
+ client: &TelemetryClient,
+ window_ms: u64,
+ counts: &std::collections::BTreeMap<String, u64>,
+ saved_sessions_usage_rows_max: u64,
+) {
let mut properties = base_properties("daemon");
- properties.set("kind", Value::from(kind));
- if let Some(reason) = exit_reason {
- properties.set("exit_reason", Value::from(reason));
+ properties.set("kind", Value::from("summary"));
+ properties.set("window_ms", Value::from(window_ms));
+ for (key, count) in counts {
+ properties.set(key, Value::from(*count));
+ }
+ if counts.contains_key("saved_sessions_list_count") {
+ properties.set(
+ "saved_sessions_usage_rows_max",
+ Value::from(saved_sessions_usage_rows_max),
+ );
}
client.track("daemon event", properties);
}
@@ -98,17 +110,6 @@ pub fn track_catalog_refresh(client: &TelemetryClient, count: usize) {
client.track("daemon event", properties);
}
-/// Track the saved-session catalog's usage-bearing rows (`daemon event`,
-/// schema v1, kind `saved_sessions_usage`): how many rows a served
-/// `list_saved_sessions` pass publish with a usage summary — the
-/// agents-view spend columns' data. A count only, never session payload.
-pub fn track_saved_sessions_usage(client: &TelemetryClient, count: usize) {
- let mut properties = base_properties("daemon");
- properties.set("kind", Value::from("saved_sessions_usage"));
- properties.set("count", Value::from(count));
- client.track("daemon event", properties);
-}
-
/// Track the abort supervision's terminal declaration (`daemon event`,
/// schema v1, kind `compaction_abort_declared`): the supervisor declared
/// a wedged worker's compaction aborted after its abort grace expired. A
diff --git a/crates/pa-core/src/session_engine/wiring.rs b/crates/pa-core/src/session_engine/wiring.rs
index 0e71c35ea9..cd53733577 100644
--- a/crates/pa-core/src/session_engine/wiring.rs
+++ b/crates/pa-core/src/session_engine/wiring.rs
@@ -118,7 +118,7 @@ impl AgentSession {
self.skills = skills;
}
- /// Bind the telemetry handle the `skill used` adoption event reports
+ /// Bind the telemetry handle the `skill_use_count` counter counts
/// through (the engine wiring owns the telemetry lifetime and
/// installs it once the session telemetry is assembled).
pub fn set_skill_telemetry(&mut self, telemetry: std::sync::Arc<telemetry::SessionTelemetry>) {
diff --git a/crates/pa-core/src/settings/manager.rs b/crates/pa-core/src/settings/manager.rs
index 939575b9ff..1fc5f57f0e 100644
--- a/crates/pa-core/src/settings/manager.rs
+++ b/crates/pa-core/src/settings/manager.rs
@@ -79,6 +79,16 @@ impl SettingsManager {
Self::from_storage(storage)
}
+ /// A new manager over the same settings store (a fresh read; the
+ /// runtime overrides carry over), for long-lived readers such as the
+ /// telemetry switch.
+ #[must_use]
+ pub fn reopen(&self) -> Self {
+ let mut fresh = Self::from_storage(Arc::clone(&self.storage));
+ fresh.apply_overrides(&self.runtime_overrides);
+ fresh
+ }
+
/// In-memory manager (tests, embedded hosts).
#[must_use]
pub fn in_memory(initial: &Settings) -> Self {
@@ -913,6 +923,20 @@ impl SettingsManager {
self.merged.transport.unwrap_or(TransportSetting::Auto)
}
+ /// `telemetry.enabled` when any scope sets it (`None`: nothing set, the
+ /// default-on posture), resolved like [`Self::get_telemetry_enabled`].
+ #[must_use]
+ pub fn telemetry_enabled_setting(&self) -> Option<bool> {
+ let set = [
+ self.global.telemetry.as_ref(),
+ self.project.telemetry.as_ref(),
+ self.runtime_overrides.telemetry.as_ref(),
+ ]
+ .iter()
+ .any(|scope| scope.and_then(|t| t.enabled).is_some());
+ set.then(|| self.get_telemetry_enabled())
+ }
+
/// Telemetry is enabled only when every scope says so (default true).
#[must_use]
pub fn get_telemetry_enabled(&self) -> bool {
@@ -1068,6 +1092,19 @@ mod tests {
assert_eq!(manager.get_default_model(), Some("z-ai/glm-5.3"));
}
+ #[test]
+ fn reopen_keeps_the_runtime_overrides_in_the_merged_settings() {
+ let mut manager = SettingsManager::in_memory(&Settings::default());
+ manager.apply_overrides(&Settings {
+ markdown: Some(MarkdownSettings {
+ code_block_indent: Some(" ".to_string()),
+ mermaid: None,
+ }),
+ ..Settings::default()
+ });
+ assert_eq!(manager.reopen().get_code_block_indent(), " ");
+ }
+
#[test]
fn code_block_indent_reads_markdown_settings_with_ts_default() {
// `markdown.codeBlockIndent` (TS getCodeBlockIndent): absent -> the
diff --git a/crates/pa-core/src/settings/types.rs b/crates/pa-core/src/settings/types.rs
index 6dd755db46..b58ba6706a 100644
--- a/crates/pa-core/src/settings/types.rs
+++ b/crates/pa-core/src/settings/types.rs
@@ -233,22 +233,11 @@ pub struct AgentTracesSettings {
pub struct TelemetrySettings {
pub enabled: Option<bool>,
pub notice_shown: Option<bool>,
- /// Self-hosted `PostHog` capture configuration. Nothing is compiled in;
- /// an empty configuration resolves to the no-op sink.
- pub posthog: Option<PostHogSettings>,
/// Local JSONL mirror at `<agentDir>/telemetry.jsonl` (default on:
/// user-observable transparency).
pub local_mirror: Option<bool>,
}
-/// Settings `telemetry.posthog`: endpoint + project capture key.
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct PostHogSettings {
- pub endpoint: Option<String>,
- pub api_key: Option<String>,
-}
-
/// User-declared MCP server (settings `mcpServers` entry).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "kebab-case")]
diff --git a/crates/pa-core/tests/kernel_prewarm.rs b/crates/pa-core/tests/kernel_prewarm.rs
index 3f55e507e0..51b78337a9 100644
--- a/crates/pa-core/tests/kernel_prewarm.rs
+++ b/crates/pa-core/tests/kernel_prewarm.rs
@@ -27,7 +27,7 @@
//! venv); like `kernel_lifecycle.rs`, these tests skip (with a note) on
//! machines without a live install so the suite stays hermetic elsewhere.
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
use std::time::{Duration, Instant};
use pa_core::session_engine::compact_session::CompactOutcome;
@@ -113,46 +113,28 @@ fn agent_model(model: &pa_types::ai::Model) -> pa_agent::types::Model {
json_round_trip(model).expect("model conversion")
}
-/// Every `kernel bootstrap` telemetry event flushed to the local mirror so
-/// far (`<agentDir>/telemetry.jsonl`, the transparency sink).
-async fn kernel_bootstrap_events(
- client: &pa_telemetry::TelemetryClient,
- agent_dir: &Path,
-) -> Vec<serde_json::Value> {
- client.flush().await.expect("telemetry flush");
- let mirror = agent_dir.join("telemetry.jsonl");
- let body = std::fs::read_to_string(&mirror).unwrap_or_default();
- body.lines()
- .filter_map(|line| serde_json::from_str::<serde_json::Value>(line).ok())
- .filter(|event| {
- event.get("name").and_then(serde_json::Value::as_str) == Some("kernel bootstrap")
- })
- .collect()
-}
-
-/// Wait for the prewarmed boot to finish: poll the telemetry mirror for the
-/// `kernel bootstrap` success event (the boot is a background task, and the
-/// client flushes on its interval, so both waits fold into this poll).
-async fn wait_for_kernel_boot(client: &pa_telemetry::TelemetryClient, agent_dir: &Path) {
+/// Wait for the prewarmed boot to finish (a background task): poll the
+/// session's kernel provisioner until a kernel runs.
+async fn wait_for_kernel_boot(engine: &pa_core::session_engine::engine::SessionEngine) {
let deadline = Instant::now() + Duration::from_mins(2);
loop {
- let events = kernel_bootstrap_events(client, agent_dir).await;
- if events
- .iter()
- .any(|event| event["properties"]["outcome"] == "success")
+ if engine
+ .kernel_provisioner_weak()
+ .upgrade()
+ .is_some_and(|provisioner| provisioner.has_running_kernel())
{
return;
}
assert!(
Instant::now() < deadline,
- "the prewarmed kernel never reported its bootstrap"
+ "the prewarmed kernel never booted"
);
tokio::time::sleep(Duration::from_millis(500)).await;
}
}
/// The prewarm fires at creation (no `ipython` tool use anywhere): the
-/// background boot reports through telemetry, the session's compaction sees
+/// background boot completes, the session's compaction sees
/// a running kernel, and the hidden `ipython_state` notice lands on the
/// durable entries — with the empty-namespace arm, because the model never
/// ran a cell.
@@ -201,6 +183,7 @@ async fn prewarmed_kernel_lands_compaction_notice_without_tool_use() {
client: client.clone(),
execution_mode: Some("test".to_string()),
now: None,
+ telemetry_enabled: None,
}),
prewarm_ipython_kernel: Some(true),
..Default::default()
@@ -209,7 +192,7 @@ async fn prewarmed_kernel_lands_compaction_notice_without_tool_use() {
.expect("create the prewarmed session");
// The prewarm's boot, without a single ipython tool call.
- wait_for_kernel_boot(&client, &agent_dir).await;
+ wait_for_kernel_boot(&engine).await;
// Plain text turns: history for the compaction, no tool use.
for turn in ["history turn one", "history turn two"] {
@@ -262,7 +245,7 @@ async fn prewarmed_kernel_lands_compaction_notice_without_tool_use() {
/// The TS depth gate: subagent sessions (rlmDepth > 0) keep the lazy
/// first-call start even when the runtime factory passes
-/// `prewarmIpythonKernel: true` — no boot, no `kernel bootstrap` event.
+/// `prewarmIpythonKernel: true` — no boot.
#[tokio::test]
#[allow(clippy::await_holding_lock)]
async fn subagent_sessions_stay_lazy_despite_the_prewarm_flag() {
@@ -294,6 +277,7 @@ async fn subagent_sessions_stay_lazy_despite_the_prewarm_flag() {
client: client.clone(),
execution_mode: Some("test".to_string()),
now: None,
+ telemetry_enabled: None,
}),
rlm_depth: Some(1),
prewarm_ipython_kernel: Some(true),
@@ -322,11 +306,145 @@ async fn subagent_sessions_stay_lazy_despite_the_prewarm_flag() {
// lazy session reports nothing.
let deadline = Instant::now() + Duration::from_secs(8);
while Instant::now() < deadline {
- let events = kernel_bootstrap_events(&client, &agent_dir).await;
assert!(
- events.is_empty(),
- "a depth-1 session must not prewarm: {events:?}"
+ !engine
+ .kernel_provisioner_weak()
+ .upgrade()
+ .is_some_and(|provisioner| provisioner.has_running_kernel()),
+ "a depth-1 session must not prewarm"
);
tokio::time::sleep(Duration::from_millis(500)).await;
}
}
+
+/// The live opt-out env is process-wide: the counters' switch test scrubs
+/// the three override vars (the Cargo test config sets `DO_NOT_TRACK`)
+/// while it runs and restores them after, serialized through its own lock.
+static TELEMETRY_ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+const TELEMETRY_ENV_VARS: [&str; 3] = ["DO_NOT_TRACK", "PI_OFFLINE", "PRIME_AGENT_TELEMETRY"];
+
+struct CleanTelemetryEnv {
+ saved: Vec<(&'static str, Option<String>)>,
+ _env_lock: std::sync::MutexGuard<'static, ()>,
+}
+
+impl CleanTelemetryEnv {
+ fn default() -> Self {
+ // Held first: the vars may not be touched while another env test
+ // runs.
+ let env_lock = TELEMETRY_ENV_LOCK
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ let saved = TELEMETRY_ENV_VARS
+ .iter()
+ .map(|var| {
+ let value = std::env::var(var).ok();
+ std::env::remove_var(var);
+ (*var, value)
+ })
+ .collect();
+ Self {
+ saved,
+ _env_lock: env_lock,
+ }
+ }
+}
+
+impl Drop for CleanTelemetryEnv {
+ fn drop(&mut self) {
+ for (var, value) in self.saved.drain(..) {
+ match value {
+ Some(value) => std::env::set_var(var, value),
+ None => std::env::remove_var(var),
+ }
+ }
+ }
+}
+
+/// The counters' live switch is installed at the engine's creation, before
+/// the MCP and kernel seams that count into them capture their handles:
+/// a settings opt-out through the whole prewarm window (the boot
+/// completes while telemetry is off) never records the boot, and a later
+/// enable cannot send what the off period counted. Regression for the
+/// pre-install-window finding: the switch used to arrive only at the
+/// first-turn install, so an off-period prewarm boot counted.
+#[tokio::test]
+#[allow(clippy::await_holding_lock)]
+async fn an_off_switch_at_creation_keeps_the_prewarm_window_uncounted() {
+ let Some(_kernel_python) = kernel_python() else {
+ return;
+ };
+ let _env = CleanTelemetryEnv::default();
+ let _guard = FAUX_LOCK
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ let dir = tempfile::TempDir::new().expect("temp dir");
+ let agent_dir = dir.path().join("agent");
+ std::fs::create_dir_all(&agent_dir).expect("agent dir");
+ let cwd = dir.path().join("project");
+ std::fs::create_dir_all(&cwd).expect("cwd");
+ let mut settings = SettingsManager::create(&cwd, &agent_dir);
+ // Telemetry off through the whole prewarm window.
+ settings.set_telemetry_enabled(false).expect("settings off");
+ let mock = std::sync::Arc::new(pa_telemetry::MockSink::new());
+ let mut config = pa_telemetry::TelemetryClientConfig::new("install-1");
+ config.sinks = vec![mock.clone() as std::sync::Arc<dyn pa_telemetry::TelemetrySink>];
+ let client = pa_telemetry::TelemetryClient::spawn(config).expect("client");
+
+ let faux = faux_session(vec!["ok".to_string()]);
+ let engine = create_session(SessionEngineConfig {
+ cron_store: None,
+ steering_mode: None,
+ follow_up_mode: None,
+ cwd: cwd.clone(),
+ agent_dir: agent_dir.clone(),
+ model: Some(agent_model(&faux.model)),
+ stream_fn: Some(faux.stream_fn),
+ tools: Vec::new(),
+ telemetry: Some(TelemetryWiring {
+ client,
+ execution_mode: Some("test".to_string()),
+ now: None,
+ telemetry_enabled: Some(
+ pa_core::session_engine::telemetry::telemetry_enabled_switch(&cwd, &agent_dir),
+ ),
+ }),
+ prewarm_ipython_kernel: Some(true),
+ ..Default::default()
+ })
+ .await
+ .expect("create the prewarmed session");
+
+ // The boot completes inside the off window (however the creation
+ // interleaved, the switch already gated the counters).
+ wait_for_kernel_boot(&engine).await;
+
+ // A later enable must not send the off-period boot.
+ settings.set_telemetry_enabled(true).expect("settings on");
+ let outcome = engine
+ .prompt("hello", PromptOptions::default())
+ .await
+ .expect("prompt");
+ assert_eq!(outcome, PromptOutcome::Prompt);
+ engine.session.agent().wait_for_idle().await;
+ engine
+ .telemetry
+ .as_ref()
+ .expect("the depth-0 session installed telemetry")
+ .end()
+ .await
+ .expect("end");
+
+ let events = mock.events();
+ let ended = events
+ .iter()
+ .find(|event| event.name == "agent session ended")
+ .expect("the session-ended event flushed after the re-enable");
+ assert_eq!(
+ ended.properties.get("kernel_bootstrap_count"),
+ Some(&serde_json::json!(0)),
+ "the off-window prewarm boot never counted:\n{:?}",
+ ended.properties
+ );
+}
diff --git a/crates/pa-core/tests/kernel_snapshot_resume.rs b/crates/pa-core/tests/kernel_snapshot_resume.rs
index 91ae35cc8b..ffda1fb7be 100644
--- a/crates/pa-core/tests/kernel_snapshot_resume.rs
+++ b/crates/pa-core/tests/kernel_snapshot_resume.rs
@@ -33,7 +33,7 @@
//! note) on machines without a live install so the suite stays hermetic
//! elsewhere. `PA_CORE_KERNEL_PYTHON` points at an explicit interpreter.
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
use std::time::{Duration, Instant};
use pa_ai::faux::{
@@ -141,49 +141,19 @@ fn agent_model(model: &pa_types::ai::Model) -> pa_agent::types::Model {
json_round_trip(model).expect("model conversion")
}
-/// Every `kernel bootstrap` telemetry event flushed to the local mirror so
-/// far (`<agentDir>/telemetry.jsonl`, the transparency sink).
-async fn kernel_bootstrap_events(
- client: &pa_telemetry::TelemetryClient,
- agent_dir: &Path,
-) -> Vec<serde_json::Value> {
- client.flush().await.expect("telemetry flush");
- let mirror = agent_dir.join("telemetry.jsonl");
- let body = std::fs::read_to_string(&mirror).unwrap_or_default();
- body.lines()
- .filter_map(|line| serde_json::from_str::<serde_json::Value>(line).ok())
- .filter(|event| {
- event.get("name").and_then(serde_json::Value::as_str) == Some("kernel bootstrap")
- })
- .collect()
-}
-
-/// One property of a telemetry event (the payload lives under
-/// `properties`).
-fn event_prop<'a>(event: &'a serde_json::Value, key: &str) -> Option<&'a serde_json::Value> {
- event.get("properties").and_then(|props| props.get(key))
-}
-
-/// Wait for a specific boot to report: a background task flushes the
-/// `kernel bootstrap` event on the client's interval, and an agent dir can
-/// already carry earlier sessions' boot events — so the wait matches on
-/// the `cold` flag rather than "any event".
-async fn wait_for_boot(
- client: &pa_telemetry::TelemetryClient,
- agent_dir: &Path,
- cold: bool,
-) -> serde_json::Value {
+/// Wait for the session's kernel to boot: running, and (for a revived
+/// boot, `cold: false`) with the snapshot restore applied.
+async fn wait_for_boot(engine: &pa_core::session_engine::engine::SessionEngine, cold: bool) {
let deadline = Instant::now() + Duration::from_mins(1);
loop {
- let events = kernel_bootstrap_events(client, agent_dir).await;
- if let Some(event) = events.iter().find(|event| {
- event_prop(event, "cold").and_then(serde_json::Value::as_bool) == Some(cold)
- }) {
- return event.clone();
+ if let Some(provisioner) = engine.kernel_provisioner_weak().upgrade() {
+ if provisioner.has_running_kernel() && (cold || provisioner.last_restore().is_some()) {
+ return;
+ }
}
assert!(
Instant::now() < deadline,
- "the kernel never reported a cold={cold} bootstrap: {events:?}"
+ "the kernel never reported a cold={cold} boot"
);
tokio::time::sleep(Duration::from_millis(200)).await;
}
@@ -273,6 +243,7 @@ impl Fixture {
client: self.client.clone(),
execution_mode: Some("test".to_string()),
now: None,
+ telemetry_enabled: None,
}),
..Default::default()
}
@@ -356,16 +327,11 @@ async fn session_end_then_resume_prewarms_and_revives_the_namespace() {
// completes here, BEFORE any prompt, so the first ipython call is a
// warm hit. `cold: false` is the revived-boot report (a snapshot
// existed to restore).
- let restored_boot = wait_for_boot(&fixture.client, &fixture.agent_dir, false).await;
+ wait_for_boot(&resumed, false).await;
let ready_elapsed = session_open.elapsed();
- assert_eq!(
- event_prop(&restored_boot, "outcome").and_then(serde_json::Value::as_str),
- Some("success"),
- "the restored boot must have succeeded"
- );
// The warm-hit bound: the boot finished before this assertion ran; a
// generous ceiling only (the sandbox may be loaded), the structural
- // claim is "ready before the first prompt", proven by the event.
+ // claim is "ready before the first prompt", proven by the boot.
assert!(
ready_elapsed < Duration::from_mins(1),
"resume boot took too long: {ready_elapsed:?}"
@@ -417,7 +383,7 @@ async fn session_end_then_resume_prewarms_and_revives_the_namespace() {
}
/// The prewarm arm does not over-fire: a FRESH session (no snapshot) with
-/// the config flag off stays lazy — no boot, no `kernel bootstrap` event.
+/// the config flag off stays lazy — no boot.
#[tokio::test]
#[allow(clippy::await_holding_lock)]
async fn fresh_session_without_snapshot_stays_lazy_without_the_flag() {
@@ -438,12 +404,13 @@ async fn fresh_session_without_snapshot_stays_lazy_without_the_flag() {
// lazy session reports nothing.
let deadline = Instant::now() + Duration::from_secs(5);
while Instant::now() < deadline {
- let events = kernel_bootstrap_events(&fixture.client, &fixture.agent_dir).await;
assert!(
- events.is_empty(),
- "a fresh session without a snapshot must not prewarm: {events:?}"
+ !engine
+ .kernel_provisioner_weak()
+ .upgrade()
+ .is_some_and(|provisioner| provisioner.has_running_kernel()),
+ "a fresh session without a snapshot must not prewarm"
);
tokio::time::sleep(Duration::from_millis(500)).await;
}
- let _ = engine;
}
diff --git a/crates/pa-daemon/src/acp/daemon.rs b/crates/pa-daemon/src/acp/daemon.rs
index d2af372201..4cfdf12b48 100644
--- a/crates/pa-daemon/src/acp/daemon.rs
+++ b/crates/pa-daemon/src/acp/daemon.rs
@@ -749,6 +749,8 @@ async fn handle_session_new(
// The client-owned daemon session: `--no-session` semantics.
let mut config = options.create_config.clone();
+ // The telemetry execution mode (TS main.ts `executionMode: appMode`).
+ config["executionMode"] = Value::String("acp".to_string());
// Verification seam: a scripted daemon session (the same `{"engine":
// "faux", ...}` form the in-process e2e rides). The product never sets
// it; the supervisor turns the path into the worker's script env.
diff --git a/crates/pa-daemon/src/agent_engine/config.rs b/crates/pa-daemon/src/agent_engine/config.rs
index d55254fa95..4a3c178826 100644
--- a/crates/pa-daemon/src/agent_engine/config.rs
+++ b/crates/pa-daemon/src/agent_engine/config.rs
@@ -95,6 +95,9 @@ pub(crate) struct CreateSessionResources {
pub(crate) skills: Vec<String>,
pub(crate) prompt_templates: Vec<String>,
pub(crate) autonomous: Option<pa_core::autonomous::AgentAutonomousConfig>,
+ /// The creating client's mode (`interactive`, `acp`, ...) for the
+ /// session's telemetry; absent reports `unknown` (TS parity).
+ pub(crate) execution_mode: Option<String>,
}
/// The create command's `--models` scope inputs (TS main.ts:548-568 +
@@ -140,3 +143,22 @@ impl pa_core::session_engine::rlm_usage::RlmChildUsageSink for ProducerUsageSink
})
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::CreateSessionResources;
+ use serde::Deserialize as _;
+
+ /// The create payload's `executionMode` reaches the session telemetry;
+ /// a create without one (an agent-spawned session) stays `None`
+ /// (reported as `unknown`, TS parity).
+ #[test]
+ fn create_resources_read_the_execution_mode() {
+ let payload = serde_json::json!({ "cwd": "/tmp", "executionMode": "interactive" });
+ let resources = CreateSessionResources::deserialize(&payload).unwrap();
+ assert_eq!(resources.execution_mode.as_deref(), Some("interactive"));
+ let resources =
+ CreateSessionResources::deserialize(&serde_json::json!({ "cwd": "/tmp" })).unwrap();
+ assert_eq!(resources.execution_mode, None);
+ }
+}
diff --git a/crates/pa-daemon/src/agent_engine/lifecycle.rs b/crates/pa-daemon/src/agent_engine/lifecycle.rs
index fc768bde18..0518364b8b 100644
--- a/crates/pa-daemon/src/agent_engine/lifecycle.rs
+++ b/crates/pa-daemon/src/agent_engine/lifecycle.rs
@@ -1080,8 +1080,14 @@ impl AgentSessionEngine {
&settings,
&self.config.agent_dir,
),
- execution_mode: Some("daemon".to_string()),
+ execution_mode: create_resources.execution_mode.clone(),
now: None,
+ telemetry_enabled: Some(
+ pa_core::session_engine::telemetry::telemetry_enabled_switch(
+ &self.cwd(),
+ &self.config.agent_dir,
+ ),
+ ),
}
});
// Bound before the awaited build: the purge-clone binding must not
diff --git a/crates/pa-daemon/src/agent_engine/tests.rs b/crates/pa-daemon/src/agent_engine/tests.rs
index df1e33cbe3..a2e12e4e85 100644
--- a/crates/pa-daemon/src/agent_engine/tests.rs
+++ b/crates/pa-daemon/src/agent_engine/tests.rs
@@ -57,6 +57,39 @@ fn write_compaction_settings(dir: &std::path::Path, reserve_tokens: u64) {
/// One faux-driven engine over its own tempdir (settings written before
/// the first prompt so the session build resolves them).
+/// Turns the repo's `cargo test` telemetry opt-out (`DO_NOT_TRACK=1` in
+/// `.cargo/config.toml`) back off for one test that asserts telemetry
+/// wiring, restoring it on drop. Debug builds have no network sink, so the
+/// opted-in test still sends nothing (its callers are ignored in release
+/// builds, which have one); serialized through the crate-wide
+/// `test_support::TELEMETRY_ENV_MUTEX` so the opt-ins and the supervisor
+/// tests' env scrub never interleave their restores.
+pub(crate) fn telemetry_opt_in() -> TelemetryOptIn {
+ let guard = crate::test_support::TELEMETRY_ENV_MUTEX
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ let previous = std::env::var_os("DO_NOT_TRACK");
+ std::env::set_var("DO_NOT_TRACK", "0");
+ TelemetryOptIn {
+ previous,
+ _guard: guard,
+ }
+}
+
+pub(crate) struct TelemetryOptIn {
+ previous: Option<std::ffi::OsString>,
+ _guard: std::sync::MutexGuard<'static, ()>,
+}
+
+impl Drop for TelemetryOptIn {
+ fn drop(&mut self) {
+ match self.previous.take() {
+ Some(value) => std::env::set_var("DO_NOT_TRACK", value),
+ None => std::env::remove_var("DO_NOT_TRACK"),
+ }
+ }
+}
+
pub(crate) fn faux_engine_with_settings(
script: &serde_json::Value,
reserve_tokens: u64,
diff --git a/crates/pa-daemon/src/agent_engine/tests/compaction.rs b/crates/pa-daemon/src/agent_engine/tests/compaction.rs
index 633825d2e4..ef9a997b6c 100644
--- a/crates/pa-daemon/src/agent_engine/tests/compaction.rs
+++ b/crates/pa-daemon/src/agent_engine/tests/compaction.rs
@@ -488,7 +488,12 @@ fn mirror_telemetry_properties(
/// turn's compaction counts into the open run's `compaction_count` and
/// the session total (TS `compaction_end` handling).
#[test]
+#[cfg_attr(
+ not(debug_assertions),
+ ignore = "release builds send to the real endpoint"
+)]
fn threshold_compaction_counts_into_the_run_telemetry() {
+ let _telemetry = super::telemetry_opt_in();
let _faux = FAUX_TEST_LOCK
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
@@ -548,7 +553,12 @@ fn threshold_compaction_counts_into_the_run_telemetry() {
/// The requested arm feeds the same seam: the boundary compaction the
/// kernel's `compact.run` scheduled counts into the open run.
#[test]
+#[cfg_attr(
+ not(debug_assertions),
+ ignore = "release builds send to the real endpoint"
+)]
fn requested_compaction_counts_into_the_run_telemetry() {
+ let _telemetry = super::telemetry_opt_in();
let _faux = FAUX_TEST_LOCK
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
@@ -608,7 +618,12 @@ fn requested_compaction_counts_into_the_run_telemetry() {
/// the same seam: the compaction the `CompactionManager` runs counts
/// into the still-open run it interrupts.
#[test]
+#[cfg_attr(
+ not(debug_assertions),
+ ignore = "release builds send to the real endpoint"
+)]
fn manual_wire_compaction_counts_into_the_run_telemetry() {
+ let _telemetry = super::telemetry_opt_in();
let _faux = FAUX_TEST_LOCK
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
diff --git a/crates/pa-daemon/src/lib.rs b/crates/pa-daemon/src/lib.rs
index a6244d56c7..f2154553db 100644
--- a/crates/pa-daemon/src/lib.rs
+++ b/crates/pa-daemon/src/lib.rs
@@ -129,3 +129,6 @@ pub(crate) mod user_bash;
pub mod util;
pub mod worker;
pub(crate) mod worker_stderr;
+
+#[cfg(test)]
+pub(crate) mod test_support;
diff --git a/crates/pa-daemon/src/model_allowlist.rs b/crates/pa-daemon/src/model_allowlist.rs
index 3fa865fa6b..af0a9e527a 100644
--- a/crates/pa-daemon/src/model_allowlist.rs
+++ b/crates/pa-daemon/src/model_allowlist.rs
@@ -119,7 +119,7 @@ impl ModelRefusalTelemetry {
/// Emit the refusal's `model refused` event (best-effort; no-op when
/// opted out). The client binds to `cwd` — the settings posture is
- /// scoped (the `PostHog` endpoint and local mirror read the project
+ /// scoped (the enabled switch and local mirror read the project
/// scope), so a session that moved directories rebinds instead of
/// reporting through the old project.
///
@@ -136,11 +136,7 @@ impl ModelRefusalTelemetry {
let settings = pa_core::settings::SettingsManager::create(cwd, &self.agent_dir);
// The same gating as the supervisor's `daemon event`: the env
// override wins, else the merged settings' telemetry switch.
- let enabled = match pa_telemetry::env_telemetry_override() {
- Some(enabled) => enabled,
- None => settings.get_telemetry_enabled(),
- };
- if !enabled {
+ if !pa_core::session_engine::telemetry::telemetry_switch(&settings).enabled() {
return;
}
// Once per distinct (surface, selector): repeated resolutions of the
@@ -334,7 +330,12 @@ mod tests {
}
#[tokio::test]
+ #[cfg_attr(
+ not(debug_assertions),
+ ignore = "release builds send to the real endpoint"
+ )]
async fn refusal_telemetry_honors_both_opt_outs() {
+ let _telemetry = crate::agent_engine::tests::telemetry_opt_in();
let dir = tempfile::tempdir().expect("tempdir");
// The create-command opt-out: no client ever.
let disabled = ModelRefusalTelemetry::new(dir.path().to_path_buf(), true);
@@ -365,7 +366,12 @@ mod tests {
/// getter re-resolving the same refused model stays silent after the
/// first event.
#[tokio::test]
+ #[cfg_attr(
+ not(debug_assertions),
+ ignore = "release builds send to the real endpoint"
+ )]
async fn refusal_telemetry_dedupes_repeated_resolves() {
+ let _telemetry = crate::agent_engine::tests::telemetry_opt_in();
let dir = tempfile::tempdir().expect("tempdir");
let telemetry = ModelRefusalTelemetry::new(dir.path().to_path_buf(), false);
telemetry.note_refused("session_start", "zai/glm-5.3", dir.path());
@@ -384,7 +390,12 @@ mod tests {
}
#[tokio::test]
+ #[cfg_attr(
+ not(debug_assertions),
+ ignore = "release builds send to the real endpoint"
+ )]
async fn refusal_telemetry_rebinds_when_the_cwd_moves() {
+ let _telemetry = crate::agent_engine::tests::telemetry_opt_in();
let dir = tempfile::tempdir().expect("tempdir");
let telemetry = ModelRefusalTelemetry::new(dir.path().join("agent"), false);
let first = dir.path().join("project-a");
diff --git a/crates/pa-daemon/src/supervisor.rs b/crates/pa-daemon/src/supervisor.rs
index 8f91305e60..b5e6de0a1f 100644
--- a/crates/pa-daemon/src/supervisor.rs
+++ b/crates/pa-daemon/src/supervisor.rs
@@ -153,6 +153,10 @@ pub struct Supervisor {
/// Daemon-lifecycle telemetry (`daemon event` schema v1), resolved at
/// run start (None = opted out); never blocks supervision paths.
telemetry: std::sync::Mutex<Option<pa_telemetry::TelemetryClient>>,
+ /// The frequent supervision events (attach/detach, worker exits and
+ /// restarts, overloads, saved-session listings), counted and sent as
+ /// one `daemon event` summary per window instead of one event each.
+ daemon_event_counts: std::sync::Mutex<notes::DaemonEventCounts>,
pub(crate) registry: SessionRegistry,
/// Worker outbound frames, with their client routing. The payload is
/// shared (`Arc`): every connected client's event arm receives every
@@ -307,6 +311,7 @@ impl Supervisor {
session_bindings: crate::session_bindings::SessionBindingTable::new(),
opening_files: std::sync::Mutex::new(std::collections::HashMap::new()),
telemetry: std::sync::Mutex::new(None),
+ daemon_event_counts: std::sync::Mutex::default(),
registry: SessionRegistry::new(),
events,
session_subscribers: subscribers::SessionSubscribers::new(),
@@ -352,17 +357,20 @@ impl Supervisor {
// inherit the raised limit.
let open_file_limit = pa_core::platform::process::raise_open_file_limit();
// Daemon telemetry: same env/settings posture as the sessions
- // (the supervisor is the `daemon` execution mode).
+ // (the supervisor is the `daemon` execution mode). Only an
+ // environment opt-out skips the client: a settings opt-out is the
+ // client's live switch, so `/telemetry on` resumes without a
+ // daemon restart.
{
let settings = pa_core::settings::SettingsManager::create(
std::env::current_dir().unwrap_or_default(),
&self.options.agent_dir,
);
- let disabled = match pa_telemetry::env_telemetry_override() {
- Some(enabled) => !enabled,
- None => !settings.get_telemetry_enabled(),
- };
- *self.telemetry.lock().unwrap() = (!disabled).then(|| {
+ let env_forced_off = matches!(
+ pa_core::session_engine::telemetry::telemetry_switch(&settings),
+ pa_core::session_engine::telemetry::TelemetrySwitch::Env { enabled: false, .. }
+ );
+ *self.telemetry.lock().unwrap() = (!env_forced_off).then(|| {
pa_core::session_engine::telemetry::build_client(&settings, &self.options.agent_dir)
});
}
@@ -513,6 +521,7 @@ impl Supervisor {
&self.options.socket_path,
self.bound_socket_identity.lock().unwrap().clone(),
);
+ self.flush_telemetry_on_exit().await;
Ok(())
}
}
diff --git a/crates/pa-daemon/src/supervisor/notes.rs b/crates/pa-daemon/src/supervisor/notes.rs
index 30df7bb789..d65c7ff1cd 100644
--- a/crates/pa-daemon/src/supervisor/notes.rs
+++ b/crates/pa-daemon/src/supervisor/notes.rs
@@ -2,10 +2,58 @@
//! notes, the rotating log line, and the spawn-ledger assembly.
use super::{paths, util, Arc, Result, Supervisor, Value};
+/// How long the frequent supervision events accumulate before their one
+/// `daemon event` summary.
+const DAEMON_EVENT_SUMMARY_WINDOW: std::time::Duration = std::time::Duration::from_secs(3600);
+
+/// The supervision counters of the current summary window.
+pub(crate) struct DaemonEventCounts {
+ window_started: std::time::Instant,
+ counts: std::collections::BTreeMap<String, u64>,
+ saved_sessions_usage_rows_max: u64,
+}
+
+impl Default for DaemonEventCounts {
+ fn default() -> Self {
+ Self {
+ window_started: std::time::Instant::now(),
+ counts: std::collections::BTreeMap::new(),
+ saved_sessions_usage_rows_max: 0,
+ }
+ }
+}
+
+fn send_daemon_event_summary(client: &pa_telemetry::TelemetryClient, counts: &DaemonEventCounts) {
+ pa_core::session_engine::telemetry::track_daemon_event_summary(
+ client,
+ counts.window_started.elapsed().as_millis() as u64,
+ &counts.counts,
+ counts.saved_sessions_usage_rows_max,
+ );
+}
+
impl Supervisor {
+ /// The daemon's live recording gate: the same env-then-settings
+ /// resolution the client's delivery pass and the session seams apply,
+ /// asked per event, so a `/telemetry` flip lands without a restart.
+ /// Daemon events count and fire only while it is on — an opt-out
+ /// window's events never ride a later summary or incident after a
+ /// re-enable.
+ fn telemetry_recording_on(&self) -> bool {
+ let cwd = std::env::current_dir().unwrap_or_default();
+ let switch = pa_core::session_engine::telemetry::telemetry_enabled_switch(
+ &cwd,
+ &self.options.agent_dir,
+ );
+ (switch.enabled)()
+ }
+
/// Emit the `daemon event` adoption signal for a session-archive sweep
/// (best-effort, non-blocking; no-op when the daemon is opted out).
pub(crate) fn note_sessions_archived(&self, count: usize) {
+ if !self.telemetry_recording_on() {
+ return;
+ }
if let Some(client) = &*self.telemetry.lock().unwrap() {
pa_core::session_engine::telemetry::track_sessions_archived(client, count);
}
@@ -19,6 +67,9 @@ impl Supervisor {
if count == 0 {
return;
}
+ if !self.telemetry_recording_on() {
+ return;
+ }
if let Some(client) = &*self.telemetry.lock().unwrap() {
pa_core::session_engine::telemetry::track_worker_children_closed(client, count);
}
@@ -27,6 +78,9 @@ impl Supervisor {
/// Emit the live-catalog warm-up settle's `daemon event` (schema v1,
/// kind `catalog_refresh`): the served model count, primitives only.
pub(super) fn note_catalog_refresh(&self, count: usize) {
+ if !self.telemetry_recording_on() {
+ return;
+ }
if let Some(client) = &*self.telemetry.lock().unwrap() {
pa_core::session_engine::telemetry::track_catalog_refresh(client, count);
}
@@ -36,6 +90,9 @@ impl Supervisor {
/// kind `deleted_child_usage_captured`): source + count, primitives
/// only.
pub(crate) fn note_deleted_child_usage_captured(&self, source: &str, count: usize) {
+ if !self.telemetry_recording_on() {
+ return;
+ }
if let Some(client) = &*self.telemetry.lock().unwrap() {
pa_core::session_engine::telemetry::track_deleted_child_usage_captured(
client, source, count,
@@ -43,14 +100,71 @@ impl Supervisor {
}
}
- /// Emit a `daemon event` (best-effort, non-blocking; no-op when the
- /// daemon is opted out).
+ /// Count a frequent supervision event (attach/detach, worker exits and
+ /// restarts, overloads, refusals) into the window's `daemon event`
+ /// summary (best-effort; no-op when the daemon is opted out).
pub(crate) fn note_daemon_event(&self, kind: &str, exit_reason: Option<&str>) {
- if let Some(client) = &*self.telemetry.lock().unwrap() {
- pa_core::session_engine::telemetry::track_daemon_event(client, kind, exit_reason);
+ let key = match (kind, exit_reason) {
+ ("worker_exited", Some("normal")) => "worker_exited_normal_count".to_string(),
+ ("worker_exited", _) => "worker_exited_crash_count".to_string(),
+ (kind, _) => format!("{kind}_count"),
+ };
+ self.count_daemon_event(|counts| *counts.counts.entry(key).or_default() += 1);
+ }
+
+ /// Count one served saved-session listing and its usage-bearing rows.
+ pub(crate) fn note_saved_sessions_listed(&self, rows_with_usage: usize) {
+ self.count_daemon_event(|counts| {
+ *counts
+ .counts
+ .entry("saved_sessions_list_count".to_string())
+ .or_default() += 1;
+ counts.saved_sessions_usage_rows_max = counts
+ .saved_sessions_usage_rows_max
+ .max(rows_with_usage as u64);
+ });
+ }
+
+ /// Apply one count; once the window is an hour old, send the summary
+ /// and start a new window.
+ fn count_daemon_event(&self, update: impl FnOnce(&mut DaemonEventCounts)) {
+ if !self.telemetry_recording_on() {
+ // Count only while telemetry is on, so an opt-out window's
+ // events never ride the next summary after a re-enable.
+ return;
+ }
+ let Some(client) = self.telemetry.lock().unwrap().clone() else {
+ return;
+ };
+ let mut counts = self
+ .daemon_event_counts
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ update(&mut counts);
+ if counts.window_started.elapsed() >= DAEMON_EVENT_SUMMARY_WINDOW {
+ send_daemon_event_summary(&client, &std::mem::take(&mut *counts));
}
}
+ /// The daemon's exit: send the current window's partial summary and
+ /// drain the telemetry client, so the last window's counts and any
+ /// queued event are not lost when the process ends.
+ pub(super) async fn flush_telemetry_on_exit(&self) {
+ let Some(client) = self.telemetry.lock().unwrap().take() else {
+ return;
+ };
+ let counts = std::mem::take(
+ &mut *self
+ .daemon_event_counts
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner),
+ );
+ if !counts.counts.is_empty() {
+ send_daemon_event_summary(&client, &counts);
+ }
+ let _ = client.shutdown().await;
+ }
+
/// Publish one session event to the session's attached connections
/// (the send-time delivery pass — TS `handleWorkerFrame`'s fan-out
/// evaluates the attached set in the same pass that writes). A full
@@ -69,6 +183,9 @@ impl Supervisor {
/// The abort supervision's declaration event (`daemon event` schema v1,
/// kind `compaction_abort_declared`): one count, never session payload.
pub(crate) fn note_compaction_abort_declared(&self) {
+ if !self.telemetry_recording_on() {
+ return;
+ }
if let Some(client) = &*self.telemetry.lock().unwrap() {
pa_core::session_engine::telemetry::track_compaction_abort_declared(client);
}
diff --git a/crates/pa-daemon/src/supervisor/sessions.rs b/crates/pa-daemon/src/supervisor/sessions.rs
index 8f769e20d2..8c97443355 100644
--- a/crates/pa-daemon/src/supervisor/sessions.rs
+++ b/crates/pa-daemon/src/supervisor/sessions.rs
@@ -438,9 +438,7 @@ impl Supervisor {
// agents-view spend columns' data (a count only, never session
// payload).
let rows_with_usage = infos.iter().filter(|info| info.usage.is_some()).count();
- if let Some(client) = &*self.telemetry.lock().unwrap() {
- pa_core::session_engine::telemetry::track_saved_sessions_usage(client, rows_with_usage);
- }
+ self.note_saved_sessions_listed(rows_with_usage);
lines
}
diff --git a/crates/pa-daemon/src/supervisor/tests.rs b/crates/pa-daemon/src/supervisor/tests.rs
index 1e850dfe28..1efade190c 100644
--- a/crates/pa-daemon/src/supervisor/tests.rs
+++ b/crates/pa-daemon/src/supervisor/tests.rs
@@ -1,5 +1,54 @@
use super::*;
+/// The cargo test config sets `DO_NOT_TRACK=1`; the daemon's live
+/// recording gate reads it (env before settings). Tests that exercise
+/// gated daemon-event paths hold this guard while the three override
+/// vars are scrubbed, and restore them after. The env is process-wide,
+/// so these tests serialize through the crate-wide
+/// `test_support::TELEMETRY_ENV_MUTEX` (shared with `agent_engine`'s
+/// `telemetry_opt_in`) while they hold it.
+const TELEMETRY_ENV_VARS: [&str; 3] = ["DO_NOT_TRACK", "PI_OFFLINE", "PRIME_AGENT_TELEMETRY"];
+
+struct CleanTelemetryEnv {
+ saved: Vec<(&'static str, Option<String>)>,
+ _env_lock: std::sync::MutexGuard<'static, ()>,
+}
+
+impl Default for CleanTelemetryEnv {
+ fn default() -> Self {
+ // Held first: the vars may not be touched while another env test
+ // runs.
+ let env_lock = crate::test_support::TELEMETRY_ENV_MUTEX
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ let saved = TELEMETRY_ENV_VARS
+ .iter()
+ .map(|var| {
+ let value = std::env::var(var).ok();
+ std::env::remove_var(var);
+ (*var, value)
+ })
+ .collect();
+ Self {
+ saved,
+ _env_lock: env_lock,
+ }
+ }
+}
+
+impl Drop for CleanTelemetryEnv {
+ fn drop(&mut self) {
+ // The manual drop runs before the field drops: the restore lands
+ // while the env lock is still held.
+ for (var, value) in self.saved.drain(..) {
+ match value {
+ Some(value) => std::env::set_var(var, value),
+ None => std::env::remove_var(var),
+ }
+ }
+ }
+}
+
/// The crash-path failure count: spawn-dies-fast churn accumulates to
/// the give-up cap (the storm's counter could never grow while
/// relaunch-spawns kept resetting it); a child that lived past the
@@ -1778,3 +1827,73 @@ async fn a_ledger_child_wake_joins_an_already_hosting_resident() {
"the ledger wake's reuse arm must not launch a second worker"
);
}
+
+/// The daemon's exit sends the partial `daemon event` summary of the
+/// current window (the window is under an hour, so no count sent it yet).
+#[tokio::test]
+async fn the_exit_flush_sends_the_partial_daemon_event_summary() {
+ let _env = CleanTelemetryEnv::default();
+ let dir = tempfile::TempDir::new().unwrap();
+ let supervisor = Supervisor::new(SupervisorOptions {
+ socket_path: dir.path().join("daemon.sock"),
+ agent_dir: dir.path().join("agent"),
+ })
+ .expect("supervisor");
+ let mock = Arc::new(pa_telemetry::MockSink::new());
+ let mut config = pa_telemetry::TelemetryClientConfig::new("install-1");
+ config.sinks = vec![mock.clone() as Arc<dyn pa_telemetry::TelemetrySink>];
+ *supervisor.telemetry.lock().unwrap() =
+ Some(pa_telemetry::TelemetryClient::spawn(config).unwrap());
+ supervisor.note_daemon_event("attach", None);
+ supervisor.note_daemon_event("attach", None);
+ assert!(mock.events().is_empty(), "the window is still open");
+ supervisor.flush_telemetry_on_exit().await;
+ let events = mock.events();
+ assert_eq!(events.len(), 1);
+ assert_eq!(events[0].name, "daemon event");
+ assert_eq!(
+ events[0].properties.get("kind"),
+ Some(&Value::from("summary"))
+ );
+ assert_eq!(
+ events[0].properties.get("attach_count"),
+ Some(&Value::from(2))
+ );
+}
+
+/// The daemon's live gate counts only while telemetry is on: events
+/// that fire during a settings opt-out window never ride the summary
+/// after a re-enable. The counters skip while off (they are not
+/// severed), so the on-period count before the window still reports.
+#[tokio::test]
+async fn off_window_daemon_events_never_count_into_the_summary() {
+ let _env = CleanTelemetryEnv::default();
+ let dir = tempfile::TempDir::new().unwrap();
+ let agent_dir = dir.path().join("agent");
+ let mut settings = pa_core::settings::SettingsManager::create(dir.path(), &agent_dir);
+ settings.set_telemetry_enabled(false).unwrap();
+ let supervisor = Supervisor::new(SupervisorOptions {
+ socket_path: dir.path().join("daemon.sock"),
+ agent_dir: agent_dir.clone(),
+ })
+ .expect("supervisor");
+ let mock = Arc::new(pa_telemetry::MockSink::new());
+ let mut config = pa_telemetry::TelemetryClientConfig::new("install-1");
+ config.sinks = vec![mock.clone() as Arc<dyn pa_telemetry::TelemetrySink>];
+ *supervisor.telemetry.lock().unwrap() =
+ Some(pa_telemetry::TelemetryClient::spawn(config).unwrap());
+ // Off: the event skips, so nothing counts.
+ supervisor.note_daemon_event("attach", None);
+ settings.set_telemetry_enabled(true).unwrap();
+ // Back on: the event counts again.
+ supervisor.note_daemon_event("attach", None);
+ supervisor.flush_telemetry_on_exit().await;
+ let events = mock.events();
+ assert_eq!(events.len(), 1);
+ assert_eq!(events[0].name, "daemon event");
+ assert_eq!(
+ events[0].properties.get("attach_count"),
+ Some(&Value::from(1)),
+ "the off-window attach never counts"
+ );
+}
diff --git a/crates/pa-daemon/src/supervisor/worker_lifecycle.rs b/crates/pa-daemon/src/supervisor/worker_lifecycle.rs
index 20c53c811f..fbf04bae27 100644
--- a/crates/pa-daemon/src/supervisor/worker_lifecycle.rs
+++ b/crates/pa-daemon/src/supervisor/worker_lifecycle.rs
@@ -259,6 +259,7 @@ impl Supervisor {
"skills",
"promptTemplates",
"autonomous",
+ "executionMode",
] {
if let Some(value) = config_object.and_then(|config| config.get(key)) {
durable_rest.insert(key.to_string(), value.clone());
diff --git a/crates/pa-daemon/src/test_support.rs b/crates/pa-daemon/src/test_support.rs
new file mode 100644
index 0000000000..9f2f6e67b8
--- /dev/null
+++ b/crates/pa-daemon/src/test_support.rs
@@ -0,0 +1,9 @@
+//! Test-only shared state: one crate-wide lock for the process env.
+
+/// Process-wide env reads and writes (the telemetry override vars)
+/// serialize through one lock across the crate's test modules: parallel
+/// test threads in the same binary otherwise race the process env. Both
+/// the supervisor tests' scrub guard and `agent_engine`'s
+/// `telemetry_opt_in` hold this lock through their restores.
+#[cfg(test)]
+pub(crate) static TELEMETRY_ENV_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());
diff --git a/crates/pa-telemetry/Cargo.toml b/crates/pa-telemetry/Cargo.toml
index b863d3f3fd..3a5b9203d9 100644
--- a/crates/pa-telemetry/Cargo.toml
+++ b/crates/pa-telemetry/Cargo.toml
@@ -14,6 +14,9 @@ tokio.workspace = true
tracing.workspace = true
uuid = { version = "1", features = ["v4"] }
+[target.'cfg(unix)'.dependencies]
+rustix = { version = "1", features = ["system", "fs"] }
+
[dev-dependencies]
tempfile = "3"
diff --git a/crates/pa-telemetry/README.md b/crates/pa-telemetry/README.md
index f7813f0fb8..4e2e4e5d6b 100644
--- a/crates/pa-telemetry/README.md
+++ b/crates/pa-telemetry/README.md
@@ -1,25 +1,21 @@
# pa-telemetry
Modular telemetry: the event schema, queueing/batching, sinks, and the
-pseudonymous installation identity for Prime Agent product analytics
-(PostHog-backed, self-hostable).
+pseudonymous installation identity for Prime Agent product analytics.
## Scope
- `Properties`: primitive-only property maps (the privacy boundary — strings,
numbers, booleans, null; structured values are rejected at insertion).
-- `TelemetryEvent`: `{name, timestamp, properties}` records.
+- `TelemetryEvent`: `{id, name, timestamp, properties}` records.
- `TelemetryClient`: non-blocking `track(event, properties)`, `flush`,
`shutdown`. One background worker, capped queue (drop-oldest), batched
flush (size + interval + explicit), fan-out to every sink. Best-effort by
contract: never blocks, never panics, never fails the agent.
-- `TelemetrySink` trait + shipped sinks: `PostHogSink` (batched capture API,
- endpoint + project key from env/settings — nothing compiled in, empty
- configuration resolves to `NoopSink`; a 401 is terminal — bad or
- missing-scope credentials disable the sink for the process instead of
- re-requesting every flush), `FlagsClient` (PostHog decide v3
- feature flags with a 5-minute TTL cache, defaults offline; a 401 stops
- the decide polling the same way),
+- `TelemetrySink` trait + shipped sinks: `AnalyticsSink` (the one product
+ destination: the TS endpoint `ANALYTICS_ENDPOINT` and wire format
+ `{installation_id, events: [{id, name, timestamp, properties}]}`, no
+ credentials, 1.5s timeout; the platform backend forwards to PostHog),
`FileSink` (local JSONL transparency mirror at `<agentDir>/telemetry.jsonl`),
`NoopSink` (opt-out fast path), `MockSink` (tests, also re-exported for
downstream crate tests).
@@ -33,8 +29,9 @@ pseudonymous installation identity for Prime Agent product analytics
crate's install id) already depends on it while it depends on no other
workspace crate; pa-core re-exports it as `platform::rename_onto` so its
platform wall stays the engine's single platform entry.
-- Env override resolution for the opt-in posture: `PI_OFFLINE`,
- `DO_NOT_TRACK`, `PRIME_AGENT_TELEMETRY`.
+- The TS boolean env parsing (`parse_bool_override`); the opt-out
+ precedence (`PI_OFFLINE`, `DO_NOT_TRACK`, `PRIME_AGENT_TELEMETRY`,
+ settings) lives in pa-core's `telemetry_switch`.
## Non-goals
@@ -56,8 +53,9 @@ pseudonymous installation identity for Prime Agent product analytics
- `Properties`, `TelemetryEvent`
- `install_id(agent_dir)`
- `rename_onto(from, to)`
-- `env_telemetry_override()`, `parse_bool_override(value)`
-- Sinks: `PostHogSink`, `FileSink`, `NoopSink`, `MockSink` (+ `RecordedBatch`)
+- `parse_bool_override(value)`, `existing_install_id(agent_dir)`
+- Sinks: `AnalyticsSink` (+ `ANALYTICS_ENDPOINT`), `FileSink`, `NoopSink`, `MockSink`
+ (+ `RecordedBatch`)
## Placement
diff --git a/crates/pa-telemetry/src/catalog.rs b/crates/pa-telemetry/src/catalog.rs
index b02e0084fd..1f40b4700a 100644
--- a/crates/pa-telemetry/src/catalog.rs
+++ b/crates/pa-telemetry/src/catalog.rs
@@ -1,14 +1,13 @@
//! The versioned event catalog: every product event's name and typed property
//! rules, the successor of the deleted `docs/telemetry-events.md`.
//!
-//! Schema version 2 adds the tracking vocabulary of the (never-merged) TS
-//! PR #2117: `agent run started`, `agent error`, `agent timing`,
-//! `agent tool summary`, `onboarding stage`, `agent feature outcome`,
-//! `agent startup stage`, `agent input stage`, and
-//! `agent installation stage`, each a catalog entry with typed property
-//! rules, plus enrichment on the legacy session events. The v1 adoption
-//! events stay catalogued (schema rules: additive changes do not bump the
-//! schema version; the new-event vocabulary does).
+//! The catalog is the low-frequency set: per-run facts ride the one
+//! `agent run completed` per run (TS parity), per-session facts ride
+//! `agent session ended`, the interactive client's adoption counters ride
+//! its one `tui exit`; the remaining events are lifecycle moments
+//! (startup, onboarding, installation, update, daemon incidents). Schema
+//! version 2 is the #2117 vocabulary (the v2 enrichment on the legacy
+//! events and the onboarding/startup/installation stages).
//!
//! [`sanitize`] is the platform adjust layer: before a batch reaches any
//! sink, every catalogued event's properties are normalized against its
@@ -27,14 +26,6 @@ use crate::properties::Properties;
/// it.
pub const SCHEMA_VERSION: u64 = 2;
-/// The property-rule revision of the error-message policy (the reviewed
-/// fixed-string set). #2117 `error_message_policy_revision`.
-pub const ERROR_MESSAGE_POLICY_REVISION: u64 = 1;
-
-/// The error-classifier revision (`classifier_revision` on `agent error`).
-/// Bumped to 2 when the `stream_drop` subtype/code joined the vocabulary.
-pub const ERROR_CLASSIFIER_REVISION: u64 = 2;
-
// ---------------------------------------------------------------------------
// Rule kinds
// ---------------------------------------------------------------------------
@@ -220,174 +211,6 @@ pub const ERROR_SUBTYPES: &[&str] = &[
"unknown",
];
-/// The #2117 error codes (provider codes, OS error codes, daemon codes).
-pub const ERROR_CODES: &[&str] = &[
- "invalid_api_key",
- "invalid_token",
- "invalid_grant",
- "token_expired",
- "expired_token",
- "missing_api_key",
- "authentication_error",
- "unauthorized",
- "permission_error",
- "permission_denied",
- "access_denied",
- "forbidden",
- "model_not_found",
- "model_access_denied",
- "usage_not_included",
- "insufficient_funds",
- "insufficient_balance",
- "insufficient_quota",
- "quota_exceeded",
- "resource_exhausted",
- "rate_limit_error",
- "rate_limit_exceeded",
- "too_many_requests",
- "overloaded_error",
- "server_error",
- "api_error",
- "service_unavailable",
- "refusal",
- "content_filter",
- "safety",
- "malformed_response",
- "stream_drop",
- "context_length_exceeded",
- "context_window_exceeded",
- "ENOENT",
- "EACCES",
- "EPERM",
- "ENOSPC",
- "EMFILE",
- "ENFILE",
- "EROFS",
- "ELOCKED",
- "EEXIST",
- "ENOTEMPTY",
- "EBUSY",
- "ENOTDIR",
- "EISDIR",
- "EIO",
- "EADDRINUSE",
- "EADDRNOTAVAIL",
- "ECONNRESET",
- "ECONNREFUSED",
- "ECONNABORTED",
- "EHOSTUNREACH",
- "ENETUNREACH",
- "ENOTFOUND",
- "EAI_AGAIN",
- "EPIPE",
- "ETIMEDOUT",
- "UND_ERR_CONNECT_TIMEOUT",
- "UND_ERR_HEADERS_TIMEOUT",
- "UND_ERR_BODY_TIMEOUT",
- "UND_ERR_SOCKET",
- "missing_session_cwd",
- "session_import_file_not_found",
- "session_already_active",
- "session_recovering",
- "daemon_supervisor_already_running",
- "supervisor_generation_stale",
- "daemon_shutdown_in_progress",
- "supervisor_recovery_cancelled",
- "command_result_uncertain",
- "unknown",
-];
-
-/// The #2117 error components.
-pub const ERROR_COMPONENTS: &[&str] = &[
- "startup",
- "configuration",
- "authentication",
- "provider",
- "tools",
- "mcp",
- "daemon",
- "rpc",
- "acp",
- "session",
- "compaction",
- "background",
- "unknown",
-];
-
-/// The #2117 error operations.
-pub const ERROR_OPERATIONS: &[&str] = &[
- "startup",
- "load",
- "save",
- "refresh",
- "validate",
- "login",
- "logout",
- "discover",
- "request",
- "stream",
- "execute",
- "connect",
- "attach",
- "parse",
- "compact",
- "retry",
- "shutdown",
- "uncaught_exception",
- "unhandled_rejection",
- "unknown",
-];
-
-/// The #2117 error stages.
-pub const ERROR_STAGES: &[&str] = &[
- "startup",
- "configuration",
- "authentication",
- "model_discovery",
- "model_request",
- "model_stream",
- "tool_execution",
- "session_persistence",
- "compaction",
- "background",
- "shutdown",
- "unknown",
-];
-
-/// The #2117 recovery actions.
-pub const RECOVERY_ACTIONS: &[&str] = &[
- "automatic_retry",
- "manual_retry",
- "credentials_updated",
- "provider_changed",
- "model_changed",
- "cancelled",
- "none",
- "unknown",
-];
-
-/// The #2117 recovery outcomes.
-pub const RECOVERY_OUTCOMES: &[&str] = &[
- "pending",
- "success",
- "failed",
- "cancelled",
- "not_observed",
- "unknown",
-];
-
-/// The #2117 classification sources.
-pub const CLASSIFICATION_SOURCES: &[&str] = &[
- "structured_reason",
- "http_status",
- "typed_error",
- "reviewed_message",
- "unknown",
-];
-
-/// The error-message sources (#2117 `error_message_source`).
-pub const ERROR_MESSAGE_SOURCES: &[&str] = &["reviewed_literal", "system_template"];
-
/// The #2117 tool categories.
pub const TOOL_CATEGORIES: &[&str] = &[
"read", "write", "edit", "bash", "grep", "find", "ls", "ipython", "mcp", "custom", "unknown",
@@ -402,37 +225,6 @@ pub const TERMINAL_OUTCOMES: &[&str] = &[
"unknown",
];
-/// The #2117 timing origins.
-pub const TIMING_ORIGINS: &[&str] = &[
- "worker_input",
- "worker_action",
- "worker_run",
- "ui_input",
- "ui_cancellation",
- "ui",
- "unknown",
-];
-
-/// The #2117 timing stages.
-pub const TIMING_STAGES: &[&str] = &[
- "first_status",
- "first_model_event",
- "first_reasoning",
- "first_text",
- "tool",
- "retry_wait",
- "compaction",
- "stream_gap",
- "terminal",
- "queue_wait",
- "local_preparation",
- "input_to_run",
- "provider_dispatch",
- "time_to_error",
- "cancellation_to_idle",
- "unknown",
-];
-
/// The #2117 run triggers.
pub const RUN_TRIGGERS: &[&str] = &["prompt", "continuation", "unknown"];
@@ -495,12 +287,6 @@ pub const FEATURE_OUTCOMES: &[&str] = &[
"unavailable",
];
-/// The #2117 configuration choices (effort levels, goal actions).
-pub const CONFIGURATION_CHOICES: &[&str] = &[
- "off", "minimal", "low", "medium", "high", "xhigh", "max", "create", "status", "pause",
- "resume", "clear", "unknown",
-];
-
/// The #2117 onboarding stages.
pub const ONBOARDING_STAGES: &[&str] = &[
"entry",
@@ -621,21 +407,6 @@ pub const INPUT_STAGES: &[&str] = &[
"cancellation_to_idle",
];
-/// The #2117 input outcomes.
-pub const INPUT_OUTCOMES: &[&str] = &[
- "started",
- "success",
- "error",
- "cancelled",
- "no_run",
- "unknown",
- "initiated",
- "completed",
- "failed",
- "canceled",
- "unavailable",
-];
-
/// The #2117 startup stages.
pub const STARTUP_STAGES: &[&str] = &[
"ui_ready",
@@ -770,14 +541,6 @@ const fn duration() -> PropKind {
}
}
-const fn http_status() -> PropKind {
- PropKind::Number {
- max: 599,
- integer: true,
- nullable: true,
- }
-}
-
const fn uuid() -> PropKind {
PropKind::Uuid
}
@@ -790,14 +553,6 @@ const fn boolean() -> PropKind {
PropKind::Boolean { nullable: false }
}
-const fn nullable_boolean() -> PropKind {
- PropKind::Boolean { nullable: true }
-}
-
-const fn error_message() -> PropKind {
- PropKind::BoundedString { max: 4096 }
-}
-
const fn cost() -> PropKind {
PropKind::Cost {
max: 1_000_000.0,
@@ -826,19 +581,6 @@ const AGENT_STARTED: EventRule = EventRule {
],
};
-/// `agent run started` (v2): fires at the run's `AgentStart`, pairing every
-/// admitted run with its id and trigger before any model call.
-const AGENT_RUN_STARTED: EventRule = EventRule {
- name: "agent run started",
- since: 2,
- properties: &[
- ("session_id", required(uuid())),
- ("run_id", required(uuid())),
- ("run_index", required(count())),
- ("trigger", required(enum_rule(RUN_TRIGGERS, "unknown"))),
- ],
-};
-
/// `agent run completed` (v1, enriched in v2): run finalize.
const AGENT_RUN_COMPLETED: EventRule = EventRule {
name: "agent run completed",
@@ -897,6 +639,56 @@ const AGENT_RUN_COMPLETED: EventRule = EventRule {
("retry_wait_ms", optional(duration())),
("compaction_duration_ms", optional(duration())),
("max_stream_gap_ms", optional(duration())),
+ // The folded per-run aggregates (one event per run):
+ ("model_latency_p50_ms", optional(duration())),
+ ("model_error_count", optional(count())),
+ ("error_authentication_count", optional(count())),
+ ("error_rate_limit_count", optional(count())),
+ ("error_timeout_count", optional(count())),
+ ("error_context_limit_count", optional(count())),
+ ("error_network_count", optional(count())),
+ ("error_provider_unavailable_count", optional(count())),
+ ("error_other_count", optional(count())),
+ ("tool_read_call_count", optional(count())),
+ ("tool_read_error_count", optional(count())),
+ ("tool_read_duration_ms", optional(duration())),
+ ("tool_read_max_duration_ms", optional(duration())),
+ ("tool_write_call_count", optional(count())),
+ ("tool_write_error_count", optional(count())),
+ ("tool_write_duration_ms", optional(duration())),
+ ("tool_write_max_duration_ms", optional(duration())),
+ ("tool_edit_call_count", optional(count())),
+ ("tool_edit_error_count", optional(count())),
+ ("tool_edit_duration_ms", optional(duration())),
+ ("tool_edit_max_duration_ms", optional(duration())),
+ ("tool_bash_call_count", optional(count())),
+ ("tool_bash_error_count", optional(count())),
+ ("tool_bash_duration_ms", optional(duration())),
+ ("tool_bash_max_duration_ms", optional(duration())),
+ ("tool_grep_call_count", optional(count())),
+ ("tool_grep_error_count", optional(count())),
+ ("tool_grep_duration_ms", optional(duration())),
+ ("tool_grep_max_duration_ms", optional(duration())),
+ ("tool_find_call_count", optional(count())),
+ ("tool_find_error_count", optional(count())),
+ ("tool_find_duration_ms", optional(duration())),
+ ("tool_find_max_duration_ms", optional(duration())),
+ ("tool_ls_call_count", optional(count())),
+ ("tool_ls_error_count", optional(count())),
+ ("tool_ls_duration_ms", optional(duration())),
+ ("tool_ls_max_duration_ms", optional(duration())),
+ ("tool_ipython_call_count", optional(count())),
+ ("tool_ipython_error_count", optional(count())),
+ ("tool_ipython_duration_ms", optional(duration())),
+ ("tool_ipython_max_duration_ms", optional(duration())),
+ ("mcp_tool_call_count", optional(count())),
+ ("mcp_tool_error_count", optional(count())),
+ ("mcp_tool_duration_ms", optional(duration())),
+ ("mcp_tool_max_duration_ms", optional(duration())),
+ ("custom_tool_call_count", optional(count())),
+ ("custom_tool_error_count", optional(count())),
+ ("custom_tool_duration_ms", optional(duration())),
+ ("custom_tool_max_duration_ms", optional(duration())),
],
};
@@ -925,137 +717,87 @@ const AGENT_SESSION_ENDED: EventRule = EventRule {
"terminal_outcome",
optional(enum_rule(TERMINAL_OUTCOMES, "unknown")),
),
+ // The folded per-session counters:
+ ("retry_count", optional(count())),
+ ("failover_count", optional(count())),
+ ("model_error_count", optional(count())),
+ ("skill_use_count", optional(count())),
+ ("mcp_connector_use_count", optional(count())),
+ ("kernel_bootstrap_count", optional(count())),
+ ("kernel_bootstrap_cold_count", optional(count())),
+ ("kernel_bootstrap_failed_count", optional(count())),
+ ("kernel_bootstrap_max_ms", optional(duration())),
+ ("rlm_child_usage_count", optional(count())),
+ ("rlm_child_input_tokens", optional(tokens())),
+ ("rlm_child_output_tokens", optional(tokens())),
+ ("rlm_child_cache_read_tokens", optional(tokens())),
+ ("rlm_child_cache_write_tokens", optional(tokens())),
+ ("rlm_child_cost", optional(cost())),
+ ("feature_model_initiated_count", optional(count())),
+ ("feature_model_completed_count", optional(count())),
+ ("feature_model_failed_count", optional(count())),
+ ("feature_model_canceled_count", optional(count())),
+ ("feature_model_unavailable_count", optional(count())),
+ ("feature_login_initiated_count", optional(count())),
+ ("feature_login_completed_count", optional(count())),
+ ("feature_login_failed_count", optional(count())),
+ ("feature_login_canceled_count", optional(count())),
+ ("feature_login_unavailable_count", optional(count())),
+ ("feature_logout_initiated_count", optional(count())),
+ ("feature_logout_completed_count", optional(count())),
+ ("feature_logout_failed_count", optional(count())),
+ ("feature_logout_canceled_count", optional(count())),
+ ("feature_logout_unavailable_count", optional(count())),
+ ("feature_effort_initiated_count", optional(count())),
+ ("feature_effort_completed_count", optional(count())),
+ ("feature_effort_failed_count", optional(count())),
+ ("feature_effort_canceled_count", optional(count())),
+ ("feature_effort_unavailable_count", optional(count())),
+ ("feature_goal_initiated_count", optional(count())),
+ ("feature_goal_completed_count", optional(count())),
+ ("feature_goal_failed_count", optional(count())),
+ ("feature_goal_canceled_count", optional(count())),
+ ("feature_goal_unavailable_count", optional(count())),
+ ("feature_new_initiated_count", optional(count())),
+ ("feature_new_completed_count", optional(count())),
+ ("feature_new_failed_count", optional(count())),
+ ("feature_new_canceled_count", optional(count())),
+ ("feature_new_unavailable_count", optional(count())),
+ ("feature_resume_initiated_count", optional(count())),
+ ("feature_resume_completed_count", optional(count())),
+ ("feature_resume_failed_count", optional(count())),
+ ("feature_resume_canceled_count", optional(count())),
+ ("feature_resume_unavailable_count", optional(count())),
+ ("feature_fork_initiated_count", optional(count())),
+ ("feature_fork_completed_count", optional(count())),
+ ("feature_fork_failed_count", optional(count())),
+ ("feature_fork_canceled_count", optional(count())),
+ ("feature_fork_unavailable_count", optional(count())),
+ ("feature_clone_initiated_count", optional(count())),
+ ("feature_clone_completed_count", optional(count())),
+ ("feature_clone_failed_count", optional(count())),
+ ("feature_clone_canceled_count", optional(count())),
+ ("feature_clone_unavailable_count", optional(count())),
+ ("feature_tree_initiated_count", optional(count())),
+ ("feature_tree_completed_count", optional(count())),
+ ("feature_tree_failed_count", optional(count())),
+ ("feature_tree_canceled_count", optional(count())),
+ ("feature_tree_unavailable_count", optional(count())),
+ ("feature_feedback_initiated_count", optional(count())),
+ ("feature_feedback_completed_count", optional(count())),
+ ("feature_feedback_failed_count", optional(count())),
+ ("feature_feedback_canceled_count", optional(count())),
+ ("feature_feedback_unavailable_count", optional(count())),
],
};
/// `agent command used` (v1): builtin command names only, never arguments.
+/// The TUI client sends it with the base properties and the command name
+/// alone (TS `captureAgentCommandUsed`), so it carries no session id.
const AGENT_COMMAND_USED: EventRule = EventRule {
name: "agent command used",
since: 1,
- properties: &[
- ("session_id", required(uuid())),
- ("command_name", required(free_string(64))),
- ],
-};
-
-/// `agent error` (v2): a provider/runtime failure occurrence or a later
-/// recovery update. The message policy keeps raw provider text out: only
-/// reviewed fixed strings ride `error_message`, everything else reports
-/// the fixed `diagnostic_message`.
-const AGENT_ERROR: EventRule = EventRule {
- name: "agent error",
- since: 2,
- properties: &[
- ("error_id", required(uuid())),
- (
- "error_event_kind",
- required(enum_rule(&["occurrence", "recovery_update"], "occurrence")),
- ),
- (
- "error_subtype",
- required(enum_rule(ERROR_SUBTYPES, "unknown")),
- ),
- (
- "error_category",
- optional(enum_rule(ERROR_CATEGORIES, "other")),
- ),
- ("error_code", optional(enum_rule(ERROR_CODES, "unknown"))),
- ("http_status", optional(http_status())),
- (
- "classification_source",
- optional(enum_rule(CLASSIFICATION_SOURCES, "unknown")),
- ),
- (
- "classifier_revision",
- optional(PropKind::Number {
- max: 10_000,
- integer: true,
- nullable: false,
- }),
- ),
- ("diagnostic_message", optional(free_string(256))),
- (
- "component",
- optional(enum_rule(ERROR_COMPONENTS, "unknown")),
- ),
- (
- "operation",
- optional(enum_rule(ERROR_OPERATIONS, "unknown")),
- ),
- ("stage", optional(enum_rule(ERROR_STAGES, "unknown"))),
- ("retryable", optional(nullable_boolean())),
- ("retry_attempt", optional(count())),
- ("retry_backoff_ms", optional(duration())),
- ("consecutive_failure_count", optional(count())),
- (
- "recovery_action",
- optional(enum_rule(RECOVERY_ACTIONS, "unknown")),
- ),
- (
- "recovery_outcome",
- optional(enum_rule(RECOVERY_OUTCOMES, "unknown")),
- ),
- ("error_message", optional(error_message())),
- ("error_message_id", optional(free_string(64))),
- (
- "error_message_source",
- optional(enum_rule(ERROR_MESSAGE_SOURCES, "system_template")),
- ),
- ("error_message_length", optional(count())),
- ("error_message_length_lower_bound", optional(boolean())),
- ("error_message_truncated", optional(boolean())),
- ("error_message_redacted", optional(boolean())),
- ],
-};
-
-/// `agent timing` (v2): one measurement per stage boundary.
-const AGENT_TIMING: EventRule = EventRule {
- name: "agent timing",
- since: 2,
- properties: &[
- ("stage", required(enum_rule(TIMING_STAGES, "unknown"))),
- ("duration_ms", required(duration())),
- (
- "outcome",
- optional(enum_rule(
- &[
- "success",
- "error",
- "cancelled",
- "shutdown_interrupted",
- "unavailable",
- "unknown",
- ],
- "unknown",
- )),
- ),
- (
- "tool_category",
- optional(enum_rule(TOOL_CATEGORIES, "custom")),
- ),
- (
- "timing_origin",
- optional(enum_rule(TIMING_ORIGINS, "unknown")),
- ),
- ],
-};
-
-/// `agent tool summary` (v2): per-run, per-tool-category aggregates.
-const AGENT_TOOL_SUMMARY: EventRule = EventRule {
- name: "agent tool summary",
- since: 2,
- properties: &[
- ("session_id", required(uuid())),
- ("run_id", required(uuid())),
- (
- "tool_category",
- required(enum_rule(TOOL_CATEGORIES, "custom")),
- ),
- ("call_count", required(count())),
- ("failure_count", required(count())),
- ("duration_ms", optional(duration())),
- ("recovered_count", optional(count())),
- ],
+ properties: &[("command_name", required(free_string(64)))],
};
/// `onboarding stage` (v2): the onboarding journey's real stages only.
@@ -1113,25 +855,6 @@ const ONBOARDING_COMPLETED: EventRule = EventRule {
],
};
-/// `agent feature outcome` (v2): user-facing feature attempts and results.
-const AGENT_FEATURE_OUTCOME: EventRule = EventRule {
- name: "agent feature outcome",
- since: 2,
- properties: &[
- ("feature_id", required(uuid())),
- (
- "feature_name",
- required(enum_rule(FEATURE_NAMES, "unknown")),
- ),
- ("outcome", required(enum_rule(FEATURE_OUTCOMES, "unknown"))),
- ("duration_ms", optional(duration())),
- (
- "configuration_choice",
- optional(enum_rule(CONFIGURATION_CHOICES, "unknown")),
- ),
- ],
-};
-
/// `agent startup stage` (v2): startup-phase timing per stage.
const AGENT_STARTUP_STAGE: EventRule = EventRule {
name: "agent startup stage",
@@ -1151,22 +874,6 @@ const AGENT_STARTUP_STAGE: EventRule = EventRule {
],
};
-/// `agent input stage` (v2): one input's lifecycle observations.
-const AGENT_INPUT_STAGE: EventRule = EventRule {
- name: "agent input stage",
- since: 2,
- properties: &[
- ("input_id", required(uuid())),
- ("stage", required(enum_rule(INPUT_STAGES, "unknown"))),
- ("outcome", required(enum_rule(INPUT_OUTCOMES, "unknown"))),
- ("duration_ms", optional(duration())),
- (
- "timing_origin",
- optional(enum_rule(TIMING_ORIGINS, "unknown")),
- ),
- ],
-};
-
/// `agent installation stage` (v2): installer/updater stage outcomes.
const AGENT_INSTALLATION_STAGE: EventRule = EventRule {
name: "agent installation stage",
@@ -1212,24 +919,6 @@ const AGENT_INSTALLATION_STAGE: EventRule = EventRule {
],
};
-/// `skill used` (v1): skill invocation, never skill content.
-const SKILL_USED: EventRule = EventRule {
- name: "skill used",
- since: 1,
- properties: &[
- ("session_id", required(uuid())),
- ("skill_name", required(free_string(128))),
- (
- "skill_kind",
- required(enum_rule(&["markdown", "python"], "markdown")),
- ),
- (
- "source",
- required(enum_rule(&["prompt", "steer", "follow_up"], "prompt")),
- ),
- ],
-};
-
/// `startup` (v1): process entry to ready interactive session environment.
const STARTUP: EventRule = EventRule {
name: "startup",
@@ -1259,6 +948,21 @@ const DAEMON_EVENT: EventRule = EventRule {
("skipped_idle", optional(count())),
("stopped", optional(count())),
("failed", optional(count())),
+ // The `summary` kind: the frequent supervision events, counted
+ // over a window of at most an hour.
+ ("window_ms", optional(duration())),
+ ("worker_exited_normal_count", optional(count())),
+ ("worker_exited_crash_count", optional(count())),
+ ("worker_restarted_count", optional(count())),
+ ("worker_overloaded_count", optional(count())),
+ ("attach_count", optional(count())),
+ ("reattach_count", optional(count())),
+ ("detach_count", optional(count())),
+ ("registration_refused_count", optional(count())),
+ ("session_rebound_count", optional(count())),
+ ("root_identity_persist_failed_count", optional(count())),
+ ("saved_sessions_list_count", optional(count())),
+ ("saved_sessions_usage_rows_max", optional(count())),
],
};
@@ -1291,281 +995,144 @@ const MODEL_REFUSED: EventRule = EventRule {
],
};
-/// `mcp connector used` (v1): server name only.
-const MCP_CONNECTOR_USED: EventRule = EventRule {
- name: "mcp connector used",
- since: 1,
- properties: &[
- (
- "action",
- required(enum_rule(&["config", "refresh", "paste-install"], "config")),
- ),
- ("server_name", optional(free_string(128))),
- ],
-};
-
-/// `rlm child usage attributed` (v1): a durable usage attribution row.
-const RLM_CHILD_USAGE: EventRule = EventRule {
- name: "rlm child usage attributed",
+/// `session archived` (v1): the daemon `kill` path.
+const SESSION_ARCHIVED: EventRule = EventRule {
+ name: "session archived",
since: 1,
properties: &[
("session_id", required(uuid())),
- (
- "origin",
- required(enum_rule(
- &["spawn_task", "agent_message", "direct_user"],
- "direct_user",
- )),
- ),
- ("input_tokens", optional(tokens())),
- ("output_tokens", optional(tokens())),
- ("cache_read_tokens", optional(tokens())),
- ("cache_write_tokens", optional(tokens())),
- ("cost", optional(cost())),
+ ("duration_ms", required(duration())),
],
};
-/// `tool executed` (v1): per tool execution, name + duration + outcome.
-const TOOL_EXECUTED: EventRule = EventRule {
- name: "tool executed",
- since: 1,
+/// A settled ipython cell that rendered as bash (v2): its executed
+/// `bash()` line share and command count, never command text. One of the
+/// two standalone TUI events (with `agent command used`), tracked per
+/// render by the upstream #3307 addition and kept intact.
+const TUI_IPYTHON_BASH_RENDERED: EventRule = EventRule {
+ name: "tui ipython bash rendered",
+ since: 2,
properties: &[
- ("session_id", required(uuid())),
- ("tool_name", required(free_string(128))),
- ("duration_ms", required(duration())),
- ("is_error", required(boolean())),
+ ("bash_lines", required(count())),
+ ("cell_lines", required(count())),
+ ("count", required(count())),
],
};
-/// `kernel bootstrap` (v1): one per actual kernel boot.
-const KERNEL_BOOTSTRAP: EventRule = EventRule {
- name: "kernel bootstrap",
+/// `tui exit` (v1, enriched): one per interactive session run (each agents
+/// view handoff ends one), carrying that run's adoption counters (the TUI
+/// interactions, the client-side feature outcomes, the input-stage counts
+/// and maxima) instead of one event per interaction.
+const TUI_EXIT: EventRule = EventRule {
+ name: "tui exit",
since: 1,
properties: &[
- ("duration_ms", required(duration())),
- ("cold", required(boolean())),
(
- "outcome",
- required(enum_rule(&["success", "error"], "error")),
+ "exit_reason",
+ required(enum_rule(
+ &["ctrl_c_twice", "ctrl_d", "session_request", "daemon_closed"],
+ "daemon_closed",
+ )),
),
+ ("turn_active", required(boolean())),
+ ("tui_scroll_count", optional(count())),
+ ("tui_selection_count", optional(count())),
+ ("tui_click_count", optional(count())),
+ ("tui_menu_open_count", optional(count())),
+ ("tui_activity_open_count", optional(count())),
+ ("tui_subagents_open_count", optional(count())),
+ ("tui_scoped_agent_count", optional(count())),
+ ("tui_image_paste_count", optional(count())),
+ ("tui_input_queued_count", optional(count())),
+ ("tui_queue_edit_count", optional(count())),
+ ("tui_prompt_stash_count", optional(count())),
+ ("tui_bash_shortcut_count", optional(count())),
+ ("tui_bash_bang_count", optional(count())),
+ ("tui_external_editor_count", optional(count())),
+ ("tui_scoped_models_count", optional(count())),
+ ("tui_suspend_count", optional(count())),
+ ("tui_agents_action_count", optional(count())),
+ ("tui_enhanced_keys_kitty", optional(boolean())),
+ ("tui_enhanced_keys_modify_other_keys", optional(boolean())),
+ ("tui_hyperlinks_enabled", optional(boolean())),
+ ("feature_model_initiated_count", optional(count())),
+ ("feature_model_completed_count", optional(count())),
+ ("feature_model_failed_count", optional(count())),
+ ("feature_model_canceled_count", optional(count())),
+ ("feature_model_unavailable_count", optional(count())),
+ ("feature_login_initiated_count", optional(count())),
+ ("feature_login_completed_count", optional(count())),
+ ("feature_login_failed_count", optional(count())),
+ ("feature_login_canceled_count", optional(count())),
+ ("feature_login_unavailable_count", optional(count())),
+ ("feature_logout_initiated_count", optional(count())),
+ ("feature_logout_completed_count", optional(count())),
+ ("feature_logout_failed_count", optional(count())),
+ ("feature_logout_canceled_count", optional(count())),
+ ("feature_logout_unavailable_count", optional(count())),
+ ("feature_effort_initiated_count", optional(count())),
+ ("feature_effort_completed_count", optional(count())),
+ ("feature_effort_failed_count", optional(count())),
+ ("feature_effort_canceled_count", optional(count())),
+ ("feature_effort_unavailable_count", optional(count())),
+ ("feature_goal_initiated_count", optional(count())),
+ ("feature_goal_completed_count", optional(count())),
+ ("feature_goal_failed_count", optional(count())),
+ ("feature_goal_canceled_count", optional(count())),
+ ("feature_goal_unavailable_count", optional(count())),
+ ("feature_new_initiated_count", optional(count())),
+ ("feature_new_completed_count", optional(count())),
+ ("feature_new_failed_count", optional(count())),
+ ("feature_new_canceled_count", optional(count())),
+ ("feature_new_unavailable_count", optional(count())),
+ ("feature_resume_initiated_count", optional(count())),
+ ("feature_resume_completed_count", optional(count())),
+ ("feature_resume_failed_count", optional(count())),
+ ("feature_resume_canceled_count", optional(count())),
+ ("feature_resume_unavailable_count", optional(count())),
+ ("feature_fork_initiated_count", optional(count())),
+ ("feature_fork_completed_count", optional(count())),
+ ("feature_fork_failed_count", optional(count())),
+ ("feature_fork_canceled_count", optional(count())),
+ ("feature_fork_unavailable_count", optional(count())),
+ ("feature_clone_initiated_count", optional(count())),
+ ("feature_clone_completed_count", optional(count())),
+ ("feature_clone_failed_count", optional(count())),
+ ("feature_clone_canceled_count", optional(count())),
+ ("feature_clone_unavailable_count", optional(count())),
+ ("feature_tree_initiated_count", optional(count())),
+ ("feature_tree_completed_count", optional(count())),
+ ("feature_tree_failed_count", optional(count())),
+ ("feature_tree_canceled_count", optional(count())),
+ ("feature_tree_unavailable_count", optional(count())),
+ ("feature_feedback_initiated_count", optional(count())),
+ ("feature_feedback_completed_count", optional(count())),
+ ("feature_feedback_failed_count", optional(count())),
+ ("feature_feedback_canceled_count", optional(count())),
+ ("feature_feedback_unavailable_count", optional(count())),
+ ("input_received_count", optional(count())),
+ ("input_queued_count", optional(count())),
+ ("input_preparation_count", optional(count())),
+ ("input_dispatch_count", optional(count())),
+ ("input_admitted_count", optional(count())),
+ ("input_terminal_count", optional(count())),
+ ("input_submitted_count", optional(count())),
+ ("input_rejected_count", optional(count())),
+ ("input_first_visible_status_count", optional(count())),
+ ("input_cancellation_to_idle_count", optional(count())),
+ ("input_received_max_ms", optional(duration())),
+ ("input_queued_max_ms", optional(duration())),
+ ("input_preparation_max_ms", optional(duration())),
+ ("input_dispatch_max_ms", optional(duration())),
+ ("input_admitted_max_ms", optional(duration())),
+ ("input_terminal_max_ms", optional(duration())),
+ ("input_submitted_max_ms", optional(duration())),
+ ("input_rejected_max_ms", optional(duration())),
+ ("input_first_visible_status_max_ms", optional(duration())),
+ ("input_cancellation_to_idle_max_ms", optional(duration())),
],
};
-/// `session archived` (v1): the daemon `kill` path.
-const SESSION_ARCHIVED: EventRule = EventRule {
- name: "session archived",
- since: 1,
- properties: &[
- ("session_id", required(uuid())),
- ("duration_ms", required(duration())),
- ],
-};
-
-/// The `tui *` adoption events (v1).
-const TUI_EVENTS: &[EventRule] = &[
- EventRule {
- name: "tui scroll used",
- since: 1,
- properties: &[
- (
- "action",
- required(enum_rule(
- &["page_up", "page_down", "top", "follow"],
- "page_up",
- )),
- ),
- ("resumed_following", required(boolean())),
- ],
- },
- EventRule {
- name: "tui selection used",
- since: 1,
- properties: &[("lines", required(count()))],
- },
- EventRule {
- name: "tui click used",
- since: 1,
- properties: &[(
- "surface",
- required(enum_rule(&["transcript", "editor", "picker"], "picker")),
- )],
- },
- EventRule {
- name: "tui enhanced keys",
- since: 1,
- properties: &[
- ("kitty", required(boolean())),
- ("modify_other_keys", required(boolean())),
- ],
- },
- EventRule {
- name: "tui hyperlinks",
- since: 1,
- properties: &[("enabled", required(boolean()))],
- },
- EventRule {
- name: "tui image pasted",
- since: 1,
- properties: &[(
- "mime_type",
- required(enum_rule(
- &["image/png", "image/jpeg", "image/gif", "image/webp"],
- "image/png",
- )),
- )],
- },
- EventRule {
- name: "tui exit",
- since: 1,
- properties: &[
- (
- "exit_reason",
- required(enum_rule(
- &["ctrl_c_twice", "ctrl_d", "session_request", "daemon_closed"],
- "daemon_closed",
- )),
- ),
- ("turn_active", required(boolean())),
- ],
- },
- EventRule {
- name: "tui input queued",
- since: 1,
- properties: &[
- (
- "lane",
- required(enum_rule(&["steering", "follow_up"], "steering")),
- ),
- (
- "steering_mode",
- required(enum_rule(&["all", "one-at-a-time"], "all")),
- ),
- ],
- },
- EventRule {
- name: "tui queue edited",
- since: 1,
- properties: &[(
- "action",
- required(enum_rule(
- &["select", "edit", "delete", "reorder"],
- "select",
- )),
- )],
- },
- EventRule {
- name: "tui suspend used",
- since: 1,
- properties: &[(
- "outcome",
- required(enum_rule(&["resumed", "failed"], "failed")),
- )],
- },
- EventRule {
- name: "tui subagents open",
- since: 1,
- properties: &[("children_total", required(count()))],
- },
- // The scoped agents view's new action (the operator's 2026-09-28
- // divergence): the created session's RLM depth, the scope root's
- // depth + 1.
- EventRule {
- name: "tui agents new scoped",
- since: 2,
- properties: &[("depth", required(count()))],
- },
- EventRule {
- name: "tui activity opened",
- since: 1,
- properties: &[(
- "kind",
- required(enum_rule(&["subagents", "heartbeats", "bash"], "subagents")),
- )],
- },
- EventRule {
- name: "tui menu opened",
- since: 1,
- properties: &[
- (
- "menu",
- required(enum_rule(
- &[
- "model",
- "mcp",
- "settings",
- "context",
- "session",
- "system-prompt",
- "logs",
- "changelog",
- "hotkeys",
- "traces",
- "list",
- ],
- "list",
- )),
- ),
- (
- "source",
- required(enum_rule(&["command", "tab"], "command")),
- ),
- ],
- },
- EventRule {
- name: "tui prompt stash",
- since: 1,
- properties: &[
- (
- "action",
- required(enum_rule(
- &["agents_view", "session_switch", "restored"],
- "session_switch",
- )),
- ),
- ("had_images", required(boolean())),
- ],
- },
- EventRule {
- name: "tui bash shortcut used",
- since: 1,
- properties: &[
- ("excluded", required(boolean())),
- ("side_conversation", required(boolean())),
- ],
- },
- EventRule {
- name: "tui bash bang executed",
- since: 1,
- properties: &[
- (
- "duration_bucket",
- required(enum_rule(
- &["lt_5s", "5_to_30s", "30s_plus", "unknown"],
- "unknown",
- )),
- ),
- (
- "exit_class",
- required(enum_rule(
- &["zero", "nonzero", "cancelled", "failed", "unknown"],
- "unknown",
- )),
- ),
- ],
- },
- // A settled ipython cell that rendered as bash: its executed bash()
- // line share and command count, never command text.
- EventRule {
- name: "tui ipython bash rendered",
- since: 2,
- properties: &[
- ("bash_lines", required(count())),
- ("cell_lines", required(count())),
- ("count", required(count())),
- ],
- },
-];
-
/// The update-flow events (v1): `update completed` plus the per-phase
/// events (one per status transition, the same names the `phase` property
/// carries).
@@ -1685,40 +1252,46 @@ const UPDATE_EVENTS: &[EventRule] = &[
},
];
-/// Every catalogued event, flattened. `AGENT_ERROR` et al. are the #2117 v2
-/// events; the v1 adoption events follow.
+/// Every catalogued event, flattened.
#[must_use]
pub fn catalog() -> Vec<&'static EventRule> {
let mut all: Vec<&'static EventRule> = vec![
&AGENT_STARTED,
- &AGENT_RUN_STARTED,
&AGENT_RUN_COMPLETED,
&AGENT_SESSION_ENDED,
&AGENT_COMMAND_USED,
- &AGENT_ERROR,
- &AGENT_TIMING,
- &AGENT_TOOL_SUMMARY,
&ONBOARDING_STAGE,
&ONBOARDING_COMPLETED,
- &AGENT_FEATURE_OUTCOME,
&AGENT_STARTUP_STAGE,
- &AGENT_INPUT_STAGE,
&AGENT_INSTALLATION_STAGE,
- &SKILL_USED,
&STARTUP,
&DAEMON_EVENT,
&MODEL_REFUSED,
- &MCP_CONNECTOR_USED,
- &RLM_CHILD_USAGE,
- &TOOL_EXECUTED,
- &KERNEL_BOOTSTRAP,
&SESSION_ARCHIVED,
+ &TUI_EXIT,
+ &TUI_IPYTHON_BASH_RENDERED,
];
- all.extend(TUI_EVENTS.iter());
all.extend(UPDATE_EVENTS.iter());
all
}
+/// The `feature_<name>_<outcome>_count` counter key for a feature outcome
+/// in the fixed vocabulary (`None` outside it).
+#[must_use]
+pub fn feature_outcome_key(feature_name: &str, outcome: &str) -> Option<String> {
+ (FEATURE_NAMES.contains(&feature_name) && FEATURE_OUTCOMES.contains(&outcome))
+ .then(|| format!("feature_{feature_name}_{outcome}_count"))
+}
+
+/// The `input_<stage>_*` key prefix for an input stage in the fixed
+/// vocabulary (`None` outside it).
+#[must_use]
+pub fn input_stage_key(stage: &str) -> Option<String> {
+ INPUT_STAGES
+ .contains(&stage)
+ .then(|| format!("input_{stage}"))
+}
+
/// Look up one event's rule.
#[must_use]
pub fn lookup(name: &str) -> Option<&'static EventRule> {
@@ -1818,128 +1391,117 @@ mod tests {
use serde_json::json;
#[test]
- fn schema_version_bumped_for_the_2117_vocabulary() {
- // The #2117 event vocabulary landed at schema version 2; the v1
- // adoption events stay catalogued at their entry version.
+ fn the_catalog_is_the_low_frequency_set() {
assert_eq!(SCHEMA_VERSION, 2);
- let catalog = catalog();
- for name in [
- "agent run started",
- "agent error",
- "agent timing",
- "agent tool summary",
- "onboarding stage",
- "agent feature outcome",
- "agent startup stage",
- "agent input stage",
- "agent installation stage",
- ] {
- let rule = catalog
- .iter()
- .find(|rule| rule.name == name)
- .unwrap_or_else(|| panic!("{name} must be catalogued"));
- assert_eq!(rule.since, 2, "{name} entered the catalog at v2");
- }
+ let names: Vec<&str> = catalog().iter().map(|rule| rule.name).collect();
for name in [
"agent started",
"agent run completed",
"agent session ended",
"agent command used",
"onboarding completed",
- "tool executed",
- "skill used",
+ "onboarding stage",
+ "agent startup stage",
+ "agent installation stage",
"session archived",
"startup",
"daemon event",
+ "model refused",
"update completed",
"tui exit",
] {
- assert!(
- catalog.iter().any(|rule| rule.name == name),
- "{name} stays catalogued"
- );
+ assert!(names.contains(&name), "{name} stays catalogued");
+ }
+ // The per-occurrence events folded into run/session/client counters.
+ for name in [
+ "agent run started",
+ "agent error",
+ "agent timing",
+ "agent tool summary",
+ "agent feature outcome",
+ "agent input stage",
+ "tool executed",
+ "skill used",
+ "mcp connector used",
+ "rlm child usage attributed",
+ "kernel bootstrap",
+ "tui scroll used",
+ ] {
+ assert!(!names.contains(&name), "{name} is folded, not an event");
}
}
+ /// Every property key matches the platform backend's key pattern
+ /// (`^[a-zA-Z][a-zA-Z0-9_]*$`, at most 64 chars; a bad key drops the
+ /// whole event there) and every event stays under its 128-key cap.
#[test]
- fn every_v2_event_carries_its_required_properties() {
- let run_started = lookup("agent run started").expect("catalogued");
- for key in ["session_id", "run_id", "run_index", "trigger"] {
+ fn every_key_passes_the_backend_pattern() {
+ for rule in catalog() {
assert!(
- run_started
- .properties
- .iter()
- .any(|(name, rule)| name == &key && rule.required),
- "agent run started requires {key}"
+ rule.properties.len() + BASE_PROPERTIES.len() <= 128,
+ "{} exceeds the backend's 128 keys",
+ rule.name
);
- }
- let tool_summary = lookup("agent tool summary").expect("catalogued");
- for key in [
- "session_id",
- "run_id",
- "tool_category",
- "call_count",
- "failure_count",
- ] {
- assert!(
- tool_summary
- .properties
- .iter()
- .any(|(name, rule)| name == &key && rule.required),
- "agent tool summary requires {key}"
- );
- }
- let installation = lookup("agent installation stage").expect("catalogued");
- for key in [
- "installation_attempt_id",
- "installation_action",
- "installation_source",
- "stage",
- "outcome",
- ] {
+ for (key, _) in rule.properties.iter().chain(BASE_PROPERTIES.iter()) {
+ let mut chars = key.chars();
+ assert!(
+ key.len() <= 64
+ && chars.next().is_some_and(|c| c.is_ascii_alphabetic())
+ && chars.all(|c| c.is_ascii_alphanumeric() || c == '_'),
+ "{}: {key}",
+ rule.name
+ );
+ }
assert!(
- installation
- .properties
- .iter()
- .any(|(name, rule)| name == &key && rule.required),
- "agent installation stage requires {key}"
+ rule.name
+ .chars()
+ .all(|c| c.is_ascii_lowercase() || c == ' ' || c == '_'),
+ "{}",
+ rule.name
);
}
}
#[test]
- fn the_scoped_new_event_catalogues_only_its_depth() {
- // The scoped ctrl+n's adoption event: the depth count stays, and
- // no other key rides it (the parent's session path is not a
- // catalogued property, so sanitize drops it).
- let rule = lookup("tui agents new scoped").expect("catalogued");
- assert_eq!(rule.since, 2);
- let mut properties = Properties::new();
- properties.set("depth", json!(2u64));
- properties.set("parent_session_path", json!("/sessions/p.jsonl"));
- let adjusted = sanitize("tui agents new scoped", &mut properties);
- assert_eq!(properties.get("depth"), Some(&json!(2u64)));
- assert!(
- properties.get("parent_session_path").is_none(),
- "the parent's path never rides the event"
+ fn counter_keys_cover_the_fixed_vocabularies() {
+ assert_eq!(
+ feature_outcome_key("goal", "completed").as_deref(),
+ Some("feature_goal_completed_count")
);
- assert_eq!(adjusted, 1, "the path key dropped");
+ assert_eq!(feature_outcome_key("goal", "exploded"), None);
+ assert_eq!(input_stage_key("queued").as_deref(), Some("input_queued"));
+ assert_eq!(input_stage_key("nope"), None);
+ let ended = lookup("agent session ended").unwrap();
+ let exit = lookup("tui exit").unwrap();
+ for name in FEATURE_NAMES {
+ for outcome in FEATURE_OUTCOMES {
+ let key = feature_outcome_key(name, outcome).unwrap();
+ assert!(ended.properties.iter().any(|(known, _)| *known == key));
+ assert!(exit.properties.iter().any(|(known, _)| *known == key));
+ }
+ }
+ for stage in INPUT_STAGES {
+ let prefix = input_stage_key(stage).unwrap();
+ for suffix in ["count", "max_ms"] {
+ let key = format!("{prefix}_{suffix}");
+ assert!(exit.properties.iter().any(|(known, _)| *known == key));
+ }
+ }
}
#[test]
fn sanitize_drops_unknown_keys_and_falls_back_enums() {
let mut properties = Properties::new();
properties.set("session_id", json!("0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1a"));
+ properties.set("outcome", json!("success"));
+ properties.set("duration_ms", json!(5));
properties.set("trigger", json!("spontaneous")); // out of vocabulary
- properties.set("run_index", json!(7u64));
- properties.set("prompt_text", json!("private prompt")); // not a catalogued property
- let adjusted = sanitize("agent run started", &mut properties);
+ properties.set("tool_bash_call_count", json!(3u64));
+ properties.set("tool_name", json!("private_tool")); // not a catalogued property
+ let adjusted = sanitize("agent run completed", &mut properties);
assert_eq!(properties.get("trigger"), Some(&json!("unknown")));
- assert_eq!(properties.get("run_index"), Some(&json!(7u64)));
- assert!(
- properties.get("prompt_text").is_none(),
- "unknown key dropped"
- );
+ assert_eq!(properties.get("tool_bash_call_count"), Some(&json!(3u64)));
+ assert!(properties.get("tool_name").is_none(), "unknown key dropped");
assert_eq!(adjusted, 2, "one fallback + one dropped key");
}
@@ -1947,18 +1509,13 @@ mod tests {
fn sanitize_clamps_numbers_and_caps_strings() {
let mut properties = Properties::new();
properties.set("session_id", json!("0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1a"));
- properties.set("run_id", json!("0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1b"));
- properties.set("run_index", json!(u64::MAX)); // over the count cap
- properties.set("trigger", json!("prompt"));
- let _ = sanitize("agent run started", &mut properties);
- assert_eq!(properties.get("run_index"), Some(&json!(1_000_000u64)));
- let mut summary = Properties::new();
- summary.set("session_id", json!("0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1a"));
- summary.set("run_id", json!("0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1b"));
- summary.set("tool_category", json!("custom"));
- summary.set("call_count", json!(3.5)); // fractional where integer
- let _ = sanitize("agent tool summary", &mut summary);
- assert!(summary.get("call_count").is_none(), "fraction dropped");
+ properties.set("outcome", json!("success"));
+ properties.set("duration_ms", json!(5));
+ properties.set("turn_count", json!(u64::MAX)); // over the count cap
+ properties.set("retry_count", json!(3.5)); // fractional where integer
+ let _ = sanitize("agent run completed", &mut properties);
+ assert_eq!(properties.get("turn_count"), Some(&json!(1_000_000u64)));
+ assert!(properties.get("retry_count").is_none(), "fraction dropped");
}
#[test]
diff --git a/crates/pa-telemetry/src/client.rs b/crates/pa-telemetry/src/client.rs
index e936760a7a..14d9511ac0 100644
--- a/crates/pa-telemetry/src/client.rs
+++ b/crates/pa-telemetry/src/client.rs
@@ -80,8 +80,8 @@ struct Channel {
/// Client configuration.
#[derive(Clone)]
pub struct TelemetryClientConfig {
- /// Pseudonymous installation id (sink-side identity, e.g. `PostHog`
- /// `distinct_id`). Load via [`crate::install_id`].
+ /// Pseudonymous installation id (the analytics body's
+ /// `installation_id`). Load via [`crate::install_id`].
pub install_id: String,
/// Base properties merged under every event's own properties
/// (version, os, execution mode...).
@@ -98,6 +98,11 @@ pub struct TelemetryClientConfig {
pub retry: RetryPolicy,
/// Fan-out sinks: every sink receives every event.
pub sinks: Vec<Arc<dyn TelemetrySink>>,
+ /// The live on/off switch, asked for every tracked event and before
+ /// every delivery pass: while it answers false, new and queued events
+ /// are dropped unsent (a mid-session opt-out applies without a
+ /// restart). `None` is always on.
+ pub enabled: Option<Arc<dyn Fn() -> bool + Send + Sync>>,
}
impl TelemetryClientConfig {
@@ -111,6 +116,7 @@ impl TelemetryClientConfig {
max_batch_bytes: DEFAULT_MAX_BATCH_BYTES,
retry: RetryPolicy::default(),
sinks: Vec::new(),
+ enabled: None,
}
}
}
@@ -288,6 +294,13 @@ impl Worker {
};
match cmd {
Cmd::Track(event) => {
+ // An event recorded while the switch is off is
+ // dropped now, so turning telemetry back on
+ // never sends what happened while it was off.
+ if self.drop_while_disabled() {
+ self.queue_dropped.fetch_add(1, Ordering::Relaxed);
+ continue;
+ }
self.enqueue(&event);
if self.channels.iter().any(|channel| {
channel.queue.len() >= self.config.batch_size
@@ -341,6 +354,21 @@ impl Worker {
now + delay
}
+ /// Ask the live switch; when it is off, drop every queued event
+ /// (counted) and report true so the pass sends nothing.
+ fn drop_while_disabled(&mut self) -> bool {
+ if self.config.enabled.as_ref().is_none_or(|enabled| enabled()) {
+ return false;
+ }
+ for channel in &mut self.channels {
+ self.queue_dropped
+ .fetch_add(channel.queue.len() as u64, Ordering::Relaxed);
+ channel.queue.clear();
+ channel.next_retry_at = None;
+ }
+ true
+ }
+
fn enqueue(&mut self, event: &TelemetryEvent) {
for channel in &mut self.channels {
if channel.queue.len() >= self.config.queue_capacity {
@@ -356,6 +384,9 @@ impl Worker {
/// One delivery pass over every channel: expire, batch, send, retry.
async fn flush_pass(&mut self) {
+ if self.drop_while_disabled() {
+ return;
+ }
let now = std::time::SystemTime::now();
let now_epoch_ms = now
.duration_since(std::time::UNIX_EPOCH)
@@ -432,6 +463,9 @@ impl Worker {
/// (bounded shutdown; a hard exit may lose reports, like the TS
/// contract).
async fn flush_final(&mut self) {
+ if self.drop_while_disabled() {
+ return;
+ }
for channel in &mut self.channels {
while !channel.queue.is_empty() {
// The final drain honors the same batch byte cap as the
@@ -781,11 +815,13 @@ mod tests {
next_retry_at: None,
};
let fresh = TelemetryEvent {
+ id: "fresh-id".into(),
name: "fresh".into(),
timestamp_ms: now_epoch_ms_for_tests(),
properties: Properties::new(),
};
let stale = TelemetryEvent {
+ id: "stale-id".into(),
name: "stale".into(),
timestamp_ms: now_epoch_ms_for_tests().saturating_sub(MAX_AGE.as_millis() as u64 + 1),
properties: Properties::new(),
@@ -843,7 +879,7 @@ mod tests {
);
properties.set("trigger", serde_json::Value::from("spontaneous"));
properties.set("secret_path", serde_json::Value::from("/home/user/project"));
- client.track("agent run started", properties);
+ client.track("agent run completed", properties);
client.flush().await.unwrap();
let events = mock.events();
assert_eq!(events.len(), 1);
diff --git a/crates/pa-telemetry/src/env.rs b/crates/pa-telemetry/src/env.rs
index 536d05f4b5..20aaa1edd8 100644
--- a/crates/pa-telemetry/src/env.rs
+++ b/crates/pa-telemetry/src/env.rs
@@ -1,12 +1,6 @@
-//! Environment-variable override resolution for the opt-in posture.
-//!
-//! Parity with the TS product's `isTelemetryEnabled` env handling:
-//! - `PI_OFFLINE` truthy disables (falsy is ignored).
-//! - `DO_NOT_TRACK` truthy disables (falsy is ignored).
-//! - `PRIME_AGENT_TELEMETRY` truthy/falsy overrides in both directions.
-//!
-//! [`env_telemetry_override`] returns the env verdict; settings (owned by
-//! pa-core) apply when the verdict is absent.
+//! Environment-variable parsing for the opt-out switch (TS
+//! `parseBooleanOverride`); the precedence lives with the switch in pa-core
+//! (`session_engine::telemetry::telemetry_switch`).
/// Parse a truthy/falsy string per the TS product: `1/true/yes/on` and
/// `0/false/no/off` (case-insensitive, trimmed); anything else is not an
@@ -21,30 +15,6 @@ pub fn parse_bool_override(value: Option<&str>) -> Option<bool> {
}
}
-/// Env verdict for telemetry. `Some(false)` disables, `Some(true)` enables,
-/// `None` defers to settings.
-#[must_use]
-pub fn env_telemetry_override() -> Option<bool> {
- override_verdict(
- parse_bool_override(std::env::var("PI_OFFLINE").ok().as_deref()),
- parse_bool_override(std::env::var("DO_NOT_TRACK").ok().as_deref()),
- parse_bool_override(std::env::var("PRIME_AGENT_TELEMETRY").ok().as_deref()),
- )
-}
-
-/// Truth table: offline and do-not-track only disable; the explicit variable
-/// applies only when neither of those disables first.
-fn override_verdict(
- offline: Option<bool>,
- dnt: Option<bool>,
- explicit: Option<bool>,
-) -> Option<bool> {
- if offline == Some(true) || dnt == Some(true) {
- return Some(false);
- }
- explicit
-}
-
#[cfg(test)]
mod tests {
use super::*;
@@ -60,19 +30,4 @@ mod tests {
assert_eq!(parse_bool_override(Some("maybe")), None);
assert_eq!(parse_bool_override(None), None);
}
-
- #[test]
- fn verdict_disables_only() {
- assert_eq!(override_verdict(Some(true), None, Some(true)), Some(false));
- assert_eq!(override_verdict(None, Some(true), Some(true)), Some(false));
- // Falsy PI_OFFLINE / DO_NOT_TRACK do not enable.
- assert_eq!(override_verdict(Some(false), Some(false), None), None);
- }
-
- #[test]
- fn explicit_variable_applies() {
- assert_eq!(override_verdict(None, None, Some(true)), Some(true));
- assert_eq!(override_verdict(None, None, Some(false)), Some(false));
- assert_eq!(override_verdict(None, None, None), None);
- }
}
diff --git a/crates/pa-telemetry/src/event.rs b/crates/pa-telemetry/src/event.rs
index a4849d4f3b..9ff95c805d 100644
--- a/crates/pa-telemetry/src/event.rs
+++ b/crates/pa-telemetry/src/event.rs
@@ -7,9 +7,13 @@ use crate::properties::Properties;
use crate::time::EpochMs;
/// A single telemetry event. Carries a stable event name and a
-/// primitive-only property map. Timestamps are captured at `track()` time.
+/// primitive-only property map. The id and timestamp are captured at
+/// `track()` time, so a retried batch re-sends the same ids (the analytics
+/// endpoint forwards the id as the `PostHog` event uuid, which dedupes).
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct TelemetryEvent {
+ /// Random uuid v4 per event.
+ pub id: String,
/// Stable event name, e.g. `agent started`.
pub name: String,
/// Milliseconds since the Unix epoch at emission time.
@@ -22,6 +26,7 @@ impl TelemetryEvent {
/// New event stamped with the current time.
pub fn new(name: impl Into<String>, properties: Properties) -> Self {
Self {
+ id: uuid::Uuid::new_v4().to_string(),
name: name.into(),
timestamp_ms: EpochMs::now().0,
properties,
@@ -40,11 +45,12 @@ impl TelemetryEvent {
serde_json::to_string(&self.to_value()).map_or(0, |text| text.len())
}
- /// The sink-facing object form: `{"name", "timestamp" (ISO-8601),
- /// "properties"}`. Sinks lift fields from this shape into their wire
- /// format (`PostHog` `event`/`timestamp`, JSONL mirror adds `distinct_id`).
+ /// The sink-facing object form: `{"id", "name", "timestamp" (ISO-8601),
+ /// "properties"}` - the analytics endpoint's event shape; the JSONL
+ /// mirror adds `distinct_id`.
pub(crate) fn to_value(&self) -> Value {
json!({
+ "id": self.id,
"name": self.name,
"timestamp": self.timestamp_iso8601(),
"properties": Value::Object(self.properties.to_map().clone()),
diff --git a/crates/pa-telemetry/src/events.rs b/crates/pa-telemetry/src/events.rs
index 729745de32..a7cc5ec3e2 100644
--- a/crates/pa-telemetry/src/events.rs
+++ b/crates/pa-telemetry/src/events.rs
@@ -1,5 +1,5 @@
-//! Typed builders for the catalog's v2 events: the compile-time surface of
-//! the #2117 tracking vocabulary. Every field is typed (numbers are `u64`,
+//! Typed builders for the catalog's lifecycle events (onboarding, startup,
+//! installation stages) and the run vocabulary enums. Every field is typed (numbers are `u64`,
//! enums are Rust enums, nullable durations are `Option<u64>`), so a firing
//! site cannot emit a stringly-typed or out-of-vocabulary value. Optional
//! fields are `Option` and simply omit the property when `None`.
@@ -72,7 +72,9 @@ impl ToolCategory {
}
}
- fn as_str(self) -> &'static str {
+ /// The category's wire name.
+ #[must_use]
+ pub fn as_str(self) -> &'static str {
match self {
Self::Read => "read",
Self::Write => "write",
@@ -89,243 +91,6 @@ impl ToolCategory {
}
}
-/// The #2117 timing stage: which boundary a timing event measures.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum TimingStage {
- FirstModelEvent,
- FirstReasoning,
- FirstText,
- Tool,
- RetryWait,
- Compaction,
- StreamGap,
- TimeToError,
-}
-
-impl TimingStage {
- fn as_str(self) -> &'static str {
- match self {
- Self::FirstModelEvent => "first_model_event",
- Self::FirstReasoning => "first_reasoning",
- Self::FirstText => "first_text",
- Self::Tool => "tool",
- Self::RetryWait => "retry_wait",
- Self::Compaction => "compaction",
- Self::StreamGap => "stream_gap",
- Self::TimeToError => "time_to_error",
- }
- }
-}
-
-/// The #2117 error event kind: a failure occurrence or a later recovery
-/// update (recovery never creates a second occurrence).
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum ErrorEventKind {
- Occurrence,
- RecoveryUpdate,
-}
-
-impl ErrorEventKind {
- fn as_str(self) -> &'static str {
- match self {
- Self::Occurrence => "occurrence",
- Self::RecoveryUpdate => "recovery_update",
- }
- }
-}
-
-/// `agent run started`: fires at the run's `AgentStart` boundary, pairing
-/// the run with its id and trigger before any model call.
-#[derive(Debug, Clone)]
-pub struct AgentRunStarted {
- pub session_id: String,
- pub run_id: String,
- pub run_index: u64,
- pub trigger: RunTrigger,
-}
-
-impl AgentRunStarted {
- pub fn track(&self, client: &TelemetryClient) {
- let mut properties = Properties::new();
- properties.set("session_id", Value::String(self.session_id.clone()));
- properties.set("run_id", Value::String(self.run_id.clone()));
- properties.set("run_index", Value::from(self.run_index));
- properties.set("trigger", Value::from(self.trigger.as_str()));
- client.track("agent run started", properties);
- }
-}
-
-/// `agent timing`: one stage boundary measurement.
-#[derive(Debug, Clone)]
-pub struct AgentTiming {
- pub stage: TimingStage,
- pub duration_ms: Option<u64>,
- pub outcome: Option<&'static str>,
- pub tool_category: Option<ToolCategory>,
- pub timing_origin: Option<&'static str>,
-}
-
-impl AgentTiming {
- pub fn track(&self, client: &TelemetryClient) {
- let Some(duration_ms) = self.duration_ms else {
- // A measurement that never observed its end edge is not an
- // event: missing durations stay null-free (no fake zeros).
- return;
- };
- let mut properties = Properties::new();
- properties.set("stage", Value::from(self.stage.as_str()));
- properties.set("duration_ms", Value::from(duration_ms));
- if let Some(outcome) = self.outcome {
- properties.set("outcome", Value::from(outcome));
- }
- if let Some(category) = self.tool_category {
- properties.set("tool_category", Value::from(category.as_str()));
- }
- if let Some(origin) = self.timing_origin {
- properties.set("timing_origin", Value::from(origin));
- }
- client.track("agent timing", properties);
- }
-}
-
-/// `agent tool summary`: per-run, per-category aggregates at run finalize.
-#[derive(Debug, Clone)]
-pub struct AgentToolSummary {
- pub session_id: String,
- pub run_id: String,
- pub tool_category: ToolCategory,
- pub call_count: u64,
- pub failure_count: u64,
- pub duration_ms: Option<u64>,
- pub recovered_count: Option<u64>,
-}
-
-impl AgentToolSummary {
- pub fn track(&self, client: &TelemetryClient) {
- if self.call_count == 0 {
- return;
- }
- let mut properties = Properties::new();
- properties.set("session_id", Value::String(self.session_id.clone()));
- properties.set("run_id", Value::String(self.run_id.clone()));
- properties.set("tool_category", Value::from(self.tool_category.as_str()));
- properties.set("call_count", Value::from(self.call_count));
- properties.set("failure_count", Value::from(self.failure_count));
- if let Some(duration) = self.duration_ms {
- properties.set("duration_ms", Value::from(duration));
- }
- if let Some(recovered) = self.recovered_count {
- properties.set("recovered_count", Value::from(recovered));
- }
- client.track("agent tool summary", properties);
- }
-}
-
-/// `agent error`: an error occurrence or recovery update. The message
-/// policy keeps raw provider text out: `diagnostic_message` carries the
-/// fixed diagnostic, and `error_message` only a reviewed fixed string.
-#[derive(Debug, Clone, Default)]
-pub struct AgentError {
- pub error_id: String,
- pub kind: Option<ErrorEventKind>,
- pub subtype: Option<&'static str>,
- pub category: Option<&'static str>,
- pub code: Option<&'static str>,
- pub http_status: Option<u64>,
- pub classification_source: Option<&'static str>,
- pub diagnostic_message: Option<&'static str>,
- pub component: Option<&'static str>,
- pub operation: Option<&'static str>,
- pub stage: Option<&'static str>,
- pub retryable: Option<bool>,
- pub retry_attempt: Option<u64>,
- pub retry_backoff_ms: Option<u64>,
- pub consecutive_failure_count: Option<u64>,
- pub recovery_action: Option<&'static str>,
- pub recovery_outcome: Option<&'static str>,
- pub error_message: Option<&'static str>,
- pub error_message_source: Option<&'static str>,
- pub error_message_length: Option<u64>,
- pub error_message_length_lower_bound: Option<bool>,
- pub error_message_truncated: Option<bool>,
- pub error_message_redacted: Option<bool>,
-}
-
-impl AgentError {
- pub fn track(&self, client: &TelemetryClient) {
- let Some(kind) = self.kind else { return };
- let mut properties = Properties::new();
- properties.set("error_id", Value::String(self.error_id.clone()));
- properties.set("error_event_kind", Value::from(kind.as_str()));
- if let Some(subtype) = self.subtype {
- properties.set("error_subtype", Value::from(subtype));
- }
- if let Some(category) = self.category {
- properties.set("error_category", Value::from(category));
- }
- if let Some(code) = self.code {
- properties.set("error_code", Value::from(code));
- }
- if let Some(status) = self.http_status {
- properties.set("http_status", Value::from(status));
- }
- if let Some(source) = self.classification_source {
- properties.set("classification_source", Value::from(source));
- properties.set(
- "classifier_revision",
- Value::from(crate::catalog::ERROR_CLASSIFIER_REVISION),
- );
- }
- if let Some(message) = self.diagnostic_message {
- properties.set("diagnostic_message", Value::from(message));
- }
- if let Some(component) = self.component {
- properties.set("component", Value::from(component));
- }
- if let Some(operation) = self.operation {
- properties.set("operation", Value::from(operation));
- }
- if let Some(stage) = self.stage {
- properties.set("stage", Value::from(stage));
- }
- if let Some(retryable) = self.retryable {
- properties.set("retryable", Value::from(retryable));
- }
- if let Some(attempt) = self.retry_attempt {
- properties.set("retry_attempt", Value::from(attempt));
- }
- if let Some(backoff) = self.retry_backoff_ms {
- properties.set("retry_backoff_ms", Value::from(backoff));
- }
- if let Some(count) = self.consecutive_failure_count {
- properties.set("consecutive_failure_count", Value::from(count));
- }
- if let Some(action) = self.recovery_action {
- properties.set("recovery_action", Value::from(action));
- }
- if let Some(outcome) = self.recovery_outcome {
- properties.set("recovery_outcome", Value::from(outcome));
- }
- if let (Some(message), Some(source)) = (self.error_message, self.error_message_source) {
- properties.set("error_message", Value::from(message));
- properties.set("error_message_source", Value::from(source));
- }
- if let Some(length) = self.error_message_length {
- properties.set("error_message_length", Value::from(length));
- }
- if let Some(lower_bound) = self.error_message_length_lower_bound {
- properties.set("error_message_length_lower_bound", Value::from(lower_bound));
- }
- if let Some(truncated) = self.error_message_truncated {
- properties.set("error_message_truncated", Value::from(truncated));
- }
- if let Some(redacted) = self.error_message_redacted {
- properties.set("error_message_redacted", Value::from(redacted));
- }
- client.track("agent error", properties);
- }
-}
-
/// `onboarding stage`: one onboarding journey stage, the flow's real
/// stages only.
#[derive(Debug, Clone)]
@@ -361,32 +126,6 @@ impl OnboardingStage {
}
}
-/// `agent feature outcome`: a feature attempt and its observed result.
-#[derive(Debug, Clone)]
-pub struct AgentFeatureOutcome {
- pub feature_id: String,
- pub feature_name: &'static str,
- pub outcome: &'static str,
- pub duration_ms: Option<u64>,
- pub configuration_choice: Option<&'static str>,
-}
-
-impl AgentFeatureOutcome {
- pub fn track(&self, client: &TelemetryClient) {
- let mut properties = Properties::new();
- properties.set("feature_id", Value::String(self.feature_id.clone()));
- properties.set("feature_name", Value::from(self.feature_name));
- properties.set("outcome", Value::from(self.outcome));
- if let Some(duration) = self.duration_ms {
- properties.set("duration_ms", Value::from(duration));
- }
- if let Some(choice) = self.configuration_choice {
- properties.set("configuration_choice", Value::from(choice));
- }
- client.track("agent feature outcome", properties);
- }
-}
-
/// `agent startup stage`: one startup phase's timing.
#[derive(Debug, Clone)]
pub struct AgentStartupStage {
@@ -416,32 +155,6 @@ impl AgentStartupStage {
}
}
-/// `agent input stage`: one input lifecycle observation.
-#[derive(Debug, Clone)]
-pub struct AgentInputStage {
- pub input_id: String,
- pub stage: &'static str,
- pub outcome: &'static str,
- pub duration_ms: Option<u64>,
- pub timing_origin: Option<&'static str>,
-}
-
-impl AgentInputStage {
- pub fn track(&self, client: &TelemetryClient) {
- let mut properties = Properties::new();
- properties.set("input_id", Value::String(self.input_id.clone()));
- properties.set("stage", Value::from(self.stage));
- properties.set("outcome", Value::from(self.outcome));
- if let Some(duration) = self.duration_ms {
- properties.set("duration_ms", Value::from(duration));
- }
- if let Some(origin) = self.timing_origin {
- properties.set("timing_origin", Value::from(origin));
- }
- client.track("agent input stage", properties);
- }
-}
-
/// `agent installation stage`: one installer/updater stage outcome.
#[derive(Debug, Clone)]
pub struct AgentInstallationStage {
@@ -501,149 +214,8 @@ impl AgentInstallationStage {
#[cfg(test)]
mod tests {
- use std::sync::Arc;
- use std::time::Duration;
-
use super::*;
- use crate::catalog::{
- AUTH_CATEGORIES, CLASSIFICATION_SOURCES, ERROR_CATEGORIES, ERROR_CODES, ERROR_COMPONENTS,
- ERROR_OPERATIONS, ERROR_STAGES, ERROR_SUBTYPES, FEATURE_NAMES, FEATURE_OUTCOMES,
- INPUT_OUTCOMES, INPUT_STAGES, INSTALLATION_ACTIONS, INSTALLATION_OUTCOMES,
- INSTALLATION_REASONS, INSTALLATION_SOURCES, INSTALLATION_STAGES, ONBOARDING_ENTRY_REASONS,
- ONBOARDING_OUTCOMES, ONBOARDING_STAGES, PROVIDER_CATEGORIES, READY_KINDS, RECOVERY_ACTIONS,
- RECOVERY_OUTCOMES, RUN_TRIGGERS, STARTUP_KINDS, STARTUP_OUTCOMES, STARTUP_STAGES,
- TERMINAL_OUTCOMES, TIMING_ORIGINS, TIMING_STAGES, TOOL_CATEGORIES,
- };
- use crate::{MockSink, TelemetryClientConfig};
-
- fn recording_client(mock: &Arc<MockSink>) -> TelemetryClient {
- let mut config = TelemetryClientConfig::new("install-1");
- config.batch_size = 1;
- config.flush_interval = Duration::from_secs(600);
- config.sinks = vec![mock.clone() as Arc<dyn crate::TelemetrySink>];
- TelemetryClient::spawn(config).expect("spawn client")
- }
-
- async fn properties_of(
- mock: &MockSink,
- name: &str,
- ) -> serde_json::Map<String, serde_json::Value> {
- tokio::time::sleep(Duration::from_millis(10)).await;
- mock.events()
- .into_iter()
- .find(|event| event.name == name)
- .expect("event tracked")
- .properties
- .into()
- }
-
- #[tokio::test]
- async fn run_started_carries_typed_properties() {
- let mock = Arc::new(MockSink::new());
- let client = recording_client(&mock);
- AgentRunStarted {
- session_id: "0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1a".into(),
- run_id: "0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1b".into(),
- run_index: 3,
- trigger: RunTrigger::Prompt,
- }
- .track(&client);
- client.flush().await.unwrap();
- let properties = properties_of(&mock, "agent run started").await;
- assert_eq!(properties["run_index"], serde_json::json!(3));
- assert_eq!(properties["trigger"], serde_json::json!("prompt"));
- assert_eq!(
- properties["session_id"],
- serde_json::json!("0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1a")
- );
- }
-
- #[tokio::test]
- async fn timing_omits_unmeasured_stages() {
- let mock = Arc::new(MockSink::new());
- let client = recording_client(&mock);
- AgentTiming {
- stage: TimingStage::Tool,
- duration_ms: None,
- outcome: Some("success"),
- tool_category: Some(ToolCategory::Bash),
- timing_origin: None,
- }
- .track(&client);
- client.flush().await.unwrap();
- assert!(mock.event_names().is_empty(), "no duration, no event");
- AgentTiming {
- stage: TimingStage::StreamGap,
- duration_ms: Some(120),
- outcome: Some("success"),
- tool_category: None,
- timing_origin: Some("worker_action"),
- }
- .track(&client);
- client.flush().await.unwrap();
- let properties = properties_of(&mock, "agent timing").await;
- assert_eq!(properties["stage"], serde_json::json!("stream_gap"));
- assert_eq!(properties["duration_ms"], serde_json::json!(120));
- assert_eq!(
- properties["timing_origin"],
- serde_json::json!("worker_action")
- );
- }
-
- #[tokio::test]
- async fn tool_summary_skips_empty_categories() {
- let mock = Arc::new(MockSink::new());
- let client = recording_client(&mock);
- AgentToolSummary {
- session_id: "0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1a".into(),
- run_id: "0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1b".into(),
- tool_category: ToolCategory::Edit,
- call_count: 0,
- failure_count: 0,
- duration_ms: None,
- recovered_count: None,
- }
- .track(&client);
- client.flush().await.unwrap();
- assert!(mock.event_names().is_empty(), "no calls, no summary");
- }
-
- #[tokio::test]
- async fn error_requires_kind_and_id() {
- let mock = Arc::new(MockSink::new());
- let client = recording_client(&mock);
- AgentError::default().track(&client);
- client.flush().await.unwrap();
- assert!(mock.event_names().is_empty(), "no kind, no event");
- AgentError {
- error_id: "0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1c".into(),
- kind: Some(ErrorEventKind::Occurrence),
- subtype: Some("rate_limited"),
- category: Some("rate_limit"),
- code: Some("rate_limit_exceeded"),
- http_status: Some(429),
- classification_source: Some("http_status"),
- ..Default::default()
- }
- .track(&client);
- client.flush().await.unwrap();
- let properties = properties_of(&mock, "agent error").await;
- assert_eq!(
- properties["error_event_kind"],
- serde_json::json!("occurrence")
- );
- assert_eq!(
- properties["error_subtype"],
- serde_json::json!("rate_limited")
- );
- assert_eq!(
- properties["error_category"],
- serde_json::json!("rate_limit")
- );
- assert_eq!(properties["http_status"], serde_json::json!(429));
- assert_eq!(properties["classifier_revision"], serde_json::json!(2));
- assert!(!properties.contains_key("error_message"), "no raw message");
- }
+ use crate::catalog::{RUN_TRIGGERS, TOOL_CATEGORIES};
#[test]
fn tool_category_mapping() {
@@ -666,55 +238,23 @@ mod tests {
#[test]
fn vocabulary_consts_stay_in_the_catalog() {
- // The builder enums must stay inside the catalog vocabularies.
for trigger in ["prompt", "continuation", "unknown"] {
assert!(RUN_TRIGGERS.contains(&trigger));
}
- for stage in [
- "first_model_event",
- "first_reasoning",
- "first_text",
- "tool",
- "retry_wait",
- "compaction",
- "stream_gap",
- "time_to_error",
+ for category in [
+ ToolCategory::Read,
+ ToolCategory::Write,
+ ToolCategory::Edit,
+ ToolCategory::Bash,
+ ToolCategory::Grep,
+ ToolCategory::Find,
+ ToolCategory::Ls,
+ ToolCategory::Ipython,
+ ToolCategory::Mcp,
+ ToolCategory::Custom,
+ ToolCategory::Unknown,
] {
- assert!(TIMING_STAGES.contains(&stage), "{stage}");
- }
- for category in TOOL_CATEGORIES {
- assert!(TOOL_CATEGORIES.contains(category));
+ assert!(TOOL_CATEGORIES.contains(&category.as_str()));
}
- assert!(ERROR_SUBTYPES.contains(&"rate_limited"));
- assert!(ERROR_SUBTYPES.contains(&"stream_drop"));
- assert!(ERROR_CATEGORIES.contains(&"rate_limit"));
- assert!(ERROR_CODES.contains(&"unknown"));
- assert!(ERROR_CODES.contains(&"stream_drop"));
- assert!(CLASSIFICATION_SOURCES.contains(&"http_status"));
- assert!(ERROR_COMPONENTS.contains(&"provider"));
- assert!(ERROR_OPERATIONS.contains(&"stream"));
- assert!(ERROR_STAGES.contains(&"model_stream"));
- assert!(RECOVERY_ACTIONS.contains(&"automatic_retry"));
- assert!(RECOVERY_OUTCOMES.contains(&"success"));
- assert!(FEATURE_NAMES.contains(&"goal"));
- assert!(FEATURE_OUTCOMES.contains(&"completed"));
- assert!(INSTALLATION_STAGES.contains(&"completed"));
- assert!(INSTALLATION_OUTCOMES.contains(&"success"));
- assert!(INSTALLATION_REASONS.contains(&"up_to_date"));
- assert!(INSTALLATION_ACTIONS.contains(&"update"));
- assert!(INSTALLATION_SOURCES.contains(&"cli"));
- assert!(READY_KINDS.contains(&"interactive"));
- assert!(INPUT_STAGES.contains(&"terminal"));
- assert!(INPUT_OUTCOMES.contains(&"no_run"));
- assert!(STARTUP_STAGES.contains(&"ui_ready"));
- assert!(STARTUP_OUTCOMES.contains(&"completed"));
- assert!(STARTUP_KINDS.contains(&"cold"));
- assert!(TERMINAL_OUTCOMES.contains(&"success"));
- assert!(TIMING_ORIGINS.contains(&"worker_action"));
- assert!(ONBOARDING_STAGES.contains(&"exit"));
- assert!(ONBOARDING_OUTCOMES.contains(&"completed"));
- assert!(ONBOARDING_ENTRY_REASONS.contains(&"first_setup"));
- assert!(PROVIDER_CATEGORIES.contains(&"prime"));
- assert!(AUTH_CATEGORIES.contains(&"none"));
}
}
diff --git a/crates/pa-telemetry/src/flags.rs b/crates/pa-telemetry/src/flags.rs
deleted file mode 100644
index 2dbc45e638..0000000000
--- a/crates/pa-telemetry/src/flags.rs
+++ /dev/null
@@ -1,212 +0,0 @@
-//! `PostHog` feature-flag client (gradual rollouts).
-//!
-//! v1 scope: fetch + [`FlagsClient::flag_enabled`] with an in-memory TTL
-//! cache; no product gating lives in this crate. Decisions are anonymous —
-//! the only identity is the pseudonymous installation id (`distinct_id`).
-//! When `PostHog` is unreachable the configured default is served and the
-//! (empty) result is cached for the TTL so an offline client never
-//! request-storms.
-
-use std::collections::HashMap;
-use std::sync::atomic::{AtomicBool, Ordering};
-use std::time::{Duration, Instant};
-
-use serde_json::Value;
-
-/// How long a decide response (or a failed fetch) stays authoritative.
-pub const FLAG_CACHE_TTL: Duration = Duration::from_mins(5);
-
-const DECIDE_API_VERSION: &str = "v=3";
-
-/// `PostHog` decide client for one installation.
-pub struct FlagsClient {
- http: reqwest::Client,
- decide_url: String,
- api_key: String,
- distinct_id: String,
- cache: std::sync::Mutex<Option<CacheEntry>>,
- /// Latched when the decide endpoint answers 401 (bad or missing-scope
- /// credentials): no further decide is attempted, so a permanently
- /// rejected key cannot poll the endpoint every TTL.
- auth_terminal: AtomicBool,
-}
-
-struct CacheEntry {
- fetched_at: Instant,
- flags: HashMap<String, Value>,
-}
-
-impl FlagsClient {
- /// New decide client for one installation: fetches the endpoint's
- /// `/decide/` flags for `distinct_id`, on a 1.5s request timeout.
- ///
- /// # Panics
- ///
- /// Panics if the internal reqwest HTTP client (rustls backend) cannot
- /// be built.
- pub fn new(endpoint: &crate::sinks::PostHogEndpoint, distinct_id: impl Into<String>) -> Self {
- let http = reqwest::Client::builder()
- .timeout(Duration::from_millis(1500))
- .build()
- .expect("reqwest client with rustls");
- let base = endpoint.endpoint.trim_end_matches('/');
- Self {
- http,
- decide_url: format!("{base}/decide/?{DECIDE_API_VERSION}"),
- api_key: endpoint.api_key.clone(),
- distinct_id: distinct_id.into(),
- cache: std::sync::Mutex::new(None),
- auth_terminal: AtomicBool::new(false),
- }
- }
-
- /// Is the flag enabled for this installation? A fresh decide cache is
- /// authoritative for every flag name (absent = default, no refetch);
- /// a stale or missing cache refetches. Offline, `default` is served and
- /// the (empty) result is cached for the TTL so a dead endpoint is polled
- /// at most once per TTL per client.
- pub async fn flag_enabled(&self, name: &str, default: bool) -> bool {
- if self.auth_terminal.load(Ordering::Relaxed) {
- return default;
- }
- if let Some(value) = self.cached_flag(name) {
- let value = value.unwrap_or(Value::Null);
- return truthy(&value).unwrap_or(default);
- }
- if let Some(flags) = self.fetch().await {
- let value = flags.get(name).cloned().unwrap_or(Value::Null);
- self.store(flags);
- truthy(&value).unwrap_or(default)
- } else {
- self.store(HashMap::new());
- default
- }
- }
-
- /// Flag value from a fresh cache: `Some(None)` = fresh cache that does not
- /// know the flag (serve default, no refetch), `None` = stale/missing
- /// cache (refetch).
- // The two Option layers are a documented contract: outer = fresh-vs-stale
- // cache, inner = flag known vs absent. Flattening loses a state.
- #[allow(clippy::option_option)]
- fn cached_flag(&self, name: &str) -> Option<Option<Value>> {
- let cache = self.cache.lock().expect("flags cache poisoned");
- let cache = cache.as_ref()?;
- if cache.fetched_at.elapsed() >= FLAG_CACHE_TTL {
- return None;
- }
- Some(cache.flags.get(name).cloned())
- }
-
- /// Replace the cache with a fresh decide result.
- fn store(&self, flags: HashMap<String, Value>) {
- *self.cache.lock().expect("flags cache poisoned") = Some(CacheEntry {
- fetched_at: Instant::now(),
- flags,
- });
- }
-
- /// Parse the `featureFlags` object out of a decide v3 response; `None`
- /// on transport failure or a malformed body.
- async fn fetch(&self) -> Option<HashMap<String, Value>> {
- let response = self
- .http
- .post(&self.decide_url)
- .header("content-type", "application/json")
- .header("user-agent", format!("prime-agent/{}", crate::VERSION))
- .json(&serde_json::json!({
- "api_key": self.api_key,
- "distinct_id": self.distinct_id,
- }))
- .send()
- .await
- .ok()?;
- if response.status().as_u16() == 401 {
- // Terminal, not retried: bad or missing-scope credentials fail
- // every decide; stop polling instead of re-asking each TTL.
- self.auth_terminal.store(true, Ordering::Relaxed);
- tracing::debug!("feature-flag decide rejected with 401, polling disabled");
- return None;
- }
- if !response.status().is_success() {
- tracing::debug!(status = %response.status(), "feature-flag decide rejected");
- return None;
- }
- let body: Value = response.json().await.ok()?;
- let flags = body.get("featureFlags")?.as_object()?.clone();
- Some(flags.into_iter().collect::<HashMap<_, _>>())
- }
-}
-
-/// `PostHog` flag values are `true`/`false` (booleans) or multivariate strings.
-/// A string other than `"false"` is an enabled variant.
-fn truthy(value: &Value) -> Option<bool> {
- match value {
- Value::Bool(enabled) => Some(*enabled),
- Value::String(variant) => Some(variant != "false"),
- _ => None,
- }
-}
-
-#[cfg(test)]
-mod tests {
- use super::*;
-
- fn entry(flags: HashMap<String, Value>, fetched_at: Instant) -> CacheEntry {
- CacheEntry { fetched_at, flags }
- }
-
- fn flags(values: &[(&str, Value)]) -> HashMap<String, Value> {
- values
- .iter()
- .map(|(name, value)| ((*name).to_string(), value.clone()))
- .collect()
- }
-
- #[test]
- fn truthy_flag_values() {
- assert_eq!(truthy(&Value::Bool(true)), Some(true));
- assert_eq!(truthy(&Value::Bool(false)), Some(false));
- assert_eq!(truthy(&Value::String("control".into())), Some(true));
- assert_eq!(truthy(&Value::String("false".into())), Some(false));
- assert_eq!(truthy(&Value::Null), None);
- }
-
- #[test]
- fn fresh_cache_serves_flag() {
- let client = FlagsClient::new(
- &crate::sinks::PostHogEndpoint::new("http://127.0.0.1:1", "phc-key"),
- "install-1",
- );
- *client.cache.lock().unwrap() = Some(entry(
- flags(&[("new_engine", Value::Bool(true))]),
- Instant::now(),
- ));
- let cache = client.cache.lock().unwrap();
- assert!(cache.as_ref().is_some());
- }
-
- #[test]
- fn stale_cache_is_ignored() {
- let client = FlagsClient::new(
- &crate::sinks::PostHogEndpoint::new("http://127.0.0.1:1", "phc-key"),
- "install-1",
- );
- *client.cache.lock().unwrap() = Some(entry(
- flags(&[("new_engine", Value::Bool(true))]),
- Instant::now().checked_sub(FLAG_CACHE_TTL).unwrap(),
- ));
- assert!(client.cached_flag("new_engine").is_none());
- }
-
- #[test]
- fn fresh_cache_is_authoritative_for_absent_flags() {
- let client = FlagsClient::new(
- &crate::sinks::PostHogEndpoint::new("http://127.0.0.1:1", "phc-key"),
- "install-1",
- );
- *client.cache.lock().unwrap() = Some(entry(HashMap::new(), Instant::now()));
- // Fresh cache that does not know the flag: no refetch signal.
- assert_eq!(client.cached_flag("absent"), Some(None));
- }
-}
diff --git a/crates/pa-telemetry/src/install_id.rs b/crates/pa-telemetry/src/install_id.rs
index 3fedce6c96..dba7b311cc 100644
--- a/crates/pa-telemetry/src/install_id.rs
+++ b/crates/pa-telemetry/src/install_id.rs
@@ -81,13 +81,33 @@ pub fn install_id(agent_dir: &Path) -> Result<String> {
}
}
+/// The stored installation id, read-only: `None` when `telemetry.json` is
+/// absent, unreadable, or invalid (status surfaces must not create one).
+#[must_use]
+pub fn existing_install_id(agent_dir: &Path) -> Option<String> {
+ read_install_id(&agent_dir.join(STATE_FILE)).ok().flatten()
+}
+
/// Valid stored id, or `None` when the file is absent or holds invalid state.
fn read_install_id(path: &Path) -> Result<Option<String>> {
- let bytes = match std::fs::read(path) {
- Ok(bytes) => bytes,
+ // The state is opened non-blocking (unix O_NONBLOCK): a special
+ // file swapped onto the path (a FIFO) would block a plain read
+ // forever, and no caller — including the `/telemetry` confirmation
+ // after a saved opt-out — may hang on the telemetry state. A
+ // non-blocking FIFO with no writer reads empty and parses to no id.
+ let mut file = match open_state_nonblocking(path) {
+ Ok(file) => file,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
- Err(err) => return Err(err).with_context(|| format!("read {}", path.display())),
+ Err(err) => return Err(err).with_context(|| format!("open {}", path.display())),
};
+ let mut bytes = Vec::new();
+ match std::io::Read::read_to_end(&mut file, &mut bytes) {
+ Ok(_) => {}
+ // A non-blocking empty read (EAGAIN on a writer-less FIFO) is
+ // no id, not an error.
+ Err(err) if err.kind() == std::io::ErrorKind::WouldBlock => return Ok(None),
+ Err(err) => return Err(err).with_context(|| format!("read {}", path.display())),
+ }
let state: Option<State> = serde_json::from_slice(&bytes).ok();
let valid = state
.filter(|s| s.version == STATE_VERSION && is_uuid(&s.installation_id))
@@ -95,6 +115,28 @@ fn read_install_id(path: &Path) -> Result<Option<String>> {
Ok(valid)
}
+/// Open the state file read-only, non-blocking on unix (`O_NONBLOCK`):
+/// whatever now sits on the path — a regular state file or a swapped-in
+/// special file — opens and reads without ever parking the caller.
+#[cfg(unix)]
+fn open_state_nonblocking(path: &Path) -> std::io::Result<std::fs::File> {
+ use std::os::unix::fs::OpenOptionsExt;
+ std::fs::OpenOptions::new()
+ .read(true)
+ .custom_flags(
+ rustix::fs::OFlags::NONBLOCK
+ .bits()
+ .try_into()
+ .expect("O_NONBLOCK fits the open flags"),
+ )
+ .open(path)
+}
+
+#[cfg(not(unix))]
+fn open_state_nonblocking(path: &Path) -> std::io::Result<std::fs::File> {
+ std::fs::OpenOptions::new().read(true).open(path)
+}
+
/// Outcome of trying to publish a candidate state file exclusively.
enum Publish {
/// The candidate is live at the target path.
@@ -219,6 +261,26 @@ fn is_uuid(value: &str) -> bool {
mod tests {
use super::*;
+ /// A special file on the state path (a FIFO) is the blocking-read
+ /// hazard: the id read must come back empty (no id) instead of
+ /// parking the caller — the `/telemetry` confirmation after a saved
+ /// opt-out may never hang on the telemetry state.
+ #[test]
+ #[cfg(unix)]
+ fn a_fifo_on_the_state_path_reads_as_no_id() {
+ let dir = tempfile::tempdir().expect("temp dir");
+ let agent_dir = dir.path().join("agent");
+ std::fs::create_dir_all(&agent_dir).expect("agent dir");
+ // A FIFO with no writer: a plain read would block forever.
+ let fifo = agent_dir.join(STATE_FILE);
+ let status = std::process::Command::new("mkfifo")
+ .arg(&fifo)
+ .status()
+ .expect("mkfifo");
+ assert!(status.success(), "mkfifo created the fifo");
+ assert_eq!(existing_install_id(&agent_dir), None);
+ }
+
#[test]
fn uuid_validation() {
assert!(is_uuid("0197d0a0-8f5c-7f2a-b0e3-2d7e0d2b3b1a"));
diff --git a/crates/pa-telemetry/src/lib.rs b/crates/pa-telemetry/src/lib.rs
index 8fbea7599d..5e9bdaaebf 100644
--- a/crates/pa-telemetry/src/lib.rs
+++ b/crates/pa-telemetry/src/lib.rs
@@ -28,7 +28,6 @@ mod client;
mod env;
mod event;
mod events;
-mod flags;
mod install_id;
mod platform;
mod properties;
@@ -37,35 +36,46 @@ mod sink;
mod sinks;
mod time;
-/// Product version stamped on outgoing requests (`prime-agent/<version>`).
-pub const VERSION: &str = env!("CARGO_PKG_VERSION");
+static VERSION: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+
+/// Set the product version stamped on every event and on outgoing requests
+/// (`prime-agent/<version>`). The binary passes its runtime version: a
+/// release restamps the packaged manifest, not the compiled-in crate
+/// version. The first call wins.
+pub fn set_version(version: &str) {
+ let _ = VERSION.set(version.to_string());
+}
+
+/// The product version: the one given to [`set_version`], else the
+/// compiled-in crate version.
+#[must_use]
+pub fn version() -> &'static str {
+ VERSION
+ .get()
+ .map_or(env!("CARGO_PKG_VERSION"), String::as_str)
+}
pub use catalog::{
- catalog, lookup, sanitize, EventRule, PropKind, PropertyRule, AUTH_CATEGORIES, BUILD_CHANNELS,
- ERROR_CATEGORIES, ERROR_CLASSIFIER_REVISION, ERROR_CODES, ERROR_COMPONENTS,
- ERROR_MESSAGE_POLICY_REVISION, ERROR_MESSAGE_SOURCES, ERROR_OPERATIONS, ERROR_STAGES,
- ERROR_SUBTYPES, FEATURE_NAMES, FEATURE_OUTCOMES, INPUT_OUTCOMES, INPUT_STAGES,
- INSTALLATION_ACTIONS, INSTALLATION_OUTCOMES, INSTALLATION_REASONS, INSTALLATION_SOURCES,
- INSTALLATION_STAGES, MODEL_CATEGORIES, ONBOARDING_ENTRY_REASONS, ONBOARDING_OUTCOMES,
- ONBOARDING_STAGES, PROVIDER_CATEGORIES, READY_KINDS, RECOVERY_ACTIONS, RECOVERY_OUTCOMES,
- RUN_TRIGGERS, STARTUP_KINDS, STARTUP_OUTCOMES, STARTUP_STAGES, STOP_REASONS, TERMINAL_OUTCOMES,
- TIMING_ORIGINS, TIMING_STAGES, TOOL_CATEGORIES, WORKLOAD_ORIGINS,
+ catalog, feature_outcome_key, input_stage_key, lookup, sanitize, EventRule, PropKind,
+ PropertyRule, AUTH_CATEGORIES, BUILD_CHANNELS, ERROR_CATEGORIES, ERROR_SUBTYPES, FEATURE_NAMES,
+ FEATURE_OUTCOMES, INPUT_STAGES, INSTALLATION_ACTIONS, INSTALLATION_OUTCOMES,
+ INSTALLATION_REASONS, INSTALLATION_SOURCES, INSTALLATION_STAGES, MODEL_CATEGORIES,
+ ONBOARDING_ENTRY_REASONS, ONBOARDING_OUTCOMES, ONBOARDING_STAGES, PROVIDER_CATEGORIES,
+ READY_KINDS, RUN_TRIGGERS, STARTUP_KINDS, STARTUP_OUTCOMES, STARTUP_STAGES, STOP_REASONS,
+ TERMINAL_OUTCOMES, TOOL_CATEGORIES, WORKLOAD_ORIGINS,
};
pub use client::{TelemetryClient, TelemetryClientConfig};
-pub use env::{env_telemetry_override, parse_bool_override};
+pub use env::parse_bool_override;
pub use event::TelemetryEvent;
pub use events::{
- AgentError, AgentFeatureOutcome, AgentInputStage, AgentInstallationStage, AgentRunStarted,
- AgentStartupStage, AgentTiming, AgentToolSummary, ErrorEventKind, OnboardingStage, RunTrigger,
- TimingStage, ToolCategory,
+ AgentInstallationStage, AgentStartupStage, OnboardingStage, RunTrigger, ToolCategory,
};
-pub use flags::{FlagsClient, FLAG_CACHE_TTL};
-pub use install_id::install_id;
+pub use install_id::{existing_install_id, install_id};
pub use platform::{base_properties, SCHEMA_VERSION};
pub use properties::Properties;
pub use rename::rename_onto;
pub use sink::{SinkOutcome, TelemetrySink};
-pub use sinks::{FileSink, MockSink, NoopSink, PostHogEndpoint, PostHogSink, RecordedBatch};
+pub use sinks::{AnalyticsSink, FileSink, MockSink, NoopSink, RecordedBatch, ANALYTICS_ENDPOINT};
#[cfg(test)]
mod tests {
@@ -207,6 +217,33 @@ mod tests {
client.shutdown().await.unwrap();
}
+ #[tokio::test]
+ async fn the_live_switch_drops_while_off_and_resumes_when_on() {
+ use std::sync::atomic::{AtomicBool, Ordering};
+ let mock = Arc::new(MockSink::new());
+ let on = Arc::new(AtomicBool::new(false));
+ let mut config = TelemetryClientConfig::new("install-1");
+ config.flush_interval = Duration::from_mins(1);
+ config.sinks = vec![mock.clone() as Arc<dyn TelemetrySink>];
+ let switch = Arc::clone(&on);
+ config.enabled = Some(Arc::new(move || switch.load(Ordering::SeqCst)));
+ let client = TelemetryClient::spawn(config).unwrap();
+ client.track("while off", Properties::new());
+ // The worker takes the event while off; telemetry is turned back
+ // on before any delivery pass, and that event still never sends.
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ on.store(true, Ordering::SeqCst);
+ client.track("back on", Properties::new());
+ client.flush().await.unwrap();
+ assert_eq!(mock.event_names(), vec!["back on"]);
+ assert_eq!(
+ client.dropped_count(),
+ 1,
+ "the event tracked while off is dropped"
+ );
+ client.shutdown().await.unwrap();
+ }
+
#[tokio::test]
async fn failing_sink_never_propagates() {
let failing = Arc::new(MockSink::failing());
diff --git a/crates/pa-telemetry/src/platform.rs b/crates/pa-telemetry/src/platform.rs
index 9c4fbcb586..b387884ac9 100644
--- a/crates/pa-telemetry/src/platform.rs
+++ b/crates/pa-telemetry/src/platform.rs
@@ -17,11 +17,12 @@ const UNKNOWN: &str = "unknown";
const MAX_VERSION_LENGTH: usize = 64;
/// The catalog's property-rule revision (additive rule changes bump it).
-pub const SCHEMA_REVISION: u64 = 2;
+pub const SCHEMA_REVISION: u64 = 3;
/// The `cpu_baseline` values.
const CPU_AVX2: &str = "avx2";
const CPU_NO_AVX2: &str = "no_avx2";
+const CPU_AVX2_ASSUMED: &str = "avx2_assumed";
const CPU_NOT_APPLICABLE: &str = "not_applicable";
/// The platform-fidelity set (memoised: probes run at most once per process).
@@ -39,7 +40,7 @@ struct PlatformFidelity {
pub fn base_properties(execution_mode: &str) -> Properties {
let fidelity = fidelity();
let mut properties = Properties::new();
- properties.set("version", Value::String(crate::VERSION.to_string()));
+ properties.set("version", Value::from(crate::version()));
properties.set("schema_version", Value::from(SCHEMA_VERSION));
// #2117/v2 common properties: the build channel, the workload origin
// (env override first, then the execution mode), and the catalog's
@@ -50,8 +51,8 @@ pub fn base_properties(execution_mode: &str) -> Properties {
Value::from(workload_origin(execution_mode)),
);
properties.set("schema_revision", Value::from(SCHEMA_REVISION));
- properties.set("os_family", Value::from(std::env::consts::OS));
- properties.set("architecture", Value::from(std::env::consts::ARCH));
+ properties.set("os_family", Value::from(os_family()));
+ properties.set("architecture", Value::from(architecture()));
properties.set("install_method", Value::String("binary".to_string()));
properties.set("execution_mode", Value::from(execution_mode));
properties.set("libc", Value::from(fidelity.libc));
@@ -65,13 +66,36 @@ pub fn base_properties(execution_mode: &str) -> Properties {
properties
}
+/// The OS in the TS product's vocabulary (Node `os.platform()`), so the
+/// Rust and TS populations land in the same `os_family` buckets.
+fn os_family() -> &'static str {
+ match std::env::consts::OS {
+ "macos" => "darwin",
+ "windows" => "win32",
+ other => other,
+ }
+}
+
+/// The CPU architecture in the TS product's vocabulary (Node `os.arch()`).
+fn architecture() -> &'static str {
+ match std::env::consts::ARCH {
+ "x86_64" => "x64",
+ "aarch64" => "arm64",
+ "x86" => "ia32",
+ "powerpc64" => "ppc64",
+ "loongarch64" => "loong64",
+ other => other,
+ }
+}
+
/// The build channel: debug builds are `development`, versions carrying a
/// `beta` prerelease are `prerelease`, everything else `release`.
fn build_channel() -> &'static str {
if cfg!(debug_assertions) {
return "development";
}
- if crate::VERSION.contains('-') && crate::VERSION.contains("beta") {
+ let version = crate::version();
+ if version.contains('-') && version.contains("beta") {
return "prerelease";
}
"release"
@@ -127,12 +151,42 @@ fn detect_libc() -> &'static str {
}
}
-/// The linked glibc version when `getconf GNU_LIBC_VERSION` output is embedded
-/// at build time; the Rust standard library exposes no portable runtime probe,
-/// so this stays `unknown` unless ldd-style inspection succeeded. Cheapest true
-/// answer: `ldd --version` needs a subprocess, which is out of budget here.
+/// The running glibc version (TS `glibcVersionRuntime`, e.g. `2.39`) on
+/// glibc Linux builds: the loaded `libc.so.6` (found in `/proc/self/maps`)
+/// carries its banner `... stable release version 2.39.`; `unknown`
+/// elsewhere or when the probe fails.
fn detect_libc_version() -> String {
- UNKNOWN.to_string()
+ if cfg!(all(target_os = "linux", target_env = "gnu")) {
+ loaded_glibc_version().unwrap_or_else(|| UNKNOWN.to_string())
+ } else {
+ UNKNOWN.to_string()
+ }
+}
+
+fn loaded_glibc_version() -> Option<String> {
+ let maps = read_text_prefix("/proc/self/maps", 1 << 20)?;
+ let path = maps
+ .lines()
+ .filter_map(|line| line.split_whitespace().nth(5))
+ .find(|path| path.ends_with("/libc.so.6"))?;
+ let library = std::fs::read(path).ok()?;
+ glibc_banner_version(&library)
+}
+
+fn glibc_banner_version(library: &[u8]) -> Option<String> {
+ let marker = b"release version ";
+ let start = library
+ .windows(marker.len())
+ .position(|window| window == marker)?
+ + marker.len();
+ let version: String = library[start..]
+ .iter()
+ .take(16)
+ .take_while(|byte| byte.is_ascii_digit() || **byte == b'.')
+ .map(|&byte| char::from(byte))
+ .collect();
+ let version = version.trim_end_matches('.');
+ (!version.is_empty()).then(|| version.to_string())
}
/// AVX2 availability on `x86_64` via /proc/cpuinfo (Linux); not applicable off
@@ -153,6 +207,10 @@ fn detect_cpu_baseline() -> &'static str {
Some(_) => CPU_NO_AVX2,
None => UNKNOWN,
}
+ } else if cfg!(target_os = "macos") {
+ // TS parity: every Intel Mac that runs a supported macOS has
+ // AVX2; the distinct value keeps the inference visible.
+ CPU_AVX2_ASSUMED
} else {
UNKNOWN
}
@@ -161,11 +219,18 @@ fn detect_cpu_baseline() -> &'static str {
}
}
-/// Kernel release via /proc (Linux); `unknown` elsewhere.
+/// The kernel release (TS `os.release()`: `uname -r` on Linux and macOS);
+/// `unknown` on Windows, where this build has no probe.
fn detect_os_release() -> String {
- if cfg!(target_os = "linux") {
- read_text_prefix("/proc/sys/kernel/osrelease", 256).unwrap_or_else(|| UNKNOWN.into())
- } else {
+ #[cfg(unix)]
+ {
+ rustix::system::uname()
+ .release()
+ .to_string_lossy()
+ .into_owned()
+ }
+ #[cfg(not(unix))]
+ {
UNKNOWN.into()
}
}
@@ -192,13 +257,14 @@ fn detect_os_product_version() -> String {
}
}
+/// Up to `max_bytes` of a text file. Reads until EOF or the cap: procfs
+/// files answer one page per `read`, so a single read would truncate them.
fn read_text_prefix(path: &str, max_bytes: usize) -> Option<String> {
use std::io::Read;
- let mut file = std::fs::File::open(path).ok()?;
- let mut buffer = vec![0u8; max_bytes];
- let read = file.read(&mut buffer).ok()?;
- buffer.truncate(read);
- String::from_utf8(buffer).ok()
+ let file = std::fs::File::open(path).ok()?;
+ let mut buffer = Vec::new();
+ file.take(max_bytes as u64).read_to_end(&mut buffer).ok()?;
+ String::from_utf8_lossy(&buffer).into_owned().into()
}
fn sanitize_version(value: &str) -> String {
@@ -240,7 +306,7 @@ mod tests {
);
assert_eq!(
properties.get("version"),
- Some(&Value::from(crate::VERSION))
+ Some(&Value::from(crate::version()))
);
assert_eq!(
properties.get("execution_mode"),
@@ -250,13 +316,10 @@ mod tests {
properties.get("install_method"),
Some(&Value::from("binary"))
);
- assert_eq!(
- properties.get("os_family"),
- Some(&Value::from(std::env::consts::OS))
- );
+ assert_eq!(properties.get("os_family"), Some(&Value::from(os_family())));
assert_eq!(
properties.get("architecture"),
- Some(&Value::from(std::env::consts::ARCH))
+ Some(&Value::from(architecture()))
);
// Fidelity fields are always present and never empty.
for key in [
@@ -281,6 +344,36 @@ mod tests {
}
}
+ /// The TS (Node) vocabulary the existing dashboards group by.
+ #[test]
+ fn platform_names_use_the_ts_vocabulary() {
+ let os = os_family();
+ assert!(["linux", "darwin", "win32", "freebsd", "android"].contains(&os) || !os.is_empty());
+ assert_ne!(os, "macos");
+ assert_ne!(os, "windows");
+ let arch = architecture();
+ assert_ne!(arch, "x86_64");
+ assert_ne!(arch, "aarch64");
+ if cfg!(target_arch = "x86_64") {
+ assert_eq!(arch, "x64");
+ }
+ if cfg!(target_os = "linux") {
+ assert_eq!(os, "linux");
+ }
+ }
+
+ #[test]
+ fn the_glibc_banner_parses() {
+ let banner =
+ b"\0GNU C Library (Ubuntu GLIBC 2.39-0ubuntu8.4) stable release version 2.39.\n\0";
+ assert_eq!(glibc_banner_version(banner).as_deref(), Some("2.39"));
+ assert_eq!(glibc_banner_version(b"no banner here"), None);
+ if cfg!(all(target_os = "linux", target_env = "gnu")) {
+ let version = detect_libc_version();
+ assert!(version.starts_with("2."), "the running glibc: {version}");
+ }
+ }
+
#[test]
fn sanitize_trims_and_caps() {
assert_eq!(sanitize_version(" 6.8.0-45-generic "), "6.8.0-45-generic");
diff --git a/crates/pa-telemetry/src/sink.rs b/crates/pa-telemetry/src/sink.rs
index 0ecdbeddf1..e133c68fed 100644
--- a/crates/pa-telemetry/src/sink.rs
+++ b/crates/pa-telemetry/src/sink.rs
@@ -25,7 +25,7 @@ pub enum SinkOutcome {
/// the future to the sink borrow, so implementations can borrow `&self`.
///
/// `install_id` is the pseudonymous installation id used as the sink-side
-/// identity (`PostHog` `distinct_id`).
+/// identity (the analytics body's `installation_id`).
pub trait TelemetrySink: Send + Sync {
/// Send one batch. Called serially by the telemetry worker, so at most one
/// `send_batch` future per sink is in flight at a time.
diff --git a/crates/pa-telemetry/src/sinks/analytics.rs b/crates/pa-telemetry/src/sinks/analytics.rs
new file mode 100644
index 0000000000..d36731a52a
--- /dev/null
+++ b/crates/pa-telemetry/src/sinks/analytics.rs
@@ -0,0 +1,121 @@
+//! The Prime Intellect analytics sink (the default product sink).
+//!
+//! Wire format is the TS product's (`core/telemetry.ts` `TelemetryClient`):
+//! `POST <endpoint>` with `{"installation_id", "events": [{"id", "name",
+//! "timestamp", "properties"}]}`, `content-type: application/json`,
+//! `user-agent: prime-agent/<version>`, no credentials. The platform backend
+//! forwards each event to `PostHog` with `distinct_id = installation_id`
+//! and `uuid = id`, so Rust and TS installs count as the same users.
+
+use std::future::Future;
+use std::pin::Pin;
+use std::time::Duration;
+
+use serde_json::{json, Value};
+
+use crate::event::TelemetryEvent;
+use crate::sink::{SinkOutcome, TelemetrySink};
+
+/// The TS product's endpoint: the one destination for product telemetry.
+pub const ANALYTICS_ENDPOINT: &str = "https://api.primeintellect.ai/api/v1/agent-analytics/events";
+
+/// TS parity: requests time out after 1.5s so telemetry never holds the agent.
+pub const DEFAULT_REQUEST_TIMEOUT: Duration = Duration::from_millis(1500);
+
+/// Batches to the analytics endpoint. Best-effort: a transport error,
+/// timeout, non-2xx status, or a 2xx that accepted nothing (the backend
+/// answers `{"accepted": 0}` when its `PostHog` delivery failed) reports
+/// [`SinkOutcome::Dropped`], and the client's bounded retry re-sends the
+/// same event ids.
+#[derive(Clone)]
+pub struct AnalyticsSink {
+ http: reqwest::Client,
+ endpoint: String,
+}
+
+impl AnalyticsSink {
+ /// Sink posting to `endpoint` (the product passes [`ANALYTICS_ENDPOINT`];
+ /// tests pass a local stub) with the TS-parity 1.5s request timeout.
+ #[must_use]
+ pub fn new(endpoint: impl Into<String>) -> Self {
+ Self::with_timeout(endpoint, DEFAULT_REQUEST_TIMEOUT)
+ }
+
+ /// Sink with an explicit request timeout (tests).
+ ///
+ /// # Panics
+ ///
+ /// Panics if the reqwest HTTP client (rustls backend) cannot be built.
+ #[must_use]
+ pub fn with_timeout(endpoint: impl Into<String>, timeout: Duration) -> Self {
+ let http = reqwest::Client::builder()
+ .timeout(timeout)
+ .build()
+ .expect("reqwest client with rustls");
+ Self {
+ http,
+ endpoint: endpoint.into(),
+ }
+ }
+
+ /// The request body as it goes on the wire.
+ #[must_use]
+ pub fn batch_body(install_id: &str, events: &[TelemetryEvent]) -> Value {
+ json!({
+ "installation_id": install_id,
+ "events": events.iter().map(TelemetryEvent::to_value).collect::<Vec<_>>(),
+ })
+ }
+}
+
+impl TelemetrySink for AnalyticsSink {
+ fn send_batch<'a>(
+ &'a self,
+ install_id: &'a str,
+ events: Vec<TelemetryEvent>,
+ ) -> Pin<Box<dyn Future<Output = SinkOutcome> + Send + 'a>> {
+ Box::pin(async move {
+ if events.is_empty() {
+ return SinkOutcome::Sent;
+ }
+ let response = self
+ .http
+ .post(&self.endpoint)
+ .header("content-type", "application/json")
+ .header("user-agent", format!("prime-agent/{}", crate::version()))
+ .json(&Self::batch_body(install_id, &events))
+ .send()
+ .await;
+ match response {
+ Ok(response) if response.status().is_success() => {
+ let accepted = response
+ .json::<Value>()
+ .await
+ .ok()
+ .and_then(|body| body.get("accepted").and_then(Value::as_u64));
+ if accepted == Some(0) {
+ tracing::debug!(
+ count = events.len(),
+ "telemetry batch accepted nothing, dropping"
+ );
+ SinkOutcome::Dropped
+ } else {
+ SinkOutcome::Sent
+ }
+ }
+ Ok(response) => {
+ tracing::debug!(
+ status = %response.status(),
+ count = events.len(),
+ "telemetry batch rejected, dropping"
+ );
+ SinkOutcome::Dropped
+ }
+ Err(err) => {
+ tracing::debug!(error = %err, count = events.len(), "telemetry batch send failed, dropping");
+ SinkOutcome::Dropped
+ }
+ }
+ })
+ }
+}
diff --git a/crates/pa-telemetry/src/sinks/mod.rs b/crates/pa-telemetry/src/sinks/mod.rs
index 5058902c8b..dd51a13f0c 100644
--- a/crates/pa-telemetry/src/sinks/mod.rs
+++ b/crates/pa-telemetry/src/sinks/mod.rs
@@ -1,11 +1,11 @@
//! Sinks shipped with the crate.
+pub mod analytics;
pub mod file;
pub mod mock;
pub mod noop;
-pub mod posthog;
+pub use analytics::{AnalyticsSink, ANALYTICS_ENDPOINT};
pub use file::FileSink;
pub use mock::{MockSink, RecordedBatch};
pub use noop::NoopSink;
-pub use posthog::{PostHogEndpoint, PostHogSink};
diff --git a/crates/pa-telemetry/src/sinks/posthog.rs b/crates/pa-telemetry/src/sinks/posthog.rs
deleted file mode 100644
index d79f1bb960..0000000000
--- a/crates/pa-telemetry/src/sinks/posthog.rs
+++ /dev/null
@@ -1,239 +0,0 @@
-//! `PostHog` batched capture sink (primary product sink).
-//!
-//! Wire format is the `PostHog` capture v2 batch API: `POST {base}/batch/` with
-//! `{"api_key", "batch": [{event, distinct_id, timestamp, properties}]}`.
-//! Endpoint and project key come from configuration (env override, then
-//! settings, resolved by the composition root); pa-telemetry ships no
-//! compiled-in endpoint or key, so the stack is self-hostable and an empty
-//! configuration resolves to `NoopSink` instead.
-
-use std::future::Future;
-use std::pin::Pin;
-use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::Arc;
-use std::time::Duration;
-
-use serde_json::json;
-
-use crate::event::TelemetryEvent;
-use crate::sink::{SinkOutcome, TelemetrySink};
-
-/// TS parity: requests time out after 1.5s so telemetry never holds the agent.
-pub const DEFAULT_REQUEST_TIMEOUT: Duration = Duration::from_millis(1500);
-
-/// A resolved `PostHog` endpoint: base URL + project capture key.
-/// Built from env (`PRIME_AGENT_TELEMETRY_ENDPOINT` / `_API_KEY`) or from
-/// settings `telemetry.posthog.*`; both fields must be non-empty.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct PostHogEndpoint {
- /// Base URL, e.g. `https://us.i.posthog.com` (no trailing slash).
- pub endpoint: String,
- /// Project capture api key.
- pub api_key: String,
-}
-
-impl PostHogEndpoint {
- /// Resolve from env overrides. `None` when either variable is unset or
- /// empty (the caller then falls back to settings or `NoopSink`).
- pub fn from_env() -> Option<Self> {
- let endpoint = std::env::var("PRIME_AGENT_TELEMETRY_ENDPOINT")
- .ok()
- .as_deref()
- .and_then(trimmed_non_empty);
- let api_key = std::env::var("PRIME_AGENT_TELEMETRY_API_KEY")
- .ok()
- .as_deref()
- .and_then(trimmed_non_empty);
- Some(Self {
- endpoint: endpoint?,
- api_key: api_key?,
- })
- }
-
- pub fn new(endpoint: impl Into<String>, api_key: impl Into<String>) -> Self {
- Self {
- endpoint: endpoint.into(),
- api_key: api_key.into(),
- }
- }
-
- fn batch_url(&self) -> String {
- format!("{}/batch/", self.endpoint.trim_end_matches('/'))
- }
-}
-
-fn trimmed_non_empty(value: &str) -> Option<String> {
- let trimmed = value.trim();
- (!trimmed.is_empty()).then(|| trimmed.to_string())
-}
-
-/// The primary sink: batches to `PostHog`. Best-effort — any non-2xx response,
-/// transport error, or timeout drops the batch (offline-safe, no retries).
-/// A 401 is terminal instead of per-batch: bad or missing-scope credentials
-/// cannot succeed on a later batch, so the sink stops requesting until the
-/// process restarts (a 401 every flush is a retry loop the endpoint can
-/// never clear).
-#[derive(Clone)]
-pub struct PostHogSink {
- http: reqwest::Client,
- batch_url: String,
- api_key: String,
- auth_terminal: Arc<AtomicBool>,
-}
-
-impl PostHogSink {
- /// Sink with the TS-parity 1.5s request timeout.
- #[must_use]
- pub fn new(endpoint: &PostHogEndpoint) -> Self {
- Self::with_timeout(endpoint, DEFAULT_REQUEST_TIMEOUT)
- }
-
- /// Sink with an explicit request timeout (tests).
- ///
- /// # Panics
- ///
- /// Panics if the reqwest HTTP client (rustls backend) cannot be built.
- #[must_use]
- pub fn with_timeout(endpoint: &PostHogEndpoint, timeout: Duration) -> Self {
- let http = reqwest::Client::builder()
- .timeout(timeout)
- .build()
- .expect("reqwest client with rustls");
- Self {
- http,
- batch_url: endpoint.batch_url(),
- api_key: endpoint.api_key.clone(),
- auth_terminal: Arc::new(AtomicBool::new(false)),
- }
- }
-
- /// The batch request body as it goes on the wire.
- pub(crate) fn batch_body(
- &self,
- install_id: &str,
- events: &[TelemetryEvent],
- ) -> serde_json::Value {
- json!({
- "api_key": self.api_key,
- "schema_version": crate::catalog::SCHEMA_VERSION,
- "batch": events
- .iter()
- .map(|event| {
- json!({
- "event": event.name,
- "distinct_id": install_id,
- "timestamp": event.timestamp_iso8601(),
- "properties": event.properties.to_map(),
- })
- })
- .collect::<Vec<_>>(),
- })
- }
-}
-
-impl TelemetrySink for PostHogSink {
- fn send_batch<'a>(
- &'a self,
- install_id: &'a str,
- events: Vec<TelemetryEvent>,
- ) -> Pin<Box<dyn Future<Output = SinkOutcome> + Send + 'a>> {
- Box::pin(async move {
- if events.is_empty() {
- return SinkOutcome::Sent;
- }
- if self.auth_terminal.load(Ordering::Relaxed) {
- return SinkOutcome::Dropped;
- }
- let body = self.batch_body(install_id, &events);
- let response = self
- .http
- .post(&self.batch_url)
- .header("content-type", "application/json")
- .header("user-agent", format!("prime-agent/{}", crate::VERSION))
- .json(&body)
- .send()
- .await;
- match response {
- Ok(response) if response.status().is_success() => SinkOutcome::Sent,
- Ok(response) if response.status().as_u16() == 401 => {
- // Terminal, not retried: the key is bad or missing a
- // scope, so no later batch can succeed either.
- self.auth_terminal.store(true, Ordering::Relaxed);
- tracing::debug!(
- count = events.len(),
- "telemetry batch rejected with 401 (bad or missing-scope credentials), sink disabled"
- );
- SinkOutcome::Dropped
- }
- Ok(response) => {
- tracing::debug!(
- status = %response.status(),
- count = events.len(),
- "telemetry batch rejected, dropping"
- );
- SinkOutcome::Dropped
- }
- Err(err) => {
- tracing::debug!(error = %err, count = events.len(), "telemetry batch send failed, dropping");
- SinkOutcome::Dropped
- }
- }
- })
- }
-}
-
-#[cfg(test)]
-mod tests {
- use super::*;
- use crate::properties::Properties;
-
- fn event(name: &str) -> TelemetryEvent {
- let mut properties = Properties::new();
- properties.set("version", serde_json::Value::from("0.1.0"));
- TelemetryEvent::new(name, properties)
- }
-
- #[test]
- fn batch_body_wire_shape() {
- let sink = PostHogSink::new(&PostHogEndpoint::new("https://ph.example", "phc-key"));
- let body = sink.batch_body("install-1", &[event("agent started")]);
- assert_eq!(body["api_key"], "phc-key");
- assert_eq!(
- body["schema_version"],
- json!(crate::catalog::SCHEMA_VERSION)
- );
- assert_eq!(body["batch"][0]["event"], "agent started");
- assert_eq!(body["batch"][0]["distinct_id"], "install-1");
- assert_eq!(body["batch"][0]["properties"]["version"], "0.1.0");
- assert!(body["batch"][0]["timestamp"]
- .as_str()
- .unwrap()
- .ends_with('Z'));
- }
-
- #[test]
- fn endpoint_env_resolution_requires_both() {
- // No env: absent.
- std::env::remove_var("PRIME_AGENT_TELEMETRY_ENDPOINT");
- std::env::remove_var("PRIME_AGENT_TELEMETRY_API_KEY");
- assert_eq!(PostHogEndpoint::from_env(), None);
- std::env::set_var("PRIME_AGENT_TELEMETRY_ENDPOINT", "https://ph.example/");
- assert_eq!(PostHogEndpoint::from_env(), None);
- std::env::set_var("PRIME_AGENT_TELEMETRY_API_KEY", " phc-key ");
- let resolved = PostHogEndpoint::from_env().expect("both set");
- assert_eq!(
- resolved,
- PostHogEndpoint::new("https://ph.example/", "phc-key")
- );
- assert_eq!(resolved.batch_url(), "https://ph.example/batch/");
- std::env::remove_var("PRIME_AGENT_TELEMETRY_ENDPOINT");
- std::env::remove_var("PRIME_AGENT_TELEMETRY_API_KEY");
- }
-
- #[tokio::test]
- async fn empty_batch_short_circuits() {
- let sink = PostHogSink::new(&PostHogEndpoint::new("http://127.0.0.1:1", "phc-key"));
- let outcome = sink.send_batch("install-1", vec![]).await;
- assert_eq!(outcome, SinkOutcome::Sent);
- }
-}
diff --git a/crates/pa-telemetry/src/time.rs b/crates/pa-telemetry/src/time.rs
index dc25c50dbf..6868a6b956 100644
--- a/crates/pa-telemetry/src/time.rs
+++ b/crates/pa-telemetry/src/time.rs
@@ -1,8 +1,8 @@
//! Millisecond-epoch to ISO-8601 (UTC) formatting, no time crate.
//!
//! Telemetry timestamps are stored as epoch milliseconds and rendered as
-//! `YYYY-MM-DDTHH:MM:SS.mmmZ` for the `PostHog` `timestamp` field and the local
-//! JSONL mirror. Civil-date math per Howard Hinnant's `civil_from_days`.
+//! `YYYY-MM-DDTHH:MM:SS.mmmZ` (JS `toISOString`) for the analytics `timestamp`
+//! field and the local JSONL mirror. Civil-date math per Howard Hinnant's `civil_from_days`.
/// Milliseconds since the Unix epoch.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
diff --git a/crates/pa-telemetry/tests/analytics_wire.rs b/crates/pa-telemetry/tests/analytics_wire.rs
new file mode 100644
index 0000000000..a8c089b154
--- /dev/null
+++ b/crates/pa-telemetry/tests/analytics_wire.rs
@@ -0,0 +1,242 @@
+//! Wire tests for the default analytics sink against a local HTTP stub: the
+//! exact TS `TelemetryClient` request (path, headers, body), the batching
+//! client's delivery through it, and the drop policy.
+
+use std::io::{Read, Write};
+use std::net::TcpListener;
+use std::sync::{mpsc, Arc};
+use std::time::Duration;
+
+use pa_telemetry::{
+ AnalyticsSink, Properties, SinkOutcome, TelemetryClient, TelemetryClientConfig, TelemetryEvent,
+ TelemetrySink,
+};
+use serde_json::json;
+
+const INSTALL_ID: &str = "0b5f4c1e-6a59-4c6e-9d3a-2f1e8b7c9a10";
+
+fn event(name: &str) -> TelemetryEvent {
+ let mut properties = Properties::new();
+ properties.set("version", json!("9.9.9"));
+ properties.set("outcome", json!("success"));
+ properties.set("visible_ttft_ms", serde_json::Value::Null);
+ TelemetryEvent::new(name, properties)
+}
+
+/// The TS body, field for field: `{installation_id, events: [{id, name,
+/// timestamp, properties}]}` and nothing else.
+fn ts_body(events: &[TelemetryEvent]) -> serde_json::Value {
+ json!({
+ "installation_id": INSTALL_ID,
+ "events": events
+ .iter()
+ .map(|event| json!({
+ "id": event.id,
+ "name": event.name,
+ "timestamp": event.timestamp_iso8601(),
+ "properties": event
+ .properties
+ .iter()
+ .map(|(key, value)| (key.clone(), value.clone()))
+ .collect::<serde_json::Map<_, _>>(),
+ }))
+ .collect::<Vec<_>>(),
+ })
+}
+
+#[tokio::test]
+async fn batch_posts_the_exact_ts_request() {
+ // The binary's runtime version (a beta restamps only the packaged
+ // manifest) rides the User-Agent and every event, not the crate's.
+ pa_telemetry::set_version("0.9.9-beta.3");
+ assert_eq!(
+ pa_telemetry::base_properties("print").get("version"),
+ Some(&json!("0.9.9-beta.3"))
+ );
+ let (base, rx) = spawn_stub(vec![(202, json!({ "accepted": 2 }))]);
+ let sink = AnalyticsSink::new(format!("{base}/api/v1/agent-analytics/events"));
+ let events = vec![event("agent started"), event("agent run completed")];
+ let outcome = sink.send_batch(INSTALL_ID, events.clone()).await;
+ assert_eq!(outcome, SinkOutcome::Sent);
+
+ let request = rx.recv().expect("stub captured request");
+ assert!(request
+ .request_line
+ .starts_with("POST /api/v1/agent-analytics/events "));
+ assert_eq!(
+ header(&request.headers, "content-type"),
+ Some("application/json")
+ );
+ assert_eq!(
+ header(&request.headers, "user-agent"),
+ Some("prime-agent/0.9.9-beta.3")
+ );
+ assert_eq!(header(&request.headers, "authorization"), None);
+ assert_eq!(request.body, ts_body(&events));
+
+ let first = &request.body["events"][0];
+ assert!(uuid_v4(first["id"].as_str().unwrap()));
+ let timestamp = first["timestamp"].as_str().unwrap();
+ // `new Date().toISOString()`: millisecond precision, UTC `Z`.
+ assert_eq!(timestamp.len(), "2026-10-01T12:00:00.000Z".len());
+ assert!(timestamp.ends_with('Z'));
+}
+
+#[tokio::test]
+async fn the_client_batches_through_the_sink() {
+ let (base, rx) = spawn_stub(vec![(202, json!({ "accepted": 2 }))]);
+ let mut config = TelemetryClientConfig::new(INSTALL_ID);
+ config.flush_interval = Duration::from_mins(1);
+ config.sinks = vec![Arc::new(AnalyticsSink::new(base)) as Arc<dyn TelemetrySink>];
+ let client = TelemetryClient::spawn(config).unwrap();
+ client.track("agent command used", properties("command_name", "model"));
+ client.track("agent command used", properties("command_name", "resume"));
+ client.flush().await.unwrap();
+
+ let request = rx.recv().expect("one request for both events");
+ assert_eq!(request.body["installation_id"], INSTALL_ID);
+ let events = request.body["events"].as_array().unwrap();
+ assert_eq!(events.len(), 2);
+ assert_eq!(events[0]["name"], "agent command used");
+ assert_eq!(events[0]["properties"]["command_name"], "model");
+ assert_eq!(events[1]["properties"]["command_name"], "resume");
+ assert_ne!(events[0]["id"], events[1]["id"]);
+ client.shutdown().await.unwrap();
+}
+
+#[tokio::test]
+async fn failures_drop_the_batch() {
+ let (base, rx) = spawn_stub(vec![
+ (500, json!({ "detail": "boom" })),
+ // The backend's answer when its PostHog delivery failed.
+ (202, json!({ "accepted": 0 })),
+ ]);
+ let sink = AnalyticsSink::new(base);
+ assert_eq!(
+ sink.send_batch(INSTALL_ID, vec![event("agent started")])
+ .await,
+ SinkOutcome::Dropped
+ );
+ assert_eq!(
+ sink.send_batch(INSTALL_ID, vec![event("agent started")])
+ .await,
+ SinkOutcome::Dropped
+ );
+ assert_eq!(rx.iter().take(2).count(), 2);
+}
+
+#[tokio::test]
+async fn an_unreachable_endpoint_times_out_as_a_drop() {
+ // A listener that never answers: the request timeout bounds the send.
+ let listener = TcpListener::bind("127.0.0.1:0").unwrap();
+ let sink = AnalyticsSink::with_timeout(
+ format!("http://{}", listener.local_addr().unwrap()),
+ Duration::from_millis(200),
+ );
+ let started = std::time::Instant::now();
+ let outcome = sink
+ .send_batch(INSTALL_ID, vec![event("agent started")])
+ .await;
+ assert_eq!(outcome, SinkOutcome::Dropped);
+ assert!(started.elapsed() < Duration::from_secs(5));
+}
+
+fn properties(key: &str, value: &str) -> Properties {
+ let mut properties = Properties::new();
+ properties.set(key, json!(value));
+ properties
+}
+
+fn uuid_v4(value: &str) -> bool {
+ uuid::Uuid::parse_str(value).is_ok_and(|id| id.get_version_num() == 4)
+}
+
+/// One request captured by the stub.
+struct StubRequest {
+ request_line: String,
+ headers: Vec<(String, String)>,
+ body: serde_json::Value,
+}
+
+/// Serve `responses` (status, raw HTTP body) one per connection, capture each
+/// request, and stop. Returns (`base_url`, receiver).
+fn spawn_stub(responses: Vec<(u16, serde_json::Value)>) -> (String, mpsc::Receiver<StubRequest>) {
+ let listener = TcpListener::bind("127.0.0.1:0").expect("bind stub");
+ let addr = listener.local_addr().expect("stub addr");
+ let (tx, rx) = mpsc::channel();
+ std::thread::spawn(move || {
+ for response in responses {
+ let (mut stream, _) = listener.accept().expect("accept");
+ // 64 KiB read buffer on a dedicated stub thread is fine for a test.
+ #[allow(clippy::large_stack_arrays)]
+ let mut buffer = [0u8; 64 * 1024];
+ let mut read_total = 0usize;
+ let mut request = String::new();
+ loop {
+ let n = stream
+ .read(&mut buffer[read_total..])
+ .expect("read request");
+ if n == 0 {
+ break;
+ }
+ request.push_str(&String::from_utf8_lossy(
+ &buffer[read_total..read_total + n],
+ ));
+ read_total += n;
+ let header_end = request.find("\r\n\r\n").expect("headers terminator");
+ if let Some(len) = content_length(&request[..header_end]) {
+ let body_start = header_end + 4;
+ if request.len() - body_start >= len {
+ break;
+ }
+ }
+ }
+ let header_end = request.find("\r\n\r\n").expect("headers terminator");
+ let header_text = &request[..header_end];
+ let request_line = header_text.lines().next().unwrap_or_default().to_string();
+ let headers: Vec<(String, String)> = header_text
+ .lines()
+ .skip(1)
+ .filter_map(|line| line.split_once(':'))
+ .map(|(name, value)| (name.trim().to_ascii_lowercase(), value.trim().to_string()))
+ .collect();
+ let body_text = &request[header_end + 4..];
+ let body: serde_json::Value =
+ serde_json::from_str(body_text).unwrap_or(serde_json::Value::Null);
+ tx.send(StubRequest {
+ request_line,
+ headers,
+ body,
+ })
+ .expect("send captured request");
+ let payload = serde_json::to_string(&response.1).expect("serialize stub response");
+ let status = response.0;
+ let reply = format!(
+ "HTTP/1.1 {status}\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{payload}",
+ payload.len()
+ );
+ stream
+ .write_all(reply.as_bytes())
+ .expect("write stub response");
+ }
+ });
+ (format!("http://{addr}"), rx)
+}
+
+fn content_length(header_text: &str) -> Option<usize> {
+ for line in header_text.lines() {
+ if let Some((name, value)) = line.split_once(':') {
+ if name.trim().eq_ignore_ascii_case("content-length") {
+ return value.trim().parse().ok();
+ }
+ }
+ }
+ None
+}
+
+fn header<'a>(headers: &'a [(String, String)], name: &str) -> Option<&'a str> {
+ headers
+ .iter()
+ .find(|(candidate, _)| candidate == name)
+ .map(|(_, value)| value.as_str())
+}
diff --git a/crates/pa-telemetry/tests/posthog_wire.rs b/crates/pa-telemetry/tests/posthog_wire.rs
deleted file mode 100644
index d1990a69b2..0000000000
--- a/crates/pa-telemetry/tests/posthog_wire.rs
+++ /dev/null
@@ -1,226 +0,0 @@
-//! Wire-shape tests for the `PostHog` sink and flags client against a local
-//! HTTP stub: batch endpoint path/body/headers, decide body, and the
-//! offline-safe drop policy.
-
-use std::io::{Read, Write};
-use std::net::TcpListener;
-use std::sync::mpsc;
-
-use pa_telemetry::{
- FlagsClient, PostHogEndpoint, PostHogSink, Properties, SinkOutcome, TelemetryEvent,
- TelemetrySink, VERSION,
-};
-
-/// One request captured by the stub.
-struct StubRequest {
- request_line: String,
- headers: Vec<(String, String)>,
- body: serde_json::Value,
-}
-
-/// Serve `responses` (status, raw HTTP body) one per connection, capture each
-/// request, and stop. Returns (`base_url`, receiver).
-fn spawn_stub(responses: Vec<(u16, serde_json::Value)>) -> (String, mpsc::Receiver<StubRequest>) {
- let listener = TcpListener::bind("127.0.0.1:0").expect("bind stub");
- let addr = listener.local_addr().expect("stub addr");
- let (tx, rx) = mpsc::channel();
- std::thread::spawn(move || {
- for response in responses {
- let (mut stream, _) = listener.accept().expect("accept");
- // 64 KiB read buffer on a dedicated stub thread is fine for a test.
- #[allow(clippy::large_stack_arrays)]
- let mut buffer = [0u8; 64 * 1024];
- let mut read_total = 0usize;
- let mut request = String::new();
- loop {
- let n = stream
- .read(&mut buffer[read_total..])
- .expect("read request");
- if n == 0 {
- break;
- }
- read_total += n;
- request.push_str(&String::from_utf8_lossy(&buffer[..n]));
- let header_end = request.find("\r\n\r\n").expect("headers terminator");
- if let Some(len) = content_length(&request[..header_end]) {
- let body_start = header_end + 4;
- if request.len() - body_start >= len {
- break;
- }
- }
- }
- let header_end = request.find("\r\n\r\n").expect("headers terminator");
- let header_text = &request[..header_end];
- let request_line = header_text.lines().next().unwrap_or_default().to_string();
- let headers: Vec<(String, String)> = header_text
- .lines()
- .skip(1)
- .filter_map(|line| line.split_once(':'))
- .map(|(name, value)| (name.trim().to_ascii_lowercase(), value.trim().to_string()))
- .collect();
- let body_text = &request[header_end + 4..];
- let body: serde_json::Value =
- serde_json::from_str(body_text).unwrap_or(serde_json::Value::Null);
- tx.send(StubRequest {
- request_line,
- headers,
- body,
- })
- .expect("send captured request");
- let payload = serde_json::to_string(&response.1).expect("serialize stub response");
- let status = response.0;
- let reply = format!(
- "HTTP/1.1 {status}\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{payload}",
- payload.len()
- );
- stream
- .write_all(reply.as_bytes())
- .expect("write stub response");
- }
- });
- (format!("http://{addr}"), rx)
-}
-
-fn content_length(header_text: &str) -> Option<usize> {
- for line in header_text.lines() {
- if let Some((name, value)) = line.split_once(':') {
- if name.trim().eq_ignore_ascii_case("content-length") {
- return value.trim().parse().ok();
- }
- }
- }
- None
-}
-
-fn header<'a>(headers: &'a [(String, String)], name: &str) -> Option<&'a str> {
- headers
- .iter()
- .find(|(candidate, _)| candidate == name)
- .map(|(_, value)| value.as_str())
-}
-
-fn event(name: &str) -> TelemetryEvent {
- let mut properties = Properties::new();
- properties.set("version", serde_json::Value::from("9.9.9"));
- properties.set("outcome", serde_json::Value::from("success"));
- TelemetryEvent::new(name, properties)
-}
-
-#[tokio::test]
-async fn batch_hits_capture_endpoint_with_documented_wire_shape() {
- let (base, rx) = spawn_stub(vec![(200, serde_json::json!({ "status": 1 }))]);
- let endpoint = PostHogEndpoint::new(&base, "phc-test-key");
- let sink = PostHogSink::new(&endpoint);
- let outcome = sink
- .send_batch(
- "install-1",
- vec![event("agent started"), event("tool executed")],
- )
- .await;
- assert_eq!(outcome, SinkOutcome::Sent);
- let request = rx.recv().expect("stub captured request");
- assert!(request.request_line.starts_with("POST /batch/ "));
- assert_eq!(
- header(&request.headers, "user-agent"),
- Some(format!("prime-agent/{VERSION}").as_str())
- );
- assert_eq!(
- header(&request.headers, "content-type"),
- Some("application/json")
- );
- assert_eq!(request.body["api_key"], "phc-test-key");
- let batch = request.body["batch"].as_array().expect("batch array");
- assert_eq!(batch.len(), 2);
- assert_eq!(batch[0]["event"], "agent started");
- assert_eq!(batch[0]["distinct_id"], "install-1");
- assert_eq!(batch[0]["properties"]["version"], "9.9.9");
- assert_eq!(batch[0]["properties"]["outcome"], "success");
- assert!(batch[0]["timestamp"]
- .as_str()
- .expect("timestamp")
- .ends_with('Z'));
-}
-
-#[tokio::test]
-async fn non_success_status_drops_the_batch() {
- let (base, rx) = spawn_stub(vec![(500, serde_json::json!({ "status": 0 }))]);
- let endpoint = PostHogEndpoint::new(&base, "phc-test-key");
- let sink = PostHogSink::new(&endpoint);
- let outcome = sink
- .send_batch("install-1", vec![event("agent started")])
- .await;
- assert_eq!(outcome, SinkOutcome::Dropped);
- let _ = rx.recv().expect("stub captured request");
-}
-
-#[tokio::test]
-async fn a_401_is_terminal_for_the_batch_sink() {
- // The stub answers 401 once; the sink must never request again.
- let (base, rx) = spawn_stub(vec![(
- 401,
- serde_json::json!({ "error": "Missing scope required: ingestion" }),
- )]);
- let endpoint = PostHogEndpoint::new(&base, "phc-test-key");
- let sink = PostHogSink::new(&endpoint);
- assert_eq!(
- sink.send_batch("install-1", vec![event("agent started")])
- .await,
- SinkOutcome::Dropped
- );
- let _ = rx.recv().expect("stub captured the rejected request");
- // The clone shares the terminal latch: later batches drop without
- // a request (no 401-per-flush retry loop for bad credentials).
- let shared = sink.clone();
- assert_eq!(
- shared
- .send_batch("install-1", vec![event("agent run completed")])
- .await,
- SinkOutcome::Dropped
- );
- assert!(rx.try_recv().is_err(), "no second request hit the stub");
-}
-
-#[tokio::test]
-async fn flags_client_decides_with_distinct_id() {
- let (base, rx) = spawn_stub(vec![(
- 200,
- serde_json::json!({
- "featureFlags": {
- "new_engine": true,
- "legacy_mode": false,
- "variant": "control"
- }
- }),
- )]);
- let endpoint = PostHogEndpoint::new(&base, "phc-test-key");
- let flags = FlagsClient::new(&endpoint, "install-1");
- // First call refetches (cache empty), then serves the flag.
- assert!(flags.flag_enabled("new_engine", false).await);
- assert!(!flags.flag_enabled("legacy_mode", true).await);
- assert!(flags.flag_enabled("variant", false).await);
- assert!(!flags.flag_enabled("absent", false).await);
- let request = rx.recv().expect("stub captured decide request");
- assert!(request.request_line.starts_with("POST /decide/?v=3 "));
- assert_eq!(request.body["api_key"], "phc-test-key");
- assert_eq!(request.body["distinct_id"], "install-1");
- // Cache is now warm: a second lookup must not hit the stub again.
- assert!(flags.flag_enabled("new_engine", false).await);
-}
-
-#[tokio::test]
-async fn a_401_is_terminal_for_the_flags_client() {
- // The decide endpoint answers 401 (missing scope): the client stops
- // polling instead of re-asking every TTL.
- let (base, rx) = spawn_stub(vec![(
- 401,
- serde_json::json!({ "error": "Missing scope required: decide" }),
- )]);
- let endpoint = PostHogEndpoint::new(&base, "phc-test-key");
- let flags = FlagsClient::new(&endpoint, "install-1");
- assert!(!flags.flag_enabled("new_engine", false).await);
- let _ = rx.recv().expect("stub captured the rejected decide");
- // The later lookups serve the configured default without a request.
- assert!(!flags.flag_enabled("legacy_mode", false).await);
- assert!(flags.flag_enabled("other", true).await);
- assert!(rx.try_recv().is_err(), "no second decide hit the stub");
-}
diff --git a/crates/pa-tui/src/client_settings.rs b/crates/pa-tui/src/client_settings.rs
index 26a91f4744..47bc14b9ef 100644
--- a/crates/pa-tui/src/client_settings.rs
+++ b/crates/pa-tui/src/client_settings.rs
@@ -197,4 +197,34 @@ pub trait ClientSettings: Send + Sync {
/// composition root resolves it (a preferred channel wins, else the
/// version's prerelease infers).
fn effective_update_channel(&self, version: &str) -> String;
+ /// The `/telemetry status` report: on or off and why, the endpoint,
+ /// and the installation id.
+ fn telemetry_status(&self) -> String;
+ /// Persists `telemetry.enabled` (the TS key) and returns the report
+ /// after the write (it names an environment variable or project
+ /// setting that still decides).
+ ///
+ /// # Errors
+ ///
+ /// Returns `Err` when opening or persisting the settings
+ /// store fails.
+ fn set_telemetry_enabled(&self, enabled: bool) -> Result<String>;
+ /// Whether the first-run telemetry disclosure is due in this
+ /// interactive view (TS agent-session-services: telemetry enabled,
+ /// onboarding already shown, notice not yet shown). Defaults to
+ /// false: a client without the disclosure surface never shows it.
+ #[must_use]
+ fn telemetry_notice_due(&self) -> bool {
+ false
+ }
+ /// Persist the notice-shown marker once the disclosure renders
+ /// (TS `setTelemetryNoticeShown`).
+ ///
+ /// # Errors
+ ///
+ /// Returns `Err` when opening or persisting the settings
+ /// store fails.
+ fn set_telemetry_notice_shown(&self) -> Result<()> {
+ Ok(())
+ }
}
diff --git a/crates/pa-tui/src/interactive.rs b/crates/pa-tui/src/interactive.rs
index 6f90e78a7c..d958d17fc9 100644
--- a/crates/pa-tui/src/interactive.rs
+++ b/crates/pa-tui/src/interactive.rs
@@ -116,7 +116,7 @@ pub enum SessionSelection {
}
/// Cap on the exit-path telemetry flush (the `tui exit` event's bound):
-/// the `PostHog` sink alone allows up to 1.5s, so an exit-path event is
+/// the analytics sink alone allows up to 1.5s, so an exit-path event is
/// dropped rather than awaited past the exit-within-1s contract. The
/// interactive loop and the composition root's exit paths share this one
/// bound.
@@ -136,9 +136,9 @@ pub struct ModelSelection {
pub thinking: Option<pa_types::ai::ModelThinkingLevel>,
}
-/// Adoption telemetry for interactive-view interactions (schema v1 events
-/// `tui scroll used`, `tui selection used`, and `tui exit`). pa-tui stays
-/// pa-types-only, so the
+/// Adoption telemetry for interactive-view interactions: the composition
+/// root counts them and reports the counters with `tui exit` (plus `agent
+/// command used` per command). pa-tui stays pa-types-only, so the
/// composition root implements this against the telemetry client.
/// The seam is object-safe (held as `Arc<dyn InteractionTelemetry>` in the
/// options and session UI), so the async methods return boxed futures with an
@@ -158,12 +158,12 @@ pub trait InteractionTelemetry: Send + Sync {
/// `surface` is `transcript` (a card expand click) / `editor` (a
/// prompt-bar caret placement) / `picker` (a menu row select).
fn click_used(&self, surface: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>>;
- /// A builtin client command was submitted (`agent command used`):
- /// `command` is the canonical name (`model`, `effort`, ...). Session
- /// commands report through the session telemetry instead.
+ /// A builtin command was submitted (`agent command used`): `command`
+ /// is the canonical name (`model`, `compact`, ...), client and session
+ /// commands alike (TS `captureAgentCommandUsed`).
fn command_used(&self, command: &'static str) -> Pin<Box<dyn Future<Output = ()> + Send + '_>>;
- /// A user-visible feature attempt's observed outcome (#2117
- /// `agent feature outcome`): `feature` is the fixed feature name
+ /// A user-visible feature attempt's observed outcome (the
+ /// `feature_<name>_<outcome>_count` counters): `feature` is the fixed feature name
/// (`model`, `effort`, `new`, `resume`, `fork`, `clone`, `tree`,
/// `login`, `logout`, `goal`, ...), `outcome` the #2117 vocabulary
/// (`initiated` for an open-picker dispatch, `completed`/`failed`/
@@ -175,7 +175,7 @@ pub trait InteractionTelemetry: Send + Sync {
outcome: &'static str,
duration_ms: Option<u64>,
) -> Pin<Box<dyn Future<Output = ()> + Send + '_>>;
- /// One input lifecycle observation (#2117 `agent input stage`): the
+ /// One input lifecycle observation (the `input_<stage>_*` counters): the
/// submission's id (a fresh uuid per submit) and the observed stage
/// (`queued` / `dispatch` / `rejected`), with the duration since the
/// submit was accepted.
@@ -465,7 +465,13 @@ impl InteractiveOptions {
/// `AgentsViewModeOptions.config`).
#[must_use]
pub fn create_config(&self) -> Value {
- let mut config = json!({ "cwd": self.cwd.display().to_string() });
+ // `executionMode` is the telemetry execution mode the daemon
+ // worker stamps on the session's events (TS main.ts
+ // `executionMode: appMode`).
+ let mut config = json!({
+ "cwd": self.cwd.display().to_string(),
+ "executionMode": "interactive",
+ });
if let Some(session_dir) = &self.session_dir {
config["sessionDir"] = json!(session_dir.display().to_string());
}
diff --git a/crates/pa-tui/src/interactive/onboarding.rs b/crates/pa-tui/src/interactive/onboarding.rs
index 86f2f76021..aa4eba3d96 100644
--- a/crates/pa-tui/src/interactive/onboarding.rs
+++ b/crates/pa-tui/src/interactive/onboarding.rs
@@ -3,8 +3,8 @@
//! screens, and the phase that runs the flow before the session screen.
use super::{
- mpsc, AgentView, Duration, ExitGuard, Instant, KeybindingsManager, Renderer, Result, SessionUi,
- UiInput,
+ mpsc, AgentView, Duration, ExitGuard, Future, Instant, KeybindingsManager, Pin, Renderer,
+ Result, SessionUi, UiInput,
};
/// Persistence for the first-run onboarding answers. The TUI crate owns
@@ -37,6 +37,15 @@ pub trait OnboardingSink: Send + Sync {
///
/// Returns `Err` when persisting the completion marker fails.
fn mark_onboarding_complete(&self) -> anyhow::Result<()>;
+ /// The flow ran but did not complete (TS `runStartupOnboarding`'s
+ /// `finally`): `outcome` is `aborted` (cancelled, quit, or no usable
+ /// model at the end) or `error` (the flow failed). Resolves once the
+ /// report is delivered (or dropped), so a quit right after cannot
+ /// tear the runtime down under it.
+ fn onboarding_incomplete(
+ &self,
+ outcome: &'static str,
+ ) -> Pin<Box<dyn Future<Output = ()> + Send + '_>>;
}
/// The model-readiness probe (TS `isOnboardingModelReady` over
@@ -379,6 +388,23 @@ pub(super) async fn run_onboarding_phase(
if task.sink.onboarding_shown() {
return Ok(false);
}
+ let result = run_onboarding_flow(task, session, view, drive).await;
+ // Only a completed flow sets the marker; every other ending reports
+ // its outcome (TS `onboarding completed` with `aborted` / `error`).
+ if !task.sink.onboarding_shown() {
+ task.sink
+ .onboarding_incomplete(if result.is_err() { "error" } else { "aborted" })
+ .await;
+ }
+ result
+}
+
+async fn run_onboarding_flow(
+ task: &OnboardingTask,
+ session: &mut SessionUi,
+ view: &mut AgentView,
+ drive: &mut PaneDrive<'_>,
+) -> Result<bool> {
if (task.model_ready)() {
// The ready branch's standing-choice gate (the operator ruling): a
// home that already carries a trace-sharing choice (a provisioned
diff --git a/crates/pa-tui/src/interactive/run.rs b/crates/pa-tui/src/interactive/run.rs
index bde5f0d843..c774c488d3 100644
--- a/crates/pa-tui/src/interactive/run.rs
+++ b/crates/pa-tui/src/interactive/run.rs
@@ -528,6 +528,11 @@ async fn run_interactive_surface(
)
.await;
}
+ // The once-per-installation telemetry disclosure (TS
+ // agent-session-services): rendered as an info row here — the alt
+ // screen hides any pre-TUI stderr print, so the row is the only
+ // shape the user actually sees.
+ session.maybe_show_telemetry_notice(&mut view);
// TS `restorePromptStashOnOpen`: a draft stashed on the way out (a
// previous chat view of this session left via the agents view or a
// switch) returns to the editor when its chat reopens.
diff --git a/crates/pa-tui/src/interactive/tests.rs b/crates/pa-tui/src/interactive/tests.rs
index 666157f8bf..56fb821aae 100644
--- a/crates/pa-tui/src/interactive/tests.rs
+++ b/crates/pa-tui/src/interactive/tests.rs
@@ -147,6 +147,15 @@ fn create_config_carries_the_requested_thinking_level() {
assert_eq!(config["thinking"], "max");
}
+/// The daemon worker stamps the client's mode on the session's telemetry
+/// (TS `executionMode: appMode`): interactive sessions report
+/// `interactive`, never the worker's own `daemon` context.
+#[test]
+fn create_config_names_the_interactive_execution_mode() {
+ let config = options(ModelSelection::default()).create_config();
+ assert_eq!(config["executionMode"], "interactive");
+}
+
#[test]
fn create_config_omits_thinking_when_no_flag_was_given() {
let config = options(ModelSelection::default()).create_config();
@@ -164,6 +173,7 @@ fn create_config_binds_a_new_child_to_its_parent() {
opts.create_config(),
json!({
"cwd": "/tmp",
+ "executionMode": "interactive",
"parentSessionPath": "/x/p.jsonl",
"rlmDepth": 2
})
diff --git a/crates/pa-tui/src/session_ui.rs b/crates/pa-tui/src/session_ui.rs
index 9fda4296fa..f2d6230226 100644
--- a/crates/pa-tui/src/session_ui.rs
+++ b/crates/pa-tui/src/session_ui.rs
@@ -471,8 +471,7 @@ pub(crate) struct SessionUi {
/// A succeeded compaction replaced the durable transcript (TS
/// `rebuildChatFromMessages`): the next loop pass re-fetches it.
pub(crate) transcript_stale: bool,
- /// Adoption telemetry (`tui scroll used` / `tui exit`); `None` drops
- /// events.
+ /// Adoption telemetry (counted into `tui exit`); `None` drops events.
pub(crate) telemetry: Option<std::sync::Arc<dyn crate::interactive::InteractionTelemetry>>,
/// Whether this run already reported its first scroll action.
scroll_adoption_emitted: bool,
diff --git a/crates/pa-tui/src/session_ui/apply.rs b/crates/pa-tui/src/session_ui/apply.rs
index bac65ff11b..9c7947221c 100644
--- a/crates/pa-tui/src/session_ui/apply.rs
+++ b/crates/pa-tui/src/session_ui/apply.rs
@@ -170,7 +170,7 @@ impl SessionUi {
self.dirty = true;
}
- /// Report the first scroll action of the run (`tui scroll used`),
+ /// Report the first scroll action of the run (`tui_scroll_count`),
/// fire-and-forget so the keypress never waits on the telemetry flush.
pub(super) fn track_scroll(&mut self, action: &'static str, resumed_following: bool) {
if self.scroll_adoption_emitted {
@@ -244,7 +244,7 @@ impl SessionUi {
}
}
- /// Report a builtin client-command submission (`agent command used`),
+ /// Report a builtin command submission (`agent command used`),
/// fire-and-forget like the scroll event: the command's handling never
/// waits on the telemetry flush.
pub(super) fn track_command_used(&mut self, command: &'static str) {
diff --git a/crates/pa-tui/src/session_ui/auth.rs b/crates/pa-tui/src/session_ui/auth.rs
index 06be602b8b..bbad593d12 100644
--- a/crates/pa-tui/src/session_ui/auth.rs
+++ b/crates/pa-tui/src/session_ui/auth.rs
@@ -400,7 +400,6 @@ impl SessionUi {
resolved: &pa_types::slash_commands::ResolvedSlashCommand,
view: &mut AgentView,
) -> Result<()> {
- self.track_command_used("mcp");
// `/mcp` is menu-only: the TS `handleMcpCommand` typed subcommands
// (login/logout/...) are deliberately removed — the connections
// view resolves its own auth internally, and a submitted argument
diff --git a/crates/pa-tui/src/session_ui/commands.rs b/crates/pa-tui/src/session_ui/commands.rs
index 09366bac61..f84b497d5e 100644
--- a/crates/pa-tui/src/session_ui/commands.rs
+++ b/crates/pa-tui/src/session_ui/commands.rs
@@ -105,6 +105,10 @@ impl SessionUi {
let command = registry
.get(resolved.name)
.expect("resolved name is builtin");
+ // `agent command used` (TS `captureAgentCommandUsed`): one report
+ // per submitted builtin, client and session commands alike, by its
+ // canonical name, before the command runs.
+ self.track_command_used(resolved.name);
match command.execution {
SlashCommandExecution::Session => self.send_prompt(text, behavior, view),
SlashCommandExecution::Client => {
@@ -190,7 +194,6 @@ impl SessionUi {
// removed; a partial + Tab opens the picker filtered instead,
// and a submitted argument is the usage error).
"model" => {
- self.track_command_used("model");
if !resolved.args.trim().is_empty() {
view.editor
.set_text(&format!("/{} {}", resolved.original_name, resolved.args));
@@ -206,7 +209,6 @@ impl SessionUi {
// without reasoning reports the TS note, a missing argument
// opens the picker, and a valid argument applies directly.
"effort" => {
- self.track_command_used("effort");
let Some(state) = self.connection_state(view).await else {
return Ok(());
};
@@ -259,7 +261,6 @@ impl SessionUi {
// `/tree` (TS `showTreeSelector`): the session-tree navigator.
"tree" => {
if resolved.args.is_empty() {
- self.track_command_used("tree");
self.track_feature_outcome("tree", "initiated", None);
self.open_tree_selector(view, None).await?;
} else {
@@ -270,7 +271,6 @@ impl SessionUi {
// message into a new session.
"fork" => {
if resolved.args.is_empty() {
- self.track_command_used("fork");
self.track_feature_outcome("fork", "initiated", None);
self.open_fork_selector(view).await?;
} else {
@@ -281,7 +281,6 @@ impl SessionUi {
// the current position.
"clone" => {
if resolved.args.is_empty() {
- self.track_command_used("clone");
self.track_feature_outcome("clone", "initiated", None);
self.handle_clone_command(view).await?;
} else {
@@ -294,7 +293,6 @@ impl SessionUi {
// the usage error with the text kept in the editor.
"copy" => {
if resolved.args.is_empty() {
- self.track_command_used("copy");
self.handle_copy_command(view).await?;
} else {
view.editor
@@ -308,7 +306,6 @@ impl SessionUi {
// TS `OAuthSelectorComponent` the tab mounts).
"login" => {
if resolved.args.is_empty() {
- self.track_command_used("login");
self.open_provider_auth(AuthSelectorKind::Login, view)
.await?;
self.track_feature_outcome("login", "initiated", None);
@@ -322,7 +319,6 @@ impl SessionUi {
// selector; an empty store answers the TS status directly.
"logout" => {
if resolved.args.is_empty() {
- self.track_command_used("logout");
self.open_provider_auth(AuthSelectorKind::Logout, view)
.await?;
self.track_feature_outcome("logout", "initiated", None);
@@ -336,7 +332,6 @@ impl SessionUi {
// path parses like `/export`'s, then the confirm guards the
// replacement.
"import" => {
- self.track_command_used("import");
let command_text = if resolved.args.is_empty() {
"/import".to_string()
} else {
@@ -349,7 +344,6 @@ impl SessionUi {
// block, the settings writes, and the TS command shapes over
// the upload subsystem this build has.
"traces" => {
- self.track_command_used("traces");
self.handle_traces_command(resolved, view).await?;
}
// `/nightly [on|off|status]` (TS `interactive-mode.ts`
@@ -357,7 +351,6 @@ impl SessionUi {
// bare) and off/stable save the `updateChannel` setting that
// `/update` and `prime-agent update` follow.
"nightly" => {
- self.track_command_used("nightly");
let arg = resolved.args.trim().to_lowercase();
if arg == "status" {
// The effective channel resolves through the
@@ -420,6 +413,28 @@ impl SessionUi {
view,
);
}
+ // `/telemetry [status|on|off]`: the report (on/off and why, the
+ // endpoint, the installation id), or the persisted switch the
+ // running telemetry clients re-read at their next send.
+ "telemetry" => {
+ let Some(settings) = &self.client_settings else {
+ self.note("/telemetry is not available in this client yet", view);
+ return Ok(());
+ };
+ let report = match resolved.args.trim().to_lowercase().as_str() {
+ "" | "status" => Ok(settings.telemetry_status()),
+ "on" => settings.set_telemetry_enabled(true),
+ "off" => settings.set_telemetry_enabled(false),
+ _ => {
+ self.error_row("Usage: /telemetry [status|on|off]", view);
+ return Ok(());
+ }
+ };
+ match report {
+ Ok(report) => self.note(&report, view),
+ Err(error) => self.error_row(&format!("{error:#}"), view),
+ }
+ }
// `/update` (the TS->Rust migration path): the confirm, then
// the download+install runs OUT-OF-BAND (a background task —
// the TUI stays mounted, the daemon keeps running, and the
@@ -431,7 +446,6 @@ impl SessionUi {
// sessions and configuration (~/.prime/agent) are never
// touched.
"update" => {
- self.track_command_used("update");
if !resolved.args.trim().is_empty() {
view.editor.set_text(text);
self.error_row("Usage: /update", view);
@@ -467,7 +481,6 @@ impl SessionUi {
// surfaces), so the command opens that view; an argument
// prefills its search field like TS's initial search.
"plugins" => {
- self.track_command_used("plugins");
self.open_mcp_view("/plugins", view, "").await?;
let search = resolved.args.trim();
if !search.is_empty() {
@@ -480,7 +493,6 @@ impl SessionUi {
// the current branch; anything else (including no argument)
// exports HTML.
"export" => {
- self.track_command_used("export");
self.handle_export_command(resolved, view).await?;
}
// TS `handleShareCommand`: an argument is the usage error (the
@@ -488,7 +500,6 @@ impl SessionUi {
// temp file and uploads as a secret gist.
"share" => {
if resolved.args.is_empty() {
- self.track_command_used("share");
self.handle_share_command(view).await?;
} else {
view.editor
@@ -503,7 +514,6 @@ impl SessionUi {
// `keybindings.json` overrides show their keys. Client-side
// rows only, never durable session entries.
"hotkeys" => {
- self.track_command_used("hotkeys");
if !resolved.args.is_empty() {
// TS keeps the text in the editor on the usage error.
view.editor
@@ -528,7 +538,6 @@ impl SessionUi {
// read-only info panel (the operator's 2026-09-26
// directive), not as transcript rows.
"session" => {
- self.track_command_used("session");
if !resolved.args.is_empty() {
view.editor.set_text(text);
self.error_row("Usage: /session", view);
@@ -574,7 +583,6 @@ impl SessionUi {
// collapses to the highest-usage agents plus a summary row
// and the expand hint, and `all` renders the whole tree.
"context" => {
- self.track_command_used("context");
let scope = match resolved.args.as_str() {
"" => info_commands::ContextTreeScope::Collapsed,
"all" => info_commands::ContextTreeScope::EveryAgent,
@@ -620,7 +628,6 @@ impl SessionUi {
// scrollable read-only info panel (the operator's 2026-09-26
// directive) instead of flooding the transcript.
"system-prompt" => {
- self.track_command_used("system-prompt");
if !resolved.args.is_empty() {
view.editor.set_text(text);
self.error_row("Usage: /system-prompt", view);
@@ -660,7 +667,6 @@ impl SessionUi {
// it), rendered in the read-only info panel (the operator's
// 2026-09-26 directive).
"logs" => {
- self.track_command_used("logs");
if !resolved.args.is_empty() {
view.editor.set_text(text);
self.error_row("Usage: /logs", view);
@@ -687,7 +693,6 @@ impl SessionUi {
// panel (the operator's 2026-09-26 directive; the TS accent
// `What's New` title is the panel's title).
"changelog" => {
- self.track_command_used("changelog");
if !resolved.args.is_empty() {
view.editor.set_text(text);
self.error_row("Usage: /changelog", view);
@@ -711,7 +716,6 @@ impl SessionUi {
self.error_row("Usage: /settings", view);
return Ok(());
}
- self.track_command_used("settings");
self.open_settings_menu(view).await;
}
// `/btw` (TS `handleSideQuestion` via the submit ladder; `/side`
@@ -723,7 +727,6 @@ impl SessionUi {
self.note_as("Usage: /btw <question>", StatusKind::Warning, view);
return Ok(());
}
- self.track_command_used("btw");
self.start_side_question(&resolved.args, view).await?;
}
// `/name` (TS `handleNameCommand`; `/rename` resolves to it):
@@ -731,7 +734,6 @@ impl SessionUi {
// rename travels to the daemon (`set_session_name` persists
// the `session_info` entry and broadcasts the change).
"name" => {
- self.track_command_used("name");
let name = resolved.args.trim();
if name.is_empty() {
match &self.session_name {
@@ -765,7 +767,6 @@ impl SessionUi {
// tier on a fast-mode-eligible model; the state refresh after
// the switch drives the status row.
"fast" => {
- self.track_command_used("fast");
if !resolved.args.is_empty() {
self.error_row("Usage: /fast", view);
return Ok(());
@@ -775,13 +776,11 @@ impl SessionUi {
// `/tier [tier]` (TS `handleTierCommand`): show or set the
// session service tier.
"tier" => {
- self.track_command_used("tier");
self.handle_tier_command(view, &resolved.args).await;
}
// `/rlm-max-depth` (TS `handleRlmMaxDepthCommand`): view or set
// the per-chat recursive depth limit.
"rlm-max-depth" => {
- self.track_command_used("rlm-max-depth");
self.handle_rlm_max_depth_command(view, &resolved.args)
.await;
}
@@ -789,7 +788,6 @@ impl SessionUi {
// tok/sec readout for this session — the dim dock row with the
// latest response's rate and the session average.
"speed" => {
- self.track_command_used("speed");
let arg = resolved.args.trim().to_lowercase();
if !arg.is_empty() && arg != "on" && arg != "off" {
self.error_row("Usage: /speed [on|off]", view);
@@ -813,7 +811,6 @@ impl SessionUi {
self.error_row("Usage: /reload", view);
return Ok(());
}
- self.track_command_used("reload");
if self.turn_active || view.working.is_some() || self.work_in_flight() {
self.note_as(
"Wait for the current response to finish before reloading.",
@@ -844,7 +841,6 @@ impl SessionUi {
self.error_row("Usage: /heartbeats", view);
return Ok(());
}
- self.track_command_used("heartbeats");
self.open_heartbeats_view(view);
}
other => {
diff --git a/crates/pa-tui/src/session_ui/notes.rs b/crates/pa-tui/src/session_ui/notes.rs
index 6b6d07024e..f4d2dc22e9 100644
--- a/crates/pa-tui/src/session_ui/notes.rs
+++ b/crates/pa-tui/src/session_ui/notes.rs
@@ -180,6 +180,30 @@ impl SessionUi {
/// would not warn anyway, and it fails OPEN (an absent field from an
/// older daemon, or an unreadable state, draws the warning rather
/// than suppressing it).
+ /// The once-per-installation telemetry disclosure (TS
+ /// agent-session-services): the interactive session renders it as an
+ /// info row — the alt screen hides any pre-TUI stderr print, so the
+ /// row is the only shape the user actually sees — and the shown
+ /// marker persists the moment the row renders (TS
+ /// `setTelemetryNoticeShown`).
+ pub(crate) fn maybe_show_telemetry_notice(&mut self, view: &mut AgentView) {
+ let Some(settings) = self.client_settings.clone() else {
+ return;
+ };
+ if !settings.telemetry_notice_due() {
+ return;
+ }
+ view.push_entry(ChatEntry::Status {
+ // The same disclosure text the print-mode notice carries
+ // (pa-cli `telemetry_notice`), plus the interactive switch.
+ text: "Prime Agent sends pseudonymous usage and performance metrics without prompts, responses, tool content, file paths, or repository data. Disable this with /telemetry off, telemetry.enabled=false, PRIME_AGENT_TELEMETRY=0, DO_NOT_TRACK=1, or offline mode."
+ .to_string(),
+ kind: StatusKind::Info,
+ });
+ let _ = settings.set_telemetry_notice_shown();
+ self.dirty = true;
+ }
+
pub(crate) async fn maybe_warn_anthropic_subscription_auth_if_subscribed(
&mut self,
provider: Option<&str>,
diff --git a/crates/pa-tui/tests/anthropic_warning_lifecycle_headless.rs b/crates/pa-tui/tests/anthropic_warning_lifecycle_headless.rs
index a0c14e64e9..59579e22a9 100644
--- a/crates/pa-tui/tests/anthropic_warning_lifecycle_headless.rs
+++ b/crates/pa-tui/tests/anthropic_warning_lifecycle_headless.rs
@@ -352,6 +352,12 @@ impl pa_tui::client_settings::ClientSettings for StubSettings {
fn set_update_channel(&self, _channel: &str) -> Result<()> {
Ok(())
}
+ fn telemetry_status(&self) -> String {
+ String::new()
+ }
+ fn set_telemetry_enabled(&self, _enabled: bool) -> Result<String> {
+ Ok(String::new())
+ }
fn effective_update_channel(&self, version: &str) -> String {
if version.contains("-beta") {
"nightly".to_string()
diff --git a/crates/pa-tui/tests/chat_detail_persist_headless.rs b/crates/pa-tui/tests/chat_detail_persist_headless.rs
index 7e16d179db..51a963894a 100644
--- a/crates/pa-tui/tests/chat_detail_persist_headless.rs
+++ b/crates/pa-tui/tests/chat_detail_persist_headless.rs
@@ -314,6 +314,12 @@ impl pa_tui::client_settings::ClientSettings for StubSettings {
fn set_update_channel(&self, _channel: &str) -> Result<()> {
Ok(())
}
+ fn telemetry_status(&self) -> String {
+ String::new()
+ }
+ fn set_telemetry_enabled(&self, _enabled: bool) -> Result<String> {
+ Ok(String::new())
+ }
fn effective_update_channel(&self, version: &str) -> String {
if version.contains("-beta") {
"nightly".to_string()
diff --git a/crates/pa-tui/tests/esc_repeat_ladder_headless.rs b/crates/pa-tui/tests/esc_repeat_ladder_headless.rs
index ae37ca7be5..d7d7c02194 100644
--- a/crates/pa-tui/tests/esc_repeat_ladder_headless.rs
+++ b/crates/pa-tui/tests/esc_repeat_ladder_headless.rs
@@ -367,6 +367,12 @@ impl pa_tui::client_settings::ClientSettings for StubSettings {
fn set_update_channel(&self, _channel: &str) -> Result<()> {
Ok(())
}
+ fn telemetry_status(&self) -> String {
+ String::new()
+ }
+ fn set_telemetry_enabled(&self, _enabled: bool) -> Result<String> {
+ Ok(String::new())
+ }
fn effective_update_channel(&self, _version: &str) -> String {
"stable".to_string()
}
diff --git a/crates/pa-tui/tests/nightly_command_headless.rs b/crates/pa-tui/tests/nightly_command_headless.rs
index 6998955ab8..1f60e2c1e5 100644
--- a/crates/pa-tui/tests/nightly_command_headless.rs
+++ b/crates/pa-tui/tests/nightly_command_headless.rs
@@ -316,6 +316,12 @@ impl pa_tui::client_settings::ClientSettings for StubSettings {
*self.update_channel.lock().expect("channel lock") = Some(channel.to_string());
Ok(())
}
+ fn telemetry_status(&self) -> String {
+ String::new()
+ }
+ fn set_telemetry_enabled(&self, _enabled: bool) -> Result<String> {
+ Ok(String::new())
+ }
fn effective_update_channel(&self, version: &str) -> String {
if let Some(channel) = self.update_channel() {
return channel;
diff --git a/crates/pa-tui/tests/settings_menu_headless.rs b/crates/pa-tui/tests/settings_menu_headless.rs
index 52fce61cda..fcbd9920b7 100644
--- a/crates/pa-tui/tests/settings_menu_headless.rs
+++ b/crates/pa-tui/tests/settings_menu_headless.rs
@@ -374,6 +374,12 @@ impl pa_tui::client_settings::ClientSettings for RecordingSettings {
fn set_update_channel(&self, _channel: &str) -> Result<()> {
Ok(())
}
+ fn telemetry_status(&self) -> String {
+ String::new()
+ }
+ fn set_telemetry_enabled(&self, _enabled: bool) -> Result<String> {
+ Ok(String::new())
+ }
fn effective_update_channel(&self, version: &str) -> String {
if version.contains("-beta") {
"nightly".to_string()
diff --git a/crates/pa-tui/tests/skills_menu_headless.rs b/crates/pa-tui/tests/skills_menu_headless.rs
index 64a71e47e8..9bb01e2896 100644
--- a/crates/pa-tui/tests/skills_menu_headless.rs
+++ b/crates/pa-tui/tests/skills_menu_headless.rs
@@ -411,6 +411,12 @@ impl pa_tui::client_settings::ClientSettings for StubSettings {
fn set_update_channel(&self, _channel: &str) -> Result<()> {
Ok(())
}
+ fn telemetry_status(&self) -> String {
+ String::new()
+ }
+ fn set_telemetry_enabled(&self, _enabled: bool) -> Result<String> {
+ Ok(String::new())
+ }
fn effective_update_channel(&self, version: &str) -> String {
if version.contains("-beta") {
"nightly".to_string()
diff --git a/crates/pa-tui/tests/telemetry_command_headless.rs b/crates/pa-tui/tests/telemetry_command_headless.rs
new file mode 100644
index 0000000000..cde1cb549c
--- /dev/null
+++ b/crates/pa-tui/tests/telemetry_command_headless.rs
@@ -0,0 +1,535 @@
+//! Headless e2e for the `/telemetry` command: bare and `status` render the
+//! seam's report, `on`/`off` persist through the settings seam and render
+//! the report after the write (including the "stays off" answer when an
+//! environment variable forces telemetry off), and a bad argument gets the
+//! usage error. The report text and the settings round-trip are covered by
+//! the pa-core telemetry status tests over the real settings store.
+#![cfg(unix)]
+// Pedantic-gate exceptions (every other pedantic warning in this crate is
+// fixed in place; each exception carries its one-line justification):
+// - the casts: terminal-layout arithmetic narrows structurally bounded
+// values (screen coordinates, byte counts, timestamps); guarded
+// conversions would add panic paths the bounds guarantee away.
+#![allow(
+ clippy::cast_possible_truncation,
+ clippy::cast_possible_wrap,
+ clippy::cast_sign_loss,
+ clippy::cast_precision_loss
+)]
+// - the render routes are flat tables (one arm per route); splitting them
+// would add indirection without changing the flow.
+#![allow(clippy::too_many_lines)]
+// - widget state structs carry independent flag bits; a nested struct
+// would add indirection without changing the shape.
+#![allow(clippy::struct_excessive_bools, clippy::fn_params_excessive_bools)]
+// - the futures are bounded by the surface's lifetime; boxing them would
+// add an allocation to the steady-state loop.
+#![allow(clippy::large_futures)]
+// - the wrappers preserve a uniform Result-returning API surface; unwrap
+// removals would ripple through the callers without changing behavior.
+#![allow(clippy::unnecessary_wraps)]
+
+use std::io::{BufRead, BufReader, Write};
+use std::os::unix::net::{UnixListener, UnixStream};
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use anyhow::Result;
+use pa_tui::interactive::{
+ run_interactive, HeadlessPlan, HeadlessStep, InteractiveOptions, ModelSelection,
+ SessionSelection, UiMode,
+};
+use serde_json::{json, Value};
+
+struct MockSupervisor {
+ listener: UnixListener,
+}
+
+impl MockSupervisor {
+ fn bind(socket: &std::path::Path) -> Self {
+ MockSupervisor {
+ listener: UnixListener::bind(socket).expect("bind mock socket"),
+ }
+ }
+
+ /// Serve one connection: attach an empty session, then answer the
+ /// loop's requests.
+ fn serve(self) {
+ let (stream, _) = self.listener.accept().expect("accept");
+ let write_stream = stream.try_clone().expect("clone mock socket");
+ let mut writer = write_stream;
+ let mut reader = BufReader::new(stream);
+
+ let hello = json!({
+ "type": "daemon_hello",
+ "protocol": { "name": "prime-agent.daemon", "version": 7 },
+ "serverCapabilities": [],
+ "clientId": "mock",
+ });
+ write_json(&mut writer, &hello);
+
+ let mut line = String::new();
+ loop {
+ line.clear();
+ match reader.read_line(&mut line) {
+ Ok(0) | Err(_) => break,
+ Ok(_) => {}
+ }
+ let Ok(envelope) = serde_json::from_str::<Value>(line.trim()) else {
+ continue;
+ };
+ let id = envelope.get("id").and_then(Value::as_str).unwrap_or("");
+ let command = envelope.get("command").cloned().unwrap_or(Value::Null);
+ let command_type = command
+ .get("type")
+ .and_then(Value::as_str)
+ .unwrap_or_default()
+ .to_string();
+ match command_type.as_str() {
+ "create" => {
+ write_json(
+ &mut writer,
+ &json!({
+ "type": "response",
+ "id": id,
+ "command": "create",
+ "success": true,
+ "data": {
+ "activeSessionId": "s1",
+ "id": "s1",
+ "sessionId": "sess-1",
+ "sessionFile": "/tmp/sess-1.jsonl",
+ },
+ }),
+ );
+ }
+ "attach" => {
+ write_json(&mut writer, &attach_data(id));
+ }
+ "get_session_stats" => {
+ write_json(
+ &mut writer,
+ &json!({
+ "type": "response",
+ "id": id,
+ "command": "get_session_stats",
+ "success": true,
+ "data": {
+ "contextUsage": { "tokens": 1200, "contextWindow": 200_000 },
+ "cost": 0.01,
+ },
+ }),
+ );
+ }
+ "detach" => {
+ write_json(
+ &mut writer,
+ &json!({
+ "type": "response",
+ "id": id,
+ "command": "detach",
+ "success": true,
+ }),
+ );
+ }
+ _ => {
+ write_json(
+ &mut writer,
+ &json!({
+ "type": "response",
+ "id": id,
+ "command": command_type,
+ "success": true,
+ "data": {},
+ }),
+ );
+ }
+ }
+ }
+ }
+}
+
+fn write_json(writer: &mut UnixStream, value: &Value) {
+ let mut line = serde_json::to_string(value).expect("serialize mock frame");
+ line.push('\n');
+ writer.write_all(line.as_bytes()).expect("write mock frame");
+ writer.flush().expect("flush mock frame");
+}
+
+/// The slim attach result: one empty session.
+fn attach_data(id: &str) -> Value {
+ json!({
+ "type": "response",
+ "id": id,
+ "command": "attach",
+ "success": true,
+ "data": {
+ "protocol": { "name": "prime-agent.daemon", "version": 7 },
+ "activeSessionId": "s1",
+ "snapshot": {
+ "activeSessionId": "s1",
+ "summary": { "id": "s1", "cwd": "/tmp" },
+ "state": {
+ "activeSessionId": "s1",
+ "cwd": "/tmp",
+ "sessionId": "sess-1",
+ "sessionName": "telemetry session",
+ "model": null,
+ "isStreaming": false,
+ "isCompacting": false,
+ "sessionActions": { "queuedCount": 0, "steering": [], "followUps": [] },
+ },
+ "messages": [],
+ "lastEventSequence": 0,
+ "lastEventCursor": null,
+ },
+ "client": { "id": "mock", "capabilities": [] },
+ "lastEventSequence": 0,
+ "lastEventCursor": null,
+ },
+ })
+}
+
+/// The settings seam stub: the telemetry switch lives in memory, and an
+/// optional environment opt-out mimics `DO_NOT_TRACK`.
+#[derive(Default)]
+struct StubSettings {
+ telemetry_enabled: std::sync::Mutex<Option<bool>>,
+ forced_off_by: Option<&'static str>,
+ notice_due: bool,
+ notice_shown: std::sync::atomic::AtomicBool,
+}
+
+impl StubSettings {
+ fn state(&self) -> (&'static str, String) {
+ if let Some(var) = self.forced_off_by {
+ return ("off", format!("forced off by {var}"));
+ }
+ match *self.telemetry_enabled.lock().expect("telemetry lock") {
+ None => ("on", "on by default".to_string()),
+ Some(true) => ("on", "turned on in settings".to_string()),
+ Some(false) => ("off", "turned off in settings".to_string()),
+ }
+ }
+}
+
+impl pa_tui::client_settings::ClientSettings for StubSettings {
+ fn theme(&self) -> Option<String> {
+ None
+ }
+ fn set_theme(&self, _theme: &str) -> Result<()> {
+ Ok(())
+ }
+ fn show_images(&self) -> bool {
+ true
+ }
+ fn set_show_images(&self, _enabled: bool) -> Result<()> {
+ Ok(())
+ }
+ fn clear_on_shrink(&self) -> bool {
+ false
+ }
+ fn set_clear_on_shrink(&self, _enabled: bool) -> Result<()> {
+ Ok(())
+ }
+ fn show_terminal_progress(&self) -> bool {
+ false
+ }
+ fn set_show_terminal_progress(&self, _enabled: bool) -> Result<()> {
+ Ok(())
+ }
+ fn image_auto_resize(&self) -> bool {
+ true
+ }
+ fn set_image_auto_resize(&self, _enabled: bool) -> Result<()> {
+ Ok(())
+ }
+ fn block_images(&self) -> bool {
+ false
+ }
+ fn set_block_images(&self, _blocked: bool) -> Result<()> {
+ Ok(())
+ }
+ fn image_model(&self) -> Option<String> {
+ None
+ }
+ fn enable_skill_commands(&self) -> bool {
+ true
+ }
+ fn set_enable_skill_commands(&self, _enabled: bool) -> Result<()> {
+ Ok(())
+ }
+ fn enable_builtin_skills(&self) -> bool {
+ true
+ }
+ fn set_enable_builtin_skills(&self, _enabled: bool) -> Result<()> {
+ Ok(())
+ }
+ fn show_hardware_cursor(&self) -> bool {
+ false
+ }
+ fn set_show_hardware_cursor(&self, _enabled: bool) -> Result<()> {
+ Ok(())
+ }
+ fn editor_padding_x(&self) -> u64 {
+ 0
+ }
+ fn set_editor_padding_x(&self, _padding: u64) -> Result<()> {
+ Ok(())
+ }
+ fn autocomplete_max_visible(&self) -> u64 {
+ 5
+ }
+ fn set_autocomplete_max_visible(&self, _max_visible: u64) -> Result<()> {
+ Ok(())
+ }
+ fn quiet_startup(&self) -> bool {
+ false
+ }
+ fn set_quiet_startup(&self, _quiet: bool) -> Result<()> {
+ Ok(())
+ }
+ fn idle_eviction_minutes(&self) -> String {
+ "90".to_string()
+ }
+ fn set_idle_eviction_minutes(&self, _value: &str) -> Result<()> {
+ Ok(())
+ }
+ fn mermaid_rendering_mode(&self) -> String {
+ "streaming".to_string()
+ }
+ fn set_mermaid_rendering_mode(&self, _mode: &str) -> Result<()> {
+ Ok(())
+ }
+ fn tree_filter_mode(&self) -> String {
+ "user-only".to_string()
+ }
+ fn set_tree_filter_mode(&self, _mode: &str) -> Result<()> {
+ Ok(())
+ }
+ fn default_service_tier(&self) -> String {
+ "default".to_string()
+ }
+ fn set_default_service_tier(&self, _tier: &str) -> Result<()> {
+ Ok(())
+ }
+ fn chat_detail(&self) -> String {
+ "details".to_string()
+ }
+ fn set_chat_detail(&self, _detail: &str) -> Result<()> {
+ Ok(())
+ }
+ fn warnings_anthropic_extra_usage(&self) -> bool {
+ true
+ }
+ fn set_warnings_anthropic_extra_usage(&self, _enabled: bool) -> Result<()> {
+ Ok(())
+ }
+ fn update_channel(&self) -> Option<String> {
+ None
+ }
+ fn set_update_channel(&self, _channel: &str) -> Result<()> {
+ Ok(())
+ }
+ fn telemetry_status(&self) -> String {
+ let (state, reason) = self.state();
+ format!("Telemetry is {state} ({reason}).\nInstallation id: stub-id")
+ }
+ fn set_telemetry_enabled(&self, enabled: bool) -> Result<String> {
+ *self.telemetry_enabled.lock().expect("telemetry lock") = Some(enabled);
+ let headline = if self.forced_off_by.is_some() && enabled {
+ "Saved telemetry on in settings, but it stays off."
+ } else if enabled {
+ "Telemetry turned on."
+ } else {
+ "Telemetry turned off."
+ };
+ Ok(format!("{headline}\n{}", self.telemetry_status()))
+ }
+ fn effective_update_channel(&self, _version: &str) -> String {
+ "stable".to_string()
+ }
+ fn telemetry_notice_due(&self) -> bool {
+ // Like the real funnel: a due notice stops being due once the
+ // marker persists.
+ self.notice_due && !self.notice_shown.load(std::sync::atomic::Ordering::Relaxed)
+ }
+ fn set_telemetry_notice_shown(&self) -> Result<()> {
+ self.notice_shown
+ .store(true, std::sync::atomic::Ordering::Relaxed);
+ Ok(())
+ }
+}
+
+fn options(socket: PathBuf, settings: Arc<StubSettings>) -> InteractiveOptions {
+ InteractiveOptions {
+ models: None,
+ socket_path: socket,
+ cwd: PathBuf::from("/tmp"),
+ session_dir: None,
+ script_path: None,
+ model_selection: ModelSelection::default(),
+ model_catalog: Vec::new(),
+ model_configured_providers: std::collections::HashSet::default(),
+ model_recent_models: Vec::new(),
+ default_thinking_level: None,
+ no_session: false,
+ session: SessionSelection::New,
+ initial_message: None,
+ show_images: true,
+ fullscreen_mouse: true,
+ theme: "prime".to_string(),
+ code_block_indent: " ".to_string(),
+ tree_filter_mode: String::new(),
+ branch_summary_skip_prompt: false,
+ version: "0.0.0".to_string(),
+ onboarding: None,
+ telemetry_disabled: None,
+ client_auth: None,
+ traces: None,
+ provider_auth: None,
+ update_commands: None,
+ telemetry: None,
+ keybindings: pa_tui::keybindings::KeybindingsManager::new(),
+ session_rlm_depth: None,
+ prompt_stash: std::sync::Arc::default(),
+ session_has_children: false,
+ restore_dock_focus: false,
+ client_settings: Some(settings),
+ }
+}
+
+fn run_plan(settings: Arc<StubSettings>, steps: Vec<HeadlessStep>) -> Vec<String> {
+ std::env::remove_var("TMUX");
+ let dir = tempfile::TempDir::new().expect("temp dir");
+ let socket = dir.path().join("tui.sock");
+ let supervisor = MockSupervisor::bind(&socket);
+ let handle = std::thread::spawn(move || supervisor.serve());
+
+ let runtime = tokio::runtime::Builder::new_multi_thread()
+ .enable_all()
+ .build()
+ .expect("tokio runtime");
+ let plan = HeadlessPlan {
+ steps,
+ width: 100,
+ height: 30,
+ };
+ let outcome = runtime
+ .block_on(run_interactive(
+ options(socket, settings),
+ UiMode::Headless(plan),
+ ))
+ .expect("interactive run");
+ handle.join().expect("mock supervisor finished");
+ outcome.frames
+}
+
+fn submit(text: &str) -> Vec<HeadlessStep> {
+ vec![
+ HeadlessStep::Submit(text.to_string()),
+ HeadlessStep::WaitMs(200),
+ ]
+}
+
+/// Bare `/telemetry` and `/telemetry status` render the report; a bad
+/// argument gets the usage error.
+#[test]
+fn telemetry_status_renders_the_report() {
+ let settings = Arc::new(StubSettings::default());
+ let mut steps = submit("/telemetry");
+ steps.extend(submit("/telemetry status"));
+ steps.extend(submit("/telemetry maybe"));
+ let all = run_plan(Arc::clone(&settings), steps).join("\n");
+ assert!(
+ all.matches("Telemetry is on (on by default).").count() >= 2,
+ "bare and status both report:\n{all}"
+ );
+ assert!(all.contains("Installation id: stub-id"), "{all}");
+ assert!(
+ all.contains("Usage: /telemetry [status|on|off]"),
+ "the usage error rendered:\n{all}"
+ );
+}
+
+/// `/telemetry off` then `/telemetry on` persist through the seam.
+#[test]
+fn telemetry_off_and_on_persist_the_switch() {
+ let settings = Arc::new(StubSettings::default());
+ let steps = submit("/telemetry off");
+ let all = run_plan(Arc::clone(&settings), steps).join("\n");
+ assert!(all.contains("Telemetry turned off."), "{all}");
+ assert!(
+ all.contains("Telemetry is off (turned off in settings)."),
+ "{all}"
+ );
+ assert_eq!(*settings.telemetry_enabled.lock().unwrap(), Some(false));
+
+ let all = run_plan(Arc::clone(&settings), submit("/telemetry on")).join("\n");
+ assert!(all.contains("Telemetry turned on."), "{all}");
+ assert_eq!(*settings.telemetry_enabled.lock().unwrap(), Some(true));
+}
+
+/// The first-run telemetry disclosure renders as a session info row
+/// (the TS session diagnostic): once per installation, from the
+/// interactive attach, and the shown marker persists with the row.
+#[test]
+fn the_first_run_telemetry_notice_renders_as_a_row() {
+ let settings = Arc::new(StubSettings {
+ notice_due: true,
+ ..StubSettings::default()
+ });
+ let all = run_plan(Arc::clone(&settings), submit("/telemetry status")).join("\n");
+ assert!(
+ all.contains("Prime Agent sends pseudonymous usage"),
+ "the disclosure row rendered:\n{all}"
+ );
+ assert!(
+ all.contains("Disable this with /telemetry off"),
+ "the interactive switch names itself:\n{all}"
+ );
+ assert!(
+ settings
+ .notice_shown
+ .load(std::sync::atomic::Ordering::Relaxed),
+ "the shown marker persisted with the row"
+ );
+
+ // The once-per-installation gate: a second attach with the same
+ // installation draws no second row.
+ let again = run_plan(Arc::clone(&settings), submit("/telemetry status")).join("\n");
+ assert!(
+ !again.contains("Prime Agent sends pseudonymous usage"),
+ "no second disclosure row:\n{again}"
+ );
+}
+
+/// The disclosure is once per installation: a run whose notice already
+/// showed draws no second row.
+#[test]
+fn an_already_disclosed_installation_renders_no_notice_row() {
+ let settings = Arc::new(StubSettings::default());
+ let all = run_plan(Arc::clone(&settings), submit("/telemetry status")).join("\n");
+ assert!(
+ !all.contains("Prime Agent sends pseudonymous usage"),
+ "no disclosure row on an already-shown install:\n{all}"
+ );
+}
+
+/// `/telemetry on` under an environment opt-out says it stays off.
+#[test]
+fn telemetry_on_says_an_environment_opt_out_still_wins() {
+ let settings = Arc::new(StubSettings {
+ forced_off_by: Some("DO_NOT_TRACK"),
+ ..StubSettings::default()
+ });
+ let all = run_plan(Arc::clone(&settings), submit("/telemetry on")).join("\n");
+ assert!(
+ all.contains("Saved telemetry on in settings, but it stays off."),
+ "{all}"
+ );
+ assert!(
+ all.contains("Telemetry is off (forced off by DO_NOT_TRACK)."),
+ "{all}"
+ );
+}
diff --git a/crates/pa-types/src/slash_commands.rs b/crates/pa-types/src/slash_commands.rs
index e05c36bb43..574bc31aa0 100644
--- a/crates/pa-types/src/slash_commands.rs
+++ b/crates/pa-types/src/slash_commands.rs
@@ -63,6 +63,7 @@ const CANONICAL_BUILTIN_SLASH_COMMANDS: &[BuiltinSlashCommand] = &[
BuiltinSlashCommand { name: "system-prompt", description: "Show the exact system prompt sent to the model", execution: SlashCommandExecution::Client, argument_hint: None, aliases: &[], takes_argument: false },
BuiltinSlashCommand { name: "logs", description: "Show where daemon and client logs are saved", execution: SlashCommandExecution::Client, argument_hint: None, aliases: &[], takes_argument: false },
BuiltinSlashCommand { name: "traces", description: "Preview, upload, or configure Prime Agent traces", execution: SlashCommandExecution::Client, argument_hint: Some("[status|on|off|preview|upload|upload-current|upload-all|login]"), aliases: &[], takes_argument: false },
+ BuiltinSlashCommand { name: "telemetry", description: "Show or change usage telemetry (pseudonymous metrics, never prompts or code)", execution: SlashCommandExecution::Client, argument_hint: Some("[status|on|off]"), aliases: &[], takes_argument: true },
BuiltinSlashCommand { name: "context", description: "Show token, cost, and context usage for agent and sub-agents", execution: SlashCommandExecution::Client, argument_hint: None, aliases: &["usage"], takes_argument: false },
BuiltinSlashCommand { name: "changelog", description: "Show changelog entries", execution: SlashCommandExecution::Client, argument_hint: None, aliases: &[], takes_argument: false },
BuiltinSlashCommand { name: "update", description: "Update to the latest Rust build (uninstalls the TypeScript version; sessions preserved)", execution: SlashCommandExecution::Client, argument_hint: None, aliases: &[], takes_argument: false },