UiMessage Types

UiMessage is the enum used to communicate from the controller to the TUI layer. These messages are designed for UI consumption, with fields optimized for display rather than internal processing. This page documents all message variants and the channel infrastructure.

Overview

UiMessage is the TUI-facing counterpart to ControllerEvent. While ControllerEvent represents internal controller state changes, UiMessage is structured for UI rendering:

// Controller emits events
let event = ControllerEvent::TextChunk { session_id, text, turn_id };

// Conversion to UI message
let msg = convert_controller_event_to_ui_message(event);

// TUI receives and handles
match msg {
    UiMessage::TextChunk { text, .. } => chat_view.append_text(&text),
    // ...
}

Message Categories

Content Messages

TextChunk

Streamed text content from the LLM:

UiMessage::TextChunk {
    session_id: i64,
    turn_id: Option<TurnId>,
    text: String,
    input_tokens: i64,
    output_tokens: i64,
}

The TUI appends each chunk to the chat view. Token counts may be zero during streaming and are updated via TokenUpdate.

Display

General display messages for status and information:

UiMessage::Display {
    session_id: i64,
    turn_id: Option<TurnId>,
    message: String,
}

Used for informational messages like “Executing tool: web_search”.

Tool Status Messages

ToolExecuting

Indicates a tool has started execution:

UiMessage::ToolExecuting {
    session_id: i64,
    turn_id: Option<TurnId>,
    tool_use_id: String,
    display_name: String,
    display_title: String,
}

The TUI can show a spinner or progress indicator using this message.

ToolCompleted

Indicates a tool has finished execution:

UiMessage::ToolCompleted {
    session_id: i64,
    turn_id: Option<TurnId>,
    tool_use_id: String,
    status: ToolResultStatus,
    error: Option<String>,
}

ToolResultStatus:

pub enum ToolResultStatus {
    Success,
    Error,
    Timeout,
}

The TUI updates the tool status display to show completion or failure.

Lifecycle Messages

Complete

Response from the LLM is complete:

UiMessage::Complete {
    session_id: i64,
    turn_id: Option<TurnId>,
    input_tokens: i64,
    output_tokens: i64,
    stop_reason: Option<String>,
}

Stop Reasons:

When stop_reason is "tool_use", the TUI knows more activity will follow.

Monitoring Messages

TokenUpdate

Real-time token usage information:

UiMessage::TokenUpdate {
    session_id: i64,
    turn_id: Option<TurnId>,
    input_tokens: i64,
    output_tokens: i64,
    context_limit: i32,
}

Used to update status bar displays with context usage percentage.

Error Messages

Error

Error from the controller:

UiMessage::Error {
    session_id: i64,
    turn_id: Option<TurnId>,
    error: String,
}

The TUI should display the error prominently, typically in red text.

System Messages

System

Local TUI system messages:

UiMessage::System {
    session_id: i64,
    message: String,
}

Used for TUI-local messages that do not originate from the controller (e.g., silent StreamStart events are converted to empty System messages).

Control Messages

CommandComplete

Control command has completed:

UiMessage::CommandComplete {
    session_id: i64,
    command: ControlCmd,
    success: bool,
    message: Option<String>,
}

ControlCmd:

pub enum ControlCmd {
    Interrupt,
    Shutdown,
    Clear,
    Compact,
}

User Interaction Messages

UserInteractionRequired

Tool needs user input:

UiMessage::UserInteractionRequired {
    session_id: i64,
    tool_use_id: String,
    request: AskUserQuestionsRequest,
    turn_id: Option<TurnId>,
}

The TUI should:

1. Display the QuestionPanel
2. Collect user responses
3. Submit via UserInteractionRegistry.submit_response()

PermissionRequired

Tool needs user permission:

UiMessage::PermissionRequired {
    session_id: i64,
    tool_use_id: String,
    request: PermissionRequest,
    turn_id: Option<TurnId>,
}

The TUI should:

1. Display the PermissionPanel
2. Collect user decision (allow/deny)
3. Submit via PermissionRegistry.submit_response()

Channel Infrastructure

Type Aliases

pub mod channels {
    use tokio::sync::mpsc;

    pub type ToControllerTx = mpsc::Sender<ControllerInputPayload>;
    pub type ToControllerRx = mpsc::Receiver<ControllerInputPayload>;
    pub type FromControllerTx = mpsc::Sender<UiMessage>;
    pub type FromControllerRx = mpsc::Receiver<UiMessage>;
}

Default Buffer Size

pub const DEFAULT_CHANNEL_SIZE: usize = 100;

Channel Creation

pub fn create_channels() -> (ToControllerTx, ToControllerRx, FromControllerTx, FromControllerRx) {
    let (to_ctrl_tx, to_ctrl_rx) = mpsc::channel(DEFAULT_CHANNEL_SIZE);
    let (from_ctrl_tx, from_ctrl_rx) = mpsc::channel(DEFAULT_CHANNEL_SIZE);
    (to_ctrl_tx, to_ctrl_rx, from_ctrl_tx, from_ctrl_rx)
}

Handling Messages

The App receives messages in its event loop:

impl App {
    fn handle_controller_message(&mut self, msg: UiMessage) {
        match msg {
            UiMessage::TextChunk { session_id, text, .. } => {
                if session_id == self.current_session {
                    self.chat_view.append_text(&text);
                }
            }
            UiMessage::ToolExecuting { tool_use_id, display_name, display_title, .. } => {
                self.chat_view.add_tool_executing(&tool_use_id, &display_name, &display_title);
            }
            UiMessage::ToolCompleted { tool_use_id, status, error, .. } => {
                self.chat_view.update_tool_status(&tool_use_id, status, error);
            }
            UiMessage::Complete { stop_reason, .. } => {
                if stop_reason.as_deref() != Some("tool_use") {
                    self.set_input_ready();
                }
            }
            UiMessage::Error { error, .. } => {
                self.chat_view.add_error(&error);
            }
            UiMessage::TokenUpdate { input_tokens, output_tokens, context_limit, .. } => {
                self.status_bar.update_tokens(input_tokens, output_tokens, context_limit);
            }
            UiMessage::UserInteractionRequired { request, .. } => {
                self.show_question_panel(request);
            }
            UiMessage::PermissionRequired { request, .. } => {
                self.show_permission_panel(request);
            }
            // ... other variants
        }
    }
}

Session Filtering

Messages include session_id for filtering in multi-session scenarios:

if msg.session_id() == self.current_session_id {
    self.process_message(msg);
}

This allows the TUI to ignore messages from background sessions.

Next Steps

• Controller Events - The source events and conversion logic
• Message Handling - The controller’s message processing