Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    AgentStart {
        prompts: Vec<Message>,
        session_id: Option<String>,
    },
    AgentEnd {
        messages: Vec<Message>,
        stop_reason: Option<String>,
        session_id: Option<String>,
    },
    TurnStart {
        turn_number: u32,
    },
    TurnEnd {
        turn_number: u32,
        assistant_message: Message,
        tool_results: Vec<ToolResultMessage>,
    },
    MessageStart {
        message: Message,
    },
    MessageUpdate {
        message: Message,
        delta: StreamDelta,
    },
    MessageEnd {
        message: Message,
    },
    TodoReminder {
        open: Vec<TodoItem>,
        attempt: u32,
        max: u32,
    },
    ToolExecutionStart {
        tool_call_id: String,
        tool_name: String,
        args: Value,
        intent: Option<String>,
        context: Option<ToolCallContext>,
    },
    ToolExecutionUpdate {
        tool_call_id: String,
        tool_name: String,
        partial_result: String,
        tab_id: Option<Uuid>,
        context: Option<ToolCallContext>,
    },
    ToolExecutionEnd {
        tool_call_id: String,
        tool_name: String,
        intent: Option<String>,
        result: ToolResult,
        is_error: bool,
    },
    ToolCallDelta {
        tool_call_id: String,
        args_delta: String,
    },
    Start {
        prompt: String,
    },
    Thinking,
    ThinkingDelta {
        text: String,
    },
    ThinkingEnd,
    TextChunk {
        text: String,
    },
    ToolCall {
        tool_call: ToolCall,
    },
    ToolStart {
        tool_call_id: String,
        tool_name: String,
        arguments: Value,
    },
    ToolProgress {
        tool_call_id: String,
        message: String,
    },
    ToolComplete {
        result: ToolResult,
    },
    ToolError {
        tool_call_id: String,
        error: String,
    },
    Complete {
        content: String,
        stop_reason: String,
    },
    Error {
        message: String,
        session_id: Option<String>,
    },
    Iteration {
        number: usize,
    },
    Usage {
        input_tokens: usize,
        output_tokens: usize,
    },
    Compaction {
        event: CompactionEvent,
    },
    Retry {
        attempt: usize,
        max_retries: usize,
        retry_after_secs: u64,
        reason: String,
        session_id: Option<String>,
    },
    TtsrInterrupt {
        rule_name: String,
        session_id: Option<String>,
    },
    Cancelled,
    PartialResponse {
        content: String,
    },
    AutoRetryStart {
        attempt: usize,
        max_attempts: usize,
        delay_ms: u64,
        error_message: String,
    },
    AutoRetryEnd {
        success: bool,
        attempt: usize,
        final_error: Option<String>,
    },
    SteeringMessage {
        message: Message,
    },
    FollowUpMessage {
        message: Message,
    },
    ApprovalRequired {
        tool_call_id: String,
        tool_name: String,
        args: Value,
        reason: String,
        session_id: Option<String>,
    },
    ApprovalResult {
        tool_call_id: String,
        approved: bool,
        reason: Option<String>,
    },
    SoftRequirementReminder {
        tool_name: String,
        reason: String,
        session_id: Option<String>,
    },
    SoftRequirementEscalation {
        tool_name: String,
        reason: String,
        session_id: Option<String>,
    },
    HarmonyLeakDetected {
        preview: String,
        session_id: Option<String>,
    },
}

Events emitted during agent execution.

Events are tagged with type and serialized as camelCase for JSON consumers. This enum is #[non_exhaustive] — new variants may be added in future releases.

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.

AgentStart

Emitted when the agent begins processing a batch of prompts.

Fields

prompts: Vec<Message>

The initial prompt messages sent to the agent.

session_id: Option<String>

Optional session identifier for correlation.

AgentEnd

Emitted when the agent finishes all processing.

Fields

messages: Vec<Message>

Final conversation messages.

stop_reason: Option<String>

