feat(cloud): build the Cloud Agent runtime on ephemeral sandboxes
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
## Outcome
Build the Cloud Agent runtime on ephemeral sandboxes while preserving durable Cloud Session continuity.
Each turn follows this lifecycle:
`checkout → create fresh sandbox → hydrate → run one Activation → pack → CAS commit → publish reply → destroy sandbox`
A Cloud Session is the stable resource. Sandboxes are replaceable execution environments, while a Workspace is portable durable content identified independently from local paths and sandbox IDs.
## MVP acceptance
1. Run a Cloud Session turn in a fresh sandbox hydrated from its latest checkpoint.
2. Commit the turn before publishing its reply.
3. Destroy the sandbox and continue the same Cloud Session in another fresh sandbox.
4. Fork a committed checkpoint into a new Cloud Session and verify source/fork divergence.
5. Cover the full journey with a deterministic system test.
The implementation must also reject stale commits, avoid duplicating redelivered Activations, prevent uncommitted replies from becoming visible, and exclude secrets from Session Bundles.
## Core invariants
- The Cloud Session record owns lifecycle state, generation, active lease, and committed head.
- Workspace UUID is durable and portable; workspace paths and sandbox IDs are runtime-local.
- Session Bundles are immutable, versioned artifacts with deterministic inclusion rules.
- One Activation owns one turn and one lease epoch.
- Pack, upload, and compare-and-swap commit complete before the reply becomes visible.
- Sandbox-provider behavior stays behind the Activation runtime boundary.
## Current sub-issues
- [x] #1338 / #1349 — split application state/config roots from workspace content.
- [x] #1337 / #1369 — establish durable Workspace UUID identity.
- [ ] #1336 / #1353 — measure workspace materialization and define policy.
- [ ] #1528 — implement the Session Bundle filesystem codec.
- [ ] #1554 — define the one-shot Cloud Session activation protocol.
- [ ] #1415 — fork a Cloud Session from a committed checkpoint.
Progress: **2 of 6 completed**.
## Delivery process
### Phase 0 — completed foundations
#1338/#1349 and #1337/#1369 established the state boundary and portable Workspace identity.
### Phase 1 — flat work now
#1336/#1353, #1528, and #1554 can proceed independently from the latest `main`.
### Phase 2 — persistence contracts
After the Phase 1 contracts are settled:
- Create the quiescent snapshot issue after #1528 and the #1336 materialization decision.
- Create `SessionRepository` after #1336 defines the storage class and #1528 defines artifact/digest semantics.
### Phase 3 — execution integration
- Create the OpenSandbox runtime/image issue after #1336, #1528, and #1554.
- Create the Activation coordinator after `SessionRepository` and #1554. It can use a fake `ActivationRuntime`, so it does not need to stack on OpenSandbox.
### Phase 4 — product closure
- Start #1415 after quiescent snapshot, #1528, and `SessionRepository` are ready.
- Create the fresh-sandbox system E2E after the coordinator, OpenSandbox runtime, and #1415 are ready.
## Delivery dependency graph
```mermaid
flowchart TD
F["Completed foundations
#1338/#1349 · #1337/#1369"] --> M["Measurements and policy
#1336/#1353"]
F --> B["Bundle codec
#1528"]
F --> A["Activation protocol
#1554"]
M --> S["Quiescent snapshot
pending issue"]
B --> S
M --> R["SessionRepository
pending issue"]
B --> R
M --> O["OpenSandbox runtime + image
pending issue"]
B --> O
A --> O
R --> C["Activation coordinator
pending issue"]
A --> C
S --> K["Cloud Session fork
#1415"]
B --> K
R --> K
C --> E["Fresh-sandbox system E2E
pending issue"]
O --> E
K --> E
```
## Working rules
- Dependency arrows are merge gates, not instructions to stack branches.
- Start independently buildable and reviewable work from the latest `main`.
- Do not create dependent issues until their required contracts merge.
- Re-evaluate downstream scope after upstream work lands.
- Do not combine multiple graph nodes in one PR unless they are technically inseparable.
## Out of scope
- Persistent per-session sandboxes or PVCs.
- Mid-turn crash recovery and exactly-once external side effects.
- Arbitrary historical forks, copy-on-write optimization, and artifact garbage collection.
- Full approval-resume workflows.
- Multiple sandbox providers and warm pools.
Contributor guide
Assessment
This issue has not been assessed yet.