Struct AgentState 

pub struct AgentState {
    pub messages: Vec<Message>,
    pub iteration: usize,
    pub stop_reason: Option<StopReason>,
    pub tool_results: Vec<ToolResult>,
    pub total_tokens: usize,
    pub input_tokens: usize,
    pub output_tokens: usize,
    pub last_input_tokens: Option<usize>,
    pub last_estimate_at_report: Option<usize>,
    pub last_estimate_divergence: Option<f64>,
}

Stable since 0.63.0

Agent execution state

Tracks the full lifecycle of an agent conversation including messages, token usage, tool results, and iteration progress.

Derives Serialize/Deserialize for session persistence and cross-process state transfer (e.g. oxios supervisor serialization).

Fields

messages: Vec<Message>

Conversation message history (user, assistant, and tool-result messages).

iteration: usize

Current agent loop iteration (incremented after each assistant turn).

stop_reason: Option<StopReason>

The reason the last turn stopped, if any.

tool_results: Vec<ToolResult>

Accumulated results from tool executions in the current conversation.

total_tokens: usize

Cumulative token count (input + output) across all turns.

input_tokens: usize

Cumulative prompt / input tokens across all turns.

output_tokens: usize

Cumulative completion / output tokens across all turns.

last_input_tokens: Option<usize>

Most-recent reported input-token count from a single LLM response.

Unlike Self::input_tokens (which is cumulative across all turns), this is overwritten on every ProviderEvent::Done with the count that turn actually sent to the model. It is the ground-truth signal used by compaction when available — see Self::current_token_source.

None until the first Done event has been observed.

last_estimate_at_report: Option<usize>

Heuristic token estimate (bytes/4) that was current when last_input_tokens was last set. Used to detect the bytes/4 drift described in #28 and surface it as a warning.

last_estimate_divergence: Option<f64>

Divergence factor (reported / estimate) at the time of the last Done. Surfaced in logs so the operator can see how badly the bytes/4 heuristic is undercounting on token-dense workloads. None until first divergence observation.

Implementations

impl AgentState

pub fn new() -> AgentState

Create a new, default-initialized agent state.

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

Add a user message

pub fn add_assistant_message(&mut self, content: String)

Add an assistant message

pub fn add_tool_result(&mut self, tool_call_id: String, content: String)

Add a tool result message to both the message history and the tool results list.

pub fn increment_iteration(&mut self)

Increment the iteration counter after an assistant turn completes.

pub fn set_stop_reason(&mut self, reason: StopReason)

Record the reason the last turn stopped.

pub fn record_usage(&mut self, input: usize, output: usize)

Accumulate token usage from a completed LLM call.

input is the input-token count for the just-completed turn — NOT a per-turn delta. The provider reports a fresh per-turn usage.input_tokens on every Done; we accumulate it into Self::input_tokens for lifetime accounting and also cache it as the most-recent observation via Self::record_provider_turn.

pub fn record_provider_turn( &mut self, input_tokens: usize, estimate_at_report: usize, )

Record the most recent provider-reported input-token count and the heuristic estimate that was current at the time of the report, so the loop can use the real count for compaction decisions and surface drift (issue #28 gap 2).

input_tokens is the value from ProviderEvent::Done.message.usage.input. estimate_at_report is the bytes/4 estimate taken at the same moment (i.e. the value the legacy path would have used for compaction).

pub fn current_token_source(&self) -> TokenSource

Current best estimate of context size, tagged with its source.

• Real(n) if the last completed turn reported usage.input_tokens.
• Heuristic(n) only before the first Done is observed (cold start).
• None if there are no messages yet.

Callers (notably maybe_compact) should prefer Real and only fall back to Heuristic on cold start. See issue #28.

pub fn clear(&mut self)

Clear all state, resetting for a new conversation.

pub fn replace_messages(&mut self, messages: Vec<Message>)

Replace the entire message history (used after context compaction).

pub fn estimate_tokens(&self) -> usize

Rough token-count estimate based on the serialized message JSON length.

pub fn is_complete(&self) -> bool

Returns true if the agent has signaled a stop reason.

Trait Implementations

impl Clone for AgentState

fn clone(&self) -> AgentState

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentState

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

Formats the value using the given formatter.

impl Default for AgentState

fn default() -> AgentState

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AgentState

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentState

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.