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

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

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

@@ -479,12 +479,13 @@ use openshell_core::proto::{
 
 ### Proto field gotchas
 
-- `DeleteSandboxRequest` uses the `name` field (not `id`):
+- `DeleteSandboxRequest` uses the canonical sandbox name and an explicit workspace:
   ```rust
   let req = openshell_core::proto::DeleteSandboxRequest {
-      name: sandbox_name,
-      workspace_scope: Some(workspace_selector(workspace)),
+      sandbox: sandbox_name,
+      workspace: workspace.to_string(),
       allow_missing: true,
+      ..Default::default()
   };
   ```
 - Delete responses carry `DeletionOutcome`: distinguish `Accepted` (cleanup
@@ -493,21 +494,23 @@ use openshell_core::proto::{
 - `WatchSandboxRequest` has extra fields beyond what you might need — always use `..Default::default()`:
   ```rust
   let req = openshell_core::proto::WatchSandboxRequest {
-      id: sandbox_id,
+      sandbox: sandbox_name,
       follow_status: false,
       follow_logs: true,
       follow_events: false,
       log_tail_lines: 0,
+      workspace: workspace.to_string(),
       ..Default::default()
   };
   ```
 - `SandboxLogLine` proto fields: `sandbox_id`, `event_time` (`Option<prost_types::Timestamp>`), `level`, `target`, `message`, `source`, `fields` (`HashMap<String, String>`).
-- Workspace-scoped request fields use `workspace_scope: Option<WorkspaceSelector>`.
-  Select one workspace with `Some(workspace_selector(name))`. List requests that
-  explicitly support cross-workspace access also accept
-  `Some(all_workspaces_selector())`; do not use that marker on other requests.
-- `GetSandboxLogsRequest` fields: `sandbox_id`, `lines` (u32), `since_time` (`Option<prost_types::Timestamp>`),
-  `sources` (Vec<String>), `min_level` (String), `workspace_scope`.
+- Single-resource requests use a `workspace: String` field with the canonical
+  workspace name. Collection list requests use
+  `workspace_scope: Option<WorkspaceSelector>` so callers can select one
+  workspace with `Some(workspace_selector(name))` or, where authorized,
+  `Some(all_workspaces_selector())`.
+- `GetSandboxLogsRequest` fields: `sandbox`, `lines` (u32), `since_time` (`Option<prost_types::Timestamp>`),
+  `sources` (Vec<String>), `min_level` (String), `workspace`.
 - `ListSandboxesRequest` fields: `page_size` (i32), `page_token` (String),
   `label_selector` (String), `workspace_scope`.
 - `ListProvidersRequest` fields: `page_size` (i32), `page_token` (String),
@@ -517,12 +520,12 @@ use openshell_core::proto::{
 - Paginated list responses return `next_page_token`. Continue with the same
   request parameters and that token until it is empty; changing filters or
   scope invalidates the token.
-- `UpdateConfigRequest` fields include `name` (String, sandbox name or empty for
-  global), `setting_key`, `setting_value`, `delete_setting` (bool), `global`
-  (bool), and `workspace_scope`. Sandbox-scoped updates require a named selector;
-  gateway-global updates must leave `workspace_scope` as `None`.
-- Most resource requests require an explicit named `workspace_scope`, including
-  the `default` workspace. An omitted selector is not an implicit default.
+- `UpdateConfigRequest` fields include `sandbox` (String, canonical sandbox name),
+  `setting_key`, `setting_value`, `delete_setting` (bool), `global` (bool), and
+  `workspace`. Sandbox-scoped updates require canonical `sandbox` and `workspace`
+  names; gateway-global updates leave both fields empty.
+- Most single-resource requests require an explicit canonical `workspace` name,
+  including the `default` workspace. An empty value is not an implicit default.
 
 ### gRPC timeouts
 

architecture/gateway.md

@@ -114,13 +114,20 @@ cross-origin or sibling-subdomain request.
 
 Public workspace-scoped RPCs carry a typed `WorkspaceSelector`. A request must
 select one non-empty workspace explicitly; `default` is an ordinary explicit
-name, not an omitted-value fallback. Sandbox, sandbox template, provider, and
-service list RPCs also accept an all-workspaces marker after Platform Admin
-authorization. Single-workspace handlers reject that marker. Platform-global
-policy operations require the selector to be absent, while workspace policy
-operations require it. The gateway authorizes the selected scope before
-performing resource lookup so malformed, unsupported, and unauthorized scopes
-have consistent behavior across resource types.
+name, not an omitted-value fallback. Every public sandbox-scoped RPC identifies
+the sandbox with a string `sandbox` and carries its canonical workspace name in
+a separate string `workspace` field. Canonical sandbox IDs remain internal metadata used
+at authentication, persistence, and compute-driver boundaries; public callers
+do not use them as sandbox references. The gateway resolves the name to the
+persisted sandbox record only after authorizing the selected workspace. A
+sandbox principal is instead resolved by the immutable ID in its authenticated
+identity, then checked against the requested name and workspace. Missing and
+unauthorized references use the same response within each principal class so
+the resolver does not expose an object-existence oracle. Sandbox, sandbox
+template, provider, and service collection list RPCs use `workspace_scope` so
+they can also accept an all-workspaces marker after Platform Admin
+authorization. Platform-global policy operations require `sandbox` and
+`workspace` to be empty, while sandbox policy operations require both.
 
 Docker and Podman report the local address through which their sandboxes can
 reach the gateway. When the primary listener covers that address, the gateway
@@ -826,8 +833,8 @@ channel and returns the exec with an error. Once a command reports its exit
 status, the gateway also bounds how long it waits for the trailing channel close.
 
 `ForwardTcp` is the client-facing byte stream for SSH and service forwarding.
-The first frame is a `TcpForwardInit` that carries the sandbox ID, an
-authorization token from `CreateSshSession`, and an explicit target:
+The first frame is a `TcpForwardInit` that carries the workspace-scoped sandbox
+name, an authorization token from `CreateSshSession`, and an explicit target:
 `target.ssh` for the sandbox SSH socket or `target.tcp` for a loopback service
 inside the sandbox. The gateway validates the token and sandbox readiness,
 sends a targeted `RelayOpen` to the supervisor, then bridges

crates/openshell-cli/src/commands/provider.rs

@@ -92,8 +92,8 @@ pub async fn sandbox_provider_list(
     let mut client = grpc_client(server, tls).await?;
     let response = client
         .list_sandbox_providers(ListSandboxProvidersRequest {
-            sandbox_name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?;
@@ -127,8 +127,8 @@ pub async fn sandbox_provider_attach(
     // Fetch current sandbox to get resource_version for CAS
     let sandbox = client
         .get_sandbox(GetSandboxRequest {
-            name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
         })
         .await
         .map_err(|status| miette!("provider attachment lookup failed ({})", status.code()))?
@@ -141,10 +141,10 @@ pub async fn sandbox_provider_attach(
     let response = match client
         .attach_sandbox_provider(AttachSandboxProviderRequest {
             request_id: String::new(),
-            sandbox_name: name.to_string(),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
             provider_name: provider.to_string(),
             expected_resource_version: resource_version,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
         })
         .await
     {
@@ -198,8 +198,8 @@ pub async fn sandbox_provider_detach(
     // Fetch current sandbox to get resource_version for CAS
     let sandbox = client
         .get_sandbox(GetSandboxRequest {
-            name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
         })
         .await
         .map_err(|status| miette!("provider detachment lookup failed ({})", status.code()))?
@@ -212,10 +212,10 @@ pub async fn sandbox_provider_detach(
     let response = match client
         .detach_sandbox_provider(DetachSandboxProviderRequest {
             request_id: String::new(),
-            sandbox_name: name.to_string(),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
             provider_name: provider.to_string(),
             expected_resource_version: resource_version,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
         })
         .await
     {
@@ -550,7 +550,7 @@ async fn auto_create_provider(
                 profile_workspace: workspace.to_string(),
                 credential_handles: HashMap::new(),
             }),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         };
 
         let response = client.create_provider(request).await.map_err(|status| {
@@ -599,7 +599,7 @@ async fn auto_create_provider(
                     profile_workspace: workspace.to_string(),
                     credential_handles: HashMap::new(),
                 }),
-                workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+                workspace: (workspace).to_string(),
             };
 
             match client.create_provider(request).await {
@@ -735,7 +735,7 @@ async fn rollback_provider_create_after_gcloud_adc_failure(
             request_id: String::new(),
             allow_missing: true,
             name: provider_name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
     {
@@ -1202,7 +1202,7 @@ pub async fn provider_create_with_options(options: ProviderCreateOptions<'_>) ->
                 profile_workspace: profile_workspace.to_string(),
                 credential_handles: HashMap::new(),
             }),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?;
@@ -1233,7 +1233,7 @@ pub async fn provider_create_with_options(options: ProviderCreateOptions<'_>) ->
                     "refresh_token".to_string(),
                 ],
                 expiration_time: None,
-                workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+                workspace: (workspace).to_string(),
             })
             .await
         {
@@ -1252,7 +1252,7 @@ pub async fn provider_create_with_options(options: ProviderCreateOptions<'_>) ->
                 request_id: String::new(),
                 provider: provider_name.clone(),
                 credential_key: adc_credential_key,
-                workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+                workspace: (workspace).to_string(),
             })
             .await
         {
@@ -1293,7 +1293,7 @@ pub async fn provider_get(
     let response = client
         .get_provider(GetProviderRequest {
             name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?;
@@ -1826,7 +1826,7 @@ pub async fn provider_refresh_status(
         .get_provider_refresh_status(GetProviderRefreshStatusRequest {
             provider: name.to_string(),
             credential_key: credential_key.unwrap_or_default().to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -1912,7 +1912,7 @@ pub async fn provider_refresh_config(
                 .map(openshell_core::time::timestamp_from_millis)
                 .transpose()
                 .into_diagnostic()?,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -1942,7 +1942,7 @@ pub async fn provider_rotate(
             request_id: String::new(),
             provider: name.to_string(),
             credential_key: credential_key.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -1981,7 +1981,7 @@ pub async fn provider_refresh_delete(
             allow_missing: true,
             provider: name.to_string(),
             credential_key: credential_key.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -2358,7 +2358,7 @@ pub async fn provider_update(options: ProviderUpdateOptions<'_>) -> Result<()> {
     let existing = match client
         .get_provider(GetProviderRequest {
             name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
     {
@@ -2454,7 +2454,7 @@ pub async fn provider_update(options: ProviderUpdateOptions<'_>) -> Result<()> {
                 })
                 .collect::<Result<HashMap<_, _>, _>>()
                 .into_diagnostic()?,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
             clear_credential_expiration_keys,
         })
         .await
@@ -2496,7 +2496,7 @@ pub async fn provider_delete(
                 request_id: String::new(),
                 allow_missing: true,
                 name: name.clone(),
-                workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+                workspace: (workspace).to_string(),
             })
             .await
         {

crates/openshell-cli/src/commands/provider_readiness.rs

@@ -124,7 +124,7 @@ fn validate_mutation_receipts(
             || !sandbox_ids.insert(desired.sandbox_id.as_str())
             || expected
                 .sandbox
-                .is_some_and(|(name, id)| desired.sandbox_name != name || desired.sandbox_id != id)
+                .is_some_and(|(name, id)| desired.sandbox != name || desired.sandbox_id != id)
             || provider.is_some_and(|provider| {
                 desired.provider_id != provider.id
                     || desired.provider_resource_version != provider.resource_version
@@ -274,10 +274,10 @@ pub async fn sandbox_provider_status(
         provider_status(
             &mut client,
             GetSandboxProviderStatusRequest {
-                sandbox_name: name.to_string(),
+                sandbox: name.to_string(),
                 provider_name: provider.to_string(),
                 receipt_id: receipt_id.to_string(),
-                workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+                workspace: workspace.to_string(),
             },
         ),
     )
@@ -348,7 +348,7 @@ fn receipt_json(receipt: &ProviderMutationReceipt) -> serde_json::Value {
     let desired = receipt.desired.as_ref().map(|desired| {
         serde_json::json!({
             "sandbox_id": desired.sandbox_id,
-            "sandbox_name": desired.sandbox_name,
+            "sandbox": desired.sandbox,
             "attachment_epoch": desired.attachment_epoch,
             "provider_id": desired.provider_id,
             "provider_resource_version": desired.provider_resource_version.to_string(),
@@ -415,7 +415,7 @@ fn print_statuses(mutation_id: &str, results: &[DisplayStatus], output: &str) ->
         let sandbox = receipt
             .desired
             .as_ref()
-            .map_or("unknown", |desired| desired.sandbox_name.as_str());
+            .map_or("unknown", |desired| desired.sandbox.as_str());
         println!(
             "{} / {}: {} ({})",
             sandbox,
@@ -486,7 +486,7 @@ mod tests {
             persisted_time: Some(openshell_core::time::timestamp_from_millis(1).unwrap()),
             desired: Some(ProviderDesiredIdentity {
                 sandbox_id: "sandbox-id".to_string(),
-                sandbox_name: "sandbox".to_string(),
+                sandbox: "sandbox".to_string(),
                 provider_id: "provider-id".to_string(),
                 ..Default::default()
             }),