Struct SessionManager 

pub struct SessionManager { /* private fields */ }

A session: its entries, where it is stored, and the current leaf.

Implementations

impl SessionManager

pub fn create( cwd: &Path, dir: &Path, id: Option<String>, ) -> Result<SessionManager, SessionError>

A new session stored in dir, created on disk once it has a conversation. id must be a valid session id.

pub fn preview(&self) -> SessionManager

A copy at the same leaf that is never written, to try appends on.

pub fn in_memory(cwd: &Path) -> SessionManager

A session that is never written.

pub fn open( path: &Path, dir: Option<&Path>, cwd: Option<&Path>, ) -> Result<SessionManager, SessionError>

Opens a session file. A missing file starts a new session at that path. The working directory comes from the header unless given, and new sessions go to dir, else the file’s directory.

pub fn continue_recent( cwd: &Path, dir: &Path, filter_cwd: bool, ) -> Result<SessionManager, SessionError>

The most recently modified session file in dir (one from cwd when filtering), or a new session.

pub fn new_session( &mut self, id: Option<String>, parent: Option<String>, ) -> Option<PathBuf>

Starts over with a fresh header and returns the new file path when persisted.

pub fn take_write_error(&mut self) -> Option<String>

The error of the session’s first failed write, returned once.

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

Appends a message on the current branch and returns its entry id.

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

Records a thinking level change.

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

Records a model change.

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

Records a compaction with the current system message, so the prompt survives when the messages before firstKeptEntryId drop out.

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

Stores extension state outside the model context.

pub fn append_custom_message( &mut self, custom_type: &str, content: Content, display: bool, details: Option<Value>, ) -> Result<String, SessionError>

Stores an extension message that is part of the model context.

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

Records usage outside the model context, such as a cache warming request’s, attributed to provider and model.

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

Names the session, with line breaks as spaces.

pub fn append_context_edit( &mut self, target_id: &str, replacement: Option<Content>, ) -> Result<String, SessionError>

Edits an earlier model-visible entry on the active branch: None drops it from the context, a replacement swaps its content. Text replacing an assistant or tool result becomes a text block.

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

Sets or clears the label of an entry.

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

The latest session name.

pub fn id(&self) -> &str

The session id.

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

The session file, when persisted.

pub fn is_persisted(&self) -> bool

Whether the session is written to disk.

pub fn dir(&self) -> &Path

The directory new session files go to.

pub fn cwd(&self) -> &Path

The session’s working directory.

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

The header.

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

The current leaf entry id.

pub fn entry(&self, id: &str) -> Option<&FileEntry>

An entry by id.

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

The label of an entry.

pub fn documents(&self) -> (Option<&Value>, Vec<&Value>)

The header and the other entries as stored, in file order: what pi’s HTML export embeds.

pub fn entries(&self) -> impl Iterator<Item = &FileEntry>

Every entry except the header, in file order.

pub fn tree(&self) -> SessionTree

pi’s getTree: entries under their parents, children oldest first. Entries whose parent is missing become roots.

pub fn branch_path(&self, from: Option<&str>) -> Vec<&FileEntry>

The path from the root to from (default: the leaf).

pub fn serialize_branch(&self) -> String

pi’s serializeSessionBranch: a fresh header and the current branch with parent ids rechained, as JSONL.

pub fn branch(&mut self, id: &str) -> Result<(), SessionError>

Moves the leaf to an existing entry. The next append starts a branch there.

pub fn reset_leaf(&mut self)

Moves the leaf before the first entry.

pub fn branch_with_summary( &mut self, from: Option<&str>, summary: String, details: Option<Value>, from_hook: Option<bool>, usage: Option<Usage>, ) -> Result<String, SessionError>

Branches to from (or the root) and records a summary of the branch left.

pub fn build_context(&self) -> SessionContext

The model context of the current branch.

pub fn build_projection(&self) -> Projection<'_>

The current branch’s context, entry by entry.

pub fn create_branched_session( &mut self, leaf_id: &str, ) -> Result<Option<PathBuf>, SessionError>

Starts a new session file holding the branch up to leaf_id, with labels on it, and switches to it. Returns the new file when persisted.

pub fn fork_from( source: &Path, cwd: &Path, dir: &Path, id: Option<String>, ) -> Result<SessionManager, SessionError>

Copies every entry of source into a new session file for cwd in dir, with parentSession pointing at the source.