Terminal User Interface (TUI)
The Palyra TUI is aratatui-based interactive environment that allows users to chat with agents, manage sessions, and approve tool executions directly from the terminal. It is implemented in crates/palyra-cli/src/tui/mod.rs crates/palyra-cli/src/tui/mod.rs#12-19.
TUI Architecture and State Management
The TUI is driven by theApp struct, which maintains the session state, transcript history, and active gRPC streams crates/palyra-cli/src/tui/mod.rs#107-131.
| Component | Role |
|---|---|
OperatorRuntime | Manages gRPC communication with the palyrad gateway crates/palyra-cli/src/client/operator.rs#15-17. |
ManagedRunStream | Wraps the bidirectional gRPC stream, handling asynchronous events and control signals crates/palyra-cli/src/client/operator.rs#31-35. |
TranscriptEntry | Represents a single turn in the conversation (User, Assistant, Tool, etc.) crates/palyra-cli/src/tui/mod.rs#93-98. |
PickerState | Manages selection UI for agents, sessions, or models crates/palyra-cli/src/tui/mod.rs#75-81. |
Run Loop and Event Handling
The TUI uses a standardcrossterm event loop crates/palyra-cli/src/tui/mod.rs#149-165. It polls for terminal input while simultaneously draining events from the active_stream crates/palyra-cli/src/tui/mod.rs#151-152.
Bridge: TUI Code Entity Space
The following diagram illustrates how TUI visual components map to the underlying Rust structs and the gRPC communication layer. TUI System Mapping Sources: crates/palyra-cli/src/tui/mod.rs#107-131, crates/palyra-cli/src/client/operator.rs#15-35, crates/palyra-cli/src/client/runtime.rs#9-12Agent Control Protocol (ACP) Bridge
The ACP bridge implements a stdio-based protocol that allows external editors or tools to control Palyra agents. It translates ACP JSON-RPC messages into Palyra gRPC calls.Bridge Implementation
The bridge is implemented incrates/palyra-cli/src/acp_bridge.rs. It maintains a BridgeState to track active sessions and runs crates/palyra-cli/src/acp_bridge.rs#38-42.
Key features include:
- Session Overrides: Support for
_metafields in ACP requests to specifysessionKey,sessionLabel, orresetSessioncrates/palyra-cli/src/acp_bridge.rs#163-170. - Permission Handling: An asynchronous flow for requesting tool execution permissions from the ACP client crates/palyra-cli/src/acp_bridge.rs#118-131.
- Stdio Transport: Uses
AllowStdIoto bridge standard input/output with the ACP protocol handler crates/palyra-cli/src/acp_bridge.rs#9-10.
ACP to gRPC Data Flow
Sources: crates/palyra-cli/src/acp_bridge.rs#100-131, crates/palyra-cli/src/client/operator.rs#137-148Agent & Session Commands
The CLI provides extensive commands for managing the lifecycle of agents and their associated conversation sessions.Agent Management
Agent commands are handled incrates/palyra-cli/src/commands/agents.rs and interact with the GatewayServiceClient crates/palyra-cli/src/commands/agents.rs#29-31.
- Create:
agents.createinitializes a new agent with a specific directory and model profile crates/palyra-cli/src/commands/agents.rs#25. - Bind:
agents.bindassociates an agent with a specificprincipal,channel, andsession_idcrates/palyra-cli/src/commands/agents.rs#148-159. - List:
agents.listretrieves all agents available on the gateway crates/palyra-cli/src/commands/agents.rs#32-43.
Session Management
Session commands are implemented incrates/palyra-cli/src/commands/sessions.rs. These commands support both administrative operations and conversational history.
- History & Search:
sessions.historyallows searching through the session catalog using natural language queries or filters crates/palyra-cli/src/commands/sessions.rs#95-122. - Compaction: Supports
CompactPreviewandCompactApplyto manage long-running context by summarizing or removing older turns crates/palyra-cli/src/commands/sessions.rs#31-32. - Checkpoints:
CheckpointCreateandCheckpointRestoreallow branching sessions at specific points in time crates/palyra-cli/src/commands/sessions.rs#34-36. - Resolution: The
Resolvecommand usesSessionResolveInputto find or create sessions based on keys and labels crates/palyra-cli/src/args/sessions.rs#41-54.
Interactive Mode
Theagent interactive command provides a simplified line-based chat interface as an alternative to the full TUI. It supports slash commands such as /exit, /help, /session, and /reset crates/palyra-cli/src/commands/agent.rs#139-190.
Command Entity Mapping
Sources: crates/palyra-cli/src/commands/agent.rs#27-30, crates/palyra-cli/src/commands/agents.rs#3-12, crates/palyra-cli/src/commands/sessions.rs#3-11