Enum AgentEvent 

pub enum AgentEvent {
    TextDelta(String),
    ReasoningDelta(String),
    ToolCallStreaming {
        name: String,
        hint: String,
    },
    ToolCallStarted {
        id: String,
        name: String,
        arguments: String,
    },
    ToolBatchStarted {
        batch_id: String,
        calls: Vec<ToolBatchCall>,
    },
    ToolBatchCompleted {
        batch_id: String,
        ok: usize,
        total: usize,
        elapsed_ms: u64,
    },
    ToolOutputChunk {
        call_id: String,
        chunk: String,
    },
    ToolCallResult {
        call_id: String,
        name: String,
        output: String,
        success: bool,
        duration: Duration,
    },
    ApprovalNeeded {
        tool_name: String,
        reason: String,
        call: ToolCall,
        messages: Vec<Message>,
    },
    TokenUsage(TokenUsage),
    PhaseChange(AgentPhase),
    TurnComplete {
        duration: Duration,
        total_tokens: usize,
        turn_count: usize,
        tool_call_count: usize,
        stop_reason: TurnStopReason,
        messages: Vec<Message>,
    },
    TurnCancelled {
        messages: Vec<Message>,
    },
    MessagesSync {
        messages: Vec<Message>,
    },
    Error {
        error: String,
        messages: Vec<Message>,
    },
    Warning(String),
    RestorePendingImages {
        images: Vec<ImagePart>,
        markers: Vec<usize>,
    },
    VisionPreprocessSuccess {
        vl_key: String,
        char_count: usize,
    },
    SubAgentDispatchStart {
        tasks: Vec<SubAgentTaskInfo>,
    },
    SubAgentDispatchEnd,
    SubAgentTaskStarted {
        index: usize,
    },
    SubAgentTaskDone {
        index: usize,
        elapsed_ms: u64,
        turns: usize,
        summary: String,
    },
    SubAgentTaskFailed {
        index: usize,
        elapsed_ms: u64,
        turns: usize,
        reason: String,
    },
    BackgroundComplete {
        summary: String,
        files_edited: Vec<String>,
        turns: usize,
        success: bool,
    },
    WorkingDirChanged(PathBuf),
    ContextStats {
        system_tokens: usize,
        sent_tokens: usize,
        dropped_tokens: usize,
        working_set_tokens: usize,
        total_messages: usize,
        tool_defs_tokens: usize,
        cold_zone_tokens: usize,
        ctx_window: usize,
        ctx_name: String,
        system_prompt: String,
    },
}

Events sent FROM the agent loop TO the UI.

Variants

TextDelta(String)

LLM text delta (streaming).

ReasoningDelta(String)

LLM reasoning/thinking content (e.g., DeepSeek-R1, MiniMax-M2.7, o1-series). Emitted when the model produces thinking content separately from the final response. UI can optionally display this in verbose mode (Ctrl+O).

ToolCallStreaming

LLM has started emitting a tool call — only the name is known so far, arguments are still streaming. UI uses this to display the tool name immediately instead of waiting for the full args.

Fields

name: String

hint: String

ToolCallStarted

A tool call is about to execute (for display). id pairs with ToolCallResult.call_id so the UI can match start→result across parallel or interleaved calls without reconstructing ids from counters.

Fields

id: String

name: String

arguments: String

ToolBatchStarted

Multiple tool calls fan out from one assistant message. Fires BEFORE the per-call ToolCallStarted events, only when ≥ 2 non-duplicate calls are about to dispatch. UI uses this to render a single grouped block (▸ Reading 4 files (parallel) + child rows) rather than N independent ▸ rows. Per-call events still fire for backward compat — UI dedupes via batch_id membership.

Fields

batch_id: String

calls: Vec<ToolBatchCall>

ToolBatchCompleted

Closes the batch opened by ToolBatchStarted. UI finalizes the group header with · N/M ok · Xs wall summary.

Fields

batch_id: String

ok: usize

total: usize

elapsed_ms: u64

ToolOutputChunk

Real-time output chunk from a running tool (e.g., bash command). Sent during tool execution before ToolCallResult.

Fields

call_id: String

chunk: String

ToolCallResult

A tool call completed with a result.

Fields

call_id: String

name: String

output: String

success: bool

duration: Duration

ApprovalNeeded

Waiting for user approval of a tool call.

Fields

tool_name: String

reason: String

call: ToolCall

messages: Vec<Message>

Snapshot of conversation.messages at the time the approval request was raised. Lets the TUI persist mid-turn session state (e.g. when /bg backgrounds a session that is waiting for approval).

TokenUsage(TokenUsage)

Token usage update.

PhaseChange(AgentPhase)

The agent’s current phase changed.

TurnComplete

Turn completed successfully.

Fields

duration: Duration

total_tokens: usize

turn_count: usize

LLM round-trips (standard agent metric).

tool_call_count: usize

Total individual tool calls.

stop_reason: TurnStopReason

Why the loop stopped. Natural for ordinary completion; see TurnStopReason for budget / cancel / error variants.

messages: Vec<Message>

