Struct Session 

pub struct Session {

    pub id: String,
    pub title: String,
    pub name: Option<String>,
    pub model: String,
    pub thinking_level: String,
    pub system_prompt: Option<String>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub total_input_tokens: u64,
    pub total_output_tokens: u64,
    pub session_cost: f64,
    pub keepwarm_cost: f64,
    pub keepwarm_tokens: KeepwarmTokens,
    pub message_count: usize,
    pub parent_session: Option<String>,
    pub compacted_into: Option<String>,
    pub env: Option<Vec<(String, String)>>,
    pub env_stripped: Vec<String>,
    pub api_messages: Vec<Arc<Value>>,
    pub abort_context: Option<String>,
    pub prompt_provenance: Option<PromptProvenance>,
    pub compaction: Option<CompactionRecord>,
}

Fields

id: String

title: String

name: Option<String>

model: String

thinking_level: String

system_prompt: Option<String>

created_at: DateTime<Utc>

updated_at: DateTime<Utc>

total_input_tokens: u64

total_output_tokens: u64

session_cost: f64

keepwarm_cost: f64

Prompt-cache keep-warm spend (task #444), already INCLUDED in session_cost; persisted so a resumed/reloaded session still labels it. Absent (0) on sessions that never kept warm.

SNAPSHOT-ONLY: never journaled. The v2 journal’s SessionMeta is deny_unknown_fields, so a new field there would make an older build (0.10.1) treat every meta record as a torn tail and truncate the session; the .json snapshot tolerates unknown fields. In journal mode the label is therefore as of the last snapshot (slightly stale until the next one); load clamps it to session_cost.

keepwarm_tokens: KeepwarmTokens

Keep-warm ping tokens, already INCLUDED in the token totals. SNAPSHOT-ONLY, like keepwarm_cost; clamped on load to the totals that survive a reload.

message_count: usize

Persisted listing hint: api_messages.len() at save time. Declared BEFORE api_messages so it lands in the header that read_session_header reads without touching the message array. Not authoritative in memory — use api_messages.len(); refreshed by session_journal::save_session_in_dir. Legacy files → 0.

parent_session: Option<String>

ID of the session this was compacted from (backward link). Declared before api_messages so read_session_header sees it (F24).

compacted_into: Option<String>

ID of the session created by compacting this one (forward link). Declared before api_messages so read_session_header sees it (F24).

env: Option<Vec<(String, String)>>

Session environment snapshot (names+values, secrets stripped). Declared before api_messages so read_session_header sees it. Belt-and-braces: values for secret keys are scrubbed on save even if a future client forgets to strip.

env_stripped: Vec<String>

Names of env vars stripped as secrets (T5, names only, never values). Declared before api_messages so read_session_header sees it.

api_messages: Vec<Arc<Value>>

abort_context: Option<String>

Legacy: the “ABORT CONTEXT” recap older Synaps saved for an interrupted turn, to prepend to the next user message. Never written now (an interrupted turn is real history plus a marker, agent_engine::engine::interrupt) and never injected: a session that still carries one is migrated when it is loaded (recap dropped, marker appended).

prompt_provenance: Option<PromptProvenance>

compaction: Option<CompactionRecord>

Typed compaction summary provenance (spec §9.3). Present on sessions produced by (or updated in place by) a compaction transition.

Implementations

impl Session

pub fn clamp_keepwarm_to_totals(&mut self)

The keep-warm labels are a subset of the totals; a journal replay can leave them (snapshot-only) ahead of totals that were reset since, so clamp them back under. Never raises anything.

impl Session

pub fn new( model: &str, thinking_level: &str, system_prompt: Option<&str>, ) -> Session

pub fn from_compaction_record( parent: &Session, summary_text: &str, record: CompactionRecord, ) -> Session

Create a successor session from a compaction transition (spec §9.3). The summary enters context through the canonical sanitized rendering (crate::compaction::compaction_context_messages); the parent’s system prompt stays TYPED metadata — the successor’s system_prompt field and the provenance record — never plain user text.

pub fn auto_title(&mut self)

Set title from the first user message if not already set

pub async fn save(&self) -> Result<(), Error>

Persist this session under the configured persistence mode (session_persistence config key; default is the unchanged legacy JSON path — see Task 35 / crate::core::session_journal).

pub async fn save_durable(&self) -> Result<(), Error>

Publish a full context checkpoint and wait for durable persistence. Captures the destination and configured mode BEFORE spawning blocking work. Unlike save, journal mode always replaces the snapshot here.

On success the snapshot file AND its containing directory have been fsynced (also newly created directory ancestry). Snapshot publication is the logical commit: errors from directory sync or journal cleanup can occur AFTER it is visible, and do not imply rollback. Callers must stop inference on ANY error and reload/retry rather than assume the old head survived. Dropping this future does not cancel blocking I/O.

Async saves to the same destination/session are ordered in-process, including blocking writers whose awaiter was dropped. Callers still own ordering of logical session mutations; this is not a multi-process transaction. Durable saves fail closed on non-Unix platforms; fsync guarantees still depend on the underlying filesystem/device.

pub async fn recover_durable(id: &str) -> Result<Session, Error>

Resolve an ambiguous head without racing an older detached writer. Read and durable re-publication share the same save-order guard. A successful read alone must not clear a failed directory-sync barrier.

pub fn load(id: &str) -> Result<Session, Error>

pub fn load_from_dir(dir: &Path, id: &str) -> Result<Session, Error>

Canonical backward-compatible host load for a caller-selected sessions directory. Both legacy snapshots and journal-backed sessions resolve through the same journal overlay implementation.

pub fn info(&self) -> SessionInfo

pub fn set_name(&mut self, name: &str) -> Result<(), Error>

Assign a name to this session. Validates name, enforces uniqueness across sessions, and rejects collisions with existing chain names. Idempotent: re-applying the current name is a no-op.

pub fn clear_name(&mut self)

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<(), Error>

Formats the value using the given formatter.

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

fn deserialize<__D>( __deserializer: __D, ) -> Result<Session, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Session

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.