feat(api)!: use sandbox names as canonical RPC references

[drew]

Summary

Standardize public API references around canonical entity names. The primary resource targeted by an RPC uses name; related resources use their role name such as sandbox, provider, service, or rule. Public workspace-scoped requests declare workspace_scope: WorkspaceSelector first.

Immutable IDs remain internal to authentication, persistence, compute-driver boundaries, and durable child-resource identity. This is an intentionally breaking API change.

Related Issue

Closes #3050

Changes

• Use name for the primary resource targeted by an RPC.
• Use role fields for related canonical-name references and remove redundant *_name fields.
• Restore workspace_scope: WorkspaceSelector as the first field on public workspace-scoped requests.
• Preserve the typed-selector validation, authorization, SDK scope choices, and documentation behavior established by PR feat(api): add typed workspace selectors #3245.
• Permit all_workspaces only on supported sandbox, sandbox-template, provider, and service collection list requests.
• Keep workspace-targeting requests such as GetWorkspaceRequest as { name }.
• Preserve authenticated sandbox bootstrap and platform provider-profile scope where a workspace selector may be omitted.
• Keep immutable IDs for internal storage, authentication, drivers, replay, and stable child-resource identity.
• Add a canonical protobuf API conventions guide and enforce its mechanical request rules during pre-commit.
• Regenerate bindings and update Rust, Python, Go, and TypeScript clients.
• Update CLI, TUI, interceptors, examples, tests, architecture, and user documentation.

Testing

• mise run pre-commit
• mise run proto:conventions
• cargo check --workspace --all-targets
• cargo test -p openshell-server --lib (1,698 passed; 9 ignored)
• Python tests (253 passed)
• TypeScript SDK tests (122 passed)
• Affected Go SDK package tests
• Go, Python, and TypeScript protobuf generation

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture and user-facing documentation updated

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3272.docs.buildwithfern.com/openshell

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[mrunalp]

Findings

1. DeleteSandbox still returns PERMISSION_DENIED for a non-member, while the new E2E test requires NOT_FOUND. Unlike other handlers, it calls authorize_workspace_selector without translating the denial. The test should fail once E2E actually runs.
   crates/openshell-server/src/grpc/sandbox.rs:1364, e2e/python/oidc/workspace_authz_test.py:710

2. Background-forward ownership is no longer uniquely scoped. Before this PR, process validation used the immutable ID stored in the PID record. Now stop_forward discards that ID, matches only --sandbox , and ignores --workspace. Since names may repeat across workspaces,
   operations on one sandbox can misidentify or terminate another workspace’s forward.
   crates/openshell-core/src/forward.rs:26, :297, :413

3. Architecture documentation still says TcpForwardInit carries a sandbox ID, but the schema now carries (sandbox, workspace_scope).
   architecture/gateway.md:802, proto/openshell.proto:1587

Overview

The central design is sound: public RPCs use (workspace_scope, sandbox name), while immutable IDs remain internal for authentication, persistence, and driver boundaries. The resolver correctly authorizes before name lookup and binds sandbox principals through their authenticated
ID.

The protobuf tag compaction is deliberately wire-incompatible—for example, CreateSandboxRequest.workspace_scope’s old tag becomes request_id. That is worth explicit maintainer approval because it prevents mixed-version operation, despite the PR’s breaking-change designation.

[mrunalp]

Key findings:

