TUI gateway RPC
The TUI gateway is the shared backend for the terminal UI, Desktop chat, and dashboard chat. It gives these clients one JSON-RPC surface for sessions, turns, user prompts, agent events, and actions that need a user response. The user interfaces page gives the wider UI view, while the web dashboard page covers the browser surface.
Gateway role
The gateway separates screen work from agent work. The client renders the transcript and prompts. The Python gateway owns sessions, tools, model calls, durable history, and command behavior. This keeps the same chat behavior across the TUI and WebSocket clients.
Backend boundary
The gateway receives client method calls and returns results or events. A session is the live link between a client view and an agent conversation. The gateway also keeps enough session state to reattach a view after a connection loss.
References: tui_gateway/AGENTS.md• L1-17 tui_gateway/server.py• L95-115
Transport model
The same JSON-RPC dispatcher serves two client paths. The terminal TUI uses a newline-delimited stdio stream. Desktop and dashboard clients use a WebSocket that carries the same frame shapes and method names.
Stdio transport
The TUI starts a Python gateway child and exchanges one JSON frame per line. Standard output is reserved for RPC frames, while gateway diagnostics go to standard error. This path is local and peer-to-peer, so the client and gateway share one process pair.
References: tui_gateway/entry.py• L36-54 tui_gateway/transport.py• L1-7 ui-tui/…/gatewayClient.ts• L444-478
WebSocket transport
The WebSocket path exposes the gateway to Desktop and dashboard clients. A connection starts with gateway.ready. That event carries the active skin, heartbeat support, change-event support, and a replay epoch. The server tracks the connection for session events and global events.
The transport sends frames in order. It keeps slow or failed peers from blocking other clients. High-rate text delta events can be grouped for the wire, while control events keep their order and are sent promptly.
References: tui_gateway/ws.py• L1-4 tui_gateway/ws.py• L92-224 tui_gateway/ws.py• L352-377
Connection lifecycle
The WebSocket read loop accepts requests in arrival order. Heartbeat calls are answered without waiting behind a long RPC. On disconnect, the gateway first finishes accepted work, then detaches or reaps the sessions owned by that connection. A quick reconnect can attach to a parked session.
The TUI client also reconnects after a dropped or silent socket. It waits for a new ready event before it treats the gateway as usable.
References: tui_gateway/ws.py• L315-350 tui_gateway/ws.py• L394-477 ui-tui/…/gatewayClient.ts• L242-354
WebSocket protocol
The protocol uses JSON-RPC 2.0 frames in both directions. Client calls have a method, parameters, and an id. The gateway returns a result or error for calls. Events are JSON-RPC notifications with method event; their parameters contain an event type, session id, and payload.
The gateway can also send a request to the client. This is used when agent work needs a user answer, such as approval, clarification, a secret, or a Desktop window action. The client answers with a frame that uses the same request id.
sequenceDiagram
participant C as TUI/Desktop client
participant G as TUI gateway
participant A as Agent or tool
C->>G: JSON-RPC request
G->>A: Run session or turn work
A-->>G: Event or user question
G-->>C: event notification or server request
C-->>G: Result or answer frame
G-->>C: JSON-RPC result
Server requests
Server requests are live waits owned by the gateway. Each request has a unique string id. A timeout, cancel, or session close removes the wait and emits one cancel event. A reconnect gets still-open requests from the session snapshot, so a user question does not depend on the event ring.
Clients advertise that they support server requests. If no attached client can answer, the gateway fails the request instead of leaving the agent blocked until a long timeout.
References: tui_gateway/server_requests.py• L1-34 tui_gateway/server_requests.py• L149-199 tui_gateway/server_requests.py• L253-293
RPC dispatch
RPC dispatch is the single route from a wire method to a gateway action. It checks the request, finds the registered handler, validates its parameters, and returns the handler result. Unknown methods produce a version mismatch error rather than a silent no-op.
Fast methods run inline. Work that can wait on a model, file system, network, or external process runs in the RPC worker pool. A long handler writes its own response through the transport bound to the request. This keeps one client’s slow work from blocking heartbeat and control traffic.
Method groups
The method catalog supports the main product flows:
prompt.submitstarts or queues user work.session.*creates, lists, resumes, activates, controls, and closes conversations.complete.*,slash.*, andcommand.*support input and command actions.config.*,model.*,tools.*, andreload.mcpupdate the working environment.connection.*, approval, clarify, voice, and Desktop bridge methods connect agent work to user actions.
The dispatcher also routes response frames from the client back to an open server request or to a compute host that owns the request.
References: tui_gateway/rpc_dispatch.py• L8-89 tui_gateway/server.py• L166-198 tui_gateway/AGENTS.md• L18-35
Event replay
Events carry a monotonic sequence number for each live session. The gateway stores a bounded recent event ring in memory. After reconnect, the client calls session.events.since with its last sequence number and receives newer event objects.
The response includes the newest sequence, the process replay epoch, and a truncation flag. If the ring dropped part of the requested range, the client must reload session state instead of trusting an incomplete tail. A new epoch tells the client that the gateway restarted and that old sequence numbers no longer apply.
flowchart LR
E[Session event] --> S[Per-session sequence]
S --> R[Bounded replay ring]
R --> Q[session.events.since]
Q --> C[Client]
R --> T{Requested range retained?}
T -- Yes --> C
T -- No --> H[Refetch session history]
The replay ring carries events, not unanswered questions. Open server requests are added to the replay response as a separate list. This lets the client restore both visible activity and pending user prompts.
References: tui_gateway/event_replay.py• L1-12 tui_gateway/event_replay.py• L67-149 tui_gateway/methods_session.py• L2338-2352
Turn submission
prompt.submit is the main path from user input to agent work. It resolves the live session, checks whether the session can accept work, applies any requested history change, and claims the turn. The gateway then streams agent progress through events and returns the initial submission status.
When a session is busy, the configured input mode decides whether new text is queued, used to steer the running turn, or causes an interrupt. A turn can include attachments and display metadata, but the gateway remains the owner of session history and turn state.
flowchart TD
I[User text] --> P[prompt.submit]
P --> V[Validate session and input]
V --> B{Session busy?}
B -- Yes --> M[Queue, steer, or interrupt]
B -- No --> A[Admit turn]
M --> A
A --> X{Turn isolation enabled?}
X -- No --> L[Run in gateway process]
X -- Yes --> H[Send to compute host]
L --> O[Stream events and persist history]
H --> O
The gateway reports progress as events such as message deltas, tool activity, status changes, and session information. The client does not run agent behavior; it renders these events and sends user answers back through RPC.
References: tui_gateway/methods_prompt.py• L681-819 tui_gateway/server.py• L676-706 tui_gateway/AGENTS.md• L52-68
Session operations
Session RPCs manage the difference between a durable conversation and a live runtime handle. Creation returns both the process-local session id and the durable stored id. Resume uses the durable id to rebuild or reconnect the live session.
Session lifecycle
The normal lifecycle is:
- Create a lazy session or resume a stored session.
- Build or reuse the agent when the session needs live work.
- Activate the session on the current client transport.
- Submit turns and receive events.
- Interrupt, close, or detach the session.
- Persist final state and reap abandoned sessions when needed.
Session listing reads durable history. The active-session view reads live sessions in the current gateway process. Activation changes the client attachment without closing the prior session.
References: tui_gateway/methods_session.py• L241-250 tui_gateway/methods_session.py• L491-500 tui_gateway/methods_session.py• L1057-1089 tui_gateway/methods_session.py• L1150-1176
Session controls
Session controls cover the actions that change or inspect a conversation. They include interrupt, close, save, branch, compress, undo, workspace changes, model changes, and terminal resize. These actions use the same session identity and transport checks as turn submission.
The gateway keeps session metadata current through session.info events. Metadata can include the model, provider, working directory, tools, usage, and current turn state. A session may remain parked after a WebSocket disconnect so a new client can resume it.
References: tui_gateway/methods_session.py• L1092-1147 tui_gateway/methods_session.py• L1179-1202 tui_gateway/methods_session.py• L2331-2359 tui_gateway/ws.py• L459-466
Compute-host bridging
Compute-host bridging moves live agent turns into a separate child process when dashboard turn isolation is enabled. The serving gateway keeps the client connection and session view. The child owns the active agent and sends turn results, progress, metadata, and user-question frames back to the parent.
This split protects the serving process from heavy model and tool work. It also lets the gateway keep handling WebSocket traffic, heartbeats, reconnects, and session control while a turn runs.
Turn bridge
For an isolated turn, the parent sends the child the session history, prompt, working directory, profile context, and turn options. The child runs the turn and returns completion metadata. The parent mirrors the child’s session key, history version, running state, and session information for client reads.
sequenceDiagram
participant C as Client
participant G as Gateway
participant H as Compute host
participant A as Agent
C->>G: prompt.submit
G->>H: turn.start
H->>A: Run turn
A-->>H: Events and metadata
H-->>G: Event or turn result
G-->>C: Stream event
G-->>C: Final session state
References: tui_gateway/compute_host_bridge.py• L50-84 tui_gateway/compute_host_bridge.py• L268-305 tui_gateway/compute_host.py• L173-280
Interactive bridge
A question created by the child still belongs to the child’s agent wait. The parent mirrors it in the live session so a reconnect can restore it. A client answer is routed back to the child. Batch clarification locks are also forwarded and mirrored until the full answer set is complete.
Interrupts and other controls follow the same parent-to-child route. The supervisor starts the host when needed, checks its identity and build, tracks replies, and can respawn it within a bounded crash policy.
References: tui_gateway/compute_host_bridge.py• L126-225 tui_gateway/host_supervisor.py• L235-304 tui_gateway/host_supervisor.py• L326-365
Change checklist
When these files or sections are changed, remember to consider these:
- Keep stdio and WebSocket frames compatible. The same dispatcher serves both paths.
- For a new server request, update its client capability path and its reconnect snapshot behavior.
- For a new session event, preserve its session id and sequence behavior so reconnect replay can restore it.
- For a new compute-host control, classify its route and define its acknowledgement and late-ack behavior.
- When changing session ids or compression state, update both the durable id used by resume and the live id used by event routing.
- Keep profile context on both the parent gateway and compute-host turn frame.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Client and gateway use different RPC catalogs | The method is rejected as unknown or its fields fail validation | Keep the shared method contract and both clients in sync |
| Replay ring no longer contains the requested range | The client can show a hole in the transcript | Check truncated and refetch session state |
| Gateway restarts while a client holds sequence numbers | Old event watermarks can hide new events | Compare the replay epoch from gateway.ready and reset watermarks |
| Client disconnects during a turn | Streaming stops for that socket and the session may become parked | Reconnect and activate or resume the session before relying on live events |
| Client does not advertise server-request support | Approval or clarification cannot reach a user and the agent would otherwise wait | Fail fast when no attached client can answer |
| Compute host stops during an isolated turn | The turn returns an error or uses the configured fallback path | Supervisor heartbeat, identity checks, bounded respawn, and parent metadata mirror |
| WebSocket send queue overflows or stalls | The peer is closed and its session events stop on that connection | Reconnect and use event replay plus session snapshots |
Key files
| File | Why to read it |
|---|---|
| tui_gateway/server.py | Gateway facade for transports, event emission, session routing, and shared runtime state |
| tui_gateway/transport.py | Common transport contract and bounded event fanout behavior |
| tui_gateway/ws.py | WebSocket handshake, read loop, heartbeat path, ordered writes, and disconnect cleanup |
| tui_gateway/rpc_dispatch.py | RPC validation, handler selection, and long-work dispatch |
| tui_gateway/server_requests.py | Backend-to-client questions and response settlement |
| tui_gateway/event_replay.py | Per-session event sequence and reconnect replay rules |
| tui_gateway/methods_prompt.py | Turn admission, busy-session behavior, and prompt submission |
| tui_gateway/methods_session.py | Session create, resume, activate, control, and event replay RPCs |
| tui_gateway/compute_host_bridge.py | Parent-side turn, metadata, control, and user-question relay |
| tui_gateway/host_supervisor.py | Compute-host lifecycle, health checks, reply tracking, and respawn policy |
| tui_gateway/compute_host.py | Child-side isolated turn execution and frame exchange |
| ui-tui/…/gatewayClient.ts | TUI transport selection, reconnect behavior, heartbeat, and buffered event delivery |
| ui-tui/…/gatewayTypes.ts | Client-side response shapes for session, prompt, and gateway operations |