[maxdubrinsky]

Summary

First focused PR split out of #1617. Adds a new openshell-sdk crate: the shared async Rust client for OpenShell gateways. It owns gRPC channel construction, TLS material handling, request interceptors, OIDC single-flight token refresh, and the Cloudflare Access edge tunnel, and exposes a sandbox-focused high-level surface plus a raw escape hatch.

The crate is additive (nothing consumes it yet, so no behavior change). The one non-additive piece is a behavior-preserving extraction: the signature-unverified JWT exp decoder moves out of openshell-core/src/grpc_client.rs into a shared openshell_core::jwt module, so the sandbox-side client and the SDK's refresh path derive token expiry from one place instead of each reimplementing it. Moving openshell-cli and openshell-tui onto the crate is a separate follow-up PR.

Related Issue

• Design: RFC 0008 (rfc-0008: SDK architecture, shared core and per-language bindings #1764), which merges first.
• Split out of feat(sdk): shared SDK rust core and language specific bindings #1617. Sequence: RFC (rfc-0008: SDK architecture, shared core and per-language bindings #1764), this crate, CLI/TUI migration, then openshell-sdk-node (napi binding, Pi example, CI).
• linear://nvidia/issue/OSGH-110/python-and-typescript-sdk-support

Changes

• New crates/openshell-sdk/:
  • OpenShellClient: high-level sandbox surface (health, sandbox CRUD, readiness and deletion waits, non-streaming exec).
  • Transport stack: channel construction and the five transport/auth modes the CLI exercises today (plaintext, mTLS, OIDC bearer over HTTPS, Cloudflare Access tunnel, insecure TLS).
  • OIDC: single-flight refresh wired into the client auth path (proactive before unary calls, reactive on Unauthenticated with one retry), behind a napi-free Refresh trait so the core stays binding-agnostic.
  • raw module: re-exports the generated tonic clients for RPCs the curated surface does not yet cover.
  • SdkError taxonomy and curated types (SandboxSpec, SandboxRef, Health, ListOptions, ExecOptions).
  • Crate README.md.
• Shared JWT-exp decoder: new openshell_core::jwt::parse_exp_secs, extracted from grpc_client.rs (which now calls it). The SDK reuses it to derive a proactive-refresh deadline from a bearer JWT when the caller does not advertise expires_at, so consumers do not reimplement JWT expiry parsing per language.
• AGENTS.md: architecture-table row for the new crate.
• Cargo.lock: additive (the crate registers via the existing members = ["crates/*"]).

No changes to openshell-cli or openshell-tui. The only openshell-core change is the JWT-exp extraction above; the transport code the CLI/TUI own today (openshell-core/src/auth.rs, openshell-cli/src/edge_tunnel.rs, tls.rs, oidc_auth.rs) is untouched here and migrates onto the SDK in the follow-up PR, where the now-duplicated code is removed.

Testing

• cargo build --workspace, cargo clippy --workspace --all-targets -- -D warnings, and cargo fmt --all -- --check are clean.
• cargo test -p openshell-sdk: 9 unit + 12 mock-gateway tests pass (incl. single-flight cancellation-safety, Debug-redaction, and token-encoding regression tests).
• cargo test -p openshell-core: 299 pass, including 3 new jwt decoder tests. The pre-existing grpc_client expiry tests still pass, confirming the decoder extraction is behavior-preserving.
• license:check and markdown:lint pass.
• E2E not applicable. Additive crate with no consumers and no behavior change; the mock-gateway tests are the regression surface for the client.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable): AGENTS.md architecture table and the crate README.md.

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

[github-actions]

Label test:e2e applied, but pull-request/1862 is at d1668e2 while the PR head is 5d5cfe9. A maintainer needs to comment /ok to test 5d5cfe9a0dd5aa2dfd006cc5c43788245a3a6065 to refresh the mirror. Once the mirror catches up, re-run Branch E2E Checks from the Actions tab.

[drew]

/ok to test 5d5cfe9

[drew]

Agent review

crates/openshell-sdk/src/client.rs: [nit] Error-variant mappings undermine the crate's own SdkError::code() discriminant contract: wait_ready/wait_deleted timeouts (lines 245, 384) and a sandbox entering the Error phase (line 224) are reported as SdkError::Connect when no connection failed, and sandbox_from_response (line 471) maps a malformed server response to InvalidConfig although the caller's configuration is fine. A binding consumer switching on code() (advertised in error.rs as the stable cross-language discriminant) would misinterpret a provisioning timeout as a connectivity failure. Dedicated variants (e.g. Timeout) or at least Rpc would be more honest.

[drew]

Review follow-up at de733448:

• Resolved seven inline threads addressed in cc9e53c3 / de733448.
• Left the refresh-error thread open: the double wrapping is fixed, but Transient and Terminal still collapse into the same SdkError::Auth discriminant.
• Left the edge-tunnel double-start race open: it is still present and remains deferred to follow-up migration/consolidation work.
• The review-body SdkError mapping concern remains unaddressed: sandbox wait timeouts/error phases still map to Connect, and a missing sandbox in a gateway response still maps to InvalidConfig.