feat: add a .NET SDK

This is a design proposal for a new sdk/dotnet/ package built from the OpenShell gRPC service in proto/. Start with the draft's PARITY.md and README.md on the linked fork branch to see the proposed API and the feature gaps against the Go, Rust, TypeScript and Python SDKs. Done means maintainers agree on the scope, feed and ownership questions, and the work is split into the proposed PRs.

User Story

As a C# developer, I want a first-party OpenShell SDK for .NET, so that I can create and manage sandboxes, run commands, and watch their state from C# applications with the same capabilities Rust, Go, TypeScript, and Python developers already have.

Problem Statement

OpenShell ships SDKs for Rust, Go, TypeScript, and Python. There is no .NET SDK, so the C# community has no supported way to use the gateway API beyond generating gRPC bindings from proto/ by hand.

Impact / Why This Matters

Each .NET team must generate and maintain its own bindings and re-implement what the other SDKs already provide: OIDC token renewal, mTLS, the Cloudflare Access tunnel, pagination, readiness and deletion waits, typed errors, and safe credential handling. The copies drift from the gateway and from each other. A first-party SDK built from the same proto/ directory removes that duplication and keeps client and gateway in step.

Proposed Design

Add sdk/dotnet/ and publish it as NuGet packages, documented alongside the other SDKs:

• OpenShell.Sdk: an async client for net8.0 and net10.0 with the union of the other SDKs' features (health, sandboxes, exec, files, services, SSH and TCP forwarding, config and policy, providers, templates, workspaces), typed errors, and a raw gRPC escape hatch.
• OpenShell.Sdk.DependencyInjection: Microsoft.Extensions.DependencyInjection registration, options validated at startup, and a health check.
• OpenShell.Sdk.Testing: an in-memory fake client for unit tests.

Authentication covers bearer tokens, OIDC (client credentials and interactive flows), mTLS, Cloudflare Access, and gateways registered on disk by the CLI. Every call emits OpenTelemetry traces and metrics when a listener subscribes. The code uses current C# idioms and is trimming and AOT compatible. Protobuf bindings are generated at build time from proto/ and never committed.

using OpenShell;

using var client = new OpenShellClient(new OpenShellClientOptions
{
    Address = new Uri("https://gateway.example.com"),
    Auth = Auth.StaticToken(Environment.GetEnvironmentVariable("OPENSHELL_TOKEN")!),
});

var sandbox = await client.Sandboxes.CreateAsync("demo", new SandboxSpec { Image = "registry.example.com/agent:1.0" });
await client.Sandboxes.WaitReadyAsync(sandbox.Name);
var result = await client.Exec.RunAsync(sandbox.Name, ["python", "-c", "print('hello')"]);
await client.Sandboxes.DeleteAsync(sandbox.Name);

Acceptance Criteria

• OpenShell.Sdk covers every user-facing RPC of the OpenShell gRPC service. The supervisor and sandbox-internal RPCs stay out of scope and remain reachable through the raw client.
• The feature set matches the union of the other SDKs, tracked in a parity matrix in the repository.
• Credentials are never sent over plaintext HTTP to a non-loopback host unless the caller opts in, and never appear in logs, exceptions, or ToString output.
• OpenShell.Sdk.DependencyInjection registers a singleton client and its per-area clients, binds options from configuration, validates them at startup, supports several named gateways, and provides a health check and a fluent builder.
• Every RPC emits one OpenTelemetry client span and a duration measurement under the OpenShell.Sdk activity source and meter, following the OpenTelemetry gRPC conventions. Nothing is recorded or allocated without a listener, and payloads and credentials are never recorded. The SDK also logs its own events through ILogger.
• The SDK uses modern C#: nullable reference types, async-only APIs with CancellationToken and IAsyncEnumerable<T>, records with required and init members, pattern matching and switch expressions, file-scoped namespaces, and TimeProvider for time. An .editorconfig and analyzers built as errors enforce the style, and the SDK is trimming and AOT compatible.
• Unit tests run on every supported .NET version, and integration tests run against a real gateway in an opt-in lane.
• Branch checks run format, build, tests, and a package dry run through mise tasks, and release tags publish the packages.
• A published docs page and the contributor docs describe the SDK.

Alternatives Considered

• Generate bindings in each .NET project: repeats the authentication, waits, and safety behavior in every consumer.
• Call another SDK or the CLI from .NET: adds a second runtime and gives .NET callers no native types, cancellation, or streaming.
• Wrap the Rust SDK through native interop: needs a native binary per platform and complicates packaging and AOT.
• An OpenShell extension point (middleware, interceptor, provider): these extend the gateway or sandbox, not a client application.
• A community SDK outside this repository: trails gateway releases. In-repo, an incompatible proto change fails CI.

Agent Investigation

The OpenShell service has 83 RPCs: 65 are user-facing and 18 belong to the in-sandbox supervisor and gateway peers, which no existing SDK implements.

A draft implementation, offered as a starting point for review, is on a fork branch: https://github.com/zcsizmadia/OpenShell/tree/feat/4392-dotnet-sdk/zcsizmadia (sdk/dotnet/). Two documents in it describe the proposal:

• sdk/dotnet/README.md: the proposed user-facing API, with usage examples for authentication, retries, dependency injection, observability, and testing.
• sdk/dotnet/PARITY.md: the feature parity matrix against the Go, Rust, TypeScript, and Python SDKs, with the status of each feature and the known differences.

The draft builds without warnings and passes its unit tests on net8.0 and net10.0. It has not run against a real gateway, and its CI jobs have not run yet.

The branch is large (about 170 files, half of them tests), so I propose landing it as separate PRs: core client and API areas, OIDC and gateway discovery, retry and telemetry with the DI package, the testing package, then CI and docs.

Related: #2565 (stabilize public API, SDK, and extension contracts) and #2825 (proto drift detection and SDK sync notifications). A .NET SDK would join both.

Questions for maintainers: is GitHub Packages the intended feed, are the DI and testing packages in scope, and who owns sdk/dotnet/?

Checklist

• I've reviewed existing issues and the published docs
• This is a design proposal, not a "please build this" request