talos_session/lib.rs
1//! Talos session management — JSONL-based session logging with tree-branching support.
2//!
3//! Sessions are stored as append-only JSONL files, organized by working directory.
4//! Each line in a JSONL file is a JSON object representing a [`SessionEntry`] with
5//! fields for `id`, `parent_id`, `timestamp`, `role`, `content`, and optional `metadata`.
6//!
7//! # Directory Layout
8//!
9//! ```text
10//! ~/.talos/sessions/
11//! <project>/
12//! <uuid>.jsonl
13//! ```
14//!
15//! # Branching Model
16//!
17//! Each session supports multiple branches. A branch is a linear sequence of entries
18//! rooted at a specific entry. The `fork` method creates a new branch from any existing
19//! entry, enabling tree-structured conversation histories.
20//!
21//! # Crash Safety
22//!
23//! JSONL is append-only. If a crash occurs, only the last line may be corrupted,
24//! which can be detected and skipped during reads.
25//!
26//! # Backward Compatibility
27//!
28//! Entries without `id` or `parent_id` fields (from older JSONL files) are treated
29//! as part of a single linear branch. They are assigned synthetic IDs on load.
30
31mod error;
32mod jsonl;
33mod manager;
34pub mod sqlite;
35mod topology;
36mod types;
37
38pub use error::SessionError;
39pub use manager::{
40 SessionCleanupCandidate, SessionCleanupPolicy, SessionCleanupReport, SessionManager,
41};
42pub use sqlite::{ForkInfo, IndexError, SearchResult, SessionIndex};
43pub use types::{Session, SessionBranch, SessionEntry, SessionInfo, SessionMetadata};
44
45#[cfg(test)]
46#[allow(warnings)]
47mod tests;