1use 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#[derive(Debug)]
25pub enum Error {
26 Invalid(String),
27 Io(io::Error),
28}
29
30impl Error {
31 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
72fn 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#[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#[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
113pub 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 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 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 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 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 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(×tamp))]);
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 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 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(×tamp), 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 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 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 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 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 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 pub fn reset_leaf(&mut self) {
523 self.leaf_id = None;
524 }
525
526 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 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 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 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 pub fn build_context_entries(&self) -> Vec<&Value> {
593 context::context_entries(&self.entries(), self.leaf())
594 }
595
596 pub fn build_session_projection(&self) -> SessionProjection<'_> {
598 context::session_projection(&self.entries(), self.leaf())
599 }
600
601 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 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}