GatewayService gRPC Interface
TheGatewayService is the central entry point for all agent interactions. It is defined in gateway.proto and implemented by the GatewayRuntimeState in the daemon. It handles session resolution, message routing, and the streaming of run events.
Key Service Responsibilities
- Session Management: Resolving human-readable session keys to internal ULIDs and managing session metadata crates/palyra-daemon/src/gateway.rs#52-68.
- Message Routing: Ingesting inbound messages from various channels and dispatching them to the orchestrator crates/palyra-daemon/src/gateway.rs#50-54.
- Run Streaming: Managing bidirectional gRPC streams for real-time interaction with the
RunStateMachinecrates/palyra-daemon/src/application/run_stream/orchestration.rs#107-144.
Gateway Entity Mapping
The following diagram maps the high-level Gateway concepts to their specific code implementations. Diagram: Gateway Service Architecture Sources: crates/palyra-daemon/src/gateway.rs#40-82, crates/palyra-daemon/src/application/run_stream/orchestration.rs#107-113Run Lifecycle and State Machine
Every interaction with an agent is encapsulated in a Run. TheRunStateMachine governs the transition of a run through its various phases, ensuring consistency and auditability.
Run States
A run progresses through theRunLifecycleState enum crates/palyra-daemon/src/orchestrator.rs#26-27:
- Pending: Initial state after creation.
- InProgress: The model is actively generating or tools are executing.
- AwaitingApproval: A tool call has been intercepted and requires user intervention.
- Done: Successful completion.
- Cancelled: Terminated by user or system policy.
- Failed: Encountered an unrecoverable error.
State Transitions
Transitions are triggered byRunTransition events crates/palyra-daemon/src/application/run_stream/orchestration.rs#198-203. For example, calling StartStreaming moves a run from Pending to InProgress.
Diagram: Run Lifecycle State Machine
Sources: crates/palyra-daemon/src/orchestrator.rs#26-27, crates/palyra-daemon/src/application/run_stream/orchestration.rs#124-141
Tape-Based Event Sourcing
Palyra uses a “Tape” metaphor for event sourcing. Every significant action within a run (input, model output, tool call, tool result) is recorded as anOrchestratorTapeRecord in the JournalStore.
Tape Structure
| Field | Description |
|---|---|
run_id | ULID identifying the specific run crates/palyra-daemon/src/journal.rs#69-71. |
seq | Monotonically increasing sequence number within the run. |
event_type | Type of event (e.g., input, thought, tool_call, status). |
payload_json | The actual data associated with the event. |
JournalStore
TheJournalStore is a SQLite-backed persistence layer crates/palyra-daemon/src/journal.rs#13-17. It provides atomic appending of tape records via append_orchestrator_tape and ensures that the history of a session can be reconstructed for “long-term memory” or session branching.
Sources: crates/palyra-daemon/src/journal.rs#56-71, crates/palyra-daemon/src/gateway.rs#89-103
Run Dispatch and Execution Flow
When a message arrives, theGatewayRuntimeState initiates the orchestration flow:
- Session Resolution: The
resolve_orchestrator_sessionfunction identifies the correct session context crates/palyra-daemon/src/gateway.rs#52-68. - Input Preparation:
prepare_model_provider_inputaugments the user’s text with retrieved memories and session context crates/palyra-daemon/src/application/provider_input.rs#53-64. - Model Execution: The
execute_model_providerfunction sends the prepared prompt to the configured LLM crates/palyra-daemon/src/application/run_stream/orchestration.rs#155-163. - Event Processing: Model outputs are streamed back to the client and simultaneously appended to the tape.
- Tool Interception: If the model requests a tool, the
execute_tool_calllogic checks policies and potentially transitions the run toAwaitingApprovalcrates/palyra-daemon/src/gateway.rs#78-81.
Session Compaction
To manage context window limits, the system performsSessionCompaction. This process summarizes older tape events into OrchestratorCompactionArtifactRecord entries, allowing the run to continue without losing critical context crates/palyra-daemon/src/application/session_compaction.rs#31-36.
Sources: crates/palyra-daemon/src/application/run_stream/orchestration.rs#147-183, crates/palyra-daemon/src/application/provider_input.rs#159-171, crates/palyra-daemon/src/application/session_compaction.rs#76-94