teknium1
36773e0d78
Three TypeScript clients each declared their own copy of the tui_gateway wire
types and had drifted apart: apps/shared had a partial GatewayEventName union
with a `(string & {})` escape hatch, ui-tui/gatewayTypes.ts a 150-line
discriminated union, and apps/desktop an `RpcEvent<T>` that was field-for-field
the shared GatewayEvent with `type: string`. None matched the emitter:
message.complete lacked warning/status/error/recoverable/error_surface,
tool.start/tool.complete lacked args/result, SessionResumeResponse lacked
session_key/messages_omitted/hydrating/auto_continue/todo_state, three
different ModelOptionProvider shapes disagreed on fields, and all three unions
handled a `tool.progress` event that no Python emitter has ever produced.
Now:
* `apps/shared/src/gateway-events.ts` is the single home: payload interfaces
typed from the Python emitters (file::symbol cited per interface),
`BackendGatewayEventMap` (89 backend names) + `ClientLocalGatewayEventMap`
(5 TUI-synthetic transport events, clearly marked, excluded from the
contract) merged into `GatewayEventMap`; `GatewayEvent<K>` is discriminated
on `type` with `seq` typed. RPC shapes shared by 2+ surfaces live beside it
(ModelOptionProvider = union of every field hermes_cli/inventory.py sets,
incl. pricing_pending/free_tier_pending; SessionResumeResponse<Info>;
SessionListItem with resolved_id; Usage).
* `JsonRpcGatewayClient.on<K>` is keyed by event name; the gateway.ready
heartbeat/replay_epoch and per-frame `seq` reads are typed instead of cast.
* ui-tui and apps/desktop import the shared names; their local duplicates are
deleted (no re-export shims — importers are repointed; the desktop plugin
SDK barrel keeps its public `RpcEvent` name as an alias of GatewayEvent).
web/src repoints ModelOptionProvider/ModelOptionsResponse.
* `tool.progress` handling is removed from the TUI handler/turnController,
desktop event sets/tools handler, shared union, tests, and two docs
(`grep '"tool.progress"' tui_gateway/` = 0 hits; the `display.tool_progress`
config mode is unrelated and untouched).
* `message.complete.warning` (history-commit note from
prompt_turn.py::_complete_turn_payload) is typed and surfaced on both
surfaces through their existing notice paths (TUI pushActivity 'warn',
desktop notify kind 'warning').
Contract: `apps/shared/src/gateway-events.json` is the sorted list of
backend-emitted names. `tests/tui_gateway/test_gateway_event_contract.py`
collects names from the Python emitter side (emit-helper literals, the
`.request → .expire` table, change-watcher table, child delta mirror,
subagent relay, desktop_ui tool emitters, gateway.ready/setup.ready/
browser-controller frames) and asserts emitted == JSON in both directions.
`apps/shared/src/gateway-events.test.ts` asserts BACKEND_EVENT_NAMES (which
the map type is `satisfies`-checked against) == JSON. Sabotage-verified: a
fake JSON name fails both tests; a fake TS name fails tsc + vitest; a fake
Python `_emit("...")` fails pytest.
5.7 KiB
tui_gateway/ + ui-tui/ — the TUI and its JSON-RPC backend
Applies on top of the root AGENTS.md. The TUI fully replaces the classic prompt_toolkit CLI;
activate with hermes --tui or HERMES_TUI=1. tui_gateway is ALSO the backend the Desktop app
and the dashboard /chat talk to — changes here have three consumers.
Process model
hermes --tui
└─ Node (Ink) ──stdio JSON-RPC── Python (tui_gateway)
│ └─ AIAgent + tools + sessions
└─ renders transcript, composer, prompts, activity
TypeScript owns the screen. Python owns sessions, tools, model calls, and slash-command logic. Never move agent behaviour into the renderer.
Transport
Newline-delimited JSON-RPC over stdio: requests from Ink, events from Python. tui_gateway/server.py
is the facade with the method/event catalog; methods live in methods_*.py siblings (methods_config,
methods_complete, methods_browser, methods_bot_relay, ...), event publishing in
event_publisher.py / event_replay.py. Desktop reaches the same server over WebSocket via
apps/shared (JsonRpcGatewayClient). New RPC = a new methods_<topic>.py or an entry in an
existing topical sibling, registered in the table — no if method == ... chain (root shape rules).
New event = a new key in apps/shared/src/gateway-events.ts::GatewayEventMap + BACKEND_EVENT_NAMES
AND apps/shared/src/gateway-events.json; tests/tui_gateway/test_gateway_event_contract.py (emitter
side) and apps/shared/src/gateway-events.test.ts (type side) both fail when either drifts.
Key surfaces
| Surface | Ink component | Gateway method / event |
|---|---|---|
| Chat streaming | app.tsx + messageLine.tsx |
prompt.submit → message.delta / message.complete |
| Tool activity | thinking.tsx |
tool.start / tool.generating / tool.complete |
| Approvals | prompts.tsx |
approval.request → approval.respond |
| Clarify / sudo / secret | prompts.tsx, maskedPrompt.tsx |
clarify.respond, sudo.respond, secret.respond |
| Session picker | sessionPicker.tsx |
session.list / session.resume |
| Slash commands | local handler + fallthrough | slash.exec → _SlashWorker; command.dispatch |
| Completions | useCompletion hook |
complete.slash, complete.path |
| Theming | theme.ts + branding.tsx |
gateway.ready carries skin data |
| Plugin compat notice | — | plugins.compat_report (see plugins/AGENTS.md) |
Shared subagent snapshots
subagent.list({session_id}) returns {subagents, delegations} for the calling
transport's live session. Live child records are pinned to the exact session
record and transport. Child authority is resolved at RPC time against the owning session's
LIVE transport slot, so every authenticated reattach path (prompt.submit, queued drain,
resume, activate, viewer failover) carries it with no registry bookkeeping — never add a
per-record transport sync at an attach site; foreign or retired generations remain inaccessible. last_tool is the last started tool, not an in-flight
indicator. Async completion units are not agents and lack exact generation authority;
delegations remains an empty array for wire compatibility. No dispatch context,
results, callbacks, or routing keys are sent. Clients hydrate from this snapshot
on their existing poll and avoid updates when unchanged.
subagent.tail({session_id, subagent_id}) returns
{subagent_id, available, text, truncated}: the last 16 KiB of the live child's
existing transcript. Poll only the selected detail. Missing/finished/foreign
children return an unavailable empty snapshot; no client-supplied path is opened.
This is live-only, not persisted completion history. Invalid session/transport
returns error 4001. subagent.steer({session_id, subagent_id, text}) remains the
shared control: status: queued acknowledges acceptance, not delivery; final
boundary races are reported by the existing runtime as missed_steer.
subagent.interrupt({session_id, subagent_id}) requires the same exact live
session/transport/generation ownership, including for subtree members. Missing
RPC session authority is rejected; direct in-process interrupt_subagent(id)
retains its legacy unscoped contract.
Slash command flow
- Built-in client commands (
/help,/quit,/clear,/resume,/copy,/paste, ...) are handled locally inapp.tsx. - Everything else →
slash.exec, which runs in the persistent_SlashWorkersubprocess →command.dispatchfallback, which the gateway resolves into a skill / alias / exec directive (a skill command resolves to{type: "skill", message}and is submitted as a normal prompt).
commands.catalog (empty-query list) and complete.slash (typed-query completions) already include
built-ins, user quick_commands, AND skill-derived commands (scan_skill_commands() /
get_skill_commands()) — clients do not need a new RPC to see skills. The command definitions
themselves come from hermes_cli/commands.py (hermes_cli/AGENTS.md).
Dev commands
cd ui-tui
npm install # first time
npm run dev # watch mode (rebuilds hermes-ink + tsx --watch)
npm start # production
npm run build # full build (hermes-ink + tsc)
npm run typecheck # tsc --noEmit
npm run lint # eslint
npm run fmt # prettier
npm test # vitest
Python tests: tests/tui_gateway/ via scripts/run_tests.sh. TS tests: vitest in ui-tui. A
Python test that asserts about package.json / .ts sources will not run on a JS-only PR — keep
JS-side assertions in vitest (root testing rules). Root TypeScript style rules apply.
Related: web/AGENTS.md (dashboard embeds this TUI over a PTY), apps/desktop/AGENTS.md (own
renderer on the same backend).