Overview & Execution Lifecycle
When an orchestrator requests a tool call, the system transitions through a multi-stage pipeline to ensure the request is safe and authorized. This lifecycle is managed primarily within therun_stream orchestration layer.
- Proposal: The agent proposes a tool call with specific arguments.
- Validation & Budgeting: The daemon checks if the tool is allowlisted and if the run has remaining execution budget crates/palyra-daemon/src/tool_protocol.rs#22-26.
- Security Evaluation: The
PolicyEngine(Cedar) evaluates the request context (principal, channel, capabilities) crates/palyra-daemon/src/tool_protocol.rs#3-6. - Approval Flow: If the tool is marked as sensitive or the policy requires it, the execution halts until a human provides a decision crates/palyra-daemon/src/application/run_stream/tool_flow.rs#147-162.
- Execution: The tool is dispatched to the appropriate runtime (Sandbox Process Runner or WASM Plugin Runner) crates/palyra-daemon/src/tool_protocol.rs#13-17.
- Attestation: A
ToolAttestationis generated, capturing the execution hash and environment metadata for auditability crates/palyra-daemon/src/tool_protocol.rs#73-80.
Tool Execution Data Flow
The following diagram maps the transition from a natural language tool request to the code entities responsible for its safe execution. Natural Language to Code Entity Mapping Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#53-69, crates/palyra-daemon/src/tool_protocol.rs#73-80, crates/palyra-daemon/src/sandbox_runner.rs#147-151Tool Protocol & Validation
Thetool_protocol.rs file defines the core constraints for tool execution. Every tool call is subject to a ToolCallConfig which defines limits on execution time and total calls per run.
Input Validation & Quotas
To prevent resource exhaustion or injection attacks, the protocol enforces strict input size limits based on the tool category crates/palyra-daemon/src/tool_protocol.rs#139-147:| Tool Category | Max Input Size |
|---|---|
| Echo / Basic | 16 KB |
| Memory Search | 64 KB |
| HTTP Fetch | 64 KB |
| Process Runner | 128 KB |
| Workspace Patch | 256 KB |
| WASM Plugin | 448 KB |
Tool Capabilities
Tools are associated withToolCapability flags, which the policy engine uses to determine risk levels crates/palyra-daemon/src/tool_protocol.rs#47-52:
ProcessExec: Execution of OS binaries.Network: Egress access to external hosts.SecretsRead: Access to the Palyra Vault.FilesystemWrite: Modifications to the workspace.
Human-in-the-loop Approval Flow
The approval system intercepts sensitive tool calls. It uses aPendingToolApproval structure to present a request to the user via the Web Console or CLI.
Decision Components
The system tracks approvals using three primary dimensions:- ApprovalSubjectType: Categorizes what is being approved (e.g.,
Tool,BrowserAction,SecretAccess) crates/palyra-daemon/src/application/approvals/mod.rs#148-154. - DecisionScope: Determines how long an approval lasts crates/palyra-daemon/src/application/approvals/mod.rs#156-183:
Once: Applies only to the current specific call.Session: Applies to all identical calls within the current session.
- RiskLevel: Calculated based on tool capabilities and input (e.g.,
Low,Medium,High) crates/palyra-daemon/src/application/approvals/mod.rs#111-115.
Approval State Machine
The approval flow is asynchronous, often involving a gRPC stream wait or a long-poll from the web UI. Approval Resolution Logic Sources: crates/palyra-daemon/src/application/approvals/mod.rs#100-115, crates/palyra-daemon/src/application/run_stream/tool_flow.rs#212-227, crates/palyra-daemon/src/transport/http/handlers/console/approvals.rs#57-97Execution & Attestation
Once authorized, tools are executed in a constrained environment. The system supports two primary runners:Sandbox Process Runner (Tier-B/C)
Used for executing local binaries. It supportsEgressEnforcementMode (None, Preflight, Strict) to control network access crates/palyra-daemon/src/sandbox_runner.rs#47-51.
- Tier-B: Uses standard OS resource limits (rlimits) crates/palyra-daemon/src/sandbox_runner.rs#65-68.
- Tier-C: Uses platform-specific isolation like
LinuxBubblewraporMacosSandboxExeccrates/palyra-sandbox/src/lib.rs#8-13.
Tool Attestation
After execution, the daemon produces aToolAttestation crates/palyra-daemon/src/tool_protocol.rs#73-80. This record includes:
- Execution Hash: A SHA-256 hash of the tool input and output to ensure integrity crates/palyra-daemon/src/tool_protocol.rs#75.
- Executor Metadata: Identifies which sandbox tier and backend (e.g.,
bwrap) was used crates/palyra-daemon/src/tool_protocol.rs#78-79. - Timing: Precise unix timestamp of execution crates/palyra-daemon/src/tool_protocol.rs#76.