Initial public release

Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
Evan Whittaker
2026-10-17 12:08:30 -05:00
commit 09a7de2520
1730 changed files with 412952 additions and 0 deletions

View File

@@ -0,0 +1,148 @@
//! Entry — one node of a session's tree, as it is written to disk and read back.
use super::*;
/// What kind of entry is stored.
///
/// Not `Eq`: a usage entry carries a floating-point cost.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", content = "data", rename_all = "snake_case")]
pub enum EntryKind {
/// Session header: cwd + creation timestamp.
Header { cwd: String, created: i64 },
/// A conversation message.
Message(Message),
/// Model switch.
ModelChange(ModelRef),
/// Compaction summary.
Compaction { summary: String, first_kept: EntryId, tokens_before: u64 },
/// Branch point summary.
BranchSummary { summary: String, from: EntryId },
/// What one provider call cost.
///
/// Written for every call the process makes, so resuming a session continues its tally instead
/// of restarting at zero, and a disputed figure has line-by-line evidence behind it. Inert for
/// context assembly: only [`EntryKind::Message`] reaches the model.
Usage {
/// Which part of the harness made the call.
source: crate::usage::UsageSource,
/// The model that served it, for a per-model breakdown.
model: String,
/// The call's tokens and cost.
totals: crate::usage::UsageTotals,
},
/// What one cache-warming call cost ([`crate::cache_warming`]).
///
/// A kind of its own rather than a [`EntryKind::Usage`] with a new source, because a source an
/// older Luxe can't parse fails that entry as corrupt and takes the whole session load with it,
/// while an unknown *kind* degrades to [`EntryKind::Unknown`] and is skipped. Inert for context
/// assembly, and counted under [`crate::usage::UsageSource::CacheWarm`] on resume.
CacheWarm {
/// The model whose cache was kept warm
model: String,
/// The call's tokens and cost
totals: crate::usage::UsageTotals,
},
/// This session worked on a pull request: opened it, pushed to it, or answered its threads.
///
/// Inert for context assembly, like [`EntryKind::Usage`]; it is what `luxe --from-pr` finds.
PullRequestLink {
/// Number within its repository.
number: u64,
/// Its web address, which names the repository.
url: String,
},
/// This session took up an issue as its brief.
///
/// Inert for context assembly; what a pull request opened from the session closes.
IssueLink {
/// Number within its repository.
number: u64,
/// Its web address.
url: String,
},
/// This session works in a worktree of its own, on this branch.
///
/// Inert for context assembly. Resuming the session re-enters the worktree — made again from
/// the branch if it was deleted — before the engine starts.
Worktree {
/// The branch
branch: String,
/// Where the worktree was, relative to the project
path: String,
},
/// An entry written by a newer Luxe than this one.
///
/// A session log is append-only and shared across versions, so an unrecognized kind must not
/// make the whole transcript unreadable. It is kept (never rewritten) so the parent chain —
/// and therefore resume — survives, and ignored everywhere else.
#[serde(other)]
Unknown,
}
/// A single node in the session tree.
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct Entry {
/// Unique ID for this entry.
pub id: EntryId,
/// Parent entry ID (None for the root/header).
pub parent_id: Option<EntryId>,
/// Unix timestamp (seconds) when this entry was created.
pub ts: i64,
/// The entry's payload.
pub kind: EntryKind,
}
/// Reads an entry, degrading an unrecognized `kind` to [`EntryKind::Unknown`] instead of failing.
///
/// Hand-written because the derive cannot deliver what [`EntryKind::Unknown`] promises.
/// `#[serde(other)]` may only sit on a *unit* variant, and in an adjacently tagged enum serde will
/// only match one when the content field is absent — so `{"kind":"future","data":{…}}`, which is
/// what a newer Luxe actually writes, failed the whole load and took every earlier entry with it.
///
/// The retry below is what separates "a kind we have never heard of" from "a kind we know, written
/// wrong". Every known variant carries fields, so stripping `data` and trying again can only
/// succeed for an unknown tag; a corrupt known entry fails both attempts and reports its original
/// error, which keeps real corruption loud.
impl<'de> Deserialize<'de> for Entry {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
#[derive(Deserialize)]
struct Raw {
id: EntryId,
parent_id: Option<EntryId>,
ts: i64,
kind: serde_json::Value,
}
let raw = Raw::deserialize(deserializer)?;
let kind = match serde_json::from_value::<EntryKind>(raw.kind.clone()) {
Ok(kind) => kind,
Err(known_shape_error) => {
let mut bare = raw.kind;
if let Some(object) = bare.as_object_mut() {
object.remove("data");
}
serde_json::from_value::<EntryKind>(bare)
.map_err(|_| serde::de::Error::custom(known_shape_error))?
}
};
Ok(Entry { id: raw.id, parent_id: raw.parent_id, ts: raw.ts, kind })
}
}
/// The entry a resume should chain from: the newest one nothing else claims as its parent.
///
/// Not simply the last line written. A session log is append-only and holds *every* branch, and it
/// now also holds inert usage records, so "last written" and "tip of the conversation" stopped
/// being the same question. Resuming from a non-leaf walks a path that stops early — and an entry
/// whose parent chain is shorter than the transcript silently discards the work after it.
pub fn latest_leaf(entries: &[Entry]) -> Option<EntryId> {
let claimed: std::collections::HashSet<&EntryId> =
entries.iter().filter_map(|entry| entry.parent_id.as_ref()).collect();
entries
.iter()
.rev()
.find(|entry| !claimed.contains(&entry.id))
.or_else(|| entries.last())
.map(|entry| entry.id.clone())
}

