Struct Session 

pub struct Session {
    pub header: SessionHeader,
    pub entries: Vec<SessionEntry>,
    pub path: Option<PathBuf>,
    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)

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 effective_model_for_current_path(&self) -> Option<(String, String)>

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

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 leaf_id(&self) -> Option<&str>

Get the current leaf entry ID.

pub fn init_from_fork_plan(&mut self, plan: ForkPlan)

Initialize the session entries and leaf from a ForkPlan.

This safely applies the new entries and leaf, and rebuilds all internal caches (including the is_linear optimization flag).

pub fn _test_set_leaf_id(&mut self, id: Option<String>)

Set the leaf ID directly (for tests only).

pub fn revert_last_user_message(&mut self) -> bool

Revert the last user message on the current path, effectively abandoning it. This is used during API retries to prevent duplicating the user prompt in the session history.

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.