Rebuild the grid-agent operator TUI with Ratatui dashboards #140

New Issue

hugo · 2026-08-23T10:47:19Z

hugo commented

2026-08-23 10:47:19 +00:00

Goal

Replace the current hand-built, line-oriented grid-agent terminal renderer with a responsive Ratatui operator dashboard. The result should make the agent's major operational areas inspectable from one keyboard-driven interface in both integrated (--tui) and split-client (--tui-client) modes.

Use btop as inspiration for information density and live operational feedback: compact panels, clear focus, gauges, bounded histories, and immediately visible pressure or failure states. This is not a request to copy btop's layout. The agent is still evolving, so this issue defines the information architecture and behavioral guarantees while leaving exact panel placement adaptable to the data that becomes available.

Current code anchors

crates/metacrate-grid-agent/src/tui.rs already owns OperatorTui, OperatorScreen, the transport-neutral reducer/snapshot model, terminal lifecycle, and the current manual String renderer. Preserve the useful state and transport boundaries; replace manual layout, truncation, clearing, and printing with Ratatui widgets and a Crossterm backend.
OperatorSnapshot already gathers health, runtime state, metrics, sessions, schedules, approvals, audit data, structured events, gap counts, and sequence state through the control plane. The TUI must consume those public views rather than reach into private runtime state.
PreferencesPanel already loads, edits, validates, masks, and saves mode, LLM, grid, and privileged-user settings. Preferences must become a first-class Ratatui form without weakening secret handling or the standalone --preferences path.
observability.rs::MetricsSnapshot already exposes active sessions/tasks, queue depth/capacity, inference and tool latency aggregates, outcome counters, rate-limit use, recorded events, and dropped-event counts.
observability.rs::StructuredEvent already exposes timestamp, severity, component, family, correlation IDs, duration, retries, result/reason codes, redaction flags, and bounded fields.
control_plane.rs::RuntimeView already exposes connection/readiness, region and pose, behavior mode, control-queue pressure, budgets, active build progress/orphans, and visual-capture progress.

Required experience

Overview

Present connection/readiness, region/pose, behavior mode, active sessions/tasks, current build or visual work, recent failures, and pending approvals as a compact dashboard.
Make degraded, disconnected, paused, saturated, dropped-event, and failed states visually distinct without relying on color alone.

Queues and performance

Provide btop-inspired gauges and bounded trend views for queue use, rate-limit use, active work, event throughput/drop counts, inference latency, and tool latency.
Show current, average where derivable, and maximum latency without inventing precision that the current aggregate metrics do not contain.
Keep a bounded in-memory history of sampled snapshots for sparklines/charts; it must not grow for the lifetime of the process or add load to the agent.
Measure and expose useful TUI-local responsiveness such as frame/render duration or refresh cadence. Add new service/rendering telemetry only when it has a concrete producer and a stable control-plane representation.

Operational areas

Retain navigable views for overview, queues/budgets, sessions, roaming schedules, approvals, event timeline, health/metrics, recent errors, diagnostics, and preferences.
Make tables selectable and scrollable, preserve focus/selection across refreshes when the selected identity still exists, and provide a contextual detail pane where the public data supports it.
Support searchable/filterable structured events and audit data, including severity, component, family, avatar/session/action correlation, time, duration, result, and reason. Event gaps and dropped counts must remain prominent.
Surface build transaction/progress/orphans and visual-capture/progress as real operational state, not only as flattened overview text.
Keep destructive or security-sensitive actions behind the existing risk-appropriate confirmations and audit/control-plane paths.

Preferences

Implement focused field navigation, edit/commit/cancel/save feedback, validation errors, scrolling, and small-terminal behavior with Ratatui widgets.
API keys and grid passwords remain masked; operator tokens, capability URLs, hidden reasoning, and other secrets must never be rendered, copied, logged, or included in test snapshots.
Preserve configuration semantics in AgentPreferences; do not create a second settings model or storage format for the TUI.

