feat(api)!: replace implicit workspace selection with typed scope selectors

[drew]

User Story

As an API or SDK client, I want workspace scope represented explicitly in request types, so that I can distinguish one workspace, the default workspace, and all workspaces without relying on empty strings or mutually exclusive booleans.

Problem Statement

Many requests document an empty workspace string as selecting default. Several also pair workspace with all_workspaces and describe mutual exclusion only in comments. Proto3 scalar fields cannot distinguish an omitted string from an explicitly empty string, and the wire type permits contradictory combinations.

Impact / Why This Matters

Clients cannot express intent precisely, generated SDKs must reproduce prose-only validation, and future changes to default-workspace behavior would require a breaking request-shape change. The ambiguity is especially visible in Kubernetes operator mode, where the gateway's logical default workspace may not be usable as a Kubernetes namespace.

Proposed Design

Introduce a reusable, presence-aware workspace selector for requests that need scope. It should distinguish:

• one explicitly named workspace;
• all authorized workspaces, where the RPC supports it; and
• omitted scope, only if OpenShell deliberately retains a documented default-workspace behavior.

Use a message or oneof so contradictory states are unrepresentable. Do not introduce magic string sentinels.

Acceptance Criteria

• All affected public requests use the same typed workspace-selection convention.
• A request cannot encode both one workspace and all workspaces.
• Omitted, empty, default, and all-workspaces behavior is explicitly decided and documented.
• Authorization is evaluated against the selected scope consistently.
• Rust, Python, TypeScript, and Go SDKs expose the same scope choices idiomatically.
• CLI and TUI behavior remains intentional and documented, including commands that omit --workspace.
• Old fields are removed or migrated with reserved names/tags and migration guidance.
• Tests cover named, default/omitted, all-workspaces, unauthorized, and malformed cases.

Alternatives Considered

Keep workspace plus all_workspaces and enforce mutual exclusion in handlers. This leaves invalid states in every generated client and does not solve presence ambiguity. Use workspace: "-" as an all-workspaces sentinel. This is compact but introduces magic-string semantics without adopting a broader hierarchical resource-name convention.

Agent Investigation

The current protobuf contains repeated workspace plus all_workspaces patterns, and the Python, TUI, and other clients construct those fields directly. Kubernetes operator-mode default workspace semantics are separately discussed in #2971.

Related: #2565, #2971. Source audit: https://gist.github.com/mrunalp/e80942c1544a0225ee588796a41ab30b.

[mrunalp]

🏗️ build-plan

Implementation Plan

Issue type: feat (breaking public API)
Complexity: High
Confidence: Medium — the code path is clear, but this is a coordinated 42-request wire migration across four SDKs

Summary

Replace every public request field whose documented meaning is "empty workspace defaults to default" with a shared, presence-aware WorkspaceSelector. The selector has mutually exclusive named-workspace and all-workspaces variants; named default is the explicit default choice, while missing selectors and empty names fail closed. The all-workspaces variant is accepted only by the four cross-workspace list RPCs.

Scope

• proto/datamodel.proto, proto/openshell.proto, proto/inference.proto: define the shared selector and marker, migrate 42 public requests, and reserve every removed field name/tag.
• crates/openshell-server/src/auth/workspace_authz.rs, grpc/workspace.rs: centralize selector parsing, validation, workspace resolution, and authorization.
• Gateway handlers in grpc/{sandbox,service,provider,policy}.rs, inference.rs, and multiplex.rs: consume the typed selector consistently while preserving authorization ordering.
• Rust SDK, CLI, and TUI request builders/tests: send one explicit named/default/all selection.
• Python, TypeScript, and Go SDK clients/tests/docs: expose the same choices idiomatically and construct the generated oneof.
• Committed Go protobuf bindings: regenerate from the migrated schema. Python and TypeScript generated output remains ignored.
• docs/sandboxes/manage-workspaces.mdx, related SDK docs/readmes, and architecture/gateway.md: document explicit default/all behavior and migration guidance.

The migration covers sandbox/template, service, provider/refresh, config/policy/log/draft, and inference requests whose current empty string means default. Resource identity fields, driver/storage envelopes, workspace membership resource names, sandbox-auth internal requests, and provider-profile requests where empty means platform scope are intentionally excluded.

Implementation Steps

1. Add WorkspaceSelector with workspace and all_workspaces oneof variants, migrate all 42 request messages to workspace_scope at new tags, reserve old names/tags, regenerate Go bindings, and validate the schema.
2. Add a central resolver/authorizer for required named scope, permitted all scope, missing/empty/malformed scope, global-only operations, and platform-admin all-workspace authorization.
3. Migrate server handlers by domain. Preserve authorization-before-resource-lookup behavior; allow all-workspace scope only on sandbox, template, provider, and service list RPCs.
4. Update Rust callers, CLI, and TUI so omitted CLI workspace resolves to and sends explicit named default, while --all-workspaces sends only the all variant.
5. Update curated Rust, Python, TypeScript, and Go SDK surfaces so callers cannot construct the old contradictory workspace-plus-boolean state.
6. Update migration and behavior documentation, then run focused and full verification.

Test Plan

• Unit tests: selector decoding and authorization for named, explicit default, missing, empty, unsupported all, authorized all, unauthorized all, and global/selector conflicts; handler coverage across affected domains.
• Integration tests: Rust mock client, Python fake stub, TypeScript mocked transport, Go converters/fakes, CLI default/explicit/all request construction, and TUI workspace toggle construction.
• E2E tests: update workspace API/OIDC coverage for named/default/all, malformed requests, cross-workspace isolation, and non-platform-admin all-workspace denial; run the relevant Docker OIDC/Python lane.

Risks & Open Questions

• This is intentionally wire-breaking. Old clients send now-reserved tags; requiring selector presence ensures version skew fails closed instead of silently operating on default. Gateway and SDK releases must therefore be coordinated.
• A staged compatibility field would conflict with the requested remove-and-reserve end state. Implement in ordered steps, but merge and release atomically.
• Provider-profile platform-vs-workspace scope and sandbox-auth internal request fields require separate design decisions and remain out of scope.
• No gateway TOML, driver, Helm, process identity, /proc, SELinux, or AppArmor behavior changes.

Documentation Impact

• Update public workspace behavior/migration docs and affected SDK examples.
• Update the gateway architecture invariant.
• No docs/reference/gateway-config.mdx or compute-driver documentation change is required.

---

Revision 1 — initial plan

[mrunalp]

Implemented in #3245.

The change introduces the typed WorkspaceSelector oneof, enforces explicit workspace selection and constrained all-workspace listing in the gateway, reserves the removed protobuf fields, and migrates the CLI, TUI, SDKs, generated Go bindings, tests, RFC, architecture, and user documentation.

Validation completed successfully with mise run pre-commit and mise run ci (plus focused Rust, Python, Go, and TypeScript SDK suites during implementation).