View File

@@ -0,0 +1,208 @@
//! JSONL — the store that keeps each session as one JSON object per line.
use super::*;
/// In-memory index of sessions for fast lookup.
#[derive(Debug, Default)]
struct SessionIndex {
/// session_id -> (path to .jsonl file, last entry id)
sessions: HashMap<SessionId, (PathBuf, Option<EntryId>)>,
}
/// JSONL-backed session store with an injectable root directory.
pub struct JsonlSessionStore {
/// Root directory for session storage.
root: PathBuf,
/// Index of known sessions.
index: SessionIndex,
/// Project hash for directory naming (derived from cwd).
project_hash: String,
}
impl JsonlSessionStore {
/// Create a new store rooted at `root`, scanning for existing sessions.
pub fn new(root: impl Into<PathBuf>) -> Self {
let root = root.into();
let mut store = Self { root, index: SessionIndex::default(), project_hash: String::new() };
store.scan_for_sessions();
store
}
/// Set the project hash (derived from cwd in production).
pub fn set_project_hash(&mut self, hash: &str) {
self.project_hash = hash.to_string();
// Rescan with the new project hash.
self.scan_for_sessions();
}
/// Scan the filesystem for existing session files and rebuild the index.
fn scan_for_sessions(&mut self) {
let project_dir = self.root.join(&self.project_hash);
if !project_dir.exists() {
return;
}
if let Ok(entries) = fs::read_dir(&project_dir) {
for entry in entries.flatten() {
let path = entry.path();
if path.extension().is_some_and(|ext| ext == "jsonl") {
if let Some(stem) = path.file_stem().and_then(|s| s.to_str()) {
let session_id = SessionId(stem.to_string());
self.index.sessions.insert(session_id, (path, None));
}
}
}
}
}
/// Get the directory for a session.
pub(super) fn session_dir(&self, session_id: &SessionId) -> PathBuf {
self.root.join(&self.project_hash).join(format!("{}.jsonl", session_id.0))
}
/// Get current timestamp in seconds.
fn now(&self) -> i64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap_or_default()
.as_secs() as i64
}
/// List all known session IDs (for the session picker).
pub fn list_sessions(&self) -> Vec<SessionId> {
self.index.sessions.keys().cloned().collect()
}
/// Path to a session's `.jsonl` file, if the store knows the session.
pub fn session_path(&self, session: &SessionId) -> Option<PathBuf> {
self.index.sessions.get(session).map(|(path, _)| path.clone())
}
/// The most recently modified session for the active project, if any.
///
/// Used by `--continue` to resume where the user left off.
pub fn most_recent_session(&self) -> Option<SessionId> {
self.modified_sessions().max_by_key(|(_, modified)| *modified).map(|(id, _)| id)
}
/// Every known session with when its file last changed, skipping one whose file is gone.
fn modified_sessions(&self) -> impl Iterator<Item = (SessionId, SystemTime)> + '_ {
self.index.sessions.iter().filter_map(|(id, (path, _))| {
let modified = path.metadata().ok()?.modified().ok()?;
Some((id.clone(), modified))
})
}
}
impl SessionStore for JsonlSessionStore {
fn create(&mut self, cwd: &str) -> Result<SessionId, SessionError> {
let session_id = SessionId::new();
let dir = self.session_dir(&session_id);
if let Some(parent) = dir.parent() {
fs::create_dir_all(parent)?;
}
let header = Entry {
id: EntryId::new(),
parent_id: None,
ts: self.now(),
kind: EntryKind::Header { cwd: cwd.to_string(), created: self.now() },
};
let file = fs::File::create(&dir)?;
let mut writer = io::BufWriter::new(file);
writeln!(
writer,
"{}",
serde_json::to_string(&header).map_err(SessionError::JsonSerialize)?
)?;
writer.flush()?;
self.index.sessions.insert(session_id.clone(), (dir, Some(header.id.clone())));
Ok(session_id)
}
fn append(
&mut self,
session: &SessionId,
parent: Option<EntryId>,
kind: EntryKind,
) -> Result<EntryId, SessionError> {
let (path, _) =
self.index.sessions.get(session).ok_or(SessionError::NotFound(session.clone()))?;
let entry = Entry { id: EntryId::new(), parent_id: parent, ts: self.now(), kind };
let file = fs::OpenOptions::new().append(true).open(path)?;
let mut writer = io::BufWriter::new(file);
writeln!(
writer,
"{}",
serde_json::to_string(&entry).map_err(SessionError::JsonSerialize)?
)?;
writer.flush()?;
if let Some(entry_info) = self.index.sessions.get_mut(session) {
entry_info.1 = Some(entry.id.clone());
}
Ok(entry.id)
}
fn load(&self, session: &SessionId) -> Result<Vec<Entry>, SessionError> {
let (path, _) =
self.index.sessions.get(session).ok_or(SessionError::NotFound(session.clone()))?;
let file = fs::File::open(path)?;
let reader = io::BufReader::new(file);
let mut entries = Vec::new();
for (line_num, line) in reader.lines().enumerate() {
let line = line?;
if line.is_empty() {
continue;
}
let entry: Entry = serde_json::from_str(&line)
.map_err(|e| SessionError::JsonParse { line: line_num + 1, error: e })?;
entries.push(entry);
}
Ok(entries)
}
fn active_path(&self, session: &SessionId, leaf: &EntryId) -> Result<Vec<Entry>, SessionError> {
let entries = self.load(session)?;
let by_id: HashMap<&EntryId, &Entry> = entries.iter().map(|e| (&e.id, e)).collect();
let mut path = Vec::new();
let mut current_id: Option<&EntryId> = Some(leaf);
while let Some(id) = current_id {
let entry = by_id.get(id).ok_or(SessionError::EntryNotFound(id.clone()))?;
path.push((*entry).clone());
current_id = entry.parent_id.as_ref();
}
// Reverse to get root-to-leaf order.
path.reverse();
Ok(path)
}
fn list_sessions(&self) -> Vec<SessionId> {
JsonlSessionStore::list_sessions(self)
}
fn most_recent_session(&self) -> Option<SessionId> {
JsonlSessionStore::most_recent_session(self)
}
fn recent_sessions(&self, limit: usize) -> Vec<(SessionId, SystemTime)> {
let mut sorted: Vec<_> = self.modified_sessions().collect();
sorted.sort_by_key(|b| std::cmp::Reverse(b.1));
sorted.truncate(limit);
sorted
}
}

