Skip to main content
This page details the interactive and integration layers of the Palyra CLI, specifically focusing on the Agent Control Protocol (ACP) implementation, the Terminal User Interface (TUI), and the command suites for agent and session management.

​
Agent Control Protocol (ACP) Bridge

The acp command implements the Agent Control Protocol stdio bridge. It allows external IDEs (like VS Code or Cursor) or other ACP-compliant clients to use Palyra as a backend agent provider via standard input/output.

​
Implementation and Data Flow

The bridge is implemented in crates/palyra-cli/src/acp_bridge.rs and acts as a translator between ACP JSON-RPC messages and Palyra’s gRPC Gateway API.
  1. Initialization: The bridge starts a PalyraAcpAgent which wraps an AgentConnection crates/palyra-cli/src/acp_bridge.rs#56-63.
  2. Session Mapping: ACP sessions are mapped to Palyra sessions using a BridgeState which tracks SessionBinding (mapping ACP SessionId to Palyra CanonicalId) crates/palyra-cli/src/acp_bridge.rs#31-42.
  3. Prompt Handling: When a client sends a prompt, the bridge calls GatewayRuntimeClient::run_agent_stream. It handles streaming events (text, tool calls) and converts them back to ACP SessionUpdate notifications crates/palyra-cli/src/acp_bridge.rs#100-116.
  4. Permission Proxy: If the Palyra daemon requires human-in-the-loop approval for a tool, the bridge can proxy this request back to the ACP client using request_permission crates/palyra-cli/src/acp_bridge.rs#118-131.

​
ACP Shim Mode

The CLI includes a “shim” mode (palyra acp shim) which provides legacy compatibility for tools expecting older agent protocol signatures while routing the actual execution through the modern ACP bridge crates/palyra-cli/src/commands/agent.rs#110. Diagram: ACP Bridge Request Flow Sources: crates/palyra-cli/src/acp_bridge.rs#31-63, crates/palyra-cli/src/commands/agent.rs#110-111.

​
Terminal User Interface (TUI)

The TUI provides a full-screen interactive terminal environment for managing sessions and chatting with agents without leaving the command line. It is built using the ratatui and crossterm libraries crates/palyra-cli/src/tui/mod.rs#7-19.

​
Key Components

​
Event Loop

The run_loop function drives the interface crates/palyra-cli/src/tui/mod.rs#148-164:
  1. Drain Events: Polls the ManagedRunStream for new tokens or tool calls from the daemon.
  2. Render: Draws the UI frames using ratatui widgets.
  3. Handle Input: Captures keystrokes via crossterm to update the input buffer or navigate the transcript.
Sources: crates/palyra-cli/src/tui/mod.rs#107-130, crates/palyra-cli/src/tui/mod.rs#148-164.

​
Agent and Session Commands

The CLI provides a suite of commands for direct agent interaction and CRUD operations on sessions.

​
Agent Commands (palyra agent ...)

​
Session Management (palyra sessions ...)

Sessions represent the persistent history and state of an agent interaction. Diagram: CLI to Daemon Entity Mapping Sources: crates/palyra-cli/src/commands/agent.rs#27-47, crates/palyra-cli/src/commands/sessions.rs#3-17, crates/palyra-cli/src/client/operator.rs#22-45.

​
Workspace Patching

A critical capability of agent commands is the ability to apply filesystem changes via apply_workspace_patch. This function enforces WorkspacePatchLimits (max bytes, max files) and performs atomic writes with rollback on failure crates/palyra-common/src/workspace_patch.rs#207-211. Sources: crates/palyra-common/src/workspace_patch.rs#23-39, crates/palyra-common/src/workspace_patch.rs#207-211.