feat(sdk/go): add Go SDK foundation, types, and sandbox client (A)

[rhuss]

Context

This is the first PR in a 6-PR decomposition of the Go SDK contribution (#2044). The decomposition was discussed in the contributor meeting on 2026-07-14 to make the review process more approachable.

The first PR is intentionally the largest because it carries the shared foundation. After this merge, the SDK is usable end-to-end for sandbox management. Each subsequent PR then incrementally adds one more resource group, and after every merge the SDK is fully working with an expanded API surface.

PR	What	Code	Tests	Status
This PR (A)	Foundation + types + sandbox	~4.6K	~8.5K	ready for review
B	Exec + file + health	~1.2K	~1.8K	after A merges
C	Provider + profile + config + refresh	~2.2K	~3.3K	after B merges
D	Policy + service + TCP + SSH	~2.6K	~3.9K	after C merges
E	Gateway + OIDC + edge + fakes	TBD	TBD	after D merges
F	Docs + CI	~0.5K	-	after E merges

What's in this PR

• Module setup: go.mod, go.sum, Makefile, mise.toml
• All domain types: types/ package (14 files) covering every SDK resource
• Full ClientInterface: all 10 sub-client accessors defined upfront
• Shared infrastructure: errors, auth primitives, gRPC connection, logging
• Sandbox client: fully functional with converter and tests
• Stub clients: all other resources return Unimplemented errors linking to feat(sdk/go): Go SDK PR decomposition plan #2270. Each subsequent PR replaces stubs with real implementations.

sdk/go/
├── go.mod, go.sum, Makefile, mise.toml
├── proto/                              # Proto definitions + generated .pb.go
├── openshell/v1/
│   ├── types/                          # All domain types (14 files)
│   ├── internal/converter/             # Proto-to-SDK converters
│   ├── internal/grpc/                  # Connection management
│   ├── client.go                       # ClientInterface + Client struct
│   ├── sandbox.go + sandbox_client.go  # Sandbox (real implementation)
│   ├── stub_clients.go                 # Stubs for resources not yet implemented
│   ├── auth*.go                        # Auth providers
│   ├── errors.go                       # Typed errors with IsNotFound() etc.
│   └── {exec,file,health,...}.go       # Interface definitions for all resources

How to Review

Review zones

Zone	Files	What to do
Must-review	client.go, types/*.go, errors.go, auth*.go, sandbox.go, sandbox_client.go, internal/grpc/conn.go	These define the API surface and core logic. Read carefully.
Pattern-review	sandbox_client_test.go, internal/converter/sandbox.go, internal/converter/sandbox_test.go	Review sandbox_client_test.go as the test pattern exemplar. Converter tests follow table-driven patterns.
Skim	stub_clients.go, go.sum, Makefile, mise.toml, doc.go, interface-only files (exec.go, file.go, etc.)	Stubs are mechanical. Interface files are just type declarations.
Skip	proto/*.pb.go, proto/*_grpc.pb.go	Generated code.

Key design decisions

• client-go conventions: typed sub-clients per resource, watch primitives, typed errors
• Domain types separate from proto: types/ package has no proto imports, insulating consumers from wire format changes
• Stub pattern for incremental delivery: stubs return ErrorUnimplemented with a link to the tracking issue. Each follow-up PR replaces stubs with real implementations without modifying client.go.
• All types upfront: the full domain model ships in this PR (~1K lines) so reviewers see the complete API shape once

What to look for

• ClientInterface covers the right API surface
• Type definitions match gRPC API semantics
• Error handling follows typed error conventions (IsNotFound(), etc.)
• Auth provider interface is extensible
• Sandbox client test coverage is adequate

Testing

All 130 tests pass:

go test ./...   # 130 passed in 7 packages

Resolves #2044 (with remaining PRs B-F)
Part of #2270

[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.