golem-scala-development

Golem Scala SDK Development

The Golem SDK for Scala.js lives under sdks/scala/ in the Golem repository. It targets the Golem WIT API v1.5.0 and produces WASM components that run on the Golem platform via a QuickJS-based guest runtime.

Repository Layout

sdks/scala/
├── core/           # golem-scala-core (Scala.js facades, agent framework) — JS-only
├── model/          # golem-scala-model (WIT value types, RPC types)
├── macros/         # golem-scala-macros (Scala 3 macros, JVM-only)
├── codegen/        # Shared build-time code generation library
├── sbt/            # golem-scala-sbt (SBT plugin, Scala 2.12)
├── mill/           # Mill plugin
├── wit/            # WIT definitions (main.wit + deps/)
│   ├── main.wit    # Primary WIT — package golem:agent-guest, world agent-guest
│   ├── deps/       # WIT dependencies (copied from golem repo)
│   └── dts/        # Generated TypeScript d.ts (source of truth for JS exports)
├── scripts/        # generate-agent-guest-wasm.sh
├── example/        # Standalone demo project (separate sbt build)
├── test-agents/    # Test agent definitions + implementations for integration tests
├── integration-tests/ # Integration test suite
└── docs/           # Documentation

Scala Versions

• Scala 3.8.2 — All Golem Scala 3 projects. Prefix sbt commands with ++3.8.2 (without ! — only golem projects with 3.8.2 in crossScalaVersions are affected).
• Scala 2.13.18 — Cross-build for Scala 2 users.
• Scala 2.12.21 — The SBT plugin (golemScalaSbt) only. Use ++2.12.21! (the ! forces override).

Important: sbt --client mode preserves Scala version across invocations. Always specify the version explicitly to avoid version drift.

SBT Project Names

Running All Tests

Use these sbt aliases (from sdks/scala/) to run all golem-scala tests:

Always run golemTestAll before considering a change complete.

Integration tests require the TypeScript SDK packages path. The GOLEM_TS_PACKAGES_PATH env var is forwarded automatically by build.sbt, but sbt --client doesn't propagate env vars. Use non-client sbt instead:

cd sdks/scala
GOLEM_TS_PACKAGES_PATH=<TS_PACKAGES_PATH> sbt golemTestAll

Compiling

From sdks/scala/:

# Compile test agents (good smoke test)
sbt "++3.8.2; testAgents/fastLinkJS"

# Compile core
sbt "++3.8.2; core/compile"

# Compile model
sbt "++3.8.2; modelJS/compile"

Use the sbt logging pattern:

cd sdks/scala
LOG=".git/agent-logs/sbt-$(date +%s)-$.log"
mkdir -p "$(dirname "$LOG")"
sbt -Dsbt.color=false "++3.8.2; testAgents/fastLinkJS" >"$LOG" 2>&1
echo "Exit: $? | Log: $LOG"
# Query: tail -50 "$LOG" or grep -i error "$LOG"

Publishing Locally

The example project depends on 0.0.0-SNAPSHOT artifacts. All golem projects have publish / skip := true by default, so you must override it.

Step 1: Publish Dependencies + Golem Libraries (Scala 3.8.2)

cd sdks/scala
sbt '++3.8.2; set ThisBuild / version := "0.0.0-SNAPSHOT"; set ThisBuild / packageDoc / publishArtifact := false; set every (publish / skip) := false; modelJVM/publishLocal; modelJS/publishLocal; macros/publishLocal; core/publishLocal'

Step 2: Publish Codegen + SBT Plugin (Scala 2.12.21)

The SBT plugin depends on codegen, so both must be published for Scala 2.12:

cd sdks/scala
sbt '++2.12.21!; set ThisBuild / version := "0.0.0-SNAPSHOT"; set ThisBuild / packageDoc / publishArtifact := false; set every (publish / skip) := false; codegen/publishLocal; sbtPlugin/publishLocal'

Step 3 (optional): Publish Scala 2.13 cross-builds

If testing with Scala 2.13 user projects:

cd sdks/scala
sbt '++2.13.18; set ThisBuild / version := "0.0.0-SNAPSHOT"; set ThisBuild / packageDoc / publishArtifact := false; set every (publish / skip) := false; modelJVM/publishLocal; modelJS/publishLocal; core/publishLocal'

Note: The golemPublishLocal alias exists in build.sbt but may need set every (publish / skip) := false prepended to work correctly. The explicit commands above are the most reliable approach.

Building the Example Project

The example project at sdks/scala/example/ is a standalone sbt project (its own build.sbt, project/plugins.sbt). It depends on the SDK at 0.0.0-SNAPSHOT.

Prerequisites

1. Publish the SDK locally (both steps above).

Clean Build

cd sdks/scala/example
rm -rf target project/target .bsp .generated .golem
sbt -batch -no-colors -Dsbt.supershell=false compile

Key SBT Tasks

• sbt golemPrepare — Generates .generated/agent_guest.wasm (extracted from plugin resources) and .generated/scala-js-template.yaml (component manifest template).
• sbt compile — Compiles the Scala agent code.
• sbt fastLinkJS — Links the Scala.js bundle (produces the JS that QuickJS will run).

Project Structure

