Struct TurnTrace 

pub struct TurnTrace {

    pub version: u32,
    pub turn_id: String,
    pub session_id: String,
    pub started_at: u64,
    pub ended_at: u64,
    pub model_provider: String,
    pub model_name: String,
    pub task: String,
    pub visible_tool_count: usize,
    pub visible_tools: Vec<String>,
    pub deferred_tools_discovered: Vec<String>,
    pub tool_calls: Vec<ToolCallTrace>,
    pub approvals: Vec<ApprovalTrace>,
    pub capabilities: Vec<CapabilityLedgerEntry>,
    pub verifier_results: Vec<VerifierTrace>,
    pub metrics: TurnMetrics,
    pub outcome: TurnOutcome,
    pub final_message: String,
}

Structured trace for a single turn of agent execution.

Separates trace data from session events. Traces are focused on harness metrics, tool calls, verifiers, and outcomes — not full conversation history.

Fields

version: u32

Schema version for forward compatibility.

turn_id: String

Unique turn identifier.

session_id: String

Session this turn belongs to.

started_at: u64

Unix timestamp (milliseconds) when the turn started.

ended_at: u64

Unix timestamp (milliseconds) when the turn ended.

model_provider: String

Model provider used.

model_name: String

Model name used.

task: String

The user task or prompt that started this turn.

visible_tool_count: usize

How many tool definitions were visible to the model.

visible_tools: Vec<String>

Names of visible tools.

deferred_tools_discovered: Vec<String>

Names of deferred tools discovered via tool.search.

tool_calls: Vec<ToolCallTrace>

All tool calls made during this turn, in order.

approvals: Vec<ApprovalTrace>

Approval decisions made during this turn.

capabilities: Vec<CapabilityLedgerEntry>

Capability lifecycle entries recorded during this turn.

verifier_results: Vec<VerifierTrace>

Verifier results from this turn.

metrics: TurnMetrics

Metrics summary.

outcome: TurnOutcome

Outcome classification.

final_message: String

Human-readable final message.

Implementations

impl TurnTrace

pub const CURRENT_VERSION: u32 = 1

Current trace schema version.

pub fn new( turn_id: impl Into<String>, session_id: impl Into<String>, model_provider: impl Into<String>, model_name: impl Into<String>, task: impl Into<String>, ) -> Self

Creates a new turn trace with the given basic fields.

pub fn finalize(&mut self)

Finalizes the trace by setting end time and wall time.

pub fn record_tool_call( &mut self, invocation: &ToolInvocation, result: &ToolResult, duration_ms: u64, )

Records a tool call in the trace.

pub fn record_approval( &mut self, tool_name: &str, risk: &str, approved: bool, duration_ms: u64, )

Records an approval decision.

pub fn record_capability(&mut self, entry: CapabilityLedgerEntry)

Records a capability lifecycle entry.

pub fn record_verifier( &mut self, verifier: &str, command: &str, passed: bool, duration_ms: u64, exit_code: Option<i32>, )

Records a verifier run.

pub fn redacted(&self) -> Self

Returns a copy of this trace with secret-like content redacted.

Trait Implementations

impl Clone for TurnTrace

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 TurnTrace

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for TurnTrace

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for TurnTrace

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

where __S: Serializer,

Serialize this value into the given Serde serializer.