palyrad), the CLI, the Browser Daemon (palyra-browserd), and various SDKs.
Overview of Protocol Architecture
Palyra utilizes Protocol Buffers (proto3) to define its service interfaces and data models. The schemas are organized withinschemas/proto/palyra/v1/ and are used to generate language-specific stubs for Rust, Kotlin, and Swift.
Core Service Components
The protocol is divided into several specialized services, each responsible for a distinct domain of the platform:| Service | Responsibility |
|---|---|
GatewayService | Central orchestrator for runs, session resolution, and agent management. |
ApprovalsService | Management and export of human-in-the-loop approval records. |
VaultService | Secure storage, retrieval, and deletion of encrypted secrets. |
BrowserService | Automation and inspection of headless Chromium instances. |
AuthService | Management of authentication profiles and provider health. |
MemoryService | Ingestion and retrieval of long-term agent memory. |
NodeService | Coordination with remote execution nodes and capabilities. |
CronService | Scheduling and execution of recurring background routines. |
Service Definitions
Gateway and Orchestration
TheGatewayService is the primary entry point for the palyra-daemon. It manages the RunStream, which is a bidirectional gRPC stream used for real-time agent execution and event propagation.
Service Mapping: Natural Language to Code Entities
Sources: schemas/proto/palyra/v1/gateway.proto#7-29, schemas/proto/palyra/v1/gateway.proto#9-10.
Browser Automation
TheBrowserService (defined in browser.proto) exposes the capabilities of palyra-browserd. It allows the daemon or CLI to perform complex web automation tasks, ranging from simple navigation to multi-tab session management with persistent profiles.
Browser Interaction Flow
Sources: schemas/proto/palyra/v1/browser.proto#7-42, schemas/proto/palyra/v1/browser.proto#76-107, schemas/proto/palyra/v1/browser.proto#227-242.
Approvals and Security
Security-sensitive actions (like tool execution or secret access) are gated by theApprovalsService. When a run requires an approval, it creates an ApprovalRecord schemas/proto/palyra/v1/gateway.proto#85-106.
- Subject Types: Defined by
ApprovalSubjectType, includingTOOL,SECRET_ACCESS, andBROWSER_ACTIONschemas/proto/palyra/v1/gateway.proto#53-61. - Decisions: Captured via
ApprovalDecision(ALLOW, DENY, TIMEOUT, etc.) schemas/proto/palyra/v1/gateway.proto#63-69.
Common Types and Versioning
Thepalyra.common.v1 package (imported in most proto files) provides shared primitives used across all services:
CanonicalId: A standardized identifier format for sessions, runs, and agents.RunStreamRequest/RunStreamEvent: The core data structures for the execution pipeline.- Protocol Versioning: Every message includes a version field
uint32 v = 1;to ensure backward compatibility during rolling updates schemas/proto/palyra/v1/gateway.proto#86, schemas/proto/palyra/v1/browser.proto#45.
Stub Generation and Validation
Palyra uses a centralized generation strategy to ensure all clients remain in sync with the daemon’s protocol.Rust Generation
Rust stubs are generated during the build process ofpalyra-cli and palyra-daemon using tonic-prost-build.
- The
build.rsscript inpalyra-daemonconfigures both client and server generation crates/palyra-daemon/build.rs#24-35. - The
build.rsscript inpalyra-cligenerates only the client stubs crates/palyra-cli/build.rs#24-35.
Cross-Language Stubs
For mobile and external integration, a PowerShell scriptscripts/protocol/generate-stubs.ps1 parses the .proto files to generate lightweight stubs in:
- Rust:
schemas/generated/rust/protocol_stubs.rsschemas/generated/rust/protocol_stubs.rs#1-60. - Kotlin:
schemas/generated/kotlin/ProtocolStubs.ktschemas/generated/kotlin/ProtocolStubs.kt#1-34. - Swift:
schemas/generated/swift/ProtocolStubs.swiftschemas/generated/swift/ProtocolStubs.swift#1-77.
Validation Pipeline
The integrity of the protocol is enforced via several validation scripts:- Schema Validation:
scripts/protocol/validate-proto.ps1usesprotocto ensure all.protofiles are syntactically correct and imports are resolvable scripts/protocol/validate-proto.ps1#56-66. - Stub Consistency:
scripts/protocol/check-generated-stubs.ps1verifies that the generated code inschemas/generated/matches the source.protofiles, failing the CI if they are out of sync scripts/protocol/check-generated-stubs.ps1#14-21. - Compilation Checks: Language-specific scripts like
scripts/protocol/validate-swift-stubs.shandscripts/protocol/validate-kotlin-stubs.ps1attempt to compile the generated stubs to catch type-naming collisions or syntax errors in the generator scripts/protocol/validate-swift-stubs.sh#20-21, scripts/protocol/validate-kotlin-stubs.ps1#24-30.