golemcloud 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 three Preview 3 worlds:
| World | Embedded artifact | Role |
|---|---|---|
golem:agent-guest/agent-guest |
agent_guest.wasm |
ordinary agent and tool guest |
golem:agent-guest/tool-middleware-guest |
tool_middleware_guest.wasm |
pure tool middleware |
golem:agent-guest/agent-tool-middleware-guest |
agent_tool_middleware_guest.wasm |
combined agent/tool/middleware guest |
The ordinary world currently includes golem:agent/agent-guest@2.0.0, exports golem:tool/guest@0.1.0, 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; notably, 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 all three WASMs into both plugin resource directories:
sdks/scala/sbt/src/main/resources/golem/wasm/
sdks/scala/mill/resources/golem/wasm/
The WASMs are build artifacts and are intentionally ignored by Git. The ordinary role's generated declarations in sdks/scala/wit/dts/ are tracked and are checked for drift in CI. The role-specific intermediate declarations and wrapper crates 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.3, matching the root CI/workflow setting- 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.3
# Repository root
cargo make wit
# SDK root
cd sdks/scala
./scripts/generate-agent-guest-wasm.sh
The generator stages each 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 role matrix when role worlds 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 role matrix, the wrapper script, or the pinned wasm-rquickjs toolchain.