Struct Session 

pub struct Session {
    pub header: SessionHeader,
    pub entries: Vec<SessionEntry>,
    pub path: Option<PathBuf>,
    pub leaf_id: Option<String>,
    pub session_dir: Option<PathBuf>,
    /* private fields */
}

A session manages conversation state and persistence.

Fields

header: SessionHeader

Session header

entries: Vec<SessionEntry>

Session entries (messages, changes, etc.)

path: Option<PathBuf>

Path to the session file (None for in-memory)

leaf_id: Option<String>

Current leaf entry ID

session_dir: Option<PathBuf>

Base directory for session storage (optional override)

Implementations

impl Session

pub async fn new(cli: &Cli, config: &Config) -> Result<Self>

Create a new session from CLI args and config.

pub async fn resume_with_picker( override_dir: Option<&Path>, config: &Config, picker_input_override: Option<String>, ) -> Result<Self>

Resume a session by prompting the user to select from recent sessions.

pub fn in_memory() -> Self

Create an in-memory (ephemeral) session.

pub fn create() -> Self

Create a new session.

pub fn create_with_dir(session_dir: Option<PathBuf>) -> Self

Create a new session with an optional base directory override.

pub fn create_with_dir_and_store( session_dir: Option<PathBuf>, store_kind: SessionStoreKind, ) -> Self

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

Open an existing session.

pub async fn open_with_diagnostics( path: &str, ) -> Result<(Self, SessionOpenDiagnostics)>

Open an existing session and return diagnostics about any recovered corruption.

pub fn open_from_v2( store: &SessionStoreV2, header: SessionHeader, mode: V2OpenMode, ) -> Result<(Self, SessionOpenDiagnostics)>

Open a session from an already-open V2 store with an explicit read mode.

pub async fn continue_recent_in_dir( override_dir: Option<&Path>, config: &Config, ) -> Result<Self>

Continue the most recent session.

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

Save the session to disk.

pub async fn flush_autosave( &mut self, trigger: AutosaveFlushTrigger, ) -> Result<()>

Flush queued autosave mutations using the requested trigger.

This is the write-behind entry point: no-op when there are no pending mutations, and one persistence operation for all coalesced mutations when pending work exists.

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

Final shutdown flush respecting the configured durability mode.

pub const fn autosave_metrics(&self) -> AutosaveQueueMetrics

Current autosave queue and lifecycle counters for observability.

pub const fn autosave_durability_mode(&self) -> AutosaveDurabilityMode

pub const fn set_autosave_durability_mode( &mut self, mode: AutosaveDurabilityMode, )

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

Append a session message entry.

pub fn append_model_message(&mut self, message: Message) -> String

Append a message from the model message types.

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

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

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

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

Append a custom entry (extension state, etc).

pub fn append_bash_execution( &mut self, command: String, output: String, exit_code: i32, cancelled: bool, truncated: bool, full_output_path: Option<String>, ) -> String

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

Get the current session name from the cached value (Gap C).

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

Set the session name by appending a SessionInfo entry.

pub fn append_compaction( &mut self, summary: String, first_kept_entry_id: String, tokens_before: u64, details: Option<Value>, from_hook: Option<bool>, ) -> String

pub fn append_branch_summary( &mut self, from_id: String, summary: String, details: Option<Value>, from_hook: Option<bool>, ) -> String

pub fn ensure_entry_ids(&mut self)

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

Convert session entries to model messages (for provider context).

pub fn to_html(&self) -> String

Render the session as a standalone HTML document.

Delegates to render_session_html() for the actual rendering. For non-blocking export, prefer export_snapshot().to_html() which avoids cloning internal caches.

pub fn set_model_header( &mut self, provider: Option<String>, model_id: Option<String>, thinking_level: Option<String>, )

Update header model info.

pub fn set_branched_from(&mut self, path: Option<String>)

pub fn export_snapshot(&self) -> ExportSnapshot

Create a lightweight snapshot for non-blocking HTML export.

Captures only the fields needed by to_html() (header, entries, path), avoiding a full Session::clone() which includes caches, autosave queues, persistence state, and other internal bookkeeping.

pub fn plan_fork_from_user_message(&self, entry_id: &str) -> Result<ForkPlan>

Plan a /fork from a user message entry ID.

Returns the entries to copy into a new session (path to the parent of the selected user message), the new leaf id, and the selected user message text for editor pre-fill.

pub fn get_path_to_entry(&self, entry_id: &str) -> Vec<String>

Get the path from an entry back to the root (inclusive). Returns entry IDs in order from root to the specified entry.

pub fn get_children(&self, entry_id: Option<&str>) -> Vec<String>

Get direct children of an entry.

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

List all leaf nodes (entries with no children).

pub fn navigate_to(&mut self, entry_id: &str) -> bool

Navigate to a specific entry, making it the current leaf. Returns true if the entry exists.

pub fn reset_leaf(&mut self)

Reset the leaf pointer to root (before any entries).

After calling this, the next appended entry will become a new root entry (parent_id = None). This is used by interactive /tree navigation when re-editing the first user message.

pub fn create_branch_from(&mut self, entry_id: &str) -> bool

Create a new branch starting from a specific entry. Sets the leaf_id to the specified entry so new entries branch from there. Returns true if the entry exists.

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

Get the entry at a specific ID (Gap B: O(1) via entry_index).

pub fn get_entry_mut(&mut self, entry_id: &str) -> Option<&mut SessionEntry>

Get the entry at a specific ID, mutable (Gap B: O(1) via entry_index).

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

Entries along the current leaf path, in chronological order.

Gap A: when is_linear is true (the 99% case — no branching has occurred), this returns all entries directly without building a parent map or tracing the path.

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

Convert session entries along the current path to model messages. This follows parent_id links from leaf_id back to root.

pub fn sibling_branches(&self) -> Option<(Option<String>, Vec<SiblingBranch>)>

Find the nearest ancestor that is a fork point (has multiple children) and return its children (sibling branch roots). Each sibling is represented by its branch-root entry ID plus the leaf ID reachable from that root.

Returns (fork_point_id, sibling_leaves) where each sibling leaf is a leaf entry ID reachable through the fork point’s children. The current leaf is included in the list.

pub fn branch_summary(&self) -> BranchInfo

Get a summary of branches in this session.

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

Add a label to an entry.

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.