Struct Session 

pub struct Session { /* private fields */ }

A conversation session with full history

Uses Arc<Vec> internally for efficient forking (copy-on-write).

Implementations

impl Session

pub fn new() -> Self

Create a new empty session

pub fn with_id(id: SessionId) -> Self

Create a session with a specific ID (for loading)

pub fn id(&self) -> &SessionId

Get the session ID

pub fn version(&self) -> u32

Get the session version

pub fn messages(&self) -> &[Message]

Get all messages

pub fn messages_mut(&mut self) -> &mut Vec<Message>

Get mutable access to messages (triggers CoW if Arc is shared)

pub fn created_at(&self) -> SystemTime

Get creation time

pub fn updated_at(&self) -> SystemTime

Get last update time

pub fn push(&mut self, message: Message)

Add a message to the session

Updates the timestamp. For adding multiple messages, prefer push_batch.

pub fn push_batch(&mut self, messages: Vec<Message>)

Add multiple messages in one operation (single timestamp update)

More efficient than multiple push calls when adding many messages.

pub fn touch(&mut self)

Explicitly update the timestamp

Call this after bulk operations that don’t update timestamps automatically.

pub fn has_pending_boundary(&self) -> bool

Whether the conversation has a pending turn boundary.

Returns true if the last message is User or ToolResults, meaning the conversation is waiting for an assistant turn and run_pending can resume without a new user message.

pub fn last_n(&self, n: usize) -> &[Message]

Get the last N messages

pub fn total_tokens(&self) -> u64

Count total tokens used.

pub fn total_usage(&self) -> Usage

Get total usage statistics for the session.

pub fn record_usage(&mut self, turn_usage: Usage)

Update cumulative usage after an LLM call.

pub fn set_system_prompt(&mut self, prompt: String)

Set a system prompt (adds or replaces System message at start)

pub fn append_system_context_blocks( &mut self, appends: &[PendingSystemContextAppend], )

Append one or more runtime system-context blocks to the canonical system prompt.

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

Get the last assistant message text content.

pub fn tool_call_count(&self) -> usize

Count tool calls made

pub fn metadata(&self) -> &Map<String, Value>

Get metadata

pub fn set_metadata(&mut self, key: &str, value: Value)

Set a metadata value

pub fn remove_metadata(&mut self, key: &str)

Remove a metadata value.

pub fn set_session_metadata( &mut self, metadata: SessionMetadata, ) -> Result<(), Error>

Store SessionMetadata in the session metadata map.

pub fn session_metadata(&self) -> Option<SessionMetadata>

Load SessionMetadata from the session metadata map.

pub fn set_system_context_state( &mut self, state: SessionSystemContextState, ) -> Result<(), Error>

Store durable system-context control state in the session metadata map.

pub fn system_context_state(&self) -> Option<SessionSystemContextState>

Load durable system-context control state from the session metadata map.

pub fn set_deferred_turn_state( &mut self, state: SessionDeferredTurnState, ) -> Result<(), Error>

Store durable deferred-turn control state in the session metadata map.

pub fn deferred_turn_state(&self) -> Option<SessionDeferredTurnState>

Load durable deferred-turn control state from the session metadata map.

pub fn set_build_state(&mut self, state: SessionBuildState) -> Result<(), Error>

Store recoverable build-only session state in the session metadata map.

pub fn build_state(&self) -> Option<SessionBuildState>

Load recoverable build-only session state from the session metadata map.

pub fn set_tool_visibility_state( &mut self, state: SessionToolVisibilityState, ) -> Result<(), Error>

Store durable tool-visibility control state in the session metadata map.

pub fn tool_visibility_state(&self) -> Option<SessionToolVisibilityState>

Load durable tool-visibility control state from the session metadata map.

pub fn set_mob_tool_authority_context( &mut self, authority_context: Option<MobToolAuthorityContext>, ) -> Result<(), Error>

Store typed mob operator authority inside canonical build-state metadata.

pub fn mob_tool_authority_context(&self) -> Option<MobToolAuthorityContext>

Load typed mob operator authority from canonical build-state metadata.

pub fn fork_at(&self, index: usize) -> Self

Fork the session at a specific message index

Creates a new session with a subset of messages. The messages are copied (not shared) since the new session has a different prefix.

pub fn fork(&self) -> Self

Fork the entire session (full history)

This is O(1) - the new session shares the message buffer via Arc. Copy-on-write occurs when either session mutates its messages.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

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.

impl Default for Session

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Session

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&Session> for SessionMeta

fn from(session: &Session) -> Self

Converts to this type from the input type.

impl Serialize for Session

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.