Golem Scala Guest Runtimes
Use the checked-in script and WIT as the source of truth. Do not reproduce the wrapper-generation steps manually.
Current contract
sdks/scala/wit/main.wit defines one Preview 3 world, golem:agent-guest/agent-guest. The script
builds it into one embedded artifact, agent_guest.wasm, which serves every guest role: agents,
tools and tool middleware. The world includes golem:agent/agent-guest@2.0.0 and exports
golem:tool/guest@0.1.0 and golem:tool/tool-middleware-guest@0.1.0.
The world imports the host surface, including all six golem:permissions@0.1.0 interfaces, and
uses the v2 schema-graph, schema-value-tree and typed-schema-value model through the synced
golem-core-v2 dependency. Read wit/main.wit rather than maintaining a second exhaustive import
list here; the host surface still includes versioned Golem APIs such as golem:api@1.5.0 and
golem:durability@1.6.0.
wit/deps/ is a generated mirror of the root WIT dependencies. Never hand-edit it. Sync it from the repository root:
cargo make wit
Generated and tracked files
The script installs agent_guest.wasm into both plugin resource directories:
sdks/scala/sbt/src/main/resources/golem/wasm/
sdks/scala/mill/resources/golem/wasm/
The WASM is a build artifact and is intentionally ignored by Git. The generated declarations in sdks/scala/wit/dts/ are tracked and are checked for drift in CI. The intermediate declarations and the wrapper crate under sdks/scala/.generated/ are untracked.
Prerequisites and regeneration
The current pipeline uses:
- Rust stable with
wasm32-wasip2 - Preview 3 (
wasm-rquickjs --target wasi-p3) wasm-rquickjs-cli0.4.15, matchingWASM_RQUICKJS_VERSIONin.github/workflows/ci.yaml- ordinary
cargo build --target wasm32-wasip2 --releaseon generated wrapper crates; it does not usecargo-component
rustup target add wasm32-wasip2
cargo install --locked wasm-rquickjs-cli@0.4.15
# Repository root
cargo make wit
# SDK root
cd sdks/scala
./scripts/generate-agent-guest-wasm.sh
The generator stages the world, generates d.ts and a wrapper crate with the user=@slot injection point, applies the repository's required Preview 3 wit-bindgen override, builds it, and copies the output to both plugins. Scala.js bundles SDK and user code into the injected module; there is no separately embedded SDK JavaScript module.
Verification
Generation runs the ordinary export-contract check. Also verify the guest component contract when the world or packaging changes:
cd sdks/scala
./scripts/test-agent-guest-export-contract.sh
./scripts/test-agent-guest-role-contracts.sh
git diff -- wit/dts
git status --short -- wit/dts sbt/src/main/resources/golem/wasm mill/resources/golem/wasm
The role-contract script requires wasm-tools and confirms that sbt and Mill package identical bytes. CI's generated-file action validates tracked d.ts drift and rejects accidentally tracked WASMs.
Regenerate after changing wit/main.wit, synced WIT dependencies, the wrapper script, or the pinned wasm-rquickjs toolchain.