NVIDIA / NVIDIA/NemoClaw

Phase 1 slice 3: Route sandbox create and delete through the OpenShell adapter

Open
#9,811 1 comment 0 reactions 1 assignee Claimed by @rsliter View on GitHub
area: cli area: onboarding integration: openclaw
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

Parent Epic: #9802

## Product decision

- Decision: Accept
- Reason: Move the existing sandbox create and delete behavior behind the typed OpenShell boundary so lifecycle actions no longer depend on CLI argument, environment, process, or output details.
- Placement: Add the transport-neutral lifecycle contract and CLI implementation under `src/lib/adapters/openshell/`. Keep onboarding, destroy, rebuild, snapshot, portable runtime, and uninstall responsible for lifecycle policy, ownership, rollback, recovery, and cleanup ordering.
- Accountable maintainer and implementation owner: @rsliter
- Validation plan: Typed-fake action tests, exact CLI implementation tests, current lifecycle regression suites, repository boundary checks, and focused existing E2E only where a real process, container, or cleanup boundary is not covered locally.
- Approval recorded: 2026-09-15

## Outcome

Route every in-scope production sandbox create and delete operation in `src/lib/` through one typed asynchronous OpenShell lifecycle interface without changing supported lifecycle, rollback, recovery, timeout, or user-facing progress behavior.

## Accepted scope

- Define transport-neutral create and delete requests, results, progress, and failure classifications.
- Move CLI argument construction, environment filtering, policy input staging, capability probing, process control, output parsing, timeout handling, cancellation, and transport diagnostics into the CLI implementation.
- Migrate ordinary onboarding, GPU native and compatibility creation, managed-bootstrap creation, snapshot cloning, recreate, destroy, rebuild, rollback, failed-attempt cleanup, portable lifecycle, scoped uninstall, and authorized full-uninstall deletion.
- Require a frozen named gateway for single-sandbox mutations. Preserve selected-gateway targeting only for the accepted unscoped full-uninstall compatibility path.
- Preserve exact ownership revalidation and lifecycle locks in action code. The adapter does not authorize deletion and does not retry mutations.
- Remove direct production create and delete command construction after the final in-scope consumer migrates. Record every remaining plugin, tooling, E2E, or provider-specific occurrence as an accepted exception or follow-on owner.

## Accepted mutation semantics

- A create request contains semantic fields rather than raw CLI arguments. Managed runtimes may provide trusted execution authority but may not pass preconstructed OpenShell create arguments through onboarding.
- A zero delete command exit means the mutation was accepted, not that deletion completed. An action may declare success only after explicit absence on the frozen gateway.
- A failure before process spawn is definite. Timeout, interruption, transport loss, output-limit termination, or acknowledgement loss after spawn is ambiguous because the remote mutation may have occurred.
- Ambiguous mutation results require exact observation before retry. No automatic transport fallback or mutation retry is allowed.
- Full uninstall may preserve `sandbox delete --all` only when the operation owns the selected gateway. Partial or unverifiable bulk deletion preserves provider, gateway, and registry state for recovery.
- Raw OpenShell output remains inside the CLI implementation. Actions consume typed progress, typed failure reasons, and bounded redacted diagnostics.

## Acceptance evidence

- Successful create preserves the current image or source, policy, provider, environment, resource, GPU, driver, label, startup, gateway, readiness, and exact-identity inputs.
- Destroy, rebuild, recreate rollback, snapshot replacement, portable cleanup, failed GPU-attempt cleanup, and scoped uninstall delete only after their current ownership checks and complete only after explicit absence.
- A same-name replacement, gateway drift, ownership drift, malformed input, or reserved environment override prevents mutation.
- Create and delete timeout, cancellation, connection loss, malformed output, persistent presence, identity replacement, and cleanup failure preserve the current recovery authority and do not trigger blind retry.
- GPU compatibility fallback remains limited to one attempt and starts only after stable sandbox absence and native-container cleanup are proven.
- Provider credential values do not enter arguments, results, logs, or diagnostics. OpenShell child environment remains allowlisted, and staged policy input uses owner-only permissions with verified cleanup.

## Capability slices and order

1. Migrate owned single-sandbox deletion and its explicit-absence reconciliation: #11838.
2. Migrate all in-scope create variants, including managed-bootstrap and snapshot creation: #11830.
3. Migrate accepted bulk uninstall behavior, remove obsolete command paths, and close the production boundary inventory: #11831.

If these slices use separate pull requests, every remaining consumer must have an accepted, assigned follow-on issue before the first partial pull request merges.

## Dependencies and coordination

- Reuse the observer contract from #9803 and policy contract from #9805.
- Reconcile the final contracts and touched consumers from #11741, #11614, #11792, #11616, and #10774 before merging conflicting code.
- Stop and re-plan if those changes alter gateway authority, lifecycle ownership, credential custody, timeout behavior, or the accepted consumer set.

## Deferred scope

- Plugin lifecycle migration and reviewed production-boundary exceptions: #9813.
- SDK and gRPC lifecycle implementations: #9826.
- New create options, lifecycle behavior, retry policy, timeout policy, progress wording, resource fields, or local image-build semantics.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.