Replace legacy python tools echo with Wasm host function

Remove leftover --enable-tools references from the README and host
functions docs. Add a small echo WASIp1 host function example and update
the Python tools example plus CI runtime args to register it via
--tool echo=... instead of using the legacy built-in echo path.

Signed-off-by: akrm al-hakimi <alhakimiakrmj@gmail.com>

Author: cachebag

.github/workflows/test-examples.yml

@@ -183,8 +183,9 @@ jobs:
             args: "-- /hello.py"
             expect: "Hello from Python on Hyperlight"
           - example: python-tools
-            args: "--enable-tools -- /test_tools.py"
+            args: "-- /test_tools.py"
             expect: "Tool returned"
+            needs_echo_tool: true
           - example: nodejs
             args: "-- /app/hello.js"
             expect: "Hello from Node.js on Hyperlight"
@@ -270,9 +271,15 @@ jobs:
         if: steps.kvm_check.outputs.available == 'true'
         run: |
           cd host
-          cargo build --release --bin hyperlight-unikraft --bin multifn-test --bin pydriver-run
+          cargo build --release --features wasm-host-fns --bin hyperlight-unikraft --bin multifn-test --bin pydriver-run
           sudo cp target/release/hyperlight-unikraft /usr/local/bin/
 
+      - name: Build echo Wasm host function
+        if: steps.kvm_check.outputs.available == 'true' && matrix.needs_echo_tool == true
+        run: |
+          rustup target add wasm32-wasip1
+          cargo build --manifest-path examples/echo-wasm-host-fxn/Cargo.toml --release --target wasm32-wasip1
+
       - name: Build local-python-base images (python-agent-driver only)
         if: steps.kvm_check.outputs.available == 'true' && matrix.example == 'python-agent-driver'
         env:
@@ -338,6 +345,10 @@ jobs:
             mkdir -p "$mount_dir"
             mount_args="--mount $mount_dir:/host"
           fi
+          tool_args=""
+          if [ "${{ matrix.needs_echo_tool }}" = "true" ]; then
+            tool_args="--tool echo=../echo-wasm-host-fxn/target/wasm32-wasip1/release/echo-wasm-host-fxn.wasm"
+          fi
           case "${{ matrix.driver }}" in
             multifn-test)
               cmd=(timeout 60 /home/runner/work/hyperlight-unikraft/hyperlight-unikraft/host/target/release/multifn-test "$kernel" "$cpio")
@@ -350,7 +361,7 @@ jobs:
               if [ -n "$memory" ]; then
                 mem_args="-m $memory"
               fi
-              cmd=(timeout 120 hyperlight-unikraft -q $mem_args "$kernel" --initrd "$cpio" $mount_args ${{ matrix.args }})
+              cmd=(timeout 120 hyperlight-unikraft -q $mem_args "$kernel" --initrd "$cpio" $mount_args $tool_args ${{ matrix.args }})
               ;;
           esac
           set +e
@@ -514,8 +525,9 @@ jobs:
             args: "-- /hello.py"
             expect: "Hello from Python on Hyperlight"
           - example: python-tools
-            args: "--enable-tools -- /test_tools.py"
+            args: "-- /test_tools.py"
             expect: "Tool returned"
+            needs_echo_tool: true
           - example: nodejs
             args: "-- /app/hello.js"
             expect: "Hello from Node.js on Hyperlight"
@@ -575,12 +587,19 @@ jobs:
         shell: pwsh
         run: |
           cd host
-          cargo build --release --bin hyperlight-unikraft --bin multifn-test --bin pydriver-run --bin pyhl
+          cargo build --release --features wasm-host-fns --bin hyperlight-unikraft --bin multifn-test --bin pydriver-run --bin pyhl
           Copy-Item target\release\hyperlight-unikraft.exe $env:USERPROFILE\.cargo\bin\ -Force
           Copy-Item target\release\multifn-test.exe $env:USERPROFILE\.cargo\bin\ -Force
           Copy-Item target\release\pydriver-run.exe $env:USERPROFILE\.cargo\bin\ -Force
           Copy-Item target\release\pyhl.exe $env:USERPROFILE\.cargo\bin\ -Force
 
