Core Concepts & Actors
Gateway Runtime (palyrad)
The central daemon process that coordinates all agent activities, tool executions, and storage operations. It acts as the hub between frontend applications (Web Console, CLI) and backend execution environments.
- Implementation:
GatewayRuntimeStateserves as the shared state container crates/palyra-daemon/src/gateway/runtime.rs#1-25. - Transport: Supports gRPC (for high-performance tool/memory access) and HTTP (for the Web Console and OpenAI-compatible endpoints) crates/palyra-daemon/src/gateway.rs#4-11.
Agent Run Loop
The iterative process where the system alternates between LLM provider turns and tool execution batches.- Logic: Managed in
process_run_stream_messagecrates/palyra-daemon/src/application/run_stream/orchestration.rs#3-15. - State Machine: Tracks transitions through
RunLifecycleState(e.g.,Queued,Running,Waiting,Terminal) crates/palyra-daemon/src/orchestrator.rs#136-137.
The Tape
An append-only journal specific to an agent run. It records every event (user messages, tool calls, tool results, and model responses) to ensure deterministic replay and auditability.- Implementation: Managed via
OrchestratorTapeAppendRequestcrates/palyra-daemon/src/journal.rs#47-50. - Replay: Replay continuity is projected using
project_replay_continuity_policycrates/palyra-daemon/src/journal.rs#50-54.
Natural Language to Code Entity Mapping (Run Lifecycle)
This diagram illustrates how a natural language request from a user flows into specific code entities and state transitions within the daemon. Sources: crates/palyra-daemon/src/application/run_stream/orchestration.rs#1-15, crates/palyra-daemon/src/gateway.rs#72-85, crates/palyra-daemon/src/orchestrator.rs#136-137Tooling & Execution
Sandbox Tiers
Palyra uses a tiered security model for executing code and processes to balance performance with isolation.- Tier B: Direct process spawn with environment scrubbing and Unix
rlimitquotas crates/palyra-daemon/src/sandbox_runner.rs#6-7. - Tier C: Heavy isolation using backends like Docker, Bubblewrap, or
sandbox_exec. Isolation planning is handled bybuild_tier_c_command_plancrates/palyra-daemon/src/sandbox_runner.rs#8-10.
Workspace Scoping
A security constraint that limits tool access (filesystem, search) to specific directory roots, preventing path traversal attacks.- Code Pointer:
ActiveWorkspaceRootandsession_active_workspace_rootcrates/palyra-daemon/src/application/tool_runtime/workspace_scope.rs#73-77.
Tool Approval Posture
Determines if a tool requires explicit operator consent before execution.- AlwaysAllow: Tool executes without prompting.
- AskEachTime: Generates an
ApprovalPromptRecordin the journal crates/palyra-daemon/src/journal.rs#87-89. - Implementation: Defined in
ToolApprovalPosturecrates/palyra-daemon/src/application/tool_registry/types.rs#13-16.
Memory & Retrieval
Hybrid Retrieval
A search strategy combining lexical (FTS5) and semantic (Vector) search to find relevant context for the agent.- Lexical: Uses SQLite FTS5 for keyword matching crates/palyra-daemon/src/journal.rs#138-140.
- Semantic: Uses cosine similarity on embeddings crates/palyra-daemon/src/journal.rs#143-145.
- Scoring: Handled by
score_memory_candidatesandscore_workspace_candidatescrates/palyra-daemon/src/gateway/runtime.rs#106-107.
Instruction Compiler
A deterministic component that assembles the “System Prompt” for the LLM by layering runtime facts, tool schemas, and trust summaries.- Implementation:
InstructionCompiler::compilecrates/palyra-daemon/src/application/instruction_compiler.rs#111-116. - Versioning: Tracked by
INSTRUCTION_COMPILER_VERSIONto ensure cache consistency crates/palyra-daemon/src/application/instruction_compiler.rs#26-26.
Memory Scopes
Memory is segmented to prevent cross-contamination between users or sessions.- Principal: Durable memory tied to a specific user identity.
- Session: Volatile memory tied to the current conversation crates/palyra-daemon/src/application/tool_registry/builtin.rs#112-114.
Security & Privacy
Redaction Pipeline
A multi-stage system that scrubs sensitive information (API keys, passwords, PII) before it is persisted to the journal or sent to the frontend.- Journal Redaction:
sanitize_payloadcrates/palyra-daemon/src/journal.rs#11-15. - Console Redaction:
redact_console_diagnostics_valuecrates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#10-15. - Sensitive Markers: Defined in
SENSITIVE_URL_PATH_MARKERScrates/palyra-daemon/src/sandbox_runner.rs#132-133 andSENSITIVE_KEY_FRAGMENTScrates/palyra-daemon/src/journal.rs#81-94.
Hash-Chaining
A tamper-evident mechanism where each journal event contains a SHA-256 hash of itself and the previous event’s hash.- Logic:
compute_hashcrates/palyra-daemon/src/journal.rs#12-15.
Security Entity Mapping (Tool Execution)
This diagram maps the high-level concept of “Secure Tool Execution” to the specific code modules responsible for enforcement. Sources: crates/palyra-daemon/src/sandbox_runner.rs#1-15, crates/palyra-daemon/src/application/approvals.rs#84-85, crates/palyra-daemon/src/sandbox_runner.rs#121-122, crates/palyra-daemon/src/journal.rs#40-40Technical Terms Reference
| Term | Definition | Code Pointer |
|---|---|---|
| ACP | Agent Control Protocol; bridge for CLI/TUI interaction. | crates/palyra-cli/src/acp_bridge.rs#27-27 |
| A2UI | Agent-to-UI; the protocol for rendering rich UI components in the console. | crates/palyra-daemon/src/gateway.rs#29-31 |
| CronJob | A scheduled agent run defined by a Recurrence rule. | crates/palyra-daemon/src/journal.rs#91-92 |
| Flow | A multi-step agent procedure or lineage. | crates/palyra-daemon/src/journal.rs#57-59 |
| JournalStore | The SQLite persistence layer for all daemon state. | crates/palyra-daemon/src/journal.rs#7-9 |
| ModelProvider | An adapter for external LLMs (OpenAI, Anthropic, etc.). | crates/palyra-daemon/src/model_provider.rs#103-106 |
| Recall | The process of retrieving relevant memories for a prompt. | crates/palyra-daemon/src/application/recall.rs#101-101 |
| Vault | Secure storage for secrets (API keys) with envelope encryption. | crates/palyra-daemon/src/gateway.rs#47-47 |