> ## 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.

# Gateway Runtime and Session Lifecycle

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

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

  * crates/palyra-cli/src/args/commitments.rs
  * crates/palyra-cli/src/args/tasks.rs
  * crates/palyra-cli/src/commands/commitments.rs
  * crates/palyra-cli/src/commands/tasks.rs
  * crates/palyra-cli/tests/help\_snapshots/commitments-help.txt
  * crates/palyra-common/src/tool\_catalog.rs
  * crates/palyra-daemon/src/acceptance.rs
  * crates/palyra-daemon/src/application/channel\_turn/mod.rs
  * crates/palyra-daemon/src/application/context\_engine.rs
  * crates/palyra-daemon/src/application/context\_references.rs
  * crates/palyra-daemon/src/application/mod.rs
  * crates/palyra-daemon/src/application/route\_message/orchestration.rs
  * crates/palyra-daemon/src/application/run\_stream/agent\_loop.rs
  * crates/palyra-daemon/src/application/run\_stream/orchestration.rs
  * crates/palyra-daemon/src/application/run\_stream/tool\_flow\.rs
  * crates/palyra-daemon/src/application/tool\_runtime/mod.rs
  * crates/palyra-daemon/src/commitments.rs
  * crates/palyra-daemon/src/flows.rs
  * crates/palyra-daemon/src/gateway.rs
  * crates/palyra-daemon/src/gateway/common.rs
  * crates/palyra-daemon/src/gateway/runtime.rs
  * crates/palyra-daemon/src/journal.rs
  * crates/palyra-daemon/src/lib.rs
  * crates/palyra-daemon/src/orchestrator.rs
  * crates/palyra-daemon/src/task\_runtime.rs
  * crates/palyra-daemon/src/tool\_posture.rs
  * crates/palyra-daemon/src/tool\_protocol.rs
  * crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/commitments.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/tasks.rs
  * crates/palyra-daemon/src/transport/http/router.rs
  * crates/palyra-daemon/tests/gateway\_grpc.rs
  * crates/palyra-daemon/tests/golden/current\_state\_inventory.json
  * crates/palyra-daemon/tests/golden/run\_tape\_basic.json
</details>

The Gateway Runtime is the central coordination hub of the Palyra daemon (`palyrad`). It manages the lifecycle of **Sessions** (durable conversation threads) and **Runs** (active agent execution turns), providing the state machinery required to bridge external transports (gRPC, HTTP) with the internal agent loop, tool execution, and the journal audit system.

## GatewayRuntimeState: The System Hub

`GatewayRuntimeState` is the shared, thread-safe state container that persists across the daemon's lifetime. It serves as the primary interface for all transport surfaces to interact with the underlying `JournalStore` and specialized runtimes (Memory, Skills, Workers).

### Key Responsibilities

