@agent-compose/sdk 0.6.0 → 0.8.0

package/src/sandbox/providers/vercel.ts

@@ -0,0 +1,331 @@
+/**
+ * Vercel sandbox provider (@vercel/sandbox 2.x) — tag building, the provider
+ * wrapper, and the "vercel" registry entry.
+ *
+ * CRITICAL: every VALUE import of @vercel/sandbox in this file is dynamic
+ * (`await import(...)`) so the package stays out of runner.bundle.js — the
+ * runner never calls these paths. Top-level imports are type-only (erased).
+ */
+
+import pRetry from "p-retry";
+import { SandboxUnavailableError } from "../../sandbox-errors.js";
+import type { SandboxProvider } from "../../types/sandbox.js";
+import { toVercelNetworkPolicy } from "../network-policy.js";
+import { SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE } from "../sizes.js";
+import { AGENT_COMPOSE_TAG } from "../provider-def.js";
+import type { OwnedSandbox, SandboxProviderDef } from "../provider-def.js";
+// Type-only — erased at compile time, so @vercel/sandbox stays out of
+// runner.bundle.js (the value imports below are dynamic for the same reason).
+import type { Sandbox as VercelSandbox, Command as VercelCommand } from "@vercel/sandbox";
+
+/** Upper bound for how old a live Vercel sandbox can be: Pro/Enterprise plan
+ *  cap (5h) + 1h slack for clock skew and `extendTimeout()` calls. */
+const VERCEL_VM_LIFETIME_WINDOW_MS = 6 * 60 * 60 * 1000;
+
+/** Vercel caps sandbox tags at 5. Build the tag set with the fleet `executor`
+ *  tag always present and always winning over caller metadata — `listOwned` /
+ *  orphan reconciliation scope on it, so a clobbered or dropped executor tag
+ *  makes the sandbox invisible to cleanup. When metadata overflows the cap,
+ *  keep executor + the lexicographically-first 4 metadata keys, so what gets
+ *  dropped is deterministic rather than dependent on object insertion order. */
+export const VERCEL_MAX_TAGS = 5;
+export function buildVercelTags(metadata: Record<string, string>): Record<string, string> {
+  const tags: Record<string, string> = { ...metadata, executor: AGENT_COMPOSE_TAG };
+  const extras = Object.keys(tags).filter((k) => k !== "executor").sort();
+  for (const key of extras.slice(VERCEL_MAX_TAGS - 1)) delete tags[key];
+  return tags;
+}
+
+function makeVercelSandboxProvider(sb: VercelSandbox, globalEnvs?: Record<string, string>): SandboxProvider {
+  // Vercel's Sandbox.create({ env }) does NOT flow to runCommand subprocesses — they start fresh shells.
+  // Capture the sandbox-level envs and merge them into every runCommand call so that env vars like
+  // ANTHROPIC_API_KEY (placeholder for network policy injection) are actually visible to subprocesses.
+  const mergeEnvs = (cmdEnvs?: Record<string, string>) =>
+    globalEnvs ? { ...globalEnvs, ...cmdEnvs } : cmdEnvs;
+
+  // Wrap a sandbox-side failure as `SandboxUnavailableError`. `retryable` is
+  // decided purely by *where* the error was caught, not by inspecting its
+  // shape: true before the runner launched any user code (file write / command
+  // launch / reconnect — safe to re-provision and retry), false once the
+  // runner streamed (user code may have run). The original message is
+  // preserved for server-side diagnostics.
+  const asUnavailable = (err: unknown, retryable: boolean): never => {
+    throw new SandboxUnavailableError(err instanceof Error ? err.message : String(err), { retryable, sandboxId: sb.name });
+  };
+
+  return {
+    // @vercel/sandbox 2.x is name-keyed: `name` is the stable identifier
+    // (`Sandbox.get({ name })`); the v1 `sandboxId` getter is gone. Our
+    // provider-facing field keeps its name — it's "the provider-native id".
+    sandboxId: sb.name,
+    commands: {
+      async run(cmd, opts) {
+        const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
+        let stdout = "";
+        let stderr = "";
+        // `sudo: true` is Vercel's native root flag — applied to the `sh`
+        // invocation so the whole shell (and its children) runs as root.
+        // A launch failure means the command never started — nothing
+        // user-side ran, so any error here is safe to re-provision + retry.
+        const handle: VercelCommand = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...(opts?.sudo ? { sudo: true } : {}) })
+          .catch((err: unknown) => asUnavailable(err, true));
+        // Stream + wait, BOTH inside the same reconnect loop. Reconnect to the
+        // already-running command on transient stream failures (e.g.
+        // BrotliDecompressionError). `h.logs()` replays from the start on
+        // reconnect, so dedupe by byte offset: `stdout` / `stderr` hold
+        // everything already delivered to the caller — skip the replayed
+        // prefix and append/emit only the genuinely-new suffix. The caller's
+        // sinks must see each byte EXACTLY once: the step-recovery log
+        // backfill slices the tee'd log file at the delivered-chars offset,
+        // so a replayed re-emit would inflate that offset past the file
+        // length and silently drop the undelivered tail.
+        //
+        // `wait()` MUST live inside this same retry, not after it. Vercel's
+        // log stream can close independently of the command actually
+        // exiting — observed live as every long-running Vercel step in the
+        // fleet dying at ~20-26 minutes with a generic "operation timed
+        // out" on `wait()`, never on `logs()`. A `wait()` fault is the same
+        // transport-fault class as a `logs()` fault: the command is
+        // `detached: true` and therefore still running on a lone `wait()`
+        // hiccup, so it must reconnect and retry too instead of failing the
+        // whole (possibly multi-hour) step non-retryably on one bad call.
+        const collect = async () => {
+          const finished = await pRetry(async (attempt) => {
+            const h = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
+            // Chars of this attempt's (replayed-from-start) stream seen so far,
+            // per stream. New bytes are whatever extends past the delivered
+            // accumulator; replay chunk boundaries need not match the original's.
+            let seenOut = 0;
+            let seenErr = 0;
+            const fresh = (data: string, seen: number, delivered: number): string => {
+              const skip = Math.min(Math.max(delivered - seen, 0), data.length);
+              return skip > 0 ? data.slice(skip) : data;
+            };
+            for await (const log of h.logs()) {
+              if (log.stream === "stdout") {
+                const add = fresh(log.data, seenOut, stdout.length);
+                seenOut += log.data.length;
+                if (add) { stdout += add; opts?.onStdout?.(add); }
+              } else {
+                const add = fresh(log.data, seenErr, stderr.length);
+                seenErr += log.data.length;
+                if (add) { stderr += add; opts?.onStderr?.(add); }
+              }
+            }
+            return await h.wait();
+          }, { retries: 3, minTimeout: 1_000, factor: 2 });
+          return { exitCode: finished.exitCode, stdout, stderr };
+        };
+        // `timeoutMs` MUST be authoritative. The AbortSignal alone is not: a
+        // command that RUNS but emits nothing (e.g. a wedged `archil checkout`
+        // on a blocked data plane) leaves `logs()`/`wait()` pending and the
+        // abort never interrupts the await — the call hangs for the activity's
+        // whole multi-hour ceiling. Race a hard client-side deadline so a hung
+        // command fails fast and the caller's degrade/retry policy takes over.
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const deadline = opts?.timeoutMs
+          ? new Promise<never>((_, reject) => {
+              timer = setTimeout(
+                () => reject(new Error(`command timed out after ${opts.timeoutMs}ms: ${cmd.slice(0, 200)}`)),
+                opts.timeoutMs);
+            })
+          : undefined;
+        try {
+          return await (deadline ? Promise.race([collect(), deadline]) : collect());
+        } catch (err) {
+          // A timeout (hard deadline or AbortSignal) is a COMMAND overrunning
+          // its budget, not the sandbox dying — the VM is alive. Surface it as
+          // a plain error so the caller's own retry/deadline policy decides
+          // (classifying it as terminal sandbox-unavailable failed whole runs
+          // over a single slow mount probe, observed live).
+          if (err instanceof Error && err.message.startsWith("command timed out after")) throw err;
+          if (signal?.aborted) throw new Error(`command timed out after ${opts?.timeoutMs}ms: ${cmd.slice(0, 200)}`);
+          return asUnavailable(err, false);
+        } finally {
+          if (timer) clearTimeout(timer);
+        }
+      },
+    },
+    files: {
+      async write(path: string, content: string) {
+        // File writes happen before the runner launches (step input / pause
+        // resolution files), so a failure here means nothing ran — retryable.
+        await sb.writeFiles([{ path, content }]).catch((err: unknown) => asUnavailable(err, true));
+      },
+      // Read over Vercel's HTTP file API — a DIFFERENT transport from the
+      // runCommand log stream, so a readback works after a stream/wait fault
+      // (the property the foreground recovery's log backfill relies on).
+      // No `asUnavailable` wrap: `read` is consumed only by the best-effort
+      // recovery backfill — classifying a missing log file as sandbox death
+      // would be wrong.
+      async read(path: string): Promise<string> {
+        const buf: Buffer | null = await sb.readFileToBuffer({ path });
+        if (buf === null) throw new Error(`file not found: ${path}`);
+        return buf.toString("utf8");
+      },
+    },
+    // Propagate errors — `killAllRunSandboxes` relies on kill failures being
+    // observable so it can leave `sandbox_id` set for `findOrphanedSandboxes`
+    // to retry on next boot. Swallowing here makes the orphan retry loop blind.
+    //
+    // kill must DESTROY: in @vercel/sandbox 2.x stop() only halts the VM — the
+    // name-keyed sandbox record persists (reserving the name; commands against
+    // a stale handle can transparently resume a stopped VM). delete() is the
+    // destroying call ("after deletion the instance becomes inert"), so stop
+    // then delete.
+    async kill() { await sb.stop(); await sb.delete(); },
+    // Vercel native snapshot — used by sandbox-environments to capture the
+    // configured VM after the customer's `setup()` completes. `expiration: 0`
+    // is Vercel's "never expires" value; env snapshots are long-lived by
+    // design (they ARE the env) so we always pass it.
+    async snapshot() {
+      const res = await sb.snapshot({ expiration: 0 });
+      // `sizeBytes` is typed non-optional but populated by the API — keep the
+      // runtime guard so a missing field degrades to "unknown size", not NaN.
+      const sizeBytes = typeof res.sizeBytes === "number" ? res.sizeBytes : undefined;
+      return {
+        snapshotId: res.snapshotId,
+        ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+      };
+    },
+    // Push a freshly-resolved egress policy onto the live sandbox —
+    // @vercel/sandbox 2.x `update({ networkPolicy })`. Lets the server
+    // re-resolve the run policy (re-minting connector access tokens)
+    // before each step instead of living with the policy baked at create.
+    // E2B implements the same seam via `sb.updateNetwork(toE2bNetwork(...))`.
+    async updateNetworkPolicy(policy) {
+      await sb.update({ networkPolicy: toVercelNetworkPolicy(policy) });
+    },
+  };
+}
+
+async function listOwned(env: Record<string, string>): Promise<OwnedSandbox[]> {
+  const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
+  const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+  // Scoped to our fleet by the `executor` tag (stamped at create) and
+  // bounded to `VERCEL_VM_LIFETIME_WINDOW_MS` — Pro/Enterprise caps VM
+  // lifetime at 5h, +1h slack for clock skew and `extendTimeout()`. The
+  // sort is pinned to createdAt-desc explicitly — the early-stop below is
+  // only correct under that order, and the server's default sort is not a
+  // contract we can rely on — so we stop at the first item older than the
+  // window instead of paging through thousands of historical terminal
+  // sandboxes (10k+ in v0.6.28). Truncating silently would hide orphans,
+  // so we throw at the page cap instead — 200 pages × the API's 50-item
+  // limit preserves the previous 10k scan bound (v1 paged 200 × 50). Each
+  // page is wrapped in pRetry so a transient 5xx/429/network blip doesn't
+  // cost a reconcile tick.
+  //
+  // 2.x cutover caveat: sandboxes created by the pre-2.x code carry no
+  // tags, so for up to VERCEL_VM_LIFETIME_WINDOW_MS after a deploy they
+  // are invisible here (and their persisted v1 sandbox ids don't resolve
+  // via `Sandbox.get({ name })`). Self-limiting — the provider's 5h
+  // lifetime cap expires them — but drain in-flight Vercel runs before
+  // deploying if losing their sandbox state matters.
+  const since = Date.now() - VERCEL_VM_LIFETIME_WINDOW_MS;
+  const out: OwnedSandbox[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < 200; page++) {
+    const result = await pRetry(
+      // limit is capped at 50 by the v2 list API — 51+ answers 400
+      // (probed live 2026-06-10; not documented in the SDK types).
+      () => VercelSandbox.list({ ...creds, limit: 50, sortBy: "createdAt", sortOrder: "desc", tags: { executor: AGENT_COMPOSE_TAG }, ...(cursor !== undefined ? { cursor } : {}) }),
+      { retries: 3, minTimeout: 500, factor: 2 },
+    );
+    for (const sb of result.sandboxes) {
+      if (sb.createdAt < since) return out;
+      if (sb.status === "running") {
+        out.push({ sandboxId: sb.name, createdAt: new Date(sb.createdAt), metadata: sb.tags ?? {} });
+      }
+    }
+    if (result.pagination.next === null) return out;
+    cursor = result.pagination.next;
+  }
+  throw new Error("Vercel listSandboxes exceeded 200 pages (10k sandboxes) within the lifetime window — refuse to silently truncate");
+}
+
+export const vercelProviderDef: SandboxProviderDef = {
+  requiredEnv: {
+    VERCEL_ACCESS_TOKEN: "Vercel access token — vercel.com/account/tokens",
+    VERCEL_TEAM_ID:      "Vercel team ID — vercel.com/account/settings",
+    VERCEL_PROJECT_ID:   "Vercel project ID — vercel.com/[team]/[project]/settings",
+  },
+  create: async (opts, env) => {
+    // Dynamic import keeps @vercel/sandbox out of runner.bundle.js (runner never calls this path)
+    const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
+    const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+    // `template` is a snapshot id (runtime is baked in); absent → fresh node24.
+    const np = opts.networkPolicy ? { networkPolicy: toVercelNetworkPolicy(opts.networkPolicy) } : {};
+    // Caller metadata rides as Vercel tags — `listOwned` filters on the
+    // `executor` key, mirroring E2B's metadata-tag scoping. buildVercelTags
+    // guarantees executor wins over metadata and survives the 5-tag cap.
+    const tags = buildVercelTags(opts.metadata);
+    // No explicit template/bootFrom → VERCEL_DEFAULT_SNAPSHOT if set (the
+    // platform agent-env base: claude, archil, rtk, bun, agentc CLI, the
+    // SDK in /workspace/node_modules, /ac:* skills, AGENTS.md — built by
+    // .agentc/environments/agent-env.ts), else raw node24. The E2B
+    // analogue is E2B_DEFAULT_TEMPLATE (see providers/e2b.ts). Because
+    // `saveLatest`/`reuse` captures snapshot the whole filesystem, everything
+    // a run bakes on top of this base chains from it — the base tools are in
+    // every derived snapshot for free.
+    const tmpl = opts.template ?? process.env.VERCEL_DEFAULT_SNAPSHOT;
+    // Machine size → vCPUs (RAM auto-follows at 2048 MB/vCPU). Always sent
+    // explicitly so the spec is deterministic and self-documenting rather
+    // than riding Vercel's implicit default; "small" maps to that default
+    // anyway, so existing runs are unchanged.
+    const resources = { vcpus: SANDBOX_VCPUS[opts.size ?? DEFAULT_SANDBOX_SIZE] };
+    // `persistent: false` — @vercel/sandbox 2.x creates persistent-by-default
+    // sandboxes: stop() auto-snapshots (and keeps billing storage), commands
+    // transparently resume a stopped VM, and kill no longer destroys. Our
+    // sandboxes are single-run and lifecycle-managed by the engine (explicit
+    // snapshot() / kill()), so opt out in BOTH branches.
+    const sb = await VercelSandbox.create(tmpl
+      ? { source: { type: "snapshot" as const, snapshotId: tmpl }, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds }
+      : { runtime: "node24" as const, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds },
+    );
+    // Pass envs as globalEnvs so they're injected into every runCommand subprocess.
+    // (Vercel's Sandbox.create env parameter does not flow to runCommand subprocesses.)
+    return makeVercelSandboxProvider(sb, opts.envs);
+  },
+  reconnect: async (sandboxId) => {
+    const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
+    const creds = {
+      token:     process.env.VERCEL_ACCESS_TOKEN ?? "",
+      teamId:    process.env.VERCEL_TEAM_ID ?? "",
+      projectId: process.env.VERCEL_PROJECT_ID ?? "",
+    };
+    // Reconnecting happens before any user code runs, so any failure here
+    // (sandbox already stopping, API blip) is a retryable sandbox-unavailable
+    // — the workflow re-provisions a fresh one rather than failing the run.
+    // 2.x is name-keyed: the id we persisted IS the sandbox name.
+    const sb = await VercelSandbox.get({ name: sandboxId, ...creds }).catch((err: unknown) => {
+      throw new SandboxUnavailableError(err instanceof Error ? err.message : String(err), { retryable: true, sandboxId });
+    });
+    return makeVercelSandboxProvider(sb);
+  },
+  getActiveCount: async (env) => (await listOwned(env)).length,
+  listOwned,
+  deleteSnapshot: async (snapshotId, env) => {
+    const { Snapshot } = await import("@vercel/sandbox");
+    const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+    const snap = await Snapshot.get({ snapshotId, ...creds });
+    await snap.delete();
+  },
+  snapshotExists: async (snapshotId, env) => {
+    const { Snapshot } = await import("@vercel/sandbox");
+    const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+    // Metadata-only lookup (no sandbox provisioned). A clean fetch ⇒ resolves.
+    // A 404 / not-found ⇒ definitively absent (false). Anything else (auth,
+    // 5xx, network) is INDETERMINATE and must propagate — never reported as
+    // "missing", which would falsely alert on a transient blip.
+    try {
+      await Snapshot.get({ snapshotId, ...creds });
+      return true;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err ?? "");
+      const status = (err as { status?: number; statusCode?: number })?.status
+        ?? (err as { statusCode?: number })?.statusCode;
+      if (status === 404 || /\b404\b|not[\s_-]?found|no such snapshot/i.test(message)) return false;
+      throw err;
+    }
+  },
+};