Layout and interaction

Use Ratatui with Crossterm so the implementation remains native and cross-platform on Linux, Windows, and macOS.
Support keyboard-only operation, an always-discoverable help/status area, clear focus indication, resize, Unicode, monochrome/color-disabled terminals, and useful degradation on small terminals.
Avoid flicker and unconditional full-screen clearing on every refresh; use Ratatui's buffered/diff rendering and redraw only when input, data, resize, or the configured refresh cadence requires it.
Slow control-plane responses and high-rate event streams must not block input. Snapshot/event history, UI channels, and retained table data remain bounded.
Preserve clean terminal restoration after normal exit, errors, Ctrl-C, and unwinding.

The detailed memory browser remains owned by #137 and the conversation/session browser by #138. This issue provides the Ratatui navigation, reusable table/detail interaction, and integration points; it must not duplicate their domain APIs or storage work.
Panels whose backend data is not stable yet should render a clear unavailable/empty state. Do not fabricate values or couple the UI to private implementation details.
Exact colors, borders, panel ratios, and final placement may evolve as new agent capabilities land. Accessibility, stable navigation, boundedness, and the public control-plane boundary are not optional.

Non-goals

Changing agent behavior, the wgpu world renderer, Mentra storage, or grid protocols solely to decorate the dashboard.
Reimplementing Ratatui widgets or maintaining the existing manual string-layout engine in parallel.
Adding OS-specific terminal code without equivalent Linux and Windows behavior.

Acceptance criteria

metacrate-grid-agent uses Ratatui with Crossterm for terminal rendering; the manual full-screen String renderer/layout path is removed rather than kept as a second UI.
Integrated, split-client, and standalone preferences modes use the same Ratatui interaction and rendering foundations while preserving their existing transport/configuration boundaries.
Every current operator area is reachable and usable with keyboard-only navigation, including actionable preferences with masked secrets and validation feedback.
A btop-inspired queues/performance view displays queue and rate-limit pressure, active work, inference/tool latency, outcomes, dropped events, and bounded recent trends from real data.
Overview and detail views expose current runtime, build, visual-capture, approval, error, health, and event information without private-runtime access.
Resize, very small terminals, Unicode, monochrome mode, disconnected/unavailable data, slow refreshes, and terminal restoration behave safely on supported platforms.
Ratatui TestBackend or equivalent deterministic tests cover layout and interaction for every screen, focus/navigation, refresh stability, preferences including secret redaction, confirmation dialogs, and representative small/large terminal sizes.
Tests prove histories and queues stay bounded and that input remains responsive while refreshes or event traffic are delayed.
Gitea Actions validation remains on ubuntu-latest; portable Rust code paths are kept compatible with Linux and Windows, with no macOS-only implementation.

Relationship to existing work

This supersedes the presentation layer delivered by closed issue #128 while retaining its control-plane, security, responsiveness, and integrated/split-mode requirements. It complements rather than replaces #137 and #138.

