Skip to main content

usage/
stats.rs

1//! The parts of `ultron/session-stats.ts` the report reads: which REPL APIs a cell names, which steer a message is,
2//! and the stored runtime counters (`ultron.module/stats`).
3
4use indexmap::IndexMap;
5use regex::Regex;
6use serde_json::{Map, Value, json};
7use std::sync::LazyLock;
8
9/// The module name: the session value `ultron.module/stats`.
10pub const SESSION_STATS_MODULE: &str = "stats";
11/// The stored document's format version.
12pub const STATS_VERSION: u64 = 1;
13
14/// REPL APIs a cell's code can name, in the order the report lists them.
15pub const CELL_APIS: [&str; 16] = [
16    "bash",
17    "read",
18    "edit",
19    "write",
20    "rlm.load",
21    "rlm.infer",
22    "rlm.map",
23    "rlm.spawn",
24    "rlm.collect",
25    "rlm.merge",
26    "mcp.call",
27    "tools.call",
28    "workflows.run",
29    "agents.*",
30    "background.start",
31    "view_image",
32];
33
34static API_PATTERNS: LazyLock<Vec<(&'static str, Regex)>> = LazyLock::new(|| {
35    // `(?<![\w.])name\s*\(`: the regex crate has no look-behind, so the preceding character is matched instead.
36    let bare = |name: &str| format!(r"(?:^|[^A-Za-z0-9_.]){name}\s*\(");
37    let dotted = |name: &str| format!(r"(?:^|[^A-Za-z0-9_]){}\s*\(", name.replace('.', r"\."));
38    CELL_APIS
39        .iter()
40        .map(|&name| {
41            let pattern = match name {
42                "bash" | "read" | "edit" | "write" | "view_image" => bare(name),
43                "agents.*" => r"(?:^|[^A-Za-z0-9_])agents\.(?:spawn|invoke|register)\s*\(".to_string(),
44                _ => dotted(name),
45            };
46            (name, Regex::new(&pattern).expect("API pattern compiles"))
47        })
48        .collect()
49});
50
51/// The REPL APIs a cell's code names (each at most once): a static read of the source, so a call inside a function
52/// the cell only defines counts too, and a call made through an alias does not.
53pub fn cell_apis(code: &str) -> Vec<&'static str> {
54    API_PATTERNS
55        .iter()
56        .filter(|(_, pattern)| pattern.is_match(code))
57        .map(|(name, _)| *name)
58        .collect()
59}
60
61static NUDGES: LazyLock<[(&'static str, Regex); 3]> = LazyLock::new(|| {
62    let re = |p: &str| Regex::new(p).expect("nudge pattern compiles");
63    [
64        (
65            "skill",
66            re(r"^\[Ultron\] [0-9]+ tool rounds in a row succeeded(?-u:\b)"),
67        ),
68        (
69            "wait",
70            re(
71                r"^\[Ultron\] (?:1 subagent or task you started is|[0-9]+ subagents or tasks you started are) still running(?-u:\b)",
72            ),
73        ),
74        (
75            "toolRounds",
76            re(r"^\[Ultron\] You have (?:now )?used [0-9]+ rounds of tool calls(?-u:\b)"),
77        ),
78    ]
79});
80
81/// Which steer a `[Ultron] ...` message is (`skill`, `wait` or `toolRounds`; see crate::nudge), or None.
82pub fn classify_nudge(text: &str) -> Option<&'static str> {
83    if !text.starts_with("[Ultron] ") {
84        return None;
85    }
86    NUDGES.iter().find(|(_, re)| re.is_match(text)).map(|(kind, _)| *kind)
87}
88
89/// Which counter a lane's cells go to: the root lane, `rlm.spawn` subagents, or anything else (typed agents, jobs).
90pub fn stats_lane(lane: &str) -> &'static str {
91    if lane == "main" {
92        "root"
93    } else if matches!(
94        lanes::lane_names::parse_lane(lane),
95        Some(lanes::lane_names::LaneOwner::Child(_))
96    ) {
97        "subagents"
98    } else {
99        "other"
100    }
101}
102
103#[derive(Clone, Debug, Default, PartialEq)]
104pub struct Cells {
105    pub count: f64,
106    pub failed: f64,
107    pub apis: IndexMap<String, f64>,
108}
109
110#[derive(Clone, Debug, Default, PartialEq)]
111pub struct Guard {
112    pub checks: f64,
113    pub blocked: f64,
114    pub unchecked: f64,
115    pub after_checks: f64,
116    pub after_findings: f64,
117    pub ms: f64,
118}
119
120/// A stored stats document with every field present (`SessionStatsDocument`).
121#[derive(Clone, Debug, PartialEq)]
122pub struct Stats {
123    pub external: bool,
124    pub since: f64,
125    pub updated_at: f64,
126    pub cells: [Cells; 3],
127    pub host_calls: IndexMap<String, f64>,
128    pub secrets_masked: f64,
129    pub guards: IndexMap<String, Guard>,
130    /// toolRounds, wait, skill.
131    pub nudges: [f64; 3],
132    pub usage_limit_blocks: f64,
133    pub merges: IndexMap<String, String>,
134    pub child_models: IndexMap<String, String>,
135    pub external_turns: (f64, f64),
136}
137
138impl Stats {
139    /// The stored document (`SessionStatsDocument`), every field present.
140    pub fn to_json(&self) -> Value {
141        let number = jsrt::json::number;
142        let numbers = |map: &IndexMap<String, f64>| -> Map<String, Value> {
143            map.iter().map(|(k, v)| (k.clone(), number(*v))).collect()
144        };
145        let texts = |map: &IndexMap<String, String>| -> Map<String, Value> {
146            map.iter().map(|(k, v)| (k.clone(), json!(v))).collect()
147        };
148        let cells = |c: &Cells| json!({"count": number(c.count), "failed": number(c.failed), "apis": numbers(&c.apis)});
149        let guards: Map<String, Value> = self
150            .guards
151            .iter()
152            .map(|(name, g)| {
153                let guard = json!({
154                    "checks": number(g.checks),
155                    "blocked": number(g.blocked),
156                    "unchecked": number(g.unchecked),
157                    "afterChecks": number(g.after_checks),
158                    "afterFindings": number(g.after_findings),
159                    "ms": number(g.ms),
160                });
161                (name.clone(), guard)
162            })
163            .collect();
164        let [tool_rounds, wait, skill] = self.nudges;
165        json!({
166            "version": STATS_VERSION,
167            "root": if self.external { "external" } else { "lane" },
168            "since": number(self.since),
169            "updatedAt": number(self.updated_at),
170            "cells": {"root": cells(&self.cells[0]), "subagents": cells(&self.cells[1]), "other": cells(&self.cells[2])},
171            "hostCalls": numbers(&self.host_calls),
172            "secretsMasked": number(self.secrets_masked),
173            "guards": guards,
174            "nudges": {"toolRounds": number(tool_rounds), "wait": number(wait), "skill": number(skill)},
175            "usageLimitBlocks": number(self.usage_limit_blocks),
176            "merges": texts(&self.merges),
177            "childModels": texts(&self.child_models),
178            "externalTurns": {"count": number(self.external_turns.0), "wallMs": number(self.external_turns.1)},
179        })
180    }
181
182    /// `emptySessionStats("lane", now)`.
183    pub fn empty(now: f64) -> Stats {
184        Stats {
185            external: false,
186            since: now,
187            updated_at: now,
188            cells: Default::default(),
189            host_calls: IndexMap::new(),
190            secrets_masked: 0.0,
191            guards: IndexMap::new(),
192            nudges: [0.0; 3],
193            usage_limit_blocks: 0.0,
194            merges: IndexMap::new(),
195            child_models: IndexMap::new(),
196            external_turns: (0.0, 0.0),
197        }
198    }
199}
200
201fn count(value: Option<&Value>) -> f64 {
202    match value.and_then(Value::as_f64) {
203        Some(n) if n.is_finite() && n >= 0.0 => n,
204        _ => 0.0,
205    }
206}
207
208fn object(value: Option<&Value>) -> Option<&Map<String, Value>> {
209    value.and_then(Value::as_object)
210}
211
212fn counts(value: Option<&Value>) -> IndexMap<String, f64> {
213    object(value)
214        .map(|m| {
215            jsrt::json::object_entries(m)
216                .into_iter()
217                .filter(|(_, v)| count(Some(v)) > 0.0)
218                .map(|(k, v)| (k.clone(), count(Some(v))))
219                .collect()
220        })
221        .unwrap_or_default()
222}
223
224fn strings(value: Option<&Value>) -> IndexMap<String, String> {
225    object(value)
226        .map(|m| {
227            jsrt::json::object_entries(m)
228                .into_iter()
229                .filter_map(|(k, v)| Some((k.clone(), v.as_str()?.to_string())))
230                .collect()
231        })
232        .unwrap_or_default()
233}
234
235/// `parseSessionStats`: None when `saved` is not a stats document of version 1. Unknown fields are dropped and
236/// malformed counters read as zero. A value that is not an object (`null` included) reads as an empty part.
237pub fn parse_session_stats(saved: Option<&Value>) -> Option<Stats> {
238    let item = object(saved)?;
239    if let Some(version) = item.get("version")
240        && version.as_f64() != Some(STATS_VERSION as f64)
241    {
242        return None;
243    }
244    let part = |key: &str| item.get(key).filter(|v| !v.is_null());
245    let cells = part("cells");
246    let cells_of = |name: &str| {
247        let c = cells.and_then(|c| c.get(name)).filter(|v| !v.is_null());
248        Cells {
249            count: count(c.and_then(|c| c.get("count"))),
250            failed: count(c.and_then(|c| c.get("failed"))),
251            apis: counts(c.and_then(|c| c.get("apis"))),
252        }
253    };
254    let mut guards = IndexMap::new();
255    if let Some(map) = object(item.get("guards")) {
256        for (name, value) in jsrt::json::object_entries(map) {
257            let g = |k: &str| count(Some(value).filter(|v| !v.is_null()).and_then(|v| v.get(k)));
258            guards.insert(
259                name.clone(),
260                Guard {
261                    checks: g("checks"),
262                    blocked: g("blocked"),
263                    unchecked: g("unchecked"),
264                    after_checks: g("afterChecks"),
265                    after_findings: g("afterFindings"),
266                    ms: g("ms"),
267                },
268            );
269        }
270    }
271    let nudges = part("nudges");
272    let nudge = |k: &str| count(nudges.and_then(|n| n.get(k)));
273    let turns = part("externalTurns");
274    Some(Stats {
275        external: item.get("root").and_then(Value::as_str) == Some("external"),
276        since: count(item.get("since")),
277        updated_at: count(item.get("updatedAt")),
278        cells: [cells_of("root"), cells_of("subagents"), cells_of("other")],
279        host_calls: counts(item.get("hostCalls")),
280        secrets_masked: count(item.get("secretsMasked")),
281        guards,
282        nudges: [nudge("toolRounds"), nudge("wait"), nudge("skill")],
283        usage_limit_blocks: count(item.get("usageLimitBlocks")),
284        merges: strings(item.get("merges")),
285        child_models: strings(item.get("childModels")),
286        external_turns: (
287            count(turns.and_then(|t| t.get("count"))),
288            count(turns.and_then(|t| t.get("wallMs"))),
289        ),
290    })
291}