---
title: "Terminal frontend"
description: "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."
type: "living"
source: "apps/tui/README.md"
verified: "2026-11-14"
group: "Frontends"
---

> **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

```sh
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:

```sh
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.