Snapshot of the conversation messages at the moment the turn ended. Mirrors TurnCancelled.messages so UIs have one uniform path for persisting session state on either terminal event.

TurnCancelled

Turn was cancelled by user before completion. The conversation has been cleaned up - partial messages removed. Contains the cleaned message list for TUI to sync.

Fields

messages: Vec<Message>

MessagesSync

Response to AgentCommand::SyncMessages. Carries a snapshot of conversation.messages at the time the agent processed the command. Used by the TUI to sync session state before backgrounding a session that is mid-turn (e.g. waiting for tool approval).

Fields

messages: Vec<Message>

Error

An error occurred. Carries a snapshot of conversation.messages so the TUI can persist mid-turn state even when the turn dies before TurnComplete/TurnCancelled fire — without this, a first-turn LLM failure silently drops the user’s typed message from disk and /resume shows nothing for that conversation. Producers that don’t hold the conversation (the inline streaming-error forwarder in run_turn_loop) send messages: Vec::new(); the terminal error path captured at handle_send_message provides the full snapshot.

Fields

error: String

messages: Vec<Message>

Warning(String)

Non-fatal advisory from a provider or other subsystem. UI renders this as a one-line yellow banner; does not abort the turn. Currently sourced from the OpenAI provider’s truncation detector when the proxy reports implausibly few prompt_tokens.

RestorePendingImages

VL preprocessing failed; the agent is returning the user’s pending images so the TUI can re-attach them to the input state. Lets the user retry the same image without re-pasting from clipboard. Hashes are TUI-side state, so the renderer recomputes them from the returned base64 bytes (best-effort; clipboard-equality dedup may fire on a fresh paste of the same image — minor UX, not breaking).

Fields

images: Vec<ImagePart>

markers: Vec<usize>

Original [Image #N] numbers, parallel to images. Round-tripped from AgentCommand::SendMessage::image_markers so the TUI can re-attach with the SAME marker numbers — keeps UP-recalled caption text matching after retry.

VisionPreprocessSuccess

VL preprocessing succeeded — surface a one-line success notice without dumping the (possibly long, sometimes uninformative) VL description into the UI. The description still rides into conversation history for the main model. vl_key is the provider key from config; char_count is text.chars().count() so users can spot zero/near-zero outputs that would mislead the main model.

Fields

vl_key: String

char_count: usize

SubAgentDispatchStart

Sub-agent batch began. tasks is the ordered list of children the dispatcher is about to fork — same order as the resulting SubAgentTaskDone/SubAgentTaskFailed events will arrive in, so the UI can pre-allocate one display slot per child and disambiguate same-basename tasks via the index.

Fields

tasks: Vec<SubAgentTaskInfo>

Per-task descriptors. path is the workspace-relative file path (preserved as the model wrote it — no basename-only truncation). dedup_suffix is the user-facing (#2), (#3) qualifier when the same path appears N times in one dispatch; empty for unique entries.

SubAgentDispatchEnd

Sub-agent batch ended (all tasks settled or pool returned). UI clears the override so subsequent thinks/tools resume normal label behaviour.

SubAgentTaskStarted

One sub-agent has been claimed from the pool and is now running. index indexes into the tasks vector emitted with the matching DispatchStart so the UI can locate its slot.

Fields

index: usize

SubAgentTaskDone

Sub-agent finished successfully. summary is a one-sentence human-readable result, already truncated to a reasonable length by the agent loop.

Fields

index: usize

elapsed_ms: u64

turns: usize

summary: String

SubAgentTaskFailed

Sub-agent failed (error, timeout, no-edit). reason is one short phrase, not a stack trace.

Fields

index: usize

elapsed_ms: u64

turns: usize

reason: String

BackgroundComplete

/background task finished. summary is the final assistant text (truncated if long). success is false on error / timeout / cancel.

Fields

summary: String

files_edited: Vec<String>

turns: usize

success: bool

WorkingDirChanged(PathBuf)

Working directory changed.

ContextStats

Context budget stats — piped into datalog and cached by the TUI for /context. Emitted after every turn’s ctx.build_messages call, so stats reflect the snapshot the model actually saw.

The rich breakdown (tool defs / cold zone / ctx window / ctx name) only appears on the second emission path in handle_send_message — the first path (TurnEvent forwarding) uses the narrow stats from the ctx::render output. TUI merges both.

Fields

system_tokens: usize

sent_tokens: usize

dropped_tokens: usize

working_set_tokens: usize

total_messages: usize

tool_defs_tokens: usize

Total bytes of tool definitions / 4. 0 when not yet computed.

cold_zone_tokens: usize

Tokens used by cold-zone compressed summaries.

ctx_window: usize

Effective token budget from the active ctx strategy (ctx.ctx_window()), including any defensive clamping.

ctx_name: String

Ctx strategy name — default / ollama / future impls.

system_prompt: String

Full assembled system prompt for the turn — lets the TUI’s /context prompt show the exact bytes sent. Empty on the narrow TurnEvent-forwarded path; only the rich emission in handle_send_message fills this.

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

Formats the value using the given formatter.