Skip to main content
The WASM Plugin Runtime provides a secure, sandboxed execution environment for Skill tools and system hooks. It leverages wasmtime to enforce strict resource constraints, including fuel (instruction) budgets and memory limits, while providing a capability-based interface for guest modules to interact with the host.

​
Runtime Host Architecture

The host environment is primarily implemented in the palyra-plugins-runtime crate, which abstracts wasmtime into a high-level WasmRuntime interface.

​
Resource Constraints and Policy

Execution is governed by the WasmPluginRunnerPolicy, which defines the sandbox boundaries for a specific plugin instance.
Policy FieldDescriptionFile Reference
fuel_budgetTotal WebAssembly instructions allowed before termination.crates/palyra-daemon/src/wasm_plugin_runner.rs#22-22
max_memory_bytesMaximum linear memory allocation for the WASM instance.crates/palyra-daemon/src/wasm_plugin_runner.rs#23-23
max_instancesLimit on recursive or concurrent instances within the store.crates/palyra-daemon/src/wasm_plugin_runner.rs#25-25
allowed_http_hostsWhitelist of domains the plugin can access via host calls.crates/palyra-daemon/src/wasm_plugin_runner.rs#26-26
The WasmRuntime uses wasmtime::StoreLimits and consume_fuel(true) to enforce these limits at the engine level crates/palyra-plugins/runtime/src/lib.rs#116-118.

​
Host Capability Interface

Plugins interact with the Palyra ecosystem through a set of imported functions defined in the HOST_CAPABILITIES_IMPORT_MODULE. These allow the guest to request access to secrets, storage, and communication channels without direct access to the host’s filesystem or network. Capability Binding Flow:
  1. Grant Resolution: The host resolves CapabilityGrantSet based on the plugin’s requested capabilities and the operator’s defined PluginCapabilityProfile crates/palyra-daemon/src/plugins.rs#54-63.
  2. Handle Mapping: Grants (e.g., a specific secret key) are mapped to opaque i32 handles crates/palyra-plugins/runtime/src/lib.rs#72-81.
  3. Linker Registration: The register_capability_bindings function links these handles to the WASM instance, allowing the guest to query them via functions like host_capability_secret_handle crates/palyra-plugins/runtime/src/lib.rs#206-230.

​
System Entity Association

The following diagram bridges the high-level plugin concepts to the specific Rust entities responsible for execution. Plugin Execution Entity Map Sources: crates/palyra-daemon/src/wasm_plugin_runner.rs#18-30, crates/palyra-daemon/src/wasm_plugin_runner.rs#96-126, crates/palyra-plugins/runtime/src/lib.rs#105-108, crates/palyra-plugins/runtime/src/lib.rs#201-204

​
Execution Entrypoints

​
run_wasm_plugin

The primary entrypoint for the daemon to execute a WASM module. It handles:
  1. Validation: Parses the input_json and validates metadata like skill_id and tool_id crates/palyra-daemon/src/wasm_plugin_runner.rs#108-112.
  2. Module Resolution: Loads the WASM bytes from either an installed skill artifact or an inline payload (if permitted by policy) crates/palyra-daemon/src/wasm_plugin_runner.rs#113-113.
  3. Timeout Enforcement: Combines the policy timeout with the requested timeout to arm an epoch-based watchdog crates/palyra-daemon/src/wasm_plugin_runner.rs#120-125.

​
execute_module

Internal function that instantiates the WASM module using wasmtime::Linker and calls the designated export (defaulting to palyra_plugin_main) crates/palyra-daemon/src/wasm_plugin_runner.rs#271-300.

​
Plugin Hooks System

Hooks allow plugins to react to system-level events within the daemon. This is managed via HookBindingRecord entries stored in bindings.json within the hooks root directory crates/palyra-daemon/src/hooks.rs#107-112.

​
Supported Events

Event StringHookEventKindDescription
gateway:startupGatewayStartupFired when the GatewayRuntimeState initializes.
skill:enabledSkillEnabledFired when a skill is moved out of quarantine.
skill:quarantinedSkillQuarantinedFired when a skill fails security audit.
Sources: crates/palyra-daemon/src/hooks.rs#79-95

​
Hook Dispatch Logic

When an event occurs, the hooks_for_plugin index is queried crates/palyra-daemon/src/hooks.rs#161-166. For each enabled binding, the daemon resolves the associated WASM module and invokes it via run_resolved_wasm_plugin crates/palyra-daemon/src/hooks.rs#15-16.

​
Agent-to-UI Protocol (A2UI)

The palyra-a2ui system provides a standardized protocol for WASM plugins to render interactive UI components within the Web Console.

​
Data Flow

  1. Plugin Output: A WASM tool returns a JSON payload conforming to the A2uiDocument schema.
  2. Console Delivery: The daemon streams this document to the web frontend as part of a tool execution result.
  3. React Rendering: The A2uiRenderer component parses the document and maps its components (text, markdown, lists, tables, forms, charts) to React components apps/web/src/a2ui/renderer.tsx#33-59.
A2UI Rendering Pipeline Sources: apps/web/src/a2ui/renderer.tsx#66-97, crates/palyra-daemon/src/wasm_plugin_runner.rs#33-35, crates/palyra-daemon/src/hooks.rs#9-10

​
Form Interaction

The A2uiForm component handles user input within the console. When a user submits an A2UI form, it triggers an onFormSubmit callback, which sends the A2uiFormSubmitEvent (containing componentId and values) back to the agent to continue the loop apps/web/src/a2ui/renderer.tsx#148-154. Sources: apps/web/src/a2ui/renderer.tsx#130-177, apps/web/src/a2ui/types.ts (implied by renderer usage)