## Goal Replace the current hand-built, line-oriented grid-agent terminal renderer with a responsive Ratatui operator dashboard. The result should make the agent's major operational areas inspectable from one keyboard-driven interface in both integrated (`--tui`) and split-client (`--tui-client`) modes. Use btop as inspiration for information density and live operational feedback: compact panels, clear focus, gauges, bounded histories, and immediately visible pressure or failure states. This is not a request to copy btop's layout. The agent is still evolving, so this issue defines the information architecture and behavioral guarantees while leaving exact panel placement adaptable to the data that becomes available. ## Current code anchors - `crates/metacrate-grid-agent/src/tui.rs` already owns `OperatorTui`, `OperatorScreen`, the transport-neutral reducer/snapshot model, terminal lifecycle, and the current manual `String` renderer. Preserve the useful state and transport boundaries; replace manual layout, truncation, clearing, and printing with Ratatui widgets and a Crossterm backend. - `OperatorSnapshot` already gathers health, runtime state, metrics, sessions, schedules, approvals, audit data, structured events, gap counts, and sequence state through the control plane. The TUI must consume those public views rather than reach into private runtime state. - `PreferencesPanel` already loads, edits, validates, masks, and saves mode, LLM, grid, and privileged-user settings. Preferences must become a first-class Ratatui form without weakening secret handling or the standalone `--preferences` path. - `observability.rs::MetricsSnapshot` already exposes active sessions/tasks, queue depth/capacity, inference and tool latency aggregates, outcome counters, rate-limit use, recorded events, and dropped-event counts. - `observability.rs::StructuredEvent` already exposes timestamp, severity, component, family, correlation IDs, duration, retries, result/reason codes, redaction flags, and bounded fields. - `control_plane.rs::RuntimeView` already exposes connection/readiness, region and pose, behavior mode, control-queue pressure, budgets, active build progress/orphans, and visual-capture progress. ## Required experience ### Overview - Present connection/readiness, region/pose, behavior mode, active sessions/tasks, current build or visual work, recent failures, and pending approvals as a compact dashboard. - Make degraded, disconnected, paused, saturated, dropped-event, and failed states visually distinct without relying on color alone. ### Queues and performance - Provide btop-inspired gauges and bounded trend views for queue use, rate-limit use, active work, event throughput/drop counts, inference latency, and tool latency. - Show current, average where derivable, and maximum latency without inventing precision that the current aggregate metrics do not contain. - Keep a bounded in-memory history of sampled snapshots for sparklines/charts; it must not grow for the lifetime of the process or add load to the agent. - Measure and expose useful TUI-local responsiveness such as frame/render duration or refresh cadence. Add new service/rendering telemetry only when it has a concrete producer and a stable control-plane representation. ### Operational areas - Retain navigable views for overview, queues/budgets, sessions, roaming schedules, approvals, event timeline, health/metrics, recent errors, diagnostics, and preferences. - Make tables selectable and scrollable, preserve focus/selection across refreshes when the selected identity still exists, and provide a contextual detail pane where the public data supports it. - Support searchable/filterable structured events and audit data, including severity, component, family, avatar/session/action correlation, time, duration, result, and reason. Event gaps and dropped counts must remain prominent. - Surface build transaction/progress/orphans and visual-capture/progress as real operational state, not only as flattened overview text. - Keep destructive or security-sensitive actions behind the existing risk-appropriate confirmations and audit/control-plane paths. ### Preferences - Implement focused field navigation, edit/commit/cancel/save feedback, validation errors, scrolling, and small-terminal behavior with Ratatui widgets. - API keys and grid passwords remain masked; operator tokens, capability URLs, hidden reasoning, and other secrets must never be rendered, copied, logged, or included in test snapshots. - Preserve configuration semantics in `AgentPreferences`; do not create a second settings model or storage format for the TUI. ## Layout and interaction - Use Ratatui with Crossterm so the implementation remains native and cross-platform on Linux, Windows, and macOS. - Support keyboard-only operation, an always-discoverable help/status area, clear focus indication, resize, Unicode, monochrome/color-disabled terminals, and useful degradation on small terminals. - Avoid flicker and unconditional full-screen clearing on every refresh; use Ratatui's buffered/diff rendering and redraw only when input, data, resize, or the configured refresh cadence requires it. - Slow control-plane responses and high-rate event streams must not block input. Snapshot/event history, UI channels, and retained table data remain bounded. - Preserve clean terminal restoration after normal exit, errors, Ctrl-C, and unwinding. ## Evolving areas and related issues - The detailed memory browser remains owned by #137 and the conversation/session browser by #138. This issue provides the Ratatui navigation, reusable table/detail interaction, and integration points; it must not duplicate their domain APIs or storage work. - Panels whose backend data is not stable yet should render a clear unavailable/empty state. Do not fabricate values or couple the UI to private implementation details. - Exact colors, borders, panel ratios, and final placement may evolve as new agent capabilities land. Accessibility, stable navigation, boundedness, and the public control-plane boundary are not optional. ## Non-goals - Changing agent behavior, the wgpu world renderer, Mentra storage, or grid protocols solely to decorate the dashboard. - Reimplementing Ratatui widgets or maintaining the existing manual string-layout engine in parallel. - Adding OS-specific terminal code without equivalent Linux and Windows behavior. ## Acceptance criteria - [ ] `metacrate-grid-agent` uses Ratatui with Crossterm for terminal rendering; the manual full-screen `String` renderer/layout path is removed rather than kept as a second UI. - [ ] Integrated, split-client, and standalone preferences modes use the same Ratatui interaction and rendering foundations while preserving their existing transport/configuration boundaries. - [ ] Every current operator area is reachable and usable with keyboard-only navigation, including actionable preferences with masked secrets and validation feedback. - [ ] A btop-inspired queues/performance view displays queue and rate-limit pressure, active work, inference/tool latency, outcomes, dropped events, and bounded recent trends from real data. - [ ] Overview and detail views expose current runtime, build, visual-capture, approval, error, health, and event information without private-runtime access. - [ ] Resize, very small terminals, Unicode, monochrome mode, disconnected/unavailable data, slow refreshes, and terminal restoration behave safely on supported platforms. - [ ] Ratatui `TestBackend` or equivalent deterministic tests cover layout and interaction for every screen, focus/navigation, refresh stability, preferences including secret redaction, confirmation dialogs, and representative small/large terminal sizes. - [ ] Tests prove histories and queues stay bounded and that input remains responsive while refreshes or event traffic are delayed. - [ ] Gitea Actions validation remains on `ubuntu-latest`; portable Rust code paths are kept compatible with Linux and Windows, with no macOS-only implementation. ## Relationship to existing work This supersedes the presentation layer delivered by closed issue #128 while retaining its control-plane, security, responsiveness, and integrated/split-mode requirements. It complements rather than replaces #137 and #138.

