ratatui-based terminal rendering loop.
Terminal User Interface (TUI)
The TUI is the primary interactive mode for the Palyra CLI. It is implemented using theratatui crate with a crossterm backend crates/palyra-cli/src/tui/mod.rs#12-19. It provides a multi-pane interface for viewing transcripts, entering prompts, and managing tool approvals.
Core Architecture
The TUI lifecycle is managed by theApp struct, which maintains the session state, transcript history, and UI focus crates/palyra-cli/src/tui/mod.rs#122-152.
| Component | Responsibility |
|---|---|
OperatorRuntime | Orchestrates gRPC communication with the daemon crates/palyra-cli/src/client/operator.rs#15-17. |
ManagedRunStream | Manages the lifecycle of a bidirectional gRPC stream for agent runs crates/palyra-cli/src/client/operator.rs#31-35. |
TuiSlashPaletteState | Tracks the state of the active slash command and its suggestions crates/palyra-cli/src/tui/slash_palette.rs#110-113. |
TranscriptEntry | Represents a single turn (User, Assistant, Tool, etc.) in the UI crates/palyra-cli/src/tui/mod.rs#109-113. |
TUI Rendering Loop
The TUI operates on a standard terminal event loop that polls for keyboard input and drains asynchronous gRPC events from theManagedRunStream crates/palyra-cli/src/tui/mod.rs#177-193.
TUI Interaction Flow
Title: TUI Event Handling and Rendering Sources: crates/palyra-cli/src/tui/mod.rs#177-193, crates/palyra-cli/src/tui/mod.rs#122-152Shared Chat Command Registry
To maintain parity between the TUI and the Web Console, Palyra uses a centralized JSON registry:chatCommandRegistry.json apps/web/src/chat/chatCommandRegistry.json#1-210. This registry defines the metadata, syntax, and capability requirements for every slash command.
Command Definitions
Commands are categorized by their execution environment crates/palyra-cli/src/shared_chat_commands.rs#21-27:- Local: Executed entirely within the client (e.g.,
/help,/settings). - Server: Dispatched to the daemon via gRPC (e.g.,
/new,/reset,/undo). - LocalCapability: Requires specific client-side features like filesystem access or browser control (e.g.,
/attach,/shell).
Registry Parity
The CLI validates this registry at compile time usingload_shared_chat_commands, ensuring no duplicate names or aliases exist crates/palyra-cli/src/shared_chat_commands.rs#135-143. Snapshot tests further verify that the TUI and Web surfaces expose the correct subsets of commands crates/palyra-cli/tests/shared_chat_command_parity.md#1-13.
Sources: apps/web/src/chat/chatCommandRegistry.json#1-210, crates/palyra-cli/src/shared_chat_commands.rs#39-56, crates/palyra-cli/src/shared_chat_commands.rs#135-195
Slash Palette & Suggestions
The Slash Palette provides real-time autocomplete for commands and entities (sessions, agents, models). It is triggered when the user types a/ in the input field.
Data Flow: Input to Suggestion
Thebuild_tui_slash_palette function processes the raw input string and cross-references it with the TuiSlashEntityCatalog to generate suggestions crates/palyra-cli/src/tui/slash_palette.rs#132-182.
Entity Resolution Logic
Title: Natural Language to Code Entity Resolution Sources: crates/palyra-cli/src/tui/slash_palette.rs#132-182, crates/palyra-cli/src/tui/slash_palette.rs#8-16, crates/palyra-cli/src/shared_chat_commands.rs#70-78Entity Catalog
TheTuiSlashEntityCatalog acts as a local cache of server-side entities used for palette filtering crates/palyra-cli/src/tui/slash_palette.rs#8-16:
- Sessions: Filtered by
session_keyortitle. - Objectives: Filtered by
nameorkind(heartbeat, program, standing-order). - Checkpoints: Filtered by
nameor tags likeundo_safecrates/palyra-cli/src/tui/slash_palette.rs#206-213.
Command Execution Flow
When a command is submitted in the TUI, it follows a specific resolution path depending on whether it is a built-in TUI command or a shared registry command.Local vs. Remote Execution
- TUI Built-ins: Commands like
/exitor/settingsmodify the internalAppstate (e.g.,app.mode = Mode::Settings) crates/palyra-cli/src/tui/mod.rs#60-67. - Server Commands: Commands like
/undoor/interruptare resolved viaOperatorRuntimeand sent asRunStreamRequestmessages over the active gRPC stream crates/palyra-cli/src/client/operator.rs#137-146.
Run Stream Control
Title: Command Dispatch to GatewayRuntimeClient Sources: crates/palyra-cli/src/client/operator.rs#137-174, crates/palyra-cli/src/client/runtime.rs#72-82, crates/palyra-cli/src/tui/mod.rs#33-38Interaction Metrics
The TUI tracks user interaction viaTuiUxMetrics, recording events such as SlashCommands, PaletteAccepts, Undo, and Interrupt crates/palyra-cli/src/tui/slash_palette.rs#66-74. These metrics are used for internal diagnostics and are accessible via the /status command apps/web/src/chat/chatCommandRegistry.json#15-25.
Sources: crates/palyra-cli/src/tui/slash_palette.rs#66-97, crates/palyra-cli/src/tui/mod.rs#148