Struct TurnResult 

pub struct TurnResult {
    pub messages: Vec<Message>,
    pub usage: Usage,
    pub stop: Option<StopReason>,
    pub pending_approvals: Vec<PendingApproval>,
    pub handoff: Option<HandoffRequest>,
}

Output of one run_turn call.

Carries the wire messages produced (assistant text and tool results), the aggregated usage across every provider call in the loop, and the stop reason from the final step.

When Self::pending_approvals is non-empty the turn is paused: the model asked for one or more sensitive tools, run_turn short- circuited before executing them, and the caller must capture a human-in-the-loop decision (idiomatic Temporal “signal” pattern) before re-driving. The choice to surface this as a result field rather than an out-of-band callback keeps run_turn pure (no side-effect handle), keeps the durability boundary at the caller (the event log already gives us replay), and lets the per-conversation Mutex / Lease release while we wait — matching the durable-workflow pattern.

Fields

messages: Vec<Message>

Wire messages — assistant text + tool result messages, in order.

usage: Usage

Sum of input_tokens / output_tokens across every provider call this turn made (the function-calling loop may iterate multiple times).

stop: Option<StopReason>

Stop reason of the final provider step.

pending_approvals: Vec<PendingApproval>

Tool calls awaiting human approval. Empty in the common case; when non-empty, the turn paused before executing any tool in this batch.

handoff: Option<HandoffRequest>

Populated when the model emitted the reserved __handoff_to tool call. The loop suspends without executing any further tools and the caller (control plane) is expected to create a child conversation, emit a signed polyc_proto::proto::polychrome::handoff::v1::Handoff event into the parent’s eventlog, and resume the parent’s turn once a HandoffReturn lands.

If multiple __handoff_to calls appear in the same tool batch (the model emitted two at once), only the first is honored — fan-out is a V2 concern and the wire shape doesn’t model parallel children today.

Trait Implementations

impl Clone for TurnResult

fn clone(&self) -> TurnResult

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TurnResult

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

Formats the value using the given formatter.

impl Default for TurnResult

fn default() -> TurnResult

Returns the “default value” for a type.