hugo added this to the 14 - metacrate grid agent milestone 2026-08-23 10:47:19 +00:00

hugo added the enhancement critical labels 2026-08-23 10:47:19 +00:00

hugo commented

2026-08-23 16:40:58 +00:00

Implemented and pushed as 95cca3e.

Completion review against the issue:

Replaced the manual line/String/full-screen-clear renderer with Ratatui widgets over the Crossterm backend; TestBackend is used only for deterministic rendering tests.
Integrated --tui, split --tui-client, and standalone --preferences now share the same Ratatui renderer and preference form while retaining their existing transports and AgentPreferences storage.
All ten operator areas are keyboard reachable. Overview exposes readiness, region/pose, behavior, sessions/tasks, approvals, failures, build/orphan state, and visual-capture state from public snapshots.
Queues & budgets provides real work/control/rate gauges; 120-sample bounded trends for queue, rate, active work, throughput, inference/tool average latency, and drops; aggregate average/max/sample latency without fabricating a current value; all inference/tool/policy outcomes; and frame/refresh/cadence telemetry.
Sessions, schedules, approvals, timeline/audit, and preferences have focused selectable/scrolling rows. Stable identities survive reordered refresh data, selected-row actions use that selection, and contextual details expose only public/redacted fields.
Timeline/audit search covers severity, component, family/action, avatar/session/action/request correlation, time, duration, retry, result, reason, principal, outcome, and authorization.
Slow refresh/control I/O runs in a bounded worker outside the input reducer; event refreshes are deduplicated and timeline/error/history/channel storage remains bounded.
Small terminals collapse to a useful status view. Unicode, resize, monochrome focus/failure markers, unavailable/disconnected states, confirmation dialogs, and terminal restoration on initialization errors, normal errors, Ctrl-C, and unwinding are covered by implementation and deterministic tests.
API keys and grid passwords remain masked; operator tokens, capability URLs, prompt/response content, hidden reasoning, and diagnostic content are never rendered.
Updated docs/grid-agent-tui.md to document the dashboard, selected-row controls, search, bounds, and security behavior. No Gitea workflow or OS-specific implementation was added.

