UAT: TuiMaterializer is completely absent — spec requires TUI-specific MaterializationStrategy to render CLI output in TUI widgets #4075

Open
opened 2026-04-06 09:58:28 +00:00 by freemo · 0 comments
Owner

Metadata

  • Branch: feat/tui-materializer
  • Commit Message: feat(tui): implement TuiMaterializer to bridge OutputSession element handles to Textual widgets
  • Milestone: (none — backlog, see note below)
  • Parent Epic: #868 (Epic: TUI Interface, Modals and Persona System)

Bug Report

What was tested: TuiMaterializer implementation against the specification

Expected behavior (from spec, sections "TUI Architecture Overview" and "Output Rendering Framework"):

The spec explicitly describes a TuiMaterializer as a core architectural component:

"The TUI communicates with the Application layer exclusively through A2A (ADR-026). It subscribes to A2A events for real-time updates and uses the existing Output Rendering Framework (ADR-021) via a TuiMaterializer that maps ElementHandle events to Textual widget operations — enabling all CLI command producers to render in the TUI without modification."

The spec also states:

"Element handles become observable data sources. A TUI MaterializationStrategy (e.g., TuiMaterializer) would subscribe to element events and route them to TUI widgets. The producer code (command logic) is completely unaware of whether it is driving a CLI, TUI, or web frontend — it writes to handles identically in all cases."

The TuiMaterializer must implement the MaterializationStrategy protocol and:

  • Subscribe to ElementEvent notifications from OutputSession
  • Route events to Textual widget operations (e.g., PanelHandle events → Textual Static or DataTable widgets)
  • Support concurrent updates from multiple producers
  • Enable all CLI command producers to render in the TUI without modification

Actual behavior (from code analysis):

No TuiMaterializer class exists anywhere in the codebase. Searching src/cleveragents/ for TuiMaterializer, tui_materializer, or any TUI-specific MaterializationStrategy implementation returns zero results.

The existing materializers in src/cleveragents/cli/output/materializers.py are:

  • MaterializationStrategy (Protocol)
  • _LiveMaterializationStrategy (for rich format)
  • RichMaterializer

None of these are TUI-aware. The TUI app currently uses a simple _Static widget with conversation.update(result.expanded_text) — a primitive string update with no connection to the Output Rendering Framework.

Code location:

  • src/cleveragents/cli/output/materializers.py — existing materializers (no TUI variant)
  • src/cleveragents/tui/app.py — lines 186-209 (primitive string update instead of TuiMaterializer)

Steps to reproduce:

  1. Run agents tui
  2. Execute any command that produces structured output (e.g., /plan list)
  3. Observe: output is rendered as a plain string update, not as structured Textual widgets
  4. Observe: no PanelHandle, TableHandle, or ProgressHandle events are routed to TUI widgets

Severity: Critical — without TuiMaterializer, the TUI cannot leverage the Output Rendering Framework. All CLI command producers must be duplicated or special-cased for TUI, defeating the "single codebase" architectural goal.

Subtasks

  • Implement TuiMaterializer class implementing MaterializationStrategy protocol
  • Map PanelHandle events to Textual Static or custom panel widgets
  • Map TableHandle events to Textual DataTable widgets
  • Map ProgressHandle events to Textual ProgressBar widgets
  • Map TreeHandle events to Textual Tree widgets
  • Support concurrent updates from multiple producers
  • Wire TuiMaterializer into the TUI app's OutputSession creation
  • Add unit tests (Behave scenarios) for TuiMaterializer event routing
  • Verify CLI command producers render correctly in TUI without modification

