Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    Start {
        thread_id: ThreadId,
        turn: usize,
    },
    UserInput {
        thread_id: ThreadId,
        content: Vec<ContentBlock>,
    },
    Thinking {
        message_id: String,
        text: String,
    },
    ThinkingDelta {
        message_id: String,
        delta: String,
    },
    TextDelta {
        message_id: String,
        delta: String,
    },
    Text {
        message_id: String,
        text: String,
    },
    ToolCallStart {
        id: String,
        name: String,
        display_name: String,
        input: Value,
        tier: ToolTier,
    },
    ToolCallEnd {
        id: String,
        name: String,
        display_name: String,
        result: ToolResult,
    },
    ToolProgress {
        id: String,
        name: String,
        display_name: String,
        stage: String,
        message: String,
        data: Option<Value>,
    },
    ToolRequiresConfirmation {
        id: String,
        name: String,
        display_name: String,
        input: Value,
        description: String,
    },
    TurnComplete {
        turn: usize,
        usage: TokenUsage,
    },
    Done {
        thread_id: ThreadId,
        total_turns: usize,
        total_usage: TokenUsage,
        duration: Duration,
    },
    Error {
        message: String,
        recoverable: bool,
    },
    AutoRetryStart {
        attempt: u32,
        max_attempts: u32,
        delay_ms: u64,
        error_message: String,
    },
    AutoRetryEnd {
        attempt: u32,
        success: bool,
        final_error: Option<String>,
    },
    Refusal {
        message_id: String,
        text: Option<String>,
    },
    Cancelled {
        turn: usize,
        usage: TokenUsage,
    },
    ContextCompacted {
        original_count: usize,
        new_count: usize,
        original_tokens: usize,
        new_tokens: usize,
    },
    SubagentProgress {

        subagent_id: String,
        subagent_name: String,
        nickname: Option<String>,
        child_thread_id: Option<ThreadId>,
        child_root_task_id: Option<String>,
        subagent_task_id: Option<String>,
        max_turns: Option<u32>,
        current_turn: Option<u32>,
        model: Option<String>,
        tool_name: String,
        tool_context: String,
        completed: bool,
        success: bool,
        tool_count: u32,
        total_tokens: u64,
    
},
}

Events emitted by the agent loop during execution. These are streamed to the client for real-time UI updates.

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.

Start

Agent loop has started

Fields

thread_id: ThreadId

turn: usize

UserInput

The user prompt that opens a turn.

Committed by the worker on the first attempt of each root-turn task, immediately before the matching AgentEvent::Start. Carries the task’s admitted submitted_input lifted into the LLM-content shape (Vec<ContentBlock> — text, image, document) so consumers can render the prompt without reaching into the projection or the task store. Retries of the same turn do not re-emit the event; downstream readers can pair UserInput 1:1 with the first Start { turn: N } per turn.

This is the durable, sequence-numbered admission event the projection never carried — MessageProjection::messages still holds the same prompt as an llm::Message, but it has no sequence and commingles with tool-result and compaction-summary user-role rows. Replay clients that need a clean, chronological “this is what the user typed” signal read this event instead.

Fields

thread_id: ThreadId

content: Vec<ContentBlock>

Lifted from the admitted task’s submitted_input. Only Text, Image, and Document blocks appear — the runtime never admits user prompts containing tool blocks, but the broader ContentBlock type lets the field round-trip through the same wire shapes the projection uses.

Thinking

Agent is “thinking” - complete thinking text after stream ends

Fields

message_id: String

text: String

ThinkingDelta

A thinking delta for streaming thinking content

Fields

message_id: String

delta: String

TextDelta

A text delta for streaming responses

Fields

message_id: String

delta: String

Text

Complete text block from the agent

Fields

message_id: String

text: String

ToolCallStart

Agent is about to call a tool

Fields

id: String

name: String

display_name: String

input: Value

tier: ToolTier

ToolCallEnd

Tool execution completed

Fields

id: String

name: String

display_name: String

result: ToolResult

ToolProgress

Progress update from an async tool operation

Fields

id: String

Tool call ID

name: String

Tool name

display_name: String

Human-readable display name

stage: String

Progress stage

message: String

Human-readable progress message

data: Option<Value>

Optional tool-specific data

ToolRequiresConfirmation

Tool requires confirmation before execution. The application determines the confirmation type (normal, PIN, biometric).

Fields

id: String

name: String

display_name: String

input: Value

description: String

TurnComplete

Agent turn completed (one LLM round-trip)

Fields

turn: usize

usage: TokenUsage

Done

Agent loop completed successfully

Fields

thread_id: ThreadId

total_turns: usize

total_usage: TokenUsage

duration: Duration

Error

An error occurred during execution

Fields

message: String

recoverable: bool

AutoRetryStart

