ACP Bridge, MCP Facade, and TUI

This section documents the interactive and interoperability layers of the Palyra CLI. These components allow the CLI to act as a bridge between the core daemon and external environments, including IDEs (via ACP), LLM-native tools (via MCP), and human operators (via the TUI).

Agent Control Protocol (ACP) Bridge

The ACP Bridge implements the Agent Control Protocol, a stateful JSON-RPC based protocol designed for IDE integrations that require session lifecycle management, reconnect-friendly prompts, and inline approval mediation crates/palyra-cli/data/docs/cli-v1-acp-shim.md#50-53.

Implementation and State Management

The bridge is managed by the PalyraAcpAgent struct crates/palyra-cli/src/acp_bridge.rs#90-97, which coordinates communication between the ACP stdio interface and the Palyra gRPC GatewayRuntimeClient. Key state is tracked in BridgeState, which maintains mappings between ACP session identifiers and Palyra’s internal ULID-based session IDs crates/palyra-cli/src/acp_bridge.rs#39-44. This allows the bridge to support metadata overrides and session reuse across reconnections crates/palyra-cli/src/acp_bridge.rs#47-60.

Data Flow: ACP to Gateway

Request Reception: The bridge listens on stdin for NDJSON-encoded ACP requests.
Session Resolution: Upon receiving a prompt or session update, the bridge calls resolve_session on the OperatorRuntime crates/palyra-cli/src/acp_bridge.rs#203-211.
Stream Execution: Prompt requests are converted into AgentRunInput and executed via execute_agent_stream crates/palyra-cli/src/commands/agent.rs#60-73.
Permission Mediation: When the daemon requires tool approval, the bridge intercepts the request and can dispatch an ACP RequestPermission call back to the IDE crates/palyra-cli/src/acp_bridge.rs#152-165.

Metadata Overrides

The bridge supports Palyra-specific extensions via the ACP _meta field, allowing clients to control session keys, labels, and reset behavior crates/palyra-cli/src/acp_bridge.rs#197-201. Sources: crates/palyra-cli/src/acp_bridge.rs#30-165, crates/palyra-cli/src/commands/agent.rs#60-73, crates/palyra-cli/data/docs/cli-v1-acp-shim.md#40-49

Model Context Protocol (MCP) Facade

The MCP Facade (palyra mcp serve) provides a narrower, tool-oriented stdio interface. It is primarily used for read-only indexing, transcript inspection, and memory search by external LLM agents crates/palyra-cli/data/docs/cli-v1-acp-shim.md#54-55.

Capabilities

Read-Only Operations: Indexing of sessions, searching memory, and inspecting tool approvals crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#10-11.
Mutation Tools: Tools like session_prompt and approval_decide are mapped directly to the daemon’s gRPC methods, ensuring they follow the same Cedar-based policy engine and governance model as native CLI flows crates/palyra-cli/data/docs/cli-v1-acp-shim.md#56-59.

Sources: crates/palyra-cli/data/docs/cli-v1-acp-shim.md#50-59, crates/palyra-cli/src/commands/mcp.rs#1-20

Terminal UI (TUI)

The TUI provides an interactive environment for session management and real-time chat. It is built using the ratatui and crossterm libraries crates/palyra-cli/src/tui/mod.rs#7-19.

Architecture

The TUI logic is encapsulated in the App struct, which manages the terminal state, input buffers, and the ManagedRunStream for active agent interactions crates/palyra-cli/src/tui/mod.rs#107-131.

Key Components

Run Loop: The run_loop function handles event polling (50ms intervals), UI rendering, and event draining from the active gRPC stream crates/palyra-cli/src/tui/mod.rs#149-165.
Focus & Modes: The UI toggles between Focus::Transcript and Focus::Input crates/palyra-cli/src/tui/mod.rs#39-42. It supports various modes including Chat, Picker (for selecting agents/models), and Approval crates/palyra-cli/src/tui/mod.rs#45-52.
Operator Runtime: The TUI uses OperatorRuntime to perform high-level actions like resolve_session and list_models during the bootstrap phase crates/palyra-cli/src/tui/mod.rs#184-231.

TUI Rendering Logic

The UI is divided into constraints using ratatui layouts. It renders a scrollable transcript of TranscriptEntry objects, which categorize messages as User, Assistant, Tool, Thinking, or System crates/palyra-cli/src/tui/mod.rs#84-98. Sources: crates/palyra-cli/src/tui/mod.rs#27-165, crates/palyra-cli/src/client/operator.rs#1-50

Integration Diagrams

Bridge and Facade Data Flow

This diagram shows how external protocols (ACP/MCP) are translated into internal gRPC calls. Title: “Protocol Translation Flow” Sources: crates/palyra-cli/src/acp_bridge.rs#90-115, crates/palyra-cli/src/commands/mcp.rs#1-20, crates/palyra-cli/src/client/operator.rs#185-195

TUI State Machine

This diagram bridges the TUI user interface concepts to the underlying Rust structs and states. Title: “TUI Interactive State” Sources: crates/palyra-cli/src/tui/mod.rs#107-131, crates/palyra-cli/src/tui/mod.rs#149-165

CLI Command Mapping

Command Family	Purpose	Implementation File
`palyra acp`	Stateful IDE bridge	crates/palyra-cli/src/acp_bridge.rs
`palyra mcp`	Stateless tool facade	crates/palyra-cli/src/commands/mcp.rs
`palyra agent interactive`	Human-centric TUI	crates/palyra-cli/src/tui/mod.rs

Sources: crates/palyra-cli/data/docs/cli-v1-acp-shim.md#6-34, crates/palyra-cli/src/commands/agent.rs#110-112

​Agent Control Protocol (ACP) Bridge

​Implementation and State Management

​Data Flow: ACP to Gateway

​Metadata Overrides

​Model Context Protocol (MCP) Facade

​Capabilities

​Terminal UI (TUI)

​Architecture

​Key Components

​TUI Rendering Logic

​Integration Diagrams

​Bridge and Facade Data Flow

​TUI State Machine

​CLI Command Mapping