Struct Session 

pub struct Session {
    pub id: Uuid,
    pub project: String,
    pub workspace_root: String,
    pub created_at: DateTime<Utc>,
    pub file_path: PathBuf,
    pub current_branch: String,
    pub branches: HashMap<String, SessionBranch>,
    pub persisted: bool,
    /* private fields */
}

A single session, backed by a JSONL file, with support for tree-branching.

Sessions maintain a collection of branches, each identified by a unique ID. The current_branch field tracks which branch is active for appending new entries.

Fields

id: Uuid

project: String

workspace_root: String

created_at: DateTime<Utc>

file_path: PathBuf

current_branch: String

branches: HashMap<String, SessionBranch>

persisted: bool

Implementations

impl Session

pub fn append(&self, message: &Message) -> Result<(), SessionError>

pub fn append_with_metadata( &self, message: &Message, metadata: SessionMetadata, ) -> Result<(), SessionError>

pub fn append_terminal_diagnostic( &self, diagnostic: &ProviderTerminalDiagnostic, ) -> Result<(), SessionError>

pub fn read_terminal_diagnostics( &self, ) -> Result<Vec<ProviderTerminalDiagnostic>, SessionError>

pub fn append_turn_transcript_outcome( &self, outcome: &TurnTranscriptOutcomeRecord, ) -> Result<(), SessionError>

Appends the authoritative terminal transcript outcome for one Turn.

Callers must write this marker only after every transcript message for the outcome has been durably appended. Recovery never infers Success from ordinary or partial message entries alone.

pub fn read_turn_transcript_outcomes( &self, ) -> Result<Vec<TurnTranscriptOutcomeRecord>, SessionError>

pub fn append_event(&self, event: &AgentEvent) -> Result<(), SessionError>

pub fn read_entries(&self) -> Result<Vec<SessionEntry>, SessionError>

pub fn read_messages(&self) -> Result<Vec<Message>, SessionError>

pub fn read_events(&self) -> Result<Vec<AgentEvent>, SessionError>

impl Session

pub fn compact_archived( &self, max_entries: usize, ) -> Result<CompactionResult, SessionError>

Archives the current log while holding the session write lock.

pub fn new( id: Uuid, project: String, workspace_root: String, file_path: PathBuf, ) -> Self

Create a new session with a single empty root branch. The file path MUST already exist on disk.

pub fn new_deferred( id: Uuid, project: String, workspace_root: String, file_path: PathBuf, ) -> Self

Create a deferred session — metadata only, no file on disk. The file is created lazily on the first ensure_persisted() call.

pub fn with_store( id: Uuid, project: String, workspace_root: String, file_path: PathBuf, store: Arc<dyn SessionStore>, ) -> Self

Create a session with an explicit store, chosen by the caller. Used by SessionManager::get_session when loading an existing file whose format is determined by extension.

pub fn ensure_persisted(&mut self) -> Result<(), SessionError>

Create the parent directory and empty JSONL file if not yet persisted. No-op if already persisted (e.g., resumed or forked sessions).

pub fn fork(&mut self, from_entry_id: &str) -> Result<String, SessionError>

Fork the current session from a specific entry, creating a new branch.

Returns the ID of the newly created branch.

Arguments

• from_entry_id - The ID of the entry to fork from. This entry must exist in one of the existing branches.

Errors

Returns SessionError::EntryNotFound if the entry ID doesn’t exist.

pub fn with_fork_identity( &mut self, new_id: Uuid, new_file_path: PathBuf, branch_id: String, )

Atomically re-stamp a forked session with a new identity.

After fork creates a new branch in memory, callers typically write the branched entries to a fresh JSONL file under a new Uuid. This method updates the in-memory Session so that subsequent append and append_event calls write to the new file and so the SQLite index sees a coherent (id, file_path, branch_id) triple.

Without this, the original session’s id/file_path would survive a fork in memory while the on-disk file moved to a new UUID — the SQLite index would then either point at the wrong file or fail to locate the fork.

Arguments

• new_id - The new session Uuid (must match the JSONL filename).
• new_file_path - The path to the new JSONL file the fork was written to.
• branch_id - The branch ID to mark as currently active on the fork.

pub fn get_branch(&self, branch_id: &str) -> Option<&SessionBranch>

Get a reference to a branch by its ID.

Returns None if the branch ID doesn’t exist.

pub fn snapshot_bytes(&self) -> Result<Vec<u8>, SessionError>

Read the session JSONL file as raw bytes, holding the per-session write lock so concurrent append calls cannot produce a torn read.

Used by fork-style operations that need to copy the source file byte-for-byte without racing with in-flight event persistence.

pub fn list_branches(&self) -> Vec<String>

List all branch IDs in this session.

pub fn file_extension(&self) -> &'static str

Returns the file extension used by this session’s store.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.