Struct SessionManager 

pub struct SessionManager { /* private fields */ }

Session tree with append-only JSONL persistence.

Implementations

impl SessionManager

pub fn append_tool_dispatch( &mut self, tool_call_id: &str, tool_name: &str, input: &JsonObject, ) -> Result<EntryId, SessionError>

Appends the TOOL_DISPATCH_TYPE record of a tool call (D-DISPATCH): a custom entry naming the call before its body runs, so resume repair can attribute an interrupted effect. custom entries never project into context (session-manager.js:164-181) — inert to v3-format readers.

Errors

I/O when persisting.

pub fn repair_interrupted_turn(&mut self) -> Result<RepairReport, SessionError>

Repairs an interrupted turn at the leaf (D-REPAIR). Call once, under write ownership, before the session is used; appends only, never rewrites or truncates:

1. a torn last line (non-empty, not valid JSON) is terminated with "\n" so it stays a permanently skipped line — appended before any closer, so a closer never concatenates onto the fragment;
2. every toolCall of the trailing assistant message without a matching toolResult in the trailing run is closed with an unknown-outcome error toolResult;
3. one RESUME_REPAIR_TYPE record and a sync() follow when anything was repaired.

Repair is idempotent: after the first repair the trailing run is balanced and the dangling scan finds nothing. In-memory sessions and sessions whose file was never created have nothing to repair and are left untouched.

Errors

I/O when reading or appending (fail-closed: the caller must not use the session).

impl SessionManager

pub fn create( cwd: &Path, session_dir: &Path, opts: CreateOptions, ) -> Result<Self, SessionError>

New persisted session for cwd (file created on the first user/assistant message).

Errors

SessionError::InvalidSessionId for a bad explicit id.

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

Opens a session file: migrates v1/v2 in place and pre-v1 Oino files to the v3 layout; a missing file starts a new session at that path.

Errors

I/O, SessionError::UnsupportedVersion, SessionError::MissingHeader (non-empty file without header), SessionError::MissingCwd.

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

Opens the newest session of cwd, else creates one.

Errors

As SessionManager::open / SessionManager::create.

pub fn in_memory( cwd: &Path, opts: CreateOptions, entries: Vec<SessionEntry>, ) -> Self

In-memory session (never written). entries are appended after a fresh header; an invalid explicit id is replaced by a generated one.

pub fn fork_from( source: &Path, target_cwd: &Path, session_dir: &Path, opts: CreateOptions, ) -> Result<Self, SessionError>

Copies all entries of source into a new session for target_cwd with parentSession = source. Written immediately.

Errors

I/O, invalid source (SessionError::MissingHeader), invalid id.

pub fn find_by_id( cwd: &Path, id: &str, session_dir: &Path, ) -> Result<Option<PathBuf>, SessionError>

Finds a session by id: exact header id, then a unique prefix (≥ 4 chars) in the cwd directory, then over all directories.

Errors

SessionError::AmbiguousId.

pub fn list( cwd: &Path, session_dir: &Path, progress: Option<&dyn ProgressSink>, cancel: Option<&AtomicBool>, ) -> Result<Vec<SessionInfo>, SessionError>

Sessions of cwd, newest modified first.

Errors

SessionError::Cancelled.

pub fn list_all( session_dir: &Path, progress: Option<&dyn ProgressSink>, cancel: Option<&AtomicBool>, ) -> Result<Vec<SessionInfo>, SessionError>

Sessions of all cwds, newest modified first.

Errors

SessionError::Cancelled.

pub fn find_most_recent( cwd: &Path, session_dir: &Path, ) -> Result<Option<PathBuf>, SessionError>

Newest valid session file of cwd.

Errors

Never fails today; Result keeps room for I/O reporting.

pub fn migrate_legacy_dir( sessions_root: &Path, ) -> Result<Vec<MigratedSession>, SessionError>

