Struct Tui 

pub struct Tui { /* private fields */ }

Main TUI handle that integrates with the event bus.

Implementations

impl Tui

pub fn new() -> Self

Creates a new TUI instance with shared state (in-process mode).

pub fn connect(base_url: &str) -> Result<Self>

Creates a TUI that connects to a running ralph-api server.

The TUI will fetch initial state via HTTP and subscribe to the RPC v1 event stream over WebSocket. No in-process observer is needed.

Arguments

• base_url — e.g. "http://127.0.0.1:3000"

pub fn spawn(args: Vec<String>) -> Result<Self>

Creates a TUI that spawns ralph run --rpc as a subprocess.

The TUI reads JSON-RPC events from the subprocess stdout and sends commands to its stdin. This mode allows the TUI to run independently of the orchestration loop process.

Arguments

• args - Arguments to pass to ralph run --rpc (e.g., -p "prompt", -c config.yml)

Example

let tui = Tui::spawn(vec![
    "-p".to_string(),
    "Implement feature X".to_string(),
    "-c".to_string(),
    "ralph.yml".to_string(),
])?;
tui.run().await?;

pub fn with_hat_map(self, hat_map: HashMap<String, (HatId, String)>) -> Self

Sets the hat map for dynamic topic-to-hat resolution.

This allows the TUI to display the correct hat for custom topics without hardcoding them in TuiState::update().

pub fn with_termination_signal(self, terminated_rx: Receiver<bool>) -> Self

Sets the termination signal receiver for graceful shutdown.

The TUI will exit when this receiver signals true.

pub fn with_interrupt_tx(self, interrupt_tx: Sender<bool>) -> Self

Sets the interrupt channel for Ctrl+C signaling.

In raw terminal mode, SIGINT is not generated by the OS when the user presses Ctrl+C. The TUI detects Ctrl+C via crossterm events and uses this channel to signal the main orchestration loop to terminate.

pub fn with_events_path(self, path: PathBuf) -> Self

Sets the path to events.jsonl for direct guidance writes.

pub fn with_urgent_steer_path(self, path: PathBuf) -> Self

Sets the path to the urgent-steer marker file for immediate ! gating.

pub fn state(&self) -> Arc<Mutex<TuiState>>

Returns the shared state for external updates.

pub fn guidance_next_queue(&self) -> Arc<Mutex<Vec<String>>>

Returns a handle to the guidance next-queue for draining in the loop runner.

pub fn observer(&self) -> impl Fn(&Event) + Send + 'static

Returns an observer closure that updates TUI state from events.

Only meaningful in in-process mode. In RPC mode, state is updated by the WebSocket bridge instead.

pub async fn run(self) -> Result<()>

Runs the TUI application loop.

In in-process mode, requires with_termination_signal() to have been called first.

In RPC client mode (HTTP/WS), the TUI manages its own lifecycle — the RPC bridge runs alongside the render loop and exits on Ctrl+C or q.

In subprocess RPC mode, the TUI spawns an event reader to consume JSON events from the subprocess stdout and uses an RPC writer to send commands to the subprocess stdin.

Errors

Returns an error if the terminal cannot be initialized or if the application loop encounters an unrecoverable error.

Trait Implementations

impl Default for Tui

fn default() -> Self

Returns the “default value” for a type.