1mod 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
26const MAX_KEYS: usize = 200;
28pub 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
46pub 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
65pub fn parse_session_stats(saved: &Value) -> Option<Value> {
68 usage::stats::parse_session_stats(Some(saved)).map(|stats| stats.to_json())
69}
70
71pub enum Stored {
73 Fresh,
75 Document(Value),
77 Foreign,
79}
80
81pub 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
97pub trait StatsStore: Send + Sync {
99 fn read(&self) -> Result<Option<Value>, String>;
100 fn write(&self, document: &Value) -> Result<(), String>;
101}
102
103pub 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
124pub type Clock = Arc<dyn Fn() -> u64 + Send + Sync>;
126
127pub struct GuardOutcome<'a> {
129 pub guard: &'a str,
130 pub phase: &'a str,
132 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 early: Option<Vec<Change>>,
144 dirty: bool,
145 timer: bool,
147 closed: bool,
148 foreign: bool,
149 open_turns: HashMap<String, u64>,
150}
151
152struct Shared {
153 state: Mutex<State>,
154 wake: Condvar,
156 writes: Mutex<()>,
158 now: Clock,
159 flush_after: Duration,
160}
161
162pub struct SessionStats {
164 shared: Arc<Shared>,
165}
166
167impl Drop for SessionStats {
168 fn drop(&mut self) {
169 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
179fn 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 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 pub fn system(root: &str) -> SessionStats {
220 SessionStats::new(root, Arc::new(|| jsrt::date::now_ms() as u64), DEFAULT_FLUSH)
221 }
222
223 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 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 if !state.timer {
280 return;
281 }
282 state.timer = false;
283 drop(state);
284 save(&shared);
285 });
286 }
287
288 pub fn touch(&self) {
290 self.change(|_| {});
291 }
292
293 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 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 pub fn guard(&self, record: &GuardOutcome<'_>) {
327 let (name, ms) = (record.guard.to_string(), record.ms);
328 let before = matches!(record.phase, "before_write" | "before_shell");
330 let (blocked, unchecked) = (record.outcome == "blocked", record.outcome == "unchecked");
331 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 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 pub fn usage_limit_block(&self) {
366 self.change(|document| add(&mut document["usageLimitBlocks"], 1.0));
367 }
368
369 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 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 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 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 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 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}