Why the agent stopped (e.g. "end_turn", "tool_use").

session_id: Option<String>

Optional session identifier for correlation.

TurnStart

Emitted at the start of each agent loop turn.

Fields

turn_number: u32

Zero-based turn index.

TurnEnd

Emitted when a turn completes, including the assistant reply and tool results.

Fields

turn_number: u32

Turn index that just completed.

assistant_message: Message

The assistant message produced this turn.

tool_results: Vec<ToolResultMessage>

Tool results collected during this turn.

MessageStart

A new message has been created in the conversation.

Fields

message: Message

The message that started.

MessageUpdate

A message has been updated with new content.

Fields

message: Message

The message in its current state.

delta: StreamDelta

Incremental delta describing what changed.

MessageEnd

A message has been finalized.

Fields

message: Message

The completed message.

TodoReminder

Emitted when the loop injects a stop-time incomplete-todo reminder (the hidden user turn) so the TUI can commit a visible banner of why the agent kept going.

Fields

open: Vec<TodoItem>

The open (pending/in_progress) todo items being nudged.

attempt: u32

Which reminder attempt this is (1-based).

max: u32

The configured max reminder count.

ToolExecutionStart

A tool is about to be executed.

Fields

tool_call_id: String

Unique identifier for this tool call.

tool_name: String

Name of the tool being invoked.

args: Value

JSON arguments passed to the tool.

intent: Option<String>

Intent trace — a concise description of what this tool call does. None for tools without intent tracing.

context: Option<ToolCallContext>

Semantic context inferred from tool name and arguments. None for tools without a known context mapping.

ToolExecutionUpdate

Partial progress from a running tool execution.

Fields

tool_call_id: String

Identifier of the tool call producing the update.

tool_name: String

Name of the tool.

partial_result: String

Partial result text so far.

tab_id: Option<Uuid>

Browser tab id that produced this progress (if the tool is tab-aware). None for tools that don’t have a tab concept, or for older tool implementations that don’t propagate tab ids.

context: Option<ToolCallContext>

Semantic context inferred from tool name and arguments. Carries structured information about what this update means.

ToolExecutionEnd

A tool execution has finished.

Fields

tool_call_id: String

Identifier of the completed tool call.

tool_name: String

Name of the tool.

intent: Option<String>

Intent trace — a concise description of what this tool call did. None for tools without intent tracing.

result: ToolResult

The tool result payload.

is_error: bool

Whether the tool execution resulted in an error.

ToolCallDelta

Partial tool-call arguments streamed by the LLM while it is still constructing a tool call. Emitted between the provider’s ToolCallStart and ToolCallEnd, before AgentEvent::ToolExecutionStart.

Each args_delta is a raw JSON fragment (not valid JSON on its own) — downstream consumers accumulate per tool_call_id.

Fields

tool_call_id: String

Tool call identifier (matches the id later carried by ToolExecutionStart).

args_delta: String

Raw JSON argument fragment from the LLM stream.

Start

Legacy: agent started processing a prompt.

Fields

prompt: String

The user prompt that triggered the run.

Thinking

Agent is waiting for the first response token.

ThinkingDelta

Incremental thinking / reasoning text from the model.

Fields

text: String

The reasoning text delta.

ThinkingEnd

The model finished a reasoning/thinking span and is about to produce the answer (or begin another content block). Signal-only (no payload).

Emitted when the provider reports ThinkingEnd. For models that interleave reasoning and text (Claude 4, o-series) this may fire more than once per turn — once per thinking span.

TextChunk

A chunk of generated text from the model.

Fields

text: String

The text delta to append.

ToolCall

The model requested a tool call.

Fields

tool_call: ToolCall

The tool call descriptor from the provider.

ToolStart

A tool execution has started.

Fields

tool_call_id: String

Identifier of the tool call.

tool_name: String

Name of the tool being invoked.

arguments: Value

JSON arguments for the tool call.

ToolProgress

Progress update from a running tool.

