GUI Chat Flow

GUI Chat Flow

Chat messages are sent as commands and received through SSE events, with sequence checks and thread-level runtime transitions.

Transport model

Chat uses two backend endpoints:

• POST /v1/chats/{chatId}/commands
• GET /v1/chats/subscribe?chat_id={id}

The command endpoint sends user intents, and the SSE stream returns snapshots and incremental updates.

sequenceDiagram
  participant UI as GUI
  participant API as Backend
  UI->>API: POST /v1/chats/{id}/commands
  API-->>UI: SSE snapshot
  API-->>UI: SSE stream_delta*
  API-->>UI: SSE stream_finished
  UI->>UI: reducer applies events

Loading

SSE event types

Event type	Purpose
snapshot	Full state sync; resets sequence to 0
stream_started	Assistant generation begins
stream_delta	Incremental content via DeltaOp[]
stream_finished	Completion with finish reason / usage
message_added	Insert message
message_updated	Update message
message_removed	Remove message
messages_truncated	Trim history
thread_updated	Thread metadata changed
runtime_updated	Runtime flags changed
pause_required	Tool confirmation pause
pause_cleared	Confirmation pause cleared
ide_tool_required	IDE tool action needed
subchat_update	Nested chat update
queue_updated	Command queue changed
ack	Command acknowledgment
background_agent_updated	Background agent update
browser_* events	Browser-related streaming and status updates
process_completed	Process completion event

Delta operations

stream_delta uses DeltaOp[] with these operations:

• append_content
• append_reasoning
• set_tool_calls
• set_thinking_blocks
• add_citation
• add_server_content_block
• set_usage
• merge_extra

Command types

Commands posted to /v1/chats/{chatId}/commands include:

• user_message
• abort
• regenerate
• update_message
• remove_message
• tool_decision
• tool_decisions
• ide_tool_result
• set_params
• retry_from_index
• branch_from_chat
• browser_context_decision

Sequence validation

• snapshot establishes the baseline and resets sequence tracking to 0
• each following event increments by 1
• a gap in sequence numbers triggers reconnect logic to obtain a fresh snapshot

Thread state machine

Per-thread runtime follows the backend-driven lifecycle rather than a single global chat state.

stateDiagram-v2
  [*] --> IDLE
  IDLE --> WAITING: command sent / awaiting result
  WAITING --> STREAMING: stream_started or stream_delta
  STREAMING --> IDLE: stream_finished
  WAITING --> PAUSED: pause_required
  PAUSED --> WAITING: pause_cleared or tool decision
  WAITING --> STOPPED: abort / terminal error
  STREAMING --> STOPPED: abort / terminal error
  STOPPED --> IDLE

Loading

The concrete runtime booleans and states observed in the code include streaming, waiting_for_response, confirmation.pause, session_state, and error.

Send invariants

• Commands are issued with a client request id.
• user_message may carry content as a string or rich content array.
• priority is supported on commands and queued items.
• abort, regenerate, and tool decision commands are explicit command types rather than local state mutations.
• snapshot_received gates whether a thread is considered synchronized enough for follow-up actions.

Related pages

• Chat System
• GUI Architecture