Struct SessionState 

pub struct SessionState {

    pub id: String,
    pub version: u32,
    pub started_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub project_root: Option<String>,
    pub shell_cwd: Option<String>,
    pub task: Option<TaskInfo>,
    pub findings: Vec<Finding>,
    pub decisions: Vec<Decision>,
    pub files_touched: Vec<FileTouched>,
    pub test_results: Option<TestSnapshot>,
    pub progress: Vec<ProgressEntry>,
    pub next_steps: Vec<String>,
    pub evidence: Vec<EvidenceRecord>,
    pub intents: Vec<IntentRecord>,
    pub active_structured_intent: Option<StructuredIntent>,
    pub stats: SessionStats,
    pub terse_mode: bool,
    pub compression_level: String,
}

Persistent session state tracking task, findings, files, decisions, and stats.

Fields

id: String

version: u32

started_at: DateTime<Utc>

updated_at: DateTime<Utc>

project_root: Option<String>

shell_cwd: Option<String>

task: Option<TaskInfo>

findings: Vec<Finding>

decisions: Vec<Decision>

files_touched: Vec<FileTouched>

test_results: Option<TestSnapshot>

progress: Vec<ProgressEntry>

next_steps: Vec<String>

evidence: Vec<EvidenceRecord>

intents: Vec<IntentRecord>

active_structured_intent: Option<StructuredIntent>

stats: SessionStats

terse_mode: bool

When true, resume / compaction prompts encourage concise model replies.

compression_level: String

Unified compression level label (off/lite/standard/max).

Implementations

impl SessionState

pub fn new() -> Self

Creates a new session with a unique ID and current timestamp.

pub fn increment(&mut self)

Bumps the version counter and marks the session as dirty.

pub fn should_save(&self) -> bool

Returns true if enough changes have accumulated to warrant a disk save.

pub fn set_task(&mut self, description: &str, intent: Option<&str>)

Sets the active task and infers a structured intent from the description.

pub fn add_finding( &mut self, file: Option<&str>, line: Option<u32>, summary: &str, )

Records a finding (discovery or observation) in the session log.

pub fn add_decision(&mut self, summary: &str, rationale: Option<&str>)

Records a design or implementation decision with optional rationale.

pub fn touch_file( &mut self, path: &str, file_ref: Option<&str>, mode: &str, tokens: usize, )

Records a file read/access in the session, incrementing its read count.

pub fn mark_modified(&mut self, path: &str)

Marks a previously touched file as modified (written to).

pub fn record_tool_call(&mut self, tokens_saved: u64, tokens_input: u64)

Increments the tool call counter and accumulates token savings.

pub fn record_intent(&mut self, intent: IntentRecord)

Records an inferred or explicit intent, coalescing consecutive duplicates.

pub fn record_tool_receipt( &mut self, tool: &str, action: Option<&str>, input_md5: &str, output_md5: &str, agent_id: Option<&str>, client_name: Option<&str>, )

Appends an auditable evidence record for a tool invocation.

pub fn record_manual_evidence(&mut self, key: &str, value: Option<&str>)

Appends a manual (non-tool) evidence record to the audit log.

pub fn has_evidence_key(&self, key: &str) -> bool

Returns true if an evidence record with the given key exists.

pub fn record_cache_hit(&mut self)

Increments the session-level cache hit counter.

pub fn record_command(&mut self)

Increments the session-level command counter.

pub fn effective_cwd(&self, explicit_cwd: Option<&str>) -> String

Returns the effective working directory for shell commands. Priority: explicit cwd arg > session shell_cwd > project_root > process cwd. Explicit CWD and stored shell_cwd are jail-checked against the project root to prevent MCP clients from escaping the workspace.

pub fn update_shell_cwd(&mut self, command: &str)

Updates shell_cwd by detecting cd in the command. Handles: cd /abs/path, cd rel/path (relative to current cwd), cd .., and chained commands like cd foo && .... The new CWD is jail-checked against the project root.

pub fn format_compact(&self) -> String

Formats the session state as a compact multi-line summary for agent context.

pub fn build_compaction_snapshot(&self) -> String

Builds a size-limited XML snapshot of session state for context compaction.

pub fn save_compaction_snapshot(&self) -> Result<String, String>

Writes the compaction snapshot to disk and returns the snapshot string.

pub fn load_compaction_snapshot(session_id: &str) -> Option<String>

Loads a previously saved compaction snapshot by session ID.

pub fn load_latest_snapshot() -> Option<String>

Loads the most recently modified compaction snapshot from disk.

When a project root can be derived from CWD, only snapshots whose embedded session data matches the project root are considered. This prevents cross-project snapshot leakage.

pub fn build_resume_block(&self) -> String

Build a compact resume block for post-compaction injection. Max ~500 tokens. Includes task, decisions, files, and archive references.

pub fn save(&mut self) -> Result<(), String>

Serializes and writes the session state to disk synchronously.

pub fn prepare_save(&mut self) -> Result<PreparedSave, String>

Serialize session state while holding the lock (CPU-only), reset the unsaved counter, and return a PreparedSave whose I/O can be deferred to a background thread via write_to_disk().

pub fn load_latest() -> Option<Self>

Loads the most recent session from disk.

Prefers the session matching the current working directory’s project root. Falls back to the global latest.json pointer only if no project-scoped match is found. This prevents cross-project session leakage.

pub fn load_latest_for_project_root(project_root: &str) -> Option<Self>

Loads the most recent session matching a specific project root.

pub fn load_by_id(id: &str) -> Option<Self>

Loads a specific session from disk by its unique ID.

pub fn list_sessions() -> Vec<SessionSummary>

Lists all saved sessions as summaries, sorted by most recently updated.

pub fn cleanup_old_sessions(max_age_days: i64) -> u32

Deletes sessions older than max_age_days, preserving the latest. Returns count removed.

Trait Implementations

impl Clone for SessionState

fn clone(&self) -> SessionState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SessionState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SessionState

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SessionState

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for SessionState

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

where __S: Serializer,

Serialize this value into the given Serde serializer.