Overview
Palyra provides two primary bridging mechanisms for external agents:- ACP (Agent Control Protocol): A stateful, session-oriented bridge designed for IDE integrations and persistent agent interactions. It supports complex session lifecycle management and inline approval mediation crates/palyra-cli/data/docs/cli-v1-acp-shim.md#50-54.
- MCP (Model Context Protocol): A stateless stdio facade following the
2024-11-05protocol version crates/palyra-cli/src/commands/mcp.rs#10-11. It is optimized for tool-driven clients that expect atools/listandtools/callinterface crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#38-41.
Agent Control Protocol (ACP) Bridge
The ACP bridge is implemented incrates/palyra-cli/src/acp_bridge.rs. It acts as a translator between the JSON-RPC based ACP protocol and Palyra’s internal gRPC-based GatewayService.
Bridge Architecture and Data Flow
The bridge maintains aBridgeState to map ACP session identifiers to Palyra’s internal ULID-based session identifiers crates/palyra-cli/src/acp_bridge.rs#38-44.
ACP Bridge Component Interaction
Sources: crates/palyra-cli/src/acp_bridge.rs#90-97, crates/palyra-cli/src/client/runtime.rs#9-12
Session Management and Metadata
ACP allows clients to pass_meta fields to override session behavior. The bridge parses these in session_overrides crates/palyra-cli/src/acp_bridge.rs#197-205:
sessionKey: Explicit key for session lookup/reuse crates/palyra-cli/src/acp_bridge.rs#20-20.sessionLabel: Human-readable label crates/palyra-cli/src/acp_bridge.rs#21-21.reset_session: Force a fresh session state crates/palyra-cli/src/acp_bridge.rs#22-22.require_existing: Fail if the session key is not found crates/palyra-cli/src/acp_bridge.rs#23-23.
Model Context Protocol (MCP) Facade
The MCP implementation provides a standardmcp serve command that exposes Palyra’s capabilities as a set of discrete tools crates/palyra-cli/src/commands/mcp.rs#22-28.
MCP Tool Inventory
TheLiveMcpBackend implements the following tools crates/palyra-cli/src/commands/mcp.rs#80-108:
| Tool Name | Type | Description |
|---|---|---|
sessions_list | Read | Lists available chat sessions crates/palyra-cli/src/commands/mcp.rs#13-13. |
session_transcript_read | Read | Retrieves the full history of a session crates/palyra-cli/src/commands/mcp.rs#14-14. |
session_export | Read | Exports session to JSON or Markdown crates/palyra-cli/src/commands/mcp.rs#15-15. |
memory_search | Read | Queries the vector/FTS5 memory store crates/palyra-cli/src/commands/mcp.rs#16-16. |
approvals_list | Read | Lists pending or past tool approvals crates/palyra-cli/src/commands/mcp.rs#17-17. |
session_create | Mutation | Initializes a new agent session crates/palyra-cli/src/commands/mcp.rs#18-18. |
session_prompt | Mutation | Sends a prompt to an agent (triggers RunStream) crates/palyra-cli/src/commands/mcp.rs#19-19. |
approval_decide | Mutation | Submits a decision for a pending tool approval crates/palyra-cli/src/commands/mcp.rs#20-20. |
Security Posture
The MCP server enforces two primary flags to restrict agent behavior:--read-only: Disables all mutation tools crates/palyra-cli/src/args/mcp.rs#13-14.--allow-sensitive-tools: Explicitly enables tools that might perform destructive actions or egress crates/palyra-cli/src/args/mcp.rs#15-16.
Operator and Runtime Clients
The CLI uses specialized client modules to communicate with the daemon.OperatorRuntime
Located incrates/palyra-cli/src/client/operator.rs, this class manages high-level operations like starting run streams and handling interactive session logic crates/palyra-cli/src/client/operator.rs#15-17.
Key function: start_run_stream crates/palyra-cli/src/client/operator.rs#137-140
- Connects to the gateway.
- Prepares
AgentRunInput. - Spawns a background task to manage the bi-directional gRPC stream (
ManagedRunStream) crates/palyra-cli/src/client/operator.rs#151-154.
GatewayRuntimeClient
Located incrates/palyra-cli/src/client/runtime.rs, this is the low-level gRPC wrapper for the GatewayServiceClient crates/palyra-cli/src/client/runtime.rs#9-12. It handles raw message construction and metadata injection (e.g., principal, device ID, and auth tokens) crates/palyra-cli/src/client/runtime.rs#84-88.
Agent Command Reference
Theagent command family provides the CLI-native way to interact with agents without using ACP/MCP bridges.
palyra agent run: Executes a single prompt and streams the result crates/palyra-cli/src/commands/agent.rs#31-47.palyra agent interactive: Starts a REPL-style session supporting slash commands like/session,/reset, and/abortcrates/palyra-cli/src/commands/agent.rs#75-109.
Interactive Command Flow
Sources: crates/palyra-cli/src/commands/agent.rs#115-136, crates/palyra-cli/src/client/operator.rs#112-118, crates/palyra-cli/src/client/operator.rs#137-146Session Management Commands
Thesessions command family (crates/palyra-cli/src/commands/sessions.rs) provides administrative control over agent history:
- List/History:
runtime.list_sessionsorlist_session_catalog(via Admin Console) crates/palyra-cli/src/commands/sessions.rs#48-50, crates/palyra-cli/src/commands/sessions.rs#114-122. - Resolution:
runtime.resolve_sessionmaps keys/labels to internal ULIDs crates/palyra-cli/src/commands/sessions.rs#128-135. - Maintenance: Commands for
cleanup,abort,retry, andbranchallow manipulating active or stalled runs crates/palyra-cli/src/commands/sessions.rs#25-28. - Compaction:
CompactPreviewandCompactApplyallow reducing session token usage by summarizing history crates/palyra-cli/src/commands/sessions.rs#31-32.