Struct Session 

pub struct Session {
    pub conversation: ConversationHistory,
    pub model_id: String,
    pub reasoning: ReasoningLevel,
    pub safety_mode: SafetyMode,
    pub last_token_usage: Option<TokenUsageTotals>,
    pub cumulative_token_usage: TokenUsageTotals,
    pub context_usage: Option<ContextUsageSnapshot>,
    pub is_subagent: bool,
    pub agent_preamble: Option<String>,
    pub plan: Option<PlanState>,
    pub scratchpad: Option<PathBuf>,
}

Persistent conversational state that survives across turns.

“Session” here means the user-visible chat session, not the tokio runtime or the TCP connection to the provider. One chat = one Session = one on-disk ConversationHistory file.

Fields

conversation: ConversationHistory

model_id: String

reasoning: ReasoningLevel

safety_mode: SafetyMode

Live safety mode for this session. Initialized from config.safety.mode, then mutated in-session by Shift+Tab / /safety (session-scoped — never written back to the config file). The reducer threads this into Cmd::ExecuteTool so the policy gate enforces the current mode, not the startup snapshot.

last_token_usage: Option<TokenUsageTotals>

Token usage for the most recent completed provider request. None means the provider did not report usage for that turn.

cumulative_token_usage: TokenUsageTotals

Prompt/completion/total API usage accumulated for this session.

context_usage: Option<ContextUsageSnapshot>

Latest model-visible context snapshot. This may be an estimate while a request is in flight and is replaced by provider-reported usage when available.

is_subagent: bool

True when this session IS a subagent (a child reducer driven by SubagentTool). system_prompt_for_state appends the subagent contract (final message = the report returned to the parent) when set. Never true for a user-facing session.

agent_preamble: Option<String>

Agent-type system-prompt block (e.g. the Explore type’s “read-only reconnaissance” charter), appended after the subagent contract. Only ever Some on subagent sessions.

plan: Option<PlanState>

Some while the session is in plan mode (see PlanState). Never Some on subagent sessions — children explore, they don’t plan.

scratchpad: Option<PathBuf>

Per-session scratch directory, once the effect layer has materialized it on disk (Cmd::EnsureScratchpad -> Msg::ScratchpadReady). None until then, and reset whenever the conversation id changes (/clear, /load, rewind fork) — the reducer re-emits EnsureScratchpad at those points. The reducer stamps this onto Cmd::ExecuteTool so tools see it via ExecContext::scratchpad. Runtime-only, never persisted.

Implementations

impl Session

pub fn snapshot_conversation(&self) -> ConversationHistory

Clone the conversation with the live meters + safety mode overlaid, so a saved file carries the full restorable state. These fields live on Session (which is NOT serialized — only conversation is), so every Cmd::SaveConversation snapshots them in and seed_conversation hydrates them back on resume.

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

The committed message log. All messages visible in the chat widget live here; partial in-flight content lives in TurnState::Generating.

pub fn append(&mut self, msg: ChatMessage, now: DateTime<Local>)

Append a committed assistant/user/tool message. Mutation happens through here so the reducer has one chokepoint to update the conversation’s updated_at and derived title.

now is the reducer’s injected clock (state.now). It stamps both the message’s commit timestamp and updated_at — the wall-clock stamp ChatMessage::new put on the message at construction is deliberately overwritten with the deterministic one, so update() is a pure function and --replay recommits identical 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.