* **Persistence Orchestration**: Synchronous SQLite access via `JournalStore` wrapped in `tokio::task::spawn_blocking` for transport-friendly async APIs [crates/palyra-daemon/src/gateway/runtime.rs#15-19](http://crates/palyra-daemon/src/gateway/runtime.rs#15-19).
* **Run Notification**: Managing `orchestrator_run_notify` for run-completion wakeups and cancel flags [crates/palyra-daemon/src/gateway/runtime.rs#9-11](http://crates/palyra-daemon/src/gateway/runtime.rs#9-11).
* **Policy & Admission**: Handling provider lease admission, tool execution limits, and approval decision caching [crates/palyra-daemon/src/gateway/runtime.rs#10-12](http://crates/palyra-daemon/src/gateway/runtime.rs#10-12).

### Data Flow: Inbound to Dispatch

The following diagram illustrates how a message travels from a transport layer through the `GatewayRuntimeState` into the orchestrator.

**Message Admission & State Association**

```mermaid theme={null}
graph TD
    subgraph "Transport Layer"
        A["Axum HTTP / Tonic gRPC"] --> B["RequestContext"]
    end

    subgraph "GatewayRuntimeState [crates/palyra-daemon/src/gateway/runtime.rs]"
        B --> C["resolve_session_blocking"]
        C --> D["OrchestratorSessionRecord"]
        D --> E["RunStateMachine [crates/palyra-daemon/src/orchestrator.rs]"]
    end

    subgraph "Journal Storage [crates/palyra-daemon/src/journal.rs]"
        D -.-> F[("SQLite: orchestrator_sessions")]
        E -.-> G[("SQLite: orchestrator_runs")]
    end

    E --> H["AgentRunLoopState"]
```

**Sources:** [crates/palyra-daemon/src/gateway/runtime.rs#26-48](http://crates/palyra-daemon/src/gateway/runtime.rs#26-48), [crates/palyra-daemon/src/orchestrator.rs#1-10](http://crates/palyra-daemon/src/orchestrator.rs#1-10), [crates/palyra-daemon/src/journal.rs#1-9](http://crates/palyra-daemon/src/journal.rs#1-9).

## Run and Session State Machine

Palyra distinguishes between a **Session** (the long-lived context) and a **Run** (a single execution attempt). A session can have many runs, but only one active run at a time is enforced by the `RunStateMachine`.

### Run Lifecycle States (`RunLifecycleState`)

The state machine tracks the progression of an agent turn:

1. **Queued**: The run is created but not yet active.
2. **Running**: The agent loop is actively processing provider turns or tools.
3. **Waiting**: The run is suspended awaiting operator approval or external input.
4. **Terminal**: The run has ended (Completed, Cancelled, or Failed).

**State Transition Logic**

```mermaid theme={null}
stateDiagram-v2
    [*] --> "Queued" : "OrchestratorRunStartRequest"
    "Queued" --> "Running" : "RunTransition::Start"
    "Running" --> "Waiting" : "Approval Required"
    "Waiting" --> "Running" : "Approval Decision / Resume"
    "Running" --> "Terminal" : "Final Answer / Error / Cancel"
    "Terminal" --> [*]
```

**Sources:** [crates/palyra-daemon/src/orchestrator.rs#107-107](http://crates/palyra-daemon/src/orchestrator.rs#107-107), [crates/palyra-daemon/src/gateway/runtime.rs#8-12](http://crates/palyra-daemon/src/gateway/runtime.rs#8-12).

## The Orchestrator and Agent Loop

The `process_run_stream_message` function in `orchestration.rs` is the entry point for the streaming agent loop. It coordinates provider turns, tool execution, and tape recording.

### The Agent Loop (`AgentRunLoopState`)

The loop iterates through the following phases:

* **Context Assembly**: Gathering session history, memory, and workspace state via the `InstructionCompiler` [crates/palyra-daemon/src/application/run\_stream/orchestration.rs#33-36](http://crates/palyra-daemon/src/application/run_stream/orchestration.rs#33-36).
* **Provider Turn**: Sending the assembled prompt to the LLM and handling streaming events [crates/palyra-daemon/src/application/run\_stream/orchestration.rs#29-32](http://crates/palyra-daemon/src/application/run_stream/orchestration.rs#29-32).
* **Tool Proposal**: If the model requests tools, the `tool_flow` module handles intake and gating [crates/palyra-daemon/src/application/run\_stream/tool\_flow.rs#1-10](http://crates/palyra-daemon/src/application/run_stream/tool_flow.rs#1-10).
* **Finalization**: Once a final answer is reached, the loop verifies the "Final Answer Contract" before terminating [crates/palyra-daemon/src/application/run\_stream/agent\_loop.rs#74-79](http://crates/palyra-daemon/src/application/run_stream/agent_loop.rs#74-79).

### Tape: The Deterministic Journal

Every observable event in the agent loop is mirrored to the **Orchestrator Tape**. This is an append-only log in the journal that allows for deterministic replay and auditability of agent decisions [crates/palyra-daemon/src/application/run\_stream/orchestration.rs#7-9](http://crates/palyra-daemon/src/application/run_stream/orchestration.rs#7-9).

**Agent Loop Execution Flow**

| Phase         | Entity                          | Role                                                                                                                                                                                                      |
| :------------ | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Intake**    | `InboundCoalescer`              | Merges rapid-fire messages into a single turn [crates/palyra-daemon/src/application/inbound\_coalescer.rs#1-10](http://crates/palyra-daemon/src/application/inbound_coalescer.rs#1-10).                   |
| **Planning**  | `plan_usage_routing`            | Selects the model provider and budget [crates/palyra-daemon/src/application/run\_stream/orchestration.rs#69-69](http://crates/palyra-daemon/src/application/run_stream/orchestration.rs#69-69).           |
| **Execution** | `tool_flow`                     | Manages parallel tool execution and approval gates [crates/palyra-daemon/src/application/run\_stream/tool\_flow.rs#138-150](http://crates/palyra-daemon/src/application/run_stream/tool_flow.rs#138-150). |
| **Recording** | `OrchestratorTapeAppendRequest` | Persists every step to the journal [crates/palyra-daemon/src/application/run\_stream/orchestration.rs#48-52](http://crates/palyra-daemon/src/application/run_stream/orchestration.rs#48-52).              |

**Sources:** [crates/palyra-daemon/src/application/run\_stream/orchestration.rs#1-15](http://crates/palyra-daemon/src/application/run_stream/orchestration.rs#1-15), [crates/palyra-daemon/src/application/run\_stream/tool\_flow.rs#1-11](http://crates/palyra-daemon/src/application/run_stream/tool_flow.rs#1-11).

## Inbound Message Admission & Coalescing

Before a run begins, inbound messages from external platforms (Slack, Discord, etc.) pass through the `InboundCoalescer`. This component prevents "race conditions" where multiple messages arrive in quick succession, ensuring they are processed as a single logical turn for the agent [crates/palyra-daemon/src/application/inbound\_coalescer.rs#1-10](http://crates/palyra-daemon/src/application/inbound_coalescer.rs#1-10).

### Channel Turn Lifecycle

1. **Admission**: The `ChannelRouter` identifies the principal and session.
2. **Coalescing**: Messages are buffered for a short window.
3. **Dispatch**: The coalesced payload is sent to `process_run_stream_message`.
4. **Delivery**: The agent's response is routed back through the `OutboundLifecycle`.

**Sources:** [crates/palyra-daemon/src/gateway.rs#79-83](http://crates/palyra-daemon/src/gateway.rs#79-83), [crates/palyra-daemon/src/application/mod.rs#47-48](http://crates/palyra-daemon/src/application/mod.rs#47-48).