Enum StreamChunk 

pub enum StreamChunk {
    Thinking(String),
    Narration {
        narration: PublicNarration,
        stage: NarrationStage,
    },
    Text(String),
    ToolCallStart {
        id: String,
        name: String,
    },
    ToolCallArgs(String),
    ToolCallEnd,
    ToolCallResult {
        name: String,
        success: bool,
        output: String,
        duration_ms: u64,
    },
    RetryAttempt {
        attempt: u32,
        max_attempts: u32,
        delay_ms: u64,
        error_message: String,
    },
    ContextCompacted {
        messages_before: usize,
        messages_after: usize,
        tokens_saved: usize,
        summary: String,
    },
    TokenUsageUpdate {
        estimated: usize,
        limit: usize,
        percentage: u8,
        status: TokenUsageStatus,
        estimated_cost: f64,
    },
    Status {
        message: String,
    },
    ConfigRequest {
        operation: String,
        key: String,
        value: Option<String>,
        requires_confirmation: bool,
    },
    ToolConfirmationRequired {
        confirmation_id: String,
        tool_name: String,
        tool_args: String,
        description: String,
        risk_level: u8,
        category: String,
    },
    ToolBlocked {
        tool_name: String,
        reason: String,
    },
    MemoryBankSaved {
        file_path: String,
        session_id: String,
        summary: String,
        messages_saved: usize,
    },
    AgentLoopIteration {
        iteration: u32,
    },
    TaskRuntimeSnapshot {
        snapshot: TaskRuntimeSnapshot,
    },
    ShellOutput {
        process_id: String,
        shell_session_id: Option<String>,
        stream: ShellOutputStream,
        data: String,
    },
    ShellLifecycle {
        process_id: String,
        shell_session_id: Option<String>,
        state: ShellProcessState,
        exit_code: Option<i32>,
        duration_ms: Option<u64>,
        command: String,
        cwd: Option<String>,
    },
    ShellSessionLifecycle {
        shell_session_id: String,
        state: ShellSessionState,
        cwd: Option<String>,
        active_process_id: Option<String>,
        active_command: Option<String>,
        available_for_reuse: bool,
        interactive: bool,
        user_managed: bool,
    },
    Done(Option<TokenUsage>),
    Cancelled,
    Paused,
    Error(String),
    ContextOverflow {
        error_message: String,
    },
    ReflectionStarted {
        reason: String,
    },
    ReflectionComplete {
        summary: String,
        stored: bool,
        promoted: bool,
    },
}

A chunk of streaming response

Variants

Thinking(String)

Content from the model’s thinking process

Narration

Public-facing narration explaining the current direction.

Fields

narration: PublicNarration

Structured public narration content for user-facing progress updates.

stage: NarrationStage

Text(String)

A text chunk from the LLM

ToolCallStart

Start of a tool call

Fields

id: String

name: String

ToolCallArgs(String)

Arguments delta for the current tool call

ToolCallEnd

End of the current tool call (LLM finished specifying the call)

ToolCallResult

Result of tool execution with status and output

Fields

name: String

Tool name

success: bool

Whether the tool succeeded

output: String

Output or error message

duration_ms: u64

Execution duration in milliseconds

RetryAttempt

Retry attempt notification for user feedback

Fields

attempt: u32

Current attempt number (1-indexed)

max_attempts: u32

Maximum attempts configured

delay_ms: u64

Delay before next retry in milliseconds

error_message: String

Error that triggered the retry

ContextCompacted

Context compaction notification for user feedback

Fields

messages_before: usize

Number of messages before compaction

messages_after: usize

Number of messages after compaction

tokens_saved: usize

Tokens saved by compaction

summary: String

Summary of what was compacted

TokenUsageUpdate

Token usage notification for user feedback Provides real-time visibility into context window utilization

Fields

estimated: usize

Estimated tokens in current request

limit: usize

Maximum input tokens allowed

percentage: u8

Utilization percentage (0-100)

status: TokenUsageStatus

Status indicator: Green (<70%), Yellow (70-90%), Red (>90%)

estimated_cost: f64

Estimated cost in USD for this request (input only)

Status

A user-facing status message intended for UIs.

This is for short, transient notifications that should not count as streamed “output” (i.e., it must not prevent retry when a provider attempt fails before any actual response content is forwarded).

Fields

message: String

Human-readable status message.

ConfigRequest

A request from the agent to change configuration.

This is surfaced to UIs (GUI/TUI) so they can prompt for confirmation or apply changes immediately in permissive mode.

Fields

operation: String

Operation type (e.g. “set”)

key: String

Config key (e.g. “provider”, “model”, “permission_level”)

value: Option<String>

Requested value. When None, this represents a “query”/“show” style request.

requires_confirmation: bool

Whether the UI must request explicit confirmation before applying.

ToolConfirmationRequired

Tool execution requires user confirmation before proceeding.

