Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    AssistantText {
        text: String,
        step: usize,
    },
    ToolCall {
        name: String,
        id: String,
        arguments: String,
        step: usize,
    },
    Latency {
        step: usize,
        llm_ms: u64,
    },
    ToolResult {
        id: String,
        name: String,
        output: String,
        step: usize,
        is_error: bool,
    },
    Usage {
        input_tokens: u32,
        output_tokens: u32,
        cache_hit_tokens: u32,
        cache_miss_tokens: u32,
        step: usize,
    },
    ContextBreakdown {
        breakdown: ContextBreakdown,
        step: usize,
    },
    PartialToken {
        text: String,
        step: usize,
    },
    PartialReasoning {
        text: String,
        step: usize,
    },
    Reasoning {
        text: String,
        step: usize,
    },
    Microcompact {
        step: usize,
        pruned: usize,
    },
    Compacted {
        removed: usize,
        kept: usize,
        summary_chars: usize,
        step: usize,
    },
    CompactionSkipped {
        step: usize,
        reason: CompactionSkipReason,
    },
    TurnFinished {
        reason: String,
        steps: usize,
    },
    PlanModeRequested {
        reason: String,
    },
    PlanModeApproved,
    PlanModeRejected {
        reason: String,
    },
    PlanProposed {
        plan_text: String,
        tool_calls: Vec<Value>,
    },
    PlanConfirmed,
    PlanRejected {
        reason: String,
    },
    MessageAppended {
        message: Message,
        usage: Option<UsageMeta>,
    },
    MessageAppendedWithAudit {
        message: Message,
        audit: AuditMeta,
    },
    CompactionBoundary {
        turn: u32,
        compacted_count: usize,
        summary_uuid: Option<String>,
        cache_hit_tokens: u32,
        cache_miss_tokens: u32,
        is_recompaction_in_chain: bool,
        turns_since_previous_compact: u32,
        previous_compact_turn: Option<u32>,
    },
    TodoUpdated {
        todos: Vec<TodoItem>,
    },
    GoalSet {
        condition: String,
        max_turns: u32,
    },
    GoalContinuing {
        reason: String,
        turns: u32,
    },
    GoalAchieved {
        condition: String,
        turns: u32,
    },
    GoalCleared,
    HookStarted {
        hook_event: String,
        hook_name: String,
        status_message: Option<String>,
    },
    HookProgress {
        hook_event: String,
        hook_name: String,
        last_line: String,
    },
    HookFinished {
        hook_event: String,
        hook_name: String,
        outcome: String,
        duration_ms: u64,
    },
    HookSystemMessage {
        text: String,
    },
    LlmRetry {
        step: usize,
        attempt: u32,
        wait_ms: u64,
        reason: String,
    },
}

A serialisable, non-exhaustive agent lifecycle event.

