> ## Documentation Index > Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt > Use this file to discover all available pages before exploring further. # Schemas and Protocol Definitions
Relevant source files The following files were used as context for generating this wiki page: * crates/palyra-common/src/process\_runner\_input.rs * crates/palyra-daemon/src/application/instruction\_compiler.rs * crates/palyra-daemon/src/application/memory.rs * crates/palyra-daemon/src/application/recall.rs * crates/palyra-daemon/src/application/service\_authorization.rs * crates/palyra-daemon/src/application/tool\_registry/builtin.rs * crates/palyra-daemon/src/application/tool\_registry/tests.rs * crates/palyra-daemon/src/application/tool\_runtime/memory.rs * crates/palyra-daemon/src/gateway/tests.rs * crates/palyra-daemon/src/sandbox\_runner.rs * crates/palyra-daemon/src/transport/grpc/services/memory/service.rs * schemas/generated/kotlin/ProtocolStubs.kt * schemas/generated/rust/protocol\_stubs.rs * schemas/generated/swift/ProtocolStubs.swift * schemas/proto/palyra/v1/browser.proto * schemas/proto/palyra/v1/gateway.proto * schemas/proto/palyra/v1/memory.proto
Palyra utilizes a strictly versioned set of schemas to ensure type safety and contract enforcement across its distributed components, including the Rust daemon, the CLI, and various frontend surfaces. The protocol architecture is centered around **Protobuf** for high-performance RPC and **JSON Schema** for model-facing tool definitions and dynamic UI updates. The primary contract is the `PROTOCOL_MAJOR_VERSION`, which is synchronized across generated stubs to prevent incompatible deployments [schemas/generated/rust/protocol\_stubs.rs#5-5](http://schemas/generated/rust/protocol_stubs.rs#5-5). ## Protobuf Ecosystem and Generated Stubs The core communication between the `palyra-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](http://crates/palyra-daemon/src/application/memory.rs#41-41). * **browser.v1**: Defines the automation interface for the `palyra-browserd` service, including navigation, DOM inspection, and tab management [schemas/generated/rust/protocol\_stubs.rs#61-61](http://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](http://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](http://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](http://schemas/generated/swift/ProtocolStubs.swift#1-3). | For details on the generation pipeline and CI validation, see [Protobuf Schemas and Generated Stubs](/schemas_and_protocol_definitions/protobuf_schemas_and_generated_stubs). **Sources:** [schemas/generated/rust/protocol\_stubs.rs#1-60](http://schemas/generated/rust/protocol_stubs.rs#1-60), [schemas/generated/kotlin/ProtocolStubs.kt#1-35](http://schemas/generated/kotlin/ProtocolStubs.kt#1-35), [schemas/generated/swift/ProtocolStubs.swift#1-78](http://schemas/generated/swift/ProtocolStubs.swift#1-78). *** ## 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 The `palyra-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](http://crates/palyra-daemon/src/application/tool_registry/builtin.rs#23-50). ### The Instruction Compiler The `InstructionCompiler` 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](http://crates/palyra-daemon/src/application/instruction_compiler.rs#22-26). ### Protocol Validation Space ```mermaid theme={null} graph TD subgraph "Natural Language Space (LLM)" A["Model Output (JSON)"] end subgraph "Code Entity Space (Daemon)" B["parse_process_runner_tool_input"] C["ToolRegistryEntry"] D["InstructionCompiler"] E["GatewayRuntimeState"] end A -- "Unvalidated JSON" --> B D -- "Tool Schema (JSON)" --> A C -- "defines" --> D B -- "ProcessRunnerToolInput" --> E ``` **Sources:** [crates/palyra-daemon/src/application/tool\_registry/builtin.rs#1-17](http://crates/palyra-daemon/src/application/tool_registry/builtin.rs#1-17), [crates/palyra-daemon/src/application/instruction\_compiler.rs#1-26](http://crates/palyra-daemon/src/application/instruction_compiler.rs#1-26), [crates/palyra-common/src/process\_runner\_input.rs#100-112](http://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. ```mermaid theme={null} graph LR subgraph "Protocol Definitions" P1["gateway.v1.OrchestratorRunStartRequest"] P2["memory.v1.MemorySearchRequest"] P3["palyra.process.run (JSON)"] end subgraph "Code Entities (palyra-daemon)" E1["GatewayServiceImpl::RunStart"] E2["MemoryLifecycleProvider::search"] E3["SandboxProcessRunner::run"] E4["JournalStore::append"] end P1 --> E1 P2 --> E2 P3 --> E3 E1 & E2 & E3 --> E4 ``` ### Key Runtime Contracts * **Memory Ingestion**: Candidates are normalized and classified via `classify_memory_write` before being committed to the `JournalStore` [crates/palyra-daemon/src/application/memory.rs#1-9](http://crates/palyra-daemon/src/application/memory.rs#1-9). * **Process Execution**: The `palyra.process.run` tool utilizes `ProcessRunnerToolInput` to normalize model mistakes (like repeating commands in `args[0]`) before spawning sandboxed processes [crates/palyra-common/src/process\_runner\_input.rs#1-6](http://crates/palyra-common/src/process_runner_input.rs#1-6). * **Recall Planning**: The `RecallPlan` coordinates retrieval across multiple sources (Memory, Workspace, Transcript) using a unified scoring profile [crates/palyra-daemon/src/application/recall.rs#1-12](http://crates/palyra-daemon/src/application/recall.rs#1-12). For details on A2UI updates and telemetry contracts, see [JSON Schemas and Cross-Surface Contracts](/schemas_and_protocol_definitions/json_schemas_and_cross-surface_contracts). **Sources:** [crates/palyra-daemon/src/application/memory.rs#1-20](http://crates/palyra-daemon/src/application/memory.rs#1-20), [crates/palyra-daemon/src/application/recall.rs#1-25](http://crates/palyra-daemon/src/application/recall.rs#1-25), [crates/palyra-common/src/process\_runner\_input.rs#44-67](http://crates/palyra-common/src/process_runner_input.rs#44-67), [crates/palyra-daemon/src/sandbox\_runner.rs#1-15](http://crates/palyra-daemon/src/sandbox_runner.rs#1-15). ## Child Pages * [Protobuf Schemas and Generated Stubs](/schemas_and_protocol_definitions/protobuf_schemas_and_generated_stubs) * [JSON Schemas and Cross-Surface Contracts](/schemas_and_protocol_definitions/json_schemas_and_cross-surface_contracts)