Skip to main content

session_file/
file.rs

1//! The session JSONL file: parsing, loading with repair, version migrations, header discovery,
2//! and listing sessions in a directory.
3
4use std::fs::{self, File, OpenOptions};
5use std::io::{self, BufRead, BufReader, Read, Write};
6
7use serde_json::Value;
8
9use crate::context::{entry_type, field};
10use crate::env::Env;
11use crate::js;
12use crate::paths::{normalize_path, resolve_path};
13use jsrt::path::join;
14
15pub const CURRENT_SESSION_VERSION: u64 = 3;
16/// Header discovery reads at most this many bytes before giving up on a file.
17const MAX_SESSION_HEADER_SCAN_BYTES: u64 = 1024 * 1024;
18
19/// One parsed line, as `JSON.parse` would accept it; falsy values (`null`, `0`, `false`, `""`) are skipped.
20fn parse_line(line: &str) -> Option<Value> {
21    if jsrt::string::trim(line).is_empty() {
22        return None;
23    }
24    serde_json::from_str::<Value>(line)
25        .ok()
26        .filter(|v| jsrt::value::truthy(Some(v)))
27}
28
29/// `parseSessionEntries`: every non-blank line that parses as JSON (malformed lines are skipped).
30pub fn parse_session_entries(content: &str) -> Vec<Value> {
31    jsrt::string::trim(content)
32        .split('\n')
33        .filter(|line| !jsrt::string::trim(line).is_empty())
34        .filter_map(|line| serde_json::from_str(line).ok())
35        .collect()
36}
37
38fn is_header(entry: &Value) -> bool {
39    entry_type(entry) == Some("session") && entry.get("id").is_some_and(Value::is_string)
40}
41
42fn lossy(bytes: &[u8]) -> String {
43    String::from_utf8_lossy(bytes).into_owned()
44}
45
46/// `loadEntriesFromFile`: all parsed lines of a session file, or nothing when the first parsed line
47/// is not a session header. A missing file is empty. When the file is a session whose last line
48/// lacks a newline, a newline is appended so the next append starts a new line.
49pub fn load_entries_from_file(env: &dyn Env, path: &str) -> io::Result<Vec<Value>> {
50    let path = normalize_path(env, path);
51    let file = match File::open(&path) {
52        Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
53        other => other?,
54    };
55    let mut reader = BufReader::with_capacity(1024 * 1024, file);
56    let mut entries = Vec::new();
57    let mut line = Vec::new();
58    let mut pending = false;
59    loop {
60        line.clear();
61        if reader.read_until(b'\n', &mut line)? == 0 {
62            break;
63        }
64        let complete = line.last() == Some(&b'\n');
65        let text = lossy(if complete { &line[..line.len() - 1] } else { &line });
66        pending = !complete;
67        entries.extend(parse_line(&text));
68    }
69    if entries.first().is_none_or(|header| !is_header(header)) {
70        return Ok(Vec::new());
71    }
72    if pending {
73        OpenOptions::new().append(true).open(&path)?.write_all(b"\n")?;
74    }
75    Ok(entries)
76}
77
78/// Why a bounded header scan stopped without an answer.
79#[derive(Debug)]
80pub enum HeaderScanError {
81    Io(io::Error),
82    /// The first parsed line did not end within [`MAX_SESSION_HEADER_SCAN_BYTES`].
83    ScanLimit,
84}
85
86/// `undefined` (keep scanning), `null` (not a session), or the header.
87fn header_candidate(line: &[u8]) -> Option<Option<Value>> {
88    let entry = parse_line(&lossy(line))?;
89    Some(is_header(&entry).then_some(entry))
90}
91
92/// `readSessionHeader`: the header from the first parsed line, reading at most
93/// [`MAX_SESSION_HEADER_SCAN_BYTES`] (plus one byte to tell a file that ends there from a longer one).
94pub fn read_session_header(path: &str) -> Result<Option<Value>, HeaderScanError> {
95    let mut file = File::open(path).map_err(HeaderScanError::Io)?;
96    let mut reader = BufReader::new((&mut file).take(MAX_SESSION_HEADER_SCAN_BYTES));
97    let mut line = Vec::new();
98    loop {
99        line.clear();
100        reader.read_until(b'\n', &mut line).map_err(HeaderScanError::Io)?;
101        if line.last() == Some(&b'\n') {
102            if let Some(header) = header_candidate(&line[..line.len() - 1]) {
103                return Ok(header);
104            }
105            continue;
106        }
107        let mut probe = [0u8; 1];
108        let at_limit = reader.into_inner().limit() == 0;
109        if at_limit && file.read(&mut probe).map_err(HeaderScanError::Io)? != 0 {
110            return Err(HeaderScanError::ScanLimit);
111        }
112        return Ok(header_candidate(&line).flatten());
113    }
114}
115
116/// Discovery is best-effort: unreadable or oversized files are not sessions.
117pub(crate) fn discovery_header(path: &str) -> Option<Value> {
118    read_session_header(path).ok().flatten()
119}
120
121pub(crate) fn header_cwd(header: &Value) -> Option<&str> {
122    header.get("cwd").and_then(Value::as_str)
123}
124
125pub(crate) fn cwd_matches(env: &dyn Env, cwd: Option<&str>, resolved_cwd: &str) -> bool {
126    cwd.is_some_and(|cwd| !cwd.is_empty() && resolve_path(env, cwd) == resolved_cwd)
127}
128
129/// File names in a directory in byte order, as Node's `readdir` (libuv scandir) returns them.
130pub(crate) fn read_dir_sorted(dir: &str) -> io::Result<Vec<String>> {
131    let mut names: Vec<String> = fs::read_dir(dir)?
132        .map(|e| e.map(|e| e.file_name().to_string_lossy().into_owned()))
133        .collect::<io::Result<_>>()?;
134    names.sort();
135    Ok(names)
136}
137
138fn mtime_ms(meta: &fs::Metadata) -> io::Result<f64> {
139    Ok(jsrt::date::mtime_ms(meta.modified()?))
140}
141
142/// `findMostRecentSession`: the most recently modified `.jsonl` session in `dir`, optionally only
143/// sessions started in `cwd`. Any directory or stat error makes the lookup unavailable (`None`).
144pub fn find_most_recent_session(env: &dyn Env, dir: &str, cwd: Option<&str>) -> Option<String> {
145    let dir = normalize_path(env, dir);
146    let resolved_cwd = cwd.filter(|c| !c.is_empty()).map(|cwd| resolve_path(env, cwd));
147    let mut files = Vec::new();
148    for name in read_dir_sorted(&dir).ok()? {
149        if name.ends_with(".jsonl") {
150            let path = join(&[&dir, &name]);
151            let mtime = mtime_ms(&fs::metadata(&path).ok()?).ok()?;
152            files.push((path, mtime));
153        }
154    }
155    js::sort_by(&mut files, |a, b| b.1 - a.1);
156    files.into_iter().map(|(path, _)| path).find(|path| {
157        discovery_header(path).is_some_and(|header| {
158            resolved_cwd
159                .as_deref()
160                .is_none_or(|resolved| cwd_matches(env, header_cwd(&header), resolved))
161        })
162    })
163}
164
165/// Generates an 8-character entry id not in use (`generateId`); after 100 collisions, a full UUID.
166pub(crate) fn generate_id(env: &mut dyn Env, in_use: impl Fn(&str) -> bool) -> String {
167    for _ in 0..100 {
168        let id: String = env.random_uuid().chars().take(8).collect();
169        if !in_use(&id) {
170            return id;
171        }
172    }
173    env.random_uuid()
174}
175
176/// v1 → v2: give every entry an id and chain `parentId`s in file order; compaction
177/// `firstKeptEntryIndex` (an index into the file) becomes `firstKeptEntryId`.
178fn migrate_v1_to_v2(entries: &mut [Value], env: &mut dyn Env) {
179    let mut prev: Option<Value> = None;
180    for i in 0..entries.len() {
181        let Value::Object(entry) = &mut entries[i] else {
182            continue;
183        };
184        if entry.get("type").and_then(Value::as_str) == Some("session") {
185            entry.insert("version".into(), 2.into());
186            continue;
187        }
188        // Upstream checks new ids against a set it never fills, so the first candidate always wins.
189        let id = Value::from(generate_id(env, |_| false));
190        entry.insert("id".into(), id.clone());
191        entry.insert("parentId".into(), prev.replace(id).unwrap_or(Value::Null));
192        if entry.get("type").and_then(Value::as_str) != Some("compaction") {
193            continue;
194        }
195        let Some(index) = entry.get("firstKeptEntryIndex").and_then(Value::as_f64) else {
196            continue;
197        };
198        let target = (index >= 0.0 && index.fract() == 0.0)
199            .then(|| entries.get(index as usize))
200            .flatten()
201            .filter(|t| entry_type(t) != Some("session"))
202            .map(|t| t.get("id").cloned());
203        let Value::Object(entry) = &mut entries[i] else {
204            continue;
205        };
206        match target {
207            // The target's id is `undefined` until it is migrated, which drops the field.
208            Some(Some(id)) => {
209                entry.insert("firstKeptEntryId".into(), id);
210            }
211            Some(None) => {
212                entry.shift_remove("firstKeptEntryId");
213            }
214            None => {}
215        }
216        entry.shift_remove("firstKeptEntryIndex");
217    }
218}
219
220/// v2 → v3: the `hookMessage` role is now `custom`.
221fn migrate_v2_to_v3(entries: &mut [Value]) {
222    for entry in entries.iter_mut() {
223        match entry_type(entry) {
224            Some("session") => entry["version"] = 3.into(),
225            Some("message") => {
226                if let Some(Value::Object(message)) = entry.get_mut("message")
227                    && message.get("role").and_then(Value::as_str) == Some("hookMessage")
228                {
229                    message.insert("role".into(), "custom".into());
230                }
231            }
232            _ => {}
233        }
234    }
235}
236
237/// `migrateToCurrentVersion`: brings entries to [`CURRENT_SESSION_VERSION`] in place. The version
238/// comes from the first header (absent: 1). Returns whether anything ran.
239pub fn migrate_session_entries(entries: &mut [Value], env: &mut dyn Env) -> bool {
240    let header = entries.iter().find(|e| entry_type(e) == Some("session"));
241    let version = match header.and_then(|h| h.get("version")) {
242        None | Some(Value::Null) => 1.0,
243        Some(v) => jsrt::value::number(v),
244    };
245    // NaN compares false everywhere: such a header reports a migration that changes nothing.
246    if version >= CURRENT_SESSION_VERSION as f64 {
247        return false;
248    }
249    if version < 2.0 {
250        migrate_v1_to_v2(entries, env);
251    }
252    if version < 3.0 {
253        migrate_v2_to_v3(entries);
254    }
255    true
256}
257
258#[derive(Clone, Debug, PartialEq)]
259pub struct SessionInfo {
260    pub path: String,
261    pub id: String,
262    /// Working directory the session started in; empty for old sessions.
263    pub cwd: String,
264    pub name: Option<String>,
265    pub parent_session_path: Option<String>,
266    /// Header timestamp in ms; `None` for an invalid date.
267    pub created: Option<i64>,
268    /// Latest user/assistant activity, else the header time, else the file mtime (ms).
269    pub modified: Option<i64>,
270    pub message_count: usize,
271    pub first_message: String,
272    pub all_messages_text: String,
273}
274
275fn text_content(content: Option<&Value>) -> Option<String> {
276    match content? {
277        Value::String(s) => Some(s.clone()),
278        Value::Array(blocks) => {
279            let mut texts = Vec::new();
280            for block in blocks {
281                let Value::Object(block) = block else { return None };
282                if block.get("type").and_then(Value::as_str) == Some("text") {
283                    texts.push(js::join_string(block.get("text")));
284                }
285            }
286            Some(texts.join(" "))
287        }
288        _ => None,
289    }
290}
291
292/// `buildSessionInfo`. `None` when the file is not a session or holds data upstream would throw on.
293fn build_session_info(path: &str, mtime: Option<f64>) -> Option<SessionInfo> {
294    let mtime = match mtime {
295        Some(m) => m,
296        None => mtime_ms(&fs::metadata(path).ok()?).ok()?,
297    };
298    let mut reader = BufReader::new(File::open(path).ok()?);
299    let mut header: Option<Value> = None;
300    let (mut message_count, mut first_message, mut all_messages) = (0, String::new(), Vec::new());
301    let mut name = None;
302    let mut last_activity: Option<f64> = None;
303    let mut buf = Vec::new();
304    loop {
305        buf.clear();
306        if reader.read_until(b'\n', &mut buf).ok()? == 0 {
307            break;
308        }
309        let chunk = buf.strip_suffix(b"\n").unwrap_or(&buf);
310        // readline with crlfDelay: Infinity ends lines at \n, \r\n and a lone \r.
311        for raw in chunk.split(|b| *b == b'\r') {
312            let Some(entry) = parse_line(&lossy(raw)) else { continue };
313            if header.is_none() {
314                if entry_type(&entry) != Some("session") {
315                    return None;
316                }
317                header = Some(entry);
318                continue;
319            }
320            match entry_type(&entry) {
321                Some("session_info") => {
322                    name = match entry.get("name") {
323                        None | Some(Value::Null) => None,
324                        Some(Value::String(n)) => Some(jsrt::string::trim(n).to_string()).filter(|n| !n.is_empty()),
325                        Some(_) => return None,
326                    };
327                    continue;
328                }
329                Some("message") => {}
330                _ => continue,
331            }
332            message_count += 1;
333            let message = match entry.get("message") {
334                // Upstream throws reading `role` of a missing message, which drops the file.
335                None | Some(Value::Null) => return None,
336                Some(Value::Object(message)) => message,
337                Some(_) => continue,
338            };
339            if !(message.get("role").is_some_and(Value::is_string) && message.contains_key("content")) {
340                continue;
341            }
342            let role = message.get("role").and_then(Value::as_str);
343            if !matches!(role, Some("user" | "assistant")) {
344                continue;
345            }
346            let activity = match message.get("timestamp") {
347                Some(Value::Number(n)) => n.as_f64(),
348                _ => js::date_value(entry.get("timestamp")).map(|t| t as f64),
349            };
350            if let Some(t) = activity {
351                last_activity = Some(last_activity.unwrap_or(0.0).max(t));
352            }
353            let text = text_content(message.get("content"))?;
354            if text.is_empty() {
355                continue;
356            }
357            if first_message.is_empty() && role == Some("user") {
358                first_message.clone_from(&text);
359            }
360            all_messages.push(text);
361        }
362    }
363    let header = header?;
364    let header_time = match header.get("timestamp") {
365        Some(Value::String(s)) => jsrt::date::parse_date(s),
366        _ => None,
367    };
368    let modified = match last_activity {
369        Some(t) if t > 0.0 => jsrt::date::time_clip(t),
370        _ => header_time.or_else(|| jsrt::date::time_clip(mtime)),
371    };
372    Some(SessionInfo {
373        path: path.to_string(),
374        // ponytail: a non-string header id is listed by upstream; skip such files here.
375        id: header.get("id")?.as_str()?.to_string(),
376        cwd: header_cwd(&header).unwrap_or_default().to_string(),
377        name,
378        parent_session_path: header.get("parentSession").and_then(Value::as_str).map(str::to_string),
379        created: js::date_value(header.get("timestamp")),
380        modified,
381        message_count,
382        first_message: if first_message.is_empty() {
383            "(no messages)".to_string()
384        } else {
385            first_message
386        },
387        all_messages_text: all_messages.join(" "),
388    })
389}
390
391fn sort_session_infos(sessions: &mut [SessionInfo]) {
392    let ms = |t: Option<i64>| t.map_or(f64::NAN, |t| t as f64);
393    js::sort_by(sessions, |a, b| ms(b.modified) - ms(a.modified));
394}
395
396/// `listSessionsFromDir`: every session in `dir`, in reverse file-name order (unsorted by activity).
397fn list_dir(dir: &str) -> Vec<SessionInfo> {
398    let Ok(mut names) = read_dir_sorted(dir) else {
399        return Vec::new();
400    };
401    names.retain(|n| n.ends_with(".jsonl"));
402    names.sort_by(|a, b| jsrt::collate::locale_compare(b, a));
403    names
404        .iter()
405        .filter_map(|name| build_session_info(&join(&[dir, name]), None))
406        .collect()
407}
408
409/// A cwd as a session directory name: `--<cwd without its leading slash, / \\ : as ->--`.
410fn encode_cwd(cwd: &str) -> String {
411    let trimmed = cwd.strip_prefix(['/', '\\']).unwrap_or(cwd);
412    format!("--{}--", trimmed.replace(['/', '\\', ':'], "-"))
413}
414
415/// `getDefaultSessionDir` without creating it: `<agent>/sessions/<encoded resolved cwd>`.
416pub fn default_session_dir_path(env: &dyn Env, cwd: &str, agent_dir: &str) -> String {
417    join(&[
418        &resolve_path(env, agent_dir),
419        "sessions",
420        &encode_cwd(&resolve_path(env, cwd)),
421    ])
422}
423
424/// `migrateSessionsFromAgentRoot` (src/migrations.ts): v0.30.0 wrote sessions straight into the
425/// agent dir; move each `<agent>/*.jsonl` whose first line is a header with a cwd into that cwd's
426/// session dir. Files that do not qualify, or whose target exists, stay where they are.
427pub fn migrate_sessions_from_agent_root(agent_dir: &str) {
428    let Ok(names) = read_dir_sorted(agent_dir) else { return };
429    for name in names.into_iter().filter(|n| n.ends_with(".jsonl")) {
430        let _ = move_root_session(agent_dir, &name);
431    }
432}
433
434fn move_root_session(agent_dir: &str, name: &str) -> Option<()> {
435    let file = join(&[agent_dir, name]);
436    let content = lossy(&fs::read(&file).ok()?);
437    let first_line = content
438        .split('\n')
439        .next()
440        .filter(|l| !jsrt::string::trim(l).is_empty())?;
441    let header: Value = serde_json::from_str(first_line).ok()?;
442    if entry_type(&header) != Some("session") {
443        return None;
444    }
445    // The header cwd is used as written (not resolved); a falsy or non-string cwd is skipped.
446    let cwd = header.get("cwd")?.as_str().filter(|c| !c.is_empty())?;
447    let dir = join(&[agent_dir, "sessions", &encode_cwd(cwd)]);
448    fs::create_dir_all(&dir).ok()?;
449    let target = join(&[&dir, name]);
450    if fs::exists(&target).unwrap_or(false) {
451        return None;
452    }
453    fs::rename(&file, &target).ok()
454}
455
456/// `getDefaultSessionDir`: the default session directory for `cwd`, created if missing.
457pub fn default_session_dir(env: &dyn Env, cwd: &str, agent_dir: &str) -> io::Result<String> {
458    let dir = default_session_dir_path(env, cwd, agent_dir);
459    fs::create_dir_all(&dir)?;
460    Ok(dir)
461}
462
463/// The directory a static lookup uses, and whether it must filter sessions by cwd: a custom
464/// directory other than the cwd's default holds sessions from many projects.
465pub(crate) fn lookup_dir(env: &dyn Env, cwd: &str, session_dir: Option<&str>) -> io::Result<(String, bool)> {
466    let agent_dir = env.agent_dir();
467    Ok(match session_dir {
468        Some(dir) => {
469            let dir = normalize_path(env, dir);
470            let filter = dir != default_session_dir_path(env, cwd, &agent_dir);
471            (dir, filter)
472        }
473        None => (default_session_dir(env, cwd, &agent_dir)?, false),
474    })
475}
476
477/// `SessionManager.list`: sessions for `cwd`, newest activity first.
478pub fn list_sessions(env: &dyn Env, cwd: &str, session_dir: Option<&str>) -> io::Result<Vec<SessionInfo>> {
479    let (dir, filter) = lookup_dir(env, cwd, session_dir)?;
480    let resolved_cwd = resolve_path(env, cwd);
481    let mut sessions = list_dir(&dir);
482    sessions.retain(|s| !filter || cwd_matches(env, Some(&s.cwd), &resolved_cwd));
483    sort_session_infos(&mut sessions);
484    Ok(sessions)
485}
486
487/// `SessionManager.listAll`: every session in a flat `session_dir`, or with `None` in every
488/// project directory under `<agent>/sessions`; newest activity first.
489pub fn list_all_sessions(env: &dyn Env, session_dir: Option<&str>) -> Vec<SessionInfo> {
490    if let Some(dir) = session_dir {
491        let mut sessions = list_dir(&normalize_path(env, dir));
492        sort_session_infos(&mut sessions);
493        return sessions;
494    }
495    let sessions_dir = join(&[&env.agent_dir(), "sessions"]);
496    let Ok(dirs) = read_dir_sorted(&sessions_dir) else {
497        return Vec::new();
498    };
499    let mut candidates: Vec<(String, Option<f64>)> = Vec::new();
500    for name in dirs {
501        let dir = join(&[&sessions_dir, &name]);
502        let is_dir = fs::symlink_metadata(&dir).is_ok_and(|m| m.is_dir() || m.file_type().is_symlink());
503        if !is_dir {
504            continue;
505        }
506        for file in read_dir_sorted(&dir)
507            .unwrap_or_default()
508            .into_iter()
509            .filter(|f| f.ends_with(".jsonl"))
510        {
511            let path = join(&[&dir, &file]);
512            let mtime = fs::metadata(&path).ok().and_then(|m| mtime_ms(&m).ok());
513            candidates.push((path, mtime));
514        }
515    }
516    let base = |p: &str| p.rsplit('/').next().unwrap_or(p).to_string();
517    js::sort_by(&mut candidates, |a, b| {
518        let by_mtime = b.1.unwrap_or(f64::NEG_INFINITY) - a.1.unwrap_or(f64::NEG_INFINITY);
519        if by_mtime != 0.0 && !by_mtime.is_nan() {
520            return by_mtime;
521        }
522        match jsrt::collate::locale_compare(&base(&b.0), &base(&a.0)) {
523            std::cmp::Ordering::Less => -1.0,
524            std::cmp::Ordering::Equal => 0.0,
525            std::cmp::Ordering::Greater => 1.0,
526        }
527    });
528    let mut sessions: Vec<SessionInfo> = candidates
529        .into_iter()
530        .filter_map(|(path, mtime)| build_session_info(&path, mtime))
531        .collect();
532    sort_session_infos(&mut sessions);
533    sessions
534}
535
536/// `SessionManager.findById`: the file whose header has exactly `id`, without reading bodies.
537pub fn find_session_by_id(env: &dyn Env, cwd: &str, id: &str, session_dir: Option<&str>) -> Option<String> {
538    let (dir, filter) = lookup_dir(env, cwd, session_dir).ok()?;
539    let resolved_cwd = resolve_path(env, cwd);
540    read_dir_sorted(&dir)
541        .ok()?
542        .into_iter()
543        .filter(|f| f.ends_with(".jsonl"))
544        .find_map(|file| {
545            let path = join(&[&dir, &file]);
546            let header = discovery_header(&path)?;
547            let matches = field(&header, "id").and_then(Value::as_str) == Some(id)
548                && (!filter || cwd_matches(env, header_cwd(&header), &resolved_cwd));
549            matches.then_some(path)
550        })
551}