Terminal User Interface (TUI)
The Palyra TUI provides a rich, interactive terminal experience for chatting with agents, managing sessions, and approving tool executions. It is built usingratatui and crossterm crates/palyra-cli/src/tui/mod.rs#7-19.
Architecture & State Machine
The TUI is governed by anApp struct that maintains the local UI state, including the OperatorRuntime for daemon communication, the current transcript, and active_stream for real-time response rendering crates/palyra-cli/src/tui/mod.rs#107-130.
Key UI Modes:
Chat: The primary interaction surface crates/palyra-cli/src/tui/mod.rs#46.Picker: A modal selection interface for switching Agents, Sessions, or Models crates/palyra-cli/src/tui/mod.rs#54-59.Approval: A dedicated state for reviewing and deciding on sensitive tool calls crates/palyra-cli/src/tui/mod.rs#50.Settings: Configuration for UI preferences like showing hidden “thinking” blocks or tool outputs crates/palyra-cli/src/tui/mod.rs#49.
TUI Component Relationship
The following diagram maps the TUI logic to the underlying code entities. TUI Entity Map Sources: crates/palyra-cli/src/tui/mod.rs#107-164, crates/palyra-cli/src/client/operator.rs#15-35Agent Control Protocol (ACP) Bridge
The ACP Bridge allows Palyra to act as a backend for external tools (like IDE extensions) that speak the Agent Control Protocol. It translates ACP JSON-RPC requests into Palyra gRPC calls.Bridge Implementation
The bridge is implemented inacp_bridge.rs and utilizes the agent-client-protocol crate crates/palyra-cli/src/acp_bridge.rs#7-18. It maintains a BridgeState to map ACP session identifiers to Palyra’s internal ULID-based sessions crates/palyra-cli/src/acp_bridge.rs#31-42.
Protocol Translation Flow:
- Session Resolution: ACP requests with
_metafields (likesessionKeyorsessionLabel) are parsed bysession_overridescrates/palyra-cli/src/acp_bridge.rs#163-170. - Permission Handling: When a Palyra agent requires approval for a tool, the bridge sends a
RequestPermissionnotification back to the ACP client crates/palyra-cli/src/acp_bridge.rs#118-131. - Stream Mapping: Palyra
RunStreamEventmessages are converted into ACPContentBlocksequences crates/palyra-cli/src/acp_bridge.rs#190-210.
ACP Data Flow
ACP to gRPC Translation Sources: crates/palyra-cli/src/acp_bridge.rs#56-63, crates/palyra-cli/src/acp_bridge.rs#133-170, crates/palyra-cli/src/client/operator.rs#137-147Session Management
Session management is handled through thepalyra sessions command group and the OperatorRuntime client module.
Core Commands
Therun_sessions_async function dispatches various session operations crates/palyra-cli/src/commands/sessions.rs#14-45:
| Command | Functionality | Code Reference |
|---|---|---|
list | Lists active and archived sessions with pagination. | crates/palyra-cli/src/commands/sessions.rs#48-94 |
history | Searches session history via the control plane. | crates/palyra-cli/src/commands/sessions.rs#95-154 |
resolve | Creates or resumes a session by Key or ID. | crates/palyra-cli/src/commands/sessions.rs#19-22 |
compact | Previews or applies session history compaction. | crates/palyra-cli/src/commands/sessions.rs#31-33 |
checkpoint | Creates/restores point-in-time session snapshots. | crates/palyra-cli/src/commands/sessions.rs#34-36 |
Session Lifecycle Logic
Sessions are identified by aCanonicalId (ULID) crates/palyra-cli/src/commands/sessions.rs#129. The OperatorRuntime provides the abstraction for these operations, wrapping the GatewayRuntimeClient which performs the actual gRPC calls crates/palyra-cli/src/client/operator.rs#101-118.
Operator Client Modules
TheOperatorRuntime is the primary high-level client used by the CLI for user-facing operations.
Managed Run Streams
A critical feature of theOperatorRuntime is the ManagedRunStream. It handles the complexity of bi-directional gRPC streaming crates/palyra-cli/src/client/operator.rs#31-35:
- Event Aggregation: It collects
RunStreamEventmessages into a consumer-friendly queue crates/palyra-cli/src/client/operator.rs#147-151. - Approval Loop: It allows the UI to send
ToolApprovalResponsemessages back through the same stream without managing the underlying gRPC channel directly crates/palyra-cli/src/client/operator.rs#50-68. - Lifecycle Management: It automatically handles closing the request side of the stream once the initial prompt is sent crates/palyra-cli/src/client/operator.rs#183-191.
Messaging Integration
The CLI also supports sending messages through configured connectors (Discord, Slack, etc.) via themessage client crates/palyra-cli/src/client/message.rs#28-41. This uses the post_connector_action helper to communicate with the daemon’s channel router crates/palyra-cli/src/client/message.rs#105-122.
Sources: crates/palyra-cli/src/client/operator.rs#137-151, crates/palyra-cli/src/client/message.rs#95-123, crates/palyra-cli/src/commands/message.rs#13-22