4.4 KiB
Grid-agent operator TUI
The operator TUI is a pure-Rust, cross-platform Ratatui dashboard over the versioned control plane. Embedded and split modes use the same reducer, snapshots, widgets, commands, and authenticated control requests; the UI never reads private runtime state. Standalone preferences uses the same Ratatui form.
Run an embedded UI with a live-grid integrated configuration:
cargo run --locked -p metacrate-grid-agent --features live-grid -- \
--config config/grid-agent.integrated.example.yml --tui
Run a separate UI against a loopback split service:
cargo run --locked -p metacrate-grid-agent -- \
--config config/grid-agent.split.example.yml --tui-client
The split client reads its operator capability from the ACL-restricted
config.yml. It never displays or copies that value. Remote
TLS clients must embed TuiTransport with their explicitly configured trust
roots; the command-line client intentionally accepts loopback TCP only.
Open preferences before a service is configured with
metacrate-grid-agent --preferences; the same panel is available from the live
TUI. It edits the endpoint, optional model, grid identity, hidden credentials,
mode, and privileged UUID list while preserving advanced YAML settings. Use
Up/Down to select, Enter to edit/commit, w to save, and Esc to cancel. Changes
to connection or authorization settings apply after restart. A one-time
--import-env /path/to/.env migrates legacy GRID_* and OPENAPI_* values.
The Overview dashboard shows readiness, region/pose, behavior, build and visual work, approvals, and recent failures. Queues & budgets shows real queue and rate-limit gauges, active work, outcome counts, dropped events, aggregate latency, and a bounded 120-refresh history. Sessions, roaming schedules, approvals, durable memory, timeline/audit, errors, diagnostics, health, and preferences retain focused tables or panels and contextual detail. Missing backend data is marked unavailable rather than estimated.
The Memory panel is operator-only. Enter loads the selected agent or record,
g changes the explicitly mapped avatar agent, n/b page, k cycles record
kind, i cycles pinned state, o changes sort, and d confirms a durable
tombstone. / searches content; source:value, from:unix-seconds, and
to:unix-seconds tokens set provenance and creation-time filters. Empty search
text browses all non-tombstoned records. Observer clients receive aggregate
agent/record health only and never memory identity, preview, or content.
Use Tab/Shift-Tab or Left/Right to change panels and Up/Down to select rows.
/ searches event, audit, correlation, time, duration, result, and reason data;
Enter applies the search and Esc clears it. r refreshes; p/u pause or
resume; f reconnects the grid; a/d approve or deny the selected approval;
x cancels the newest visible action; e expires the selected session; t
toggles the selected roaming schedule; s requests shutdown; and q or
Ctrl-C exits. Mutations other than pause/resume require confirmation, with
shutdown marked high risk. Exiting or crashing a split TUI does not stop the
service.
Ratatui's Crossterm backend provides buffered/diff rendering without clearing
the full screen on every frame. Layouts respond to resize and collapse to a
compact status view on very small terminals; focus and failure markers remain
visible without color when NO_COLOR is set or TERM=dumb. Input, refresh
work, results, event history, errors, and performance history are all bounded.
Slow snapshots run outside the input reducer, and refresh ticks are dropped
when the bounded worker queue is full. The terminal guard restores raw mode,
cursor visibility, and the alternate screen on success, error, Ctrl-C, or
panic unwinding.
Diagnostic panels show only explicitly captured redacted envelopes. Memory content appears only in the operator-only Memory detail panel; it is never copied into diagnostics, audit events, or observer responses. API keys, grid passwords, operator tokens, capability URLs, and model reasoning have no TUI representation.
Focused verification:
cargo test --locked -p metacrate-grid-agent tui --lib
cargo test --locked -p metacrate-grid-agent --test preferences_config
cargo test --locked -p metacrate-grid-agent --test dependency_policy
cargo clippy --locked -p metacrate-grid-agent --all-targets --features live-grid -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --locked -p metacrate-grid-agent --no-deps