Phase 2 slice 1: Qualify OpenShell transports and migrate sandbox inventory and readiness
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
> [!WARNING]
> This issue has a refined plan but no recorded `Accept` decision. Only @rsliter should implement it after acceptance.
Parent Epic: #9802
## Outcome
Use the OpenShell TypeScript SDK `0.0.116` for sandbox inventory and readiness on named NemoClaw-managed gateways. Preserve the Phase 1 behavior contract and prohibit automatic CLI fallback.
## Scope authority
- #11229 accepted OpenShell `0.0.116` as the only supported managed runtime. PR #11251 completed that migration.
- #9803 and PR #10574 established the typed Phase 1 inventory and readiness contract.
- PR #11921 owns credential-free SDK delivery. When it merges, it satisfies this issue's package-delivery prerequisite.
- The remaining SDK transport placement in this issue still requires an `Accept` decision.
## Proposed scope
- Add an SDK-backed implementation of the existing sandbox observer contract.
- Support named NemoClaw-managed gateways and workspace `default`.
- Reuse the managed SDK connection owner for gateway targeting and mTLS material.
- Use the release-pinned raw main-service client for sandbox `get` and `list`. The curated SDK methods do not preserve both explicit workspace selection and cancellation.
- Keep readiness and deletion convergence in NemoClaw action code. Do not use SDK `waitReady` or `waitDeleted` because their semantics do not match the existing debounce, identity, and cleanup rules.
- Map SDK status and connection failures into the existing transport-neutral error contract.
- Keep SDK and wire types inside `src/lib/adapters/openshell/`.
- Select the SDK explicitly for migrated consumers. Do not fall back to the CLI after an SDK failure.
- Retain the CLI implementation until a later closure slice proves that no supported consumer needs it.
## Capability slices
### Slice 1: Managed sandbox inventory and readiness
- Use the SDK observer for in-scope inventory, lookup, and readiness consumers.
- Run the shared behavior contract against the CLI and SDK implementations.
- Preserve the existing readiness deadline, transient `Error` debounce, stable-ready checks, identity proof, traces, and diagnostics.
### Slice 2: Post-destroy absence reconciliation
- Use SDK observation to confirm sandbox absence after an accepted or ambiguous destroy result.
- Keep bounded polling and cleanup decisions in the existing action owner.
- Preserve the gateway, sandbox registry, provider state, and recovery authority when absence cannot be proved.
## Acceptance evidence
- `Ready`, non-ready, terminal, missing, timeout, authentication, schema, and transport results match the Phase 1 contract.
- The observer sends requests only to the named gateway and workspace.
- Missing or invalid gateway state, TLS material, authentication, or SDK responses fail with typed and redacted results.
- SDK failures never invoke the CLI.
- A transient read failure retries only within the existing read-only action deadline.
- Confirmed post-destroy absence permits cleanup. Persistent presence or inconclusive observation preserves managed state.
- Contributor, CI, release, and installed-product environments load SDK `0.0.116` through the artifact delivered by PR #11921.
- Focused live evidence uses the supported OpenShell gateway and SDK version.
## Test plan
- Convert the existing CLI inventory fixtures into a shared CLI and SDK observer contract.
- Add SDK adapter tests for gateway targeting, workspace selection, mTLS loading, request mapping, cancellation, response validation, error mapping, and redaction.
- Run the existing readiness action tests against the SDK observer.
- Extend destroy reconciliation and gateway-cleanup tests for confirmed absence, persistent presence, another live sandbox, timeout, authentication failure, schema failure, and transport loss.
- Run CLI type checking and the affected CLI, integration, and package-contract suites.
- Run focused live inventory, readiness, and post-destroy evidence against OpenShell `0.0.116`.
## Security and failure behavior
- Resolve the named gateway to its managed loopback port. Ignore ambient gateway selectors.
- Validate the managed state directory before reading `tls/ca.crt`, `tls/client/tls.crt`, and `tls/client/tls.key`.
- Read bounded regular TLS files without following links. Keep their contents inside the SDK connection owner.
- Stop before an RPC when the gateway target, state directory, or TLS material is invalid.
- Do not include credentials, SDK messages, request data, or internal paths in consumer errors or logs.
- Abort in-flight reads when the action deadline expires.
- Treat transport loss after destroy as inconclusive. Do not authorize gateway or registry cleanup without confirmed absence.
## Dependencies and sequencing
- Blocked by Phase 1 closure issue #9813.
- PR #11921 must merge or be superseded before the SDK becomes the selected installed-product backend.
- Resolve draft PR #11909 before implementation because it changes lifecycle and observer ownership.
- Slice 2 follows the final post-destroy cleanup contract from PR #11614.
- Slice 1 can merge independently of Slice 2 after its blockers resolve.
## Deferred scope
- External gateway inventory through OIDC or edge tokens.
- Sandbox mutations and command execution.
- Generated clients for OpenShell services omitted from the SDK.
- Migration of the destroy mutation itself.
- Deletion of the CLI observer.
- Selection of any OpenShell release other than `0.0.116`.
## Stop conditions
`Ready to implement: no`.
Record `Accept`, close the Phase 1 dispositions in #9813, resolve PR #11909, and complete SDK delivery through PR #11921 before implementation. Re-plan if the supported OpenShell release or observer ownership changes.
Contributor guide
Assessment
This issue has not been assessed yet.