tonic library in Rust) for high-performance, type-safe remote procedure calls. The system uses a centralized schema repository to generate language-specific stubs for Rust, Swift, and Kotlin, ensuring cross-platform consistency across the daemon, mobile apps, and desktop clients.
Protocol Schema Architecture
The protocol is organized into several functional domains defined in.proto files within the schemas/proto/palyra/v1/ directory.
Core Service Definitions
| Service | File | Primary Responsibility |
|---|---|---|
GatewayService | gateway.proto | Main entry point for runs, session management, and agent orchestration. |
BrowserService | browser.proto | Interface for the palyra-browserd automation engine. |
AuthServiceClient | auth.proto | Management of AuthProfile and provider credentials. |
VaultService | gateway.proto | Secure storage for secrets and sensitive bytes. |
CanvasService | gateway.proto | Management of the Agent-to-User Interface (A2UI) state. |
Common Types and Messaging
Thecommon.proto file defines the fundamental building blocks used across all services, such as CanonicalId (ULID-based identifiers) and MessageEnvelope for secure message passing schemas/proto/palyra/v1/common.proto#6-11, schemas/proto/palyra/v1/common.proto#98-108.
Sources: schemas/proto/palyra/v1/gateway.proto#7-29, schemas/proto/palyra/v1/browser.proto#7-42, schemas/proto/palyra/v1/common.proto#1-142
Data Flow: RunStream and Event Lifecycle
The most critical interface in Palyra is the bidirectionalRunStream within the GatewayService. It facilitates real-time interaction between the user (or client) and the agent.
RunStream Interaction Model
- Request: The client sends a
RunStreamRequestcontaining aMessageEnvelopeschemas/proto/palyra/v1/common.proto#259-276. - Execution: The daemon processes the input, potentially triggering tool calls or model generations.
- Events: The daemon streams back
RunStreamEventmessages, which are aoneofunion ofModelToken,ToolProposal,ToolResult, and others schemas/proto/palyra/v1/common.proto#300-307.
Mapping Protocol to Entities
The following diagram bridges the Protobuf definitions to the logical entities they represent in the system. “Natural Language Space to Code Entity Space: Messaging” Sources: schemas/proto/palyra/v1/common.proto#98-108, schemas/proto/palyra/v1/common.proto#144-151, schemas/proto/palyra/v1/common.proto#251-257, schemas/proto/palyra/v1/gateway.proto#9-10Browser Automation Interface
TheBrowserService exposes a high-level API for controlling headless Chromium instances. It includes standard automation actions (Click, Type, Navigate) and Palyra-specific session management.
Key Browser Operations
- Session Lifecycle:
CreateSessionallows specifying aSessionBudgetto limit resource consumption (timeouts, bandwidth, actions) schemas/proto/palyra/v1/browser.proto#57-74, schemas/proto/palyra/v1/browser.proto#76-91. - State Inspection:
InspectSessioncan return cookies, storage, and DOM snapshots schemas/proto/palyra/v1/browser.proto#227-242. - Extension Relay:
RelayActionenables communication with the Palyra Browser Extension schemas/proto/palyra/v1/browser.proto#40.
Generated Stubs and Multi-Language Support
Palyra uses a code generation pipeline to transform.proto definitions into native language structures. This ensures that changes to the protocol are immediately reflected across all components of the monorepo.
Language Targets
- Rust: Generated into
protocol_stubs.rsusingtonic-build. Includes traits likeAuthServiceClientandGatewayServiceschemas/generated/rust/protocol_stubs.rs#7-58. - Swift: Generated for the iOS/macOS apps, providing
Equatablestructs and protocols schemas/generated/swift/ProtocolStubs.swift#3-77. - Kotlin: Generated for Android/JVM, using
data classfor messages schemas/generated/kotlin/ProtocolStubs.kt#4-34.
Validation Pipeline
The repository includes scripts to validate that the generated stubs are in sync with the.proto files and that they compile correctly in their respective target languages.
| Script | Purpose |
|---|---|
validate-proto.ps1 | Uses protoc to check schema syntax and imports scripts/protocol/validate-proto.ps1#43-66. |
check-generated-stubs.ps1 | Ensures that the files in schemas/generated/ match the current .proto definitions scripts/protocol/check-generated-stubs.ps1#14-21. |
validate-rust-stubs.ps1 | Attempts to compile the Rust stubs using rustc scripts/protocol/validate-rust-stubs.ps1#24-29. |
Security and Integrity
The protocol incorporates security features directly into the message definitions:- Replay Protection: The
ReplayProtectionmessage includes a nonce, timestamp, and signature to prevent man-in-the-middle replay attacks schemas/proto/palyra/v1/common.proto#14-21. - Audit Logging: The
JournalEventstructure includeshashandprev_hashfields, enabling the creation of hash-chained audit logs for every action taken during a run schemas/proto/palyra/v1/common.proto#110-142. - Trust Levels:
SecurityContextdefines theTrustLevel(Untrusted, UserTrusted, System) of a message, which is used by the policy engine to make authorization decisions schemas/proto/palyra/v1/common.proto#82-96.