Terminal frontend
The vulpine terminal skin on pi-tui: a client of the gateway over the Client Core bound as vigil / ui (text only), with the shared voice rows, the transcript and the brain's ask-back dialogs answered as text utterances; tested headless against a loopback fake gateway.
Living doc, checked against the code 2026-11-14
tui — the vulpine terminal skin
The terminal frontend: a text-only client of the gateway, as Vulpine.app and the browser are. The Client Core
(packages/voice-client) runs the protocol-5 hello, the owner handshake (ADR 0024) and the session. The TUI draws what
comes back with pi-tui (@earendil-works/pi-tui 1.4.0, the version Pi 1.4.0 ships). It works from any SSH or Mosh
terminal, a phone’s included.
It binds as kind vigil, role ui, no audio (ADR 0033 §2): it never arms, never owns a turn, never captures and
never plays. The gateway admits a ui hello that declares no PCM as a text-only client (binary_audio: false). It
binds no speech output for the session, sends no PCM, refuses PCM from it (audio_not_declared) and answers its typed
turns with text frames.
What it shows
- The voice rows:
describeVoiceChromefrompackages/vulpine-voice-ui-state, unchanged (session, presentation, led, input, output, effective, reduced-motion, error, ended, capabilities). A text-only client’s capabilities row readsnone. - The binding rows: the link, the bound persona and model, and the gateway’s own
stateframe (presence, room, a brain tool in flight, chips, mood). - The avatar slot to the left of the rows: an
AvatarSlot { render(state): string[] }, given the presentation and the eikon lifecycle signal it maps to (state.idle…state.error). The default is a plain-text fox. - The transcript, read as Vigil reads it: a final
user_transcriptis a “You” line,turn_startedopens the speaker’s line,assistant_deltagrows it,turn_completedsettles it. A typed turn goes out with its own id (tui-<n>) and shows at once as a pending echo. The gateway echoes the id on the turn’s transcript, which replaces the echo in place, so each typed line shows once. With no transcript the echo stays. - The brain’s ask-back dialogs (
brain_ui_request: select, confirm, input). The TUI answers by sending the words as a text utterance, which the gateway judges as it judges a spoken answer (ws/ui_answer.rs): yes or no for a confirm, the option’s own text for a select, the typed value for an input, “cancel” on escape (a confirm declines with “no”).brain_ui_answeredcloses the dialog and the transcript says how it settled.
The Core, as it is
The Core takes the TUI’s kind, role and audio: null as options and publishes the brain’s dialog frames as
brain_ui_request / brain_ui_answered events, so the TUI has no seam of its own into the socket.
The TUI sees its own session’s turns and the dialogs they raise. With --observe it also follows another live
session read only: bare --observe follows the sole live session that is not a ui (the Glyph’s), and
--observe=<session id> the one the Admin row names. The gateway forwards that session’s transcript, reply text, turn
ends and dialogs as observed events, drawn as marked lines (◦ You, ◦ Fox). Its dialogs show as system lines; what
the TUI types goes to its own session, and /answer (below) answers the observed one. observe_ended says the session
went, and a reconnect asks again. The binding rows show observing <session id>, and the Admin’s session row reads
codec ui · text only · observing <id>. A refusal (observe_ambiguous with two voice sessions, observe_no_session
with none) is the error line.
Run and test
just apps::tui --observe # the relay route (127.0.0.1:8780); ctrl+c quits
bun apps/tui/src/main.ts --gateway ws://127.0.0.1:8780 # or VULPINE_TUI_GATEWAY
bun run --cwd apps/tui typecheck
bun test apps/tui/tests
just apps::tui is the command for a phone’s SSH or Mosh session. With no --gateway it dials the relay route: this
machine’s loopback :8780, which just apps::glyph-relay start carries to the gateway host (on the gateway host, the
gateway’s own port). It says so when no relay listens. --agent (default operator), --loadout (default: the gateway’s
default) and --persona (default: the gateway’s default persona) choose the bind. There is no token: admission is
the owner handshake. The owner receipt lives for the process, so a reconnect resumes the same owner and a restart is a
fresh one.
Limits
- Text only: no microphone, no playback.
- An input dialog’s value that starts with a cancel word (“stop …”, “cancel …”) is read by the gateway as a cancel, as a spoken one is.
- A dialog method other than select, confirm or input is shown, not answered.
/answerneeds the observed session’s owner file: a Rust shell that persists its owner, or the Glyph (its Owner export). Vigil keeps its receipt in its tab and exports none.
Answering the observed session’s dialog
A dialog open on the observed session can be answered from here as that session’s owner. The gateway checks the owner on the answer: the owner must be attached, its token must match, and it must be the session’s voice owner and the dialog’s authority. So the TUI reads the observed session’s own receipt from an owner file:
just apps::tui --observe --observe-owner ~/.local/state/vulpine/clients/foxline-glyph/owner.json
- The file is the Rust
OwnerStoreformat (crates/vulpine_client):{"version":1,"gateway_url":…,"owner":{…}}, mode 0600 in a 0700 folder. The Glyph writes its own at that path after each admitted bind (export_owner_receipt). A Rust shell withpersist_owner()writesclients/<client>/owner.json. - What the reader refuses: a symlink, a file swapped between the look and the open, anything but a regular file of
at most 4096 bytes, any mode bit for the group or others, JSON with other members or an owner not in the wire’s
shape, and a receipt another gateway admitted (
ws://host:8780andws://host:8780/are one gateway). A refused file stops the TUI before it starts, with one line on stderr and exit 64. The resume token is never printed. /answer <text>answers the dialog open on the observed session through the Core’sanswerObserved(theobserved_answerframe). The gateway’s judge reads the text as for a typed answer: yes or no, an option’s text, a value. The TUI refuses with one System line, sending nothing, when there is no owner file, it is not bound yet, the gateway’s hello does not offerobserved_answer, no observed dialog is open, there are no words, or there are more than 1000 characters (counted as the gateway counts them, not in UTF-16 units). A sent answer shows as◦ answer sent (<method>): <text>; the gateway settles it as the observedbrain_ui_answered(◦ confirm: confirmed by observer). A refusal arrives as the error line (observe_answer_not_owner, …).- The rows. The title reads
· observing · answeringwhen an owner file was read. The binding rows showobserved ask <method>: <title>while a dialog is open, and the observed dialog’s system line lists a select’s or confirm’s options.