rivet-dev / rivet-dev/dynamic-apps
Document and stabilize the wasm command ABI (host ↔ guest module interface)
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 1k
- Forks
- 51
- Avg merge
- 6m
- Merged PRs (30d)
- 13
Description
Problem
WASM command modules (registry/native/*) interface with the secure-exec runtime through an ABI that is currently implicit, undocumented, and evolving. It spans:
- the WASI target surface (
wasm32-wasip1) the guest is compiled against, - secure-exec's patched wasi-libc and custom extensions (e.g. networking —
netdb.h/sockets — added viapatches/wasi-libc/*+patch-wasi-libc.sh), - the runtime-provided syscalls the kernel/sidecar exposes to the guest (fds, sockets, pty, process/spawn, signals),
- the command entry/dispatch contract (dispatch-by-header/magic-number,
argv[0]multicall aliases, env, exit codes).
Because this contract isn't written down or version-stabilized, third parties can't reliably build compatible wasm commands, and changes to the patched libc / syscall surface risk silently breaking existing modules.
Naming TBD — this is the interface between the host/runtime and the guest wasm modules (the "guest ABI" / "wasm command ABI" / syscall surface). Part of this issue is settling on a name.
Ask
- Document the ABI: the exact contract a wasm module must satisfy to run as an agentOS command.
- Stabilize it: define a stability/versioning policy so guest modules and the runtime evolve compatibly.
Should cover
- Supported WASI subset + which functions are provided/stubbed/extended.
- secure-exec extensions / custom syscalls beyond WASI (networking, pty, process, sockets).
- The patched-wasi-libc surface (what
patch-wasi-libc.shadds/changes vs upstream). - Command invocation contract: entry dispatch (header/magic number),
argv[0]multicall, env, fd conventions, exit codes. - How the sidecar/kernel presents fds / sockets / pty / child processes to the module.
Context
Surfaced during the registry { packageDir } migration: the C command build depends on a patched wasi-libc sysroot for networking (netdb.h), which highlighted that the host↔guest wasm contract is load-bearing but undocumented.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading registry/native/, patches/wasi-libc/, and patch-wasi-libc.sh, then trace the secure-exec runtime surfaces named in the issue: WASI functions, custom syscalls, command dispatch, and fd conventions. Done means the host↔guest contract is documented and given a stability/versioning policy, including supported, stubbed, and extended interfaces.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c, shell, wasm
- Domain
- compilers, documentation, operating-systems
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100