Struct SessionStats 

pub struct SessionStats {
    pub turns: u64,
    pub input_tokens: u64,
    pub output_tokens: u64,
    pub cache_read_tokens: u64,
    pub cache_write_tokens: u64,
    pub cache_turns: u64,
    pub tools: Vec<ToolStat>,
    pub tool_errors: u64,
    pub last_input_tokens: Option<u64>,
    pub cost: Option<Cost>,
}

Aggregate view of a conversation for /usage: how many turns reported usage, the summed token counts, and which tools ran.

Pure data — no timing, and no cost OF ITS OWN: cost is filled by the caller that knows the provider (pricing::cost_of, called from the actor’s Request::Usage reply), because pricing keys on a base_url/model pair that an AgentMessage cannot carry. Every other field folds from the transcript alone. Derive order is fixed so tests can compare by value.

Fields

turns: u64

Assistant messages that carried Some(usage).

input_tokens: u64

output_tokens: u64

cache_read_tokens: u64

Cache counts absent on a call are treated as 0.

cache_write_tokens: u64

cache_turns: u64

Assistant messages that reported AT LEAST ONE cache field — the honest denominator for cache_hit_pct(). A provider that reports nothing must OMIT the rate rather than print 0% (streamfn.rs:1255 cache_read_tokens: (usage.cached_input_tokens > 0).then_some(...): zero is rig’s sentinel for “not reported”).

tools: Vec<ToolStat>

One entry per distinct tool name, sorted by calls descending, ties by name ascending. Empty when no tool has been called. (WAS Vec<(String, u64)> — same sort, more facts.)

tool_errors: u64

Σ tools[..].errors — the headline count summary() prints.

last_input_tokens: Option<u64>

Provider-reported input tokens of the most recent Assistant message with Some(usage). None until a turn reports usage. NOT summed by aggregate() (see below): it is a “how full was the last request” fact.

cost: Option<Cost>

The session’s $ cost. None from the pure fold (the fold has no provider); Some once the actor prices it. skip_serializing_if keeps it off the wire when absent — mandatory for an additive variant.

Implementations

impl SessionStats

pub fn summary(&self) -> String

The one-line summary both front-ends print: plain text — no colors, no layout, no context; front-ends add chrome.

Contract:

• turns == 0 ⇒ "(no usage reported)".
• otherwise ⇒ "usage: N turns, X in, Y out[, C cache read][, W cache write][, tools: …]" where the cache fields are omitted when 0, the tools: segment is omitted when no tool ran, and the tool names are capped at TOOL_LIST_CAP, the remainder folded into "+K more".
• appends , N% cache when cache_hit_pct() is Some, , N tool error(s) when tool_errors > 0, and , ~$d.dddd when cost is Some — (N turns unpriced) when Cost::unpriced_turns > 0. % cache sits right after the cache tokens, tool error(s) after tools:, and ~$ last.
• The trailing context U/L readout is intentionally NOT here: its limit comes from the front-end (REPL model_limit, TUI status.context_limit), so each wraps/appends it.

pub fn cache_hit_pct(&self) -> Option<u8>

Cache hit rate as an integer percent, rounded to the nearest percent.

Contract:

• Some((cache_read * 100 + input / 2) / input) when input_tokens > 0 && cache_turns > 0, else None: a session that reported no cache OMITS the clause instead of claiming 0%.
• the denominator is input_tokens ALONE. On the chat-completions wire a cached read is a SUBSET of input_tokens (rig maps prompt_tokens_details.cached_tokens), so adding cache_read back would double-count. A provider on the Anthropic wire — where input_tokens EXCLUDES cache reads/writes — would understate here; wcode speaks the OpenAI-compatible wire only, and that is the documented assumption (D028).
• saturates at 100: more cached tokens than input is a provider bug, and 120% on screen would be worse than the clamp.
• cache_write is not a hit: it is reported separately and priced.

pub fn tool_error_pct(&self) -> Option<u8>

Share of tool calls that did not succeed, rounded to the nearest percent.

Some((tool_errors * 100 + calls / 2) / calls) over Σcalls when a tool ran at all, else None. errors counts hook-blocked and synthesized aborts (see ToolStat), so this is “not a success”, never “the tool is buggy”; saturates at 100 for the same reason as cache_hit_pct.

Trait Implementations

impl Clone for SessionStats

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SessionStats

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

Formats the value using the given formatter.

impl Default for SessionStats

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SessionStats

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for SessionStats

impl PartialEq for SessionStats

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for SessionStats

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SessionStats