palyra-plugins-runtime crate. This system is the foundation for Skills, which are signed, versioned artifacts containing WASM modules, manifests, and metadata.
Plugin Runtime Architecture
The runtime is built on Wasmtime and implements a strict capability-based security model. Plugins cannot access the host system directly; they must interact through a set of “Host Capability” imports defined in the WIT-like interface.WasmRuntime Implementation
TheWasmRuntime class in crates/palyra-plugins/runtime/src/lib.rs manages the lifecycle of WASM execution. It enforces hard limits on resource consumption to prevent Denial of Service (DoS) attacks.
| Limit | Description | Default Value |
|---|---|---|
fuel_budget | Instruction count limit (deterministic) | 10,000,000 crates/palyra-plugins/runtime/src/lib.rs#34-34 |
max_memory_bytes | Maximum linear memory allocation | 64 MB crates/palyra-plugins/runtime/src/lib.rs#35-35 |
max_table_elements | Maximum WASM table entries | 100,000 crates/palyra-plugins/runtime/src/lib.rs#36-36 |
max_instances | Concurrent instance limit per store | 256 crates/palyra-plugins/runtime/src/lib.rs#37-37 |
Capability Grant System
Plugins operate under aCapabilityGrantSet, which allowlists specific external resources. These grants are translated into integer handles passed to the WASM guest at runtime.
Code Entity Mapping: Runtime Execution
Sources: [crates/palyra-plugins/runtime/src/lib.rs#105-186](http://crates/palyra-plugins/runtime/src/lib.rs#105-186), [crates/palyra-plugins/runtime/src/lib.rs#42-81](http://crates/palyra-plugins/runtime/src/lib.rs#42-81)
Skill Artifacts & Manifests
A Skill is a packaged.palyra-skill archive (ZIP format) containing a mandatory skill.toml manifest, WASM modules, and optional assets.
skill.toml Structure
The manifest defines the skill’s identity, required capabilities, and tool entrypoints.- Identity:
skill_id,version, andpublisher. - Entrypoints: Mapping of tool IDs to WASM function exports crates/palyra-skills/src/models.rs.
- Capabilities: Requested access to HTTP hosts, filesystem roots, and secrets crates/palyra-skills/examples/echo-http/skill.toml#24-41.
Security & Trust Store
Palyra employs a Trust-on-First-Use (TOFU) pinning mechanism for skill publishers.- Verification: The
verify_skill_artifactfunction checks Ed25519 signatures against theSkillTrustStorecrates/palyra-skills/src/verify.rs. - Quarantine: Newly discovered skills or those with signature mismatches are placed in quarantine until promoted by an operator.
- Audit: The
audit_skill_artifact_securityfunction performs static analysis on the WASM module (e.g., checking exported function counts) crates/palyra-skills/src/audit.rs.
[crates/palyra-skills/src/lib.rs#11-24](http://crates/palyra-skills/src/lib.rs#11-24), [crates/palyra-skills/src/manifest.rs#12-49](http://crates/palyra-skills/src/manifest.rs#12-49)
Plugin Execution Flow
When a tool call is dispatched to a WASM plugin, thewasm_plugin_runner.rs in the daemon handles the resolution and execution.
- Resolution:
resolve_module_sourcedetermines if the module is inline or part of an installed skill crates/palyra-daemon/src/wasm_plugin_runner.rs#179-213. - Capability Mapping:
capability_grants_from_manifestextracts the required permissions from theskill.tomlcrates/palyra-skills/src/runtime.rs. - Execution:
execute_moduleinitializes theWasmRuntime, sets the fuel budget, and invokes the entrypoint crates/palyra-daemon/src/wasm_plugin_runner.rs#271-310.
Error Handling
The runner maps WASM traps and resource exhaustion toWasmPluginRunErrorKind:
QuotaExceeded: Hit fuel or memory limits.CapabilityDenied: Attempted to access a resource not in the manifest.TimedOut: Exceededwall_clock_timeout_ms.
[crates/palyra-daemon/src/wasm_plugin_runner.rs#43-51](http://crates/palyra-daemon/src/wasm_plugin_runner.rs#43-51), [crates/palyra-daemon/src/wasm_plugin_runner.rs#96-126](http://crates/palyra-daemon/src/wasm_plugin_runner.rs#96-126)
CLI Skill Commands
Thepalyra skills command group provides the primary interface for managing the skill lifecycle.
| Command | Function | Key Implementation |
|---|---|---|
package build | Compiles manifest and WASM into a signed artifact | build_signed_skill_artifact crates/palyra-cli/src/commands/skills.rs#59-67 |
package verify | Validates signatures and trust status | verify_skill_artifact crates/palyra-cli/src/commands/skills.rs#124-126 |
install | Adds a skill to the managed skills directory | install_skill_artifact crates/palyra-cli/tests/skills_lifecycle.rs#186-197 |
list | Displays installed skills and their runtime status | emit_inventory_list crates/palyra-cli/src/output/skills.rs#25-57 |
[crates/palyra-cli/src/commands/skills.rs#5-105](http://crates/palyra-cli/src/commands/skills.rs#5-105), [crates/palyra-cli/src/output/skills.rs#4-119](http://crates/palyra-cli/src/output/skills.rs#4-119)