Struct SessionManager 

pub struct SessionManager { /* private fields */ }

Manages a single session’s entries and persistence.

Raw persisted entries are always retained in entries. Active model-visible history may differ from the raw branch when a SessionEntry::Compaction exists on the current branch. In that case, callers should prefer get_active_messages() over get_messages() when assembling context for an LLM request.

Implementations

impl SessionManager

pub fn new(cwd: &Path, session_dir: &Path) -> Result<Self>

Create a new session. Writes the header to disk immediately.

pub fn open(path: &Path) -> Result<Self>

Open an existing session file, skipping malformed lines.

pub fn in_memory() -> Self

In-memory session (no persistence).

pub fn in_memory_with_messages(messages: Vec<Message>) -> Self

In-memory session seeded with a linear message history.

pub fn continue_recent(cwd: &Path, session_dir: &Path) -> Result<Option<Self>>

Find the most recently modified session for a given cwd.

pub fn name(&self) -> Option<&str>

Get the session name.

pub fn summary(&self) -> Option<&str>

Get the session summary.

pub fn set_name(&mut self, name: &str)

Set the session name.

pub fn set_summary(&mut self, summary: impl Into<String>)

Set the session summary.

pub fn clear_summary(&mut self)

Clear the session summary.

pub fn title(&self, max_chars: usize) -> Option<String>

A short, single-line chat title derived from persisted session metadata or message history.

pub fn append(&mut self, entry: SessionEntry) -> Result<()>

Append an entry. Sets parent_id to current leaf_id, updates leaf_id, and writes to file if persisted.

pub fn append_assistant_turn( &mut self, model: &Model, turn_index: u32, message: AssistantMessage, ) -> Result<(String, Option<String>)>

Append an assistant turn and, when available, its canonical usage record.

pub fn append_assistant_turn_with_model_meta( &mut self, model_meta: &ModelMeta, turn_index: u32, message: AssistantMessage, ) -> Result<(String, Option<String>)>

Append an assistant turn and, when available, its canonical usage record.

pub fn append_tool_result_message( &mut self, result: ToolResultMessage, ) -> Result<String>

Append a tool result message and return the persisted entry id.

pub fn append_recovery_checkpoint( &mut self, checkpoint: RecoveryCheckpoint, ) -> Result<String>

Append a recovery checkpoint custom entry and return the persisted entry id.

pub fn persist_agent_event_entries( &mut self, model: &Model, event: &AgentEvent, ) -> Result<Vec<&'static str>>

Persist the session entries implied by an agent event.

Returns a short description of what was written so callers can surface best-effort persistence diagnostics without owning the persistence logic.

pub fn persist_agent_event_entries_with_model_meta( &mut self, model_meta: &ModelMeta, event: &AgentEvent, ) -> Result<Vec<&'static str>>

Persist the session entries implied by an agent event.

Returns a short description of what was written so callers can surface best-effort persistence diagnostics without owning the persistence logic.

pub fn append_canonical_usage_for_assistant_turn( &mut self, model: &Model, assistant_message_id: &str, turn_index: u32, message: &AssistantMessage, ) -> Result<Option<String>>

Append a canonical usage entry for an assistant turn, if the turn reports usage and no equivalent canonical record already exists.

This is best-effort metadata persistence: callers should treat errors as non-fatal to the main agent flow.

pub fn append_canonical_usage_for_assistant_turn_with_model_meta( &mut self, model_meta: &ModelMeta, assistant_message_id: &str, turn_index: u32, message: &AssistantMessage, ) -> Result<Option<String>>

Append a canonical usage entry for an assistant turn, if the turn reports usage and no equivalent canonical record already exists.

This is best-effort metadata persistence: callers should treat errors as non-fatal to the main agent flow.

pub fn usage_records(&self) -> Vec<SessionUsageRecord>

Read canonical usage rows attached to this session.

pub fn append_checkpoint_record( &mut self, record: SessionCheckpointRecord, ) -> Result<String>

pub fn checkpoint_records(&self) -> Vec<SessionCheckpointRecord>

pub fn find_checkpoint_record( &self, needle: &str, ) -> Option<SessionCheckpointRecord>

pub fn restore_checkpoint( &self, checkpoint_state: &CheckpointState, needle: &str, ) -> Result<Vec<PathBuf>>

pub fn has_canonical_usage_request_id(&self, request_id: &str) -> bool

Check whether a canonical usage record already exists for the given request id.

pub fn has_canonical_usage_for_assistant_message( &self, assistant_message_id: &str, ) -> bool

Check whether a canonical usage record already exists for the given assistant turn.

pub fn get_branch(&self) -> Vec<&SessionEntry>

Walk parent_ids from leaf_id to root, return raw entries in chronological order.

This is the durable branch as persisted on disk. It may include SessionEntry::Compaction markers plus raw pre-compaction messages. Callers building model-visible context should prefer get_active_messages().

pub fn get_messages(&self) -> Vec<&Message>

Get raw message entries for the current branch.

This reflects the durable branch exactly and intentionally ignores compaction semantics. For model-visible history after a compaction, prefer get_active_messages().

pub fn latest_compaction(&self) -> Option<&SessionEntry>

Return the latest compaction entry on the active branch, if any.

pub fn get_active_messages(&self) -> Vec<Message>

Build the model-visible message history for the active branch.

Compaction semantics are branch-local and replacement-based:

• if there is no compaction entry on the branch, this returns the raw branch messages;
• if a compaction entry exists, all raw messages before that boundary are replaced by a synthetic user summary message derived from the latest compaction entry, followed by the raw messages from first_kept_id onward that are still on the active branch.

Raw persisted entries remain intact on disk and are still available via get_branch() / get_messages().

pub fn active_message_count(&self) -> usize

Get the active model-visible branch entries.

This is a convenience wrapper over get_active_messages() for callers that still want borrowed-like iteration semantics at the message layer.

pub fn get_tree(&self) -> Vec<TreeNode>

Build the full tree structure from all entries.

pub fn navigate(&mut self, target_id: &str) -> Result<()>

Change the current position in the tree to a different entry.

pub fn fork(&self, entry_id: &str, new_path: &Path) -> Result<SessionManager>

Create a new session file containing only entries up to (and including) the given entry_id, following its branch from root.

pub fn recovery_checkpoints(&self) -> Vec<RecoveryCheckpoint>

Return all persisted recovery checkpoints in session order.

pub fn recovery_ledger(&self) -> RecoveryLedger

Build a recovery ledger from persisted recovery checkpoint entries.

pub fn entries(&self) -> &[SessionEntry]

Get all entries.

pub fn path(&self) -> Option<&Path>

Get the session file path.

pub fn leaf_id(&self) -> Option<&str>

Get the current leaf id.

pub fn set_leaf_id_for_in_memory(&mut self, leaf_id: String)

Set the current leaf id for an in-memory session.

pub fn snapshot_with_pending_user_message( &self, id: String, timestamp: u64, text: String, ) -> Self

pub fn session_id(&self) -> Option<String>

Get the stable session id derived from the persisted file name, if any.

pub fn list(session_dir: &Path) -> Result<Vec<SessionInfo>>

List available sessions in a directory.

Trait Implementations

impl Clone for SessionManager

fn clone(&self) -> SessionManager

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SessionManager

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

Formats the value using the given formatter.