> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent and Session Commands

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * apps/web/src/chat/chatCommandRegistry.json
  * crates/palyra-cli/src/acp\_bridge.rs
  * crates/palyra-cli/src/args/acp.rs
  * crates/palyra-cli/src/args/agent.rs
  * crates/palyra-cli/src/args/docs.rs
  * crates/palyra-cli/src/args/hooks.rs
  * crates/palyra-cli/src/args/sessions.rs
  * crates/palyra-cli/src/client/operator.rs
  * crates/palyra-cli/src/client/runtime.rs
  * crates/palyra-cli/src/commands/acp.rs
  * crates/palyra-cli/src/commands/agent.rs
  * crates/palyra-cli/src/commands/agents.rs
  * crates/palyra-cli/src/commands/mcp.rs
  * crates/palyra-cli/src/commands/sessions.rs
  * crates/palyra-cli/src/commands/tui.rs
  * crates/palyra-cli/src/shared\_chat\_commands.rs
  * crates/palyra-cli/src/tui/mod.rs
  * crates/palyra-cli/src/tui/render.rs
  * crates/palyra-cli/src/tui/render\_helpers.rs
  * crates/palyra-cli/src/tui/slash\_palette.rs
  * crates/palyra-cli/src/tui/status.rs
  * crates/palyra-cli/tests/help\_snapshots/tui-help.txt
  * crates/palyra-cli/tests/shared\_chat\_command\_parity.md
  * crates/palyra-daemon/src/agents.rs
</details>

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](http://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](http://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](http://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](http://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**

```mermaid theme={null}
graph TD
    subgraph "CLI Space"
        A["AgentCommand::Run"] --> B["resolve_grpc_connection()"]
        B --> C["build_agent_run_input()"]
        C --> D["execute_agent_stream()"]
    end

    subgraph "Code Entities"
        D --> E["GatewayRuntimeClient::agent_run()"]
        E --> F["ManagedRunStream"]
    end

    subgraph "Daemon Space"
        F -.-> G["palyrad::GatewayService"]
        G --> H["AgentRunLoopState"]
    end
```

Sources: [crates/palyra-cli/src/commands/agent.rs#43-114](http://crates/palyra-cli/src/commands/agent.rs#43-114), [crates/palyra-cli/src/client/operator.rs#1-50](http://crates/palyra-cli/src/client/operator.rs#1-50), [crates/palyra-cli/src/args/agent.rs#11-103](http://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](http://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](http://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](http://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](http://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](http://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](http://crates/palyra-cli/src/tui/mod.rs#46-54).
* **Context**: Attaching workspace artifacts or checkpoints to the next prompt.

### TUI Implementation Structure

| Component                | Responsibility                                      | Source                                                                                          |
| :----------------------- | :-------------------------------------------------- | :---------------------------------------------------------------------------------------------- |
| `App`                    | Central state owner (session, transcript, composer) | [crates/palyra-cli/src/tui/mod.rs#216-240](http://crates/palyra-cli/src/tui/mod.rs#216-240)     |
| `render`                 | Frame layout and widget dispatch                    | [crates/palyra-cli/src/tui/render.rs#10-48](http://crates/palyra-cli/src/tui/render.rs#10-48)   |
| `TuiComposer`            | Text input handling and draft management            | [crates/palyra-cli/src/tui/composer.rs#1-30](http://crates/palyra-cli/src/tui/composer.rs#1-30) |
| `SessionRuntimeSnapshot` | Aggregated usage and metadata from Console API      | [crates/palyra-cli/src/tui/status.rs#20-96](http://crates/palyra-cli/src/tui/status.rs#20-96)   |

Sources: [crates/palyra-cli/src/tui/mod.rs#1-240](http://crates/palyra-cli/src/tui/mod.rs#1-240), [crates/palyra-cli/src/tui/render.rs#1-174](http://crates/palyra-cli/src/tui/render.rs#1-174), [crates/palyra-cli/src/tui/status.rs#1-150](http://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](http://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](http://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](http://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](http://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](http://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](http://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](http://crates/palyra-daemon/src/agents.rs#183-189).

Sources: [crates/palyra-cli/src/commands/sessions.rs#17-69](http://crates/palyra-cli/src/commands/sessions.rs#17-69), [crates/palyra-cli/src/commands/agents.rs#18-48](http://crates/palyra-cli/src/commands/agents.rs#18-48), [crates/palyra-daemon/src/agents.rs#41-65](http://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](http://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](http://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](http://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](http://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](http://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](http://crates/palyra-cli/src/commands/mcp.rs#118-122).

**Bridge and Facade Mapping**

```mermaid theme={null}
graph LR
    subgraph "External Tool"
        IDE["IDE / Editor"]
        EXT_LLM["External LLM Client"]
    end

    subgraph "Palyra CLI Bridge"
        IDE -- "JSON-RPC (ACP)" --> ACP["acp_bridge.rs"]
        EXT_LLM -- "JSON-RPC (MCP)" --> MCP["commands/mcp.rs"]
    end

    subgraph "Palyra Daemon"
        ACP --> GW["GatewayService"]
        MCP --> GW
        MCP --> MEM["MemoryService"]
    end
```

Sources: [crates/palyra-cli/src/acp\_bridge.rs#1-136](http://crates/palyra-cli/src/acp_bridge.rs#1-136), [crates/palyra-cli/src/commands/mcp.rs#1-134](http://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](http://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](http://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](http://crates/palyra-cli/src/commands/agent.rs#109-114), [crates/palyra-cli/src/args/agent.rs#84-100](http://crates/palyra-cli/src/args/agent.rs#84-100), [crates/palyra-cli/src/tui/mod.rs#37-41](http://crates/palyra-cli/src/tui/mod.rs#37-41)