+      - name: Build echo Wasm host function
+        if: matrix.needs_echo_tool == true
+        shell: pwsh
+        run: |
+          rustup target add wasm32-wasip1
+          cargo build --manifest-path examples/echo-wasm-host-fxn/Cargo.toml --release --target wasm32-wasip1
+
       - name: Download prebuilt image
         uses: actions/download-artifact@v4
         with:
@@ -596,6 +615,7 @@ jobs:
           $driver = '${{ matrix.driver }}'
           $runArgs = '${{ matrix.args }}'
           $needsMount = '${{ matrix.needs_mount }}'
+          $needsEchoTool = '${{ matrix.needs_echo_tool }}'
 
           # Read memory from the example's Justfile (single source of truth).
           $memory = ''
@@ -617,6 +637,11 @@ jobs:
             $mountArgs = @('--mount', ($mountDir + ':/host'))
           }
 
+          $toolArgs = @()
+          if ($needsEchoTool -eq 'true') {
+            $toolArgs = @('--tool', 'echo=examples/echo-wasm-host-fxn/target/wasm32-wasip1/release/echo-wasm-host-fxn.wasm')
+          }
+
           # Strict mode: expected output must appear AND the driver
           # must exit 0. Matches Linux semantics.
           $PSNativeCommandUseErrorActionPreference = $false
@@ -643,7 +668,7 @@ jobs:
                 $memArgs = @('-m', $memory)
               }
               $out = & hyperlight-unikraft -q @memArgs `
-                $kernel --initrd $cpio @mountArgs @argList 2>&1
+                $kernel --initrd $cpio @mountArgs @toolArgs @argList 2>&1
               $rc = $LASTEXITCODE
             }
           }

README.md

@@ -49,7 +49,7 @@ This project enables running Linux applications (Python, Node.js, Go, Rust, C/C+
 
 ### Key Features
 
-- **Thin, opt-in host surface** — by default, the guest has no access to the host filesystem, network, or any host functions. When you enable features like `--mount`, `--net`, `--enable-tools`, or `--tool`, a single `__dispatch` JSON-RPC bridge is registered as the only guest→host channel. See [host_functions.md](docs/host_functions.md) for the full list of dispatchable operations
+- **Thin, opt-in host surface** — by default, the guest has no access to the host filesystem, network, or custom host tools. When you enable capabilities like `--mount`, `--net`, or `--tool`, a single `__dispatch` JSON-RPC bridge is registered as the only guest→host channel. See [host_functions.md](docs/host_functions.md) for the full list of dispatchable operations
 - **Identity-mapped memory** - Simplified memory layout (vaddr == paddr)
 - **Generic cmdline mechanism** - Pass arguments to any application via `-- arg1 arg2 ...`
 - **Fast cold start** - Hyperlight's lightweight design enables millisecond startup times
@@ -182,6 +182,7 @@ just run
 | `helloworld-c` | Static PIE C binary | Compiled with `musl-gcc` |
 | `rust` | Static PIE Rust binary | Compiled with `rustc --target x86_64-unknown-linux-musl` |
 | `python` | CPython 3.12 | Rootfs from Docker, script passed via cmdline |
+| `python-tools` | CPython 3.12 + host function call | Calls an echo Wasm host function registered with `--tool echo=...` |
 | `go` | Static PIE Go binary | Compiled with musl via Docker for CGO support |
 | `nodejs` | Node.js 21 | Rootfs from Alpine, script passed via cmdline |
 | `hostfs-posix-c` | C + unmodified POSIX | `open`/`read`/`write`/`mkdir` against `/host`, forwarded by `lib/hostfs` |
@@ -281,7 +282,6 @@ Options:
   -m, --memory <MEMORY>        Memory allocation (e.g., 256Mi, 512Mi, 1Gi) [default: 512Mi]
       --stack <STACK>          Stack size (e.g., 8Mi) [default: 8Mi]
   -q, --quiet                  Quiet mode — suppress host-side status messages
-      --enable-tools           Register the built-in echo tool
       --tool <NAME=WASM>        Register a WASIp1 module as a host tool (requires wasm-host-fns)
       --tool-wasi-dir <HOST[:GUEST]>
                                Preopen a read-write host directory for Wasm tools
@@ -315,10 +315,13 @@ Build the CLI with the optional `wasm-host-fns` feature to register host-side cu
 
 ```bash
 cargo build --manifest-path host/Cargo.toml --release --features wasm-host-fns --bin hyperlight-unikraft