package/src/sandbox/registry.ts

@@ -0,0 +1,198 @@
+/**
+ * Sandbox provider registry — creates and manages isolated execution
+ * environments across every registered provider, and owns the ONE sandbox
+ * retry policy. Providers: "vercel" (Vercel Sandbox), "e2b" (E2B),
+ * "e2b-desktop" (E2B Desktop). Each provider validates its required env vars
+ * at creation time.
+ */
+
+import { SandboxNotFoundError, RateLimitError } from "e2b";
+import pRetry from "p-retry";
+import type { FailedAttemptError } from "p-retry";
+import type { SandboxProvider } from "../types/sandbox.js";
+import type { SandboxCreateOpts, SandboxProviderDef, OwnedSandbox } from "./provider-def.js";
+import { vercelProviderDef } from "./providers/vercel.js";
+import { e2bProviderDef } from "./providers/e2b.js";
+import { e2bDesktopProviderDef } from "./providers/desktop.js";
+
+export type SandboxProviderName = "vercel" | "e2b" | "e2b-desktop";
+
+export const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
+  "vercel":      vercelProviderDef,
+  "e2b":         e2bProviderDef,
+  "e2b-desktop": e2bDesktopProviderDef,
+};
+
+/** Is this a FLEETING sandbox-provider race worth retrying — the sandbox being
+ *  paused / reclaimed / stopped under load, an upstream 5xx/429, or a dropped
+ *  connection — vs a PERMANENT failure that must fail fast?
+ *
+ *  E2B raises TYPED errors, so prefer `instanceof` (upgrade-stable — survives any
+ *  message rewording): a reconnect/snapshot that hits a sandbox mid-pause throws
+ *  `SandboxNotFoundError`, rate limits throw `RateLimitError`. (Permanent
+ *  template/snapshot-not-found only occurs on CREATE, which is no longer retried.)
+ *  The message regex is the FALLBACK for the untyped Vercel transport + raw socket
+ *  errors — and deliberately omits bare "timeout"/"network": E2B's permanent
+ *  plan-cap 400 ("timeout … exceeds the maximum sandbox lifetime") contains
+ *  "timeout" and must fail fast, not retry 4×. */
+function isTransientSandboxError(error: unknown): boolean {
+  if (error instanceof SandboxNotFoundError || error instanceof RateLimitError) return true;
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  // The 5xx match is anchored to a status-code context ("status 503",
+  // "502 Bad Gateway", …) — a bare \b5\d\d\b would classify ANY standalone
+  // 500-599 number in a message (durations, row counts) as retryable.
+  return /paus|stopp|resum|transition|status(?:\s+code)?[:\s]+5\d\d\b|\b5\d\d\s+(?:internal|bad gateway|service|gateway)|\b429\b|ECONNRESET|ECONNREFUSED|ETIMEDOUT|socket hang up|fetch failed/i
+    .test(message);
+}
+
+/** The ONE place the sandbox retry policy lives. Provisioning, reconnecting, and
+ *  snapshotting all race with the sandbox being paused/reclaimed; this runs the call
+ *  through p-retry's generic backoff, retrying ONLY the transient race (and failing
+ *  fast otherwise). reconnectSandbox and provider.snapshot() all go through it, so
+ *  no provider re-implements the pattern or can forget it. `shouldRetry` is
+ *  overridable for call sites where the default classification is wrong (see
+ *  reconnectSandbox's SandboxNotFoundError handling). */
+function withSandboxRetry<T>(
+  fn: () => Promise<T>,
+  shouldRetry: (error: FailedAttemptError) => boolean = isTransientSandboxError,
+): Promise<T> {
+  return pRetry(fn, { retries: 4, minTimeout: 400, factor: 2, shouldRetry });
+}
+
+/** Add snapshot-retry to a freshly-obtained provider. create/reconnect are retried at
+ *  the registry call (`createSandbox`/`reconnectSandbox`); snapshot is a method, so it
+ *  gets the same `withSandboxRetry` here. `commands.run` is deliberately NOT wrapped —
+ *  retrying user-code execution could double-apply side effects, so step execution
+ *  relies on the engine's pre-step sandbox recovery instead. No-op without a snapshot. */
+function withSnapshotRetry(p: SandboxProvider): SandboxProvider {
+  if (!p.snapshot) return p;
+  const snapshot = p.snapshot.bind(p);
+  return { ...p, snapshot: () => withSandboxRetry(snapshot) };
+}
+
+/** Provision a sandbox for the named provider. */
+export async function createSandbox(provider: SandboxProviderName, opts: SandboxCreateOpts): Promise<SandboxProvider> {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def) throw new Error(`Unknown sandbox provider: "${provider}". Known: ${Object.keys(SANDBOX_PROVIDERS).join(", ")}`);
+  const missing = Object.entries(def.requiredEnv)
+    .filter(([key]) => !process.env[key])
+    .map(([key, desc]) => `  ${key}  — ${desc}`);
+  if (missing.length > 0) throw new Error(`Sandbox provider "${provider}" requires env vars:\n${missing.join("\n")}`);
+  const env = Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]!]));
+  // Provision once — do NOT wrap create in withSandboxRetry: a create whose RESPONSE
+  // is lost (client-side timeout after the provider already provisioned) would, on
+  // retry, mint a SECOND billed sandbox and orphan the first. Provision failures are
+  // re-attempted at the workflow layer. The result is still wrapped so snapshot()
+  // retries the transient pause/reclaim race (which is where the race actually lives).
+  return withSnapshotRetry(await def.create(opts, env));
+}
+
+/** Reconnect to an existing sandbox by provider + provider-native sandbox ID. */
+export async function reconnectSandbox(provider: SandboxProviderName, sandboxId: string): Promise<SandboxProvider> {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.reconnect) throw new Error(`Provider "${provider}" does not support reconnect`);
+  // Retry the transient reconnect/resume race, then add snapshot-retry to the
+  // result. On RECONNECT, SandboxNotFoundError usually means the sandbox is
+  // genuinely gone (killed / lifetime-expired) — permanent — but it can also
+  // be the transient mid-pause race, so it gets exactly ONE retry instead of
+  // burning the full 4-attempt backoff before surfacing.
+  return withSnapshotRetry(await withSandboxRetry(
+    () => def.reconnect!(sandboxId),
+    (error) => error instanceof SandboxNotFoundError ? error.attemptNumber <= 1 : isTransientSandboxError(error),
+  ));
+}
+
+/** Delete a snapshot by id on the named provider. No live sandbox needed. */
+export async function deleteSandboxSnapshot(provider: SandboxProviderName, snapshotId: string): Promise<void> {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.deleteSnapshot) throw new Error(`Provider "${provider}" does not support deleteSnapshot`);
+  const missing = Object.entries(def.requiredEnv)
+    .filter(([k]) => !process.env[k])
+    .map(([k, desc]) => `  ${k} — ${desc}`);
+  if (missing.length > 0) throw new Error(`Sandbox provider "${provider}" requires env vars:\n${missing.join("\n")}`);
+  return def.deleteSnapshot(snapshotId, Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!])));
+}
+
+/**
+ * Does `snapshotId` resolve on the named provider for this account? A cheap
+ * metadata lookup — never provisions a sandbox. `true` = resolves, `false` =
+ * provider says it does not exist. Transport/credential errors propagate (an
+ * indeterminate result is not "missing"). Used at server boot to validate the
+ * platform base snapshots the default templates boot from.
+ */
+export async function snapshotResolves(provider: SandboxProviderName, snapshotId: string): Promise<boolean> {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.snapshotExists) throw new Error(`Provider "${provider}" does not support snapshotExists`);
+  const missing = Object.entries(def.requiredEnv)
+    .filter(([k]) => !process.env[k])
+    .map(([k, desc]) => `  ${k} — ${desc}`);
+  if (missing.length > 0) throw new Error(`Sandbox provider "${provider}" requires env vars:\n${missing.join("\n")}`);
+  return def.snapshotExists(snapshotId, Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!])));
+}
+
+/**
+ * Current active-sandbox count per configured provider, for quota gauges.
+ * Skips providers whose required env isn't set or which don't implement
+ * `getActiveCount`. Errors are surfaced per-provider so one flaky provider
+ * doesn't silence the rest.
+ */
+export type SandboxQuotaResult = Partial<Record<SandboxProviderName, number | Error>>;
+
+export async function getSandboxQuotas(): Promise<SandboxQuotaResult> {
+  const out: SandboxQuotaResult = {};
+  await Promise.all(
+    (Object.entries(SANDBOX_PROVIDERS) as Array<[SandboxProviderName, SandboxProviderDef]>).map(async ([name, def]) => {
+      if (!def.getActiveCount) return;
+      if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return;
+      const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!]));
+      try { out[name] = await def.getActiveCount(env); }
+      catch (err) { out[name] = err instanceof Error ? err : new Error(String(err)); }
+    }),
+  );
+  return out;
+}
+
+/**
+ * List every alive sandbox owned by this fleet, across all configured
+ * providers — the orphan-reconciler SoT. Providers without `listOwned`
+ * or missing env are skipped. Errors propagate per-provider so one flaky
+ * provider doesn't silence the rest.
+ */
+export type OwnedSandboxResult = Partial<Record<SandboxProviderName, OwnedSandbox[] | Error>>;
+
+export async function listOwnedSandboxes(): Promise<OwnedSandboxResult> {
+  const out: OwnedSandboxResult = {};
+  await Promise.all(
+    (Object.entries(SANDBOX_PROVIDERS) as Array<[SandboxProviderName, SandboxProviderDef]>).map(async ([name, def]) => {
+      if (!def.listOwned) return;
+      if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return;
+      const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!]));
+      try { out[name] = await def.listOwned(env); }
+      catch (err) { out[name] = err instanceof Error ? err : new Error(String(err)); }
+    }),
+  );
+  return out;
+}
+
+/** Kill a sandbox by provider + native ID. Used by the orphan reconciler. */
+export async function killSandboxById(provider: SandboxProviderName, sandboxId: string): Promise<void> {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.reconnect) throw new Error(`Provider "${provider}" does not support reconnect (required for kill-by-id)`);
+  const sb = await def.reconnect(sandboxId);
+  await sb.kill();
+}
+
+/** Kill all sandboxes across all registered providers. Call at startup to clean up after crashes. */
+export async function killAllSandboxes(
+  onError?: (provider: SandboxProviderName, err: unknown) => void,
+): Promise<void> {
+  await Promise.allSettled(
+    (Object.entries(SANDBOX_PROVIDERS) as Array<[SandboxProviderName, SandboxProviderDef]>)
+      .filter(([, def]) => def.killAll)
+      .map(([name, def]) => {
+        const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k] ?? ""]));
+        if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return Promise.resolve();
+        return def.killAll!(env).catch(err => onError?.(name, err));
+      }),
+  );
+}

