Struct TurnSummary 

pub struct TurnSummary {
    pub thread_id: ThreadId,
    pub turn: usize,
    pub total_turns: u32,
    pub turn_usage: TokenUsage,
    pub total_usage: TokenUsage,
    pub provenance: AuditProvenance,
    pub response_id: Option<String>,
    pub stop_reason: Option<StopReason>,
    pub tool_call_count: usize,
    pub duration_ms: u64,
    pub tool_runtime: ToolRuntime,
    pub strict_durability: bool,
}

Structured server-facing outcome metadata for a single turn.

Captures everything the server needs to durably persist about a turn’s LLM-level provenance: thread/turn identity, provider and model identifiers, response ID and stop reason from the turn-closing LLM call, token usage, tool-call count, wall-clock duration, and the TurnOptions the caller requested.

Why this exists

The original TurnOutcome only exposed token counts and turn numbers. Later server phases need:

• Provider / model — to correlate rows across provider rotations and to route audit streams by provider.
• Response ID — to join durable turn rows against the raw provider response stored externally (observability pipelines, replay, support escalations).
• Stop reason — to branch on end_turn vs tool_use vs refusal without re-parsing message history.
• Tool-call count — to bill tool execution and detect runaway turns without walking the tool registry.
• Duration — to feed SLO dashboards and auto-tune retry budgets.
• Tool runtime / strict durability flags — to record which execution profile was in effect, so later replay can reconstruct the same decisions.

Serialization

TurnSummary is fully serializable. Servers are expected to persist it alongside (or inside) their turn rows. Duration is exposed as duration_ms (milliseconds) to avoid a serde dance around std::time::Duration.

Authoritative vs convenience

Fields in TurnSummary are authoritative for server execution: they are produced by the same code path that writes the durable event store and are guaranteed to be consistent with the events the server observed on the wire. Convenience accessors on TurnOutcome (e.g. the legacy input_tokens / output_tokens fields on Done) are kept only so local callers do not have to break; new code should read from summary instead.

Fields

thread_id: ThreadId

Thread this turn belongs to.

Duplicated from the call site so the summary is self-describing when persisted alone (for durable audit rows).

turn: usize

Turn number that produced this outcome (1-indexed).

total_turns: u32

Total number of turns executed in this run so far.

For mid-run outcomes like NeedsMoreTurns / PendingToolCalls this equals turn. For terminal outcomes (Done, Refusal, Cancelled) it reflects the final total.

turn_usage: TokenUsage

Token usage for the LLM call(s) that produced this turn.

total_usage: TokenUsage

Cumulative token usage across every turn in this run so far.

provenance: AuditProvenance

Provider / model provenance captured from the turn-closing LLM call — identical shape to AuditProvenance so durable audit rows stay consistent with turn rows.

response_id: Option<String>

Provider response ID from the turn-closing LLM call.

None when the provider did not return an ID or the turn terminated before the LLM responded (e.g. cancelled before the first call).

stop_reason: Option<StopReason>

Stop reason reported by the turn-closing LLM call.

None when no response was produced for this turn (e.g. the turn was cancelled before the LLM replied, or the turn was resumed purely from external tool results without calling the LLM again).

tool_call_count: usize

Number of tool calls the LLM requested in this turn.

Zero for pure text turns.

duration_ms: u64

Wall-clock duration of this turn, in milliseconds.

Measured from the start of run_turn to the moment the outcome is returned. Clamped to u64::MAX on the unlikely overflow.

tool_runtime: ToolRuntime

The ToolRuntime selected for this turn.

strict_durability: bool

Whether strict durability was requested for this turn.

Implementations

impl TurnSummary

pub fn new( thread_id: ThreadId, turn: usize, provenance: AuditProvenance, options: &TurnOptions, ) -> Self

Construct an empty summary for a thread / provider / model.

Used by the runtime as a starting point; it then updates specific fields as the turn progresses. Tests and downstream consumers should generally pattern-match on the outcome and read fields from the populated summary rather than construct one from scratch.

Trait Implementations

impl Clone for TurnSummary

fn clone(&self) -> TurnSummary

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TurnSummary

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for TurnSummary

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for TurnSummary

impl PartialEq for TurnSummary

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for TurnSummary

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 TurnSummary