Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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: describeVoiceChrome from packages/vulpine-voice-ui-state, unchanged (session, presentation, led, input, output, effective, reduced-motion, error, ended, capabilities). A text-only client’s capabilities row reads none.
  • The binding rows: the link, the bound persona and model, and the gateway’s own state frame (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_transcript is a “You” line, turn_started opens the speaker’s line, assistant_delta grows it, turn_completed settles 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_answered closes 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.
  • /answer needs 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 OwnerStore format (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 with persist_owner() writes clients/<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:8780 and ws://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’s answerObserved (the observed_answer frame). 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 offer observed_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 observed brain_ui_answered (◦ confirm: confirmed by observer). A refusal arrives as the error line (observe_answer_not_owner, …).
  • The rows. The title reads · observing · answering when an owner file was read. The binding rows show observed ask <method>: <title> while a dialog is open, and the observed dialog’s system line lists a select’s or confirm’s options.

Was this page helpful?