Skip to content
Back to search

wasm-tool-layers

Rust libraries for building a tool once as a CLI, MCP server, REST API and web UI, natively or as a sandboxed WASM component, from one description of its commands.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gerbillinae--wasm-tool-layers/badge.svg)](/listings/gerbillinae--wasm-tool-layers)

HTML

<a href="/listings/gerbillinae--wasm-tool-layers"><img src="/api/listings/gerbillinae--wasm-tool-layers/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 137 lines
  1. # wasm-tool-layers
  2. Rust libraries for building a tool once and offering it as a CLI, an MCP server, a REST API with a web UI, and optionally a sandboxed WebAssembly component, all generated from one description of its commands. The native build and the component run the same code the same way, and a conformance suite checks that they do.
  3. The design and its reasoning are in [opinionated/optional/wasm.md](https://github.com/gerbillinae/opinionated/blob/main/optional/wasm.md). A complete example tool is [anki-cards-rs](https://github.com/gerbillinae/anki-cards-rs).
  4. ## The shape
  5. ```
  6. interfaces CLI · MCP · REST · TUI generated from describe(), the same in both runtimes
  7. seam Backend what every interface talks to
  8. adapter tool-native | tool-host + export_tool!
  9. instance ToolInstance implemented once, in the tool's core
  10. core registry · library · tool-rest the same source on both targets
  11. ports native | WASI and host imports the only place the runtimes differ
  12. ```
  13. A tool implements `ToolInstance` once. `tool-native` runs it in process; `tool_wasi::export_tool!` exports it as a component, which `tool-host` runs. Both give the same extension shape, the same lifecycle, the same data directory and the same answer to a crash.
  14. ## The crates
  15. | Crate | For | What it is |
  16. |---|---|---|
  17. | `tool-contract` | every tool | The command registry, `describe()` (schemas, routes, errors, features, declared needs), `invoke`, `ToolError`, `Context`, `ToolInstance`, the `Backend` trait, route adaptors, and `conformance` |
  18. | `tool-ports` | every tool's core | The port traits the core reaches the world through: HTTP out, clock, secrets, questions, progress, timers, background work, change notification, serving, audio, and the data directory |
  19. | `tool-cli` | hosts | A CLI generated at run time from `describe()`, plus custom commands |
  20. | `tool-mcp` | hosts | MCP over stdio, generated from `describe()`, with changes since each session's last call |
  21. | `tool-rest` | a tool's core | Its HTTP interface, generated from the registry: command routes, browser adapters (the page, state, event stream), the token check |
  22. | `tool-serve` | hosts | The listening socket (hyper): localhost only, Origin and Host checks, forwarding with a "client gone" signal; the `serve` command |
  23. | `tool-native` | native builds | A `ToolInstance` on an owner thread behind a `Backend` handle, native ports (checked against the declared needs), and the standard CLI (`run`) |
  24. | `tool-wasi` | components | `export_tool!` (a `ToolInstance` as the component, with its ports), WASI ports, an async HTTP client, and serving `tool-rest` as `wasi:http/handler` |
  25. | `tool-files` | tool cores | Lock files and atomic writes over std::fs, for data a tool keeps in its directory; the same code natively and in a component |
  26. | `tool-host` | WASM hosts | The generic host as a library (wasmtime): grants, the owner thread, suspend and resume, the compilation cache, and extensions for custom capabilities |
  27. | `wasm-tool` | users | `tool-host` with nothing added: runs any tool component |
  28. | `tool-audio` | tools that play sound | A command-line player, as a native port and (feature `host`) as the `local:audio/player` WIT interface; `stub/` is a component that implements it as unavailable |
  29. `wit/` holds the `opinionated:tool` WIT package (the contract between a component and its host), `local:audio`, and the WASI 0.3.0 packages they use.
  30. ## Using them
  31. Each crate is its own dependency, from this one repository. Use the same tag for all of them, so they come from one checkout:
  32. ```toml
  33. [dependencies]
  34. tool-contract = { git = "https://github.com/gerbillinae/wasm-tool-layers", tag = "v0.3.0" }
  35. tool-ports = { git = "https://github.com/gerbillinae/wasm-tool-layers", tag = "v0.3.0" }
  36. tool-native = { git = "https://github.com/gerbillinae/wasm-tool-layers", tag = "v0.3.0" }
  37. ```
  38. The core implements the instance contract once:
  39. ```rust
  40. impl tool_contract::ToolInstance for MyTool {
  41. fn describe(&self) -> Description { REGISTRY.describe(self) }
  42. fn configure(&self, settings: Map<String, Value>) -> Result<(), ToolError> { … }
  43. fn invoke(self: Arc<Self>, cx: &Context, command: &str, input: Value) -> LocalFuture<Result<Value, ToolError>> {
  44. REGISTRY.invoke(self, cx, command, input)
  45. }
  46. // optional: state, shutdown, http, suspend, resume, memory_limit
  47. }
  48. ```
  49. The native `main` is its ports plus one call:
  50. ```rust
  51. tool_native::run(App { name: "my-tool", instructions: None, commands: Box::new(|_desc| vec![]) }, |services| {
  52. MyTool::new(Ports { http: Box::new(UreqHttp::checked(services.declared.clone())), data_dir: services.data_dir, … })
  53. })
  54. ```
  55. The component is its own WIT world (including `opinionated:tool/tool-component`) plus one macro:
  56. ```rust
  57. wit_bindgen::generate!({ world: "my:tool/component", path: "wit", with: { … }, generate_all });
  58. tool_wasi::export_tool!(Component, MyTool, || MyTool::new(host_ports()));
  59. ```
  60. ### Or skip the native build
  61. A tool can ship as its component alone, in one binary: a build script compiles the component (a second cargo, its own target directory), the bytes are embedded, and `tool_host::run_embedded` runs them with the tool's own command line (`TOOL COMMAND`, no component path). Its default grants (typically `--grant-declared` and its extension's flags) apply unless `--no-default-grants`; `--host-help` lists the host's flags. The core is then only ever built for WASM. anki-cards-rs's [`wasm-only` branch](https://github.com/gerbillinae/anki-cards-rs/tree/wasm-only) does this.
  62. ```rust
  63. tool_host::run_embedded(extension, tool_host::Embedded {
  64. wasm: my_tool_wasm::WASM, // include_bytes! of what build.rs built
  65. instructions: Some(MCP_INSTRUCTIONS.into()),
  66. default_flags: vec!["--grant-declared".into()],
  67. })
  68. ```
  69. ## Declared needs
  70. A tool declares what it reaches beyond itself (`Registry::needs`), computed from its config: HTTP authorities, secret names, a data directory. They're in `describe()`. The native build enforces them (`UreqHttp::checked`, `EnvSecrets::checked`), so an undeclared capability fails in development, not only in the sandbox. A host grants them only when asked: `--grant-declared`. Granted secrets come from where the native build reads them (the environment, then `~/keys.env`).
  71. ## Suspend and resume
  72. The host can discard an instance and later start a fresh one from a snapshot the program chose to keep. That sheds memory (linear memory never shrinks), stops idle tools, and carries session state to the next run. The snapshot is opaque bytes; postcard is the recommendation (types it encodes must not use `skip_serializing_if`). Either side can start it:
  73. - **The program:** `host.request-suspend(snapshot)`, at any point; `export_tool!` does it once memory passes the tool's `memory_limit`.
  74. - **The host:** `suspend(reason)`, with reason `idle`, `memory` or `exit`. The program accepts with a snapshot, or refuses with a reason, for example while audio plays.
  75. The fresh instance is configured as before, then given the snapshot (`resume`) before any other call. The host's socket, MCP output and subscribers outlive instances.
  76. ## Keeping data
  77. A tool that keeps data of its own gets a directory, `Ports::data_dir`: natively `$<NAME>_DATA_DIR` or the platform's data folder (`tool_contract::standard_data_dir`); under a host, a grant, which the component sees as `/data`. The tool reads and writes it with plain std::fs and decides its own format and locking. Several processes may share it. wasi:filesystem has no advisory locks, so `tool-files` builds lock files from exclusive create, with atomic writes by rename; a lock waits by the tool's own timer, so a holder in the same process carries on. Use a self-describing format (JSON with serde defaults) for data that outlives builds.
  78. ## Flags
  79. Both builds, before the command:
  80. ```
  81. --data-dir DIR the tool's data directory (native default: the standard one)
  82. --no-data native: no data directory
  83. --data host: grant the standard data directory
  84. --snapshot FILE resume from FILE, and suspend into FILE on exit
  85. ```
  86. The host only:
  87. ```
  88. --allow-http HOST[:PORT] --secret NAME --grant-declared
  89. --suspend-idle SECS ask the component to suspend after SECS without calls
  90. --recycle-above-mb N ask it to suspend past N MiB (and twice a fresh instance's)
  91. --no-cache compile the component every run (the compilation cache is on by default)
  92. ```
  93. ## Conformance
  94. `tool_contract::conformance` has checks any `Backend` must pass (`check`) and runs the same steps through two backends to compare results and final state (`compare`). A tool runs both against its native build and its component; anki-cards' suite (`anki-cards-conformance`) does, against a strict fake AnkiConnect.
  95. ## Versions
  96. The WASM side tracks wasmtime closely: wasmtime 50 (Rust 1.97 or later), WASI 0.3.0, and so `wasip3` 0.9 and wit-bindgen 0.62 in components. A component and its host must agree on the WASI version.
  97. ## Status
  98. Extracted from the anki-cards port, where every piece is used and tested. The APIs are young and will change.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.