Skip to content
6 changes: 3 additions & 3 deletions .agents/skills/verify-sandbox-asleep/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,14 +31,14 @@ one TLC worker, so a failure always prints the shortest trace. A pass takes abou

## Coverage record

Synced with commit `623b52bf4`. Paths are under `packages/trpc/src/`.
Synced with commit `183e91e8`. Paths are under `packages/trpc/src/`.

| Action | Code |
| --- | --- |
| `ProvisionDone` | `provisionCloudWorkspace` in `router/cloud-workspace/provision.ts`: `provisionSandbox`, the transition to `awake`, then `recordSandboxAwake` |
| `WakeResume` / `WakeRecord` | `wakeCloudWorkspace` in `router/cloud-workspace/wake.ts`: `wakeSandbox` in `lib/sandbox/vercel.ts`, then `recordSandboxAwake` in `router/cloud-workspace/sandbox-expiry.ts` |
| `WakeResume` / `WakeRecord` | `wakeCloudWorkspace` in `router/cloud-workspace/wake.ts`: `wakeSandbox` in `lib/sandbox/vercel.ts`, then `recordSandboxAwake` in `router/cloud-workspace/sandbox-expiry.ts`. A wake that read the box running and resumed it after a timeout stop is the same `WakeResume`: the box was stopped when the call resumed it |
| `TopUpExtend` / `TopUpRecord` | `sandbox.keepalive` in `router/sandbox/sandbox.ts`: `topUpSandboxSession`, then `recordSandboxAwake` |
| `StopBox` / `StopRecord` | `stopAndSnapshot` or `stopSandbox`, then `recordSandboxAsleep` in `router/cloud-workspace/sandbox-sleep.ts`, from `cloudWorkspace.sleep` (`cloud-workspace.ts`), `restartCloudWorkspace` (`wake.ts`), and the spend-cap stops in `meter.ts` (`settleBoot`, `settleOrganizationNow`, the refused adopt in `adoptRunningBoxes`) |
| `StopBox` / `StopRecord` | `stopAndSnapshot` or `stopSandbox`, then `recordSandboxAsleep` in `router/cloud-workspace/sandbox-sleep.ts`, from `cloudWorkspace.sleep` (`cloud-workspace.ts`), `restartCloudWorkspace` and `wakeAfterStop` (`wake.ts`; `environment.promote` calls `wakeAfterStop` after the snapshot in `promoteSandboxToEnvironment` stopped the source, so `StopBox` there is the snapshot), a refused `wakeCloudWorkspace` whose own call resumed the box (it records that session awake first, a `WakeRecord`, then stops it; a refusal for a box another wake resumed stops nothing), and the spend-cap stops in `meter.ts` (`settleBoot`, `settleOrganizationNow`, the refused adopt in `adoptRunningBoxes`) |
| `WatchFire` | `watchSandboxExpiry` in `sandbox-expiry.ts`, queued by `queueWatch` through `publishCloudWorkspaceJob` (`jobs.ts`), served by `apps/api/src/app/api/cloud-workspaces/sandbox-expiry/route.ts` |
| `ReconcileList` / `ReconcileApply` | `reconcileCloudWorkspaces` in `sandbox-expiry.ts`: `listActiveWorkspaceSandboxes`, then `syncSandboxExpiries` against each listing's `currentSessionId` |
| `Archive` | `cloudWorkspace.delete` in `cloud-workspace.ts`: the transition to `archived`, then `queueReap` |
Expand Down
2 changes: 2 additions & 0 deletions docs/cloud-sandbox-considerations.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ schedule (`/api/cloud-workspaces/jobs/reconcile-usage`, every 30 minutes, set
in the Upstash console and watched by a Sentry cron monitor) finalizes each
running box's memory GB-minutes and takes the next lock; a box whose next lock
is refused is stopped. Stopping, archiving or deleting a box settles the rest.
The same run opens a boot for any session from the last hour that has none
(`adoptRunningBoxes` in `meter.ts`), billed from the session's start.
Environment builds are not billed. Prices and limits live in Autumn, not here.
Each paid seat adds its plan's GB-minutes to one team pool through Autumn
seat licenses; see [Seats and cloud hours in Autumn](autumn-seat-licenses.md).
Expand Down
23 changes: 20 additions & 3 deletions docs/cloud-sandbox-mismatches.md
Original file line number Diff line number Diff line change
Expand Up @@ -776,9 +776,26 @@ obvious tidy-up once the golden exists — leaves the workspace unable to ever
resume (`410 Cannot resume sandbox: no snapshot available`), which is how one
e2e workspace died. So the snapshot stays (`keepLastSnapshots` evicts it on
the source's next stop), and a source that was running is started again
before promote returns. A row whose sandbox is gone or unresumable is marked
`failed` by the next `access`, so it gets the failed screen and a Remove
button rather than a sidebar entry that never opens.
before promote returns, through `wakeAfterStop`: the new session is a wake,
authorized and metered like any other. Until 2026-11 the restart ran the boot
command directly, and 69 sessions in a week ran with no boot row. A row whose
sandbox is gone or unresumable is marked `failed` by the next `access`, so it
gets the failed screen and a Remove button rather than a sidebar entry that
never opens.

**Any call on a `Sandbox` object resumes a stopped session.** The SDK wraps
`runCommand`, `writeFiles`, `extendTimeout` and the rest in `withResume`: on a
"stopped" answer it resumes and retries. A box read `running` that hits its
timeout a moment later is resumed by the next call on that object, and no
code chose to start it. Measured: 9 sessions in a week started 0.8–1.5 s after
a timeout stop. `wakeSandbox` passes `onResume` to `Sandbox.get` and runs
`beforeResume` (which authorizes the boot) for such a session; a refused one is
stopped at once. A top-up goes through the session, which never resumes.
Other callers on a box read `running` are covered only by the reconcile, which
adopts any session that has no boot row within one run: promote's
`source.snapshot()` (wrapped in `withResume`), and `applySandboxPolicy`, whose
`update` does not resume in SDK 4.0.0 but would if a later SDK wrapped it.
`provisionSandbox` on a box it already made is covered by its own boot.

**`stop()` returns before the stop's snapshot is current.** The sandbox is
still `stopping` when the call resolves, and a fork taken then boots from
Expand Down
7 changes: 4 additions & 3 deletions packages/trpc/src/lib/sandbox/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,10 @@ Two habits that pay for themselves here:
a fix that only exists on your machine.
- **The claim is the whole handoff.** `buildSandboxClaim` assembles what a box
needs to be one workspace — the identity file, the firewall rules, the
managed environment, the host secret — and `provisionSandbox`, `wakeSandbox`
and `promoteSandboxToEnvironment` all take it, so a create, a wake and a
restart after promote hand the box the same thing.
managed environment, the host secret — and `provisionSandbox` and
`wakeSandbox` take it. A restart after promote is a wake (`wakeAfterStop`),
so a create, a wake and that restart hand the box the same thing, and each
new session gets a boot row.

`docs/cloud-sandbox-considerations.md` is the companion list: what we still owe
before a non-internal user can create a sandbox. Several entries there are only
Expand Down
1 change: 1 addition & 0 deletions packages/trpc/src/lib/sandbox/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ export {
findSandboxSession,
HOST_SERVICE_PORT,
listActiveWorkspaceSandboxes,
listSandboxSessions,
MEMORY_MB_PER_VCPU,
promoteSandboxToEnvironment,
provisionSandbox,
Expand Down
164 changes: 164 additions & 0 deletions packages/trpc/src/lib/sandbox/vercel.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ import {
agentToolsMounts,
findSandboxSession,
listActiveWorkspaceSandboxes,
listSandboxSessions,
promoteSandboxToEnvironment,
type SandboxClaim,
SESSION_TIMEOUT_MS,
topUpSandboxSession,
Expand Down Expand Up @@ -116,6 +118,168 @@ describe("findSandboxSession", () => {
});
});

describe("listSandboxSessions", () => {
const raw = (id: string, startedAt: number, stoppedAt?: number) => ({
id,
memory: 8192,
vcpus: 4,
status: stoppedAt === undefined ? "running" : "stopped",
startedAt,
...(stoppedAt === undefined ? {} : { stoppedAt }),
updatedAt: stoppedAt ?? startedAt,
});
let read = 0;
stub(Sandbox, {
get: async () => ({
listSessions: async () =>
(async function* () {
for (const session of [
raw("live", NOW - 10 * 60_000),
raw("recent", NOW - 50 * 60_000, NOW - 20 * 60_000),
raw("old", NOW - 3 * HOUR, NOW - 2 * HOUR),
raw("older", NOW - 5 * HOUR, NOW - 4 * HOUR),
]) {
read += 1;
yield session;
}
})(),
}),
});

test("lists the live session and those ended since, and reads no further back", async () => {
const sessions = await listSandboxSessions("ws-box", NOW - HOUR);
expect(sessions?.map((session) => session.id)).toEqual(["live", "recent"]);
expect(read).toBe(3);
});
});

describe("promoteSandboxToEnvironment", () => {
const sourceCalls: string[] = [];
const source = {
status: "running",
region: "iad1",
vcpus: 4,
currentSession: () => ({ sessionId: "sess_A" }),
snapshot: async () => {
sourceCalls.push("snapshot");
return { snapshotId: "snap_1" };
},
writeFiles: async () => {
sourceCalls.push("writeFiles");
},
runCommand: async () => {
sourceCalls.push("runCommand");
},
mkDir: async () => {
sourceCalls.push("mkDir");
},
};
const golden = {
currentSnapshotId: "snap_golden_0",
runCommand: async () => {},
stop: async () => {},
};
let createTags: unknown;
stub(Sandbox, {
get: async ({ name }: { name: string }) =>
name === "ws-box"
? source
: { status: "stopped", currentSnapshotId: "snap_golden_1" },
create: async (params: { tags: unknown }) => {
createTags = params.tags;
return golden;
},
});

test("ends the source's session for the snapshot and leaves its restart to the caller", async () => {
expect(
await promoteSandboxToEnvironment({
sourceSandbox: "ws-box",
goldenName: "env-1",
organizationId: "org_1",
}),
).toEqual({
goldenName: "env-1",
region: "iad1",
stopped: { sessionId: "sess_A" },
});
expect(sourceCalls).toEqual(["snapshot"]);
expect(createTags).toEqual({ kind: "environment", org: "org_1" });
});
});

describe("wakeSandbox", () => {
type Box = { memoryMb: number; vcpus: number };
let running: boolean;
let onResume: (sandbox: unknown) => Promise<void>;
const box = {
get status() {
return running ? "running" : "stopped";
},
expiresAt: new Date(NOW + 60_000),
vcpus: 4,
domain: () => "https://box.test",
currentSession: () => ({ vcpus: 8, sessionId: "sess_new" }),
update: async () => {},
writeFiles: async () => {},
// The SDK's withResume: a call on a stopped session resumes it, then retries.
extendTimeout: async () => {
await onResume(box);
},
runCommand: async () => {
await onResume(box);
throw new Error("stop before settle");
},
};
stub(Sandbox, {
get: async (params: { onResume: typeof onResume }) => {
onResume = params.onResume;
return box;
},
});
stub(globalThis, { fetch: async () => new Response("{}") });
const identity = {
SUPERSET_SANDBOX_CONTRACT: "1",
SUPERSET_API_URL: "https://api.test",
SUPERSET_SANDBOX_WORKSPACE_ID: "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
SUPERSET_SANDBOX_ORGANIZATION_ID: "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
SUPERSET_SANDBOX_REPOSITORIES: "[]",
SUPERSET_SANDBOX_IMAGE_TAG: "image",
SUPERSET_SANDBOX_PROVIDER: "vercel",
SUPERSET_BUNDLE_SHA: "a".repeat(64),
};
async function wake(): Promise<Box[]> {
const authorized: Box[] = [];
await wakeSandbox({
providerSandboxId: "ws-box",
claim: { vcpus: 4, identity, networkPolicy: {} } as never,
beforeResume: async (resumed) => {
authorized.push(resumed);
if (running) throw new Error("stop before settle");
},
}).catch((error: Error) => {
if (error.message !== "stop before settle") throw error;
});
return authorized;
}

test("a box read running that a call resumed runs beforeResume for the new session", async () => {
running = true;
expect(await wake()).toEqual([
{
memoryMb: 16_384,
vcpus: 8,
resumedSession: { sessionId: "sess_new", expiresAt: box.expiresAt },
},
]);
});

test("a box read stopped runs beforeResume once, before its own resume", async () => {
running = false;
expect(await wake()).toEqual([{ memoryMb: 8192, vcpus: 4 }]);
});
});

describe("listActiveWorkspaceSandboxes", () => {
test("finds older resumed workspaces when tag-filtered lists use creation order", async () => {
expect(await listActiveWorkspaceSandboxes(NOW - 4 * HOUR)).toEqual([
Expand Down
Loading
Loading