# Native OpenTUI terminal frontend

Every interactive terminal surface uses `@opentui/core@0.6.6`. Node owns the
agent and services; a packaged Bun 1.3.14 process owns OpenTUI, raw terminal
input, focus, layout, scrolling, selection and painting. The October 16
[instrument interface](instrument-tui.md) replaces the former Earth palette with
terminal defaults and introduces lightweight geometry and collapsible telemetry.
Header actions, agent tabs, history, pinned tasks, expandable input, enhancement
controls and metrics retain their functional structure.
The implementation uses OpenTUI's [imperative native renderables](https://github.com/anomalyco/opentui/tree/main/packages/core).

## Component contract

`native/protocol.ts` carries semantic documents and actions. The host sends
stable-ID content patches, coalesces updates and permits one unacknowledged
frame. Missing acknowledgements fail visibly and restore terminal ownership.
Keyboard, paste, pointer and capability bytes go directly to OpenTUI. The Node
input facade receives editor changes, submissions and backend shortcuts.

The worker builds native Box, Text, Markdown, Code, ScrollBox, Textarea,
Select, TabSelect, Image and EmbeddedTerminal renderables. Menus, nested
prompts, secret input, onboarding, memory maps, camera controls, progress,
agent command center and Neovim share this component tree and focus model.
External interactive programs use an explicit suspended terminal handoff.
Machine-readable and piped output remain plain streams.

There is no terminal-cell screen compositor, physical cursor painter, manual
wrapped-row index, mouse escape parser or second raw keyboard parser in the
application. Semantic text preserves attributes and links while following the
operator's terminal colors; cursor/screen controls are discarded. Persisted tool data and live inference,
shell, trajectory, action-tree, media and sub-agent data become native cards.
Session restoration preserves semantic documents and old stored transcripts.

## October 15 verification

- `pnpm --filter omnius exec vitest run tests/native-components.test.ts` runs
  actual OpenTUI under packaged Bun, including long-history scrolling and
  concurrent editing, Unicode paste, independent stack/tree scroll positions,
  native menus, secret masking, cards, themes, media controls, image fallback,
  footer actions, and an embedded terminal.
- `node scripts/benchmark-tui-history.mjs --output FILE` records those native
  scenario timings. They include native layout/render/input work; they are
  not a claim about per-keystroke latency or a speedup over the old renderer.
- `node scripts/test-tui-production-terminal.mjs --report FILE --transcript FILE`
  launches the actual CLI in a real PTY, observes the screen independently,
  uses isolated settings/data, permits local metadata and blocks all inference.
  Add `--entry /path/to/installed/omnius/dist/index.js` to test a clean tarball
  installation using observation of the actual worker IPC.
- `node scripts/test-tui-production-local.mjs --preflight FILE` validates an
  already-resident, verified GPU/model scope, then exercises the actual CLI's
  local answer, tool execution, streaming and Stop paths. Its transport observer
  records request scope and test markers without replacing the backend.

Earlier `native-tui-*-20261015.json` evidence describes the previous row adapter
and a synthetic fixture. Those measurements are historical and do not validate
this complete semantic frontend. Current results are recorded separately.

The final targeted run passed 484 CLI tests across 63 files and 189 orchestrator
tests across five files, including the mandatory daemon web transport tests.
All 15 actual native component scenarios and six metadata-only production PTY
checks passed. A separate production CLI run passed eight checks with the real
local model: an answer, a file-read tool round trip, streaming with 200 wheel
events, continued editing, resize, Stop, editable recovery and clean shutdown.
Input painted in 26 ms during that streaming wheel burst. This is one observed
live measurement, not a general latency percentile.

Current receipts:

- [Targeted tests and broader-suite limits](evidence/native-tui-targeted-verification-20261015.json)
- [Actual native component scenarios](evidence/native-tui-semantic-components-20261015.json)
- [Production terminal checks](evidence/native-tui-production-terminal-20261015.json)
- [Verified GPU 0 and actual local-model CLI checks](evidence/native-tui-local-inference-repair-20261015.json)
- [Clean package artifact checks](evidence/native-tui-package-artifact-20261015.json)
- [Installed package terminal and runtime checks](evidence/native-tui-package-install-20261015.json)
- [Independent committed-source build and 484 tests](evidence/native-tui-committed-scope-20261015.json)

The broader CLI suite did not finish: its interrupted run observed 257 failures
in Telegram tests. Those failures were not all investigated or established as
pre-existing. A full-suite pass is not claimed.

## Local inference repair

The broker's explicit operator hold caused local requests to fail and automatic
fallback to select a remote route. Omnius now retains a sanitized local failure
reason beside the effective route and clears it after local recovery. GPU
selection initializes consistently for interactive, single-task and daemon
entry points, and native Ollama requests retain the exact GPU allowlist.

API model routing preserves organization namespaces such as `robit/`; it strips
only known routing prefixes or resolves an advertised route. Global config,
settings, default database and terminal history honor `OMNIUS_CONFIG_HOME`.
CLI test setup assigns an isolated configuration home so tests cannot change
the operator's live routing settings.

The operator explicitly approved normal local inference on GPU 0. The supported
health-checked resume released the hold; actual server and runner placement were
verified on GPU 0 before generation. The hold remains released after successful
testing. Other GPU workloads and host device selections are preserved.
The live run made 12 local physical requests: 11 returned HTTP 200 and a repeated
helper rerank operation returned a nonfatal HTTP 409. All user-facing checks
passed. Tool-bearing requests were observed with `think: false` without a forced
environment override.

## Packaging

The builder emits `dist/tui/native/worker.js` separately and keeps exact
OpenTUI/Bun runtime dependencies. It rebuilds every workspace package before
bundling. Clean builds remove deleted legacy renderer modules from distributable
outputs. Tests and tarball installation must disable unrelated postinstall
daemon/service startup while validating the native runtime assets.
The final tarball passed all six production terminal checks in a fresh isolated
installation. Node CLI help, a real SQLite round trip, packaged Bun/OpenTUI and
the separately bundled native worker were also verified. The tarball contains
the README and injected README metadata, with no tests, coverage, caches,
sourcemaps, build caches or deleted legacy renderer modules.