View File

@@ -0,0 +1,53 @@
//! Links — the pull request, issue and worktree a session recorded working on.
use super::*;
/// The newest of `sessions` — given newest first — that worked on pull request `number`.
///
/// A session unreadable for any reason is passed over: finding the right one is worth more than
/// stopping at a damaged one.
pub fn session_for_pull_request(
store: &dyn SessionStore,
sessions: &[SessionId],
number: u64,
) -> Option<SessionId> {
sessions
.iter()
.find(|session| {
store.load(session).is_ok_and(|entries| {
entries.iter().any(|entry| {
matches!(&entry.kind, EntryKind::PullRequestLink { number: linked, .. } if *linked == number)
})
})
})
.cloned()
}
/// The issue a session took up as its brief, the last one it recorded.
pub fn session_issue(entries: &[Entry]) -> Option<u64> {
entries.iter().rev().find_map(|entry| match &entry.kind {
EntryKind::IssueLink { number, .. } => Some(*number),
_ => None,
})
}
/// The worktree branch a session works on, the last one it recorded.
pub fn session_worktree(entries: &[Entry]) -> Option<String> {
entries.iter().rev().find_map(|entry| match &entry.kind {
EntryKind::Worktree { branch, .. } => Some(branch.clone()),
_ => None,
})
}
/// The pull requests a session worked on, in the order it first did.
pub fn linked_pull_requests(entries: &[Entry]) -> Vec<u64> {
let mut linked = Vec::new();
for entry in entries {
if let EntryKind::PullRequestLink { number, .. } = &entry.kind {
if !linked.contains(number) {
linked.push(*number);
}
}
}
linked
}