Migrates every pre-v1 *.jsonl directly in sessions_root (D21).

Errors

The first I/O error; files migrated before it stay migrated.

pub fn new_session(&mut self, opts: CreateOptions) -> Result<(), SessionError>

Fresh header and empty tree.

Errors

SessionError::InvalidSessionId.

pub fn set_session_file(&mut self, path: &Path) -> Result<(), SessionError>

Binds to path: loads it when it exists, otherwise starts a new session that will be written there.

Errors

As SessionManager::open.

pub const fn is_persisted(&self) -> bool

Whether this manager writes to disk (isPersisted: false for in-memory).

pub const fn is_flushed(&self) -> bool

Whether the file has been created (header + buffered entries written).

pub fn cwd(&self) -> &Path

Session cwd.

pub fn session_dir(&self) -> &Path

Sessions root.

pub fn uses_default_session_dir(&self) -> bool

Whether the sessions root is <default agent dir>/sessions.

pub fn session_id(&self) -> &str

Session id.

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

Session file path (planned path before the first flush).

pub const fn header(&self) -> &SessionHeader

Header.

pub fn entry_count(&self) -> usize

Number of distinct entry ids.

pub const fn index(&self) -> &EntryIndex

The pure entry index (for the free functions in crate::context).

pub fn sync(&mut self) -> Result<(), SessionError>

Flush + fsync the session file. Also fsyncs the parent directory until the current file’s creation is known durable (POSIX). Fail-closed durability barrier (D-FLUSH): callers treat SessionError::Io as “do not proceed”.

A session whose first flush never succeeded (for example an unwritable directory) retries it here, so the error surfaces at the barrier instead of being silently retried forever. In-memory sessions and sessions with nothing written yet succeed without touching the file system.

Errors

SessionError::Io when the file cannot be opened for append, fsynced, or its first flush retried.

pub fn append_entry(&mut self, kind: EntryKind) -> Result<EntryId, SessionError>

Generic append at the leaf (used by boundary drafts).

Errors

I/O when persisting.

pub fn append_message( &mut self, message: AgentMessage, ) -> Result<EntryId, SessionError>

Appends a message; summary roles are rejected (use compaction/branch entries).

Errors

SessionError::InvalidAppend, I/O.

pub fn append_thinking_level_change( &mut self, level: &str, ) -> Result<EntryId, SessionError>

Appends a thinking_level_change.

Errors

I/O.

pub fn append_model_change( &mut self, provider: &str, model_id: &str, ) -> Result<EntryId, SessionError>

Appends a model_change.

Errors

I/O.

pub fn append_usage( &mut self, kind: &str, provider: &str, model: &str, usage: Usage, note: Option<String>, ) -> Result<EntryId, SessionError>

Appends a usage entry (empty note omitted).

Errors

I/O.

pub fn append_compaction( &mut self, draft: CompactionDraft, ) -> Result<EntryId, SessionError>

Appends a compaction. Without an explicit checkpoint the current projection’s system state is stored, stamped with the entry time.

Errors

I/O.

pub fn append_custom_entry( &mut self, custom_type: &str, data: Option<JsonValue>, ) -> Result<EntryId, SessionError>

Appends a custom entry (extension state).

Errors

I/O.

pub fn append_session_info( &mut self, name: Option<&str>, ) -> Result<EntryId, SessionError>

Appends a session_info (CR/LF runs → one space, trimmed).

Errors

I/O.

pub fn append_custom_message_entry( &mut self, custom_type: &str, content: UserContentField, display: bool, details: Option<JsonValue>, ) -> Result<EntryId, SessionError>

Appends a custom_message (participates in context).

Errors

I/O.

pub fn append_context_edit( &mut self, target: &EntryId, replacement: Option<EditableContent>, ) -> Result<EntryId, SessionError>

Appends a context_edit of an editable entry on the active branch; string replacements of assistant/toolResult targets are normalised to one text block.

