Tool Dispatch and Lifecycle
Tool execution follows a rigorous lifecycle managed by theRunStream within the palyrad gateway. This process ensures that every tool call is evaluated against the ToolCallPolicy, recorded in the JournalStore, and executed within the appropriate sandbox.
Execution Flow
The primary entry point for tool execution in a run stream isprocess_run_stream_tool_proposal_event crates/palyra-daemon/src/application/run_stream/tool_flow.rs#53-69.
- Security Evaluation:
evaluate_tool_proposal_securitychecks the tool against Cedar policies and determines if it is sensitive crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-134. - Proposal Recording: The proposal is broadcast via the “Tape” (event stream) and recorded in the journal crates/palyra-daemon/src/application/run_stream/tool_flow.rs#136-146.
- Approval Resolution: If the policy or tool sensitivity requires it, the system awaits user intervention via
resolve_run_stream_tool_approval_outcomecrates/palyra-daemon/src/application/run_stream/tool_flow.rs#212-228. - Policy Decision:
resolve_tool_proposal_decision_for_contextsynthesizes the security evaluation and approval results into a finalToolDecisioncrates/palyra-daemon/src/application/run_stream/tool_flow.rs#163-174. - Runtime Dispatch: If allowed,
execute_tool_with_runtime_dispatchroutes the call to either thesandbox_runner(for native processes) or thewasm_plugin_runnercrates/palyra-daemon/src/gateway/mod.rs#25.
Tool Execution Data Flow
The following diagram illustrates the transition from a natural language intent to a code-enforced execution. “Tool Execution Flow” Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#53-101, crates/palyra-daemon/src/tool_protocol.rs#13-17, crates/palyra-policy/src/lib.rs#211-215Security Policy and Approvals
Palyra uses the Cedar policy language to define fine-grained access control for tools. Tools are classified byToolCapability (e.g., ProcessExec, Network, SecretsRead) crates/palyra-daemon/src/tool_protocol.rs#47-52.
ToolCallPolicy
TheToolCallConfig struct defines the global constraints for a session:
allowed_tools: Explicit list of permitted tool names crates/palyra-daemon/src/tool_protocol.rs#21.max_calls_per_run: Budget to prevent infinite loops crates/palyra-daemon/src/tool_protocol.rs#22.execution_timeout_ms: Hard wall-clock limit crates/palyra-daemon/src/tool_protocol.rs#23.
Approval Workflow
Sensitive actions (defined inSENSITIVE_CAPABILITY_POLICY_NAMES) crates/palyra-daemon/src/tool_protocol.rs#148-149 trigger a ToolDecision where approval_required is true crates/palyra-daemon/src/tool_protocol.rs#32. The daemon halts execution and waits for a RunStreamRequest containing a ToolApprovalResponse crates/palyra-daemon/src/application/run_stream/tool_flow.rs#216-227.
Sources: crates/palyra-daemon/src/tool_protocol.rs#19-44, crates/palyra-policy/src/lib.rs#99-181
Multi-Tier Sandboxing Model
Palyra implements a three-tier sandboxing model to balance performance and security.| Tier | Mechanism | Target | Isolation Level |
|---|---|---|---|
| Tier A | None | Trusted internal tools | Low (In-process) |
| Tier B | OS Resource Limits | Native binaries | Medium (cgroups/JobObjects) |
| Tier C | Full Namespacing | High-risk native binaries | High (Bubblewrap/Sandbox-exec) |
| Wasm | WebAssembly | Skill Plugins | Extreme (Instruction-level) |
Native Process Sandbox (Tier B & C)
Thesandbox_runner handles the execution of native commands. It enforces:
- Executable Denylist: Prevents spawning shells like
bash,powershell, ornodedirectly crates/palyra-daemon/src/sandbox_runner.rs#30-44. - Workspace Anchoring: Commands are constrained to a
workspace_rootcrates/palyra-daemon/src/sandbox_runner.rs#84. - Egress Enforcement: Modes include
None,Preflight(DNS check), andStrict(Runtime blocking) crates/palyra-daemon/src/sandbox_runner.rs#47-51.
bwrap (Bubblewrap) to create new PID, Network, and Mount namespaces crates/palyra-sandbox/src/lib.rs#130-144. It mounts a minimal /usr and /bin while providing a private /tmp and /dev crates/palyra-sandbox/src/lib.rs#145-157.
Wasm Plugin Runtime
For third-party “Skills,” Palyra uses a Wasmtime-based runtime crates/palyra-plugins/runtime/src/lib.rs#105-108.- Fuel Injection: Limits the number of instructions executed crates/palyra-plugins/runtime/src/lib.rs#174.
- Capability Grants: Wasm modules must request specific hosts or secrets, which are mapped to integer handles crates/palyra-plugins/runtime/src/lib.rs#43-48.
- Memory Limits: Defaulted to 64MB per instance crates/palyra-plugins/runtime/src/lib.rs#35.
Implementation Detail: Sandbox Dispatch
Therun_constrained_process function in sandbox_runner.rs serves as the primary orchestrator for native execution.
“Sandbox Execution Architecture”
Key Functions
canonical_workspace_root: Ensures the workspace path is absolute and exists crates/palyra-daemon/src/sandbox_runner.rs#172.validate_interpreter_argument_guardrails: Prevents passing script strings (e.g.,-c "rm -rf /") to allowed interpreters crates/palyra-daemon/src/sandbox_runner.rs#170.execute_process: Spawns the child process and polls for stdout/stderr while monitoring quotas crates/palyra-daemon/src/sandbox_runner.rs#203-209.