Enum TurnOutcome 

pub enum TurnOutcome {
    NeedsMoreTurns {
        turn: usize,
        turn_usage: TokenUsage,
        total_usage: TokenUsage,
        summary: TurnSummary,
    },
    Done {
        total_turns: u32,
        total_usage: TokenUsage,
        summary: TurnSummary,
    },
    AwaitingConfirmation {
        tool_call_id: String,
        tool_name: String,
        display_name: String,
        input: Value,
        description: String,
        continuation: Box<ContinuationEnvelope>,
        summary: TurnSummary,
    },
    Refusal {
        total_turns: u32,
        total_usage: TokenUsage,
        summary: TurnSummary,
    },
    Cancelled {
        total_turns: u32,
        total_usage: TokenUsage,
        summary: TurnSummary,
    },
    Error(AgentError),
    PendingToolCalls {
        turn: usize,
        turn_usage: TokenUsage,
        total_usage: TokenUsage,
        tool_calls: Vec<PendingToolCallInfo>,
        continuation: Box<ContinuationEnvelope>,
        summary: TurnSummary,
    },
}

Outcome of running a single turn.

This is returned by run_turn to indicate what happened and what to do next.

Server-facing contract

Every terminal variant (everything except TurnOutcome::Error) carries a TurnSummary with the provider/model/stop-reason/response-id/usage provenance that later server phases need to durably persist. Matching by field name continues to work because the legacy variant fields are preserved alongside the new summary field.

Variants

NeedsMoreTurns

Turn completed successfully, but more turns are needed.

Tools were executed and their results are stored in the message history. Call run_turn again with AgentInput::Continue to proceed.

Fields

turn: usize

The turn number that just completed

turn_usage: TokenUsage

Token usage for this turn

total_usage: TokenUsage

Cumulative token usage so far

summary: TurnSummary

Structured server-facing outcome metadata.

Done

Agent completed successfully (no more tool calls).

Fields

total_turns: u32

Total turns executed

total_usage: TokenUsage

Cumulative token usage

summary: TurnSummary

Structured server-facing outcome metadata.

AwaitingConfirmation

A tool requires user confirmation.

Present this to the user and call run_turn with AgentInput::Resume to continue.

Fields

tool_call_id: String

ID of the pending tool call (from LLM)

tool_name: String

Tool name string (for LLM protocol)

display_name: String

Human-readable display name

input: Value

Tool input parameters

description: String

Description of what confirmation is needed

continuation: Box<ContinuationEnvelope>

Versioned continuation envelope for resuming.

summary: TurnSummary

Structured server-facing outcome metadata.

Refusal

Model refused the request (safety/policy).

Fields

total_turns: u32

Total turns executed

total_usage: TokenUsage

Cumulative token usage

summary: TurnSummary

Structured server-facing outcome metadata.

Cancelled

The turn was cancelled via a cancellation token.

Fields

total_turns: u32

Total turns executed before cancellation

total_usage: TokenUsage

Cumulative token usage

summary: TurnSummary

Structured server-facing outcome metadata.

Error(AgentError)

An error occurred.

No TurnSummary is attached because the error may have occurred before the turn produced any durable LLM provenance.

PendingToolCalls

Tool calls are ready for external execution.

Only returned when ToolRuntime::External is set in TurnOptions. The caller is responsible for executing the tool calls and resuming with AgentInput::SubmitToolResults, providing one ExternalToolResult for each pending tool call.

The continuation must be passed back unmodified — it carries the turn identity, token usage, and agent state needed to validate and apply the results.

Fields

turn: usize

The turn number that produced these tool calls

turn_usage: TokenUsage

Token usage for this turn’s LLM call

total_usage: TokenUsage

Cumulative token usage so far

tool_calls: Vec<PendingToolCallInfo>

Tool calls to execute externally

continuation: Box<ContinuationEnvelope>

Versioned continuation envelope for resuming after external tool execution.

summary: TurnSummary

Structured server-facing outcome metadata.

Implementations

impl TurnOutcome

pub const fn summary(&self) -> Option<&TurnSummary>

Returns the attached TurnSummary, if the variant carries one.

Present on every variant except TurnOutcome::Error.

Trait Implementations

impl Debug for TurnOutcome

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

Formats the value using the given formatter.