Struct SessionManager 

pub struct SessionManager { /* private fields */ }

Manages conversation sessions as append-only trees stored in JSONL files.

SessionManager handles session persistence, branching, and tree traversal. Each session is stored as a JSONL file where each line is a session entry. Entries form a tree structure allowing for session branching and history.

Implementations

impl SessionManager

pub fn create(cwd: &str, session_dir: Option<&str>) -> Self

Create a new session and persist it to disk.

pub fn open( path: &str, session_dir: Option<&str>, cwd_override: Option<&str>, ) -> Self

Open an existing session from a file path.

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

Continue the most recent session, or create a new one if none exists.

pub fn in_memory(cwd: &str) -> Self

Create an in-memory session without file persistence.

pub fn set_session_file(&mut self, session_file: &str)

Switch to a different session file

pub fn new_session(&mut self, options: Option<NewSessionOptions>)

Create a new session with optional ID and parent

pub fn is_persisted(&self) -> bool

Check if session is persisted to disk

pub fn validate_session_id(id: &str) -> bool

Validate a session ID format.

Checks that the session_id conforms to the expected UUID format. Returns true if valid.

pub fn is_readonly(&self) -> bool

Returns true if this session is in read-only mode.

A session is read-only when:

• It was opened without write permissions
• Its underlying file is set to read-only on the filesystem

Read-only sessions reject any append/branch operations.

pub fn can_append(&self) -> bool

Check if appending to this session is allowed.

Combination of !is_readonly() + in-memory or writable backing file.

pub fn persisted_count(&self) -> usize

Get the number of agent messages that have already been persisted.

pub fn set_persisted_count(&self, count: usize)

Set the number of agent messages that have been persisted.

pub fn get_cwd(&self) -> String

Get working directory

pub fn get_session_dir(&self) -> String

Get session directory

pub fn get_session_id(&self) -> String

Get session ID

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

Get session file path

pub fn cleanup_if_empty(&self)

Remove the session file from disk if the session has no real conversation (i.e., no user message was ever persisted). Called before switching to a new session or quitting.

pub fn append_message(&mut self, message: AgentMessage) -> String

Append a message as child of current leaf

pub fn append_thinking_level_change(&mut self, thinking_level: &str) -> String

Append a thinking level change

pub fn append_model_change(&mut self, provider: &str, model_id: &str) -> String

Append a model change

pub fn append_compaction( &mut self, summary: &str, _first_kept_entry_id: &str, tokens_before: i64, _details: Option<Value>, _from_hook: Option<bool>, ) -> String

Append a compaction summary

pub fn append_custom_entry( &mut self, custom_type: &str, data: Option<Value>, ) -> String

Append a custom entry (for extensions)

pub fn append_session_info(&mut self, name: &str) -> String

Append a session info entry (e.g., display name)

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

Get the current session name from the latest session_info entry

pub fn append_custom_message_entry( &mut self, custom_type: &str, content: ContentValue, display: bool, details: Option<Value>, ) -> String

Append a custom message entry (for extensions) that participates in LLM context

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

Get the current leaf ID

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

Get the current leaf entry

pub fn get_entry(&self, id: &str) -> Option<SessionEntry>

Get an entry by ID

pub fn get_children(&self, parent_id: &str) -> Vec<SessionEntry>

Get all direct children of an entry

pub fn get_parent(&self, id: &str) -> Option<SessionEntry>

Get the parent of an entry

pub fn get_label(&self, id: &str) -> Option<String>

Get the label for an entry

pub fn append_label_change( &mut self, target_id: &str, label: Option<&str>, ) -> Result<String, String>

Set or clear a label on an entry

pub fn get_branch(&self, from_id: Option<&str>) -> Vec<SessionEntry>

Walk from entry to root, returning all entries in path order

pub fn get_path_to_root(&self, from_id: &str) -> Vec<SessionEntry>

Get path to root for a given entry

pub fn get_ancestry(&self, from_id: &str) -> Vec<SessionEntry>

Get ancestry (same as path to root)

pub fn get_depth(&self, id: &str) -> i64

Get depth of an entry

pub fn build_session_context(&self) -> SessionContext

Build the session context (what gets sent to the LLM)

pub fn get_header(&self) -> Option<SessionHeader>

Get session header

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

Get all session entries (excludes header)

pub fn get_tree(&self, _id: Uuid) -> Result<Vec<SessionTreeNode>>

Get the session as a tree structure If id is provided, returns tree for that session (backward compat)

pub fn branch(&mut self, branch_from_id: &str) -> Result<(), String>

Start a new branch from an earlier entry

pub fn reset_leaf(&mut self)

Reset the leaf pointer to null (before any entries)

pub fn branch_with_summary( &mut self, branch_from_id: Option<&str>, summary: &str, _details: Option<Value>, _from_hook: Option<bool>, ) -> String

Start a new branch with a summary of the abandoned path

pub fn add_label( &mut self, target_id: &str, label: &str, ) -> Result<String, String>

Add a label to the session

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

Remove a label from an entry

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

Get the latest compaction entry

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

Get all compaction entries

pub fn get_session_stats(&self) -> SessionStats

Get session statistics

pub async fn list( cwd: &str, session_dir: Option<&str>, ) -> Result<Vec<SessionInfo>>

List all sessions for a directory

pub async fn list_all() -> Result<Vec<SessionInfo>>

List all sessions across all project directories

pub fn fork_from( source_path: &str, target_cwd: &str, session_dir: Option<&str>, ) -> Result<Self, String>

Fork a session from another project directory into the current project

pub fn delete_session(path: &str) -> Result<()>

Delete a session

pub fn rename_session(&mut self, name: &str) -> String

Rename a session (set its display name)

pub async fn new() -> Result<Self>

Create a new SessionManager (async for backward compatibility)

pub async fn new_async() -> Result<Self>

Create a new SessionManager (async for backward compatibility)

pub fn session_path(&self, id: &Uuid) -> PathBuf

Get the session file path for a given session ID

pub async fn list_sessions(&self) -> Result<Vec<SessionMeta>>

List all sessions (backward compat)

pub async fn save(&self, _id: Uuid, _entries: &[SessionEntry]) -> Result<()>

Save entries (backward compat)

pub async fn load(&self, _id: Uuid) -> Result<Vec<SessionEntry>>

Load entries (backward compat)

pub async fn delete(&self, id: Uuid) -> Result<()>

Delete a session (backward compat)

pub async fn branch_from( &self, parent_id: Uuid, entry_id: Uuid, ) -> Result<(Uuid, Vec<SessionEntry>)>

Create a branch from an existing session at a given entry

pub async fn get_branch_info(&self, _id: Uuid) -> Result<Option<BranchInfo>>

Get branch info for a session

pub async fn get_tree_async(&self, _id: Uuid) -> Result<Vec<SessionTreeNode>>

Get tree for a specific session (backward compat)

pub async fn save_meta(&self, _meta: &SessionMeta) -> Result<()>

Save metadata (backward compat)

pub async fn load_meta(&self, _id: Uuid) -> Result<Option<SessionMeta>>

Load metadata (backward compat)

pub async fn create_session(&mut self) -> Result<SessionMeta>

Create a new session (backward compat)

pub fn branch_from_entry(&self, entry_id: &str) -> Result<String, String>

Fork from current session at a specific entry, creating a new session file. Synchronous.

Trait Implementations

impl Clone for SessionManager

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.