Struct AgentSessionState 

pub struct AgentSessionState {

    pub session_id: String,
    pub conversation: Vec<Content>,
    pub messages: Arc<Vec<Message>>,
    pub schema_version: SchemaVersion,
    pub stats: SessionStats,
    pub auto_compact_suppressed: u8,
    pub constraints: SessionConstraints,
    pub outcome: TaskOutcome,
    pub stop_reason: Option<String>,
    pub total_cost_usd: Option<f64>,
    pub is_completed: bool,
    pub current_stage: Option<String>,
    pub created_contexts: Vec<String>,
    pub modified_files: Vec<String>,
    pub executed_commands: Vec<String>,
    pub warnings: Vec<String>,
    pub last_file_path: Option<String>,
    pub last_dir_path: Option<String>,
    pub consecutive_tool_loops: usize,
    pub tool_loop_limit_hit: bool,
    pub consecutive_escalations: u32,
    pub progress_hashes: VecDeque<u64>,
    pub stagnant_turns: usize,
    pub last_processed_message_idx: usize,
    pub previous_response_chains: HashMap<(String, String), ResponsesContinuationState>,
    pub error_recovery: Arc<Mutex<ErrorRecoveryState>>,
    pub pending_actions: PendingActions,
    pub consecutive_idle_turns: usize,
    pub max_tool_loop_streak: usize,
    pub turn_count: usize,
    pub turn_total_ms: u128,
    pub turn_max_ms: u128,
    pub turn_durations_ms: Vec<u128>,
    pub turn_tool_observations: Vec<ToolExecutionObservation>,
    /* private fields */
}

Manages the state of an active agent session, including conversation history, statistics, and turn-based constraints.

Fields

session_id: String

The thread or session ID.

conversation: Vec<Content>

Provider-specific conversation history (e.g., Gemini style).

messages: Arc<Vec<Message>>

Standardized conversation messages (OpenAI/Anthropic style).

Stored in an Arc so request construction can share the history with the provider without cloning the full conversation every turn. Mutations use copy-on-write; the common unique-owner path remains O(1).

schema_version: SchemaVersion

Schema version for durable state persistence.

stats: SessionStats

Statistics for the current session.

auto_compact_suppressed: u8

Auto-compaction suppression state: SUPPRESS_NONE allows compaction; other values gate automatic compaction until cleared by success, model switch, or explicit /compact.

constraints: SessionConstraints

Constraints and limits for the session.

outcome: TaskOutcome

Outcome of the session if completed.

stop_reason: Option<String>

Provider stop reason associated with the last model turn, when available.

total_cost_usd: Option<f64>

Estimated total API cost in USD for the session, when available.

is_completed: bool

Whether the session has completed.

current_stage: Option<String>

Current reasoning stage.

created_contexts: Vec<String>

modified_files: Vec<String>

executed_commands: Vec<String>

warnings: Vec<String>

last_file_path: Option<String>

last_dir_path: Option<String>

consecutive_tool_loops: usize

tool_loop_limit_hit: bool

consecutive_escalations: u32

Consecutive escalation events in the current escalation chain. Reset to 0 when tool calls dispatch without escalation.

progress_hashes: VecDeque<u64>

Rolling window of progress hashes for stagnation detection. Each entry is a hash of the assistant response content + key state.

stagnant_turns: usize

Consecutive turns with matching progress hashes.

last_processed_message_idx: usize

previous_response_chains: HashMap<(String, String), ResponsesContinuationState>

Responses-style continuation state keyed by normalized provider/model pairs.

error_recovery: Arc<Mutex<ErrorRecoveryState>>

Agent-local recent error diagnostics for interrupted or repeated tool failures.

pending_actions: PendingActions

Pending tool actions that have been issued but not yet returned.

consecutive_idle_turns: usize

max_tool_loop_streak: usize

turn_count: usize

turn_total_ms: u128

turn_max_ms: u128

turn_durations_ms: Vec<u128>

turn_tool_observations: Vec<ToolExecutionObservation>

One canonical terminal observation per tool invocation in this turn.

Implementations

impl AgentSessionState

pub fn new( session_id: String, max_turns: usize, max_tool_loops: usize, max_context_tokens: usize, ) -> Self

pub fn note_request_sent(&mut self)

Records that an LLM request was just dispatched, so the next call to Self::cache_gap_exceeds can measure the idle gap since this request.

pub fn cache_gap_exceeds(&self, threshold: Duration) -> Option<Duration>

Returns the elapsed time since the last dispatched request when it exceeds threshold, or None if there was no prior request or the gap is still within the threshold. Used to warn that the provider prompt cache has likely expired before the next request re-pays full input cost.

pub fn note_reasoning_effort_change( &mut self, effort: Option<ReasoningEffortLevel>, ) -> bool

