Module wasm_runner

Expand description

WASM tool execution sandbox and built-in tool catalog.

Provides types and configuration for running tools inside isolated WASM sandboxes with fuel metering, memory limits, and host filesystem isolation.

§K3 Tool Lifecycle

Tools go through: Build -> Deploy -> Execute -> Version -> Revoke. This module provides the execution runtime and tool catalog; the lifecycle management is in crate::tree_manager.

§Feature Gate

This module is compiled unconditionally, but the actual Wasmtime runtime integration requires the wasm-sandbox feature flag. Without it, WasmToolRunner::new returns a runner that rejects all tool loads with WasmError::RuntimeUnavailable.

§Security

Each tool execution gets its own isolated store:

No host filesystem access (unless WASI explicitly enabled)
No network access
CPU bounded by fuel metering
Memory bounded by configurable cap
Wall-clock timeout as safety net

Structs§

AgentInspectTool: Built-in agent.inspect tool.
AgentListTool: Built-in agent.list tool.
AgentResumeTool: Built-in agent.resume tool.
AgentSendTool: Built-in agent.send tool.
AgentSpawnTool: Built-in agent.spawn tool.
AgentStopTool: Built-in agent.stop tool.
AgentSuspendTool: Built-in agent.suspend tool.
BuiltinToolSpec: Specification of a built-in kernel tool.
Certificate: A signing certificate in the CA chain.
CompiledModuleCache: Compiled module cache with LRU eviction.
DeployedTool: A tool with its spec and version history.
FsCopyTool: Built-in fs.copy tool.
FsCreateDirTool: Built-in fs.create_dir tool.
FsExistsTool: Built-in fs.exists tool.
FsGlobTool: Built-in fs.glob tool.
FsMoveTool: Built-in fs.move tool.
FsReadDirTool: Built-in fs.read_dir tool.
FsReadFileTool: Built-in fs.read_file tool.
FsRemoveTool: Built-in fs.remove tool.
FsStatTool: Built-in fs.stat tool.
FsWriteFileTool: Built-in fs.write_file tool.
IpcSendTool: Built-in ipc.send tool.
IpcSubscribeTool: Built-in ipc.subscribe tool.
SandboxConfig: Filesystem sandbox configuration for built-in tools.
SandboxDecision: Result of evaluating the multi-layer sandbox stack.
ShellCommand: A shell command to be executed in the sandbox.
ShellExecTool: Built-in shell.exec tool wrapping execute_shell.
ShellPipeline: A shell pipeline compiled into a chain-linked WASM tool spec.
ShellResult: Result of a shell command execution.
SysChainQueryTool: Built-in sys.chain.query tool.
SysChainStatusTool: Built-in sys.chain.status tool.
SysCronAddTool: Built-in sys.cron.add tool.
SysCronListTool: Built-in sys.cron.list tool.
SysCronRemoveTool: Built-in sys.cron.remove tool.
SysEnvGetTool: Built-in sys.env.get tool.
SysServiceHealthTool: Built-in sys.service.health tool.
SysServiceListTool: Built-in sys.service.list tool.
SysTreeInspectTool: Built-in sys.tree.inspect tool.
SysTreeReadTool: Built-in sys.tree.read tool.
ToolRegistry: Registry of available tools for dispatch.
ToolSignature: A cryptographic signature binding a tool definition to a signer identity.
ToolState: Per-execution state for a WASM tool.
ToolVersion: A deployed version of a tool.
WasmSandboxConfig: Configuration for the WASM sandbox.
WasmTool: A loaded WASM tool module.
WasmToolResult: Result of a WASM tool execution.
WasmToolRunner: WASM tool runner.
WasmValidation: Validation result for a WASM module.

Enums§

BackendSelection: Backend selection for tool execution.
SandboxLayer: Which sandbox layer denied (or allowed) access.
ToolCategory: Category of a built-in kernel tool.
ToolError: Tool execution errors.
ToolSigningAuthority: Tool signing authority – identifies who signed a tool module.
WasiFsScope: WASI filesystem access scope for a tool.
WasmError: WASM runner errors.

Traits§

BuiltinTool: Trait for built-in kernel tools.

Functions§

builtin_tool_catalog: Return the complete catalog of 27 built-in kernel tools.
compute_module_hash: Compute SHA-256 hash of WASM module bytes.
execute_shell: Execute a shell command and return the result.
verify_tool_signature: Verify a tool’s Ed25519 signature against a public key.