• DeleteSandbox returns PERMISSION_DENIED for non-members, while the E2E suite expects NOT_FOUND (handler (

  OpenShell/crates/openshell-server/src/grpc/sandbox.rs

  Line 1360 in a3c5878

  async fn handle_delete_sandbox_inner(

  ), E2E expectation
  (

  OpenShell/e2e/python/oidc/workspace_authz_test.py

  Line 715 in a3c5878

  if rpc_name in {

  )).

• Background port forwards are tracked and matched by sandbox name and port, without workspace or immutable identity. Stopping/deleting foo in one workspace can terminate foo’s forward from another workspace (forward.rs
  (

  OpenShell/crates/openshell-core/src/forward.rs

  Line 413 in a3c5878

  pub fn stop_forward(name: &str, port: u16) -> Result<bool> {

  )).

• Removed protobuf tags are reused rather than reserved. For example, CreateSandboxRequest reassigns old tags 7 and 8, risking cross-version wire misinterpretation and violating issue feat(api)!: unify sandbox references across gateway RPCs #3050’s acceptance criteria (proto
  (

  OpenShell/proto/openshell.proto

  Line 1143 in a3c5878

  // Create sandbox request.

  )).

• Contributor guidance remains stale: the TUI skill still documents nonexistent workspace_scope fields (skill (

  OpenShell/.agents/skills/tui-development/SKILL.md

  Line 480 in a3c5878

  ### Proto field gotchas

  )).

[drew]

Addressed findings 1–3 in commit 90c5d02:

• DeleteSandbox now maps unauthorized workspace access to NOT_FOUND, with the server authorization test updated accordingly.
• Background forwards are now keyed by workspace and sandbox name, and process validation checks workspace, name, port, and the immutable sandbox ID before listing or signaling a PID. forward list also exposes the workspace.
• The gateway architecture text, TUI contributor guidance, public CLI skill, and port-forwarding docs now reflect the end-state API and tracking behavior.

On finding 4: the protobuf tag reuse is intentional and maintainer-directed. This PR explicitly breaks API and wire compatibility; mixed-version clients and servers are unsupported, and clients must regenerate from the new schema. We are therefore deliberately not reserving the removed tags or names solely for backward compatibility, so no code change is planned for that finding.

[github-actions]

Label test:e2e applied for bd37630. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[johntmyers]

gator-agent

Blocked

Gator cannot begin the current-head code review because this PR has merge conflicts with main.

Next action: @drew, please rebase or merge main, resolve the conflicts, and push the updated branch. Gator will validate and review the new head afterward.

Gator metadata

• Head SHA: 91eb1f2d88dba97ebb6fc80525f931e8ab4ed574
• Gator payload: 9
• Next state: gator:blocked
• Blocked reason: merge_conflict

[johntmyers]

gator-agent

PR Review Status

Thanks @drew. I checked your response to @mrunalp’s earlier review: the current head now conceals unauthorized DeleteSandbox lookups, scopes background forwards by workspace and immutable identity, and updates the affected architecture and user documentation. I also treated the deliberate protobuf tag reuse as maintainer-approved for this intentionally wire-incompatible change. The initial full-diff review found two remaining correctness blockers.

Action required: fix the two findings below and push an updated head for a focused follow-up review.

Blocking findings:

• GATOR-defae1d4-01: durable sandbox mutations expose different authorization status semantics when request_id is set.
• GATOR-defae1d4-02: DeleteService can remove a concurrently recreated endpoint instead of the instance it resolved.

Carried findings:

• None

Gator metadata

• Validation: Project-valid implementation of linked issue #3050, authored and directed by a maintainer.
• Docs: User-facing and architecture documentation are updated for the canonical-reference change.
• Checks: Current-head Branch Checks are failing and E2E is still running; review findings must be resolved before pipeline handoff.
• E2E: test:e2e is applied and the current-head workflow is in progress.
• Head SHA: defae1d41352eac0633404148a350de5077980a0
• Base SHA: 50c5cf8ed0423f545fee7e0ccc7e7699eec9e290
• Merge base SHA: 50c5cf8ed0423f545fee7e0ccc7e7699eec9e290
• Patch ID: 75023ee424d6b7d00c1d866c61c877c18683b894
• Gator payload: 9
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[johntmyers]

gator-agent

PR Review Status

Thanks @drew. I reviewed the non-equivalent rebase, the removal of the protobuf convention checker, and the refreshed schema fingerprints against the previously reviewed author patch. The two prior Gator findings remain resolved, and the critical-only delta review found no newly introduced Critical security, data-loss, or correctness defects.

Blocking findings:

• No blocking findings remain

Carried findings:

• None

Gator metadata

• Validation: Project-valid implementation of linked issue #3050, authored and directed by a maintainer.
• Docs: User-facing, architecture, SDK, contributor, and protobuf convention documentation reflect the canonical-reference change.
• Checks: Current-head Branch Checks are running; Helm Lint, Trivy Changes, DCO, GPU E2E, and completed jobs are green.
• E2E: test:e2e is applied and the current-head Branch E2E Checks workflow is queued or running.
• Head SHA: e9f532583c59bd6bd38ac073af662d6e563f5820
• Base SHA: e38d7254e6099a42d6b80329b8e4ef6f0817931f
• Merge base SHA: e38d7254e6099a42d6b80329b8e4ef6f0817931f
• Patch ID: d15ecf549c3196f47a575d075fbfa459ca54714d
• Gator payload: 9
• Review mode: critical_only
• Previous reviewed SHA: ae926499c7c4e871460e04994d952f7496a4dd75
• Review budget exhausted: yes
• Maintainer decision required: no — prior findings remain resolved, the delta stays within the maintainer-authored API convention scope, and no new Critical was found.
• Next state: gator:watch-pipeline

[johntmyers]

gator-agent

PR Review Status

Thanks @drew. I reviewed the provider-receipt JSON naming correction and its regression test against the previously reviewed patch. The two prior Gator findings remain resolved, and the critical-only delta review found no newly introduced Critical security, data-loss, or correctness defects.

Blocking findings:

• No blocking findings remain

Carried findings:

• None

Gator metadata

• Validation: Project-valid implementation of linked issue #3050, authored and directed by a maintainer.
• Docs: User-facing, architecture, SDK, contributor, and protobuf convention documentation reflect the canonical-reference change.
• Checks: Current-head Branch Checks are running; Helm Lint, Trivy Changes, DCO, GPU E2E, and completed jobs are green.
• E2E: test:e2e is applied and the current-head Branch E2E Checks workflow is running.
• Head SHA: aa7134deb23565aa1cc5abe0039a0c50a64bcdcd
• Base SHA: e38d7254e6099a42d6b80329b8e4ef6f0817931f
• Merge base SHA: e38d7254e6099a42d6b80329b8e4ef6f0817931f
• Patch ID: f7566211bfc75f294be8bdaaaee51fc338e2e418
• Gator payload: 9
• Review mode: critical_only
• Previous reviewed SHA: e9f532583c59bd6bd38ac073af662d6e563f5820
• Review budget exhausted: yes
• Maintainer decision required: no — prior findings remain resolved, the delta stays within the maintainer-authored canonical-reference scope, and no new Critical was found.
• Next state: gator:watch-pipeline

[johntmyers]

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: The current head completed Gator's critical-only review with no blocking findings remaining; the PR merged while the required E2E workflow was still being monitored.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.