Overview of Services
Palyra’s communication architecture is built on top of gRPC (for internal and node-to-node communication) and JSON envelopes (for Web Console and A2UI). The.proto files define the RPC methods, request/response structures, and core domain entities like CanonicalId, ApprovalRecord, and BrowserSession.
Core Service Architecture
The following diagram illustrates how the major Protobuf services map to the codebase entities and their interactions. Service to Code Entity Mapping Sources: schemas/proto/palyra/v1/gateway.proto#7-51, schemas/proto/palyra/v1/browser.proto#7-42, crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs#50-591. Gateway & Control Plane Services
The Gateway is the primary entry point for agent orchestration and state management. It is defined inpalyra/v1/gateway.proto.
GatewayService
Manages the lifecycle of agent “Runs” and sessions.RunStream: A bidirectional stream for executing agent loops schemas/proto/palyra/v1/gateway.proto#9-10.AppendEvent: Manually appends events to the session’s hash-chained journal crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs#94-110.RouteMessage: Handles inbound messages from various channels (Discord, Slack, etc.) and routes them to the appropriate agent schemas/proto/palyra/v1/gateway.proto#16-16.
ApprovalsService
Provides an interface for managing human-in-the-loop (HITL) requirements.ApprovalRecord: Contains details about a requested action, the policy snapshot evaluated, and the final decision schemas/proto/palyra/v1/gateway.proto#85-106.ApprovalSubjectType: Categorizes requests intoTOOL,SECRET_ACCESS,BROWSER_ACTION, etc schemas/proto/palyra/v1/gateway.proto#53-61.
VaultService
Handles encrypted secret management.PutSecret/GetSecret: Standard CRUD for secrets scoped to specific principals or sessions schemas/proto/palyra/v1/gateway.proto#38-39.
2. Browser Automation Service
TheBrowserService (defined in palyra/v1/browser.proto) facilitates high-level browser interaction, enforced by security budgets.
Browser Session Lifecycle
The service managesBrowserSession objects which wrap Chromium instances.
| Method | Description | Security Constraint |
|---|---|---|
CreateSession | Spawns a new browser context | SessionBudget enforced schemas/proto/palyra/v1/browser.proto#76-91 |
Navigate | Moves to a URL | action_allowed_domains check schemas/proto/palyra/v1/browser.proto#19-19 |
Observe | Captures accessibility tree/DOM | max_observe_snapshot_bytes schemas/proto/palyra/v1/browser.proto#29-29 |
RelayAction | Communicates with the Browser Extension | Loopback-only transport schemas/proto/palyra/v1/browser.proto#40-40 |
Data Flow: Browser Action
Sources: schemas/proto/palyra/v1/browser.proto#7-42, schemas/proto/palyra/v1/browser.proto#57-743. Auth and Identity Services
TheAuthService manages model provider credentials and health.
AuthProfile: Represents a configured provider (e.g., OpenAI, Anthropic) with its associated credentials schemas/generated/rust/protocol_stubs.rs#17-17.GetHealth: Returns the connectivity status and rate-limit metrics for configured profiles schemas/generated/rust/protocol_stubs.rs#31-33.OAuthRefreshState: Tracks the lifecycle of OAuth2 tokens for providers requiring refresh flows schemas/generated/rust/protocol_stubs.rs#45-45.
4. Shared Common Types
Thepalyra.common.v1 package contains primitive types used across all services to ensure interoperability.
CanonicalId: A standard wrapper for ULIDs (Universally Unique Lexicographically Sortable Identifiers) used for sessions, runs, and events crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs#111-114.RunStreamEvent: The polymorphic message type used in the bidirectionalRunStream, carrying log updates, tool calls, and state patches schemas/proto/palyra/v1/gateway.proto#9-10.ApprovalPrompt: Defines how a request should be presented to a user, including options and timeouts schemas/proto/palyra/v1/gateway.proto#101-101.
5. Generated Stubs and Parity
To maintain strict contract adherence, stubs are generated for multiple languages. These stubs are checked during CI to ensure they match the.proto source.
Implementation Status by Language
| Language | Stub Location | Primary Usage |
|---|---|---|
| Rust | protocol_stubs.rs | palyrad and palyra CLI schemas/generated/rust/protocol_stubs.rs#1-5 |
| Kotlin | ProtocolStubs.kt | Android / JVM Mobile Client schemas/generated/kotlin/ProtocolStubs.kt#1-4 |
| Swift | ProtocolStubs.swift | iOS / macOS Desktop Client schemas/generated/swift/ProtocolStubs.swift#1-3 |
Protocol Versioning
All services enforce aPROTOCOL_MAJOR_VERSION check (currently 1). Requests with mismatched major versions are rejected with FAILED_PRECONDITION crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs#102-104.
Sources: schemas/generated/rust/protocol_stubs.rs#5-5, schemas/generated/kotlin/ProtocolStubs.kt#1-3, schemas/generated/swift/ProtocolStubs.swift#1-2