// Explains the zio-golem WIT folder structure and how to regenerate the agent_guest.wasm base image. Use when working with WIT definitions, upgrading Golem versions, or regenerating the guest runtime WASM.
Generating Scala code in the golem subproject. Use when adding code generation steps, build-time source generators, scalameta AST construction, or sbt/Mill sourceGenerators to the golem/ subtree.
Compile, publish, and test the ZIO Golem Scala.js SDK. Use when working on the golem/ subtree: building the SDK, publishing locally, compiling/running the example demo, regenerating the agent_guest.wasm, or debugging end-to-end deployment.
Run and debug Golem Scala SDK integration tests. Use when running golem integration tests, debugging test failures, or working with GolemExamplesIntegrationSpec.
| name | zio-golem-base-image |
| description | Explains the zio-golem WIT folder structure and how to regenerate the agent_guest.wasm base image. Use when working with WIT definitions, upgrading Golem versions, or regenerating the guest runtime WASM. |
The base image agent_guest.wasm is a QuickJS-based WASM component that serves as the guest runtime for Scala.js agents on Golem. It must be regenerated whenever WIT definitions change.
golem/wit/
├── main.wit # Hand-maintained world definition (golem:agent-guest)
├── deps.toml # wit-deps manifest — points to golemcloud/golem main branch
├── deps.lock # Auto-generated lock file (gitignored)
└── deps/ # Auto-populated by wit-deps (gitignored)
├── golem-core/
├── golem-agent/
├── golem-1.x/
├── golem-rdbms/
├── golem-durability/
├── blobstore/
├── cli/
├── clocks/
├── config/
├── ...
└── sockets/
main.wit defines the golem:agent-guest world — the set of imports/exports the agent component uses. This file is checked in and maintained manually.deps.toml declares a single dependency source: the golem repo's main branch tarball. wit-deps downloads and extracts the WIT packages from it.deps/ and deps.lock are gitignored — they are populated by running wit-deps from golem/.The base image must be regenerated whenever:
wit/main.wit changes — adding/removing imports or exportsdeps.toml then regenerate)wasm-rquickjs updates — a new version of the wrapper generator may produce different outputThe generated agent_guest.wasm is checked in at two locations (embedded in the sbt and mill plugins):
golem/sbt/src/main/resources/golem/wasm/agent_guest.wasmgolem/mill/resources/golem/wasm/agent_guest.wasmcurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-wasip1
cargo install cargo-component
cargo install wit-deps-cli
The script enforces a specific version of wasm-rquickjs and will refuse to run if the installed version does not match. The required version is defined by REQUIRED_WASM_RQUICKJS_VERSION in generate-agent-guest-wasm.sh.
cargo install wasm-rquickjs-cli@0.1.0
From the repository root (zio-blocks/):
./golem/scripts/generate-agent-guest-wasm.sh
The script performs these steps:
wit-deps update in golem/ to fetch the latest WIT dependencies into golem/wit/deps/.generated/agent-wit-root/ (copies main.wit + deps/)wasm-rquickjs generate-wrapper-crate to produce a Rust crate from the WITcargo component build --release targeting wasm32-wasip1agent_guest.wasm into both plugin resource directoriesTo update the WIT dependencies without regenerating the WASM:
cd golem && wit-deps
The generation script always uses wit-deps update to ensure deps are fresh. To update deps without a full regeneration:
cd golem && wit-deps update
At build time, the sbt/mill GolemPlugin extracts the embedded agent_guest.wasm from plugin resources and writes it to the user project's .generated/agent_guest.wasm. Then golem-cli uses this base runtime to compose the final component: it injects the user's Scala.js bundle into the QuickJS runtime and wraps it as a proper Golem agent component.
The Scala SDK does not parse WIT to generate Scala bindings. Instead, Scala macros + ZIO Schema produce AgentMetadata at compile time, and WitTypeBuilder maps schema types to WIT-compatible JS representations at runtime. The WIT definitions only flow through the WASM guest runtime.