Expand --enable-tools to support user-provided host functions

[danbugs]

Context

--enable-tools currently registers a hardcoded echo tool. The library API already supports arbitrary host functions (users write Rust), but there's no CLI equivalent for users who want custom tools without writing a Rust program.

Problem

Passing custom host-side code to a CLI is fundamentally hard. There's no universal way to accept arbitrary host-side logic without either assuming a toolchain or embedding a runtime.

Options explored

1. Guest-side Python handlers

--tool greet=./greet.py — mount the script into the guest, dispatch tool calls inside the guest Python runtime.

• Pro: users write Python, zero new deps, sandboxed by the VM for free
• Con: handlers run inside the VM, can't access the host — breaks the "escape hatch" contract of host functions

2. Embedded scripting (Rhai or Lua)

--tool greet=./greet.rhai — embed a lightweight scripting engine in the hyperlight-unikraft binary.

• Pro: no external deps, runs on the host, capability control (scripts can only call Rust-bound functions like read_file, http_get, etc.)
• Con: not a full host function — no std lib, no crate deps, limited to whatever building blocks we expose. Users learn a new (small) language

3. Wasm modules

--tool greet=./greet.wasm — run handlers in a Wasm runtime (wasmtime).

• Pro: language-agnostic (Rust/Go/C compile to Wasm), sandboxed with WASI capabilities
• Con: adds a Wasm runtime dep, users must compile to Wasm, overhead

4. Executable protocol

--tool greet=./handler — invoke any binary, JSON on stdin/stdout.

• Pro: full power, any language
• Con: user must compile/install their own binary, no sandboxing

5. Don't

Keep --enable-tools as a demo of the capability. Users who need custom tools use the library API.

Recommendation

No single approach gives both "full host-side power" and "just drop in a script." The realistic split:

• CLI users who want convenience: guest-side Python handlers (option 1) or Rhai (option 2) cover the 80% case
• Users who need full power: library API (already works today)

Open to input on which approach (if any) is worth pursuing based on actual user demand.

[cachebag]

I'm not sure. Wasm does seem like a good format to distribute host functions and getting the sandboxing for free is nice, but it will inevitably restrict what the host function can do.

I think in a sense, that restriction is actually the point. WASI capabilities let you be quite precise about the things tools can access, which is a stronger security model than what is there today where host functions are atomic. If a handler genuinely needs unrestricted host access, I think that's the case the library API already covers well?

I could add a --tool name=./handler.wasm flag that invokes Wasm modules via wasmtime with configurable WASI capabilities, wired into the existing __dispatch JSON envelope. Then we'd gate it behind a wasm-tools feature flag so it's opt-in and doesn't pull in wasmtime for users who don't need it.

If we're going that route, maybe a scripting language like Lua/Rhai works best (i.e., to remove the compilation step) and then hyperlight-unikraft can just have an embedded lightweight Lua/Rhai interpreter behind a feature flag?

I think this might be fine but is eliding a compile step an actual issue worth addressing here? Isn't it more so the case that users of this project are already compiling Unikraft images and Rust code, so the real friction is sandboxing and capability control?