wehub-resource-sync
106 lines
4.1 KiB
Markdown
106 lines
4.1 KiB
Markdown
# TUI Frontend
|
|
|
|
OpenSquilla terminal chat has one stable default backend and one opt-in preview
|
|
backend:
|
|
|
|
| Backend or target | Status | How to use | Requirements |
|
|
| --- | --- | --- | --- |
|
|
| `native` | Stable default | `opensquilla chat` | Python package only |
|
|
| `opentui` | Preview opt-in | `OPENSQUILLA_TUI_BACKEND=opentui uv run opensquilla chat` | Source checkout, Bun, and local OpenTUI package dependencies |
|
|
| `live-opentui` | Manual harness target | Real-terminal harness only | tmux, OpenTUI deps, and live provider config |
|
|
|
|
`live-opentui` is not an `OPENSQUILLA_TUI_BACKEND` value. It is a guarded test
|
|
target that launches the OpenTUI preview path through the real CLI.
|
|
|
|
The TUI contracts are renderer-independent and built around two separate planes:
|
|
|
|
- **Streaming plane:** batches token deltas before writing to the terminal, so
|
|
long answers do not redraw the whole interface for every token.
|
|
- **Structured UI plane:** sends normalized TUI domain events to plugins. Plugin
|
|
snapshots can be rendered by capable TUI backends and by future renderers.
|
|
|
|
The stable default terminal chat is Python-native and does not require Bun,
|
|
npm, or OpenTUI node modules. OpenTUI is a source-checkout preview backend
|
|
selected explicitly with `OPENSQUILLA_TUI_BACKEND=opentui`.
|
|
|
|
## Plugin Slots
|
|
|
|
Plugins consume renderer-independent events and publish small snapshots through
|
|
named slots. Current slots include:
|
|
|
|
| Slot | Purpose |
|
|
| --- | --- |
|
|
| `router_hud` | Active-turn model-routing decision. |
|
|
| `status` | Compact status or queue notices. |
|
|
| `tool_activity` | Tool cards and tool summary history. |
|
|
| `usage` | Token, cache, and cost summary. |
|
|
| `inspector` | Optional detail panel state for selected items. |
|
|
|
|
The first plugin is `RouterHudPlugin`. It listens for
|
|
`router_decision` events and updates the bottom toolbar without changing router
|
|
selection behavior.
|
|
|
|
## Router HUD
|
|
|
|
When routing metadata is available, capable TUI backends can render a Router
|
|
HUD. In the current implementation, the OpenTUI footer is the primary preview
|
|
display for this HUD. The HUD is display-only: it consumes turn metadata and
|
|
does not change model selection.
|
|
|
|
The HUD can show:
|
|
|
|
- selected tier and model;
|
|
- baseline model;
|
|
- route source;
|
|
- confidence;
|
|
- estimated savings;
|
|
- fallback state;
|
|
- thinking mode;
|
|
- prompt policy;
|
|
- whether routing was applied;
|
|
- rollout phase.
|
|
|
|
`routing_applied=true` with a full rollout is shown as an active route.
|
|
`routing_applied=false` or an observe rollout is shown as observe-only. Fallback
|
|
routes use warning styling.
|
|
|
|
## Backend Selection
|
|
|
|
The default backend is stable Python-native terminal chat.
|
|
|
|
The internal backend selector reads `OPENSQUILLA_TUI_BACKEND`. Unset or empty
|
|
values select stable terminal chat. Set the variable to `opentui` only in a
|
|
source checkout when evaluating the preview backend. Legacy values fail before
|
|
chat launch with a clear unsupported-backend error.
|
|
|
|
```sh
|
|
bun install --frozen-lockfile --cwd=src/opensquilla/cli/tui/opentui/package
|
|
OPENSQUILLA_TUI_BACKEND=opentui uv run opensquilla chat
|
|
```
|
|
|
|
The preview backend is loaded from the OpenTUI package next to the running
|
|
source tree; it is not required for normal terminal chat.
|
|
|
|
Do not add parallel terminal/frontend implementations without fresh product
|
|
direction and replay plus real-terminal evidence.
|
|
|
|
## Replay Benchmarks
|
|
|
|
The replay harness measures the OpenTUI rendering path without a live provider:
|
|
|
|
```sh
|
|
uv run python scripts/bench_tui_replay.py --renderer opentui --fixture long-stream --summary-json .artifacts/tui/opentui-long-stream.json
|
|
uv run python scripts/bench_tui_replay.py --renderer opentui --fixture dense-history --summary-json .artifacts/tui/opentui-dense-history.json
|
|
```
|
|
|
|
Summary fields include `renderer`, `fixture`, `available`, `skip_reason`,
|
|
`event_count`, `text_chars`, `tool_count`, `router_decision_count`, `wall_ms`,
|
|
`flush_count`, `max_buffer_chars`, `coalescing_ratio`, `transcript_items`,
|
|
`visible_items`, `expanded_tools`, `projection_wall_ms`,
|
|
`rendered_text_matches`, `plugin_error_count`, and `errors`.
|
|
|
|
Use the OpenTUI results as preview backend evidence.
|
|
|
|
For terminal-level launch and rendering evidence, use the
|
|
[real-terminal TUI harness](../tui-real-terminal-harness.md).
|