Messaging

Messages are the medium for user-AI interaction. Users send messages and the AI streams responses, with support for Markdown rendering, code highlighting, thinking process display, and tool call cards — the entire process is visible in real time.

Message Types

Type	Description	Rendering
💬 User Message	Content entered by the user	Plain text
📝 AI Reply	Text generated by AI	Markdown + code highlighting
🧠 Thinking Process	AI’s reasoning process	Collapsible, Markdown rendered
⚙️ Tool Call	Tool requested by AI for execution	Input/output cards
📄 Summary	Compressed summary after context compaction (summary)	Markdown rendered
📃 Plain Text	Unformatted text content (text)	Plain text
🔧 Tool Message	Independent tool role message (tool role)	Input/output cards
ℹ️ System Message	System notifications	Plain text

MessageRole has 4 types: user, assistant, system, tool ContentType has 6 types: text, markdown, summary, thinking, toolcall_input, toolcall_output

Message Sending Flow

Messages use a local-first strategy: stored locally first for immediate display, then synced asynchronously in the background. After sending a message, the user sees it appear in the UI with zero wait.

Send Failure Handling

Sync State	User-Visible Behavior
pending	Message shows sending animation
synced	Message displays normally
failed	Message shows failure marker + 🔄 retry button

💡 Retries use the same client_id, and the server idempotently deduplicates, so no duplicate messages are produced.

Turn State Machine

Each AI processing cycle constitutes a Turn, which has a well-defined lifecycle:

State	Meaning	User-Visible Behavior
Pending	Waiting to execute	Message shows “Processing”
Running	Currently executing	AI streams output, tool cards flash
Interrupted	Waiting for tool execution	Tool card shows “Executing”
Completed	Normal completion	AI reply fully displayed
Failed	Execution failed	Error message shown
Cancelled	User cancelled	Stopped marker shown
Merged	Merged into another turn	Not displayed separately

Streaming Messages

AI replies arrive token by token in a stream, so users don’t have to wait for the complete response:

Streaming messages are transmitted via dual channels:

Channel	Purpose	Characteristics
Topic Channel	First chunk + final complete message	Persistent, supports offline recovery
Live Channel	Intermediate chunks	Non-persistent, low latency, tolerant to loss

💡 The final complete message is pushed via the Topic channel, so even if intermediate chunks are lost, the complete content is eventually received.

Stopping a Turn

Users can stop a running turn at any time:

AI Thinking Display

The AI’s reasoning process is collapsed by default; users can expand it to view:

Feature	Description
Collapsed by default	Saves UI space
Click to expand	View full reasoning process
Streaming animation	Pulse animation effect during generation
Markdown rendering	Supports formatted display

Tool Call Cards

Each RTC tool call is displayed as a card with input and output sections:

Feature	Description
Sectioned Display	Input parameters and output results shown independently
JSON Formatting	Parameters and results auto-pretty-printed
Status Indicator	Running (🟠 orange pulse) / Completed (🟢 green)
Copy Button	One-click copy of input/output content

Message List

Feature	Description
📊 Sorting	Ascending by send time (oldest first)
📑 Pagination	Cursor-based pagination, loads history from server
📜 Auto-scroll	Automatically scrolls to bottom when new messages arrive
🔔 New Message Alert	Shows ”↓ New messages” button when user scrolls away from bottom

Message Retry

Scenario	Handling
Send failure	Marked as failed, retry button displayed
Idempotency	Uses client_id for deduplication; retries produce no duplicates
RTC failure	Exponential backoff retry (1s → 2s → 4s → … → 30s cap)

Next Steps

• Session Management — Learn about the session container that holds messages
• Remote Tool Calling — Learn about the mechanics behind tool call cards
• Real-time Communication — Learn about the dual-channel architecture for streaming messages