package/src/sandbox/sizes.ts

@@ -0,0 +1,95 @@
+/**
+ * Sandbox machine sizes + the E2B template aliases derived from them.
+ *
+ * A coarse hardware knob that maps to provider machine specs at create time:
+ * Vercel honours it natively via `resources.vcpus`; E2B sizing is baked into
+ * the template, so on E2B a size resolves to a pre-built per-size template.
+ */
+
+/** Sandbox hardware SKU. Named for the actual machine spec (vCPU + RAM) rather
+ *  than abstract t-shirt sizes. Memory is always 2048 MB per vCPU:
+ *    2vcpu-4gb   =  2 vCPU /  4 GiB  (Vercel's own default machine)
+ *    4vcpu-8gb   =  4 vCPU /  8 GiB
+ *    8vcpu-16gb  =  8 vCPU / 16 GiB  (per-sandbox ceiling on STANDARD accounts —
+ *                                     probed live: 16 & 32 vCPU 400 on dev)
+ *    32vcpu-64gb = 32 vCPU / 64 GiB  (ENTERPRISE ONLY — standard accounts reject >8 vCPU) */
+export type SandboxSize = "2vcpu-4gb" | "4vcpu-8gb" | "8vcpu-16gb" | "32vcpu-64gb";
+
+/** SKU → Vercel vCPU count (RAM follows at 2048 MB/vCPU). */
+export const SANDBOX_VCPUS: Record<SandboxSize, number> = {
+  "2vcpu-4gb":    2,
+  "4vcpu-8gb":    4,
+  "8vcpu-16gb":   8,
+  "32vcpu-64gb": 32,
+};
+
+/** SDK fallback size when neither the caller nor the deployment specifies one.
+ *  Deliberately conservative — the OPERATIONAL default is the server's
+ *  `SANDBOX_DEFAULT_SIZE` env var (now also `2vcpu-4gb`). Keeping the default
+ *  small matters because Vercel rate-limits creation by vCPUs-per-window
+ *  (`api-sandboxes-vcpus-creation`); a large default 429s bursty/simultaneous
+ *  creates. Workloads that need more RAM/CPU declare `resources.size` on the
+ *  workflow rather than inflating the default for everyone. */
+export const DEFAULT_SANDBOX_SIZE: SandboxSize = "2vcpu-4gb";
+
+/** The E2B sizes we pre-build a template for. E2B sizing is template-baked
+ *  (no per-create cpu/mem knob), so honouring `resources.size` on E2B means
+ *  ONE pre-built template per size. `32vcpu-64gb` is absent (E2B has no
+ *  >8-vCPU equivalent). `8vcpu-16gb` is also absent: it needs 16 GiB RAM, but
+ *  the E2B account caps memory at 8 GiB (`Template.build` 400s with
+ *  "Memory can't be higher than 8192 MiB"). Add it back here (and rebuild the
+ *  templates) only once the account's memory limit is raised. The register/
+ *  invoke guards reject an unsupported E2B size before it can reach here. */
+export const E2B_TEMPLATE_SIZES: readonly SandboxSize[] = [
+  "2vcpu-4gb",
+  "4vcpu-8gb",
+];
+
+/** Is `size` one E2B can be built/booted at? `32vcpu-64gb` (no >8-vCPU E2B
+ *  equivalent) and `8vcpu-16gb` (exceeds the account's 8 GiB memory cap) are
+ *  not — the guards lean on this so the "no E2B equivalent" decision lives in
+ *  exactly one place. */
+export function isE2bSupportedSize(size: SandboxSize): boolean {
+  return E2B_TEMPLATE_SIZES.includes(size);
+}
+
+/** Machine spec for a SandboxSize, in the shape `Template.build` wants. RAM is
+ *  always 2048 MB/vCPU, matching the size name + Vercel parity
+ *  (`SANDBOX_VCPUS` × 2048). Used by `infra/e2b-template/build.ts` to stamp the
+ *  per-size base + agent-env templates. */
+export function e2bMachineSpec(size: SandboxSize): { cpuCount: number; memoryMB: number } {
+  const cpuCount = SANDBOX_VCPUS[size];
+  return { cpuCount, memoryMB: cpuCount * 2048 };
+}
+
+/** Stable E2B template ALIAS for the platform base at a given size
+ *  (`agent-compose-base-<size>`). Aliases — not snapshot ids — so the refs are
+ *  multi-account-clean: the same string resolves in any E2B account that built
+ *  the templates. Built by `infra/e2b-template/build.ts`; the E2B provider
+ *  boots this when a run on E2B declares no explicit `bootFrom`/template. */
+export function e2bBaseTemplate(size: SandboxSize): string {
+  return `agent-compose-base-${size}`;
+}
+
+/** Stable E2B template ALIAS for the agent runtime (base + claude binary) at a
+ *  given size (`agent-env-<size>`). The agent default templates boot from this
+ *  via `bootFrom: { snapshotId: e2bAgentEnvTemplate(size) }`. Multi-account-clean
+ *  for the same reason as `e2bBaseTemplate`. */
+export function e2bAgentEnvTemplate(size: SandboxSize): string {
+  return `agent-env-${size}`;
+}
+
+/** Is `id` one of the platform-managed E2B template aliases — a
+ *  `agent-compose-base-<size>` or `agent-env-<size>` for a supported size?
+ *
+ *  These are stable, platform-built, multi-account-clean strings (NOT tenant
+ *  captures), so any workflow may boot from them: the same alias resolves to
+ *  the same platform base in every account, and there is no tenant data behind
+ *  it to leak. The dispatch snapshot gate uses this to vouch a platform E2B
+ *  boot alias without it having to be a team-owned capture or a published
+ *  template's bootFrom. */
+export function isPlatformE2bTemplateAlias(id: string): boolean {
+  return E2B_TEMPLATE_SIZES.some(
+    (size) => id === e2bBaseTemplate(size) || id === e2bAgentEnvTemplate(size),
+  );
+}