rivet-dev / rivet-dev/dynamic-apps

Document and stabilize the wasm command ABI (host ↔ guest module interface)

Open
#163 0 comments 0 reactions 0 assignees View on GitHub

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 via patches/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.sh adds/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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.