GatewayRuntimeState
TheGatewayRuntimeState is the primary shared state object for the daemon. It encapsulates access to the JournalStore, AgentRegistry, ModelProvider, and various runtime configurations crates/palyra-daemon/src/gateway.rs#141-174. It provides the high-level API for session management, run execution, and administrative inspection.
Key Responsibilities
- Session Resolution: Mapping incoming requests (via
session_keyorsession_id) to anOrchestratorSessionRecordcrates/palyra-daemon/src/gateway.rs#1044-1100. - Run Orchestration: Initializing and stepping the
RunStateMachinecrates/palyra-daemon/src/gateway.rs#1455-1480. - Tape Management: Appending events to the append-only “tape” for a specific run crates/palyra-daemon/src/gateway.rs#1630-1650.
- Approval Flow: Intercepting sensitive tool calls and managing the
PendingToolApprovallifecycle crates/palyra-daemon/src/gateway.rs#135-142.
Run Lifecycle and State Machine
Every interaction with an agent is encapsulated in a Run. Runs follow a strict state transition model defined in theRunStateMachine crates/palyra-daemon/src/orchestrator.rs#77-77.
Lifecycle States
| State | Description |
|---|---|
Accepted | The run has been created and persisted but not yet processed crates/palyra-daemon/src/journal.rs#186-186. |
Running | The orchestrator is actively processing the run (e.g., calling an LLM or executing a tool) crates/palyra-daemon/src/journal.rs#187-187. |
Succeeded | The run completed its objective successfully crates/palyra-daemon/src/journal.rs#188-188. |
Failed | The run terminated due to an error (e.g., provider failure, timeout) crates/palyra-daemon/src/journal.rs#189-189. |
Run Execution Flow
Theorchestrator_run_start function initiates the lifecycle crates/palyra-daemon/src/gateway.rs#1455-1455. It prepares the ProviderRequest by aggregating historical tape events, system prompts, and current user input crates/palyra-daemon/src/application/provider_input.rs#53-64.
Sources: crates/palyra-daemon/src/orchestrator.rs#77-77, crates/palyra-daemon/src/journal.rs#185-193, crates/palyra-daemon/src/gateway.rs#1455-1480
The Orchestrator Loop
The orchestration engine operates on a loop that processesRunStreamRequest envelopes. It bridges the gap between the Natural Language Space (User Input) and the Code Entity Space (Tool Execution).
Run Stream Logic
Theconsole_chat_message_stream_handler sets up a multi-step execution pipeline crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#139-182:
- Input Preparation: Normalizes text and attachments crates/palyra-daemon/src/application/provider_input.rs#108-156.
- Context Augmentation: Injects relevant memory items into the prompt based on semantic similarity crates/palyra-daemon/src/application/provider_input.rs#159-200.
- Provider Invocation: Sends the augmented prompt to the
ModelProvider. - Tool Dispatch: If the model requests a tool call, the orchestrator evaluates the
Cedarpolicy and either executes the tool in a sandbox or creates aPendingToolApprovalcrates/palyra-daemon/src/gateway.rs#78-81.
Run Execution Diagram
Title: Orchestration Execution Flow Sources: crates/palyra-daemon/src/gateway.rs#1455-1480, crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#139-182, crates/palyra-daemon/src/application/provider_input.rs#53-64Tape Event Logging
The “Tape” is a sequential, append-only log of every event that occurs within a run. It is stored in theorchestrator_tape table of the JournalStore crates/palyra-daemon/src/journal.rs#69-70.
Event Types
- Input: The original user message and parameters.
- ProviderRequest/Response: Full snapshots of the interaction with the LLM.
- ToolCall: The arguments sent to a specific skill.
- ToolOutput: The result returned from the sandbox.
- ApprovalRequest/Decision: Human-in-the-loop interactions.
run_id and a monotonic seq number crates/palyra-daemon/src/journal.rs#26-26. This allows the orchestrator to “re-read” the tape to reconstruct context for subsequent turns.
Sources: crates/palyra-daemon/src/journal.rs#63-70, crates/palyra-daemon/src/gateway.rs#1630-1650
Session Management
Sessions provide long-term persistence across multiple runs. They are identified by asession_id (ULID) and an optional session_key (human-readable alias) crates/palyra-daemon/src/journal.rs#68-68.
Session Resolution
When a message arrives via a channel (e.g., Discord, CLI, or Web Console), theresolve_orchestrator_session function is called crates/palyra-daemon/src/gateway.rs#1044-1044. It performs the following:
- Lookup: Finds an existing session by
session_keyorsession_idcrates/palyra-daemon/src/gateway.rs#1052-1065. - Creation: If not found and permitted, creates a new
OrchestratorSessionRecord. - Context Binding: Associates the session with a specific
principalanddevice_idcrates/palyra-daemon/src/gateway.rs#1066-1080.
Session State Diagram
Title: Session Resolution and Mapping Sources: crates/palyra-daemon/src/gateway.rs#1044-1100, crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#36-69, crates/palyra-daemon/src/journal.rs#68-68Administrative and Operational Control
The Gateway exposes endpoints for managing active runs and inspecting the system state.- Run Cancellation: The
orchestrator_cancel_runfunction allows terminating aRunningstate run, which is vital for long-running tool executions crates/palyra-daemon/src/gateway.rs#1520-1540. - Recent Events: The
list_recent_journal_eventsAPI provides a real-time snapshot of system activity for the Admin Dashboard crates/palyra-daemon/src/gateway.rs#1700-1720. - Usage Tracking:
get_orchestrator_usage_summaryaggregates token counts and tool execution metrics per principal crates/palyra-daemon/src/gateway/runtime.rs#18-19.