baobab/core/supervisor/cmd/TUI_README.md

Supervisor Terminal UI (TUI)

A modern, interactive Terminal User Interface for the Hero Supervisor that provides intuitive job management with real-time updates and visual navigation.

Features

🎯 Intuitive Interface

• Split-pane Layout: Job list on the left, details on the right
• Real-time Updates: Auto-refreshes every 2 seconds
• Color-coded Status: Visual job status indicators
• Keyboard Navigation: Vim-style and arrow key support

📋 Job Management

• Create Jobs: Interactive form with tab navigation
• Monitor Jobs: Real-time status updates with color coding
• View Details: Detailed job information and output
• View Logs: Access job execution logs
• Stop/Delete: Job lifecycle management
• Bulk Operations: Clear all jobs with confirmation

🎨 Visual Design

• Status Colors:
  • 🔵 Blue: Dispatched
  • 🟡 Yellow: Started
  • 🟢 Green: Finished
  • 🔴 Red: Error
  • 🟣 Magenta: Waiting for Prerequisites
• Highlighted Selection: Clear visual feedback
• Popup Messages: Status and error notifications
• Confirmation Dialogs: Safe bulk operations

Usage

1. Start the TUI

cd /Users/timurgordon/code/git.ourworld.tf/herocode/baobab/core/supervisor
cargo run --bin supervisor-tui -- --config examples/cli_config.toml

2. Navigation

Main View

• ↑/↓ or j/k: Navigate job list
• Enter/Space: View job details
• n/c: Create new job
• r: Manual refresh
• d: Delete selected job (with confirmation)
• s: Stop selected job
• C: Clear all jobs (with confirmation)
• q: Quit application

Job Creation Form

• Tab: Next field
• Shift+Tab: Previous field
• Enter: Next field (or newline in script field)
• F5: Submit job
• Esc: Cancel and return to main view

Job Details/Logs View

• Esc/q: Return to main view
• l: Switch to logs view
• d: Switch to details view

Interface Layout

┌─────────────────────────────────────────────────────────────┐
│                Hero Supervisor TUI - Job Management         │
├─────────────────────┬───────────────────────────────────────┤
│ Jobs                │ Job Details                           │
│                     │                                       │
│ >> 1a2b3c4d - ✅ Fi │ Job ID: 1a2b3c4d5e6f7g8h             │
│    2b3c4d5e - 🟡 St │ Status: Finished                      │
│    3c4d5e6f - 🔴 Er │                                       │
│    4d5e6f7g - 🔵 Di │ Output:                               │
│                     │ Calculation result: 70                │
│                     │ 70                                    │
├─────────────────────┴───────────────────────────────────────┤
│ q: Quit | n: New Job | ↑↓: Navigate | Enter: Details        │
└─────────────────────────────────────────────────────────────┘

Job Creation Workflow

1. Press 'n' to create a new job
2. Fill in the form:
   • Caller: Your name or identifier
   • Context: Job description
   • Script: Rhai script (supports multi-line)
3. Press F5 to submit
4. Watch real-time execution in the main view

Example Rhai Scripts

// Simple calculation
let result = 10 + 20 * 3;
print("Calculation result: " + result);
result

// String manipulation
let message = "Hello from OSIS Actor!";
print(message);
message.to_upper()

// Loop example
let sum = 0;
for i in 1..=10 {
    sum += i;
}
print("Sum of 1-10: " + sum);
sum

Key Improvements over CLI

✅ Better UX

• Visual Navigation: No need to remember numbers
• Real-time Updates: See job progress immediately
• Split-pane Design: View list and details simultaneously
• Form Validation: Clear error messages

✅ Enhanced Productivity

• Auto-refresh: Always up-to-date information
• Keyboard Shortcuts: Fast navigation and actions
• Confirmation Dialogs: Prevent accidental operations
• Multi-line Script Input: Better script editing

✅ Professional Interface

• Color-coded Status: Quick visual assessment
• Consistent Layout: Predictable interface elements
• Popup Notifications: Non-intrusive feedback
• Graceful Error Handling: User-friendly error messages

Prerequisites

• Redis server running (default: localhost:6379)
• OSIS actor binary built and configured
• Terminal with color support
• Minimum terminal size: 80x24

Troubleshooting

Display Issues

• Ensure terminal supports colors and Unicode
• Resize terminal if layout appears broken
• Use a modern terminal emulator (iTerm2, Alacritty, etc.)

Performance

• TUI auto-refreshes every 2 seconds
• Large job lists may impact performance
• Use 'r' for manual refresh if needed

Navigation Issues

• Use arrow keys if vim keys (j/k) don't work
• Ensure terminal is in focus
• Try Esc to reset state if stuck

Advanced Features

Bulk Operations

• Clear All Jobs: Press 'C' with confirmation
• Safe Deletion: Confirmation required for destructive operations

Real-time Monitoring

• Auto-refresh: Updates every 2 seconds
• Status Tracking: Watch job progression
• Immediate Feedback: See results as they complete

Multi-line Scripts

• Rich Text Input: Full script editing in TUI
• Syntax Awareness: Better than single-line CLI input
• Preview: See script before submission