Agent Control Protocol (ACP) Bridge
The ACP Bridge allows external tools (such as IDE extensions or automated scripts) to control Palyra agents via a standardized stdio-based JSON-RPC protocol. It acts as a translation layer between theagent_client_protocol and the Palyra gRPC Gateway.
Bridge Implementation
The bridge is primarily implemented incrates/palyra-cli/src/acp_bridge.rs via the PalyraAcpAgent struct crates/palyra-cli/src/acp_bridge.rs#56-63. It manages the mapping between ACP session IDs and Palyra ULID-based session identifiers using BridgeState crates/palyra-cli/src/acp_bridge.rs#39-42.
Key functionalities include:
- Metadata Overrides: Allows external clients to pass
sessionKey,sessionLabel, andresetSessionflags via the ACP_metafield crates/palyra-cli/src/acp_bridge.rs#20-23. - Permission Handling: Bridges ACP
RequestPermissioncalls to the Palyra approval system crates/palyra-cli/src/acp_bridge.rs#118-131. - Legacy Compatibility: Provides an
acp-shimfor older toolchains that expect specific legacy behaviors crates/palyra-cli/src/commands/agent.rs#110-111.
Data Flow: ACP to Gateway
The following diagram illustrates how an ACP request from an IDE is translated into a Palyra Run Stream. ACP Request Translation Flow Sources: crates/palyra-cli/src/acp_bridge.rs#31-63, crates/palyra-cli/src/acp_bridge.rs#163-170Terminal User Interface (TUI)
The Palyra TUI provides a rich, interactive environment for managing agent sessions without leaving the terminal. It is built using theratatui and crossterm crates.
TUI Architecture and State
The TUI lifecycle is managed by theApp struct crates/palyra-cli/src/tui/mod.rs#107-130. It maintains:
- Transcript: A vector of
TranscriptEntryobjects representing user, assistant, tool, and system messages crates/palyra-cli/src/tui/mod.rs#94-98. - Modes: The UI can switch between
Chat,Picker(for agents/sessions),Settings, andApprovalmodes crates/palyra-cli/src/tui/mod.rs#45-52. - Runtime: An
OperatorRuntimeinstance that handles the asynchronous gRPC communication with the daemon crates/palyra-cli/src/tui/mod.rs#108-108.
Key Components
| Component | Responsibility |
|---|---|
ManagedRunStream | Handles the background gRPC stream for a single run, emitting events to the TUI crates/palyra-cli/src/client/operator.rs#31-35. |
run_loop | The main event loop that polls for terminal events and drains stream events crates/palyra-cli/src/tui/mod.rs#148-164. |
PickerState | Manages the selection of agents or sessions within a modal overlay crates/palyra-cli/src/tui/mod.rs#76-81. |
Session Management
The CLI provides comprehensive commands for managing the lifecycle of agent sessions, including branching, history, and state recovery.Session Lifecycle Commands
Thesessions command group is defined in crates/palyra-cli/src/args/sessions.rs crates/palyra-cli/src/args/sessions.rs#4-214 and implemented in crates/palyra-cli/src/commands/sessions.rs.
- List and History:
sessions listandsessions historyallow searching and filtering existing sessions crates/palyra-cli/src/commands/sessions.rs#48-122. - Branching:
sessions branchcreates a new session from the state of an existing one, allowing for parallel exploration of different agent paths crates/palyra-cli/src/args/sessions.rs#91-97. - Checkpoints: Users can create named checkpoints within a session and restore them later crates/palyra-cli/src/args/sessions.rs#139-161.
- Export:
sessions exportallows dumping session transcripts in various formats (e.g., JSON) crates/palyra-cli/src/args/sessions.rs#105-111.
Interactive Session Handling
For standard terminal interaction (outside the full TUI),run_agent_interactive_async provides a REPL-like experience crates/palyra-cli/src/commands/agent.rs#115-135. It supports slash commands such as:
/exit: Terminate the session crates/palyra-cli/src/commands/agent.rs#145-147./reset: Reset the current session state crates/palyra-cli/src/commands/agent.rs#176-189./abort: Abort a running execution crates/palyra-cli/src/commands/agent.rs#191-204.
Workspace Patching
A critical part of session management involves the agent’s ability to modify files. Theapply_workspace_patch function in crates/palyra-common/src/workspace_patch.rs handles the atomic application of multi-file changes crates/palyra-common/src/workspace_patch.rs#207-211. It enforces security limits (e.g., max_files_touched, max_patch_bytes) and provides rollback capabilities on failure crates/palyra-common/src/workspace_patch.rs#23-39.
Sources: crates/palyra-cli/src/commands/sessions.rs#3-44, crates/palyra-cli/src/commands/agent.rs#115-154, crates/palyra-common/src/workspace_patch.rs#101-138