• build.sbt — Enables ScalaJSPlugin + GolemPlugin, sets scalaJSUseMainModuleInitializer := false, ESModule output.
• project/plugins.sbt — Adds golem-scala-sbt and sbt-scalajs.
• golem.yaml — Declares app name, includes .generated/scala-js-template.yaml, defines component scala:demo.
• repl-counter.rib — Rib script for end-to-end testing via golem-cli repl.

End-to-End Testing

Start the Local Golem Server

golem-cli server run --clean

This starts the all-in-one Golem server on localhost:9881.

Using run.sh

cd sdks/scala/example
bash run.sh

The script does:

1. sbt golemPrepare — Generate wasm + manifest template
2. golem-cli build --yes — Build the WASM component (links QuickJS runtime + Scala.js bundle)
3. golem-cli deploy --yes — Deploy to local Golem server
4. golem-cli repl scala:demo --script-file repl-counter.rib — Run the demo

Manual Steps

cd sdks/scala/example
sbt golemPrepare
golem-cli build --yes
golem-cli deploy --yes --local
golem-cli repl scala:demo --script-file repl-counter.rib --local

Regenerating agent_guest.wasm

The agent_guest.wasm is the QuickJS-based WASM runtime that wraps the Scala.js bundle. Regenerate it when WIT definitions change.

Script

cd sdks/scala
./scripts/generate-agent-guest-wasm.sh

What It Does

1. Stages WIT package from sdks/scala/wit/ (skipping the all/ dep directory).
2. Generates TypeScript d.ts definitions via wasm-rquickjs generate-dts → saved to sdks/scala/wit/dts/.
3. Generates QuickJS wrapper crate via wasm-rquickjs generate-wrapper-crate.
4. Builds with cargo component build --release.
5. Installs the wasm into sdks/scala/sbt/src/main/resources/golem/wasm/agent_guest.wasm and sdks/scala/mill/resources/golem/wasm/agent_guest.wasm.
6. Copies d.ts files to sdks/scala/wit/dts/.

Prerequisites

Before running the script, sync WIT dependencies from the repo root:

cargo make wit

Requirements

• wasm-rquickjs v0.1.0 (cargo install wasm-rquickjs-cli@0.1.0)
• Rust toolchain + cargo-component (cargo install cargo-component)

WIT Management

Files

• Primary: sdks/scala/wit/main.wit — The golem:agent-guest package definition.
• Dependencies: sdks/scala/wit/deps/ — Copied from wit/deps/ in the Golem repo root.
• TypeScript reference: sdks/scala/wit/dts/ — Generated d.ts files showing exact JS types expected by the wasm runtime. exports.d.ts is the source of truth for what the JS module must export.

Updating WIT Dependencies

WIT dependencies are managed the same way as the Rust and TypeScript SDKs — via cargo make wit from the repository root:

cargo make wit

This copies all WIT packages from wit/deps/ into sdks/scala/wit/deps/. The results are committed to the repository.

TypeScript SDK Reference

The TypeScript SDK at sdks/ts/wit/ is the reference for correct WIT definitions when in doubt.

RPC Client Architecture

The Scala SDK's remote agent call path uses async-invoke-and-await from the WIT golem:agent/host@1.5.0 interface, matching the TypeScript SDK behavior:

Host functions used

Key files

Async behavior

• apply() returns a genuinely async Future[Out] — the WASM event loop is yielded while waiting
• cancelable() returns (Future[Out], CancellationToken) — calling token.cancel() invokes FutureInvokeResult.cancel() (best-effort)
• Multiple concurrent RPC calls are possible since each uses its own FutureInvokeResult resource
• trigger(), scheduleAt(), scheduleCancelableAt() remain synchronous (wrapped in Future)

Known Issue: Multi-Component App Scala.js Linking Error

When a Scala component is part of a multi-component (mixed-language) app, the build_mixed_language_app CLI test fails with:

Referring to non-existent class golem.runtime.__generated.autoregister.component_name.RegisterAgents

Root cause (two issues):

1. Source directory mismatch: The common build.sbt configures .in(file(".")) (root project), so sbt scans ./src/main/scala/. But in a multi-component app, Scala sources are in a subdirectory like scala-main/src/main/scala/. The SBT plugin's source generator finds zero @agentImplementation classes → RegisterAgents.scala is never generated.

2. Literal component_name in common template: The common build.sbt has golemBasePackage := Some("component_name"). Common templates have no ComponentName context (it's None), so the placeholder is never substituted. The module initializer references golem.runtime.__generated.autoregister.component_name.RegisterAgents but the class doesn't exist.

Impact: The Scala template works for standalone (single-language) apps because sources land at the root src/main/scala/. It fails only in multi-component apps where each language's sources are in a component subdirectory.

Fix needed: The GolemPlugin must auto-discover source directories from component subdirectories, and either auto-infer golemBasePackage from discovered sources or the template system must pass the component name to the common build.sbt.

Relevant files:

• cli/golem-cli/templates/scala/common/build.sbt — template with literal component_name
• cli/golem-cli/src/app/template/generator.rs — template transform logic (common templates get no ComponentName transform)
• sdks/scala/sbt/src/main/scala/golem/sbt/GolemPlugin.scala — SBT plugin source generator and module initializer
• sdks/scala/codegen/src/main/scala/golem/codegen/autoregister/AutoRegisterCodegen.scala — returns empty result when no impls found but module initializer still references generated class

Common Errors and Solutions