Uses String for the finish reason to avoid coupling to the FinishReason type. New variants can be added without a breaking change (see #[non_exhaustive]).

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.

AssistantText

Model generated text without tool calls.

Fields

text: String

step: usize

ToolCall

Model requested to execute a tool.

Fields

name: String

id: String

arguments: String

step: usize

Latency

Time taken for the LLM request (excluding tool execution), in ms.

Fields

step: usize

llm_ms: u64

ToolResult

Result of executing a tool call.

Fields

id: String

name: String

output: String

step: usize

is_error: bool

true if the tool execution produced an error (output begins with "ERROR: " or was a permission denial). UI consumers should use this field instead of inspecting the output string prefix.

Usage

Token usage statistics from the LLM provider.

Fields

input_tokens: u32

output_tokens: u32

cache_hit_tokens: u32

Tokens served from the provider’s prompt cache (cache-hit pricing applies).

cache_miss_tokens: u32

Tokens written to the provider’s prompt cache (full input pricing applies).

step: usize

ContextBreakdown

Goal-328: locally-estimated per-component token breakdown of the prompt sent to the provider for step. Distinct from Self::Usage (the provider’s reported truth) — see crate::llm::ContextBreakdown for the bucket definitions.

Emitted once per step right after Self::Usage so consumers see the provider truth first, then the local estimate. Steps without an LLM call (denial-limit finishes, stuck-detection short-circuits) skip the event entirely.

Fields

breakdown: ContextBreakdown

step: usize

PartialToken

Partial token from streaming response (if streaming enabled).

Fields

text: String

step: usize

PartialReasoning

Partial reasoning / thinking delta from a streaming response. Emitted live (before the answer’s PartialToken deltas) for providers that stream an explicit reasoning channel, so UI layers can render the chain-of-thought as it is produced. The authoritative, fully-joined reasoning string still arrives once per step via AgentEvent::Reasoning, which finalises the streamed block.

Fields

text: String

step: usize

Reasoning

Reasoning / thinking content from a model that exposes an explicit reasoning channel (DeepSeek R1, OpenAI o1, etc.). Carries the full reasoning text for the current step; providers that stream reasoning tokens (DeepSeek’s reasoning_content SSE deltas) accumulate them and emit the final, fully-joined string in this event. UI layers render it as a thinking… block separate from the assistant message body. Emitted exactly once per step that produced reasoning content; steps without reasoning skip the event.

Fields

text: String

step: usize

Microcompact

No-LLM proactive pruning of old tool results by count. Emitted with pruned > 0 when the Microcompactor replaced the content of old tool-result messages with a placeholder.

Fields

step: usize

pruned: usize

Compacted

Transcript was compacted to fit size constraints.

Fields

removed: usize

kept: usize

summary_chars: usize

step: usize

CompactionSkipped

Proactive compaction was skipped — either the circuit breaker tripped (CompactionSkipReason::CircuitBreaker) or the compaction call itself failed (CompactionSkipReason::Error). Compaction is best-effort; a skipped compaction is never fatal to the turn.

Fields

step: usize

reason: CompactionSkipReason

TurnFinished

Agent run completed.

Fields

reason: String

Human-readable reason for termination (e.g. “no_more_tool_calls”).

steps: usize

Number of iterations executed.

PlanModeRequested

Goal-202: Agent is requesting permission to enter plan mode. Emitted by RequestPlanModeTool before any exploration begins. The TUI / HTTP surface should prompt the user and call AgentRuntime::approve_plan_mode_request or reject_plan_mode_request.

Fields

reason: String

PlanModeApproved

Goal-202: The user approved the plan-mode entry request.

PlanModeRejected

Goal-202: The user rejected the plan-mode entry request.

Fields

reason: String

PlanProposed

Agent has produced a plan and is waiting for confirmation.

Fields

plan_text: String

tool_calls: Vec<Value>

PlanConfirmed

Plan was confirmed, execution will proceed.

PlanRejected

Plan was rejected with a reason.

Fields

reason: String

MessageAppended

A complete message was just appended to the agent transcript.

Fired exactly once per committed message inside the agent runtime: once for the user message that starts a turn, once for the compaction summary if cross-turn compaction fires, and once per message in the kernel’s output batch. Carries the full Message (role, content, tool_calls, tool_call_id, reasoning_content) so persistence consumers can write the canonical record without reassembling it from the finer AssistantText / ToolCall / ToolResult streaming events.

usage — token usage for this message (non-None for assistant messages produced by an LLM call, g156).

Not emitted for seeded transcript messages loaded from an existing session on resume (those are already on disk).

Fields

message: Message

usage: Option<UsageMeta>

Token usage for this message (g156).

MessageAppendedWithAudit

Variant of [MessageAppended] specifically for Role::Tool messages that have an associated [AuditMeta] (Goal 153). The persistence sink handles this identically to MessageAppended but populates the audit field of crate::session::TranscriptEntry.

Emitting a separate variant (rather than Option<AuditMeta> on MessageAppended) keeps the common path zero-cost and avoids making audit an optional field on every event.

Fields

message: Message

audit: AuditMeta

CompactionBoundary

Cross-turn compaction just fired; a compact_boundary marker should be written to the session JSONL (g157).

turn — the turn index when compaction occurred. compacted_count — how many messages were removed. summary_uuid — UUID of the compaction summary message that replaced them. cache_hit_tokens — tokens served from the provider’s prompt cache on the just-completed turn (g336). Zero when no usage was reported. cache_miss_tokens — tokens that missed the prompt cache on the just-completed turn (g336). Zero when no usage was reported. is_recompaction_in_chain — true when this is not the first compaction in the session (g338). Signals a recompaction chain — the compaction strategy may be failing for this session. turns_since_previous_compact — how many turns elapsed since the previous compaction (g338). 0 when no previous compaction. previous_compact_turn — the turn index of the previous compaction, or None on the first compaction (g338).

Fields

turn: u32

compacted_count: usize

summary_uuid: Option<String>

cache_hit_tokens: u32

cache_miss_tokens: u32

is_recompaction_in_chain: bool

turns_since_previous_compact: u32

previous_compact_turn: Option<u32>

TodoUpdated

Goal-167: emitted when the agent updates its task checklist via todo_write. Carries the complete replacement list so consumers can render the current state without storing diffs.

Fields

todos: Vec<TodoItem>

GoalSet

A /goal was set for this session.

Fields

condition: String

The completion condition as written by the user.

max_turns: u32

Hard cap on autonomous turns.

GoalContinuing

The judge evaluated the condition and found it not yet met. The loop will continue with another turn.

Fields

reason: String

The judge’s explanation for why the condition is not yet met.

turns: u32

Number of turns elapsed so far.

GoalAchieved

The judge evaluated the condition and confirmed it is met.

Fields

condition: String

The original condition string.

turns: u32

Total turns taken to reach the goal.

GoalCleared

The active goal was cleared — either by /goal clear, turn-budget exhaustion, or an explicit DELETE /sessions/:id/goal call.

HookStarted

A hook started executing.

Fields

hook_event: String

hook_name: String

status_message: Option<String>

HookProgress

A hook produced incremental stdout output.

Fields

hook_event: String

hook_name: String

last_line: String

HookFinished

A hook finished executing.

Fields

hook_event: String

hook_name: String

outcome: String

duration_ms: u64

HookSystemMessage

A hook produced a system message to show to the user.

Fields

text: String

LlmRetry

Emitted when the LLM call fails with a retryable error (rate limit or timeout) and the agent will back off before retrying.

Fields

step: usize

Which step (ReAct iteration) triggered the retry.

attempt: u32

Which retry attempt this is (1 = first retry after initial failure).

wait_ms: u64

How many milliseconds the agent will sleep before the next attempt.

reason: String

Short human-readable description of the error (“rate_limited” or “timeout”).

Trait Implementations

impl Clone for AgentEvent

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 AgentEvent

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

Formats the value using the given formatter.

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

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for AgentEvent

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for AgentEvent

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for AgentEvent