@agent-compose/sdk 0.8.1 → 0.8.3

package/src/runtimes/claude-code.ts

@@ -34,7 +34,7 @@
  *     token-metering gateway's Anthropic passthrough (ADR-0039).
  */
 
-import type { AgentMessage } from "../index.js";
+import type { AgentMessage, AgentMessageTaskNotification } from "../index.js";
 import { createCliAgentRuntime, shellQuote, type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 import { formatError } from "../utils/errors.js";
 
@@ -72,6 +72,140 @@ function toolResultText(content: unknown): string {
   return content == null ? "" : JSON.stringify(content) ?? "";
 }
 
+// ── Task notifications (background-task completion evidence) ────────────────
+//
+// When a background task stops — an async Agent spawn finishing, a
+// background command exiting — claude-code's completion evidence reaches
+// the stream in TWO shapes, and BOTH are mapped here (either one dropped
+// leaves transcripts believing async agents run forever — the incident
+// where spawn cards never left "launched"):
+//
+//   - `system` events with `subtype: "task_notification"` — the ONLY shape
+//     `-p --output-format stream-json` actually emits, verified live on
+//     2.1.212 (the baked E2B version) and 2.1.236, both when the task
+//     finishes MID-turn and on the idle wake (where it precedes a fresh
+//     system/init and a result stamped `origin.kind: "task-notification"`).
+//     Flat JSON: task_id / tool_use_id / status / summary, plus
+//     `usage.{total_tokens,tool_uses,duration_ms}` for agent tasks.
+//   - `<task-notification>` XML blocks as USER-role text — the form the
+//     harness injects into the model's own conversation (and the shape a
+//     resumed turn can surface as a user event). Kept as the second arm so
+//     neither transport ever depends on which side of a resume the
+//     notification lands.
+//
+// Parsed into structure; the internal plumbing either shape carries
+// (output-file paths, resume hints in <note>/<diagnostics>) is deliberately
+// not forwarded — no renderer should ever see it.
+
+const TASK_NOTIFICATION_RE = /<task-notification>([\s\S]*?)<\/task-notification>/g;
+
+const NOTIFICATION_SUMMARY_MAX = 500;
+const NOTIFICATION_REPORT_MAX = 20_000;
+
+/** First `<tag>…</tag>` inside a notification body, or null. */
+function innerTag(body: string, tag: string): string | null {
+  const m = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`).exec(body);
+  const text = m?.[1]?.trim() ?? "";
+  return text.length > 0 ? text : null;
+}
+
+/** The harness entity-escapes text it embeds into notification XML —
+ *  reverse the closed five so the report reads as the agent wrote it. */
+function unescapeEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+const clip = (s: string, max: number): string =>
+  (s.length > max ? `${s.slice(0, max - 1)}…` : s);
+
+function intTag(body: string, tag: string): number | undefined {
+  const raw = innerTag(body, tag);
+  if (!raw) return undefined;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+/** Parse every `<task-notification>` block out of one user-role text blob.
+ *  Pure and tolerant over untrusted harness text: a block without a task id
+ *  is skipped, absent fields stay absent, everything is clamped. Exported
+ *  for tests. */
+export function parseTaskNotifications(
+  text: string, timestamp: string,
+): AgentMessageTaskNotification[] {
+  if (!text.includes("<task-notification>")) return [];
+  const out: AgentMessageTaskNotification[] = [];
+  TASK_NOTIFICATION_RE.lastIndex = 0;
+  for (let m = TASK_NOTIFICATION_RE.exec(text); m !== null; m = TASK_NOTIFICATION_RE.exec(text)) {
+    const body = m[1] ?? "";
+    const taskId = innerTag(body, "task-id");
+    if (!taskId) continue;
+    const toolUseId = innerTag(body, "tool-use-id");
+    const summary = innerTag(body, "summary");
+    const report = innerTag(body, "result");
+    const usageBody = /<usage>([\s\S]*?)<\/usage>/.exec(body)?.[1] ?? "";
+    const tokens = intTag(usageBody, "subagent_tokens");
+    const toolUses = intTag(usageBody, "tool_uses");
+    const durationMs = intTag(usageBody, "duration_ms");
+    out.push({
+      type: "task_notification",
+      taskId: clip(taskId, 128),
+      ...(toolUseId ? { toolUseId: clip(toolUseId, 128) } : {}),
+      status: innerTag(body, "status") ?? "finished",
+      summary: summary ? clip(unescapeEntities(summary.replace(/\s+/g, " ")), NOTIFICATION_SUMMARY_MAX) : "",
+      ...(report ? { report: clip(unescapeEntities(report), NOTIFICATION_REPORT_MAX) } : {}),
+      ...(tokens !== undefined || toolUses !== undefined || durationMs !== undefined
+        ? { usage: {
+            ...(tokens !== undefined ? { tokens } : {}),
+            ...(toolUses !== undefined ? { toolUses } : {}),
+            ...(durationMs !== undefined ? { durationMs } : {}),
+          } }
+        : {}),
+      timestamp,
+    });
+  }
+  return out;
+}
+
+/** One `system`/`task_notification` stream-json event mapped onto the same
+ *  structured message the XML parse produces, or null when the event names
+ *  no task id. Pure and tolerant over untrusted harness JSON: absent fields
+ *  stay absent, everything is clamped; `output_file` (internal plumbing) is
+ *  deliberately not forwarded. Exported for tests. */
+export function parseSystemTaskNotification(
+  p: Record<string, unknown>, timestamp: string,
+): AgentMessageTaskNotification | null {
+  const taskId = typeof p.task_id === "string" && p.task_id.trim().length > 0 ? p.task_id.trim() : null;
+  if (!taskId) return null;
+  const toolUseId = typeof p.tool_use_id === "string" && p.tool_use_id.length > 0 ? p.tool_use_id : null;
+  const summary = typeof p.summary === "string" ? p.summary : "";
+  const nonneg = (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+  const u = (typeof p.usage === "object" && p.usage !== null ? p.usage : {}) as Record<string, unknown>;
+  const tokens = nonneg(u.total_tokens);
+  const toolUses = nonneg(u.tool_uses);
+  const durationMs = nonneg(u.duration_ms);
+  return {
+    type: "task_notification",
+    taskId: clip(taskId, 128),
+    ...(toolUseId ? { toolUseId: clip(toolUseId, 128) } : {}),
+    status: typeof p.status === "string" && p.status.length > 0 ? p.status : "finished",
+    summary: clip(summary.replace(/\s+/g, " ").trim(), NOTIFICATION_SUMMARY_MAX),
+    ...(tokens !== undefined || toolUses !== undefined || durationMs !== undefined
+      ? { usage: {
+          ...(tokens !== undefined ? { tokens } : {}),
+          ...(toolUses !== undefined ? { toolUses } : {}),
+          ...(durationMs !== undefined ? { durationMs } : {}),
+        } }
+      : {}),
+    timestamp,
+  };
+}
+
 /** Claude Code's real reasoning knob is its own `--effort <level>` flag
  *  (low|medium|high|xhigh|max — verified against `claude -p --help`). The
  *  CliReasoningEffort union IS the CLI's vocabulary, so the level rides the
@@ -100,12 +234,30 @@ export const claudeCodeSpec: CliAgentSpec = {
     'sudo cp "$REAL" /usr/local/bin/claude && sudo chmod 0755 /usr/local/bin/claude',
   // Claude reads the prompt from stdin in -p mode.
   promptPayload: (prompt) => prompt,
-  buildCommand: ({ promptPath, sessionId, model, cwd, effort }) => {
+  // Mid-turn stream input (steering): with `--input-format stream-json`,
+  // stdin carries JSONL user messages, and one that arrives WHILE a turn
+  // runs is folded into the running turn at the next tool boundary — the
+  // interactive UI's queued-user-input behaviour, verified live against
+  // claude 2.1.233 (a message injected during a 20s Bash call shaped the
+  // same turn's final reply, and the tool ran undisturbed). Slash-command
+  // expansion and `--resume` both work unchanged in this mode (verified on
+  // the same build). A message that lands after the result would start a
+  // NEW turn in-process, which is why the transport's feeder stops at the
+  // result line instead of forwarding past it.
+  streamInput: {
+    promptLine: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: prompt } }),
+    messageLine: (text) => JSON.stringify({ type: "user", message: { role: "user", content: text } }),
+  },
+  buildCommand: ({ promptPath, sessionId, model, cwd, effort, streamInput }) => {
     const flags = [
       "-p",
       // stream-json is the JSONL event stream; -p requires --verbose with it.
       "--output-format stream-json",
       "--verbose",
+      // Stream-input turns feed stdin as JSONL user messages from the
+      // transport's FIFO (mid-turn injection); plain turns keep the raw
+      // prompt file.
+      ...(streamInput ? ["--input-format stream-json"] : []),
       // Raw API stream events ride along as `stream_event` lines — the
       // text_delta source for progressive rendering (mapEvent below). The
       // complete `assistant` message events still arrive; deltas are
@@ -157,17 +309,29 @@ export const claudeCodeSpec: CliAgentSpec = {
           return [];
         });
       }
-      // User API message: the CLI echoes tool results back as user content.
+      // User API message: the CLI echoes tool results back as user content,
+      // and injects `<task-notification>` blocks (background-task completion
+      // evidence) as user TEXT — parsed into structure, never dropped and
+      // never forwarded raw. Other user text (the echo of the prompt, system
+      // reminders) stays unmapped: it is not agent output.
       case "user": {
-        const message = p.message as { content?: ClaudeContentBlock[] } | undefined;
+        const message = p.message as { content?: ClaudeContentBlock[] | string } | undefined;
+        if (typeof message?.content === "string") {
+          return parseTaskNotifications(message.content, ts);
+        }
         const blocks = Array.isArray(message?.content) ? message.content : [];
-        return blocks.flatMap((b): AgentMessage[] =>
-          b.type === "tool_result"
-            ? [{
-                type: "tool_result", toolUseId: String(b.tool_use_id ?? ""),
-                output: toolResultText(b.content), isError: b.is_error === true, ...parent, timestamp: ts,
-              }]
-            : []);
+        return blocks.flatMap((b): AgentMessage[] => {
+          if (b.type === "tool_result") {
+            return [{
+              type: "tool_result", toolUseId: String(b.tool_use_id ?? ""),
+              output: toolResultText(b.content), isError: b.is_error === true, ...parent, timestamp: ts,
+            }];
+          }
+          if (b.type === "text" && typeof b.text === "string") {
+            return parseTaskNotifications(b.text, ts);
+          }
+          return [];
+        });
       }
       // Raw API stream event (--include-partial-messages): text deltas of
       // the in-progress block map to the live-only `text_delta` kind so a
@@ -234,7 +398,18 @@ export const claudeCodeSpec: CliAgentSpec = {
           timestamp: ts,
         }];
       }
-      // system/init carries the session id (extractSessionId); nothing to map.
+      // System events: init carries the session id (extractSessionId), and
+      // the background-task lane rides here too — `task_notification` is
+      // the completion evidence stream-json actually emits (see the section
+      // header above), so it maps to the structured message BOTH turn
+      // engines persist. Everything else under system (task_started,
+      // task_updated, background_tasks_changed, thinking_tokens) is
+      // lifecycle noise here.
+      case "system": {
+        if (p.subtype !== "task_notification") return [];
+        const notification = parseSystemTaskNotification(p, ts);
+        return notification ? [notification] : [];
+      }
       default:
         return [];
     }

package/src/runtimes/codex.ts

@@ -53,6 +53,54 @@ export function isCodexAdvisoryNoise(text: string): boolean {
   return CODEX_ADVISORY_PATTERNS.some((re) => re.test(text));
 }
 
+// ── Thread-store writer-lock preflight (2026-08-18 prod incident) ────────────
+// codex guards each persisted thread with an OS advisory flock on
+// `$CODEX_HOME/thread-writer-locks/<thread-id>.lock` (codex-rs
+// thread-store/src/local/writer_lock.rs). Two consequences drive this
+// preflight's shape:
+//   - the flock is held exactly as long as the holding PROCESS lives — the
+//     kernel releases it on any death (SIGKILL, VM crash), so a lock that
+//     still blocks is held by a LIVE process, never a stale file;
+//   - codex sweeps unheld (stale) lock FILES itself on store init.
+// The incident: a canceled turn's codex survived its fire-and-forget SIGTERM
+// long enough for the user's next turn to launch `codex exec resume`, which
+// died with `thread-store conflict: thread … already has an active writer`
+// (code -32600). So before a RESUME the launch script:
+//   1. waits (bounded) for a dying previous writer to release the flock —
+//      the canceled predecessor was already TERM'd, it just needs a moment;
+//   2. clears the lock file ONLY under a successfully acquired `flock -n`
+//      (proof the holder is dead) — belt-and-suspenders on top of codex's
+//      own sweep, and the guard against any future file-existence check;
+//   3. NEVER touches a lock whose holder is alive: removing a live-held
+//      lock file would let a second writer flock a fresh inode (two writers
+//      on one rollout), so a still-held lock after the wait is left for
+//      codex to surface as the honest conflict it is.
+// No `flock(1)` on the guest (or no lock file) → the preflight is a no-op.
+
+/** Bounded wait for a dying previous writer: attempts × sleep = 5s, matching
+ *  the teardown's SIGTERM grace (sdk _cli-agent.ts REAP_TERM_WAIT_ATTEMPTS). */
+export const CODEX_LOCK_WAIT_ATTEMPTS = 20;
+export const CODEX_LOCK_WAIT_SECONDS = "0.25";
+
+/** Thread ids are uuid-shaped; anything else skips the preflight entirely so
+ *  hostile config can never become shell injection via the lock path. */
+const CODEX_THREAD_ID_SAFE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** The sh fragment prepended to a resume launch. `waitAttempts` is a test
+ *  seam (the live-holder test must not sleep 5s); production callers take
+ *  the default. Exported for tests. */
+export function codexWriterLockPreflight(
+  threadId: string,
+  waitAttempts: number = CODEX_LOCK_WAIT_ATTEMPTS,
+): string {
+  if (!CODEX_THREAD_ID_SAFE.test(threadId)) return "";
+  return `ac_lk="\${CODEX_HOME:-$HOME/.codex}/thread-writer-locks/${threadId}.lock"; `
+    + `if [ -e "$ac_lk" ] && command -v flock >/dev/null 2>&1; then ac_lki=0; `
+    + `while ! flock -n "$ac_lk" true 2>/dev/null && [ "$ac_lki" -lt ${waitAttempts} ]; do `
+    + `sleep ${CODEX_LOCK_WAIT_SECONDS}; ac_lki=$((ac_lki+1)); done; `
+    + `flock -n "$ac_lk" rm -f -- "$ac_lk" 2>/dev/null || true; fi; `;
+}
+
 /** Exported for the fixture-based parity tests (ADR-0020): the legacy JSONL
  *  `mapEvent` is the golden the ACP normaliser is asserted equal to. Not part
  *  of the public runtime surface — `createCodexRuntime` stays the entry point. */
@@ -60,6 +108,11 @@ export const codexSpec: CliAgentSpec = {
   kind: "codex",
   authEnv: "CODEX_API_KEY",
   bin: "codex",
+  // codex holds a per-thread advisory flock for its writer's whole lifetime
+  // (see the writer-lock preflight above): a live predecessor process blocks
+  // every resume of the same thread, so supersede teardown must KILL it —
+  // never detach it alive (server runner-kill.ts consumes this flag).
+  exclusiveSessionWriter: true,
   // ACP-mode invocation (ADR-0020 increment 1). `codex` has no native `--acp`
   // flag; the adapter (a Rust binary shipped via npm) speaks ACP and drives a
   // compatible bundled `@openai/codex`. The runner attempts this first and
@@ -95,14 +148,24 @@ export const codexSpec: CliAgentSpec = {
       // backstop for a caller that bypasses that gate. The value comes from
       // the closed CliReasoningEffort set, so it is shell-safe unquoted.
       ...(effort ? ["-c", `model_reasoning_effort=${effort === "max" ? "xhigh" : effort}`] : []),
-      ...(cwd ? ["-C", shellQuote(cwd)] : []),
     ].join(" ");
+    // Working directory via a shell `cd` — the idiom EVERY other runtime uses
+    // (claude-code/cursor/droid/opencode) — NOT codex's `-C` flag. `-C` is
+    // accepted by `codex exec` but REJECTED by `codex exec resume`
+    // ("unexpected argument '-C'"), so a fresh turn worked and every follow-up
+    // died. `cd` sets the cwd identically for both paths; promptPath is
+    // absolute (/tmp/…), so the `< prompt` redirect survives the cd.
+    const cd = cwd ? `cd ${shellQuote(cwd)} && ` : "";
+    // Resume-only launch preflight: self-heal a released-or-dying writer
+    // lock before `codex exec resume` (see codexWriterLockPreflight). A
+    // fresh turn mints a new thread id — no lock can exist for it yet.
+    const preflight = sessionId ? codexWriterLockPreflight(sessionId) : "";
     // Fresh turn: `codex exec <flags> - < prompt`. Continue a thread:
     // `codex exec resume <id> <flags> - < prompt`. (`-` = read prompt from stdin.)
     const exec = sessionId
       ? `codex exec resume ${shellQuote(sessionId)} ${flags}`
       : `codex exec ${flags}`;
-    return `${exec} - < ${shellQuote(promptPath)}`;
+    return `${preflight}${cd}${exec} - < ${shellQuote(promptPath)}`;
   },
   extractSessionId: (p) =>
     p.type === "thread.started" && typeof p.thread_id === "string" ? p.thread_id : undefined,

package/src/sandbox/providers/e2b.ts

@@ -237,11 +237,15 @@ function makeE2bSandboxProvider(sb: Sandbox): SandboxProvider {
       return { resumeHandle: sb.sandboxId };
     },
     // The provider kill-clock seam: e2b's `setTimeout` REPLACES the deadline
-    // (extend or reduce) relative to now. The server's session lifecycle
-    // keeps this behind its own suspend clock so the deferred pause always
-    // wins the race against the create-time timeout.
+    // (extend or reduce) relative to now, in MILLISECONDS. The server's
+    // session lifecycle uses it two ways: a FAR-HORIZON push while the
+    // session is active (the kill-clock is an orphan backstop, never
+    // load-bearing during a live turn) and a short re-arm when the deferred
+    // pause is about to park the VM. Clamped to the plan cap exactly like
+    // the create timeout — an over-cap push would 400 and leave the OLD
+    // (possibly short) deadline standing.
     async extendLifetime(ms) {
-      await sb.setTimeout(ms);
+      await sb.setTimeout(Math.min(ms, e2bMaxSandboxMs()));
     },
     // Push a freshly-resolved egress policy onto the live sandbox via E2B's
     // native `updateNetwork` — the E2B analogue of Vercel's `update({

package/src/sandbox/providers/local.ts

@@ -5,6 +5,16 @@
 import { promises as fs } from "node:fs";
 import { dirname } from "node:path";
 import { spawn } from "node:child_process";
+/** The two listener registrations we need, declared LOCALLY.
+ *  `ChildProcess` inherits `.on` from EventEmitter, but when a tree ends up
+ *  with more than one @types/node the inheritance link breaks and `.on`
+ *  disappears — which resolution you get depends on install layout, so this
+ *  typechecked locally and failed CI three times. Referencing no node types
+ *  at all is the only version-proof shape. */
+type ProcListeners = {
+  on(event: "error", cb: (err: Error) => void): unknown;
+  on(event: "close", cb: (code: number | null) => void): unknown;
+};
 import { Readable, Writable } from "node:stream";
 import type { SandboxProvider } from "../../types/sandbox.js";
 
@@ -36,8 +46,9 @@ export function makeLocalSandboxProvider(): SandboxProvider {
           proc.stderr?.setEncoding("utf8");
           proc.stdout?.on("data", (chunk: string) => { stdout += chunk; opts?.onStdout?.(chunk); });
           proc.stderr?.on("data", (chunk: string) => { stderr += chunk; opts?.onStderr?.(chunk); });
-          proc.on("error", reject);
-          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
+          const ev = proc as unknown as ProcListeners;
+          ev.on("error", reject);
+          ev.on("close", (code: number | null) => resolve({ exitCode: code ?? 0, stdout, stderr }));
         });
       },
       // Duplex spawn — the in-VM `child_process` pipe the ACP client needs.
@@ -67,8 +78,9 @@ export function makeLocalSandboxProvider(): SandboxProvider {
         proc.stderr.on("data", (chunk: string) => { stderr += chunk; });
 
         const exited = new Promise<{ exitCode: number; stderr: string }>((resolve, reject) => {
-          proc.on("error", reject);
-          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stderr }));
+          const ev = proc as unknown as ProcListeners;
+          ev.on("error", reject);
+          ev.on("close", (code: number | null) => resolve({ exitCode: code ?? 0, stderr }));
         });
 
         return {

package/src/sandbox/sizes.ts

@@ -1,27 +1,68 @@
 /**
- * Sandbox machine sizes + the E2B template aliases derived from them.
+ * Sandbox machine sizes — THE single source of the size vocabulary.
  *
- * 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.
+ * Everything that names a size (the server's `SANDBOX_DEFAULT_SIZE` env enum,
+ * the register/invoke zod schemas, the run + session row types, the CLI's
+ * `--size` flag, the dashboard pickers via `GET /v1/sandbox-sizes`) derives
+ * from `SANDBOX_SIZES` / `SandboxSize` here. Adding a size is a ONE-LINE edit
+ * to `SANDBOX_MACHINES`: the type, the enums, the E2B build matrix and the
+ * pickers all follow. Do NOT re-declare the union inline anywhere.
+ *
+ * A size is a coarse hardware knob that maps to provider machine specs:
+ * Vercel honours it natively via `resources.vcpus`; E2B sizing is BAKED INTO
+ * THE TEMPLATE (e2b 2.30.5 has no create-time cpu/mem knob — `NewSandbox`
+ * carries only `templateID`), 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,
-};
+/** Every sandbox hardware SKU, with its real machine spec. Named for the
+ *  machine (vCPU + RAM) rather than abstract t-shirt sizes, so a size can
+ *  never quietly mean something different than it says.
+ *
+ *  RAM is 2048 MB/vCPU everywhere EXCEPT `8vcpu-8gb`, which exists because
+ *  E2B caps a sandbox at 8 vCPU / 8192 MB (e2b.dev/docs/billing: Hobby and
+ *  Pro both "8 vCPU / 8 GB", raised only by arrangement): 8 vCPU at the 2 GB
+ *  rule would need 16 GiB and cannot be built. `8vcpu-8gb` is the CPU ceiling
+ *  at the memory ceiling — the only way to get 8 cores on E2B today, and a
+ *  spec already proven bakeable by the devbox (`E2B_DEVBOX_SPEC`).
+ *
+ *  Adding an entry here automatically: widens `SandboxSize`, widens every
+ *  derived enum, and — if it fits under the E2B caps — adds it to
+ *  `E2B_TEMPLATE_SIZES`, which is what `infra/e2b-template/build.ts` and the
+ *  `sandbox-images` CI job loop over. Two templates get baked per size, so
+ *  the matrix is not free; see that workflow's header. */
+export const SANDBOX_MACHINES = {
+  /** 1 vCPU / 2 GiB — the cheap floor. Plenty for a terminal session or a
+   *  shell-shaped agent; tight for a big `bun install` or a browser. */
+  "1vcpu-2gb":   { vcpus: 1,  memoryMB: 2048 },
+  /** 2 vCPU / 4 GiB — the default (Vercel's own default machine too). */
+  "2vcpu-4gb":   { vcpus: 2,  memoryMB: 4096 },
+  /** 4 vCPU / 8 GiB — comfortable for builds and multi-tool agent turns. */
+  "4vcpu-8gb":   { vcpus: 4,  memoryMB: 8192 },
+  /** 8 vCPU / 8 GiB — E2B's per-sandbox CEILING (cores maxed at the memory
+   *  cap). NOT expressible on Vercel, whose RAM follows vCPUs at 2 GB each. */
+  "8vcpu-8gb":   { vcpus: 8,  memoryMB: 8192 },
+  /** 8 vCPU / 16 GiB — Vercel only; exceeds E2B's 8 GiB memory cap. */
+  "8vcpu-16gb":  { vcpus: 8,  memoryMB: 16384 },
+  /** 32 vCPU / 64 GiB — Vercel Enterprise only; far past every E2B cap. */
+  "32vcpu-64gb": { vcpus: 32, memoryMB: 65536 },
+} as const satisfies Record<string, { vcpus: number; memoryMB: number }>;
+
+/** Sandbox hardware SKU. Derived from `SANDBOX_MACHINES` — never re-spelled
+ *  as an inline union. */
+export type SandboxSize = keyof typeof SANDBOX_MACHINES;
+
+/** The vocabulary as an ordered, smallest-first array — the shape zod
+ *  (`z.enum`), the CLI's `--size` validation, and the wire catalogue want.
+ *  Ordering is the pickers' display order, so keep it ascending. */
+export const SANDBOX_SIZES = Object.keys(SANDBOX_MACHINES) as readonly SandboxSize[] as
+  readonly [SandboxSize, ...SandboxSize[]];
+
+/** SKU → Vercel vCPU count (Vercel's RAM follows automatically at 2048
+ *  MB/vCPU — which is why `isVercelSupportedSize` exists). */
+export const SANDBOX_VCPUS: Record<SandboxSize, number> = Object.fromEntries(
+  SANDBOX_SIZES.map((s) => [s, SANDBOX_MACHINES[s].vcpus]),
+) as Record<SandboxSize, number>;
 
 /** SDK fallback size when neither the caller nor the deployment specifies one.
  *  Deliberately conservative — the OPERATIONAL default is the server's
@@ -29,37 +70,79 @@ export const SANDBOX_VCPUS: Record<SandboxSize, number> = {
  *  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. */
+ *  workflow rather than inflating the default for everyone.
+ *
+ *  NOT `1vcpu-2gb`: the floor is an opt-IN for cheap sessions, not a quiet
+ *  downgrade of every existing run's machine. */
 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. */
+/** SESSION default — deliberately one size up from the run default
+ *  (2026-08-13): a session's sandbox carries the full desktop toolbelt
+ *  (VS Code + Chromium + dockerd) plus the KasmVNC encoder at the 60fps
+ *  cap, and that stack swap-thrashes on 4 GiB while the encoder starves on
+ *  2 shared vCPUs. Workflow runs keep DEFAULT_SANDBOX_SIZE — no desktop,
+ *  no toolbelt weight. Sessions bill active time only (parked = storage),
+ *  so the delta applies to active hours, not the fleet. */
+export const SESSION_DEFAULT_SANDBOX_SIZE: SandboxSize = "4vcpu-8gb";
+
+/** E2B's per-sandbox ceiling on the plans we run (e2b.dev/docs/billing —
+ *  Hobby: "8 vCPU / 8 GB"; Pro: the same, "8+" only by arrangement with
+ *  support). Recorded live too: `Template.build` 400s with "Memory can't be
+ *  higher than 8192 MiB" past the memory cap.
+ *
+ *  These two numbers are the ONLY knob for which sizes get an E2B template —
+ *  raise them after E2B raises the account limit and the build matrix (and
+ *  therefore the session picker) widens on its own. */
+export const E2B_MAX_VCPUS = 8;
+export const E2B_MAX_MEMORY_MB = 8192;
+
+/** The E2B sizes we pre-build a template for — DERIVED from the caps, not
+ *  hand-listed, so a new `SANDBOX_MACHINES` entry can never be offered
+ *  without a template or omitted despite fitting. E2B sizing is
+ *  template-baked (no per-create cpu/mem knob), so honouring `resources.size`
+ *  on E2B means ONE pre-built template per size; `infra/e2b-template/build.ts`
+ *  loops exactly this list. The register / invoke / session-spawn / resize
+ *  guards all reject an unsupported E2B size before it can reach a create. */
+export const E2B_TEMPLATE_SIZES: readonly SandboxSize[] = SANDBOX_SIZES.filter(
+  (s) => SANDBOX_MACHINES[s].vcpus <= E2B_MAX_VCPUS
+    && SANDBOX_MACHINES[s].memoryMB <= E2B_MAX_MEMORY_MB,
+);
+
+/** Is `size` one E2B can be built/booted at? False for the sizes past E2B's
+ *  8 vCPU / 8 GiB ceiling (`8vcpu-16gb`, `32vcpu-64gb`) — those run on Vercel.
+ *  The "no E2B equivalent" decision lives in exactly one place: the caps. */
 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. */
+/** Vercel's fixed memory-per-vCPU ratio. Vercel takes `resources.vcpus` and
+ *  allocates RAM itself at this rate — there is no independent memory knob. */
+export const VERCEL_MEMORY_MB_PER_VCPU = 2048;
+
+/** Is `size` expressible on Vercel? Only when its RAM matches what Vercel
+ *  would allocate for that vCPU count — otherwise asking for it would hand
+ *  the caller a machine that does not match the name (`8vcpu-8gb` would come
+ *  back with 16 GiB). Vercel's own ceiling (32 vCPU, Enterprise) is a plan
+ *  matter, not a shape matter, so it is not encoded here. */
+export function isVercelSupportedSize(size: SandboxSize): boolean {
+  const m = SANDBOX_MACHINES[size];
+  return m.memoryMB === m.vcpus * VERCEL_MEMORY_MB_PER_VCPU;
+}
+
+/** Machine spec for a SandboxSize, in the shape `Template.build` wants. Used
+ *  by `infra/e2b-template/build.ts` to stamp the per-size base + agent-env
+ *  templates. Reads the explicit table rather than deriving RAM from vCPUs —
+ *  `8vcpu-8gb` is deliberately off the 2048 MB/vCPU line. */
 export function e2bMachineSpec(size: SandboxSize): { cpuCount: number; memoryMB: number } {
-  const cpuCount = SANDBOX_VCPUS[size];
-  return { cpuCount, memoryMB: cpuCount * 2048 };
+  const m = SANDBOX_MACHINES[size];
+  return { cpuCount: m.vcpus, memoryMB: m.memoryMB };
+}
+
+/** Human label for a size — "2 vCPU · 4 GB". The wire catalogue carries it so
+ *  the dashboard never has to parse the id back into numbers. */
+export function sandboxSizeLabel(size: SandboxSize): string {
+  const m = SANDBOX_MACHINES[size];
+  return `${m.vcpus} vCPU · ${Math.round(m.memoryMB / 1024)} GB`;
 }
 
 /** Stable E2B template ALIAS for the platform base at a given size

package/src/sandbox.ts

@@ -23,10 +23,18 @@ export { DOT_SEGMENT_PATH_RE2, toVercelNetworkPolicy, toE2bNetwork } from "./san
 
 export type { SandboxSize } from "./sandbox/sizes.js";
 export {
+  SANDBOX_SIZES,
+  SANDBOX_MACHINES,
   SANDBOX_VCPUS,
   DEFAULT_SANDBOX_SIZE,
+  SESSION_DEFAULT_SANDBOX_SIZE,
   E2B_TEMPLATE_SIZES,
+  E2B_MAX_VCPUS,
+  E2B_MAX_MEMORY_MB,
+  VERCEL_MEMORY_MB_PER_VCPU,
   isE2bSupportedSize,
+  isVercelSupportedSize,
+  sandboxSizeLabel,
   e2bMachineSpec,
   e2bBaseTemplate,
   e2bAgentEnvTemplate,