Checks whether effort differs from the reasoning effort used for the previous request in this session, then stores effort as the new baseline. Returns true only when a prior effort was recorded and it differs from effort (i.e. this is a genuine mid-task change, not the first request of the session).

pub fn note_model_change(&mut self, model: &str) -> bool

Checks whether model differs from the model used for the previous request in this session, then stores model as the new baseline. Returns true only when a prior model was recorded and it differs from model (i.e. this is a genuine mid-task switch, not the first request of the session). Prompt caches are unique per model, so a switch re-pays full input cost even for an otherwise identical prefix.

pub fn record_turn(&mut self, start: &Instant, recorded: &mut bool)

Record a completed turn.

pub fn finalize_outcome(&mut self, max_turns: usize)

pub fn register_tool_loop(&mut self) -> usize

pub fn reset_tool_loop_guard(&mut self)

pub fn previous_response_id_for( &self, provider: &str, model: &str, ) -> Option<String>

pub fn previous_response_chain_for( &self, provider: &str, model: &str, ) -> Option<&ResponsesContinuationState>

pub fn set_previous_response_chain( &mut self, provider: &str, model: &str, response_id: Option<&str>, messages: Vec<Message>, )

pub fn clear_previous_response_chain_for(&mut self, provider: &str, model: &str)

pub fn clear_previous_response_chain(&mut self)

pub fn mark_tool_loop_limit_hit(&mut self)

pub fn messages_mut(&mut self) -> &mut Vec<Message>

Mutable access to the conversation history.

Returns mutable history with copy-on-write when a request still shares it.

pub fn add_user_message(&mut self, text: String)

Add a user message to the history with metadata.

pub fn add_user_message_with_intent( &mut self, text: String, intent_id: Option<String>, )

Add a user message and optionally tag it with the steering intent that produced it. The tag survives message serialization for recovery.

pub fn record_progress_hash_and_check_stagnation(&mut self) -> bool

Record the current assistant response hash and return true if stagnation detected.

pub fn attach_metadata_to_last(&mut self, source: &str, estimated_tokens: usize)

Attach metadata to the most recent message. Used by the execution loop to annotate LLM responses and tool results after they are pushed.

pub fn utilization(&self) -> f64

Check if context limits are approaching.

pub fn total_tokens(&self) -> usize

Calculate total estimated tokens in the conversation. Returns the cached value updated incrementally on each push. Use Self::reconcile_token_count after mutations that bypass push methods.

pub fn reconcile_token_count(&mut self)

Recompute the cached token count from scratch by scanning all messages. Call this after mutations that bypass push methods (e.g., normalize_history, direct messages field access, or deserialization).

pub fn adjust_token_count(&mut self, delta: isize)

Manually adjust the cached token count. Use when a message is added or removed outside of the standard push methods.

pub fn preflight_token_check( &self, system_prompt_tokens: usize, tool_def_tokens: usize, reserved_output_tokens: usize, ) -> (bool, usize, usize)

Pre-flight check: does the assembled prompt fit within the context window?

Estimates total tokens for the full request (conversation history + system prompt + tool definitions) and compares against the available budget (max_context_tokens - reserved_output_tokens).

Returns (fits, estimated_total, available_budget).

pub fn find_safe_split_point(&self, preferred_split_at: usize) -> usize

Find a safe split point for history trimming that doesn’t break tool call/output pairs.

pub fn normalize(&mut self)

Normalize history to enforce call/output pairing invariants.

pub fn clear_conversation_history(&mut self)

Clear all conversation history for a context reset.

Following the context engineering pattern: “Context reset uses external artifacts as startup material to open a clean new context/session. It does not preserve the full conversation history.”

This clears messages, conversation, resets the token count, and resets the processed-message cursor. The orient context (injected via the system prompt) provides the agent with durable artifact references to reorient from. Response continuation chains are also cleared since they reference the discarded history.

pub fn into_results( self, summary: String, thread_events: Vec<ThreadEvent>, total_duration_ms: u128, ) -> TaskResults

pub fn push_tool_result( &mut self, call_id: String, tool_name: &str, result: &Value, is_gemini: bool, )

Push a successful tool result to both conversation (for Gemini) and messages.

pub fn push_tool_error( &mut self, call_id: String, tool_name: &str, error_payload: &Value, is_gemini: bool, )

Push a tool error to both conversation (for Gemini) and messages.

pub fn push_warning(&mut self, warning: impl Into<String>)

Record a session warning, skipping exact duplicates.

In long-running sessions, the same warning can fire repeatedly (e.g. “Tool was rate limited; halting further tool calls this turn.” on every rate-limited call). Deduplicating keeps the TaskResults.warnings Vec bounded and the evaluator prompt clean. The Vec is also capped at MAX_SESSION_WARNINGS as a safety net against unbounded growth from unique-but-repetitive warnings. When the cap is reached a single elision marker is appended so consumers know warnings were truncated rather than silently losing data.