Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / tui-gateway-rpc

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.submit starts or queues user work.
  • session.* creates, lists, resumes, activates, controls, and closes conversations.
  • complete.*, slash.*, and command.* support input and command actions.
  • config.*, model.*, tools.*, and reload.mcp update 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:

  1. Create a lazy session or resume a stored session.
  2. Build or reuse the agent when the session needs live work.
  3. Activate the session on the current client transport.
  4. Submit turns and receive events.
  5. Interrupt, close, or detach the session.
  6. 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

TriggerConsequenceGuard
Client and gateway use different RPC catalogsThe method is rejected as unknown or its fields fail validationKeep the shared method contract and both clients in sync
Replay ring no longer contains the requested rangeThe client can show a hole in the transcriptCheck truncated and refetch session state
Gateway restarts while a client holds sequence numbersOld event watermarks can hide new eventsCompare the replay epoch from gateway.ready and reset watermarks
Client disconnects during a turnStreaming stops for that socket and the session may become parkedReconnect and activate or resume the session before relying on live events
Client does not advertise server-request supportApproval or clarification cannot reach a user and the agent would otherwise waitFail fast when no attached client can answer
Compute host stops during an isolated turnThe turn returns an error or uses the configured fallback pathSupervisor heartbeat, identity checks, bounded respawn, and parent metadata mirror
WebSocket send queue overflows or stallsThe peer is closed and its session events stop on that connectionReconnect and use event replay plus session snapshots

Key files

FileWhy to read it
tui_gateway/server.pyGateway facade for transports, event emission, session routing, and shared runtime state
tui_gateway/transport.pyCommon transport contract and bounded event fanout behavior
tui_gateway/ws.pyWebSocket handshake, read loop, heartbeat path, ordered writes, and disconnect cleanup
tui_gateway/rpc_dispatch.pyRPC validation, handler selection, and long-work dispatch
tui_gateway/server_requests.pyBackend-to-client questions and response settlement
tui_gateway/event_replay.pyPer-session event sequence and reconnect replay rules
tui_gateway/methods_prompt.pyTurn admission, busy-session behavior, and prompt submission
tui_gateway/methods_session.pySession create, resume, activate, control, and event replay RPCs
tui_gateway/compute_host_bridge.pyParent-side turn, metadata, control, and user-question relay
tui_gateway/host_supervisor.pyCompute-host lifecycle, health checks, reply tracking, and respawn policy
tui_gateway/compute_host.pyChild-side isolated turn execution and frame exchange
ui-tui/…/gatewayClient.tsTUI transport selection, reconnect behavior, heartbeat, and buffered event delivery
ui-tui/…/gatewayTypes.tsClient-side response shapes for session, prompt, and gateway operations