This is emitted when a tool call is detected but the session’s permission level requires user approval before execution. The UI should display a confirmation dialog and respond via the confirmation channel.

Fields

confirmation_id: String

Unique ID for this confirmation request

tool_name: String

Tool name that requires confirmation

tool_args: String

Tool arguments (JSON string)

description: String

Human-readable description of what the tool will do

risk_level: u8

Risk level (0-10, higher = more dangerous)

category: String

Category of the tool (e.g., “write”, “shell”, “network”)

ToolBlocked

Tool execution was blocked by permission settings.

This is emitted when a tool call is detected but the session’s permission level blocks the operation entirely (e.g., Sandbox mode blocking writes).

Fields

tool_name: String

Tool name that was blocked

reason: String

Reason for blocking

MemoryBankSaved

Memory bank entry saved notification for user feedback Emitted when context is saved to persistent memory bank file

Fields

file_path: String

Path to the saved memory bank file

session_id: String

Session ID associated with this entry

summary: String

Brief summary of what was saved

messages_saved: usize

Number of messages saved

AgentLoopIteration

Agentic loop iteration boundary marker.

Emitted at the start of each agentic loop iteration. When iteration > 0, it signals that the text following this marker is the LLM’s intermediate reasoning about previous tool results (not the final response). UIs should render this text differently (e.g., with a ◆ prefix or distinct styling) and clearly delineate iteration boundaries.

Fields

iteration: u32

Zero-based iteration index (0 = first LLM call, 1+ = continuation after tools)

TaskRuntimeSnapshot

Runtime-authored task-state snapshot.

Fields

snapshot: TaskRuntimeSnapshot

Authoritative runtime snapshot for the tracked task tree.

ShellOutput

Real-time shell output chunk (stdout or stderr).

Emitted while a shell command is executing so the UI can stream output into an embedded terminal component. Each chunk is a small fragment of text (typically one or a few lines).

Fields

process_id: String

Unique identifier for the shell process (matches ShellLifecycle).

shell_session_id: Option<String>

Long-lived shell session that produced this output, if any.

stream: ShellOutputStream

Whether this chunk comes from stdout or stderr.

data: String

The raw text data (may contain ANSI escape sequences).

ShellLifecycle

Shell process lifecycle event.

Emitted when a shell process transitions between states (started, completed, failed, stopped, paused, resumed). The UI uses this to update the console header, show exit codes, and enable/disable control buttons.

Fields

process_id: String

Unique identifier for the shell process (matches ShellOutput).

shell_session_id: Option<String>

Long-lived shell session that owns this command run, if any.

state: ShellProcessState

New state of the process.

exit_code: Option<i32>

Exit code (only meaningful when state is Completed or Failed).

duration_ms: Option<u64>

Wall-clock duration in milliseconds (set on terminal states).

command: String

The command string that was executed.

cwd: Option<String>

Working directory for the command.

ShellSessionLifecycle

Interactive shell session lifecycle event.

Fields

shell_session_id: String

Long-lived shell session identifier.

state: ShellSessionState

New state of the shell session.

cwd: Option<String>

Current working directory tracked for the session.

active_process_id: Option<String>

Active command process id, when the session is busy.

active_command: Option<String>

Active command string, when the session is busy.

available_for_reuse: bool

Whether the session is currently eligible for reuse.

interactive: bool

Whether the session is a user-facing interactive shell.

user_managed: bool

Whether the session is currently reserved for direct user management.

Done(Option<TokenUsage>)

Stream completed successfully with optional token usage

Cancelled

Stream was cancelled

Paused

Stream was paused (cancelled with the intent to resume later).

The caller is responsible for capturing the PausedExecutionState from the accumulated streaming context. This variant is a signal to the UI to render a resumable pause marker rather than a hard cancellation.

Error(String)

An error occurred

ContextOverflow

Context overflow error - requires compaction before retry.

This is emitted when the LLM request exceeds the model’s context window. Unlike generic errors, this signals to the pipeline that it should:

1. Compact the context (summarize history, remove old messages)
2. Retry the request with the reduced context
3. Optionally learn the model’s actual limit for future requests

Fields

error_message: String

The original error message from the provider

ReflectionStarted

Experiential reflection phase has started (ERL-inspired).

UIs can use this to surface that the pipeline is performing a post-answer self-review step rather than continuing normal tool use.

Fields

reason: String

Human-readable reason for triggering reflection.

ReflectionComplete

Experiential reflection phase completed (ERL-inspired).

This reports both the learned summary and whether the result stayed only in short-term/session storage or was also promoted into long-term memory.

Fields

summary: String

Brief summary of what was learned.

stored: bool

Whether the reflection was stored in session working memory.

promoted: bool

Whether the reflection was promoted to long-term memory bank.

Trait Implementations

impl Clone for StreamChunk

fn clone(&self) -> StreamChunk

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for StreamChunk

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

Formats the value using the given formatter.