palyrad), various client applications (Web, Desktop, CLI), and external nodes. Palyra utilizes a combination of Protobuf for structured RPC/streaming and JSON Envelopes for flexible UI rendering and message exchange.
Overview of Contract Architecture
Palyra’s architecture relies on strictly defined schemas to ensure type safety across Rust, Kotlin, and Swift. The system is divided into three primary layers:- Protobuf Layer: Defines gRPC services and message structures for high-performance daemon-to-client and daemon-to-node communication.
- JSON Envelope Layer: Defines the structure of messages, configurations, and UI patches transmitted over HTTP or WebSockets.
- A2UI (Agent-to-User Interface) Protocol: A specialized JSON-based protocol for dynamic UI updates, allowing agents to “render” components in the user’s dashboard.
Protocol Generation and Validation
The codebase includes a suite of scripts to ensure that generated code stays in sync with schema definitions.- Generation:
scripts/protocol/generate-stubs.ps1scripts/protocol/generate-stubs.ps1#1-203 processes.protofiles to create language-specific stubs. - Validation: CI gates run
scripts/protocol/check-generated-stubs.ps1scripts/protocol/check-generated-stubs.ps1#1-24 andscripts/protocol/validate-proto.ps1scripts/protocol/validate-proto.ps1#1-72 to prevent drift between schemas and generated code.
| Component | Path | Description |
|---|---|---|
| Proto Definitions | schemas/proto/palyra/v1/ | Source of truth for all gRPC/Protobuf contracts. |
| Rust Stubs | schemas/generated/rust/protocol_stubs.rs | Generated types for the Daemon and CLI. |
| Kotlin Stubs | schemas/generated/kotlin/ProtocolStubs.kt | Generated types for Android/JVM clients. |
| Swift Stubs | schemas/generated/swift/ProtocolStubs.swift | Generated types for iOS/macOS clients. |
| JSON Schemas | schemas/json/envelopes/ | JSON Schema files for message and UI validation. |
Protobuf Service Definitions
The core functionality of Palyra is exposed via gRPC services defined in theschemas/proto/ directory. These services handle everything from the main execution gateway to secret management and browser automation.
Key Services
- GatewayService: The primary entry point for starting runs (
RunStream) and managing agents schemas/proto/palyra/v1/gateway.proto#7-29. - ApprovalsService: Manages the lifecycle of human-in-the-loop approvals schemas/proto/palyra/v1/gateway.proto#31-35.
- BrowserService: Provides a remote interface for headless Chromium control schemas/proto/palyra/v1/browser.proto#7-42.
- VaultService: Handles encrypted secret storage and retrieval schemas/proto/palyra/v1/gateway.proto#37-42.
JSON Envelopes and A2UI Protocol
While Protobuf handles the “pipes,” JSON Envelopes handle the “content,” especially for web-based interactions and configuration portability.A2UI (Agent-to-User Interface)
The A2UI protocol allows the daemon to send UI “patches” to the web dashboard. Instead of sending a full page, the daemon sendsPatchOperation sets (Add, Replace, Remove) crates/palyra-a2ui/src/lib.rs#29-41. This enables real-time, granular updates to the “Canvas” without full re-renders.
Envelope Schemas
All JSON data follows strict versioned schemas to ensure the frontend can safely parse incoming messages.- A2UI Envelope: Governs UI state synchronization schemas/json/envelopes/a2ui-envelope.v1.json#1-201.
- Message Envelope: Wraps chat messages and metadata.
- Config Envelopes: Used for exporting and importing agent configurations.
Protocol Validation (Natural Language to Code)
The diagram below illustrates how a conceptual UI update (Natural Language Space) is transformed into a validatedPatchDocument (Code Entity Space).
Diagram: A2UI Update Flow
For details on A2UI patch mechanics, JSON schema validation, and normalization, see JSON Envelopes and A2UI Protocol.
Sources: crates/palyra-a2ui/src/lib.rs#29-47, schemas/json/envelopes/a2ui-envelope.v1.json#132-149
Cross-Language Type Mapping
The protocol generation pipeline ensures that domain concepts are represented consistently across the stack. This mapping is vital for features likeVaultService, where secrets must be handled with identical logic in Rust and Swift.
Diagram: Cross-Language Entity Mapping
| Concept | Rust Entity | Swift Entity | Kotlin Entity |
|---|---|---|---|
| Auth Profile | palyra_auth_v1::AuthProfile | PalyraAuthV1.AuthProfile | PalyraAuthV1.AuthProfile |
| Browser Session | palyra_browser_v1::BrowserSessionSummary | PalyraBrowserV1.BrowserSessionSummary | PalyraBrowserV1.BrowserSessionSummary |
| Gateway Health | palyra_gateway_v1::HealthRequest | PalyraGatewayV1.HealthRequest | PalyraGatewayV1.HealthRequest |