feat(sdk/go): add Go SDK foundation and core clients (1/3)

[rhuss]

Context

This is a large contribution and I want to be upfront about that. What you're looking at is the handover of a prototype Go SDK that I built to explore the API surface described in #2044. The good news: it's complete. The SDK covers the full OpenShell gRPC API, follows client-go conventions, and includes 250+ passing unit tests. The not-so-good news: that completeness means a lot of code to review.

To make this manageable, I've split the contribution into three PRs. This split was designed to help both human reviewers and AI review agents work through the changes incrementally:

PR	What	Files	Merge order
This PR (1/3)	Foundation: types, converters, core clients, proto bindings	117	First
#2226 (2/3)	Gateway client, OIDC auth, fakes, edge client	+70	After 1/3
#2227 (3/3)	Fern documentation (4 MDX pages), CI job, mise tasks	+7	After 2/3

Each PR builds on the previous one. Once PR 1/3 is merged, the diff for PR 2/3 will auto-update to show only the incremental changes. PR 1/3 is self-contained: it compiles and all tests pass independently.

Spec-driven development

This SDK was built using Speckit, a spec-driven development workflow. Every design decision, from the type hierarchy to the converter patterns to the error mapping, started as a specification that was reviewed and refined before implementation. The specs live in a separate PR on my fork and include detailed design documents, research notes, and task breakdowns.

I'd like to raise a question for the maintainers: would you be interested in keeping design specs alongside the SDK code? The Speckit workflow works well as a sub-project within a monorepo, where specs sit next to the code they describe (e.g., sdk/go/specs/). But it also works fine with specs kept externally. I have a fourth PR with the specs ready, but whether to include them is entirely up to you. I'm happy either way.

What's in this PR

• Module setup: sdk/go/go.mod (module github.com/NVIDIA/OpenShell/sdk/go, Go 1.24+)
• Proto bindings: 3 proto files + generated .pb.go (committed, no protoc needed to build)
• Domain types: types/ package with all SDK structs, errors, options, interfaces
• Internal layer: internal/converter/ (proto-to-SDK) and internal/grpc/ (connection management)
• Core clients: sandbox, provider, service, exec, file, health, SSH, TCP, policy, config, profile, refresh
• Auth primitives: AuthProvider interface, refreshable token wrapper
• Tests: Unit tests for all converters and client validation logic

sdk/go/
├── go.mod, go.sum, Makefile, mise.toml
├── proto/                          # Proto definitions + generated .pb.go
├── openshell/v1/
│   ├── types/                      # Domain types, errors, options
│   ├── internal/converter/         # Proto <-> SDK type conversion
│   ├── internal/grpc/              # gRPC connection management
│   ├── client.go                   # Top-level Client with sub-clients
│   ├── *_client.go + *_client_test.go
│   └── auth*.go                    # Auth primitives

Resolves #2044

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.