Enum EngineEvent 

pub enum EngineEvent {
    TextDelta {
        text: String,
    },
    TextDone,
    ThinkingStart,
    ThinkingDelta {
        text: String,
    },
    ThinkingDone,
    ResponseStart,
    ToolCallStart {
        id: String,
        name: String,
        args: Value,
        is_sub_agent: bool,
    },
    ToolCallResult {
        id: String,
        name: String,
        output: String,
    },
    ToolOutputLine {
        id: String,
        line: String,
        is_stderr: bool,
    },
    SubAgentStart {
        agent_name: String,
    },
    TodoUpdate {
        items: Vec<TodoItem>,
        diff: TodoDiff,
    },
    BgTaskUpdate {
        task_id: u32,
        spawner: Option<u32>,
        status: AgentStatus,
    },
    ApprovalRequest {
        id: String,
        tool_name: String,
        detail: String,
        preview: Option<DiffPreview>,
        effect: ToolEffect,
    },
    AskUserRequest {
        id: String,
        question: String,
        options: Vec<String>,
    },
    ActionBlocked {
        tool_name: String,
        detail: String,
        preview: Option<DiffPreview>,
    },
    ContextUsage {
        used: usize,
        max: usize,
    },
    StatusUpdate {
        model: String,
        provider: String,
        context_pct: f64,
        approval_mode: String,
        active_tools: usize,
    },
    Footer {
        prompt_tokens: i64,
        completion_tokens: i64,
        cache_read_tokens: i64,
        thinking_tokens: i64,
        total_chars: usize,
        elapsed_ms: u64,
        rate: f64,
        context: String,
    },
    SpinnerStart {
        message: String,
    },
    SpinnerStop,
    TurnStart {
        turn_id: String,
    },
    TurnEnd {
        turn_id: String,
        reason: TurnEndReason,
    },
    LoopCapReached {
        cap: u32,
        recent_tools: Vec<String>,
    },
    Info {
        message: String,
    },
    Warn {
        message: String,
    },
    Error {
        message: String,
    },
}

Events emitted by the engine to the client.

The client is responsible for rendering these events appropriately for its medium (terminal, GUI, JSON stream, etc.).

Variants

TextDelta

A chunk of streaming text from the LLM response.

Fields

text: String

The text chunk.

TextDone

The LLM finished streaming text. Flush any buffered output.

ThinkingStart

The LLM started a thinking/reasoning block.

ThinkingDelta

A chunk of thinking/reasoning content.

Fields

text: String

The thinking text chunk.

ThinkingDone

The thinking/reasoning block finished.

ResponseStart

The LLM response section is starting (shown after thinking ends).

ToolCallStart

A tool call is about to be executed.

Fields

id: String

Unique ID for this tool call (from the LLM).

name: String

Tool name (e.g., “Bash”, “Read”, “Edit”).

args: Value

Tool arguments as JSON.

is_sub_agent: bool

Whether this is a sub-agent’s tool call.

ToolCallResult

A tool call completed with output.

Fields

id: String

Matches the id from ToolCallStart.

name: String

Tool name.

output: String

The tool’s output text.

ToolOutputLine

A line of streaming output from a tool (currently Bash only).

Emitted as each line arrives from stdout/stderr, before ToolCallResult. Clients can render these in real-time for a “live terminal” feel.

Fields

id: String

Matches the id from ToolCallStart.

line: String

The output line (no trailing newline).

is_stderr: bool

Whether this line came from stderr.

SubAgentStart

A sub-agent is being invoked.

Fields

agent_name: String

Name of the sub-agent being invoked.

TodoUpdate

A sub-agent finished. The model called TodoWrite and the engine accepted the new list. Emitted exactly once per accepted call (skipped when the new list is byte-identical to the previous one — the dedup-nudge path returns the “unchanged” message to the model without surfacing a transition to clients).

Carries the full new list AND a server-computed diff against the previously persisted list so every client renders the same animation primitives (added / changed / removed) without having to maintain its own previous-list snapshot.

Establishes the principle from DESIGN.md § Progress Tracking: Model-Owned, History-Persisted, Engine-Surfaced — the engine surfaces transitions, the conversation history persists the list, the system prompt does not re-inject it.

Fields

items: Vec<TodoItem>

The full todo list as written by the model on this call.

diff: TodoDiff

Server-computed diff against the previously persisted list (matched by content string). On the first write of a session, every item shows up in added.

