palyrad), the browser daemon (palyra-browserd), and various clients (CLI, Web Console, and Desktop Companion).
Overview and Pipeline
Palyra uses a contract-first design where all cross-process communication is defined in.proto files located in schemas/proto/palyra/v1/. These definitions are used to generate type-safe stubs for Rust, Kotlin, and Swift to ensure synchronization across the multi-language workspace.
Build and Validation Pipeline
The generation and validation of these stubs are managed by a suite of scripts that ensure the generated code is always in sync with the schema definitions.- Schema Validation:
protocis used to verify the structural integrity of all.protofiles scripts/protocol/validate-proto.ps1#43-66. - Stub Generation: The
generate-stubs.ps1script parses the proto files to create simplified language-specific stubs inschemas/generated/scripts/protocol/generate-stubs.ps1#82-91. - Compilation Check: Each generated stub is compiled using its respective compiler (
rustc,kotlinc,swiftc) to ensure the generated code is valid scripts/protocol/validate-rust-stubs.ps1#25-29, scripts/protocol/validate-kotlin-stubs.ps1#25-29, scripts/protocol/validate-swift-stubs.ps1#22-26.
Data Flow: Schema to Implementation
The following diagram illustrates how a service definition ingateway.proto transitions from a schema to a functional entity in the codebase.
Protocol Entity Mapping
Sources: schemas/proto/palyra/v1/gateway.proto#7-29, schemas/proto/palyra/v1/browser.proto#7-42, schemas/generated/rust/protocol_stubs.rs#154-179
Service Definitions
GatewayService
The primary interface forpalyrad. It handles session lifecycles, agent management, and the core execution stream.
| RPC Method | Input | Output | Description |
|---|---|---|---|
RunStream | stream RunStreamRequest | stream RunStreamEvent | The bidirectional heart of orchestration schemas/proto/palyra/v1/gateway.proto#9-10. |
RouteMessage | RouteMessageRequest | RouteMessageResponse | Entry point for external channel messages schemas/proto/palyra/v1/gateway.proto#16. |
ListSessions | ListSessionsRequest | ListSessionsResponse | Queries active and historical orchestrator sessions schemas/proto/palyra/v1/gateway.proto#13. |
CreateAgent | CreateAgentRequest | CreateAgentResponse | Persists a new agent configuration schemas/proto/palyra/v1/gateway.proto#19. |
ApprovalsService & VaultService
These services manage sensitive human-in-the-loop (HITL) flows and encrypted secret storage.- ApprovalsService: Provides methods to
ListApprovalsandGetApprovalrecords schemas/proto/palyra/v1/gateway.proto#31-35. It usesApprovalRecordto track decisions made by users regarding tool calls or sensitive actions schemas/proto/palyra/v1/gateway.proto#85-106. - VaultService: Manages secrets with scoped keys (e.g.,
GlobalorWorkspace). Methods includePutSecret,GetSecret, andDeleteSecretschemas/proto/palyra/v1/gateway.proto#37-42.
BrowserService
Implemented bypalyra-browserd, this service provides high-level browser automation primitives.
Browser Action Interaction
Sources: schemas/proto/palyra/v1/browser.proto#7-33, schemas/proto/palyra/v1/browser.proto#76-107
Key functionalities include:
- Session Management:
CreateSessionwithSessionBudgetconstraints (timeouts, max actions) schemas/proto/palyra/v1/browser.proto#57-91. - DOM Interaction:
Click,Type,Select, andHighlightschemas/proto/palyra/v1/browser.proto#20-24. - Observation:
Screenshot,Observe(DOM snapshots), andNetworkLogschemas/proto/palyra/v1/browser.proto#28-30.
AuthService
Manages authentication profiles and credentials used by agents to interact with external platforms.- Profiles:
ListAuthProfilesandSetAuthProfilemanage stored credentials like OAuth tokens or API keys schemas/proto/palyra/v1/protocol_stubs.rs#52-58. - Health:
GetHealthreturnsAuthHealthSummaryto indicate if credentials have expired or require re-authentication schemas/proto/palyra/v1/protocol_stubs.rs#31-33.
Common Message Types
Thepalyra.common.v1 package defines shared types used across all services to maintain consistency.
- CanonicalId: A ULID-based identifier encoded in Crockford Base32, used for all primary keys (sessions, runs, events) schemas/proto/palyra/v1/common.proto#6-11.
- MessageEnvelope: The standard container for communication, including
EnvelopeOrigin(who sent it) andSecurityContext(trust levels) schemas/proto/palyra/v1/common.proto#98-108. - JournalEvent: The structure for the append-only audit log, containing
payload_jsonand hash-chaining fields (hash,prev_hash) schemas/proto/palyra/v1/common.proto#110-142.
Tool Call Lifecycle Messages
The gRPC layer facilitates the tool execution protocol through specific messages:- ToolProposal: Sent by an agent to request execution schemas/proto/palyra/v1/common.proto#144-151.
- ToolApprovalRequest: Generated if a policy or risk level requires human intervention schemas/proto/palyra/v1/common.proto#208-218.
- ToolResult: The final output or error from the tool execution schemas/proto/palyra/v1/common.proto#231-238.