Skip to main content
The Gateway and Orchestration Engine is the central nervous system of the palyrad daemon. It manages the high-level lifecycle of agent interactions, bridging external communication channels (Discord, CLI, Web Console) with the internal execution logic (LLM providers, tool execution, and the Run State Machine).

​
GatewayRuntimeState

The GatewayRuntimeState serves as the primary container for the daemon’s active operational state. It holds references to the JournalStore, ModelProvider, ChannelRouter, and the Vault, coordinating their interactions during a run.

​
Key Responsibilities

​
Configuration Snapshot

The runtime behavior is governed by GatewayRuntimeConfigSnapshot, which defines limits for tape entries, gRPC/QUIC binding addresses, and specific sub-engine configs like BrowserServiceRuntimeConfig and CanvasHostRuntimeConfig crates/palyra-daemon/src/gateway/runtime.rs#29-49.

​
Run State Machine (RSM)

The RunStateMachine manages the transition of a “Run” through its lifecycle. A Run is a single unit of execution triggered by a user prompt or a scheduled event.

​
Lifecycle States

Runs transition through the following RunLifecycleState values crates/palyra-daemon/src/orchestrator.rs#77-77:
  1. Accepted: The run has been created and queued.
  2. Preparing: Context is being gathered (memory recall, attachment processing).
  3. Running: The LLM is being queried or tools are being executed.
  4. AwaitingApproval: Execution is paused pending a user decision on a sensitive tool.
  5. Succeeded/Failed/Cancelled: Terminal states.

​
Data Flow: Natural Language to Code Entities

The following diagram illustrates how a natural language message from a user is transformed into internal code entities within the Gateway. Sources: crates/palyra-daemon/src/gateway.rs#42-54, crates/palyra-daemon/src/gateway/runtime.rs#1-25, crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs

​
Session, Run, and Tape Lifecycle

Palyra uses a hierarchical data model to maintain context and history:
EntityCode SymbolPersistenceScope
SessionOrchestratorSessionRecordJournalStoreLong-lived conversation thread between a Principal and an Agent.
RunOrchestratorRunRecordJournalStoreA single execution “turn” (User -> Assistant -> Tools).
TapeOrchestratorTapeRecordJournalStoreAn append-only log of events (messages, tool calls, logs) within a Run.

​
Tape Event Management

The “Tape” is an immutable ledger of what happened during a run. GatewayRuntimeState enforces limits such as MAX_MODEL_TOKEN_TAPE_EVENTS_PER_RUN (1024) to prevent context window overflow crates/palyra-daemon/src/gateway.rs#103-103. Sources: crates/palyra-daemon/src/journal.rs#67-69, crates/palyra-daemon/src/gateway.rs#89-105

​
gRPC GatewayService

The GatewayService (implemented via Tonic) is the primary API for all clients.

​
Key RPC Methods

Sources: crates/palyra-daemon/src/gateway.rs#84-88, crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs

​
Channel Routing and Pairing

The ChannelRouter manages how different platforms (CLI, Discord, Web) interact with the gateway.

​
Pairing Workflow

For non-trusted channels (like Discord DMs), Palyra uses a pairing flow to bind a platform identity to a Palyra principal:
  1. Generate Code: palyra channels pairing-code generate.
  2. Consume Code: User sends /pair <code> in the external channel.
  3. Approval: The operator approves the PairingPendingRecord via the console crates/palyra-daemon/src/channel_router.rs#94-101.

​
Security Labels

Inbound messages can carry security_labels which influence policy evaluation during the run crates/palyra-daemon/tests/gateway_grpc.rs#146-155. Sources: crates/palyra-daemon/src/channel_router.rs#112-118, crates/palyra-daemon/src/channels.rs#160-179

​
Tool Approval Workflow

When a run attempts to execute a tool marked as sensitive (e.g., shell_execute), the engine triggers the approval workflow.

​
Process Flow

  1. Policy Hit: evaluate_with_config returns PolicyDecision::Allow but with approval_required: true crates/palyra-daemon/tests/admin_surface.rs#110-120.
  2. Suspend: The RunStateMachine transitions to AwaitingApproval.
  3. Notification: An ApprovalRecord is created in the JournalStore crates/palyra-daemon/src/gateway.rs#58-59.
  4. Resolution: The operator provides an ApprovalDecision (Approve/Deny) via the GatewayService::ResolveApproval RPC.

​
Risk Levels

Approvals are categorized by ApprovalRiskLevel (Low, Medium, High, Critical) based on the tool’s metadata and the resource being accessed crates/palyra-daemon/src/gateway.rs#58-59. Sources: crates/palyra-daemon/src/gateway.rs#95-102, crates/palyra-daemon/src/gateway/runtime.rs#129-136, crates/palyra-daemon/src/journal.rs#57-59