BgTaskUpdate

A background sub-agent’s status changed.

Emitted on every transition through crate::bg_agent::AgentStatus (Pending → Running { iter } → terminal). Drained from the registry’s status queue inside the inference loop alongside crate::bg_agent::BgAgentRegistry::drain_completed, so any sink (CLI / TUI / headless / ACP) sees the same event stream without having to poll the registry directly.

Closes the engine/UI boundary leak documented in #1076 — prior to this variant the TUI was the only client that could see live bg status because it shared the process and grabbed Arc<BgAgentRegistry> straight out of KodaSession.

Fields

task_id: u32

Monotonic id assigned at reserve() time, stable for the lifetime of the task.

spawner: Option<u32>

Sub-agent invocation id of the spawner, or None if the task was launched from the top-level loop. See crate::bg_agent::BgTaskSnapshot::spawner.

status: AgentStatus

New status. Includes Running { iter } heartbeats so clients can render iteration progress without polling.

ApprovalRequest

The engine needs user approval before executing a tool.

The client must respond with EngineCommand::ApprovalResponse matching the same id.

Fields

id: String

Unique ID for this approval request.

tool_name: String

Tool name requiring approval.

detail: String

Human-readable description of the action.

preview: Option<DiffPreview>

Structured diff preview (rendered by the client).

effect: ToolEffect

The classified effect that triggered confirmation.

AskUserRequest

The model needs a clarifying answer from the user before proceeding.

The client must respond with EngineCommand::AskUserResponse matching the same id. The answer is returned to the model as the tool result, so inference can continue.

Fields

id: String

Unique ID for this request.

question: String

The question to ask.

options: Vec<String>

Optional answer choices (empty = freeform).

ActionBlocked

An action was blocked by safe mode (shown but not executed).

Fields

tool_name: String

Tool name that was blocked.

detail: String

Description of the blocked action.

preview: Option<DiffPreview>

Diff preview (if applicable).

ContextUsage

Context window usage updated after assembling messages.

Emitted once per inference turn so the client can display context percentage and trigger auto-compaction without reading engine-internal global state.

Fields

used: usize

Tokens used in the current context window.

max: usize

Maximum context window size.

StatusUpdate

Progress/status update for the persistent status bar.

Fields

model: String

Current model identifier.

provider: String

Current provider name.

context_pct: f64

Context window usage (0.0–1.0).

approval_mode: String

Current approval mode label.

active_tools: usize

Number of in-flight tool calls.

Footer

Inference completion footer with timing and token stats.

Fields

prompt_tokens: i64

Input tokens used.

completion_tokens: i64

Output tokens generated.

cache_read_tokens: i64

Tokens read from cache.

thinking_tokens: i64

Tokens used for reasoning.

total_chars: usize

Total response characters.

elapsed_ms: u64

Wall-clock time in milliseconds.

rate: f64

Characters per second.

context: String

Human-readable context usage string.

SpinnerStart

Spinner/progress indicator (presentational hint).

Clients may render this as a terminal spinner, a status bar update, or ignore it entirely. The ratatui TUI uses the status bar instead.

Fields

message: String

Status message to display.

SpinnerStop

Stop the spinner (presentational hint).

See SpinnerStart — clients may ignore this.

TurnStart

An inference turn is starting.

Emitted at the beginning of inference_loop(). Clients can use this to lock input, start timers, or update status indicators.

Fields

turn_id: String

Unique identifier for this turn.

TurnEnd

An inference turn has ended.

Emitted when inference_loop() completes. Clients can use this to unlock input, drain type-ahead queues, or update status.

Fields

turn_id: String

Matches the turn_id from TurnStart.

reason: TurnEndReason

Why the turn ended.

LoopCapReached

The engine’s iteration hard cap was reached.

The client must respond with EngineCommand::LoopDecision. Until the client responds, the inference loop is paused.

Fields

cap: u32

The iteration cap that was hit.

recent_tools: Vec<String>

Recent tool names for context.

Info

Informational message (not from the LLM).

Fields

message: String

The informational message.

Warn

Warning message.

Fields

message: String

The warning message.

Error

Error message.

Fields

message: String

The error message.

Trait Implementations

impl Clone for EngineEvent

fn clone(&self) -> EngineEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for EngineEvent

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for EngineEvent

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for EngineEvent

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

where __S: Serializer,

Serialize this value into the given Serde serializer.