Skip to main content

Async Requirement Execution Implementation

Overview​

Implemented non-blocking async requirement execution for the TUI, eliminating UI freezes during long-running requirement workflows. The implementation uses tokio channels for real-time progress updates.

Architecture​

Components​

  1. RequirementProgress Enum (radium-core/src/workflow/requirement_executor.rs)

    • Progress update states: Started, TaskStarted, TaskCompleted, TaskFailed, Completed, Failed
    • Sent through mpsc channel during execution
    • Includes task details, progress counts, and error information

  2. ActiveRequirement Struct (apps/tui/src/requirement_progress.rs)

    • Tracks requirement execution state
    • Receives and processes progress updates
    • Calculates progress percentage
    • Maintains current status string for UI display

  3. Async Executor (radium-core/src/workflow/requirement_executor.rs)

    • execute_requirement_with_progress() method sends progress updates
    • Spawned in tokio::spawn for non-blocking execution
    • Updates sent after each significant event

  4. Event Loop Integration (apps/tui/src/main.rs)

    • Non-blocking progress polling using try_recv()
    • Updates UI in real-time
    • Shows final summary on completion

Key Features​

Non-Blocking Execution​

  • UI remains responsive during requirement execution
  • User can type, navigate, and interact while execution runs
  • 100ms event loop polling interval

Real-Time Progress Updates​

  • Live status updates as tasks execute
  • Task completion/failure tracking
  • Progress percentage calculation
  • Current task display

Graceful Error Handling​

  • Channel disconnection detection
  • Timeout handling
  • Graceful cleanup on completion

Test Coverage​

Unit Tests (apps/tui/src/requirement_progress.rs)​

  1. Initialization Tests

    • test_active_requirement_initialization() - Verifies initial state

  2. Progress Update Tests

    • test_active_requirement_started_update() - Tests Started event
    • test_active_requirement_task_completed_update() - Tests task completion
    • test_progress_percentage() - Tests percentage calculation

  3. Async Communication Tests

    • test_progress_channel_communication() - Tests tokio channel integration

All tests pass and provide comprehensive coverage of the progress tracking logic.

Usage​

In TUI​

/requirement REQ-178 --project PROJ-14

The TUI will:

  1. Initialize the requirement executor
  2. Spawn async execution in background
  3. Display progress updates in real-time
  4. Show final summary when complete
  5. Remain responsive throughout

Progress States​

  • Initializing: "β ‹ Initializing..."
  • Starting: "β ‹ Starting execution (N tasks)..."
  • Executing: "β ‹ Executing task 1/N: Task Title"
  • Completed: "● Completed: Task Title"
  • Failed: "βœ— Failed: Task Title (Error)"
  • Complete: "βœ“ Completed (N tasks)"

Implementation Details​

Progress Channel​

  • Buffer size: 100 messages
  • Type: tokio::sync::mpsc::channel<RequirementProgress>
  • One sender (executor), one receiver (TUI)

Status Updates​

  • Sent after each task event
  • Includes task number, title, and status
  • Final result includes execution time and statistics

Cleanup​

  • Automatic cleanup when channel closes
  • Active requirement removed from app state
  • Summary displayed before cleanup

Future Enhancements​

Based on CodeMachine-CLI patterns, the following enhancements are planned:

1. Visual Timeline​

  • Left panel: Task timeline with status indicators
  • Right panel: Real-time output/logs
  • Expandable/collapsible task nodes

2. Enhanced Progress Display​

  • Animated spinners for running tasks
  • Progress bars for long-running operations
  • Color-coded status indicators

3. Telemetry Bar​

  • Runtime display (HH:MM:SS)
  • Token usage tracking
  • Cost estimation

4. Toast Notifications​

  • Non-intrusive success/failure notifications
  • Auto-dismiss after duration
  • Stack multiple toasts
  • Context-aware keyboard shortcuts
  • Current mode display
  • Selection info

6. Log Streaming​

  • Real-time log file streaming
  • Incremental log reader (only read new lines)
  • Syntax highlighting
  • Auto-scroll to bottom

7. History View​

  • Past execution history
  • Filterable/searchable
  • Open log viewer for past runs

Code Locations​

Core Implementation​

  • crates/radium-core/src/workflow/requirement_executor.rs:370-628 - Async executor with progress
  • crates/radium-core/src/workflow/mod.rs:51-54 - Progress export

TUI Integration​

  • apps/tui/src/requirement_progress.rs - Progress tracking (195 lines with tests)
  • apps/tui/src/app.rs:1473-1601 - Handle requirement command
  • apps/tui/src/main.rs:75-123 - Event loop progress polling
  • apps/tui/src/lib.rs:11 - Module declaration

Performance​

  • Event Loop: 100ms polling interval (non-blocking)
  • Channel Buffer: 100 messages (prevents backpressure)
  • Memory: Minimal overhead (~1KB per active requirement)
  • CPU: Negligible (polling only when events available)

Testing​

Run tests:

# Unit tests
cargo test -p radium-tui -- requirement_progress

# Integration tests (requires Braingrid)
cargo test -p radium-core -- requirement_executor

Known Limitations​

  1. Theme Conflicts: Current implementation conflicts with ongoing UI/UX theme updates
  2. Single Execution: Only one requirement can be executed at a time
  3. No Cancellation: Cannot cancel in-progress execution (future enhancement)
  4. No Resume: Cannot resume interrupted executions

Next Steps​

  1. βœ… Implement async requirement execution
  2. βœ… Add comprehensive tests
  3. ⏳ Resolve theme conflicts
  4. ⏳ Add visual timeline (inspired by CodeMachine-CLI)
  5. ⏳ Implement telemetry bar
  6. ⏳ Add toast notification system
  7. ⏳ Implement log streaming
  8. ⏳ Add history view

References​

  • CodeMachine-CLI: /old/CodeMachine-CLI/src/ui/components/
  • Gemini-CLI: /old/gemini-cli/
  • Braingrid Integration: crates/radium-core/src/context/braingrid_client.rs