View File

@@ -0,0 +1,464 @@
#![allow(clippy::unwrap_used)]
use super::*;
use std::path::PathBuf;
fn temp_root() -> PathBuf {
let dir = std::env::temp_dir().join("luxe-test-sessions");
let hash = Uuid::new_v4().to_string();
dir.join(hash)
}
#[test]
fn session_id_new_is_unique() {
let a = SessionId::new();
let b = SessionId::new();
assert_ne!(a, b);
}
#[test]
fn entry_id_new_is_unique() {
let a = EntryId::new();
let b = EntryId::new();
assert_ne!(a, b);
}
#[test]
fn create_session_writes_header() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("test-project");
let session = store.create("/tmp/test").unwrap();
// Verify the file exists.
let path = store.session_dir(&session);
assert!(path.exists());
// Load and verify header.
let entries = store.load(&session).unwrap();
assert_eq!(entries.len(), 1);
match &entries[0].kind {
EntryKind::Header { cwd, created } => {
assert_eq!(cwd, "/tmp/test");
assert!(*created > 0);
}
_ => panic!("expected header entry"),
}
fs::remove_dir_all(root).ok();
}
#[test]
fn append_and_load() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("test-project");
let session = store.create("/tmp/test").unwrap();
// Append a user message.
let msg = Message::user("hello");
let parent = store.append(&session, None, EntryKind::Message(msg.clone())).unwrap();
// Append an assistant reply.
let reply = Message::assistant("hi there");
store.append(&session, Some(parent), EntryKind::Message(reply)).unwrap();
// Load and verify.
let entries = store.load(&session).unwrap();
assert_eq!(entries.len(), 3); // header + 2 messages
match &entries[1].kind {
EntryKind::Message(msg) => {
assert_eq!(msg.role, crate::message::Role::User);
assert_eq!(msg.content.len(), 1);
}
_ => panic!("expected message entry"),
}
fs::remove_dir_all(root).ok();
}
#[test]
fn active_path_reconstructs_conversation() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("test-project");
let session = store.create("/tmp/test").unwrap();
// Build a linear conversation: header -> user -> assistant
let h_id = {
let entries = store.load(&session).unwrap();
entries[0].id.clone()
};
let u_id = store.append(&session, Some(h_id), EntryKind::Message(Message::user("q"))).unwrap();
let a_id =
store.append(&session, Some(u_id), EntryKind::Message(Message::assistant("a"))).unwrap();
// Walk from the leaf.
let path = store.active_path(&session, &a_id).unwrap();
assert_eq!(path.len(), 3);
// Verify order (root to leaf).
match &path[0].kind {
EntryKind::Header { .. } => {}
_ => panic!("first should be header"),
}
match &path[1].kind {
EntryKind::Message(msg) => assert_eq!(msg.role, crate::message::Role::User),
_ => panic!("second should be user message"),
}
match &path[2].kind {
EntryKind::Message(msg) => assert_eq!(msg.role, crate::message::Role::Assistant),
_ => panic!("third should be assistant message"),
}
fs::remove_dir_all(root).ok();
}
#[test]
fn branching_two_children() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("test-project");
let session = store.create("/tmp/test").unwrap();
// header -> user -> assistant (shared ancestor)
let h_id = {
let entries = store.load(&session).unwrap();
entries[0].id.clone()
};
let u_id = store.append(&session, Some(h_id), EntryKind::Message(Message::user("q"))).unwrap();
let a_id =
store.append(&session, Some(u_id), EntryKind::Message(Message::assistant("a1"))).unwrap();
// Two branches from the assistant message.
let b1_id = store
.append(&session, Some(a_id.clone()), EntryKind::Message(Message::assistant("b1")))
.unwrap();
let b2_id =
store.append(&session, Some(a_id), EntryKind::Message(Message::assistant("b2"))).unwrap();
// Path 1: header -> user -> assistant -> b1
let path1 = store.active_path(&session, &b1_id).unwrap();
assert_eq!(path1.len(), 4);
match &path1[3].kind {
EntryKind::Message(msg) => {
assert_eq!(msg.content[0], crate::message::ContentBlock::Text("b1".into()))
}
_ => panic!("expected message"),
}
// Path 2: header -> user -> assistant -> b2
let path2 = store.active_path(&session, &b2_id).unwrap();
assert_eq!(path2.len(), 4);
match &path2[3].kind {
EntryKind::Message(msg) => {
assert_eq!(msg.content[0], crate::message::ContentBlock::Text("b2".into()))
}
_ => panic!("expected message"),
}
// Paths share the first 3 entries.
for i in 0..3 {
assert_eq!(path1[i].id, path2[i].id);
}
fs::remove_dir_all(root).ok();
}
#[test]
fn resume_after_reopen() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("test-project");
let session = store.create("/tmp/test").unwrap();
// Build a conversation.
let h_id = {
let entries = store.load(&session).unwrap();
entries[0].id.clone()
};
let u_id = store.append(&session, Some(h_id), EntryKind::Message(Message::user("q"))).unwrap();
let a_id =
store.append(&session, Some(u_id), EntryKind::Message(Message::assistant("a"))).unwrap();
// Drop the store and reopen.
drop(store);
let mut store2 = JsonlSessionStore::new(&root);
store2.set_project_hash("test-project");
// Load should still work.
let entries = store2.load(&session).unwrap();
assert_eq!(entries.len(), 3);
// Active path should reconstruct correctly.
let path = store2.active_path(&session, &a_id).unwrap();
assert_eq!(path.len(), 3);
fs::remove_dir_all(root).ok();
}
#[test]
fn corrupt_jsonl_fails_loud() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("test-project");
let session = store.create("/tmp/test").unwrap();
// Append a valid entry.
store.append(&session, None, EntryKind::Message(Message::user("ok"))).unwrap();
// Corrupt the file by appending invalid JSON.
let path = store.session_dir(&session);
fs::OpenOptions::new()
.append(true)
.open(&path)
.unwrap()
.write_all(b"not valid json\n")
.unwrap();
// Load should fail with a parse error.
let result = store.load(&session);
assert!(result.is_err());
fs::remove_dir_all(root).ok();
}
/// The `.jsonl` on disk outlives the build that wrote it, so its shape is a compatibility
/// promise rather than an implementation detail.
///
/// Deliberately not a round-trip. Serializing a value and reading it straight back exercises
/// both halves of the *current* code, so a renamed field or a retagged variant passes
/// unnoticed — both sides moved together. What actually breaks is a session written by an
/// earlier build, and only a literal from that era can catch it.
#[test]
fn the_on_disk_entry_shape_is_frozen() {
// These literals are copied from a real `.luxe/sessions/*.jsonl`, not written from what
// the struct looks like it ought to produce. Guessing is how this test was first written
// asserting a flat `kind`/`data` pair, which the code has never emitted.
let stored = r#"{"id":"e1","parent_id":null,"ts":1234567890,"kind":{"kind":"header","data":{"cwd":"/tmp/project","created":1234567890}}}"#;
let entry: Entry = serde_json::from_str(stored).expect("an older header still loads");
assert_eq!(entry.id, EntryId("e1".into()));
assert_eq!(entry.parent_id, None);
assert_eq!(entry.ts, 1234567890);
let EntryKind::Header { cwd, created } = entry.kind else { panic!("expected a header") };
assert_eq!(cwd, "/tmp/project");
assert_eq!(created, 1234567890);
let stored = r#"{"id":"e2","parent_id":"e1","ts":1,"kind":{"kind":"message","data":{"role":"user","content":[{"type":"text","content":"hello"}]}}}"#;
let entry: Entry = serde_json::from_str(stored).expect("an older message still loads");
assert_eq!(entry.parent_id, Some(EntryId("e1".into())));
let EntryKind::Message(message) = entry.kind else { panic!("expected a message") };
assert_eq!(message.role, crate::message::Role::User);
assert_eq!(message.text(), "hello");
// And what we write today is what we just promised to keep reading.
let written = serde_json::to_string(&Entry {
id: EntryId("e3".into()),
parent_id: Some(EntryId("e2".into())),
ts: 7,
kind: EntryKind::Header { cwd: "/w".into(), created: 7 },
})
.unwrap();
assert_eq!(
written,
r#"{"id":"e3","parent_id":"e2","ts":7,"kind":{"kind":"header","data":{"cwd":"/w","created":7}}}"#
);
// A link to the pull request a session worked on, copied from the round trip that closed
// #146 on luxe-dev: `luxe --from-pr` reads exactly this
let stored = r#"{"id":"f25fd65c-ee99-4db8-9ed9-76aa08ed7fd9","parent_id":"035e7a31-2d6b-410a-b1d1-361920bf0615","ts":1790289080,"kind":{"kind":"pull_request_link","data":{"number":146,"url":"https://github.com/nora-quinn/luxe-dev/pull/146"}}}"#;
let entry: Entry = serde_json::from_str(stored).unwrap();
assert_eq!(
entry.kind,
EntryKind::PullRequestLink {
number: 146,
url: "https://github.com/nora-quinn/luxe-dev/pull/146".into()
}
);
assert_eq!(serde_json::to_string(&entry).unwrap(), stored);
// A session's worktree, copied from the real check that made, resumed and removed one:
// resuming reads exactly this to know which branch to re-enter
let stored = r#"{"id":"3508477e-67b5-48a6-880f-364e78b3a263","parent_id":"557b8a9d-0a0d-416d-9ba0-3570271e0b58","ts":1790294351,"kind":{"kind":"worktree","data":{"branch":"wt-check","path":".luxe/worktrees/wt-check"}}}"#;
let entry: Entry = serde_json::from_str(stored).unwrap();
assert_eq!(
entry.kind,
EntryKind::Worktree { branch: "wt-check".into(), path: ".luxe/worktrees/wt-check".into() }
);
assert_eq!(serde_json::to_string(&entry).unwrap(), stored);
// The issue a session took up, copied from the real `luxe --issue 151`: a pull request
// opened from the session reads exactly this to say what it closes
let stored = r#"{"id":"e83c41d6-04c1-409a-82b6-4a23398220a1","parent_id":"76abaff5-9102-42ab-913b-65192df21a92","ts":1790310478,"kind":{"kind":"issue_link","data":{"number":151,"url":"https://github.com/nora-quinn/luxe-dev/issues/151"}}}"#;
let entry: Entry = serde_json::from_str(stored).unwrap();
assert_eq!(
entry.kind,
EntryKind::IssueLink {
number: 151,
url: "https://github.com/nora-quinn/luxe-dev/issues/151".into()
}
);
assert_eq!(serde_json::to_string(&entry).unwrap(), stored);
// A cache refresh's spend, copied from the live check that kept an Opus 4.8 turn's cache
// alive through `sleep 300`: its own kind, so an older build skips it as `Unknown` where a
// `usage` entry with a source it can't parse would fail the whole session load
let stored = r#"{"id":"f9de6ec2-99c5-4c9f-bc72-2eb976e3507c","parent_id":"cc47a2e6-c9dc-4e8d-b506-5efc02e844f6","ts":1791214401,"kind":{"kind":"cache_warm","data":{"model":"claude-opus-4-8","totals":{"calls":1,"prompt_tokens":11512,"completion_tokens":1,"cache_read_tokens":11510,"cache_write_tokens":0,"reasoning_tokens":0,"cost_usd":0.00579,"unpriced_calls":0,"plan_usd":0.0,"plan_calls":0}}}}"#;
let entry: Entry = serde_json::from_str(stored).unwrap();
let EntryKind::CacheWarm { model, totals } = &entry.kind else {
panic!("expected a cache refresh, got {:?}", entry.kind)
};
assert_eq!(model, "claude-opus-4-8");
assert_eq!((totals.cache_read_tokens, totals.cache_write_tokens), (11_510, 0));
assert_eq!(serde_json::to_string(&entry).unwrap(), stored);
}
/// Corruption inside a kind we *do* know must still fail loudly — the unknown-kind fallback
/// exists for tags from the future, not as a way to quietly accept a damaged transcript.
#[test]
fn a_known_kind_written_wrong_still_fails_loud() {
let broken =
r#"{"id":"e1","parent_id":null,"ts":1,"kind":{"kind":"header","data":{"cwd":42}}}"#;
assert!(
serde_json::from_str::<Entry>(broken).is_err(),
"a malformed header must not degrade to Unknown"
);
}
/// [`EntryKind::Unknown`] makes three promises about a log a newer Luxe has written to: it
/// stays readable, the unrecognized entry is kept rather than dropped, and the parent chain
/// still walks through it. All three were documented; none were tested.
#[test]
fn an_entry_from_a_newer_luxe_does_not_break_the_transcript() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("forward-compat");
let session = store.create("/tmp/test").unwrap();
let header = store.load(&session).unwrap()[0].id.clone();
let first =
store.append(&session, Some(header), EntryKind::Message(Message::user("before"))).unwrap();
// A kind this build has never heard of, appended the way a newer one would.
let path = store.session_dir(&session);
let future = format!(
"{{\"id\":\"future-1\",\"parent_id\":\"{first}\",\"ts\":9,\"kind\":{{\"kind\":\"telemetry_v2\",\"data\":{{\"whatever\":true}}}}}}\n"
);
fs::OpenOptions::new().append(true).open(&path).unwrap().write_all(future.as_bytes()).unwrap();
let entries = store.load(&session).expect("an unknown kind must not fail the load");
let unknown = entries
.iter()
.find(|entry| entry.id == EntryId("future-1".into()))
.expect("the unrecognized entry is kept, not dropped");
assert_eq!(unknown.kind, EntryKind::Unknown);
assert_eq!(
unknown.parent_id,
Some(first.clone()),
"its parent link survives, which is what keeps resume walking"
);
// Resume chains onto it, and the conversation either side is still reachable.
let after = store
.append(
&session,
Some(EntryId("future-1".into())),
EntryKind::Message(Message::assistant("after")),
)
.unwrap();
let said: Vec<String> = store
.active_path(&session, &after)
.unwrap()
.iter()
.filter_map(|entry| match &entry.kind {
EntryKind::Message(message) => Some(message.text()),
_ => None,
})
.collect();
assert_eq!(said, vec!["before", "after"], "the transcript spans the unknown entry");
fs::remove_dir_all(root).ok();
}
#[test]
fn most_recent_session_picks_newest() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("test-project");
let first = store.create("/tmp/test").unwrap();
// Ensure a distinct mtime for the second file.
std::thread::sleep(std::time::Duration::from_millis(1100));
let second = store.create("/tmp/test").unwrap();
assert!(store.session_path(&first).unwrap().exists());
assert_eq!(store.most_recent_session().as_ref(), Some(&second));
// A fresh store rescans from disk and still finds the newest.
let reopened = JsonlSessionStore::new(&root);
let mut reopened = reopened;
reopened.set_project_hash("test-project");
assert_eq!(reopened.most_recent_session().as_ref(), Some(&second));
fs::remove_dir_all(root).ok();
}
#[test]
fn most_recent_session_empty_is_none() {
let root = temp_root();
let mut store = JsonlSessionStore::new(&root);
store.set_project_hash("empty-project");
assert!(store.most_recent_session().is_none());
assert!(store.session_path(&SessionId("nope".into())).is_none());
}
/// A compaction is appended *after* the conversation and keeps it reachable. Chaining it under
/// `first_kept` instead — which is what it used to do — forks the branch: the summary lands on
/// a twig nothing points at, and the entries after `first_kept` end up on the other side of the
/// fork, so the leaf that resume finds walks a path missing half the session.
#[test]
fn a_compaction_extends_the_conversation_rather_than_forking_it() {
let root = temp_root();
let mut store = JsonlSessionStore::new(root);
let session_id = store.create("/tmp/test").unwrap();
// Chained onto the header, the way a real turn chains onto whatever the leaf was.
let mut parent = latest_leaf(&store.load(&session_id).unwrap());
let mut ids = Vec::new();
for index in 0..4 {
let message = EntryKind::Message(Message::user(format!("m{index}")));
let id = store.append(&session_id, parent.clone(), message).unwrap();
parent = Some(id.clone());
ids.push(id);
}
let leaf = ids.last().cloned();
let first_kept = ids[2].clone();
let compacted = store
.compact(&session_id, leaf, "## Goal\nTest compaction.\n", &first_kept, 9_000)
.unwrap();
let entries = store.load(&session_id).unwrap();
assert_eq!(entries.len(), 6, "header + four messages + compaction");
match &entries[5].kind {
EntryKind::Compaction { summary, first_kept: kept, tokens_before } => {
assert_eq!(summary, "## Goal\nTest compaction.\n");
assert_eq!(kept, &first_kept);
assert_eq!(*tokens_before, 9_000, "what it replaced, not a placeholder zero");
}
other => panic!("expected a Compaction entry, got {other:?}"),
}
// It is the tip, and everything written before it is still reachable through it.
assert_eq!(latest_leaf(&entries).as_ref(), Some(&compacted));
let path = store.active_path(&session_id, &compacted).unwrap();
assert_eq!(path.len(), 6, "nothing is stranded on a fork: {path:?}");
assert_eq!(path.last().map(|entry| &entry.id), Some(&compacted));
}