Skip to main content

session_core/
session_stats.rs

1//! The session's runtime counters (`ultron/session-stats.ts`): what the runtime sees while a session runs and no
2//! other session value keeps, for the session report (`/usage`, `ultron usage`). They are the session value
3//! `ultron.module/stats`, written as the TypeScript recorder writes it, so either implementation reads the other's.
4//!
5//! Cells are counted where they run (every lane's `rlm` tool), host requests where the kernels make them, guard
6//! outcomes as the file hooks record them, steers as they are queued for the root, refused work as the usage ledger
7//! refuses it, merges and subagent models as the delegation host settles them. Nothing here holds code, output,
8//! paths or prompts: only counts, API names, task ids and times.
9//!
10//! Recording never fails and never blocks on the store: changes are counted in memory and saved
11//! `flush_ms` (500 ms) after the first unsaved one, and on [`SessionStats::flush`]. A store that cannot be written
12//! keeps the counters in memory and the next change tries again; a stored document in a format this build does not
13//! know is left as it is.
14
15mod external_root;
16
17use crate::durable_store::{SharedSession, lock as lock_session};
18use jsrt::sync;
19use serde_json::{Value, json};
20use session_journal::Write;
21use std::collections::HashMap;
22use std::sync::{Arc, Condvar, Mutex, PoisonError};
23use std::time::Duration;
24use usage::stats::{SESSION_STATS_MODULE, STATS_VERSION, cell_apis, classify_nudge, stats_lane};
25
26/// Distinct host request types kept (later ones are not added), and task ids kept per map (the newest).
27const MAX_KEYS: usize = 200;
28/// How long after the first unsaved change the counters are saved.
29pub const DEFAULT_FLUSH: Duration = Duration::from_millis(500);
30
31fn count(value: Option<&Value>) -> f64 {
32    match value.and_then(Value::as_f64) {
33        Some(n) if n.is_finite() && n >= 0.0 => n,
34        _ => 0.0,
35    }
36}
37
38fn empty_cells() -> Value {
39    json!({"count": 0, "failed": 0, "apis": {}})
40}
41
42fn empty_guard() -> Value {
43    json!({"checks": 0, "blocked": 0, "unchecked": 0, "afterChecks": 0, "afterFindings": 0, "ms": 0})
44}
45
46/// `emptySessionStats(root, now)`.
47pub fn empty_session_stats(root: &str, now: u64) -> Value {
48    json!({
49        "version": STATS_VERSION,
50        "root": root,
51        "since": now,
52        "updatedAt": now,
53        "cells": {"root": empty_cells(), "subagents": empty_cells(), "other": empty_cells()},
54        "hostCalls": {},
55        "secretsMasked": 0,
56        "guards": {},
57        "nudges": {"toolRounds": 0, "wait": 0, "skill": 0},
58        "usageLimitBlocks": 0,
59        "merges": {},
60        "childModels": {},
61        "externalTurns": {"count": 0, "wallMs": 0},
62    })
63}
64
65/// `parseSessionStats`: a stored document with every field present, or None when `saved` is not one (not an object,
66/// or another version). Unknown fields are dropped and malformed counters read as zero.
67pub fn parse_session_stats(saved: &Value) -> Option<Value> {
68    usage::stats::parse_session_stats(Some(saved)).map(|stats| stats.to_json())
69}
70
71/// What the store holds, read as `readVersioned` reads it.
72pub enum Stored {
73    /// Nothing usable (no value, or not a stats document): count from zero.
74    Fresh,
75    /// A stats document (an unversioned one reads as version 1).
76    Document(Value),
77    /// A document in a format version this build does not know: counted in memory, never overwritten.
78    Foreign,
79}
80
81/// `parseSessionStats(readVersioned("ultron.module/stats", saved))`.
82pub fn read_stored(saved: Option<&Value>) -> Stored {
83    let Some(Value::Object(document)) = saved else {
84        return Stored::Fresh;
85    };
86    let mut document = document.clone();
87    match document.get("version") {
88        None => {
89            document.insert("version".into(), json!(STATS_VERSION));
90        }
91        Some(version) if version.as_f64() == Some(STATS_VERSION as f64) && version.is_number() => {}
92        Some(_) => return Stored::Foreign,
93    }
94    parse_session_stats(&Value::Object(document)).map_or(Stored::Fresh, Stored::Document)
95}
96
97/// Where the counters are kept (`HostModuleStore`).
98pub trait StatsStore: Send + Sync {
99    fn read(&self) -> Result<Option<Value>, String>;
100    fn write(&self, document: &Value) -> Result<(), String>;
101}
102
103/// The session value `ultron.module/stats` of a session journal (`createSessionModuleStore(session, "stats")`).
104pub struct SessionStore(pub SharedSession);
105
106impl StatsStore for SessionStore {
107    fn read(&self) -> Result<Option<Value>, String> {
108        Ok(lock_session(&self.0)
109            .value(session_journal::ns::MODULE, SESSION_STATS_MODULE)
110            .cloned())
111    }
112
113    fn write(&self, document: &Value) -> Result<(), String> {
114        lock_session(&self.0)
115            .commit(&[Write::set(
116                session_journal::ns::MODULE,
117                SESSION_STATS_MODULE,
118                document.clone(),
119            )])
120            .map(|_| ())
121    }
122}
123
124/// Milliseconds since the epoch (tests: a fake clock).
125pub type Clock = Arc<dyn Fn() -> u64 + Send + Sync>;
126
127/// One guard outcome (`GuardRecord`, the fields counted here).
128pub struct GuardOutcome<'a> {
129    pub guard: &'a str,
130    /// `before_write`, `before_shell` or `after_cell`.
131    pub phase: &'a str,
132    /// `allowed`, `blocked`, `unchecked`, `clean`, `advisory` or `findings`.
133    pub outcome: &'a str,
134    pub ms: f64,
135}
136
137type Change = Box<dyn Fn(&mut Value) + Send>;
138
139struct State {
140    document: Value,
141    store: Option<Arc<dyn StatsStore>>,
142    /// Changes made before the stored document was read; applied on top of it once it is.
143    early: Option<Vec<Change>>,
144    dirty: bool,
145    /// A save is scheduled (`#timer`).
146    timer: bool,
147    closed: bool,
148    foreign: bool,
149    open_turns: HashMap<String, u64>,
150}
151
152struct Shared {
153    state: Mutex<State>,
154    /// Wakes the scheduled save early (a flush or close took its place).
155    wake: Condvar,
156    /// Saves run one at a time, in order.
157    writes: Mutex<()>,
158    now: Clock,
159    flush_after: Duration,
160}
161
162/// `SessionStatsRecorder`: counts in memory and saves the document shortly after a change.
163pub struct SessionStats {
164    shared: Arc<Shared>,
165}
166
167impl Drop for SessionStats {
168    fn drop(&mut self) {
169        // A scheduled save of a recorder nobody holds is not waited for.
170        sync::lock(&self.shared.state).timer = false;
171        self.shared.wake.notify_all();
172    }
173}
174
175fn add(value: &mut Value, n: f64) {
176    *value = jsrt::json::number(count(Some(value)) + n);
177}
178
179/// `keep(map, key, value)`: `key` as the newest entry of a bounded map (the oldest past [`MAX_KEYS`] are dropped).
180fn keep(map: &mut Value, key: &str, value: &str) {
181    let Some(map) = map.as_object_mut() else {
182        return;
183    };
184    map.shift_remove(key);
185    map.insert(key.to_string(), json!(value));
186    let excess = map.len().saturating_sub(MAX_KEYS);
187    let old: Vec<String> = map.keys().take(excess).cloned().collect();
188    for key in old {
189        map.shift_remove(&key);
190    }
191}
192
193impl SessionStats {
194    /// A recorder for a session whose root is `root` (`lane`, or `external` for Claude Code over MCP), counting
195    /// from `now()`; it saves to nothing until [`SessionStats::attach`] gives it its store.
196    pub fn new(root: &str, now: Clock, flush_after: Duration) -> SessionStats {
197        let document = empty_session_stats(root, now());
198        SessionStats {
199            shared: Arc::new(Shared {
200                state: Mutex::new(State {
201                    document,
202                    store: None,
203                    early: Some(Vec::new()),
204                    dirty: false,
205                    timer: false,
206                    closed: false,
207                    foreign: false,
208                    open_turns: HashMap::new(),
209                }),
210                wake: Condvar::new(),
211                writes: Mutex::new(()),
212                now,
213                flush_after,
214            }),
215        }
216    }
217
218    /// A recorder on the system clock that saves 500 ms after a change.
219    pub fn system(root: &str) -> SessionStats {
220        SessionStats::new(root, Arc::new(|| jsrt::date::now_ms() as u64), DEFAULT_FLUSH)
221    }
222
223    /// Read the stored counters from `store` and keep counting on top of them (`#load`); changes made before are
224    /// applied to what was stored. The session keeps the kind of root it has now.
225    pub fn attach(&self, store: Arc<dyn StatsStore>) {
226        let read = store.read();
227        let mut state = sync::lock(&self.shared.state);
228        if state.store.is_some() || state.early.is_none() {
229            return;
230        }
231        match read.map(|saved| read_stored(saved.as_ref())) {
232            Ok(Stored::Document(mut stored)) => {
233                stored["root"] = state.document["root"].clone();
234                state.document = stored;
235            }
236            // A store that could not be read is not overwritten either: its saved totals may be fine.
237            Ok(Stored::Foreign) | Err(_) => state.foreign = true,
238            Ok(Stored::Fresh) => {}
239        }
240        state.store = Some(store);
241        let early = state.early.take().unwrap_or_default();
242        let changed = !early.is_empty();
243        for change in &early {
244            change(&mut state.document);
245        }
246        if changed {
247            self.schedule(&mut state);
248        }
249    }
250
251    fn change(&self, change: impl Fn(&mut Value) + Send + 'static) {
252        let mut state = sync::lock(&self.shared.state);
253        if state.closed {
254            return;
255        }
256        if let Some(early) = &mut state.early {
257            early.push(Box::new(change));
258            return;
259        }
260        change(&mut state.document);
261        self.schedule(&mut state);
262    }
263
264    fn schedule(&self, state: &mut State) {
265        state.dirty = true;
266        state.document["updatedAt"] = json!((self.shared.now)());
267        if state.timer || state.closed {
268            return;
269        }
270        state.timer = true;
271        let shared = self.shared.clone();
272        std::thread::spawn(move || {
273            let state = sync::lock(&shared.state);
274            let (mut state, _) = shared
275                .wake
276                .wait_timeout_while(state, shared.flush_after, |s| s.timer)
277                .unwrap_or_else(PoisonError::into_inner);
278            // A flush or close that came first took the save over.
279            if !state.timer {
280                return;
281            }
282            state.timer = false;
283            drop(state);
284            save(&shared);
285        });
286    }
287
288    /// Something ran in the session: its counters are saved even while they are all zero.
289    pub fn touch(&self) {
290        self.change(|_| {});
291    }
292
293    /// One cell ran on `lane`: whether it failed, and how many secrets were masked in its output.
294    pub fn cell(&self, lane: &str, code: &str, failed: bool, masked: usize) {
295        let (apis, cells) = (cell_apis(code), stats_lane(lane));
296        self.change(move |document| {
297            let cells = &mut document["cells"][cells];
298            add(&mut cells["count"], 1.0);
299            if failed {
300                add(&mut cells["failed"], 1.0);
301            }
302            for api in &apis {
303                let entry = &mut cells["apis"][*api];
304                add(entry, 1.0);
305            }
306            add(&mut document["secretsMasked"], masked as f64);
307        });
308    }
309
310    /// A kernel made a host request of this type.
311    pub fn host_call(&self, kind: &str) {
312        let kind = kind.to_string();
313        self.change(move |document| {
314            let Some(calls) = document["hostCalls"].as_object_mut() else {
315                return;
316            };
317            if !calls.contains_key(&kind) && calls.len() >= MAX_KEYS {
318                return;
319            }
320            let entry = calls.entry(kind.clone()).or_insert(json!(0));
321            add(entry, 1.0);
322        });
323    }
324
325    /// One guard outcome (Loki, extensions).
326    pub fn guard(&self, record: &GuardOutcome<'_>) {
327        let (name, ms) = (record.guard.to_string(), record.ms);
328        // A shell command checked before it runs counts as a before-write check: it is one.
329        let before = matches!(record.phase, "before_write" | "before_shell");
330        let (blocked, unchecked) = (record.outcome == "blocked", record.outcome == "unchecked");
331        // Advisory-only reports are not findings to fix.
332        let findings = matches!(record.outcome, "findings" | "unchecked");
333        self.change(move |document| {
334            let Some(guards) = document["guards"].as_object_mut() else {
335                return;
336            };
337            let guard = guards.entry(name.clone()).or_insert_with(empty_guard);
338            add(&mut guard["ms"], count(Some(&json!(ms))));
339            if before {
340                add(&mut guard["checks"], 1.0);
341                if blocked {
342                    add(&mut guard["blocked"], 1.0);
343                }
344                if unchecked {
345                    add(&mut guard["unchecked"], 1.0);
346                }
347            } else {
348                add(&mut guard["afterChecks"], 1.0);
349                if findings {
350                    add(&mut guard["afterFindings"], 1.0);
351                }
352            }
353        });
354    }
355
356    /// A steer sent to the root; text that is not one of the known steers is not counted.
357    pub fn nudge(&self, message: &str) {
358        let Some(kind) = classify_nudge(message) else {
359            return;
360        };
361        self.change(move |document| add(&mut document["nudges"][kind], 1.0));
362    }
363
364    /// A tool call, model request or admission refused because a root's limit was hit.
365    pub fn usage_limit_block(&self) {
366        self.change(|document| add(&mut document["usageLimitBlocks"], 1.0));
367    }
368
369    /// How `rlm.merge` ended for a worktree child.
370    pub fn merge(&self, task_id: &str, status: &str) {
371        let (task_id, status) = (task_id.to_string(), status.to_string());
372        self.change(move |document| keep(&mut document["merges"], &task_id, &status));
373    }
374
375    /// The model an `rlm.spawn` subagent ran on.
376    pub fn child_model(&self, task_id: &str, model: &str) {
377        let (task_id, model) = (task_id.to_string(), model.to_string());
378        self.change(move |document| keep(&mut document["childModels"], &task_id, &model));
379    }
380
381    /// A turn of an external root began (Claude Code's UserPromptSubmit, or its first cell).
382    pub fn external_turn_started(&self, turn: &str) {
383        {
384            let mut state = sync::lock(&self.shared.state);
385            if state.open_turns.contains_key(turn) {
386                return;
387            }
388            let now = (self.shared.now)();
389            state.open_turns.insert(turn.to_string(), now);
390        }
391        self.change(|document| add(&mut document["externalTurns"]["count"], 1.0));
392    }
393
394    pub fn external_turn_ended(&self, turn: &str) {
395        let elapsed = {
396            let mut state = sync::lock(&self.shared.state);
397            let Some(started) = state.open_turns.remove(turn) else {
398                return;
399            };
400            (self.shared.now)().saturating_sub(started)
401        };
402        self.change(move |document| add(&mut document["externalTurns"]["wallMs"], elapsed as f64));
403    }
404
405    /// The counters as they are now, saved or not.
406    pub fn snapshot(&self) -> Value {
407        let state = sync::lock(&self.shared.state);
408        let mut document = state.document.clone();
409        for change in state.early.iter().flatten() {
410            change(&mut document);
411        }
412        document
413    }
414
415    /// Save unsaved changes now. Never fails: a store that refuses the write leaves them for the next change.
416    pub fn flush(&self) {
417        {
418            let mut state = sync::lock(&self.shared.state);
419            state.timer = false;
420        }
421        self.shared.wake.notify_all();
422        save(&self.shared);
423    }
424
425    /// Save and stop recording (open external turns end now).
426    pub fn close(&self) {
427        let open: Vec<String> = sync::lock(&self.shared.state).open_turns.keys().cloned().collect();
428        for turn in open {
429            self.external_turn_ended(&turn);
430        }
431        self.flush();
432        let mut state = sync::lock(&self.shared.state);
433        state.closed = true;
434        state.timer = false;
435        drop(state);
436        self.shared.wake.notify_all();
437    }
438}
439
440fn save(shared: &Shared) {
441    let _one_at_a_time = sync::lock(&shared.writes);
442    let (store, document) = {
443        let mut state = sync::lock(&shared.state);
444        let Some(store) = state.store.clone() else {
445            return;
446        };
447        if !state.dirty || state.foreign {
448            return;
449        }
450        state.dirty = false;
451        (store, state.document.clone())
452    };
453    if store.write(&document).is_err() {
454        sync::lock(&shared.state).dirty = true;
455    }
456}