Skip to main content
Palyra utilizes Protocol Buffers (v3) as the canonical definition for its internal and external service interfaces. These schemas define the communication contracts for the gateway, memory, browser automation, and security subsystems. A dedicated code generation pipeline ensures that these definitions remain synchronized across the Rust daemon, Kotlin/Android clients, and Swift/iOS applications.

​
Protobuf Schema Definitions

The core schemas are located in schemas/proto/palyra/v1/ and are organized by functional domain. All services follow a versioned package naming convention (e.g., palyra.gateway.v1) schemas/proto/palyra/v1/gateway.proto#3-3.

​
Core Service Schemas

ServiceFilePrimary Responsibility
GatewayServicegateway.protoCore agent orchestration, session resolution, and event streaming schemas/proto/palyra/v1/gateway.proto#7-29.
BrowserServicebrowser.protoChromium/Simulated engine control, including navigation, DOM interaction, and tab management schemas/proto/palyra/v1/browser.proto#7-45.
VaultServicegateway.protoSecure storage and retrieval of secrets indexed by scope and key schemas/proto/palyra/v1/gateway.proto#37-42.
ApprovalsServicegateway.protoManagement and export of human-in-the-loop (HITL) authorization records schemas/proto/palyra/v1/gateway.proto#31-35.
AuthServiceauth.protoManagement of AuthProfile entities and provider-specific credentials schemas/generated/rust/protocol_stubs.rs#7-59.

​
Common Types and Versioning

All messages include a version field uint32 v to support forward and backward compatibility during rolling updates schemas/proto/palyra/v1/browser.proto#48-48. Common primitives, such as CanonicalId (ULID-based identifiers), are shared via common.proto schemas/proto/palyra/v1/gateway.proto#5-5.

​
Interface Data Flow: Browser Automation

The following diagram illustrates how the BrowserService protobuf definition maps to system entities. Diagram: Browser Protocol Entity Mapping Sources: schemas/proto/palyra/v1/browser.proto#7-45, schemas/proto/palyra/v1/browser.proto#65-82.

​
Code Generation Pipeline

Stubs are generated using the scripts/protocol/generate-stubs.sh script schemas/generated/rust/protocol_stubs.rs#1-1. This pipeline produces strongly-typed interfaces for three target languages:
  1. Rust: Generated in schemas/generated/rust/protocol_stubs.rs. It includes pub mod blocks for each protobuf package and traits for service clients schemas/generated/rust/protocol_stubs.rs#7-59.
  2. Kotlin: Generated in schemas/generated/kotlin/ProtocolStubs.kt. It uses data class representations for messages and interface definitions for services schemas/generated/kotlin/ProtocolStubs.kt#4-34.
  3. Swift: Generated in schemas/generated/swift/ProtocolStubs.swift. It utilizes enum namespaces and struct message types with Equatable conformance schemas/generated/swift/ProtocolStubs.swift#3-77.

​
Stub Structure and Constraints

Generated stubs are marked as DO NOT EDIT to prevent manual drift schemas/generated/rust/protocol_stubs.rs#1-1. In the current build phase, many generated stubs utilize placeholder fields (e.g., val placeholder: Int = 0) to maintain ABI stability while the underlying serialization logic is finalized schemas/generated/kotlin/ProtocolStubs.kt#5-26. Diagram: Generation Pipeline and Artifact Distribution Sources: schemas/generated/rust/protocol_stubs.rs#1-1, schemas/generated/kotlin/ProtocolStubs.kt#1-1, schemas/generated/swift/ProtocolStubs.swift#1-1.

​
CI Validation and Hygiene

To ensure that schemas and generated stubs do not drift, the CI pipeline enforces several hygiene checks:
  • Runtime Artifact Hygiene: The scripts/check-runtime-artifacts.sh script is executed during the quality job to ensure no stale or unauthorized binary artifacts are present in the schema directories .github/workflows/ci.yml#230-232.
  • Security Scanning: All generated code is included in the CodeQL analysis matrix for Rust and JavaScript/TypeScript to detect potential vulnerabilities in the protocol implementation .github/workflows/codeql.yml#19-25.
  • Version Coherence: The scripts/release/assert-version-coherence.ps1 script validates that the protocol version matches the repository release version during the packaging flow .github/workflows/release.yml#45-45.
  • Cross-Platform Build Tests: CI validates that the generated stubs compile correctly across Linux, macOS, and Windows runners .github/workflows/ci.yml#26-34.

​
Protocol Security Gates

The security-gates job performs supply chain auditing on the tools used for protocol management, including cargo-audit and cargo-deny to check for vulnerabilities in the protobuf compiler dependencies .github/workflows/security.yml#95-99. Sources: .github/workflows/ci.yml#215-232, .github/workflows/security.yml#95-99, .github/workflows/codeql.yml#19-25, .github/workflows/release.yml#41-60.