Agent and Session Commands

This section covers the command-line interfaces and interactive environments provided by the palyra-cli for managing agents and sessions. It details the transition from one-shot command execution to the interactive Terminal User Interface (TUI), and the protocols (ACP/MCP) used to bridge Palyra with external editors and LLM clients.

​

Agent Run and Interactive Lifecycle

The palyra agent command family is the primary entry point for executing model-driven runs. It supports two main modes: one-shot execution via palyra agent run and an interactive terminal session via palyra agent interactive crates/palyra-cli/src/commands/agent.rs#43-46.

​

One-Shot Runs (agent run)

The run_agent function dispatches the Run subcommand, which builds an AgentRunInput request based on provided arguments like --prompt, --session-id, and --approval-mode crates/palyra-cli/src/commands/agent.rs#47-107. It uses execute_agent_stream to manage the gRPC stream of events from the daemon, handling real-time output and automatic continuation runs if --auto-resume is enabled crates/palyra-cli/src/commands/agent.rs#109-114.

​

Interactive Sessions (agent interactive)

The interactive mode initializes a full TUI environment. It resolves a gRPC connection and blocks on run_agent_interactive_async, which manages the terminal lifecycle and user input loop crates/palyra-cli/src/commands/agent.rs#123-164.

​

Execution Data Flow

The following diagram illustrates the data flow from a CLI command into the Gateway gRPC service. CLI to Gateway Run Dispatch Sources: crates/palyra-cli/src/commands/agent.rs#43-114, crates/palyra-cli/src/client/operator.rs#1-50, crates/palyra-cli/src/args/agent.rs#11-103

​

Terminal User Interface (TUI)

The Palyra TUI is a ratatui-based interactive environment that provides a rich interface for agent interaction, workspace management, and session control crates/palyra-cli/src/tui/mod.rs#1-6.

​

Layout and Rendering

The TUI frame is divided into four functional areas:

1. Header: Displays gRPC endpoint, session identity, active agent, and model status crates/palyra-cli/src/tui/render.rs#52-81.
2. Transcript: The central scrollable area showing user prompts, assistant responses, tool executions, and thinking blocks crates/palyra-cli/src/tui/render.rs#159-174.
3. Composer: A multi-line input area with support for draft persistence and token estimation crates/palyra-cli/src/tui/render.rs#11-26.
4. Footer: Displays session usage metrics (tokens, cost, latency) and context budget warnings crates/palyra-cli/src/tui/render.rs#32-33.

​

The Slash Palette

The TUI features a “slash palette” triggered by the / key. This overlay provides searchable access to:

• Commands: /workspace, /rollback, /compact, /settings.
• Entities: Picking agents, sessions, or model profiles crates/palyra-cli/src/tui/mod.rs#46-54.
• Context: Attaching workspace artifacts or checkpoints to the next prompt.

​

TUI Implementation Structure

Sources: crates/palyra-cli/src/tui/mod.rs#1-240, crates/palyra-cli/src/tui/render.rs#1-174, crates/palyra-cli/src/tui/status.rs#1-150

​

Session and Agent Management

The CLI provides comprehensive CRUD and resolution tools for managing the state of the daemon’s agent registry and session history.

​

Session Lifecycle

The palyra sessions command interacts with both the Gateway gRPC service (for session resolution and runs) and the Admin Console HTTP API (for queue control, checkpoints, and background tasks) crates/palyra-cli/src/commands/sessions.rs#1-6.

• Resolution: SessionsCommand::Resolve converts keys or labels into concrete ULIDs crates/palyra-cli/src/commands/sessions.rs#50-63.
• Compaction: CompactPreview and CompactApply allow operators to prune long transcripts to stay within model context limits crates/palyra-cli/src/commands/sessions.rs#184-210.
• Checkpoints: Users can create and restore session checkpoints to branch or undo assistant actions crates/palyra-cli/src/commands/sessions.rs#211-220.

​

Agent Registry

The palyra agents command manages the AgentRecord entries stored in agents.toml on the daemon crates/palyra-daemon/src/agents.rs#1-10.

• Sticky Bindings: AgentRegistry::bind_agent_for_context pins a specific agent to a (principal, channel, session_id) triplet so future turns in that session use the same agent configuration crates/palyra-daemon/src/agents.rs#122-138.
• Identity: AgentsCommand::Identity resolves the effective agent for the current CLI context based on the precedence: Session Binding > Default Agent > Fallback crates/palyra-daemon/src/agents.rs#183-189.

Sources: crates/palyra-cli/src/commands/sessions.rs#17-69, crates/palyra-cli/src/commands/agents.rs#18-48, crates/palyra-daemon/src/agents.rs#41-65

​

External Protocols: ACP and MCP

Palyra implements two standard protocols to allow external tools to drive the agent loop.

​

ACP (Agent Client Protocol) Bridge

The AcpBridge exposes the Palyra gateway as an ACP agent. This allows IDEs (like VS Code or JetBrains) to manage sessions and prompts over JSON-RPC crates/palyra-cli/src/acp_bridge.rs#1-4.

• State Mapping: BridgeState maintains an in-memory mapping between ACP session IDs and Gateway session ULIDs crates/palyra-cli/src/acp_bridge.rs#130-136.
• Permission Bridge: ACP approval requests are translated into common_v1::ToolApprovalRequest calls on the gateway crates/palyra-cli/src/acp_bridge.rs#33-38.

​

MCP (Model Context Protocol) Facade

The palyra mcp serve command provides an MCP server facade. This allows other LLM clients (like Claude Desktop) to use Palyra as a “tool” crates/palyra-cli/src/commands/mcp.rs#1-5.

• Exposed Tools: It surfaces tools like sessions_list, memory_search, and session_prompt to the external client crates/palyra-cli/src/commands/mcp.rs#19-26.
• Read-Only Mode: The --read-only flag disables mutating tools (like session_prompt or approval_decide) to prevent external clients from modifying Palyra state crates/palyra-cli/src/commands/mcp.rs#118-122.

Bridge and Facade Mapping Sources: crates/palyra-cli/src/acp_bridge.rs#1-136, crates/palyra-cli/src/commands/mcp.rs#1-134

​

Replay and Resume System

Palyra’s run system is designed for resilience and interruption.

• Interrupt and Replay: The --interrupt-active-run flag allows the CLI to abort a current daemon-side run and immediately start a new prompt in the same session crates/palyra-cli/src/args/agent.rs#84-90.
• Auto-Resume: When a model run hits a token limit or requires a continuation (e.g., long tool chains), the CLI can automatically trigger a follow-up run via AgentAutoResumeArg::OnContinuation crates/palyra-cli/src/args/agent.rs#161-164.
• Rollback: Within the TUI, the /rollback command (implemented in tui/rollback.rs) allows the operator to revert the session to a previous checkpoint recorded in the JournalStore.

Sources: crates/palyra-cli/src/commands/agent.rs#109-114, crates/palyra-cli/src/args/agent.rs#84-100, crates/palyra-cli/src/tui/mod.rs#37-41