Enum StreamChunk 

#[non_exhaustive]
pub enum StreamChunk {
    TextDelta {
        delta: String,
    },
    ToolCallStarted {
        id: String,
        name: String,
    },
    ToolCallArgsDelta {
        id: String,
        delta: String,
    },
    ToolCallFinished {
        id: String,
        name: String,
        args: Value,
    },
    ReasoningDelta {
        delta: String,
    },
    ReasoningFinished {
        signature: Option<String>,
    },
    RedactedReasoningBlock {
        data: String,
    },
    TurnFinished {
        reason: FinishReason,
        usage: Usage,
        service_tier: Option<String>,
    },
    RunStarted {
        run_id: RunId,
    },
    StepStarted {
        run_id: RunId,
        step_id: StepId,
        iteration: usize,
    },
    StepFinished {
        run_id: RunId,
        step_id: StepId,
        iteration: usize,
        new_messages_so_far: Arc<Vec<Message>>,
    },
    ToolResult {
        run_id: RunId,
        step_id: StepId,
        call_id: String,
        content: ToolResultContent,
    },
    RunFinished {
        run_id: RunId,
        reason: FinishReason,
        usage: Usage,
        new_messages: Vec<Message>,
    },
    HistoryCompacted {
        run_id: RunId,
        before_count: usize,
        after_count: usize,
        strategy: &'static str,
    },
}

Event the engine emits as a run progresses.

Variants split into two families:

1. Provider stream events, surfaced once per turn — TextDelta, ToolCall*, Reasoning*, RedactedReasoningBlock, TurnFinished. Adapters lower wire deltas into these. Started/ Finished pairs always nest cleanly: a ToolCallFinished arrives before any other tool call’s Started.
2. Engine lifecycle events, synthesized by the engine itself around the provider stream — RunStarted, StepStarted, StepFinished, ToolResult, RunFinished, HistoryCompacted.

Every chunk reaches every crate::ChatMiddleware::on_chunk; the engine also drives its own assistant-history reconstruction off these events, so middlewares that override crate::ChatMiddleware::on_chunk_mut can rewrite them in flight to influence what gets persisted.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

TextDelta

Incremental visible text from the model. Concatenate deltas in arrival order to reconstruct the assistant text block.

Fields

delta: String

New text appended this delta. Empty deltas are legal.

ToolCallStarted

A new tool call has begun. The model has emitted the tool name but no arguments yet. Pair with the matching Self::ToolCallFinished (same id) once the call is fully assembled.

Fields

id: String

Provider-assigned id; mirrors back as call_id on the Self::ToolResult the engine emits after execution.

name: String

Tool name as registered in the request’s tools list.

ToolCallArgsDelta

Incremental tool-call argument JSON. Concatenate deltas in arrival order to rebuild the args JSON for live UIs; engines that only need the final structure can ignore these and read Self::ToolCallFinished::args instead.

Fields

id: String

Tool call id; matches the originating Self::ToolCallStarted::id.

delta: String

JSON fragment appended this delta.

ToolCallFinished

A tool call is fully assembled and ready to execute. The engine invokes the tool after this chunk and emits a Self::ToolResult when execution completes.

Fields

id: String

Tool call id; matches the originating Self::ToolCallStarted::id.

name: String

Tool name, repeated for convenience so consumers do not have to track the originating Started chunk.

args: Value

Final, parsed JSON arguments.

ReasoningDelta

Incremental reasoning text. Same accumulation contract as Self::TextDelta, but feeds an crate::AssistantBlock::Reasoning block instead of crate::AssistantBlock::Text. Some providers (Anthropic extended thinking) require the assembled reasoning to be replayed verbatim on subsequent turns when tools are involved.

Fields

delta: String

New reasoning text appended this delta.

ReasoningFinished

End of a visible reasoning block. Carries the provider signature when applicable (Anthropic extended thinking); other providers may emit None. Engines should pair this with the accumulated reasoning text to materialize an AssistantBlock::Reasoning.

Fields

signature: Option<String>

Provider signature for the reasoning block (Anthropic extended thinking). Persist alongside the reasoning text in crate::AssistantBlock::Reasoning; replay verbatim on subsequent turns when tools are involved.

RedactedReasoningBlock

A complete redacted reasoning block delivered atomically. data is opaque provider material that must be replayed verbatim on the next request. Engines should materialize AssistantBlock::RedactedReasoning directly from this chunk; no deltas are emitted around it.

Fields

data: String

Verbatim provider payload; treat as opaque bytes.

TurnFinished

End of a single provider turn. Equivalent to a Chat Completions finish_reason plus the final usage. Multiple turns can fire per run when the model is in a tool-use loop.

Fields

reason: FinishReason

Why the model stopped this turn.

usage: Usage

Token counters reported by the provider for this turn.

service_tier: Option<String>

Provider-reported service tier for the turn (Anthropic: "standard" / "priority" / "batch"). None when the provider does not surface one. Per-turn rather than aggregated because it is a categorical label, not a counter.

RunStarted

Engine has accepted the run; emitted exactly once per run before the first provider call.

Fields

run_id: RunId

Identifier shared by every chunk this run produces.

StepStarted

Engine is starting a step (one provider turn plus the tool calls it triggers).

Fields

run_id: RunId

Run this step belongs to.

step_id: StepId

Identifier shared by every chunk this step produces.

iteration: usize

0-based iteration number; bounded by crate::RunConfig::max_iterations.

StepFinished

Engine has finished a step. Includes the cumulative messages added to history so far, so observers can snapshot mid-conversation without waiting for Self::RunFinished.

Fields

run_id: RunId

Run this step belongs to.

step_id: StepId

Step that just finished.

iteration: usize

0-based iteration number, matching Self::StepStarted::iteration.

new_messages_so_far: Arc<Vec<Message>>

All messages this run has appended to history so far, shared so observers can read without cloning the vector.

ToolResult

A tool finished executing and produced a reply. Emitted after Self::ToolCallFinished and before the next provider turn picks up the result.

Fields

run_id: RunId

Run that owns the tool call.

step_id: StepId

Step that owns the tool call.

call_id: String

Matches Self::ToolCallFinished::id.

content: ToolResultContent

Tool reply, with is_error preserved for the next provider turn.

RunFinished

Engine has finished the run. Emitted exactly once per run, even on aborts and middleware terminations.

Fields

run_id: RunId

Run that just finished.

reason: FinishReason

Why the run ended.

usage: Usage

Token totals across every turn in the run.

new_messages: Vec<Message>

All messages this run added to history. On abort, partial tool results are preserved so the next run sees a consistent shape.

HistoryCompacted

Emitted by Conversation::stream (not the engine) when history compaction ran before the request was sent. Carries message counts from before/after compaction and the strategy’s name so observability middlewares can report what was dropped.

Fields

run_id: RunId

Run for which compaction ran. Shared with the engine-emitted chunks of the same run.

before_count: usize

Number of messages in history before compaction.

after_count: usize

Number of messages in history after compaction.

strategy: &'static str

Name reported by the strategy (CompactionStrategy::name()), e.g. "truncate" or "summarize".

Trait Implementations

impl Debug for StreamChunk

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

Formats the value using the given formatter.