-hyperlight-unikraft kernel --initrd app.cpio --tool greet=./greet.wasm
+rustup target add wasm32-wasip1
+cargo build --manifest-path examples/echo-wasm-host-fxn/Cargo.toml --release --target wasm32-wasip1
+hyperlight-unikraft kernel --initrd app.cpio \
+    --tool echo=examples/echo-wasm-host-fxn/target/wasm32-wasip1/release/echo-wasm-host-fxn.wasm
 ```
 
-The guest still calls the existing `__dispatch` envelope, for example `{"name":"greet","args":{"who":"Ada"}}`. The Wasm handler runs on the host in Wasmtime, receives that request JSON on stdin, and writes either a raw JSON result or `{"result": ...}` / `{"error": "..."}` to stdout. WASI filesystem and environment access are off unless granted with `--tool-wasi-dir`, `--tool-wasi-dir-ro`, `--tool-wasi-env`, or `--tool-wasi-env-inherit`.
+The guest still calls the existing `__dispatch` envelope, for example `{"name":"echo","args":{"message":"hello"}}`. The Wasm handler runs on the host in Wasmtime, receives that request JSON on stdin, and writes either a raw JSON result or `{"result": ...}` / `{"error": "..."}` to stdout. WASI filesystem and environment access are off unless granted with `--tool-wasi-dir`, `--tool-wasi-dir-ro`, `--tool-wasi-env`, or `--tool-wasi-env-inherit`.
 
 ## Project Structure
 

docs/host_functions.md

@@ -15,7 +15,7 @@ Implementation lives in [`host/src/lib.rs`](../host/src/lib.rs). Guest-side call
 | `fs_*` tools | **Off** | `--mount HOST[:GUEST]` (repeatable) |
 | `net_*` tools | **Off** | `--net`, `--net-allow`, or `--net-block` |
 | Inbound listen | **Off** | `--port PORT` (requires network enabled) |
-| Custom tools | **Off** | `--tool NAME=WASM` with `wasm-host-fns`, `SandboxBuilder::tool()`, or legacy/demo `--enable-tools` echo |
+| Custom tools | **Off** | `--tool NAME=WASM` with `wasm-host-fns` or `SandboxBuilder::tool()` |
 
 With **no flags**, the guest cannot reach the host filesystem or network through dispatch. Only internal plumbing (`__hl_exit`, `__hl_sleep`) is wired.
 
@@ -85,7 +85,6 @@ hyperlight-unikraft KERNEL [--initrd CPIO] [options] [-- APP_ARGS...]
 | `--net-allow HOST_OR_IP` | Allow-list outbound destinations (implies `--net`). Repeatable. |
 | `--net-block HOST_OR_IP` | Block-list; all other destinations allowed (implies `--net`). Mutually exclusive with `--net-allow`. |
 | `--port PORT` | Allow `net_bind` / listen on `PORT` (implies `--net`). Without `--port`, outbound-only: bind is rejected. |
-| `--enable-tools` | Registers only the built-in `echo` demo tool. It does not load user code; prefer `--tool NAME=WASM` for CLI custom tools or `SandboxBuilder::tool()` for library users. |
 | `--tool NAME=WASM` | With the Cargo feature `wasm-host-fns`, registers `WASM` as a host-side WASIp1 custom tool named `NAME`. Repeatable. |
 | `--tool-wasi-dir HOST[:GUEST]` | Preopens a read-write host directory for every CLI Wasm tool. Default guest path is `/host`. Repeatable. |
 | `--tool-wasi-dir-ro HOST[:GUEST]` | Preopens a read-only host directory for every CLI Wasm tool. Default guest path is `/host`. Repeatable. |
@@ -200,19 +199,20 @@ Sockets are host-side (`socket2`); the guest sees opaque numeric **`fd`** handle
 
 ## Custom tools
 
-**CLI demo tool:** `--enable-tools` registers only a built-in `echo` tool that returns `args` unchanged. It is useful as a smoke test and compatibility path, but it is not the CLI extension mechanism for user-provided host functions. CLI examples should prefer a Wasm `echo.wasm` registered with `--tool echo=...`; library examples should register an echo handler with `SandboxBuilder::tool()`.
-
-**CLI Wasm tools:** build with the optional feature and pass one or more `--tool` flags:
+**CLI Wasm tools:** build with the optional feature and pass one or more `--tool` flags. The `examples/echo-wasm-host-fxn` module is a minimal echo handler used by `examples/python-tools`:
 
 ```bash
 cargo build --manifest-path host/Cargo.toml --features wasm-host-fns --bin hyperlight-unikraft
