apache / apache/maka

feat(cloud): build the Cloud Agent runtime on ephemeral sandboxes

Open
#1,286 15 comments 0 reactions 2 assignees Assigned to @MicroGery View on GitHub
enhancement
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

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.