Errors

SessionError::UnknownEntry, SessionError::InvalidAppend, I/O.

pub fn append_label_change( &mut self, target: &EntryId, label: Option<&str>, ) -> Result<EntryId, SessionError>

Sets (or with None/empty clears) the label of target.

Errors

SessionError::UnknownEntry, I/O.

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

Latest session_info name in file order (trimmed; empty ⇒ None).

pub const fn leaf_id(&self) -> Option<&EntryId>

Current leaf id (None after SessionManager::reset_leaf or when empty).

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

Current leaf entry.

pub fn entry(&self, id: &EntryId) -> Option<&SessionEntry>

Entry by id.

pub fn children(&self, parent: Option<&EntryId>) -> Vec<&SessionEntry>

Entries whose parent is parent (None ⇒ roots), file order.

pub fn label(&self, id: &EntryId) -> Option<&str>

Current label of an entry.

pub fn branch(&self, from: Option<&EntryId>) -> Vec<&SessionEntry>

Root → from (default leaf), all entry types; unknown id ⇒ empty.

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

All entries in file order.

pub fn tree(&self) -> Vec<SessionTreeNode>

Tree of all entries (roots and orphans in file order, children by timestamp).

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

Builds context entries at the leaf.

pub fn build_session_projection(&self) -> SessionProjection

Builds the session projection at the leaf.

pub fn build_session_context(&self) -> SessionContext

Builds the session context at the leaf.

pub fn set_leaf(&mut self, id: &EntryId) -> Result<(), SessionError>

Moves the leaf; nothing is written.

Errors

SessionError::UnknownEntry.

pub fn reset_leaf(&mut self)

Clears the leaf; the next entry becomes a new root.

pub fn branch_with_summary( &mut self, from: Option<&EntryId>, summary: BranchSummaryDraft, ) -> Result<EntryId, SessionError>

Moves the leaf to from (None ⇒ new root) and appends a branch_summary there.

Errors

SessionError::UnknownEntry, I/O.

pub fn create_branched_session( &self, leaf: &EntryId, ) -> Result<PathBuf, SessionError>

Writes a new session file containing the path root → leaf (/clone), with parentSession = this file. self is unchanged.

Errors

SessionError::UnknownEntry, SessionError::InvalidAppend for in-memory sessions (use SessionManager::branch_into_new_session), I/O.

pub fn branch_into_new_session( &mut self, leaf: &EntryId, ) -> Result<Option<PathBuf>, SessionError>

Branched-session semantics: replaces self with the branched session (the file is written only if it contains a user/assistant message). Returns the new path for persisted sessions.

Errors

SessionError::UnknownEntry, I/O.

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.

impl Debug for SessionManager

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

Formats the value using the given formatter.

impl ReadonlySession for SessionManager

fn cwd(&self) -> &Path

Session cwd.

fn session_id(&self) -> &str

Session id.

fn session_file(&self) -> Option<&Path>

Session file, when persisted.

fn header(&self) -> &SessionHeader

Header.

fn session_name(&self) -> Option<String>

Latest session name.

fn leaf_id(&self) -> Option<&EntryId>

Current leaf.

fn entry(&self, id: &EntryId) -> Option<&SessionEntry>

Entry by id.

fn children(&self, parent: Option<&EntryId>) -> Vec<&SessionEntry>

Children in file order.

fn label(&self, id: &EntryId) -> Option<&str>

Current label of an entry.

fn branch(&self, from: Option<&EntryId>) -> Vec<&SessionEntry>

Root → from (default leaf).

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

All entries in file order.

fn tree(&self) -> Vec<SessionTreeNode>

Tree view.

fn build_context_entries(&self) -> Vec<SessionEntry>

Context-selected entries at the leaf.

fn build_session_projection(&self) -> SessionProjection

Projection at the leaf.

fn build_session_context(&self) -> SessionContext

Context at the leaf.