-hyperlight-unikraft kernel --initrd app.cpio --tool greet=./greet.wasm
+rustup target add wasm32-wasip1
+cargo build --manifest-path examples/echo-wasm-host-fxn/Cargo.toml --release --target wasm32-wasip1
+hyperlight-unikraft kernel --initrd app.cpio \
+    --tool echo=examples/echo-wasm-host-fxn/target/wasm32-wasip1/release/echo-wasm-host-fxn.wasm
 ```
 
 Each `--tool NAME=WASM` module is compiled and linked before VM boot, then invoked as a fresh WASIp1 command for every matching guest `__dispatch` call. The handler receives the existing dispatch request on stdin:
 
 ```json
-{"name":"NAME","args":<json_value>}
+{"name":"echo","args":<json_value>}
 ```
 
 The handler writes JSON to stdout. It may write either a raw JSON result value or the normal dispatch envelope:

examples/echo-wasm-host-fxn/Cargo.lock

@@ -0,0 +1,9 @@
+[package]
+name = "echo-wasm-host-fxn"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[[bin]]
+name = "echo-wasm-host-fxn"
+path = "src/main.rs"

examples/echo-wasm-host-fxn/Cargo.toml

@@ -0,0 +1,19 @@
+# echo-wasm-host-fxn
+#
+# Builds a tiny WASIp1 command module that can be registered with:
+#   --tool echo=target/wasm32-wasip1/release/echo-wasm-host-fxn.wasm
+
+set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]
+
+target := "wasm32-wasip1"
+wasm := "target/wasm32-wasip1/release/echo-wasm-host-fxn.wasm"
+
+build:
+    rustup target add {{target}}
+    cargo build --release --target {{target}}
+
+path:
+    @echo {{wasm}}
+
+clean:
+    cargo clean

examples/echo-wasm-host-fxn/Justfile

@@ -0,0 +1,18 @@
+# echo-wasm-host-fxn
+
+A tiny WASIp1 command module used by the Python host-tools example as a custom host function.
+
+The Hyperlight host runs the module through `--tool echo=...`. The module receives the `__dispatch` request JSON on stdin:
+
+```json
+{"name":"echo","args":{"message":"hello"}}
+```
+
+It writes `{"result": args}` to stdout, so the outer host dispatch returns the original `args` value as the tool result.
+
+```bash
+just build
+hyperlight-unikraft kernel --initrd app.cpio \
+    --tool echo=target/wasm32-wasip1/release/echo-wasm-host-fxn.wasm \
+    -- /test_tools.py
+```