Struct ConversationState 

pub struct ConversationState {
    pub session: Session,
    pub context_head: ContextHeadPersistence,
    pub api_messages: Vec<Arc<Value>>,
    pub total_input_tokens: u64,
    pub total_output_tokens: u64,
    pub total_cache_read_tokens: u64,
    pub total_cache_creation_tokens: u64,
    pub session_cost: f64,
    pub keepwarm_cost: f64,
    pub keepwarm_tokens: ConversationTokens,
    pub queued_message: Option<String>,
    pub pending_events: Vec<String>,
}

Conversation state tracked by the engine.

Fields

session: Session

context_head: ContextHeadPersistence

api_messages: Vec<Arc<Value>>

total_input_tokens: u64

total_output_tokens: u64

total_cache_read_tokens: u64

total_cache_creation_tokens: u64

session_cost: f64

keepwarm_cost: f64

Prompt-cache keep-warm spend (task #444), already INCLUDED in session_cost and shown separately; persisted with it (Session::keepwarm_cost).

keepwarm_tokens: ConversationTokens

Keep-warm ping tokens, already INCLUDED in the total_* counters above and shown separately so /stats adds up.

queued_message: Option<String>

Message queued to send after current stream completes.

pending_events: Vec<String>

Events buffered during streaming — drained on stream completion.

Implementations

impl ConversationState

pub fn new(session: Session) -> ConversationState

Create a new conversation with a fresh session.

pub fn from_resumed(session: Session) -> ConversationState

Create from a resumed session. A session saved before interruption markers existed (legacy abort_context recap) is migrated here too — /resume loads sessions without going through engine::setup — idempotently: an already-migrated session is untouched.

pub async fn save(&mut self) -> bool

Save the current conversation state to disk. Returns whether it was written: false when there is nothing to save (empty history), the context head is unverified (context_head), or the write failed (logged).

pub fn prepare_save(&mut self) -> Option<Session>

Fold the live state into self.session and return the snapshot to write — or None when there is nothing to save (empty history) or the context head is unverified. The session actor hands the snapshot to its background writer (session::persister) instead of awaiting the I/O. The clone is cheap: messages are Arc-shared.

pub async fn persist_context_head( &mut self, session_id: &str, messages: Vec<Arc<Value>>, ) -> Result<(), Error>

Persist a runtime-requested head using host metadata and latest usage. The caller completes the receipt with this exact result and continues consuming the runtime’s typed terminal error on failure.

pub async fn clear(&mut self, runtime: &Runtime)

Clear the current session and start fresh.

pub fn snapshot(&self, consecutive_auto_turns: u32) -> ConversationSnapshot

Serializable mirror for clients (SessionEventWire::Conversation). consecutive_auto_turns is actor/App-side state, not conversation state, so the caller supplies it.

pub fn add_usage( &mut self, input_tokens: u64, output_tokens: u64, cache_read: u64, cache_creation: u64, cache_creation_5m: Option<u64>, cache_creation_1h: Option<u64>, model: &str, )

Add usage from a model turn.

cache_creation_5m / cache_creation_1h are the cache-write TTL split. When either is present the cost uses the split rates (5m: 1.25×, 1h: 2.0×); when both are None the aggregate cache_creation is billed at the 5m rate (fail-cheap fallback).