Agent Control Protocol (ACP) Bridge
The ACP bridge is the preferred mechanism for IDE-style integrations where the client expects a stateful session lifecycle, reconnect-friendly prompts, and inline approval mediation crates/palyra-cli/data/docs/cli-v1-acp-shim.md#38-42. It operates as a bidirectional stdio bridge, translating ACP JSON-RPC requests into Palyra gRPC gateway calls.Implementation and State Management
The bridge is implemented incrates/palyra-cli/src/acp_bridge.rs. It maintains a BridgeState to track the mapping between ACP session identifiers and Palyra-specific identifiers crates/palyra-cli/src/acp_bridge.rs#39-44.
- Session Binding: The
SessionBindingstruct tracks thegateway_session_id_ulid, the user-providedsession_key, and the working directory (cwd) crates/palyra-cli/src/acp_bridge.rs#31-36. - Metadata Overrides: Clients can influence session behavior via
_metafields, includingsessionKey,sessionLabel,resetSession, andrequireExistingcrates/palyra-cli/src/acp_bridge.rs#20-23.
Data Flow: ACP to Gateway
The following diagram illustrates how an ACPprompt request is transformed into a Palyra RunStream.
Diagram: ACP Request Translation
Sources: crates/palyra-cli/src/acp_bridge.rs#47-60, crates/palyra-cli/src/acp_bridge.rs#134-150
Model Context Protocol (MCP) Facade
The MCP facade provides a narrower, stdio-oriented interface for tools that expect thetools/list and tools/call pattern crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#36-41. Unlike the stateful ACP bridge, the MCP facade is often used for indexing, retrieval, and specific mutation tasks.
Tool Surface
The MCP server exposes several tools mapped to internal Palyra services:| Tool Name | Purpose | Backend Method |
|---|---|---|
sessions_list | List active/archived sessions | LiveMcpBackend::sessions_list |
session_transcript_read | Fetch full session history | LiveMcpBackend::session_transcript_read |
memory_search | Search RAG memory items | LiveMcpBackend::memory_search |
session_prompt | Trigger a new agent run | LiveMcpBackend::session_prompt |
approval_decide | Resolve a pending human-in-the-loop prompt | LiveMcpBackend::approval_decide |
Security Posture
The MCP facade enforces strict security boundaries:- Read-Only Mode: Running with
--read-onlydisables all mutation tools (session_create,session_prompt, etc.) crates/palyra-cli/src/commands/mcp.rs#24-25. - Sensitive Tools: Mutation tools require the
--allow-sensitive-toolsflag crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#16-18. - Policy Alignment: MCP mutations reuse the existing run-stream and approval machinery. If a tool call requires human approval, the MCP result reports
status=approval_requiredcrates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#32-34.
Daemon Management & Diagnostics
Thepalyra gateway (formerly palyra daemon) command family manages the lifecycle and health of the bridge targets crates/palyra-cli/src/commands/daemon.rs#23-25.
Key Operations
- Discovery:
palyra gateway discoverprovides a trust-state report for remote dashboard access, verifying certificates and CA pins crates/palyra-cli/src/commands/daemon.rs#48-50. - Health:
palyra gateway healthprobes the HTTP and gRPC endpoints for responsiveness crates/palyra-cli/src/commands/daemon.rs#26. - Status:
palyra gateway admin-statusfetches a detailed snapshot of the daemon’s internal state, including transport details, security configuration, and journal counters crates/palyra-cli/src/commands/daemon.rs#138-162.
Support Bundle
For troubleshooting protocol failures, thesupport-bundle command aggregates diagnostics from multiple subsystems:
- System Heartbeat: Collected via
console/v1/system/heartbeatcrates/palyra-cli/src/commands/system.rs#20-23. - Presence: Aggregates state from the model provider, browserd, channels, and memory maintenance crates/palyra-daemon/src/transport/http/handlers/console/system.rs#73-108.
CLI-v1-ACP-Shim
Thecli-v1-acp-shim.md documentation defines the canonical command families for the Palyra ecosystem. It establishes a preference for modern command names over legacy aliases to ensure stability for automated integrations crates/palyra-cli/data/docs/cli-v1-acp-shim.md#69-77.
| Modern Command | Legacy Alias | Purpose |
|---|---|---|
palyra setup | palyra init | Bootstrap and packaged installation |
palyra gateway | palyra daemon | Runtime and administrative control |
palyra onboarding wizard | palyra onboard | Initial user configuration |