Skip to main content

session_file/
manager.rs

1//! `SessionManager`: an append-only session tree persisted as JSONL.
2
3use std::fmt;
4use std::fs::{self, OpenOptions};
5use std::io::{self, Write};
6use std::path::Path;
7
8use indexmap::IndexMap;
9use serde_json::{Value, json};
10
11use crate::context::{
12    self, Leaf, SessionContext, SessionProjection, entry_type, id_key, is_message_with_role, object, str_key,
13};
14use crate::env::Env;
15use crate::file::{
16    self, CURRENT_SESSION_VERSION, HeaderScanError, generate_id, header_cwd, load_entries_from_file,
17    migrate_session_entries, read_session_header,
18};
19use crate::js;
20use crate::paths::{normalize_path, parent, resolve_path};
21use jsrt::path::join;
22
23/// Errors from session operations. `Invalid` messages are the TypeScript error messages.
24#[derive(Debug)]
25pub enum Error {
26    Invalid(String),
27    Io(io::Error),
28}
29
30impl Error {
31    /// The Node error code an I/O failure maps to (`EEXIST`, `ENOENT`, ...).
32    pub fn code(&self) -> Option<&'static str> {
33        let Error::Io(e) = self else { return None };
34        Some(match e.kind() {
35            io::ErrorKind::AlreadyExists => "EEXIST",
36            io::ErrorKind::NotFound => "ENOENT",
37            io::ErrorKind::PermissionDenied => "EACCES",
38            io::ErrorKind::IsADirectory => "EISDIR",
39            io::ErrorKind::NotADirectory => "ENOTDIR",
40            _ => "EIO",
41        })
42    }
43}
44
45impl fmt::Display for Error {
46    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
47        match self {
48            Error::Invalid(message) => f.write_str(message),
49            Error::Io(e) => write!(f, "{}: {e}", self.code().unwrap_or("EIO")),
50        }
51    }
52}
53
54impl std::error::Error for Error {}
55
56impl From<io::Error> for Error {
57    fn from(e: io::Error) -> Self {
58        Error::Io(e)
59    }
60}
61
62fn invalid<T>(message: impl Into<String>) -> Result<T, Error> {
63    Err(Error::Invalid(message.into()))
64}
65
66#[derive(Clone, Debug, Default)]
67pub struct NewSessionOptions {
68    pub id: Option<String>,
69    pub parent_session: Option<String>,
70}
71
72/// `assertValidSessionId`: alphanumerics with interior `.`, `_`, `-`.
73fn assert_valid_session_id(id: &str) -> Result<(), Error> {
74    let bytes = id.as_bytes();
75    let edge_ok = |b: Option<&u8>| b.is_some_and(u8::is_ascii_alphanumeric);
76    let valid = edge_ok(bytes.first())
77        && edge_ok(bytes.last())
78        && bytes
79            .iter()
80            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-'));
81    if valid {
82        Ok(())
83    } else {
84        invalid(
85            "Session id must be non-empty, contain only alphanumeric characters, '-', '_', and '.', and start and end with an alphanumeric character",
86        )
87    }
88}
89
90/// A node of [`SessionTree`]; `children` index into [`SessionTree::nodes`].
91#[derive(Clone, Debug, PartialEq)]
92pub struct TreeNode<'a> {
93    pub entry: &'a Value,
94    pub children: Vec<usize>,
95    pub label: Option<&'a Value>,
96    pub label_timestamp: Option<&'a Value>,
97}
98
99/// `getTree()` as an arena (deep sessions stay iterative): roots are entries with a `null`,
100/// self-referencing or missing parent; children are ordered by timestamp, oldest first.
101#[derive(Clone, Debug, PartialEq)]
102pub struct SessionTree<'a> {
103    pub nodes: Vec<TreeNode<'a>>,
104    pub roots: Vec<usize>,
105}
106
107#[derive(Clone, Debug)]
108struct LabelState {
109    label: Value,
110    timestamp: Value,
111}
112
113/// `SessionManager`: entries form a tree through `id`/`parentId`; the leaf is the current position.
114/// Appends add a child of the leaf; branching moves the leaf. Persisted sessions are written only once
115/// the first assistant message exists, then appended line by line.
116pub struct SessionManager {
117    env: Box<dyn Env>,
118    session_id: String,
119    session_file: Option<String>,
120    session_dir: String,
121    cwd: String,
122    persist: bool,
123    flushed: bool,
124    file_entries: Vec<Value>,
125    by_id: IndexMap<String, usize>,
126    labels: IndexMap<String, LabelState>,
127    leaf_id: Option<Value>,
128}
129
130impl fmt::Debug for SessionManager {
131    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
132        f.debug_struct("SessionManager")
133            .field("session_id", &self.session_id)
134            .field("session_file", &self.session_file)
135            .field("leaf_id", &self.leaf_id)
136            .finish_non_exhaustive()
137    }
138}
139
140fn append_line(path: &str, entries: &[&Value]) -> io::Result<()> {
141    let mut text = String::new();
142    for entry in entries {
143        text.push_str(&jsrt::json::stringify(entry));
144        text.push('\n');
145    }
146    OpenOptions::new()
147        .append(true)
148        .create(true)
149        .open(path)?
150        .write_all(text.as_bytes())
151}
152
153fn write_all(path: &str, entries: &[Value], create_new: bool) -> io::Result<()> {
154    let mut text = String::new();
155    for entry in entries {
156        text.push_str(&jsrt::json::stringify(entry));
157        text.push('\n');
158    }
159    let mut options = OpenOptions::new();
160    options.write(true);
161    if create_new {
162        options.create_new(true);
163    } else {
164        options.create(true).truncate(true);
165    }
166    options.open(path)?.write_all(text.as_bytes())
167}
168
169fn file_timestamp(iso: &str) -> String {
170    iso.replace([':', '.'], "-")
171}
172
173impl SessionManager {
174    fn construct(
175        env: Box<dyn Env>,
176        cwd: &str,
177        session_dir: &str,
178        session_file: Option<&str>,
179        persist: bool,
180        options: Option<NewSessionOptions>,
181        preloaded: Option<Vec<Value>>,
182    ) -> Result<Self, Error> {
183        let (session_dir, cwd) = (normalize_path(&*env, session_dir), resolve_path(&*env, cwd));
184        let mut manager = SessionManager {
185            env,
186            session_id: String::new(),
187            session_file: None,
188            session_dir,
189            cwd,
190            persist,
191            flushed: false,
192            file_entries: Vec::new(),
193            by_id: IndexMap::new(),
194            labels: IndexMap::new(),
195            leaf_id: None,
196        };
197        if persist && !manager.session_dir.is_empty() && !Path::new(&manager.session_dir).exists() {
198            fs::create_dir_all(&manager.session_dir)?;
199        }
200        match (session_file, preloaded) {
201            (Some(file), preloaded) => manager.set_session_file_with(file, preloaded)?,
202            (None, Some(entries)) if !entries.is_empty() => manager.load_entries(entries, options)?,
203            _ => {
204                manager.new_session(options)?;
205            }
206        }
207        Ok(manager)
208    }
209
210    /// `create`: a new persisted session in `session_dir` (default: the cwd's dir under the agent dir).
211    pub fn create(
212        env: Box<dyn Env>,
213        cwd: &str,
214        session_dir: Option<&str>,
215        options: Option<NewSessionOptions>,
216    ) -> Result<Self, Error> {
217        let dir = match session_dir.filter(|d| !d.is_empty()) {
218            Some(dir) => normalize_path(&*env, dir),
219            None => file::default_session_dir(&*env, cwd, &env.agent_dir())?,
220        };
221        Self::construct(env, cwd, &dir, None, true, options, None)
222    }
223
224    /// `open`: a specific session file. The cwd comes from `cwd_override`, else the header, else
225    /// the process cwd; `session_dir` defaults to the file's directory.
226    pub fn open(
227        env: Box<dyn Env>,
228        path: &str,
229        session_dir: Option<&str>,
230        cwd_override: Option<&str>,
231    ) -> Result<Self, Error> {
232        let resolved = resolve_path(&*env, path);
233        let mut header = None;
234        let mut preloaded = None;
235        if cwd_override.is_none() && Path::new(&resolved).exists() {
236            match read_session_header(&resolved) {
237                Ok(found) => header = found,
238                Err(HeaderScanError::Io(e)) => return Err(e.into()),
239                // The bounded scan only speeds up discovery; a full load stays authoritative.
240                Err(HeaderScanError::ScanLimit) => {
241                    let entries = load_entries_from_file(&*env, &resolved)?;
242                    header = entries.first().filter(|e| entry_type(e) == Some("session")).cloned();
243                    preloaded = Some(entries);
244                }
245            }
246        }
247        let process_cwd = env.cwd();
248        let cwd = cwd_override
249            .or_else(|| header.as_ref().and_then(header_cwd))
250            .unwrap_or(&process_cwd)
251            .to_string();
252        let dir = session_dir
253            .filter(|d| !d.is_empty())
254            .map_or_else(|| parent(&*env, &resolved), |dir| normalize_path(&*env, dir));
255        Self::construct(env, &cwd, &dir, Some(&resolved), true, None, preloaded)
256    }
257
258    /// `inMemory`: a session that is never written, optionally adopting stored entries.
259    pub fn in_memory(
260        env: Box<dyn Env>,
261        cwd: &str,
262        options: Option<NewSessionOptions>,
263        entries: Option<Vec<Value>>,
264    ) -> Result<Self, Error> {
265        Self::construct(env, cwd, "", None, false, options, entries)
266    }
267
268    /// `forkFrom`: copies another session's entries into a new session for `target_cwd`.
269    pub fn fork_from(
270        mut env: Box<dyn Env>,
271        source_path: &str,
272        target_cwd: &str,
273        session_dir: Option<&str>,
274        options: Option<NewSessionOptions>,
275    ) -> Result<Self, Error> {
276        let source = resolve_path(&*env, source_path);
277        let target = resolve_path(&*env, target_cwd);
278        let entries = load_entries_from_file(&*env, &source)?;
279        if entries.is_empty() {
280            return invalid(format!(
281                "Cannot fork: source session file is empty or invalid: {source}"
282            ));
283        }
284        if !entries.iter().any(|e| entry_type(e) == Some("session")) {
285            return invalid(format!("Cannot fork: source session has no header: {source}"));
286        }
287        let dir = match session_dir.filter(|d| !d.is_empty()) {
288            Some(dir) => normalize_path(&*env, dir),
289            None => file::default_session_dir(&*env, &target, &env.agent_dir())?,
290        };
291        fs::create_dir_all(&dir)?;
292        let options = options.unwrap_or_default();
293        if let Some(id) = &options.id {
294            assert_valid_session_id(id)?;
295        }
296        let id = match options.id {
297            Some(id) => id,
298            None => env.session_id(),
299        };
300        let timestamp = jsrt::date::iso_string(env.now_ms());
301        let path = join(&[&dir, &format!("{}_{id}.jsonl", file_timestamp(&timestamp))]);
302        let header = json!({
303            "type": "session", "version": CURRENT_SESSION_VERSION, "id": id,
304            "timestamp": timestamp, "cwd": target, "parentSession": source,
305        });
306        write_all(&path, &[header], true)?;
307        let body: Vec<&Value> = entries.iter().filter(|e| entry_type(e) != Some("session")).collect();
308        append_line(&path, &body)?;
309        Self::construct(env, &target, &dir, Some(&path), true, None, None)
310    }
311
312    fn set_session_file_with(&mut self, session_file: &str, preloaded: Option<Vec<Value>>) -> Result<(), Error> {
313        let path = resolve_path(&*self.env, session_file);
314        self.session_file = Some(path.clone());
315        if !Path::new(&path).exists() {
316            self.new_session(None)?;
317            self.session_file = Some(path);
318            return Ok(());
319        }
320        let entries = match preloaded {
321            Some(entries) => entries,
322            None => load_entries_from_file(&*self.env, &path)?,
323        };
324        if entries.is_empty() {
325            // An empty file gets a header; any other non-session content is left untouched.
326            if fs::metadata(&path)?.len() > 0 {
327                return invalid(format!("Session file is not a valid ultron session: {path}"));
328            }
329            self.new_session(None)?;
330            self.session_file = Some(path);
331            self.rewrite_file()?;
332            self.flushed = true;
333            return Ok(());
334        }
335        self.load_entries(entries, None)?;
336        self.flushed = true;
337        Ok(())
338    }
339
340    /// `newSession`: a fresh header and no entries. Returns the new session file path (persisted only).
341    pub fn new_session(&mut self, options: Option<NewSessionOptions>) -> Result<Option<String>, Error> {
342        let options = options.unwrap_or_default();
343        if let Some(id) = &options.id {
344            assert_valid_session_id(id)?;
345        }
346        self.session_id = match options.id {
347            Some(id) => id,
348            None => self.env.session_id(),
349        };
350        let timestamp = jsrt::date::iso_string(self.env.now_ms());
351        let header = object(vec![
352            ("type", Some("session".into())),
353            ("version", Some(CURRENT_SESSION_VERSION.into())),
354            ("id", Some(self.session_id.clone().into())),
355            ("timestamp", Some(timestamp.clone().into())),
356            ("cwd", Some(self.cwd.clone().into())),
357            ("parentSession", options.parent_session.map(Value::from)),
358        ]);
359        self.file_entries = vec![header];
360        self.by_id.clear();
361        self.labels.clear();
362        self.leaf_id = None;
363        self.flushed = false;
364        if self.persist {
365            let name = format!("{}_{}.jsonl", file_timestamp(&timestamp), self.session_id);
366            self.session_file = Some(join(&[&self.session_dir, &name]));
367        }
368        Ok(self.session_file.clone())
369    }
370
371    fn load_entries(&mut self, mut entries: Vec<Value>, options: Option<NewSessionOptions>) -> Result<(), Error> {
372        match entries.iter().find(|e| entry_type(e) == Some("session")) {
373            Some(header) => {
374                self.session_id = match header.get("id") {
375                    Some(Value::String(id)) => id.clone(),
376                    other => js::join_string(other),
377                };
378                let migrated = migrate_session_entries(&mut entries, self.env.as_mut());
379                self.file_entries = entries;
380                if migrated {
381                    self.rewrite_file()?;
382                }
383            }
384            None => {
385                self.new_session(options)?;
386                self.file_entries.extend(entries);
387            }
388        }
389        self.build_index();
390        Ok(())
391    }
392
393    fn build_index(&mut self) {
394        self.by_id.clear();
395        self.labels.clear();
396        self.leaf_id = None;
397        for (i, entry) in self.file_entries.iter().enumerate() {
398            if entry_type(entry) == Some("session") {
399                continue;
400            }
401            self.by_id.insert(id_key(entry.get("id")), i);
402            self.leaf_id = entry.get("id").cloned();
403            if entry_type(entry) == Some("label") {
404                Self::apply_label(&mut self.labels, entry);
405            }
406        }
407    }
408
409    fn apply_label(labels: &mut IndexMap<String, LabelState>, entry: &Value) {
410        let key = id_key(entry.get("targetId"));
411        if jsrt::value::truthy(entry.get("label")) {
412            labels.insert(
413                key,
414                LabelState {
415                    label: entry["label"].clone(),
416                    timestamp: entry.get("timestamp").cloned().unwrap_or(Value::Null),
417                },
418            );
419        } else {
420            labels.shift_remove(&key);
421        }
422    }
423
424    fn rewrite_file(&self) -> io::Result<()> {
425        match (&self.session_file, self.persist) {
426            (Some(path), true) => write_all(path, &self.file_entries, false),
427            _ => Ok(()),
428        }
429    }
430
431    fn has_assistant(&self) -> bool {
432        self.file_entries.iter().any(|e| is_message_with_role(e, "assistant"))
433    }
434
435    /// `_persist`: nothing reaches disk until an assistant message exists; then the whole session is
436    /// written once (failing if the file already exists) and later entries are appended.
437    fn persist_entry(&mut self, index: usize) -> io::Result<()> {
438        let Some(path) = self.session_file.clone().filter(|_| self.persist) else {
439            return Ok(());
440        };
441        if !self.has_assistant() {
442            if self.flushed {
443                append_line(&path, &[&self.file_entries[index]])?;
444            }
445            return Ok(());
446        }
447        if self.flushed {
448            append_line(&path, &[&self.file_entries[index]])
449        } else {
450            write_all(&path, &self.file_entries, true)?;
451            self.flushed = true;
452            Ok(())
453        }
454    }
455
456    fn append_entry(&mut self, entry: Value) -> Result<(), Error> {
457        let index = self.file_entries.len();
458        self.by_id.insert(id_key(entry.get("id")), index);
459        self.leaf_id = entry.get("id").cloned();
460        self.file_entries.push(entry);
461        Ok(self.persist_entry(index)?)
462    }
463
464    fn new_id(&mut self) -> String {
465        let by_id = &self.by_id;
466        generate_id(self.env.as_mut(), |id| by_id.contains_key(&str_key(id)))
467    }
468
469    fn now_iso(&mut self) -> String {
470        jsrt::date::iso_string(self.env.now_ms())
471    }
472
473    /// The common `type, id, parentId, timestamp` head followed by `fields`.
474    fn entry_with(&mut self, kind: &str, fields: Vec<(&str, Option<Value>)>) -> Value {
475        let mut pairs = vec![
476            ("type", Some(Value::from(kind))),
477            ("id", Some(self.new_id().into())),
478            ("parentId", Some(self.leaf_id.clone().unwrap_or(Value::Null))),
479            ("timestamp", Some(self.now_iso().into())),
480        ];
481        pairs.extend(fields);
482        object(pairs)
483    }
484
485    fn append(&mut self, entry: Value) -> Result<String, Error> {
486        let id = entry["id"].as_str().unwrap_or_default().to_string();
487        self.append_entry(entry)?;
488        Ok(id)
489    }
490
491    /// `appendMessage`: a message entry as child of the leaf. Returns its id.
492    pub fn append_message(&mut self, message: Value) -> Result<String, Error> {
493        let entry = self.entry_with("message", vec![("message", Some(message))]);
494        self.append(entry)
495    }
496
497    /// `getSessionName`: the latest `session_info` name; empty clears it.
498    pub fn session_name(&self) -> Option<String> {
499        let entry = self
500            .entries()
501            .into_iter()
502            .rev()
503            .find(|e| entry_type(e) == Some("session_info"))?;
504        entry
505            .get("name")
506            .and_then(Value::as_str)
507            .map(jsrt::string::trim)
508            .filter(|n| !n.is_empty())
509            .map(str::to_string)
510    }
511
512    /// `branch`: moves the leaf to an earlier entry; the next append starts a new branch there.
513    pub fn branch(&mut self, branch_from_id: &str) -> Result<(), Error> {
514        let Some(entry) = self.entry(branch_from_id) else {
515            return invalid(format!("Entry {branch_from_id} not found"));
516        };
517        self.leaf_id = entry.get("id").cloned();
518        Ok(())
519    }
520
521    /// `resetLeaf`: the next append creates a new root.
522    pub fn reset_leaf(&mut self) {
523        self.leaf_id = None;
524    }
525
526    // ---- reads ----
527
528    pub fn cwd(&self) -> &str {
529        &self.cwd
530    }
531
532    pub fn session_dir(&self) -> &str {
533        &self.session_dir
534    }
535
536    pub fn session_id(&self) -> &str {
537        &self.session_id
538    }
539
540    pub fn session_file(&self) -> Option<&str> {
541        self.session_file.as_deref()
542    }
543
544    /// The leaf id; `None` before the first entry (or after `reset_leaf`).
545    pub fn leaf_id(&self) -> Option<&Value> {
546        self.leaf_id.as_ref()
547    }
548
549    fn leaf_entry(&self) -> Option<&Value> {
550        self.leaf_id
551            .as_ref()
552            .filter(|id| jsrt::value::truthy(Some(id)))
553            .and_then(|id| self.lookup(&id_key(Some(id))))
554    }
555
556    fn lookup(&self, key: &str) -> Option<&Value> {
557        self.by_id.get(key).map(|i| &self.file_entries[*i])
558    }
559
560    pub fn entry(&self, id: &str) -> Option<&Value> {
561        self.lookup(&str_key(id))
562    }
563
564    /// `getChildren`: direct children in index order.
565    pub fn children(&self, parent_id: &str) -> Vec<&Value> {
566        self.by_id
567            .values()
568            .map(|i| &self.file_entries[*i])
569            .filter(|e| e.get("parentId").and_then(Value::as_str) == Some(parent_id))
570            .collect()
571    }
572
573    pub fn label(&self, id: &str) -> Option<&Value> {
574        self.labels.get(&str_key(id)).map(|l| &l.label)
575    }
576
577    /// `getBranch`: root-first path to `from_id` (default: the leaf).
578    pub fn branch_entries(&self, from_id: Option<&str>) -> Vec<&Value> {
579        let start = match from_id {
580            Some("") => None,
581            Some(id) => self.entry(id),
582            None => self.leaf_entry(),
583        };
584        context::walk_to_root(start, self.by_id.len(), |key| self.lookup(key))
585    }
586
587    fn leaf(&self) -> Leaf<'_> {
588        self.leaf_id.as_ref().map_or(Leaf::Root, Leaf::Id)
589    }
590
591    /// `buildContextEntries` from the leaf.
592    pub fn build_context_entries(&self) -> Vec<&Value> {
593        context::context_entries(&self.entries(), self.leaf())
594    }
595
596    /// `buildSessionProjection` from the leaf.
597    pub fn build_session_projection(&self) -> SessionProjection<'_> {
598        context::session_projection(&self.entries(), self.leaf())
599    }
600
601    /// `buildSessionContext` from the leaf.
602    pub fn build_session_context(&self) -> SessionContext {
603        self.build_session_projection().into()
604    }
605
606    pub fn header(&self) -> Option<&Value> {
607        self.file_entries.iter().find(|e| entry_type(e) == Some("session"))
608    }
609
610    /// `getEntries`: every entry except headers.
611    pub fn entries(&self) -> Vec<&Value> {
612        self.file_entries
613            .iter()
614            .filter(|e| entry_type(e) != Some("session"))
615            .collect()
616    }
617
618    pub fn tree(&self) -> SessionTree<'_> {
619        let entries = self.entries();
620        let mut node_of: std::collections::HashMap<String, usize> = std::collections::HashMap::new();
621        let mut nodes: Vec<TreeNode> = entries
622            .iter()
623            .enumerate()
624            .map(|(i, entry)| {
625                let key = id_key(entry.get("id"));
626                node_of.insert(key.clone(), i);
627                let label = self.labels.get(&key);
628                TreeNode {
629                    entry,
630                    children: Vec::new(),
631                    label: label.map(|l| &l.label),
632                    label_timestamp: label.map(|l| &l.timestamp),
633                }
634            })
635            .collect();
636        let mut roots = Vec::new();
637        for entry in &entries {
638            let node = node_of[&id_key(entry.get("id"))];
639            let parent = entry.get("parentId");
640            if parent == Some(&Value::Null) || parent == entry.get("id") {
641                roots.push(node);
642            } else {
643                match node_of.get(&id_key(parent)) {
644                    Some(&p) => nodes[p].children.push(node),
645                    None => roots.push(node),
646                }
647            }
648        }
649        let times: Vec<f64> = nodes
650            .iter()
651            .map(|n| js::date_value(n.entry.get("timestamp")).map_or(f64::NAN, |t| t as f64))
652            .collect();
653        for node in &mut nodes {
654            js::sort_by(&mut node.children, |a, b| times[*a] - times[*b]);
655        }
656        SessionTree { nodes, roots }
657    }
658}