palyrad), exposing a high-performance gRPC interface for agent interaction, session management, and administrative control. It implements the palyra.gateway.v1.GatewayService and manages the lifecycle of bidirectional streams used for agent execution.
gRPC Service Architecture
The Gateway is implemented as a centralGatewayRuntimeState crates/palyra-daemon/src/gateway.rs#141-141 which coordinates several specialized gRPC service implementations. It handles authentication, request routing, and state persistence through the Journal.
Core Services
The daemon hosts several gRPC services on the same port:- GatewayService: Handles agent runs (
RunStream), message routing (RouteMessage), and agent/session management. - AuthService: Manages authentication profiles and credentials crates/palyra-daemon/src/gateway.rs#42-44.
- VaultService: Provides secure secret storage and retrieval crates/palyra-daemon/src/gateway.rs#43-43.
- CronService: Manages scheduled routines and automated tasks crates/palyra-daemon/src/gateway.rs#43-43.
Connection Management
The Gateway supports both standard gRPC (over TCP/TLS) and QUIC-based transport if enabled in the configuration crates/palyra-daemon/src/gateway/runtime.rs#42-44.Bidirectional Run Streaming
TheRunStream RPC is the core protocol for agent interaction. It uses a bidirectional gRPC stream to allow real-time communication between the client (CLI/Web Console) and the Orchestrator.
Protocol Flow
- Initiation: Client sends a
RunStreamRequestcontaining aRunStartRequestcrates/palyra-daemon/src/gateway.rs#67-67. - State Transition: The
RunStateMachinetransitions the run toInProgresscrates/palyra-daemon/src/application/run_stream/orchestration.rs#198-203. - Event Loop: The daemon streams
RunStreamEventmessages to the client. These include:StatusUpdate: Changes in the run lifecycle (e.g.,Started,Done) crates/palyra-daemon/src/application/run_stream/orchestration.rs#204-211.TapeEntry: Incremental updates to the run history (text, tool calls, etc.) crates/palyra-daemon/src/application/run_stream/orchestration.rs#132-139.
- Client Input: Clients can send
RouteMessageorCancelRequestmid-stream crates/palyra-daemon/src/application/run_stream/orchestration.rs#114-118.
Data Flow: RunStream Initiation
The following diagram bridges the Protobuf definitions to the internal Rust orchestration logic. “RunStream Protocol Logic” Sources: crates/palyra-daemon/src/gateway.rs#67-68, crates/palyra-daemon/src/application/run_stream/orchestration.rs#186-211, crates/palyra-daemon/src/orchestrator.rs#29-29Session & Agent Management
The Gateway manages the mapping between Principals, Devices, and Sessions.Key Entities
| Entity | Code Reference | Description |
|---|---|---|
| Principal | HEADER_PRINCIPAL | The identity string (e.g., user:alice) crates/palyra-daemon/src/gateway.rs#86-86. |
| Device ID | HEADER_DEVICE_ID | A ULID identifying the specific client hardware crates/palyra-daemon/src/gateway.rs#87-87. |
| Session | OrchestratorSessionRecord | A persistent container for a conversation thread crates/palyra-daemon/src/gateway.rs#68-68. |
| Agent | AgentRecord | Configuration defining model, tools, and system prompt crates/palyra-daemon/src/gateway.rs#47-47. |
Message Routing
TheRouteMessage function handles inbound messages from various channels (CLI, Discord, Slack). It validates the CanonicalId of the target session crates/palyra-daemon/src/gateway.rs#22-22 and appends the message to the Journal crates/palyra-daemon/src/gateway.rs#63-63.
Implementation Details
Security & Authentication
The Gateway enforces authentication viaGatewayAuthConfig crates/palyra-daemon/src/gateway.rs#40-40. Requests must typically include a Bearer token and context headers:
x-palyra-principal: Identifies the user or service crates/palyra-daemon/src/gateway.rs#86-86.x-palyra-device-id: Identifies the device crates/palyra-daemon/src/gateway.rs#87-87.x-palyra-channel: Identifies the transport (e.g.,cli,web) crates/palyra-daemon/src/gateway.rs#88-88.
admin_auth_token configured in the daemon crates/palyra-common/src/daemon_config_schema.rs#13-13.
Resource Constraints
The Gateway enforces strict limits on payload sizes and processing latency to ensure system stability:- Journal Write Latency: Budget of 25ms crates/palyra-daemon/src/gateway.rs#92-92.
- Tool Execution Latency: Budget of 200ms crates/palyra-daemon/src/gateway.rs#93-93.
- Memory Item Size: Max 16KB per item crates/palyra-daemon/src/gateway.rs#118-118.
- Cron Job Name: Max 128 bytes crates/palyra-daemon/src/gateway.rs#104-104.
Component Mapping
This diagram maps the gRPC service names to their implementation files and state management. “gRPC Service to Code Entity Mapping” Sources: crates/palyra-daemon/src/gateway.rs#41-44, crates/palyra-daemon/src/gateway/runtime.rs#38-58, crates/palyra-daemon/src/journal.rs#63-63Background Queue Integration
The Gateway interacts with theBackgroundQueue to process long-running tasks like “post-run reflection” crates/palyra-daemon/src/background_queue.rs#12-12. When a run completes, the Gateway may schedule a task in the background queue to update memory or evaluate run performance crates/palyra-daemon/src/application/run_stream/orchestration.rs#11-12.
Sources: crates/palyra-daemon/src/gateway.rs#1-102, crates/palyra-daemon/src/gateway/runtime.rs#1-133, crates/palyra-daemon/src/application/run_stream/orchestration.rs#107-144, crates/palyra-daemon/src/background_queue.rs#31-44.