Skip to main content

usage/
log.rs

1//! A native session file read for the session report without opening the session (`ultron/session-log.ts`): a
2//! digest of each entry (who wrote it and what it used, never its text), the latest values of the namespaces the
3//! report reads, and every operation's lane and result.
4
5use crate::stats::{cell_apis, classify_nudge};
6use indexmap::IndexMap;
7use serde_json::{Map, Value};
8use session_journal::catalog::HeaderLine;
9use session_journal::ns;
10use std::io::{BufRead, BufReader};
11use std::path::{Path, PathBuf};
12
13#[derive(Clone, Copy, Debug, PartialEq)]
14pub struct LogUsage {
15    pub input: f64,
16    pub output: f64,
17    pub cache_read: f64,
18    pub cache_write: f64,
19    pub total_tokens: f64,
20    /// Provider-reported cost; None when the response carried none.
21    pub cost: Option<f64>,
22}
23
24#[derive(Clone, Debug, PartialEq)]
25pub struct LogToolCall {
26    pub name: String,
27    /// For an `rlm` cell: the REPL APIs its code names.
28    pub apis: Option<Vec<&'static str>>,
29}
30
31#[derive(Clone, Copy, Debug, PartialEq, Eq)]
32pub enum EntryKind {
33    User,
34    Assistant,
35    ToolResult,
36    Custom,
37    Compaction,
38    BranchSummary,
39    Other,
40}
41
42#[derive(Clone, Debug, PartialEq)]
43pub struct LogEntry {
44    pub id: String,
45    pub parent_id: Option<String>,
46    pub timestamp: f64,
47    pub kind: EntryKind,
48    pub provider: Option<String>,
49    pub model: Option<String>,
50    pub usage: Option<LogUsage>,
51    pub tool_calls: Vec<LogToolCall>,
52    pub tool_name: Option<String>,
53    pub is_error: bool,
54    pub redactions: f64,
55    pub nudge: Option<&'static str>,
56    /// An automatic memory recall (an `ultron.memory` custom message).
57    pub recall: Option<Recall>,
58}
59
60/// What one automatic recall put in front of the model (session-core `auto_memory::recall_message`).
61#[derive(Clone, Copy, Debug, PartialEq)]
62pub struct Recall {
63    pub memories: usize,
64    pub brief: bool,
65    pub stale: usize,
66}
67
68#[derive(Clone, Debug, PartialEq)]
69pub struct LogUsageRow {
70    pub usage: LogUsage,
71    pub entry_id: Option<String>,
72    pub adjustment: bool,
73}
74
75/// One model response of a durable runtime conversation other than the root's (an `rlm.spawn` child, a typed agent,
76/// another root conversation): its `ultron.assistant` entry in the session's durable records (`ultron.module/durable`).
77/// The root conversation's responses are transcript entries already, so they are not listed.
78#[derive(Clone, Debug, PartialEq)]
79pub struct DurableResponse {
80    /// The lane the conversation runs: its owning child task's name (`ultron.rlm-child.<task>`); none for another
81    /// root conversation.
82    pub lane: Option<String>,
83    /// Whether a task (a subagent) owns the conversation.
84    pub owned: bool,
85    /// `provider/model` of the response.
86    pub model: String,
87    pub usage: LogUsage,
88}
89
90/// What the durable records say, gathered while reading (resolved into [`DurableResponse`]s at the end).
91#[derive(Default)]
92struct DurableDigest {
93    /// Conversation id -> its owning task id (none for a root conversation).
94    owners: std::collections::HashMap<u64, Option<u64>>,
95    /// Task id -> its `input.name` (a child task's lane).
96    task_names: std::collections::HashMap<u64, String>,
97    /// (conversation, `provider/model`, usage), in commit order.
98    responses: Vec<(u64, String, LogUsage)>,
99}
100
101/// A durable commit line: `{"kind":"list","op":"append","seq":N,"namespace":"ultron.module","key":"durable",...}`.
102static DURABLE_MARK: std::sync::LazyLock<String> =
103    std::sync::LazyLock::new(|| format!(r#""namespace":"{}","key":"{}""#, ns::MODULE, ns::DURABLE_KEY));
104
105/// Whether a list-append line is a durable commit: its namespace and key come within its first bytes (as
106/// `state::commit_write` orders a list append's fields).
107fn is_durable_commit(line: &str) -> bool {
108    let head = &line.as_bytes()[..line.len().min(160)];
109    head.windows(DURABLE_MARK.len()).any(|w| w == DURABLE_MARK.as_bytes())
110}
111
112impl DurableDigest {
113    /// One durable commit (`{seq, writes}`).
114    fn commit(&mut self, record: &Value) {
115        for write in record.get("writes").and_then(Value::as_array).into_iter().flatten() {
116            let value = &write["value"];
117            match write.get("type").and_then(Value::as_str) {
118                Some("conversation") => {
119                    if let Some(id) = value["id"].as_u64() {
120                        self.owners.insert(id, value["owner"]["taskId"].as_u64());
121                    }
122                }
123                Some("task") => {
124                    if let (Some(id), Some(name)) = (value["id"].as_u64(), value["input"]["name"].as_str()) {
125                        self.task_names.entry(id).or_insert_with(|| name.to_string());
126                    }
127                }
128                Some("entry") if value["kind"] == harness::chat::entries::ASSISTANT => {
129                    let Some(conversation) = value["conversationId"].as_u64() else {
130                        continue;
131                    };
132                    if conversation == durable::ROOT_CONVERSATION_ID.0 {
133                        continue;
134                    }
135                    let message = &value["model"][0];
136                    let Some(usage) = log_usage(message.get("usage")) else {
137                        continue;
138                    };
139                    let model = format!(
140                        "{}/{}",
141                        message["provider"].as_str().unwrap_or("unknown"),
142                        message["model"].as_str().unwrap_or("unknown")
143                    );
144                    self.responses.push((conversation, model, usage));
145                }
146                _ => {}
147            }
148        }
149    }
150
151    fn resolve(self) -> Vec<DurableResponse> {
152        self.responses
153            .into_iter()
154            .map(|(conversation, model, usage)| {
155                let owner = self.owners.get(&conversation).copied().flatten();
156                DurableResponse {
157                    lane: owner.and_then(|task| self.task_names.get(&task).cloned()),
158                    owned: owner.is_some(),
159                    model,
160                    usage,
161                }
162            })
163            .collect()
164    }
165}
166
167#[derive(Clone, Debug, PartialEq)]
168pub struct LogOperation {
169    pub id: String,
170    pub lane: String,
171    pub kind: String,
172    pub started_at: f64,
173}
174
175#[derive(Clone, Debug, PartialEq)]
176pub struct LogResult {
177    pub operation_id: String,
178    pub kind: String,
179    pub status: String,
180    pub from_tip_id: Option<String>,
181    pub tip_id: Option<String>,
182    pub started_at: f64,
183    pub ended_at: f64,
184}
185
186#[derive(Clone, Debug, PartialEq)]
187pub struct Header {
188    pub id: String,
189    pub cwd: String,
190    pub created_at: f64,
191    pub parent_session_id: Option<String>,
192}
193
194#[derive(Clone, Debug, PartialEq)]
195pub struct SessionLog {
196    pub path: PathBuf,
197    pub header: Header,
198    pub modified_at: f64,
199    pub bytes: u64,
200    pub entries: Vec<LogEntry>,
201    pub usage_rows: Vec<LogUsageRow>,
202    /// Latest value by `namespace/key`, for the namespaces in [`KEPT_NAMESPACES`].
203    pub values: IndexMap<String, Value>,
204    pub operations: IndexMap<String, LogOperation>,
205    pub results: Vec<LogResult>,
206    /// Responses of the durable runtime's non-root conversations (sub-agents), from its records.
207    pub durable_responses: Vec<DurableResponse>,
208    pub unreadable_lines: u64,
209}
210
211/// A read failure: `Session` for a file that is not a native session (`SessionLogError`), `Io` otherwise.
212#[derive(Clone, Debug, PartialEq, Eq)]
213pub enum LogError {
214    Session(String),
215    Io(String),
216}
217
218impl LogError {
219    pub fn message(&self) -> &str {
220        match self {
221            LogError::Session(m) | LogError::Io(m) => m,
222        }
223    }
224}
225
226const KEPT_NAMESPACES: [&str; 9] = [
227    ns::SESSION_NAME,
228    ns::LANE_CONFIG,
229    ns::BRANCH_TIP,
230    ns::TASKS,
231    ns::USAGE,
232    ns::RLM_FRAMES,
233    ns::MEMORY_STATE,
234    ns::MODULE,
235    "ultron.claude-code.lanes",
236];
237
238pub fn record(value: Option<&Value>) -> Option<&Map<String, Value>> {
239    value.and_then(Value::as_object)
240}
241
242fn amount(value: Option<&Value>) -> f64 {
243    match value.and_then(Value::as_f64) {
244        Some(n) if n.is_finite() && n > 0.0 => n,
245        _ => 0.0,
246    }
247}
248
249pub fn log_usage(value: Option<&Value>) -> Option<LogUsage> {
250    let usage = record(value)?;
251    let cost = record(usage.get("cost"))
252        .and_then(|c| c.get("total"))
253        .and_then(Value::as_f64);
254    let input = amount(usage.get("input"));
255    let output = amount(usage.get("output"));
256    let cache_read = amount(usage.get("cacheRead"));
257    let cache_write = amount(usage.get("cacheWrite"));
258    let total = amount(usage.get("totalTokens"));
259    Some(LogUsage {
260        input,
261        output,
262        cache_read,
263        cache_write,
264        total_tokens: if total != 0.0 {
265            total
266        } else {
267            input + output + cache_read + cache_write
268        },
269        cost: cost.filter(|c| c.is_finite() && *c >= 0.0),
270    })
271}
272
273fn text_of(content: Option<&Value>) -> String {
274    match content {
275        Some(Value::String(s)) => s.clone(),
276        Some(Value::Array(parts)) => parts
277            .iter()
278            .filter_map(Value::as_object)
279            .filter(|p| p.get("type").and_then(Value::as_str) == Some("text"))
280            .filter_map(|p| p.get("text").and_then(Value::as_str))
281            .collect(),
282        _ => String::new(),
283    }
284}
285
286fn timestamp_of(value: Option<&Value>) -> f64 {
287    value.and_then(Value::as_f64).filter(|n| n.is_finite()).unwrap_or(0.0)
288}
289
290fn string_of(value: Option<&Value>) -> Option<String> {
291    value.and_then(Value::as_str).map(str::to_string)
292}
293
294fn digest_entry(write: &Map<String, Value>) -> Option<LogEntry> {
295    let id = write.get("id")?.as_str()?.to_string();
296    let mut entry = LogEntry {
297        id,
298        parent_id: string_of(write.get("parentId")),
299        timestamp: timestamp_of(write.get("timestamp")),
300        kind: EntryKind::Other,
301        provider: None,
302        model: None,
303        usage: None,
304        tool_calls: Vec::new(),
305        tool_name: None,
306        is_error: false,
307        redactions: 0.0,
308        nudge: None,
309        recall: None,
310    };
311    let kind = write.get("type").and_then(Value::as_str);
312    if let Some(k) = kind.and_then(|k| match k {
313        "compaction" => Some(EntryKind::Compaction),
314        "branch_summary" => Some(EntryKind::BranchSummary),
315        "custom" => Some(EntryKind::Custom),
316        _ => None,
317    }) {
318        entry.kind = k;
319        entry.usage = log_usage(write.get("usage"));
320        return Some(entry);
321    }
322    let Some(message) = record(write.get("message")).filter(|_| kind == Some("message")) else {
323        return Some(entry);
324    };
325    match message.get("role").and_then(Value::as_str) {
326        Some("assistant") => {
327            entry.kind = EntryKind::Assistant;
328            entry.provider = string_of(message.get("provider"));
329            entry.model = string_of(message.get("model"));
330            entry.usage = log_usage(message.get("usage"));
331            for part in message.get("content").and_then(Value::as_array).into_iter().flatten() {
332                let Some(item) = part.as_object() else { continue };
333                if item.get("type").and_then(Value::as_str) != Some("toolCall") {
334                    continue;
335                }
336                let Some(name) = item.get("name").and_then(Value::as_str) else {
337                    continue;
338                };
339                let code = record(item.get("arguments"))
340                    .and_then(|a| a.get("code"))
341                    .and_then(Value::as_str);
342                entry.tool_calls.push(LogToolCall {
343                    name: name.to_string(),
344                    apis: code.filter(|_| name == "rlm").map(cell_apis),
345                });
346            }
347        }
348        Some("toolResult") => {
349            entry.kind = EntryKind::ToolResult;
350            entry.tool_name = string_of(message.get("toolName"));
351            entry.is_error = message.get("isError") == Some(&Value::Bool(true));
352            entry.redactions = (text_of(message.get("content")).matches("[REDACTED:").count()) as f64;
353        }
354        Some("user") => {
355            entry.kind = EntryKind::User;
356            entry.nudge = classify_nudge(&text_of(message.get("content")));
357        }
358        Some("custom") => {
359            entry.kind = EntryKind::Custom;
360            if message.get("customType").and_then(Value::as_str) == Some(protocol::custom_types::RECALLED_MEMORY) {
361                let details = record(message.get("details"));
362                let field = |key: &str| details.and_then(|d| d.get(key));
363                entry.recall = Some(Recall {
364                    memories: field("ids").and_then(Value::as_array).map_or(0, Vec::len),
365                    brief: field("digest").is_some_and(|d| !d.is_null()),
366                    stale: field("stale").and_then(Value::as_u64).unwrap_or(0) as usize,
367                });
368            }
369        }
370        _ => {}
371    }
372    Some(entry)
373}
374
375fn parse_header(line: &str, path: &Path) -> Result<Header, LogError> {
376    let shown = path.display();
377    let not_native = || LogError::Session(format!("{shown} is not a native Ultron session file"));
378    let h = match HeaderLine::parse(line) {
379        HeaderLine::NotJson => {
380            return Err(LogError::Session(format!(
381                "{shown} is not a session file (its first line is not JSON)"
382            )));
383        }
384        HeaderLine::Pi(h) if h.contains_key("version") => {
385            return Err(LogError::Session(format!(
386                "{shown} is a Pi-format session (version {}); only native Ultron sessions are reported",
387                jsrt::value::string(h.get("version"))
388            )));
389        }
390        HeaderLine::Native(h) => h,
391        HeaderLine::Pi(_) | HeaderLine::Other => return Err(not_native()),
392    };
393    let (Some(id), Some(cwd)) = (
394        h.get("id").and_then(Value::as_str),
395        h.get("cwd").and_then(Value::as_str),
396    ) else {
397        return Err(not_native());
398    };
399    Ok(Header {
400        id: id.to_string(),
401        cwd: cwd.to_string(),
402        created_at: timestamp_of(h.get("createdAt")),
403        parent_session_id: string_of(h.get("parentSessionId")),
404    })
405}
406
407/// Lines as `readline` yields them: split on `\n` (a `\r` before it dropped), the last one even without a newline.
408fn for_each_line(path: &Path, mut each: impl FnMut(&str) -> Result<bool, LogError>) -> Result<(), LogError> {
409    let file = std::fs::File::open(path).map_err(|e| LogError::Io(jsrt::fs::error_message(&e, "open", path)))?;
410    let mut reader = BufReader::new(file);
411    let mut buffer = Vec::new();
412    loop {
413        buffer.clear();
414        let read = reader
415            .read_until(b'\n', &mut buffer)
416            .map_err(|e| LogError::Io(e.to_string()))?;
417        if read == 0 {
418            return Ok(());
419        }
420        if buffer.last() == Some(&b'\n') {
421            buffer.pop();
422            if buffer.last() == Some(&b'\r') {
423                buffer.pop();
424            }
425        }
426        if !each(&String::from_utf8_lossy(&buffer))? {
427            return Ok(());
428        }
429    }
430}
431
432/// Read only a session file's header (its first line).
433pub fn read_session_header(path: &Path) -> Result<Header, LogError> {
434    let mut header = None;
435    for_each_line(path, |line| {
436        header = Some(parse_header(line, path)?);
437        Ok(false)
438    })?;
439    header.ok_or_else(|| LogError::Session(format!("{} is empty", path.display())))
440}
441
442/// File modification time in milliseconds (`Math.round(stat.mtimeMs)`) and size.
443pub fn file_times(path: &Path) -> Result<(f64, u64), LogError> {
444    let meta = std::fs::metadata(path).map_err(|e| LogError::Io(jsrt::fs::error_message(&e, "stat", path)))?;
445    Ok((meta.modified().map_or(0.0, jsrt::date::mtime_ms).round(), meta.len()))
446}
447
448/// Read a native session file. Fails with [`LogError::Session`] for a file that is not one.
449pub fn read_session_log(path: &Path) -> Result<SessionLog, LogError> {
450    let (modified_at, bytes) = file_times(path)?;
451    let header = read_session_header(path)?;
452    let mut log = SessionLog {
453        path: path.to_path_buf(),
454        header,
455        modified_at,
456        bytes,
457        entries: Vec::new(),
458        usage_rows: Vec::new(),
459        values: IndexMap::new(),
460        operations: IndexMap::new(),
461        results: Vec::new(),
462        durable_responses: Vec::new(),
463        unreadable_lines: 0,
464    };
465    let mut durable = DurableDigest::default();
466    // List appends are skipped unread (stream frames are most of a file), except the durable runtime's commits.
467    let skip = |line: &str| line.starts_with(r#"{"kind":"list""#) && !is_durable_commit(line);
468    session_journal::catalog::scan_writes(path, skip, |writes| {
469        let Some(writes) = writes else {
470            log.unreadable_lines += 1;
471            return;
472        };
473        for write in writes.iter().filter_map(Value::as_object) {
474            apply(&mut log, &mut durable, write);
475        }
476    })
477    .map_err(|e| LogError::Io(jsrt::fs::error_message(&e, "open", path)))?;
478    log.durable_responses = durable.resolve();
479    Ok(log)
480}
481
482fn apply(log: &mut SessionLog, durable: &mut DurableDigest, write: &Map<String, Value>) {
483    let kind = write.get("kind").and_then(Value::as_str);
484    if kind == Some("list") {
485        if write.get("op").and_then(Value::as_str) == Some("append")
486            && write.get("namespace").and_then(Value::as_str) == Some(ns::MODULE)
487            && write.get("key").and_then(Value::as_str) == Some(ns::DURABLE_KEY)
488            && let Some(record) = write.get("value")
489        {
490            durable.commit(record);
491        }
492        return;
493    }
494    if kind == Some("entry") {
495        if let Some(entry) = digest_entry(write) {
496            log.entries.push(entry);
497        }
498        return;
499    }
500    if kind == Some("usage") {
501        if let Some(usage) = log_usage(write.get("usage")) {
502            log.usage_rows.push(LogUsageRow {
503                usage,
504                entry_id: string_of(write.get("entryId")),
505                adjustment: write.get("adjustment") == Some(&Value::Bool(true)),
506            });
507        }
508        return;
509    }
510    let (Some("value"), Some(namespace), Some(key)) = (
511        kind,
512        write.get("namespace").and_then(Value::as_str),
513        write.get("key").and_then(Value::as_str),
514    ) else {
515        return;
516    };
517    let op = write.get("op").and_then(Value::as_str);
518    let value = record(write.get("value"));
519    if namespace == ns::OP_META {
520        if op == Some("set")
521            && let Some(v) = value
522            && let Some(lane) = v.get("lane").and_then(Value::as_str)
523        {
524            let intent = record(v.get("intent"))
525                .and_then(|i| i.get("kind"))
526                .and_then(Value::as_str);
527            log.operations.insert(
528                key.to_string(),
529                LogOperation {
530                    id: key.to_string(),
531                    lane: lane.to_string(),
532                    kind: intent.unwrap_or("run").to_string(),
533                    started_at: timestamp_of(v.get("startedAt")),
534                },
535            );
536        }
537        return;
538    }
539    if namespace == ns::OP_RESULT {
540        if op == Some("set")
541            && let Some(v) = value
542        {
543            let text = |k: &str| v.get(k).and_then(Value::as_str);
544            log.results.push(LogResult {
545                operation_id: text("operationId").unwrap_or(key).to_string(),
546                kind: text("kind").unwrap_or("run").to_string(),
547                status: text("status").unwrap_or("unknown").to_string(),
548                from_tip_id: text("fromTipId").map(str::to_string),
549                tip_id: text("tipId").map(str::to_string),
550                started_at: timestamp_of(v.get("startedAt")),
551                ended_at: timestamp_of(v.get("endedAt")),
552            });
553        }
554        return;
555    }
556    if !KEPT_NAMESPACES.contains(&namespace) {
557        return;
558    }
559    let address = format!("{namespace}/{key}");
560    match op {
561        Some("set") => {
562            let v = write.get("value").cloned().unwrap_or(Value::Null);
563            log.values.insert(address, v);
564        }
565        Some("delete") => {
566            log.values.shift_remove(&address);
567        }
568        _ => {}
569    }
570}
571
572impl SessionLog {
573    pub fn value(&self, namespace: &str, key: &str) -> Option<&Value> {
574        self.values.get(&format!("{namespace}/{key}"))
575    }
576
577    /// The latest values of a namespace, by key, in the order they were first written.
578    pub fn values_of(&self, namespace: &str) -> Vec<(&str, &Value)> {
579        let prefix = format!("{namespace}/");
580        self.values
581            .iter()
582            .filter_map(|(address, value)| address.strip_prefix(&prefix).map(|key| (key, value)))
583            .collect()
584    }
585}