Schema Architecture and Envelopes
Palyra utilizes a dual-protocol approach: Protobuf for high-performance gRPC communication between internal services (Gateway, Browser, Node) and JSON Envelopes for public-facing APIs, webhooks, and state persistence. The JSON schemas define the structure for:- Message Envelopes: The standard wrapper for agent-to-user and user-to-agent communication.
- A2UI Envelopes: Agent-to-UI patches used to dynamically update the React dashboard apps/web/src/components/A2UI#1-20.
- Webhook Envelopes: Payloads for external platform integrations like Discord and Slack scripts/protocol/generate-stubs.ps1#1-50.
- Config Export/Import: The schema for migrating and validating
RootFileConfigand SQLite-backed state.
Data Flow: Schema to Runtime
The following diagram illustrates how schemas move from definition to cross-language enforcement. Protocol Contract Distribution Sources: scripts/protocol/generate-stubs.ps1#1-40, scripts/protocol/validate-proto.ps1#6-15, .github/workflows/ci.yml#173-180Stub Generation and Validation
To prevent drift between the Rust implementation and client libraries, Palyra uses a centralized generation script located atscripts/protocol/generate-stubs.ps1 scripts/protocol/generate-stubs.ps1#1-10.
Key Scripts
| Script | Purpose |
|---|---|
generate-stubs.ps1 | Orchestrates the generation of Rust, Kotlin, and Swift code from .proto and JSON schemas. |
validate-proto.ps1 | Uses protoc to verify that all .proto files in schemas/proto are syntactically correct and importable scripts/protocol/validate-proto.ps1#43-66. |
validate-rust-stubs.ps1 | Ensures generated Rust code compiles within the workspace. |
validate-kotlin-stubs.ps1 | Uses kotlinc to verify that ProtocolStubs.kt is valid scripts/protocol/validate-kotlin-stubs.ps1#9-29. |
validate-swift-stubs.sh | Uses swiftc to compile the generated ProtocolStubs.swift into a module scripts/protocol/validate-swift-stubs.sh#7-21. |
check-generated-stubs.ps1 | A CI utility that regenerates stubs and checks for git diffs to ensure committed stubs are up-to-date scripts/protocol/check-generated-stubs.ps1#9-21. |
CI Enforcement and Security Gates
The integrity of protocol contracts is enforced in the GitHub ActionsCI and Security Gates workflows.
- Stub Parity: The
qualityjob inci.ymlrunscheck-generated-stubs.ps1. If a developer modifies a schema but forgets to run the generation script, the CI fails scripts/protocol/check-generated-stubs.ps1#16-20. - Schema Validation: Every PR triggers
validate-proto.ps1to ensure that gRPC service definitions forGatewayService,BrowserService, and others remain compatible scripts/protocol/validate-proto.ps1#57-66. - Cross-Platform Compilation: Stubs are compiled on Linux, macOS, and Windows runners to ensure language-specific compiler compatibility (e.g.,
swiftcon macOS,kotlincon Ubuntu) .github/workflows/ci.yml#18-23.
System Component Mapping
The following diagram bridges the natural language definitions of the protocol to the specific code entities that handle them. Code-to-System Mapping Sources: .github/workflows/ci.yml#45-50, scripts/protocol/validate-kotlin-stubs.ps1#7-15, scripts/protocol/validate-swift-stubs.sh#5-10Security and Supply Chain
The protocol layer is subject to high-risk pattern scanning and dependency auditing.- Audit Gates: The
security-gatesjob runscargo auditandnpm auditto ensure that serialization libraries (likeserdeorprost) do not have known vulnerabilities .github/workflows/security.yml#95-99. - SBOM Generation:
cargo-cyclonedxgenerates a Software Bill of Materials (SBOM) for all protocol-related crates to track the provenance of the communication stack .github/workflows/security.yml#131-133. - High-Risk Patterns: Scripts like
check-high-risk-patterns.share executed to ensure that no sensitive data (e.g., Vault secrets) is accidentally exposed through the JSON envelope definitions .github/workflows/security.yml#128-129.