Definition of Done

  • TuiMaterializer implements MaterializationStrategy protocol
  • All element handle types (PanelHandle, TableHandle, ProgressHandle, TreeHandle) route to appropriate Textual widgets
  • CLI command producers render in TUI without modification
  • Concurrent updates from multiple producers are handled correctly
  • All existing TUI and CLI tests continue to pass
  • New Behave scenarios cover TuiMaterializer event routing
  • Pyright type checking passes with no suppressions
  • All nox stages pass
  • Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.


Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `feat/tui-materializer` - **Commit Message**: `feat(tui): implement TuiMaterializer to bridge OutputSession element handles to Textual widgets` - **Milestone**: *(none — backlog, see note below)* - **Parent Epic**: #868 (Epic: TUI Interface, Modals and Persona System) ## Bug Report **What was tested:** TuiMaterializer implementation against the specification **Expected behavior (from spec, sections "TUI Architecture Overview" and "Output Rendering Framework"):** The spec explicitly describes a `TuiMaterializer` as a core architectural component: > "The TUI communicates with the Application layer exclusively through A2A (ADR-026). It subscribes to A2A events for real-time updates and uses the existing Output Rendering Framework (ADR-021) via a `TuiMaterializer` that maps `ElementHandle` events to Textual widget operations — enabling all CLI command producers to render in the TUI without modification." The spec also states: > "Element handles become observable data sources. A TUI `MaterializationStrategy` (e.g., `TuiMaterializer`) would subscribe to element events and route them to TUI widgets. The producer code (command logic) is completely unaware of whether it is driving a CLI, TUI, or web frontend — it writes to handles identically in all cases." The `TuiMaterializer` must implement the `MaterializationStrategy` protocol and: - Subscribe to `ElementEvent` notifications from `OutputSession` - Route events to Textual widget operations (e.g., `PanelHandle` events → Textual `Static` or `DataTable` widgets) - Support concurrent updates from multiple producers - Enable all CLI command producers to render in the TUI without modification **Actual behavior (from code analysis):** No `TuiMaterializer` class exists anywhere in the codebase. Searching `src/cleveragents/` for `TuiMaterializer`, `tui_materializer`, or any TUI-specific `MaterializationStrategy` implementation returns zero results. The existing materializers in `src/cleveragents/cli/output/materializers.py` are: - `MaterializationStrategy` (Protocol) - `_LiveMaterializationStrategy` (for `rich` format) - `RichMaterializer` None of these are TUI-aware. The TUI app currently uses a simple `_Static` widget with `conversation.update(result.expanded_text)` — a primitive string update with no connection to the Output Rendering Framework. **Code location:** - `src/cleveragents/cli/output/materializers.py` — existing materializers (no TUI variant) - `src/cleveragents/tui/app.py` — lines 186-209 (primitive string update instead of TuiMaterializer) **Steps to reproduce:** 1. Run `agents tui` 2. Execute any command that produces structured output (e.g., `/plan list`) 3. Observe: output is rendered as a plain string update, not as structured Textual widgets 4. Observe: no `PanelHandle`, `TableHandle`, or `ProgressHandle` events are routed to TUI widgets **Severity:** Critical — without `TuiMaterializer`, the TUI cannot leverage the Output Rendering Framework. All CLI command producers must be duplicated or special-cased for TUI, defeating the "single codebase" architectural goal. ## Subtasks - [ ] Implement `TuiMaterializer` class implementing `MaterializationStrategy` protocol - [ ] Map `PanelHandle` events to Textual `Static` or custom panel widgets - [ ] Map `TableHandle` events to Textual `DataTable` widgets - [ ] Map `ProgressHandle` events to Textual `ProgressBar` widgets - [ ] Map `TreeHandle` events to Textual `Tree` widgets - [ ] Support concurrent updates from multiple producers - [ ] Wire `TuiMaterializer` into the TUI app's `OutputSession` creation - [ ] Add unit tests (Behave scenarios) for `TuiMaterializer` event routing - [ ] Verify CLI command producers render correctly in TUI without modification ## Definition of Done - [ ] `TuiMaterializer` implements `MaterializationStrategy` protocol - [ ] All element handle types (`PanelHandle`, `TableHandle`, `ProgressHandle`, `TreeHandle`) route to appropriate Textual widgets - [ ] CLI command producers render in TUI without modification - [ ] Concurrent updates from multiple producers are handled correctly - [ ] All existing TUI and CLI tests continue to pass - [ ] New Behave scenarios cover `TuiMaterializer` event routing - [ ] Pyright type checking passes with no suppressions - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
HAL9000 added this to the v3.5.0 milestone 2026-04-09 03:11:19 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
Reference
cleveragents/cleveragents-core#4075
No description provided.