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_event(&self, event: &AgentEvent) -> Result<(), SessionError>

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

Read all entries from the session’s JSONL file.

Entries are reconstructed from the JSONL format. Entries without id or parent_id (backward compatibility) are assigned synthetic IDs and treated as a single linear branch.

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

Read all messages from the session’s JSONL file for the current branch.

Only entries with role "user", "assistant", or "system" that contain valid message data are returned.

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

Read all events from the session’s JSONL file.

impl Session

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 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.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

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.