.palyra-skill) for extending agent capabilities using WebAssembly (Wasm). It implements a layered security model combining Ed25519 code signing, publisher trust via Trust-On-First-Use (TOFU), and a resource-constrained Wasmtime runtime with fine-grained capability grants.
Skill Artifact Format
A skill artifact is a ZIP-compressed archive containing a mandatory manifest, signed modules, and optional assets. The structure is strictly validated to prevent path traversal and unauthorized file inclusion crates/palyra-skills/src/artifact.rs#1-20.Manifest Structure (skill.toml)
The skill.toml file defines the identity, entrypoints, and required capabilities of the skill. It is parsed using parse_manifest_toml crates/palyra-skills/src/manifest.rs#38-43.
| Section | Description |
|---|---|
manifest_version | Current version (2) crates/palyra-skills/src/constants.rs#20-20. |
skill_id | Unique identifier (e.g., acme.echo_http) crates/palyra-skills/src/tests.rs#27-27. |
entrypoints.tools | Defines the tool ID, input/output JSON schemas, and risk profile crates/palyra-skills/src/tests.rs#33-47. |
capabilities | Explicit allowlists for HTTP egress, filesystem roots, and secrets crates/palyra-skills/src/tests.rs#49-65. |
operator.plugin | Maps tools to specific Wasm modules and entrypoint functions crates/palyra-skills/src/tests.rs#79-83. |
Internal Artifact Layout
skill.toml: The validated manifest crates/palyra-skills/src/constants.rs#28-28.signature.json: Ed25519 signature of the payload SHA-256 hash crates/palyra-skills/src/constants.rs#28-28.modules/: Wasm binaries crates/palyra-cli/src/commands/skills.rs#43-52.sbom.cdx.json: CycloneDX Software Bill of Materials crates/palyra-skills/src/constants.rs#27-27.provenance.json: SLSA-style build provenance crates/palyra-skills/src/constants.rs#27-27.
Security and Trust Model
Palyra employs a “Fail-Closed” trust model for skill execution.Code Signing and Verification
Artifacts are signed during theskills package build flow using an Ed25519 key crates/palyra-cli/src/commands/skills.rs#79-87. The verify_skill_artifact function ensures the signature matches the payload and that the publisher is trusted crates/palyra-skills/src/verify.rs#43-43.
Publisher Trust (TOFU + Allowlist)
Trust is managed via theSkillTrustStore crates/palyra-skills/src/models.rs#19-19:
- Allowlist: Explicitly trusted publisher public keys.
- TOFU (Trust-On-First-Use): If enabled, the first time a publisher’s key is seen, it is recorded and trusted for subsequent updates crates/palyra-cli/src/commands/skills.rs#145-146.
- Integrity: The
trust.jsonfile is protected by a SHA-256 HMAC to prevent manual tampering crates/palyra-cli/src/commands/skills.rs#139-139.
Security Audit
Before installation, artifacts undergo aSkillSecurityAudit which checks for:
- Wasm Export Limits: Prevents excessive surface area crates/palyra-skills/src/constants.rs#27-27.
- Filesystem Safety: Detects symlink escapes or unsafe permissions crates/palyra-daemon/src/plugins.rs#158-163.
- Capability Overreach: Flags skills requesting broad wildcards (e.g.,
*for HTTP egress) crates/palyra-skills/src/manifest.rs#147-155.
Wasm Plugin Runtime
Plugins are executed in a sandboxed environment powered bywasmtime. The WasmRuntime enforces strict resource quotas and capability mediation crates/palyra-plugins/runtime/src/lib.rs#1-6.
Resource Quotas
Limits are defined inRuntimeLimits and enforced per-invocation crates/palyra-plugins/runtime/src/lib.rs#44-54:
- Fuel Budget: Instruction-level metering (default 10M) crates/palyra-plugins/runtime/src/lib.rs#59-59.
- Memory: Linear memory cap (default 64MB) crates/palyra-plugins/runtime/src/lib.rs#60-60.
- Instances/Tables: Caps on module instantiation and table elements crates/palyra-plugins/runtime/src/lib.rs#61-62.
Capability Mediation
Plugins cannot access the host directly. Instead, they receive opaque integer handles for granted resources crates/palyra-plugins/runtime/src/lib.rs#98-112.Data Flow: Skill Invocation
Sources: crates/palyra-daemon/src/wasm_plugin_runner.rs#163-186, crates/palyra-plugins/runtime/src/lib.rs#3-6Plugin SDK and WIT Interface
The interaction between the host and the Wasm guest is defined by the Palyra Plugin SDK using the WebAssembly Interface Type (WIT) format.WIT Interface (palyra-sdk.wit)
The SDK exposes “Tier A” capabilities via the palyra:plugins/host-capabilities import module crates/palyra-plugins/sdk/src/lib.rs#24-24.
Key SDK Constants:
- World Name:
palyra-plugincrates/palyra-plugins/sdk/src/lib.rs#22-22. - Entrypoint:
runcrates/palyra-plugins/sdk/src/lib.rs#46-46. - Handle Bases: HTTP (10,000), Secret (20,000), Storage (30,000), Channel (40,000) crates/palyra-plugins/runtime/src/lib.rs#29-32.
Typed Plugin Contracts
Beyond simple tools, plugins can implement specific host extension points calledTypedPluginContractKind crates/palyra-plugins/sdk/src/lib.rs#60-73.
| Contract Kind | Purpose |
|---|---|
memory_provider | Custom agent memory storage/retrieval crates/palyra-plugins/sdk/src/lib.rs#80-80. |
routing_strategy | Logic for selecting LLM providers crates/palyra-plugins/sdk/src/lib.rs#82-82. |
run_lifecycle_hook | Logic executed at agent run start/end crates/palyra-plugins/sdk/src/lib.rs#83-83. |
delivery_adapter | Custom channel messaging logic crates/palyra-plugins/sdk/src/lib.rs#89-89. |
Code Entity Mapping
Sources: crates/palyra-daemon/src/wasm_plugin_runner.rs#163-167, crates/palyra-plugins/runtime/src/lib.rs#22-25, crates/palyra-daemon/src/plugins.rs#68-96CLI and Console Integration
The skill lifecycle is exposed through thepalyra skills CLI and the Web Console.
- Packaging:
run_skills(SkillsCommand::Package)handles artifact creation and signing crates/palyra-cli/src/commands/skills.rs#23-36. - Inventory:
console_skills_list_handlerprovides a JSON view of installed skills and their runtime status crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#23-27. - Dynamic Building: The
Dynamic Tool Builderallows generating skill scaffolds from natural language prompts or learning candidates crates/palyra-daemon/src/transport/http/handlers/console/skills.rs#94-112.
Sources:
- crates/palyra-cli/src/commands/skills.rs
- crates/palyra-daemon/src/wasm_plugin_runner.rs
- crates/palyra-plugins/runtime/src/lib.rs
- crates/palyra-plugins/sdk/src/lib.rs
- crates/palyra-skills/src/lib.rs
- crates/palyra-skills/src/manifest.rs
- crates/palyra-skills/src/artifact.rs
- crates/palyra-daemon/src/transport/http/handlers/console/skills.rs
- crates/palyra-daemon/src/plugins.rs