JSON Envelope Schemas
Theschemas/json/ directory contains the formal definitions for non-gRPC data structures. These schemas ensure consistency between the Rust-based daemon, the React web console, and external connectors.
Key Schema Categories
| Schema Type | Purpose | Key Entities |
|---|---|---|
| Message Envelope | Defines the structure for inter-agent and connector messaging. | Message, Payload, Metadata |
| A2UI Envelope | Handles Agent-to-User Interface JSON Patches. | A2UIPatch, CanvasState |
| Config Export/Import | Governs the serialization of daemon configuration for portability. | RootFileConfig, VaultExport |
| Webhook Envelope | Defines the payload structure for inbound webhooks. | WebhookEvent, Signature |
| Common Primitives | Shared types like ULIDs, Timestamps, and URI formats. | Ulid, IsoDateTime |
Protocol Validation and Stub Generation
To maintain type safety across the monorepo and for external consumers, Palyra employs a “Schema-First” approach. Protobuf definitions inschemas/proto/ are validated and then used to generate stubs for Rust, Kotlin, and Swift.
Validation Pipeline
The validation process ensures that all.proto files are syntactically correct and can be compiled into a descriptor set.
validate-proto.ps1: This script locates theprotoccompiler and attempts to generate a descriptor set (palyra-protocol.pb) from all files inschemas/proto/scripts/protocol/validate-proto.ps1#9-66.- Stub Generation: Once validated,
generate-stubs.ps1is invoked to produce language-specific source files inschemas/generated/.
Language-Specific Stub Validation
After generation, each stub file undergoes a “smoke compile” to ensure the generated code is valid in its target language:- Rust: Validated using
rustc --crate-type libto produce an.rlibscripts/protocol/validate-rust-stubs.ps1#25-29. - Kotlin: Validated using
kotlincto produce a.jarscripts/protocol/validate-kotlin-stubs.ps1#25-29. - Swift: Validated using
swiftc -emit-moduleto produce a.swiftmodulescripts/protocol/validate-swift-stubs.sh#20-21.
Stub Coherence Flow
The following diagram illustrates the relationship between the raw schemas, the generation scripts, and the validation checks. Diagram: Schema-to-Stub Pipeline Sources: scripts/protocol/validate-proto.ps1#48-71, scripts/protocol/validate-rust-stubs.ps1#7-29, scripts/protocol/validate-kotlin-stubs.ps1#7-29, scripts/protocol/validate-swift-stubs.sh#5-21CI/CD Integration
The protocol integrity is enforced by the CI pipeline to prevent “drift” between the schemas and the generated code.Coherence Checks
Thecheck-generated-stubs.ps1 script (run in CI) ensures that the stubs currently committed to the repository match exactly what would be generated from the current schemas. If a developer modifies a .proto file but forgets to run the generation script, the CI will fail.
CI Workflow Steps
Theci.yml workflow executes these checks as part of the quality and build-and-test jobs:
- Protocol Contract Validation: Ensures schemas are valid scripts/protocol/validate-proto.ps1#71.
- Stub Coherence: Verifies generated code is up-to-date.
- Cross-Platform Compilation: The
build-and-testjob compiles the workspace on Ubuntu, macOS, and Windows to ensure the Rust stubs work across all targets /.github/workflows/ci.yml#17-23.
Implementation Details
Tooling Requirements
To run the full validation suite locally, the following tools must be present in the systemPATH:
protoc(Protobuf Compiler) scripts/protocol/validate-proto.ps1#43-46rustc(Rust Compiler) scripts/protocol/validate-rust-stubs.ps1#9-15kotlinc(Kotlin Compiler) scripts/protocol/validate-kotlin-stubs.ps1#9-15swiftc(Swift Compiler) scripts/protocol/validate-swift-stubs.sh#7-10
File Locations
- Protobuf Source:
schemas/proto/palyra/v1/ - JSON Source:
schemas/json/ - Rust Stubs:
schemas/generated/rust/protocol_stubs.rs - Kotlin Stubs:
schemas/generated/kotlin/ProtocolStubs.kt - Swift Stubs:
schemas/generated/swift/ProtocolStubs.swift