UAT: TUI TerminalEmbed and ShellTerminal widgets are completely absent — spec requires embedded terminal for tool output and shell interaction #4076

New issue

Open

opened 2026-04-06 10:00:55 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 10:00:55 +00:00

Owner

Metadata

Branch: feat/tui-terminal-embed
Commit Message: feat(tui): implement TerminalEmbed and ShellTerminal widgets for tool output and shell interaction
Milestone: (backlog — see note below)
Parent Epic: #868 (Epic: TUI Interface, Modals and Persona System)

Bug Report

What was tested: TUI terminal widget implementation against the specification

Expected behavior (from spec, sections "TUI Architecture Overview" and widget table):

The spec defines two terminal-related widgets for the TUI:

TerminalEmbed: A bordered terminal widget with $primary 50% border, green/red tint, used for shell or tool terminal output. Appears inline in the conversation stream when tools execute shell commands.
ShellTerminal: A full terminal emulator widget for interactive shell sessions within the TUI.

The spec also describes terminal focus handling:

"When a terminal widget (TerminalEmbed or ShellTerminal) has focus, a single escape press is ambiguous — the terminal itself may use escape sequences. The TUI requires a double-tap within 400ms"

The spec shows TerminalEmbed appearing in the conversation stream:

│  🔧 local/file-read ✔                                            ▼
│  ┌─ src/auth/handler.py ─────────────┐
│  │  45 │ def login(self, req):      │
│  │  46 │     creds = extract(req)   │
│  │  47 │     return auth(creds)     │
│  └──────────────────────────────────┘

Actual behavior (from code analysis):

No TerminalEmbed or ShellTerminal class exists anywhere in the codebase. Searching src/cleveragents/tui/ for these classes returns zero results.

The src/cleveragents/tui/widgets/ directory contains only:

actor_selection_overlay.py
help_panel_overlay.py
permission_question.py
persona_bar.py
prompt.py
reference_picker.py
slash_command_overlay.py
thought_block.py

No terminal-related widgets exist. The TUI has no mechanism to display tool output inline in the conversation stream or provide interactive shell sessions.

Code location:

src/cleveragents/tui/widgets/ — directory listing shows no terminal widgets

Steps to reproduce:

Run agents tui
Execute a plan that invokes shell tools
Observe: no TerminalEmbed widget appears in the conversation stream
Observe: tool output is not displayed with the bordered terminal style

Severity: High — without TerminalEmbed, tool execution output cannot be displayed inline in the TUI conversation. This is a core UX feature for monitoring plan execution.

Subtasks

Implement TerminalEmbed widget with bordered terminal style ($primary 50% border, green/red tint)
Implement ShellTerminal widget for interactive shell sessions
Implement double-tap escape handling (400ms window) for terminal focus
Wire TerminalEmbed to display tool execution output inline in conversation
Wire ShellTerminal to _cleveragents/terminal/* A2A extension methods
Add unit tests (Behave scenarios) for terminal widget rendering
Add integration tests (Robot Framework) for terminal interaction

Definition of Done

TerminalEmbed widget renders tool output with correct border style
ShellTerminal widget provides interactive shell sessions
Double-tap escape (400ms) exits terminal focus
Tool execution output appears inline in conversation stream via TerminalEmbed
All existing TUI tests continue to pass
New Behave scenarios cover terminal widget behavior
Pyright type checking passes with no suppressions
All nox stages pass
Coverage >= 97%

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-terminal-embed` - **Commit Message**: `feat(tui): implement TerminalEmbed and ShellTerminal widgets for tool output and shell interaction` - **Milestone**: (backlog — see note below) - **Parent Epic**: #868 (Epic: TUI Interface, Modals and Persona System) ## Bug Report **What was tested:** TUI terminal widget implementation against the specification **Expected behavior (from spec, sections "TUI Architecture Overview" and widget table):** The spec defines two terminal-related widgets for the TUI: 1. **`TerminalEmbed`**: A bordered terminal widget with `$primary 50%` border, green/red tint, used for shell or tool terminal output. Appears inline in the conversation stream when tools execute shell commands. 2. **`ShellTerminal`**: A full terminal emulator widget for interactive shell sessions within the TUI. The spec also describes terminal focus handling: > "When a terminal widget (TerminalEmbed or ShellTerminal) has focus, a single `escape` press is ambiguous — the terminal itself may use escape sequences. The TUI requires a double-tap within 400ms" The spec shows `TerminalEmbed` appearing in the conversation stream: ``` │ 🔧 local/file-read ✔ ▼ │ ┌─ src/auth/handler.py ─────────────┐ │ │ 45 │ def login(self, req): │ │ │ 46 │ creds = extract(req) │ │ │ 47 │ return auth(creds) │ │ └──────────────────────────────────┘ ``` **Actual behavior (from code analysis):** No `TerminalEmbed` or `ShellTerminal` class exists anywhere in the codebase. Searching `src/cleveragents/tui/` for these classes returns zero results. The `src/cleveragents/tui/widgets/` directory contains only: - `actor_selection_overlay.py` - `help_panel_overlay.py` - `permission_question.py` - `persona_bar.py` - `prompt.py` - `reference_picker.py` - `slash_command_overlay.py` - `thought_block.py` No terminal-related widgets exist. The TUI has no mechanism to display tool output inline in the conversation stream or provide interactive shell sessions. **Code location:** - `src/cleveragents/tui/widgets/` — directory listing shows no terminal widgets **Steps to reproduce:** 1. Run `agents tui` 2. Execute a plan that invokes shell tools 3. Observe: no `TerminalEmbed` widget appears in the conversation stream 4. Observe: tool output is not displayed with the bordered terminal style **Severity:** High — without `TerminalEmbed`, tool execution output cannot be displayed inline in the TUI conversation. This is a core UX feature for monitoring plan execution. ## Subtasks - [ ] Implement `TerminalEmbed` widget with bordered terminal style (`$primary 50%` border, green/red tint) - [ ] Implement `ShellTerminal` widget for interactive shell sessions - [ ] Implement double-tap `escape` handling (400ms window) for terminal focus - [ ] Wire `TerminalEmbed` to display tool execution output inline in conversation - [ ] Wire `ShellTerminal` to `_cleveragents/terminal/*` A2A extension methods - [ ] Add unit tests (Behave scenarios) for terminal widget rendering - [ ] Add integration tests (Robot Framework) for terminal interaction ## Definition of Done - [ ] `TerminalEmbed` widget renders tool output with correct border style - [ ] `ShellTerminal` widget provides interactive shell sessions - [ ] Double-tap `escape` (400ms) exits terminal focus - [ ] Tool execution output appears inline in conversation stream via `TerminalEmbed` - [ ] All existing TUI tests continue to pass - [ ] New Behave scenarios cover terminal widget behavior - [ ] Pyright type checking passes with no suppressions - [ ] All nox stages pass - [ ] Coverage >= 97% > **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

freemo added a new dependency

2026-04-06 10:01:08 +00:00

#868 Epic: TUI Interface, Modals and Persona System

freemo added the

Points

label

2026-04-06 10:04:33 +00:00

freemo referenced this issue

2026-04-06 10:10:44 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 10:15:25 +00:00