Experimental Go SDK

.agents/skills/modifying-wit-interfaces/SKILL.md

@@ -47,6 +47,7 @@ sub-projects below by copying from the root. **Never manually edit a sub-project
 | `sdks/ts/wit/deps/` | **all** root deps + golem-ai (overlaid from `sdks/ts/wit/golem-ai`) |
 | `sdks/scala/wit/deps/` | **all** root deps |
 | `sdks/moonbit/golem_sdk/wit/deps/` | **all** root deps |
+| `sdks/go/golem/wit/deps/` | **all** root deps |
 
 The exact copy lists live in the `wit-golem-common`, `wit-golem-cli`, and
 `wit-sdks` tasks in `Makefile.toml`.
@@ -90,7 +91,7 @@ This mirrors the correct subset of the root `wit/deps/` into each sub-project, i
 cargo make check-wit
 ```
 
-This re-runs the sync and then `git status` over every per-crate `wit/deps` copy (golem-common, golem-cli, and all four SDKs) to ensure the committed WIT files match what the sync produces. CI runs this; if it fails, you forgot to run `cargo make wit` (or you hand-edited a generated sub-project copy).
+This re-runs the sync and then `git status` over every per-crate `wit/deps` copy (golem-common, golem-cli, and all five SDKs — rust, ts, scala, moonbit, go) to ensure the committed WIT files match what the sync produces. CI runs this; if it fails, you forgot to run `cargo make wit` (or you hand-edited a generated sub-project copy).
 
 ### Step 4: Build and verify
 
@@ -142,7 +143,8 @@ If WIT changes affect SDK interfaces:
 2. **TS SDK**: Rebuild packages (`npx pnpm run build` in `sdks/ts/`), then rebuild agent template WASM (`npx pnpm run build-agent-template`)
 3. **Scala SDK**: Regenerate `agent_guest.wasm`, adjust Scala SDK types or codecs if the WIT shape changed, and run the relevant Scala test suites
 4. **MoonBit SDK**: Regenerate WIT bindings (`wit-bindgen moonbit` in `sdks/moonbit/golem_sdk/`), then `moon fmt` and `moon check --target wasm`
-5. **Test components**: Rebuild any test components that use the changed interfaces (see their `AGENTS.md`)
+5. **Go SDK**: Regenerate WIT bindings (`cargo make generate-sdk-go-bindings`), then `GOOS=wasip1 GOARCH=wasm go build ./...` in `sdks/go/golem/`
+6. **Test components**: Rebuild any test components that use the changed interfaces (see their `AGENTS.md`)
 
 ## Checklist
 

.agents/skills/pre-pr-checklist/SKILL.md

@@ -32,6 +32,7 @@ Choose tests based on what you changed. **Do not run `cargo make test`** — it
 | Rust SDK (`sdks/rust/`) | `cargo test -p golem-rust` + `cargo make worker-executor-tests` |
 | TypeScript SDK (`sdks/ts/`) | `npx pnpm run test` (in `sdks/ts/`) + `cargo make cli-integration-tests` |
 | MoonBit SDK (`sdks/moonbit/`) | `moon test` (in `sdks/moonbit/golem_sdk/`) |
+| Go SDK (`sdks/go/golem/`) | `go test ./...` (in `sdks/go/golem/`); host-call paths only build under a generated app — see the `sdk-development` skill |
 | CLI structured output/schema | `cargo test -p golem-cli cli_output_schema_ --lib` + `cargo make check-cli-output-schema` |
 | CLI JSON output affecting skill tests | Update affected `golem-skills/tests/harness` code, tests, or scenarios. Run `npm run build && npm test` in `golem-skills/tests/harness` only if harness TypeScript code/tests changed. |
 
@@ -54,6 +55,7 @@ cargo make worker-executor-tests-misc
 | HTTP API endpoints | `cargo make generate-openapi` then `cargo clean -p golem-client && cargo build -p golem-client` (also refreshes `docs/src/content/rest-api/*.mdx`) |
 | Service config structs/defaults | `cargo make generate-configs` |
 | WIT interfaces | `cargo make wit` |
+| Go SDK WIT bindings (after a WIT change) | `cargo make generate-sdk-go-bindings` |
 | TS SDK runtime code | `npx pnpm run build-agent-template` (in `sdks/ts/`) |
 | Skill catalog (`golem-skills/skills/**`) | `cargo make generate-docs-skills` (refreshes `docs/src/content/how-to-guides/*.mdx`) |
 | CLI output schema summary | `cargo make update-cli-output-schema-summary` |

.agents/skills/sdk-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdk-development
-description: "Working on the Rust, TypeScript, or MoonBit SDKs in sdks/. Use when modifying SDK code, adding SDK features, or testing SDK changes with the main Golem platform."
+description: "Working on the Rust, TypeScript, MoonBit, or Go SDKs in sdks/. Use when modifying SDK code, adding SDK features, releasing an SDK, or testing SDK changes with the main Golem platform."
 ---
 
 # SDK Development
@@ -155,6 +155,94 @@ moon fmt
 moon info    # Regenerate .mbti interface files
 ```
 
+## Go SDK (`sdks/go/golem/`)
+
+Module path **`github.com/golemcloud/golem/sdks/go/golem`**, package `golem`.
+
+The directory is `sdks/go/golem`, not `sdks/go`, on purpose: Go binds an import to the *package
+clause*, but tooling and readers expect it to match the **last path element**. Naming the directory
+`golem` makes them agree, so agents import the SDK with no alias:
+
+```go
+import "github.com/golemcloud/golem/sdks/go/golem"   // binds `golem`
+```
+
+A hyphenated name (`golem-go-sdk`) could not do this — hyphens are not valid Go identifiers, so it
+would force an alias back. It also leaves `sdks/go/` free for siblings.
+
+Built with
+`componentize-go`, which is pinned per-project through Go's `tool` directive — never installed
+globally.
+
+### Building and testing
+
+```shell
+cd sdks/go/golem
+go test ./...                                       # native tests; fast, no wasm needed
+go vet .                                            # host vet, hand-written package
+GOOS=wasip1 GOARCH=wasm go build ./...              # compile everything for the real target
+GOOS=wasip1 GOARCH=wasm go vet -unsafeptr=false -composites=false .
+```
+
+Vet is scoped to `.`, not `./...`: the generated `internal/wit` bindings legitimately trip vet's
+`unsafe.Pointer` / unkeyed-field checks, so the whole tree is *compiled* (the `go build` above), not
+vetted, for the wasm target. CI runs exactly this set — plus a "bindings are committed" check — in the
+`build-golem-go` job (`.github/workflows/ci.yaml`).
+
+Native tests cover everything that does not reach a host import. `empty.s` lets a generated package
+*compile* for the host, but the linker still needs a definition for any `//go:wasmimport` symbol that
+host-arch code actually **references** — so RPC calls, `Future`, and `ClientFor` can only run under
+wasm. Exercise those by creating an app with `golem app new … go` in a playground and building it;
+the playground's `.golem-sdk-overrides` points the generated `go.mod` at this checkout.
+
+### Regenerating WIT bindings
+
+```shell
+cargo make generate-sdk-go-bindings
+```
+
+Generated code lands in `internal/wit/` and is **wiped on every run**. The hand-written export slots
+in `internal/exports/` survive because `--export-pkg-name` points the generated glue at them. The task
+also runs `dev-tools/go-bindgen-fixup`, which works around two upstream wit-bindgen `crates/go` bugs
+(tag-constant collisions, and a missing `empty.s` for the exports package).
+
+### ⚠️ Releasing: Go has no package registry
+
+Every other SDK publishes to a registry (crates.io / npm / maven / mooncakes) from a workflow
+triggered by a `golem-<lang>-v*` tag. **Go has none — the git tag *is* the release**, read directly
+from this repo by `proxy.golang.org`. There is no publish workflow to run.
+
+Because the module lives in a subdirectory, Go **requires** the tag to be prefixed with that
+subdirectory. This is a Go rule, not a choice:
+
+```
+sdks/go/golem/v0.1.0   ✅ the only form Go recognises
+golem-go-v0.1.0        ❌ invisible to Go — do not use
+```
+
+Notes:
+
+- This deliberately breaks the `golem-<lang>-v*` convention the other SDKs follow. It cannot be
+  avoided; see <https://go.dev/ref/mod> ("module subdirectory ... also serves as a prefix for
+  semantic version tags").
+- It does **not** collide with anything. There is no root `go.mod`, so the repo's `v1.5.x` release
+  tags are invisible to Go, and no existing tag has the `sdks/go/golem/` shape.
+- Consumers using the default `GOPROXY` download only the `sdks/go/golem` subtree (~7 MB), not the
+  whole repository. Only `GOPROXY=direct` clones the full repo, once per module cache. Repo size is
+  not a concern: the mirror serves far larger monorepos of exactly this shape (aws-sdk-go-v2 is
+  ~1.2 GB with subdirectory-tagged modules); the only hard limit is 500 MiB on the *module zip*.
+- The mirror stores a module permanently only if it can **detect a license**, and Go has no metadata
+  field for it — `sdks/go/golem/LICENSE` is the only mechanism, so it must stay in the module subtree.
+  It carries the Apache License 2.0 (the current SDK-license direction; a later session aligns the
+  other SDKs, which still ship the Golem Source License for now).
+
+### Local SDK overrides
+
+`GOLEM_GO_PATH` (or `GOLEM_PATH`, which derives it) makes the CLI emit a `replace` directive into a
+generated app's `go.mod`, pointing at the local checkout. This is how the playground tests SDK changes
+without publishing — and, until the first tag exists, the **only** way a generated Go app can resolve
+the SDK.
+
 ## Downstream Rebuild Requirements
 
 SDK changes can require rebuilding test components. This is the most common source of errors.
@@ -176,7 +264,8 @@ SDK changes can require rebuilding test components. This is the most common sour
 
 ## WIT Dependencies
 
-Both SDKs have WIT files synced from the root `wit/` directory. **Never manually edit** `wit/deps/` in either SDK.
+Every SDK has WIT files synced from the root `wit/` directory. **Never manually edit** `wit/deps/` in
+any SDK — `cargo make wit` mirrors them, and `cargo make diff-wit` guards against drift.
 
 ```shell
 # From repository root
@@ -189,6 +278,7 @@ cargo make wit
 2. SDK builds successfully
 3. SDK tests pass
 4. Agent template rebuilt (if TS SDK runtime code changed)
-5. Dependent test components rebuilt (if any)
-6. Platform tests pass (`cargo make worker-executor-tests` for Rust SDK, `cargo make cli-integration-tests` for TS SDK)
-7. Code formatted and linted
+5. Go SDK: a generated app still builds (the only cover for host-call paths)
+6. Dependent test components rebuilt (if any)
+7. Platform tests pass (`cargo make worker-executor-tests` for Rust SDK, `cargo make cli-integration-tests` for TS SDK)
+8. Code formatted and linted

.github/workflows/ci.yaml

@@ -351,6 +351,28 @@ jobs:
         working-directory: sdks/moonbit/golem_sdk_tools
         run: moon update
 
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          # Stock Go, tracking the version pinned in the module; componentize-go
+          # is a pinned `go tool` (go.mod) that fetches its own toolchain, so the
+          # Go SDK's CLI integration test (test_go_counter) needs only this.
+          go-version-file: sdks/go/golem/go.mod
+          cache-dependency-path: sdks/go/golem/go.sum
+
+      - name: Cache componentize-go toolchain
+        uses: actions/cache@v5
+        with:
+          # On first `golem build` of a Go component, componentize-go downloads a
+          # full patched Go toolchain into this dir (the "will use downloaded
+          # version" build-log line) — hundreds of MB. Cache it so the Go SDK's
+          # CLI integration test doesn't re-fetch it each run. Keyed on the SDK
+          # go.sum, which tracks the pinned componentize-go version.
+          path: ~/.cache/componentize-go
+          key: componentize-go-${{ runner.os }}-${{ hashFiles('sdks/go/golem/go.sum') }}
+          restore-keys: |
+            componentize-go-${{ runner.os }}-
+
       - name: Sync WIT dependencies
         run: cargo make wit
 
@@ -621,6 +643,66 @@ jobs:
         run: cargo test --all-features
         working-directory: sdks/rust
 
+  build-golem-go:
+    runs-on: blacksmith
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          # Tracks the version pinned in the module (currently go 1.25.5); stock
+          # Go only — the SDK deliberately does not use TinyGo.
+          go-version-file: sdks/go/golem/go.mod
+          cache-dependency-path: sdks/go/golem/go.sum
+
+      # cargo-make drives the WIT dep sync and the go-bindgen-fixup step that the
+      # bindings regeneration runs. componentize-go itself is a pinned `go tool`
+      # (go.mod), so no wasm-tools / WASI SDK are needed here.
+      - uses: ./.github/actions/setup-rust
+        with:
+          use-cache: 'false'
+          install-cargo-make: 'true'
+
+      # Regenerate the committed WIT bindings (syncs wit/deps first via the task's
+      # `wit` dependency) and fail if they drift from what's checked in — mirrors
+      # the "types are committed" gate the TS and Scala SDKs use.
+      - name: Regenerate Go WIT bindings
+        run: cargo make generate-sdk-go-bindings
+
+      - name: Verify Go WIT bindings are committed
+        run: |
+          if ! git diff --exit-code sdks/go/golem/internal/wit; then
+            echo "❌ sdks/go/golem/internal/wit differs from the committed version."
+            echo "Please run 'cargo make generate-sdk-go-bindings' and commit the result."
+            exit 1
+          fi
+
+      # Lint the hand-written package with golangci-lint (the standard Go
+      # meta-linter: govet, errcheck, ineffassign, staticcheck, unused + the
+      # doc-comment-form checks). Config + generated-code exclusions live in
+      # sdks/go/golem/.golangci.yml. The official action fetches a pinned binary
+      # and caches analysis — this replaces the host `go vet` step too, since its
+      # govet covers it (and the .golangci.yml exclusions handle the generated
+      # internal/wit bindings that forced the old vet flag workaround).
+      - name: Lint (golangci-lint)
+        uses: golangci/golangci-lint-action@v9
+        with:
+          version: v2.12
+          working-directory: sdks/go/golem
+
+      - name: Vet (wasip1)
+        working-directory: sdks/go/golem
+        run: GOOS=wasip1 GOARCH=wasm go vet -unsafeptr=false -composites=false .
+
+      - name: Build for wasip1
+        working-directory: sdks/go/golem
+        run: GOOS=wasip1 GOARCH=wasm go build ./...
+
+      - name: Run tests
+        working-directory: sdks/go/golem
+        run: go test ./...
+
   build-golem-ts:
     runs-on: blacksmith
     steps:

Cargo.toml

@@ -276,6 +276,7 @@ tracing-serde = "0.2.0"
 tracing-subscriber = { version = "0.3.20", features = ["env-filter", "fmt", "std", "json", ] }
 tracing-test = "0.2.5"
 tree-sitter = "0.26.5"
+tree-sitter-go = "0.23.4"
 tree-sitter-json = "0.24.8"
 tree-sitter-rust = "0.24.0"
 tree-sitter-typescript = "0.23.2"

Makefile.toml

@@ -111,6 +111,7 @@ args = [
     "--src", "wit/deps", "--dst", "sdks/ts/wit/deps",
     "--src", "wit/deps", "--dst", "sdks/scala/wit/deps",
     "--src", "wit/deps", "--dst", "sdks/moonbit/golem_sdk/wit/deps",
+    "--src", "wit/deps", "--dst", "sdks/go/golem/wit/deps",
 ]
 
 [tasks.wit-golem-cli]
@@ -129,7 +130,7 @@ args = [
 private = true
 script_runner = "@duckscript"
 script = '''
-status = exec git status --porcelain -- golem-common/wit/deps cli/golem-cli/wit/deps sdks/rust/golem-rust/wit/deps sdks/ts/wit/deps sdks/scala/wit/deps sdks/moonbit/golem_sdk/wit/deps
+status = exec git status --porcelain -- golem-common/wit/deps cli/golem-cli/wit/deps sdks/rust/golem-rust/wit/deps sdks/ts/wit/deps sdks/scala/wit/deps sdks/moonbit/golem_sdk/wit/deps sdks/go/golem/wit/deps
 ok = eq ${status.code} 0
 if not ${ok}
     echo "git status failed (exit ${status.code}):"
@@ -403,6 +404,33 @@ else
 fi
 '''
 
+[tasks.generate-sdk-go-bindings]
+description = "Regenerates the Go SDK's WIT bindings (sdks/go/golem/internal/wit)"
+dependencies = ["wit"]
+cwd = "./sdks/go/golem"
+script_runner = "@duckscript"
+script = '''
+# The componentize-go version is pinned in sdks/go/golem/go.mod via the `tool` directive
+# (never `latest`); `go tool` therefore resolves the exact pinned build.
+# --all-features is a GLOBAL flag and must precede the subcommand: golem's p3 WIT
+# uses @unstable annotations (timezone).
+# Imports + the wasmexport glue are generated into internal/wit (wiped each run).
+# The export packages are NOT generated: --export-pkg-name points the glue at
+# internal/exports, which we hand-write (the `Exports` slots the SDK fills in at
+# init). That keeps generated and hand-written code strictly separated.
+exec --fail-on-error go tool componentize-go --all-features bindings --output internal/wit --pkg-name github.com/golemcloud/golem/sdks/go/golem/internal/wit --export-pkg-name github.com/golemcloud/golem/sdks/go/golem/internal/exports --format
+
+# Works around a wit-bindgen crates/go codegen bug; see dev-tools/go-bindgen-fixup.
+exec --fail-on-error cargo run --quiet --manifest-path ../../../dev-tools/Cargo.toml --bin go-bindgen-fixup -- internal/wit
+exec --fail-on-error gofmt -w internal/wit
+
+# The generated code is wasm-only (//go:wasmimport declarations have no bodies),
+# so it can only be type-checked for the wasip1 target, not the host.
+set_env GOOS wasip1
+set_env GOARCH wasm
+exec --fail-on-error go build ./internal/wit/...
+'''
+
 [tasks.clean-sdk-scala]
 description = "Cleans the Scala SDK"
 cwd = "./sdks/scala"

cli/golem-cli/Cargo.toml

@@ -101,6 +101,7 @@ tracing = { workspace = true }
 tracing-log = "0.2.0"
 tracing-subscriber = { workspace = true }
 tree-sitter = { workspace = true }
+tree-sitter-go = { workspace = true }
 tree-sitter-json = { workspace = true }
 tree-sitter-rust = { workspace = true }
 tree-sitter-typescript = { workspace = true }

cli/golem-cli/build.rs

@@ -23,7 +23,7 @@ use std::process::Command;
 static SKIP_ENV_VAR_NAME: &str = "GOLEM_BUILD_SKIP_SHADOW";
 const GENERATED_TEMPLATES_DIR_NAME: &str = "templates";
 const SKILL_DESTINATION: &str = ".agents/skills";
-const SUPPORTED_LANGUAGES: &[&str] = &["ts", "rust", "scala", "moonbit"];
+const SUPPORTED_LANGUAGES: &[&str] = &["ts", "rust", "scala", "moonbit", "go"];
 
 fn main() {
     generate_embedded_templates().unwrap();

cli/golem-cli/src/app/build/check/agents.rs

@@ -120,6 +120,7 @@ mod tests {
             GuestLanguage::TypeScript,
             GuestLanguage::Rust,
             GuestLanguage::MoonBit,
+            GuestLanguage::Go,
         ] {
             let source = repo
                 .common_template_file_contents(language, Path::new("AGENTS.md"))