palyrad Gateway gRPC service, abstracting the complexities of session management and stream handling.
Terminal User Interface (TUI)
The TUI is aratatui-based operator client that allows for interactive chat sessions, tool approval workflows, and session management directly from the terminal. It is launched via the palyra tui command crates/palyra-cli/src/commands/tui.rs#3-26.
Core Implementation
The TUI is built around theApp struct, which maintains the UI state, and the OperatorRuntime, which handles gRPC communication with the daemon crates/palyra-cli/src/tui/mod.rs#107-130.
OperatorRuntime: Encapsulates the gRPC connection and provides high-level methods for listing agents, resolving sessions, and starting run streams crates/palyra-cli/src/client/operator.rs#15-17.ManagedRunStream: Manages the lifecycle of a bidirectional gRPC stream, handling event routing and tool approval responses crates/palyra-cli/src/client/operator.rs#31-35.- Event Loop: The
run_loopfunction polls for terminal events (key presses) while simultaneously draining events from the activeManagedRunStreamcrates/palyra-cli/src/tui/mod.rs#148-164.
UI States and Navigation
The TUI operates in several modes defined by theMode enum, including Chat, Picker (for selecting agents/models), Settings, and Approval crates/palyra-cli/src/tui/mod.rs#45-52.
| Mode | Purpose |
|---|---|
Chat | Primary interaction interface for sending prompts and viewing transcripts. |
Approval | Intercepts tool calls requiring manual operator confirmation. |
Picker | Interactive lists for switching between agents, sessions, or model profiles. |
Settings | Toggles for UI preferences like showing “thinking” blocks or tool details. |
TUI Architecture Diagram
The following diagram illustrates the relationship between the TUI frontend entities and the underlying runtime clients. “TUI Component Map” Sources: crates/palyra-cli/src/tui/mod.rs#107-130, 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 allows Palyra to act as a host for agents following the Agent Control Protocol. It maps ACP JSON-RPC notifications and requests (typically over stdio) into Palyra’s gRPC-basedRunStream protocol crates/palyra-cli/src/acp_bridge.rs#7-18.
Session Binding
The bridge maintains aBridgeState that maps ACP SessionIds to Palyra’s internal ULID-based session identifiers crates/palyra-cli/src/acp_bridge.rs#31-42. This allows legacy agents to maintain state across multiple turns while the bridge handles the ResolveSession logic with the daemon crates/palyra-cli/src/acp_bridge.rs#163-170.
Data Flow and Transformation
When an ACP agent sends a prompt, thePalyraAcpAgent implementation:
- Resolves or creates a Palyra session using
session_overridescrates/palyra-cli/src/acp_bridge.rs#163-170. - Converts ACP
ContentBlocks (text or resources) into a unified prompt string crates/palyra-cli/src/acp_bridge.rs#190-210. - Opens a
ManagedRunStreamvia theOperatorRuntimecrates/palyra-cli/src/client/operator.rs#137-146. - Streams events back to the ACP client as
SessionUpdatenotifications crates/palyra-cli/src/acp_bridge.rs#100-116.
ACP to gRPC Bridge Mapping
“ACP to gRPC Entity Mapping” Sources: crates/palyra-cli/src/acp_bridge.rs#81-116, crates/palyra-cli/src/client/operator.rs#137-175, crates/palyra-cli/src/client/runtime.rs#203-210Session and Agent Management
The CLI provides a suite of commands for managing the entities that the TUI and ACP Bridge interact with.Session Commands
Managed incrates/palyra-cli/src/commands/sessions.rs, these commands interface with the OperatorRuntime to perform CRUD and lifecycle operations on sessions crates/palyra-cli/src/commands/sessions.rs#45-47.
list: Fetches a paginated list of sessions, optionally including archived ones crates/palyra-cli/src/commands/sessions.rs#48-50.history: Performs a full-text search across session transcripts using the control plane search API crates/palyra-cli/src/commands/sessions.rs#95-122.compact-apply: Manually triggers the session compaction process to reduce context window usage crates/palyra-cli/src/args/sessions.rs#121-133.checkpoint-create: Creates a named snapshot of a session’s current state crates/palyra-cli/src/args/sessions.rs#139-149.
Agent Commands
Managed incrates/palyra-cli/src/commands/agents.rs, these commands handle agent identity and environment bindings crates/palyra-cli/src/commands/agents.rs#29-31.
bind: Associates an agent with a specific principal, channel, or session crates/palyra-cli/src/commands/agents.rs#148-159.interactive: A lightweight, non-TUI interactive mode that uses standard input/output for quick testing crates/palyra-cli/src/commands/agent.rs#115-135.