@agent-compose/sdk 0.8.1 → 0.8.2

package/dist/runtimes/openai-desktop.js

@@ -1756,6 +1756,13 @@ class AgentComposeClient {
     const body = await this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/preview/${port}`, { method: "DELETE" });
     return body.closed;
   }
+  holdBackgroundWork(conversationId, input) {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work`, { method: "POST", body: { ...input?.minutes !== undefined ? { minutes: input.minutes } : {} } });
+  }
+  async releaseBackgroundWork(conversationId) {
+    const body = await this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work`, { method: "DELETE" });
+    return body.released;
+  }
   forkSession(conversationId, input) {
     return this.fetch(`/api/v1/conversations/${encodeURIComponent(conversationId)}/fork`, { method: "POST", body: input?.title ? { title: input.title } : {} });
   }
@@ -2005,7 +2012,7 @@ class AgentComposeClient {
   async createRepoLink(input, opts) {
     const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
     const body = await this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}/repo-links`, { method: "POST", body: input });
-    return body.link;
+    return body.links;
   }
   deleteRepoLink(linkId, opts) {
     const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
@@ -2029,9 +2036,17 @@ class AgentComposeClient {
   createApiKey(input) {
     return this.fetch("/api-keys", { method: "POST", body: input });
   }
-  async listApiKeys() {
-    const body = await this.fetch("/api-keys");
-    return body.data;
+  async listApiKeys(opts) {
+    const qs = new URLSearchParams;
+    if (opts?.limit !== undefined)
+      qs.set("limit", String(opts.limit));
+    if (opts?.status !== undefined)
+      qs.set("status", opts.status);
+    if (opts?.cursor !== undefined)
+      qs.set("cursor", opts.cursor);
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    const body = await this.fetch(`/api-keys${suffix}`);
+    return { data: body.data, hasMore: body.has_more, nextCursor: body.next_cursor ?? null };
   }
   getUsage(from, to) {
     const qs = `?from=${encodeURIComponent(from.toISOString())}&to=${encodeURIComponent(to.toISOString())}`;
@@ -3783,6 +3798,29 @@ function wrapJsonlCommand(args) {
 function now4() {
   return new Date().toISOString();
 }
+var TAIL_REATTACH_DELAY_MS = 2000;
+var LAUNCH_EXEC_TIMEOUT_MS = 30000;
+var LAUNCH_PID_RECOVERY_ATTEMPTS = 3;
+var LAUNCH_PID_RECOVERY_DELAY_MS = 1000;
+var INSTALL_PROBE_TIMEOUT_MS = 30000;
+function parsePid(raw) {
+  const pid = Number.parseInt(raw.trim().split(`
+`).pop() ?? "", 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : Number.NaN;
+}
+async function recoverLaunchPid(read, pidPath) {
+  for (let attempt = 0;attempt < LAUNCH_PID_RECOVERY_ATTEMPTS; attempt++) {
+    try {
+      const pid = parsePid(await read(pidPath));
+      if (!Number.isNaN(pid))
+        return pid;
+    } catch {}
+    if (attempt < LAUNCH_PID_RECOVERY_ATTEMPTS - 1) {
+      await new Promise((r) => setTimeout(r, LAUNCH_PID_RECOVERY_DELAY_MS));
+    }
+  }
+  return Number.NaN;
+}
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -3868,7 +3906,7 @@ class CliAgentRunner {
   async ensureInstalled() {
     if (this.installed)
       return;
-    const probe = await this.sandbox.commands.run(`command -v ${this.spec.bin}`);
+    const probe = await this.sandbox.commands.run(`command -v ${this.spec.bin}`, { timeoutMs: INSTALL_PROBE_TIMEOUT_MS });
     if (probe.exitCode === 0) {
       this.installed = true;
       return;
@@ -4033,51 +4071,153 @@ class CliAgentRunner {
         keepBytes: JSONL_GUARD_KEEP_BYTES
       });
       const lines = new AsyncQueue;
-      let buf = "";
-      const onStdout = (data) => {
-        buf += data;
-        let nl;
-        while ((nl = buf.indexOf(`
-`)) >= 0) {
-          const line = buf.slice(0, nl).trim();
-          buf = buf.slice(nl + 1);
-          if (line)
-            lines.push(line);
-        }
-      };
-      const runOpts = {
-        ...this.options.cwd ? { cwd: this.options.cwd } : {},
-        onStdout,
-        timeoutMs: 0
-      };
-      let exited = false;
-      const settle = (res) => {
-        exited = true;
-        const tail = buf.trim();
-        if (tail)
-          lines.push(tail);
-        lines.close();
-        return res;
-      };
-      const fail = (err) => {
-        exited = true;
-        lines.close();
-        throw err;
-      };
-      let kill;
-      let runPromise;
+      let exitCode = null;
+      let exitStderr = "";
+      let transportError = null;
+      let consumerStopped = false;
+      let reap = () => {};
+      let transport;
+      const durableRead = this.sandbox.files.read?.bind(this.sandbox.files);
       if (this.sandbox.commands.runBackground) {
-        const handle = await this.sandbox.commands.runBackground(guardedCmd, runOpts);
-        kill = () => handle.kill();
-        runPromise = handle.wait().then(settle, fail);
+        const outPath = `${promptPath}.out`;
+        const errPath = `${promptPath}.err`;
+        const detachedScript = `{ ${guardedCmd}; } >> ${shellQuote(outPath)} 2>> ${shellQuote(errPath)} </dev/null; ` + `printf '\\n%s %s\\n' ${shellQuote(sentinel)} "$?" >> ${shellQuote(outPath)}`;
+        const pidPath = `${promptPath}.pid`;
+        const launchCmd = `: > ${shellQuote(outPath)}; : > ${shellQuote(errPath)}; ` + `if command -v setsid >/dev/null 2>&1; then setsid sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & ` + `else sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & fi; ` + `echo "$!" > ${shellQuote(pidPath)}; echo "$!"`;
+        let pid = Number.NaN;
+        let launched = null;
+        let launchErr = null;
+        try {
+          launched = await this.sandbox.commands.run(launchCmd, {
+            ...this.options.cwd ? { cwd: this.options.cwd } : {},
+            timeoutMs: LAUNCH_EXEC_TIMEOUT_MS
+          });
+        } catch (err) {
+          launchErr = err;
+        }
+        if (launched) {
+          pid = parsePid(launched.stdout ?? "");
+          if (launched.exitCode !== 0 || Number.isNaN(pid)) {
+            throw new Error(`failed to launch ${this.spec.kind}: ` + `exit ${launched.exitCode}${launched.stderr ? `: ${launched.stderr.slice(-500)}` : ""}`);
+          }
+        } else {
+          pid = durableRead ? await recoverLaunchPid(durableRead, pidPath) : Number.NaN;
+          if (Number.isNaN(pid))
+            throw launchErr;
+          console.warn(`[cli-agent] ${this.spec.kind} launch exec stream died but the detached runner is up ` + `(pid ${pid} via ${pidPath}) — continuing on the durable transport: ${formatError(launchErr)}`);
+        }
+        let offset = 0;
+        let currentTail = null;
+        const consumeLine = (raw) => {
+          offset += Buffer.byteLength(raw, "utf8") + 1;
+          const line = raw.trim();
+          if (!line)
+            return;
+          if (line.startsWith(sentinel)) {
+            const code = Number(line.slice(sentinel.length).trim());
+            exitCode = Number.isFinite(code) ? code : 0;
+            return;
+          }
+          lines.push(line);
+        };
+        reap = () => {
+          this.sandbox.commands.run(`kill -TERM -- -${pid} 2>/dev/null; kill -TERM ${pid} 2>/dev/null; true`, { timeoutMs: 1e4 }).catch(() => {});
+          currentTail?.kill().catch(() => {});
+        };
+        transport = (async () => {
+          while (exitCode === null && !consumerStopped && !opts.signal?.aborted) {
+            let buf = "";
+            let handle = null;
+            const onStdout = (data) => {
+              buf += data;
+              let nl;
+              while ((nl = buf.indexOf(`
+`)) >= 0) {
+                consumeLine(buf.slice(0, nl));
+                buf = buf.slice(nl + 1);
+                if (exitCode !== null) {
+                  handle?.kill().catch(() => {});
+                  return;
+                }
+              }
+            };
+            try {
+              handle = await this.sandbox.commands.runBackground(`tail -c +${offset + 1} -f ${shellQuote(outPath)}`, { timeoutMs: 0, onStdout });
+            } catch {}
+            if (handle) {
+              if (exitCode !== null)
+                handle.kill().catch(() => {});
+              currentTail = handle;
+              await handle.wait().catch(() => {
+                return;
+              });
+              currentTail = null;
+            }
+            if (exitCode !== null || consumerStopped || opts.signal?.aborted)
+              break;
+            if (durableRead) {
+              try {
+                const bytes = Buffer.from(await durableRead(outPath), "utf8");
+                let rest = bytes.subarray(offset).toString("utf8");
+                let nl;
+                while (exitCode === null && (nl = rest.indexOf(`
+`)) >= 0) {
+                  consumeLine(rest.slice(0, nl));
+                  rest = rest.slice(nl + 1);
+                }
+              } catch {}
+            }
+            if (exitCode !== null)
+              break;
+            let alive = null;
+            try {
+              const probe = await this.sandbox.commands.run(`kill -0 ${pid} 2>/dev/null`, { timeoutMs: 1e4 });
+              alive = probe.exitCode === 0;
+            } catch {
+              alive = null;
+            }
+            if (alive === false) {
+              exitCode = JSONL_GUARD_NO_SENTINEL_EXIT;
+              break;
+            }
+            console.warn(`[cli-agent] ${this.spec.kind} turn stream lost with the runner alive — re-tailing ${outPath} from byte ${offset}`);
+            await new Promise((r) => setTimeout(r, TAIL_REATTACH_DELAY_MS));
+          }
+          if (exitCode !== null && exitCode !== 0 && durableRead) {
+            try {
+              exitStderr = (await durableRead(errPath)).slice(-2000);
+            } catch {}
+          }
+        })().finally(() => lines.close());
       } else {
-        runPromise = this.sandbox.commands.run(guardedCmd, runOpts).then(settle, fail);
+        let buf = "";
+        const onStdout = (data) => {
+          buf += data;
+          let nl;
+          while ((nl = buf.indexOf(`
+`)) >= 0) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (line)
+              lines.push(line);
+          }
+        };
+        const runOpts = {
+          ...this.options.cwd ? { cwd: this.options.cwd } : {},
+          onStdout,
+          timeoutMs: 0
+        };
+        transport = this.sandbox.commands.run(guardedCmd, runOpts).then((res) => {
+          const tail = buf.trim();
+          if (tail)
+            lines.push(tail);
+          exitCode = res.exitCode;
+          exitStderr = (res.stderr ?? "").slice(-2000);
+        }, (err) => {
+          transportError = err;
+        }).finally(() => lines.close());
       }
-      runPromise.catch(() => {});
-      const reap = () => {
-        if (!exited)
-          kill?.().catch(() => {});
-      };
+      transport.catch(() => {});
       if (opts.signal) {
         if (opts.signal.aborted)
           reap();
@@ -4101,18 +4241,28 @@ class CliAgentRunner {
             yield msg;
           }
         }
-        const res = await runPromise;
-        if (res.exitCode !== 0 && !sawError) {
-          const tail = (res.stderr ?? "").slice(-2000);
-          yield { type: "error", text: `${this.spec.kind} exited with code ${res.exitCode}${tail ? `: ${tail}` : ""}`, timestamp: now4() };
+        await transport;
+        if (transportError)
+          throw transportError;
+        if (exitCode === null) {
+          if (!sawError) {
+            yield { type: "error", text: `${this.spec.kind} aborted — the in-sandbox runner was terminated`, timestamp: now4() };
+          }
+          return;
+        }
+        if (exitCode !== 0 && !sawError) {
+          const detail = exitCode === JSONL_GUARD_NO_SENTINEL_EXIT ? " (the runner died without reporting an exit code)" : "";
+          yield { type: "error", text: `${this.spec.kind} exited with code ${exitCode}${detail}${exitStderr ? `: ${exitStderr}` : ""}`, timestamp: now4() };
           return;
         }
         if (!sawError)
           yield { type: "done", sessionId: sessionId ?? "", timestamp: now4() };
       } finally {
         opts.signal?.removeEventListener("abort", reap);
-        reap();
-        this.sandbox.commands.run(`rm -f ${shellQuote(promptPath)} ${shellQuote(guardPath)}`, { timeoutMs: 1e4 }).catch(() => {});
+        consumerStopped = true;
+        if (exitCode === null)
+          reap();
+        this.sandbox.commands.run(`rm -f ${shellQuote(promptPath)} ${shellQuote(guardPath)} ${shellQuote(`${promptPath}.out`)} ${shellQuote(`${promptPath}.err`)} ${shellQuote(`${promptPath}.pid`)}`, { timeoutMs: 1e4 }).catch(() => {});
       }
     } catch (err) {
       yield { type: "error", text: formatError(err), timestamp: now4() };
@@ -4153,11 +4303,11 @@ var codexSpec = {
       "--skip-git-repo-check",
       "--dangerously-bypass-approvals-and-sandbox",
       ...model ? ["-m", shellQuote(model)] : [],
-      ...effort ? ["-c", `model_reasoning_effort=${effort === "max" ? "xhigh" : effort}`] : [],
-      ...cwd ? ["-C", shellQuote(cwd)] : []
+      ...effort ? ["-c", `model_reasoning_effort=${effort === "max" ? "xhigh" : effort}`] : []
     ].join(" ");
+    const cd = cwd ? `cd ${shellQuote(cwd)} && ` : "";
     const exec = sessionId ? `codex exec resume ${shellQuote(sessionId)} ${flags}` : `codex exec ${flags}`;
-    return `${exec} - < ${shellQuote(promptPath)}`;
+    return `${cd}${exec} - < ${shellQuote(promptPath)}`;
   },
   extractSessionId: (p) => p.type === "thread.started" && typeof p.thread_id === "string" ? p.thread_id : undefined,
   mapEvent: (p) => {
@@ -4552,23 +4702,36 @@ function toE2bNetwork(policy) {
 }
 
 // src/sandbox/sizes.ts
-var SANDBOX_VCPUS = {
-  "2vcpu-4gb": 2,
-  "4vcpu-8gb": 4,
-  "8vcpu-16gb": 8,
-  "32vcpu-64gb": 32
+var SANDBOX_MACHINES = {
+  "1vcpu-2gb": { vcpus: 1, memoryMB: 2048 },
+  "2vcpu-4gb": { vcpus: 2, memoryMB: 4096 },
+  "4vcpu-8gb": { vcpus: 4, memoryMB: 8192 },
+  "8vcpu-8gb": { vcpus: 8, memoryMB: 8192 },
+  "8vcpu-16gb": { vcpus: 8, memoryMB: 16384 },
+  "32vcpu-64gb": { vcpus: 32, memoryMB: 65536 }
 };
+var SANDBOX_SIZES = Object.keys(SANDBOX_MACHINES);
+var SANDBOX_VCPUS = Object.fromEntries(SANDBOX_SIZES.map((s) => [s, SANDBOX_MACHINES[s].vcpus]));
 var DEFAULT_SANDBOX_SIZE = "2vcpu-4gb";
-var E2B_TEMPLATE_SIZES = [
-  "2vcpu-4gb",
-  "4vcpu-8gb"
-];
+var SESSION_DEFAULT_SANDBOX_SIZE = "4vcpu-8gb";
+var E2B_MAX_VCPUS = 8;
+var E2B_MAX_MEMORY_MB = 8192;
+var E2B_TEMPLATE_SIZES = SANDBOX_SIZES.filter((s) => SANDBOX_MACHINES[s].vcpus <= E2B_MAX_VCPUS && SANDBOX_MACHINES[s].memoryMB <= E2B_MAX_MEMORY_MB);
 function isE2bSupportedSize(size) {
   return E2B_TEMPLATE_SIZES.includes(size);
 }
+var VERCEL_MEMORY_MB_PER_VCPU = 2048;
+function isVercelSupportedSize(size) {
+  const m = SANDBOX_MACHINES[size];
+  return m.memoryMB === m.vcpus * VERCEL_MEMORY_MB_PER_VCPU;
+}
 function e2bMachineSpec(size) {
-  const cpuCount = SANDBOX_VCPUS[size];
-  return { cpuCount, memoryMB: cpuCount * 2048 };
+  const m = SANDBOX_MACHINES[size];
+  return { cpuCount: m.vcpus, memoryMB: m.memoryMB };
+}
+function sandboxSizeLabel(size) {
+  const m = SANDBOX_MACHINES[size];
+  return `${m.vcpus} vCPU · ${Math.round(m.memoryMB / 1024)} GB`;
 }
 function e2bBaseTemplate(size) {
   return `agent-compose-base-${size}`;
@@ -4785,7 +4948,7 @@ function makeE2bSandboxProvider(sb) {
       return { resumeHandle: sb.sandboxId };
     },
     async extendLifetime(ms) {
-      await sb.setTimeout(ms);
+      await sb.setTimeout(Math.min(ms, e2bMaxSandboxMs()));
     },
     async updateNetworkPolicy(policy) {
       await sb.updateNetwork(toE2bNetwork(policy));
@@ -6439,38 +6602,49 @@ there is nothing to type, paste, or screenshot a credential from.
 
 ## Recording a demo — the desktop, captured to a video the human can play
 
-"Record a demo of you using X" is a normal ask, and this machine does it:
-start a screen recording, drive the app with \`xdotool\` exactly as in Computer
-Use, stop the recording, and report the file. (For a LIVE view no recording is
-needed — the session header's **Desktop** button already streams this display
-to any teammate watching; a recording is the durable, replayable artifact.
-Both modes exist; say so when it matters.)
+"Record a demo of you using X" is a normal ask, and this machine does it.
+(For a LIVE view no recording is needed — the session header's **Desktop**
+button already streams this display to any teammate watching; a recording is
+the durable, replayable artifact. Both modes exist; say so when it matters.)
+
+**Use \`ac-record\` — the platform recorder is already on PATH** (cloud
+sessions; \`command -v ac-record\` to confirm on older machines):
 
-**ffmpeg is NOT pre-installed** — install it first, once per machine:
+    ac-record start     # begins capturing the desktop (display :0)
+    # ... drive the app with xdotool, screenshotting as you go ...
+    ac-record stop      # finishes + saves to recordings/ in your workspace
+    ac-record status    # one JSON line: {"recording":true,...}
 
-    sudo apt-get update -q && sudo apt-get install -y -q ffmpeg
+It records the whole display (with desktop audio when the machine has a
+PulseAudio monitor), enforces sane caps (5 min / 200 MB — start a fresh
+recording per scene rather than one long take), keeps the file playable even
+if the machine dies mid-take, and \`stop\` prints the saved path — the file
+lands ON THE DRIVE in \`recordings/\`, visible in Files and playable in the
+dashboard. A human watching the Desktop pane sees the recording indicator
+while you record.
 
-(drop \`sudo\` if you are already root). Then the whole recipe:
+If \`ac-record\` is missing (older machine), record by hand.
+**ffmpeg IS pre-installed** on platform images (\`command -v ffmpeg\`; only
+if absent: \`sudo apt-get update -q && sudo apt-get install -y -q ffmpeg\`):
 
     DISPLAY=:0 ffmpeg -f x11grab \\
       -video_size "$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)" \\
       -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\
       demo.webm &
     FFMPEG_PID=$!
-    # ... drive the app with xdotool, screenshotting as you go ...
+    # ... drive the app with xdotool ...
     kill -INT "$FFMPEG_PID" && wait "$FFMPEG_PID"
 
-The gotchas, each one earned:
+The hand-rolled gotchas, each one earned:
 - **Stop with SIGINT (\`kill -INT\`), never SIGKILL** — ffmpeg finalizes the
   file on SIGINT; a hard kill truncates the encode mid-write.
-- **Record WebM (matroska-family), not MP4** — mp4 writes its moov atom at the
-  END, so a killed or crashed encode leaves an UNPLAYABLE file; webm stays
-  playable up to the last written frame and plays natively in the browser.
-  MP4's only edge is compatibility with some external players — transcode
-  afterwards if you truly need it, never record straight to it.
+- **Record WebM (matroska-family), not plain MP4** — mp4 writes its moov atom
+  at the END, so a killed or crashed encode leaves an UNPLAYABLE file; webm
+  stays playable up to the last written frame and plays natively in the
+  browser. (\`ac-record\` sidesteps this with fragmented mp4.)
 - **\`-video_size\` must match the real screen** — x11grab does not default to
   it; read the geometry from \`xdotool getdisplaygeometry\` as above.
-- **10–12 fps is right for a screen demo** — small files, legible UI motion;
+- **10–15 fps is right for a screen demo** — small files, legible UI motion;
   this is not video production.
 - **Write to the drive, not /tmp** — the recording must land in your working
   directory to persist and show up in Files; a file in /tmp dies with the

package/dist/sandbox/sizes.d.ts

@@ -1,19 +1,78 @@
 /**
- * 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). */
+/** 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 declare 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. */
+    readonly "1vcpu-2gb": {
+        readonly vcpus: 1;
+        readonly memoryMB: 2048;
+    };
+    /** 2 vCPU / 4 GiB — the default (Vercel's own default machine too). */
+    readonly "2vcpu-4gb": {
+        readonly vcpus: 2;
+        readonly memoryMB: 4096;
+    };
+    /** 4 vCPU / 8 GiB — comfortable for builds and multi-tool agent turns. */
+    readonly "4vcpu-8gb": {
+        readonly vcpus: 4;
+        readonly 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. */
+    readonly "8vcpu-8gb": {
+        readonly vcpus: 8;
+        readonly memoryMB: 8192;
+    };
+    /** 8 vCPU / 16 GiB — Vercel only; exceeds E2B's 8 GiB memory cap. */
+    readonly "8vcpu-16gb": {
+        readonly vcpus: 8;
+        readonly memoryMB: 16384;
+    };
+    /** 32 vCPU / 64 GiB — Vercel Enterprise only; far past every E2B cap. */
+    readonly "32vcpu-64gb": {
+        readonly vcpus: 32;
+        readonly memoryMB: 65536;
+    };
+};
+/** 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 declare const SANDBOX_SIZES: readonly [SandboxSize, ...SandboxSize[]];
+/** SKU → Vercel vCPU count (Vercel's RAM follows automatically at 2048
+ *  MB/vCPU — which is why `isVercelSupportedSize` exists). */
 export declare const SANDBOX_VCPUS: Record<SandboxSize, number>;
 /** SDK fallback size when neither the caller nor the deployment specifies one.
  *  Deliberately conservative — the OPERATIONAL default is the server's
@@ -21,30 +80,61 @@ export declare 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 declare const DEFAULT_SANDBOX_SIZE: SandboxSize;
-/** 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. */
+/** 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 declare const SESSION_DEFAULT_SANDBOX_SIZE: SandboxSize;
+/** 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 declare const E2B_MAX_VCPUS = 8;
+export declare 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 declare const E2B_TEMPLATE_SIZES: readonly SandboxSize[];
-/** 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. */
+/** 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 declare function isE2bSupportedSize(size: SandboxSize): boolean;
-/** 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 declare 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 declare function isVercelSupportedSize(size: SandboxSize): boolean;
+/** 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 declare function e2bMachineSpec(size: SandboxSize): {
     cpuCount: number;
     memoryMB: number;
 };
+/** 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 declare function sandboxSizeLabel(size: SandboxSize): string;
 /** 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

package/dist/sandbox.d.ts

@@ -14,7 +14,7 @@ export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions,
 export type { SandboxNetworkHeaderTransform, SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxNetworkPolicy, } from "./sandbox/network-policy.js";
 export { DOT_SEGMENT_PATH_RE2, toVercelNetworkPolicy, toE2bNetwork } from "./sandbox/network-policy.js";
 export type { SandboxSize } from "./sandbox/sizes.js";
-export { SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES, isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate, isPlatformE2bTemplateAlias, } 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, isPlatformE2bTemplateAlias, } from "./sandbox/sizes.js";
 export { E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION, e2bDevboxTemplateRef, } from "./sandbox/devbox.js";
 export { AGENT_COMPOSE_TAG } from "./sandbox/provider-def.js";
 export type { SandboxCreateOpts, OwnedSandbox } from "./sandbox/provider-def.js";