Auto-retry was initiated for a transient LLM error (rate limit, server error, etc.). The delay_ms field gives the runtime’s chosen backoff before re-attempting; consumers can render a “Retrying X/N in Ys…” indicator and clear it on the matching AutoRetryEnd.

Fields

attempt: u32

1-based retry attempt number (first retry = 1).

max_attempts: u32

Maximum retry attempts configured for this run.

delay_ms: u64

Backoff before the next attempt in milliseconds.

error_message: String

Human-readable reason the retry was triggered.

AutoRetryEnd

Auto-retry settled. success = true means a subsequent attempt succeeded; success = false means the retry budget was exhausted and final_error carries the last error.

Fields

attempt: u32

Total attempts performed (matches the last AutoRetryStart’s attempt).

success: bool

Whether a follow-up attempt eventually succeeded.

final_error: Option<String>

Last error when the retry budget ran out.

Refusal

The model refused the request (safety/policy).

Fields

message_id: String

text: Option<String>

Cancelled

The run was cancelled via its CancellationToken.

This is a terminal event, emitted exactly once on every cancellation return site (mirroring AgentEvent::Done and AgentEvent::Refusal). Cancellation can land at the top of a turn, mid-stream while the model is still producing tokens, while a tool is in flight, or during context compaction — in every case the run closes with this event so a streaming consumer receives a closing marker and never hangs waiting for Done.

turn is the turn number reached when the cancel was honored and usage is the partial token usage accumulated so far.

Fields

turn: usize

usage: TokenUsage

ContextCompacted

Context was compacted to reduce size

Fields

original_count: usize

Number of messages before compaction

new_count: usize

Number of messages after compaction

original_tokens: usize

Estimated tokens before compaction

new_tokens: usize

Estimated tokens after compaction

SubagentProgress

Progress update from a running subagent

Fields

subagent_id: String

ID of the parent tool call that spawned this subagent

subagent_name: String

Name of the subagent (e.g., “explore”, “plan”)

nickname: Option<String>

Human-friendly nickname assigned by the parent (e.g., “Zara”)

child_thread_id: Option<ThreadId>

Durable child thread reference, when available.

child_root_task_id: Option<String>

Durable child root task reference, when available.

subagent_task_id: Option<String>

Durable parent-visible invocation task reference, when available.

max_turns: Option<u32>

Maximum turns configured for this subagent

current_turn: Option<u32>

Current turn number of the subagent

model: Option<String>

Model being used by the subagent

tool_name: String

Summary label associated with the latest subagent update.

tool_context: String

Brief context associated with the latest subagent update.

completed: bool

Whether the summarized update represents terminal completion.

success: bool

Whether the subagent succeeded (only meaningful if completed)

tool_count: u32

Current total tool count for this subagent

total_tokens: u64

Current total tokens used by this subagent

Implementations

impl AgentEvent

pub const fn start(thread_id: ThreadId, turn: usize) -> AgentEvent

pub const fn user_input( thread_id: ThreadId, content: Vec<ContentBlock>, ) -> AgentEvent

pub fn thinking( message_id: impl Into<String>, text: impl Into<String>, ) -> AgentEvent

pub fn thinking_delta( message_id: impl Into<String>, delta: impl Into<String>, ) -> AgentEvent

pub fn text_delta( message_id: impl Into<String>, delta: impl Into<String>, ) -> AgentEvent

pub fn text( message_id: impl Into<String>, text: impl Into<String>, ) -> AgentEvent

pub fn tool_call_start( id: impl Into<String>, name: impl Into<String>, display_name: impl Into<String>, input: Value, tier: ToolTier, ) -> AgentEvent

pub fn tool_call_end( id: impl Into<String>, name: impl Into<String>, display_name: impl Into<String>, result: ToolResult, ) -> AgentEvent

pub fn tool_progress( id: impl Into<String>, name: impl Into<String>, display_name: impl Into<String>, stage: impl Into<String>, message: impl Into<String>, data: Option<Value>, ) -> AgentEvent

pub fn tool_requires_confirmation( id: impl Into<String>, name: impl Into<String>, display_name: impl Into<String>, input: Value, description: impl Into<String>, ) -> AgentEvent

pub const fn done( thread_id: ThreadId, total_turns: usize, total_usage: TokenUsage, duration: Duration, ) -> AgentEvent

pub fn error(message: impl Into<String>, recoverable: bool) -> AgentEvent

pub fn refusal( message_id: impl Into<String>, text: Option<String>, ) -> AgentEvent

pub const fn cancelled(turn: usize, usage: TokenUsage) -> AgentEvent

pub const fn context_compacted( original_count: usize, new_count: usize, original_tokens: usize, new_tokens: usize, ) -> AgentEvent

Trait Implementations

impl Clone for AgentEvent

fn clone(&self) -> AgentEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentEvent

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentEvent

fn deserialize<__D>( __deserializer: __D, ) -> Result<AgentEvent, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentEvent

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

where __S: Serializer,

Serialize this value into the given Serde serializer.