Struct AgentSession 

pub struct AgentSession { /* private fields */ }

Bridges the agent loop events and session persistence.

Handles:

• Event-driven message persistence (persist tool results as they arrive)
• Automatic model/thinking/tool change detection and persistence

Implementations

impl AgentSession

pub fn new(mgr: SessionManager) -> Self

Create a new AgentSession from a SessionManager (pi-compatible: keeps the manager).

pub fn create(cwd: &Path, session_dir: Option<&Path>) -> Self

Create a new persisted session.

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

Open a specific session file.

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

Create an in-memory session (no persistence).

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

Continue most recent session or create new.

pub fn fork_from( source_path: &Path, target_cwd: &Path, session_dir: Option<&Path>, options: Option<&NewSessionOptions>, ) -> Result<Self>

Fork a session from another project directory.

pub fn set_compaction_config( &mut self, api_key: String, model_name: &str, context_window: u64, model_config: Option<ModelConfig>, )

Configure compaction with API key, model, context window, and model config.

pub fn set_auto_compact(&mut self, enabled: bool)

Enable or disable auto-compaction.

pub fn set_registry(&mut self, registry: Arc<ProviderRegistry>)

Set the provider registry for per-message cost computation (pi-style).

pub fn sync_thinking_level(&mut self)

Sync the thinking level from the session context. Should be called after the session context changes.

pub fn compaction_settings_mut(&mut self) -> &mut CompactionSettings

Get the current compaction settings (mutable, for modification).

pub fn compaction_settings(&self) -> &CompactionSettings

Get the current compaction settings.

pub fn set_extensions(&mut self, extensions: Vec<Box<dyn Extension>>)

Set the list of extensions (for compaction hooks).

pub fn abort_compaction(&self)

Abort any in-progress compaction (matching pi’s abortCompaction()). The cancellation will be picked up by extension hooks on their next cancel.is_cancelled() check.

pub fn on_compaction_event(&mut self, callback: CompactionEventCallback)

Register a compaction lifecycle event listener.

pub fn reset_overflow_recovery(&mut self)

Reset overflow recovery state (called when starting a new turn). Pi-compatible: reset overflow recovery when a user message arrives (matches pi’s _overflowRecoveryAttempted reset in message_start for user role).

pub fn is_context_overflow_error(msg: &AgentMessage) -> bool

Check if a provider error indicates context overflow. Matches pi’s context overflow detection patterns.

pub fn session(&self) -> &Session

Borrow the underlying session manager. Borrow the underlying Session.

pub fn session_manager(&self) -> &SessionManager

Borrow the underlying SessionManager.

pub fn session_mut(&mut self) -> &mut Session

Mutably borrow the underlying Session.

pub fn into_session(self) -> Session

Consume and return the inner Session.

pub fn ensure_flushed(&mut self)

Flush is handled automatically by SessionManager on every append_message. Call this to force an early flush (e.g. before saving state externally).

pub fn cwd(&self) -> &Path

pub fn session_dir(&self) -> &Path

pub fn is_persisted(&self) -> bool

pub fn session_id(&self) -> String

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

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

pub fn on_model_change(&mut self, provider: &str, model_id: &str) -> bool

Persist a model change if it differs from the last known model. Pi-compatible: writes immediately to the session.

pub fn on_thinking_level_change(&mut self, level: &str) -> bool

Persist a thinking level change if it differs from the last known level. Pi-compatible: writes immediately to the session.

pub fn on_active_tools_change(&mut self, tools: &[String]) -> bool

Persist an active tools change if it differs from the last known set. Pi-compatible: writes immediately to the session.

pub fn new_session(&mut self)

Reset the session (creates a new empty session) and clear all tracked state so the new session starts fresh.

pub fn send_user_message(&mut self, content: &str) -> String

Append a user message to the session (pi-compatible: persists immediately). Returns the entry id.

pub fn send_user_message_obj(&mut self, msg: &AgentMessage) -> String

Append a user message (pre-constructed) to the session. Returns the entry id.

pub fn on_agent_event(&mut self, event: &AgentEvent)

Process an agent event for automatic persistence (pi-compatible).

Pi persists every message (user, assistant, tool result, custom) immediately on message_end, not deferred to agent_end. Extension messages use custom_message entries (excluded from LLM context); all others use regular message entries.

Cost is computed per-message at creation time using the model’s cost config from the provider registry (pi-style: calculateCost in models.ts).

Call this from your agent event handler.

pub async fn check_auto_compact(&mut self) -> Result<bool, String>

Check if compaction should run and execute it if needed. Should be called after the agent finishes a turn (after on_agent_end). Returns true if compaction was performed.

pub async fn check_overflow_compact( &mut self, will_retry: bool, ) -> Result<bool, String>

Run compaction after a context overflow error. If will_retry is true, the agent turn will be retried after compaction. Returns Ok(true) if compaction was performed, Ok(false) if recovery already attempted.

pub async fn run_manual_compact( &mut self, custom_instructions: Option<&str>, ) -> Result<String, String>

Run compaction manually (ignores auto-compact setting). Returns the compaction summary text, or an error message.

pub async fn summarize_branch_navigation( &mut self, old_leaf_id: Option<&str>, target_id: &str, custom_instructions: Option<&str>, ) -> Result<String, String>

Summarise the abandoned branch when navigating to a different node.

Collects entries between old_leaf_id and the common ancestor with target_id, summarises them via the provider, and appends a BranchSummaryEntry to the session.

Returns the summary text, or an error message.

pub async fn set_branch( &mut self, branch_from_id: &str, custom_instructions: Option<&str>, ) -> Result<Option<String>, String>

Move the leaf pointer to an earlier entry (starts a new branch). Optionally summarizes the abandoned path if a provider is configured. custom_instructions are passed to the summarization prompt (pi-compatible). Returns the branch summary text if summarization was performed.

pub fn persist_extension_message(&mut self, msg: &AgentMessage)

Persist a tool result message (public so the agent loop can persist crash-safely). Deduplicates by tool_call_id. Persist an Extension message as a custom_message session entry (pi-compatible). Extension messages are NOT persisted as regular messages — they use the custom_message entry type which supports custom_type, display, and details.