Domain Entity Overview
The following diagram illustrates the relationship between high-level domain concepts and their corresponding implementations in the Rust codebase.Concept to Code Mapping
Sources: crates/palyra-daemon/src/agents.rs#46-49, crates/palyra-daemon/src/orchestrator.rs#77-78, crates/palyra-daemon/src/journal.rs#67-68, crates/palyra-daemon/src/gateway.rs#86-86Core Definitions
Agents
An Agent is a configured entity with a specific identity, instructions, and set of capabilities. In the codebase, agents are managed via theAgentRegistry and persisted as AgentRecord structs. Agents are resolved during message routing based on AgentResolutionSource.
- Implementation:
AgentRecordcrates/palyra-daemon/src/agents.rs#47-47 - Key Function:
AgentRegistry::resolvecrates/palyra-daemon/src/gateway/runtime.rs#2-6
Runs and Sessions
- Session: A long-lived container for an interaction between a Principal and one or more Agents. It maintains the continuity of the conversation and is represented by
OrchestratorSessionRecord. - Run: A single execution unit within a session. A Run is a state machine (
RunStateMachine) that progresses through variousRunLifecycleStatephases (e.g.,Running,AwaitingApproval,Completed). - Implementation:
OrchestratorSessionRecordcrates/palyra-daemon/src/journal.rs#67-68RunStateMachinecrates/palyra-daemon/src/orchestrator.rs#77-77RunLifecycleStatecrates/palyra-daemon/src/orchestrator.rs#77-77
Principals and Devices
- Principal: The identity of the actor (human or system) initiating a request. It is passed in the
x-palyra-principalheader. - Device ID: A unique identifier for the hardware or client instance making the request, passed in
x-palyra-device-id. - Implementation:
RequestContextcrates/palyra-daemon/src/transport/grpc/auth.rs#40-40 (referenced in crates/palyra-daemon/src/gateway.rs#40-40)
Tools and Skills
- Tool: A specific function or capability that an Agent can invoke (e.g.,
shell,http_fetch,browser). Tool execution is governed by thetool_protocol. - Skill: A packaged collection of tools, often distributed as a Wasm module. Skills have a lifecycle managed by
SkillStatusRecord. - Implementation:
execute_tool_callcrates/palyra-daemon/src/tool_protocol.rs#78-79SkillStatusRecordcrates/palyra-daemon/src/journal.rs#70-70
Data Structures and Protocols
Tape and Journal
Palyra uses a ledger-based approach for persistence and auditability.- Journal: The primary append-only store for all system events, including configuration changes, session starts, and tool results. Managed by
JournalStore. - Tape: A subset of the journal specific to a single Run. It contains the sequence of events (messages, tool calls, token chunks) that constitute the “recording” of that run.
- Implementation:
JournalStorecrates/palyra-daemon/src/journal.rs#63-63OrchestratorTapeRecordcrates/palyra-daemon/src/journal.rs#69-69
Canvas
Canvas is a specialized environment for rendering rich, interactive user interfaces generated by agents. It usesCanvasStatePatchRecord to synchronize state between the agent and the frontend.
- Implementation:
CanvasStatePatchRecordcrates/palyra-daemon/src/journal.rs#59-59,CanvasHostRuntimeConfigcrates/palyra-daemon/src/gateway/runtime.rs#108-116
A2UI (Agent-to-User Interface)
The A2UI protocol is the JSON-based communication standard used by agents to update the UI dynamically. It relies on JSON Patch documents to perform granular updates to theCanvas state.
- Implementation:
palyra_a2uicrate, specificallyapply_patch_documentandparse_patch_documentcrates/palyra-daemon/src/gateway.rs#13-15
Connectivity and Orchestration
Channels and Connectors
- Connector: An adapter for an external platform (e.g., Discord, Slack).
- Channel: A specific communication pipe within a connector (e.g., a specific Discord thread).
- ChannelRouter: The logic responsible for matching inbound messages to the correct Agent and Session.
- Implementation:
ChannelRoutercrates/palyra-daemon/src/channel_router.rs#50-54InboundMessagecrates/palyra-daemon/src/channel_router.rs#51-51
Orchestration Flow
The following diagram shows the data flow from a message arrival to the execution of a tool. Sources: crates/palyra-daemon/src/gateway.rs#50-82, crates/palyra-daemon/src/orchestrator.rs#77-78, crates/palyra-daemon/src/journal.rs#63-70Technical Constants
The system enforces several constraints defined in the gateway:- MAX_SESSIONS_PAGE_LIMIT: 500 crates/palyra-daemon/src/gateway.rs#90-90
- JOURNAL_WRITE_LATENCY_BUDGET_MS: 25ms crates/palyra-daemon/src/gateway.rs#92-92
- MAX_MEMORY_ITEM_BYTES: 16 KiB crates/palyra-daemon/src/gateway.rs#118-118
- MAX_CANVAS_TOKEN_TTL_MS: 24 hours crates/palyra-daemon/src/gateway.rs#137-137