Fields

tool_call_id: String

Identifier of the tool call.

message: String

Human-readable progress message.

ToolComplete

A tool execution has completed.

Fields

result: ToolResult

The tool result payload.

ToolError

A tool execution failed.

Fields

tool_call_id: String

Identifier of the failed tool call.

error: String

Error description.

Complete

The agent produced a final response.

Fields

content: String

Full response text.

stop_reason: String

Stop reason string (e.g. "EndTurn").

Error

An error occurred during agent execution.

Fields

message: String

Human-readable error message.

session_id: Option<String>

Optional session identifier.

Iteration

Agent loop iteration counter update.

Fields

number: usize

Current iteration number.

Usage

Token usage report for a completed turn.

Fields

input_tokens: usize

Number of prompt / input tokens consumed.

output_tokens: usize

Number of completion / output tokens produced.

Compaction

Context compaction lifecycle event.

Fields

event: CompactionEvent

The underlying compaction event detail.

Retry

The agent is retrying after a transient error.

Fields

attempt: usize

Current retry attempt (1-based).

max_retries: usize

Maximum number of retries allowed.

retry_after_secs: u64

Seconds until the next attempt.

reason: String

Why the previous attempt failed.

session_id: Option<String>

Optional session identifier.

TtsrInterrupt

A TTSR rule violation was detected during streaming. The stream was aborted and a system reminder will be injected.

Fields

rule_name: String

Name of the violated rule.

session_id: Option<String>

Session identifier for logging.

Cancelled

The agent run was cancelled by the caller.

PartialResponse

A partial response delivered mid-stream (useful for UI rendering).

Fields

content: String

Accumulated response content so far.

AutoRetryStart

An automatic retry attempt is starting.

Fields

attempt: usize

Current retry attempt (1-based).

max_attempts: usize

Total retry attempts that will be made.

delay_ms: u64

Milliseconds before this attempt is sent.

error_message: String

The error that triggered the retry.

AutoRetryEnd

An automatic retry attempt has concluded.

Fields

success: bool

Whether the retry succeeded.

attempt: usize

Which attempt this was (1-based).

final_error: Option<String>

Final error if the retry failed, None on success.

SteeringMessage

A system-level steering message injected into the conversation.

Fields

message: Message

The steering message to add to the context.

FollowUpMessage

A follow-up message appended to continue the conversation.

Fields

message: Message

The follow-up message.

ApprovalRequired

A tool call requires human approval.

Fields

tool_call_id: String

Tool call identifier.

tool_name: String

Name of the tool requiring approval.

args: Value

Arguments passed to the tool.

reason: String

Why approval is needed.

session_id: Option<String>

Session identifier for correlation.

ApprovalResult

Result of an approval request.

Fields

tool_call_id: String

Tool call identifier this result corresponds to.

approved: bool

Whether the tool call was approved.

reason: Option<String>

Optional reason from the approver.

SoftRequirementReminder

A soft-required tool was not called on the first turn. The loop injects a reminder steering message.

Fields

tool_name: String

Tool that should have been called.

reason: String

Reason why the tool is needed.

session_id: Option<String>

Session identifier for correlation.

SoftRequirementEscalation

A soft-required tool was not called after multiple turns. Escalation — stronger action may be needed.

Fields

tool_name: String

Tool that should have been called.

reason: String

Reason why the tool is needed.

session_id: Option<String>

Session identifier for correlation.

HarmonyLeakDetected

GPT-5 Harmony protocol leak detected in streaming output. The stream was aborted to prevent the leaked content from being persisted or acted upon.

Fields

preview: String

A preview of the leaked content (truncated, privacy-safe).

session_id: Option<String>

Session identifier for correlation.

Implementations

impl AgentEvent

pub fn is_terminal(&self) -> bool

Returns true if this event represents the end of the agent lifecycle.

pub fn type_name(&self) -> &'static str

Returns the snake_case variant name of this event (useful for logging / serialization).

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.