PROTOCOL_MAJOR_VERSION, which is synchronized across generated stubs to prevent incompatible deployments schemas/generated/rust/protocol_stubs.rs#5-5.
Protobuf Ecosystem and Generated Stubs
The core communication between thepalyra-daemon and its clients (or external workers) is defined via Protobuf v3. These schemas are organized into functional domains (v1) and are used to generate native stubs for Rust, Kotlin, and Swift.
Protocol Domains
- gateway.v1: The primary interface for run orchestration, session management, and the agent loop.
- memory.v1: Handles durable memory ingestion, search, and lifecycle management crates/palyra-daemon/src/application/memory.rs#41-41.
- browser.v1: Defines the automation interface for the
palyra-browserdservice, including navigation, DOM inspection, and tab management schemas/generated/rust/protocol_stubs.rs#61-61. - auth.v1: Manages authentication profiles, credentials (API keys, OAuth), and health metrics schemas/generated/rust/protocol_stubs.rs#7-7.
- node.v1 / plugin.v1: Handles inter-node communication and the Wasm plugin execution interface.
Cross-Language Support
Stubs are automatically generated and committed to the repository to ensure that frontends (Web/React, Desktop/Tauri, Mobile) stay in sync with the daemon’s internal logic.| Language | Generated File Path | Purpose |
|---|---|---|
| Rust | schemas/generated/rust/protocol_stubs.rs | Internal daemon and CLI communication. |
| Kotlin | schemas/generated/kotlin/ProtocolStubs.kt | Android and JVM-based integrations schemas/generated/kotlin/ProtocolStubs.kt#1-2. |
| Swift | schemas/generated/swift/ProtocolStubs.swift | iOS and macOS native application support schemas/generated/swift/ProtocolStubs.swift#1-3. |
JSON Schemas and Model Contracts
While Protobuf handles the “system-to-system” space, JSON Schemas govern the “Model-to-Daemon” space. Every tool in the Palyra registry includes a JSON Schema that defines its input requirements, which is served to the LLM during the prompt compilation phase.Builtin Tool Registry
Thepalyra-daemon maintains a static registry of builtin tools (e.g., palyra.memory.search, palyra.process.run). These tools use object_schema definitions to enforce strict validation on model-generated arguments crates/palyra-daemon/src/application/tool_registry/builtin.rs#23-50.
The Instruction Compiler
TheInstructionCompiler acts as a bridge, transforming system state and tool schemas into a deterministic instruction set for the LLM. It tracks a INSTRUCTION_COMPILER_VERSION to ensure that any change in the underlying contract (such as tool descriptions or safety notes) results in a new content hash for auditability crates/palyra-daemon/src/application/instruction_compiler.rs#22-26.
Protocol Validation Space
Sources: crates/palyra-daemon/src/application/tool_registry/builtin.rs#1-17, crates/palyra-daemon/src/application/instruction_compiler.rs#1-26, crates/palyra-common/src/process_runner_input.rs#100-112.Cross-Surface Communication Flow
The protocol definitions ensure that an action initiated in one surface (e.g., the Web Console) is correctly interpreted by the daemon and executed within the safety boundaries.Entity Mapping
The following diagram illustrates how high-level protocol concepts map to specific code entities within the daemon’s transport and application layers.Key Runtime Contracts
- Memory Ingestion: Candidates are normalized and classified via
classify_memory_writebefore being committed to theJournalStorecrates/palyra-daemon/src/application/memory.rs#1-9. - Process Execution: The
palyra.process.runtool utilizesProcessRunnerToolInputto normalize model mistakes (like repeating commands inargs[0]) before spawning sandboxed processes crates/palyra-common/src/process_runner_input.rs#1-6. - Recall Planning: The
RecallPlancoordinates retrieval across multiple sources (Memory, Workspace, Transcript) using a unified scoring profile crates/palyra-daemon/src/application/recall.rs#1-12.