Focused gates:

cargo clippy -p metacrate-grid-agent --all-targets --all-features -- -D warnings: pass
Ratatui/reducer tests: 10 pass (every screen at small/large sizes, mono/Unicode, focus/scroll/identity, refresh stability, confirmation, filtering, bounded history, delayed refresh responsiveness)
Control-plane conformance: 11 pass across in-process and loopback TCP
Preferences/security: 3 pass
Dependency/cross-platform policy: 7 pass
Acceptance evidence: 2 pass
Rustdoc with -D warnings: pass

A Windows target probe reached the existing aws-lc-sys build dependency and stopped because this Linux host does not have x86_64-w64-mingw32-gcc installed; it did not report a TUI/Ratatui/Crossterm source error. Repository policy requires ubuntu-latest workflows, which remain unchanged.

The pre-existing repository-wide codegen license and compatibility parity metadata failures are unrelated to this presentation-only issue and were left untouched as required.

Implemented and pushed as 95cca3e. Completion review against the issue: - Replaced the manual line/String/full-screen-clear renderer with Ratatui widgets over the Crossterm backend; TestBackend is used only for deterministic rendering tests. - Integrated --tui, split --tui-client, and standalone --preferences now share the same Ratatui renderer and preference form while retaining their existing transports and AgentPreferences storage. - All ten operator areas are keyboard reachable. Overview exposes readiness, region/pose, behavior, sessions/tasks, approvals, failures, build/orphan state, and visual-capture state from public snapshots. - Queues & budgets provides real work/control/rate gauges; 120-sample bounded trends for queue, rate, active work, throughput, inference/tool average latency, and drops; aggregate average/max/sample latency without fabricating a current value; all inference/tool/policy outcomes; and frame/refresh/cadence telemetry. - Sessions, schedules, approvals, timeline/audit, and preferences have focused selectable/scrolling rows. Stable identities survive reordered refresh data, selected-row actions use that selection, and contextual details expose only public/redacted fields. - Timeline/audit search covers severity, component, family/action, avatar/session/action/request correlation, time, duration, retry, result, reason, principal, outcome, and authorization. - Slow refresh/control I/O runs in a bounded worker outside the input reducer; event refreshes are deduplicated and timeline/error/history/channel storage remains bounded. - Small terminals collapse to a useful status view. Unicode, resize, monochrome focus/failure markers, unavailable/disconnected states, confirmation dialogs, and terminal restoration on initialization errors, normal errors, Ctrl-C, and unwinding are covered by implementation and deterministic tests. - API keys and grid passwords remain masked; operator tokens, capability URLs, prompt/response content, hidden reasoning, and diagnostic content are never rendered. - Updated docs/grid-agent-tui.md to document the dashboard, selected-row controls, search, bounds, and security behavior. No Gitea workflow or OS-specific implementation was added. Focused gates: - cargo clippy -p metacrate-grid-agent --all-targets --all-features -- -D warnings: pass - Ratatui/reducer tests: 10 pass (every screen at small/large sizes, mono/Unicode, focus/scroll/identity, refresh stability, confirmation, filtering, bounded history, delayed refresh responsiveness) - Control-plane conformance: 11 pass across in-process and loopback TCP - Preferences/security: 3 pass - Dependency/cross-platform policy: 7 pass - Acceptance evidence: 2 pass - Rustdoc with -D warnings: pass A Windows target probe reached the existing aws-lc-sys build dependency and stopped because this Linux host does not have x86_64-w64-mingw32-gcc installed; it did not report a TUI/Ratatui/Crossterm source error. Repository policy requires ubuntu-latest workflows, which remain unchanged. The pre-existing repository-wide codegen license and compatibility parity metadata failures are unrelated to this presentation-only issue and were left untouched as required.

hugo closed this issue

2026-08-23 16:41:02 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/MetaCrate#140