@agent-compose/sdk 0.5.7 → 0.5.9

package/src/sandbox.ts

@@ -8,7 +8,9 @@
 import { promises as fs } from "node:fs";
 import { dirname } from "node:path";
 import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
 import { Sandbox, SandboxNotFoundError, RateLimitError } from "e2b";
+import type { SandboxNetworkOpts as E2bNetworkOpts, SandboxNetworkRule as E2bNetworkRule } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
 import type { FailedAttemptError } from "p-retry";
@@ -17,7 +19,7 @@ import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult } fr
 import type { ConnectorRequestRules } from "./types/workflow-metadata.js";
 import type { NetworkPolicy as VercelNetworkPolicy, NetworkPolicyRule as VercelNetworkPolicyRule } from "@vercel/sandbox";
 
-export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions, SandboxCommandResult } from "./types/sandbox.js";
+export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions, SandboxCommandResult, SandboxDuplexProcess, SandboxSpawnDuplexOptions } from "./types/sandbox.js";
 
 export type SandboxProviderName = "vercel" | "e2b" | "e2b-desktop";
 
@@ -41,10 +43,11 @@ const VERCEL_VM_LIFETIME_WINDOW_MS = 6 * 60 * 60 * 1000;
  * Network policy for outbound HTTPS requests — ONE shape for every provider;
  * only the enforcement point differs. When a sandbox makes a request matching
  * a domain in `allow`, the egress layer injects the specified headers before
- * forwarding — credentials never exist inside the VM. Vercel's firewall
- * enforces this natively (`requestRules` translate to native `match` rules);
- * E2B enforces it via the embedded iron-proxy, which pulls the identical
- * resolved policy from the server.
+ * forwarding — credentials never exist inside the VM. Both providers enforce
+ * this natively at the platform edge from the resolved policy passed at
+ * create: Vercel via its firewall (`requestRules` translate to native `match`
+ * rules), E2B via its native network firewall (`toE2bNetwork` →
+ * `allowOut`/`denyOut`/`rules`). See `toVercelNetworkPolicy` / `toE2bNetwork`.
  */
 export interface SandboxNetworkHeaderTransform {
   headers?: Record<string, string>;
@@ -52,9 +55,12 @@ export interface SandboxNetworkHeaderTransform {
 
 export interface SandboxNetworkAllowRule {
   transform?: SandboxNetworkHeaderTransform[];
-  /** Tier-2 request gate (method/path) — the transform (and, on iron-proxy,
-   *  the request itself) only applies when the request matches. Present on
-   *  connector-auth rules; see `ConnectorRequestRules`. */
+  /** Tier-2 request gate (method/path) — the transform only applies when the
+   *  request matches. Honoured on Vercel (translated to native `match` rules).
+   *  NOT honoured on E2B: its native rules carry only a `transform`, no
+   *  method/path matcher, so a brokered credential rides ALL requests to an
+   *  allowed host there (see `toE2bNetwork`). Present on connector-auth rules;
+   *  see `ConnectorRequestRules`. */
   requestRules?: ConnectorRequestRules;
 }
 
@@ -71,6 +77,98 @@ export type SandboxNetworkPolicy =
       subnets?: SandboxNetworkSubnetPolicy;
     };
 
+/** Sandbox machine size. A coarse small/medium/large knob that maps to
+ *  provider machine specs at create time. Vercel honours it natively via
+ *  `resources.vcpus` (2048 MB RAM per vCPU). E2B sizing is baked into the
+ *  template, so E2B ignores this field. Default: "small". */
+/** 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),
+  );
+}
+
 export interface SandboxCreateOpts {
   envs:           Record<string, string>;
   metadata:       Record<string, string>;
@@ -78,13 +176,14 @@ export interface SandboxCreateOpts {
   /** Provider-specific template/snapshot identifier. E2B: template id or
    *  snapshot id (omit → E2B's default base). Vercel: snapshot id (omit → node24). */
   template?:      string;
+  /** Machine size. Vercel maps it to `resources.vcpus`; E2B ignores it
+   *  (size is template-defined). Omit → `DEFAULT_SANDBOX_SIZE`. */
+  size?:          SandboxSize;
   /** Outbound request policy with header transforms — ONE shape for every
-   *  provider; only the enforcement point differs. Vercel's firewall
-   *  enforces + injects natively from this value. E2B enforces it via an
-   *  EMBEDDED iron-proxy inside the VM (loopback DNS + iptables, started
-   *  at boot), which fetches the identical resolved policy from the
-   *  server's per-run egress-policy endpoint — so this field is not passed
-   *  to E2B's API. See server/src/sandbox/iron-proxy.ts. */
+   *  provider; only the enforcement point differs. Both providers enforce +
+   *  inject natively at create from this value: Vercel via its firewall
+   *  (`toVercelNetworkPolicy`), E2B via its native network firewall
+   *  (`toE2bNetwork` → `network: { allowOut, denyOut, rules }`). */
   networkPolicy?: SandboxNetworkPolicy;
 }
 
@@ -130,6 +229,16 @@ interface SandboxProviderDef {
    * up eventually by the provider's own retention.
    */
   deleteSnapshot?: (snapshotId: string, env: Record<string, string>) => Promise<void>;
+  /**
+   * Does this snapshot id resolve on the provider for this account? A cheap
+   * metadata lookup — NEVER provisions a sandbox. Used at server boot to
+   * validate that the platform base snapshots the default templates boot from
+   * actually exist for this deployment (catching e.g. a dev-account snapshot
+   * baked into prod). Returns true if it resolves, false if the provider
+   * reports it does not exist. Transport/credential errors PROPAGATE — an
+   * indeterminate result must not be reported as "missing".
+   */
+  snapshotExists?: (snapshotId: string, env: Record<string, string>) => Promise<boolean>;
 }
 
 // ── E2B helpers ───────────────────────────────────────────────────────────────
@@ -141,26 +250,61 @@ export function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider {
     commands: {
       async run(cmd, opts) {
         let stderr = "";
-        const result = await commands.run(cmd, {
-          ...opts,
+        // SandboxProvider exposes `sudo: true`; E2B has no `sudo` flag — it runs
+        // a command as root via `user: "root"` (Vercel/local map sudo to their own
+        // mechanism). Passing `sudo` straight through means E2B ignores it and runs
+        // as the non-root default user, so a root-only command (e.g. `archil mount`,
+        // which REQUIRES root) silently fails. Translate sudo → user:"root".
+        const { sudo, ...rest } = (opts ?? {}) as { sudo?: boolean } & Record<string, unknown>;
+        const runOpts = {
+          ...rest,
+          ...(sudo ? { user: "root" } : {}),
           onStderr: (chunk: string) => {
             stderr += chunk;
             opts?.onStderr?.(chunk);
           },
-        });
-        return {
-          exitCode: result.exitCode,
-          stdout: result.stdout,
-          stderr: typeof (result as { stderr?: unknown }).stderr === "string"
-            ? (result as { stderr: string }).stderr
-            : stderr,
         };
+        // E2B's commands.run THROWS CommandExitError on a non-zero exit, but the
+        // SandboxProvider contract (and the Vercel provider) RETURNS a result with
+        // `exitCode` so callers can branch on it (e.g. the archil-mount degrade
+        // path inspects res.exitCode/res.stderr; a thrown bare "exit status N"
+        // loses the command's stderr). Normalize the throw back into a result;
+        // only a genuine failure (spawn error, timeout, dead sandbox — no numeric
+        // exitCode on the error) propagates.
+        try {
+          const result = await commands.run(cmd, runOpts);
+          return {
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: typeof (result as { stderr?: unknown }).stderr === "string"
+              ? (result as { stderr: string }).stderr
+              : stderr,
+          };
+        } catch (e) {
+          const ce = e as { exitCode?: unknown; stdout?: unknown; stderr?: unknown };
+          if (typeof ce.exitCode === "number") {
+            return {
+              exitCode: ce.exitCode,
+              stdout: typeof ce.stdout === "string" ? ce.stdout : "",
+              stderr: typeof ce.stderr === "string" ? ce.stderr : stderr,
+            };
+          }
+          throw e;
+        }
       },
     },
     files: {
-      async write(path, content) { await sb.files.write(path, content); },
+      // e2b 2.30 overloads `files.write` (single `(path, data)` and batch
+      // `(WriteEntry[])`); TS can't resolve the union from a bare two-arg call,
+      // so bind the single-file overload explicitly. The `WriteInfo` return is
+      // discarded — our provider contract is `Promise<void>`.
+      async write(path, content) {
+        await (sb.files.write as (p: string, d: string) => Promise<unknown>)(path, content);
+      },
     },
-    kill: () => sb.kill(),
+    // e2b 2.30 `kill()` returns Promise<boolean>; our provider contract is
+    // Promise<void>, so discard the result.
+    async kill() { await sb.kill(); },
   };
 }
 
@@ -235,6 +379,16 @@ function makeE2bSandboxProvider(sb: Sandbox): SandboxProvider {
       const { snapshotId } = await sb.createSnapshot();
       return { snapshotId };
     },
+    // Push a freshly-resolved egress policy onto the live sandbox via E2B's
+    // native `updateNetwork` — the E2B analogue of Vercel's `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. The update endpoint replaces egress rules
+    // atomically (omitted fields are cleared), so we always pass the full
+    // translated network config.
+    async updateNetworkPolicy(policy) {
+      await sb.updateNetwork(toE2bNetwork(policy));
+    },
   };
 }
 
@@ -368,6 +522,70 @@ export function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): VercelNetwo
   return { ...policy, allow };
 }
 
+/**
+ * Translate our policy shape into E2B's native `network` config
+ * (`SandboxNetworkOpts`) — the E2B analogue of `toVercelNetworkPolicy`.
+ *
+ *   - `allowOut`: the set of allowed egress targets — every host named in
+ *     `allow` PLUS every CIDR in `subnets.allow`. The Archil raw-TCP
+ *     data-plane CIDRs ride here as FIRST-CLASS allow entries (E2B has no
+ *     root-exemption to lean on, unlike the old in-VM iptables model).
+ *   - `denyOut`: the all-traffic sentinel (`0.0.0.0/0`) so the policy is
+ *     DEFAULT-DENY — only `allowOut` targets pass. E2B applies allow before
+ *     deny, so a host in both lists is allowed.
+ *   - `rules`: per-host header injection. For each host carrying transform(s),
+ *     emit one rule per transform with `{ transform: { headers } }`. A host
+ *     with a rule MUST also be in `allowOut` (registering a rule does not
+ *     grant egress on its own — E2B's API requires the host in `allowOut`).
+ *
+ * BEHAVIOURAL DIVERGENCE FROM iron-proxy / Vercel — path/method gating is NOT
+ * available on E2B native rules. An `SandboxNetworkRule` carries only a
+ * `transform` (header injection); there is no method/path matcher. So our
+ * Tier-2 `requestRules` (`{ methods, pathPrefixes }`) cannot be enforced here:
+ * a brokered credential rides EVERY request to an allowed host on E2B, whereas
+ * Vercel (native `match`) and the old iron-proxy gated it to the declared
+ * method+path. The host allowlist still confines WHICH hosts the credential
+ * can reach; it just can't narrow to a method/path within an allowed host.
+ *
+ * String policies map straight through: "allow-all" → no restriction (omit
+ * `allowOut`/`denyOut`), "deny-all" → block all egress.
+ */
+export function toE2bNetwork(policy: SandboxNetworkPolicy): E2bNetworkOpts {
+  if (policy === "allow-all") return {};
+  if (policy === "deny-all") return { denyOut: ({ allTraffic }) => [allTraffic] };
+
+  // List-form allow (no transforms): allowlist the hosts, default-deny the rest.
+  const allowHosts: string[] = Array.isArray(policy.allow)
+    ? [...policy.allow]
+    : Object.keys(policy.allow ?? {});
+  const subnetAllow = policy.subnets?.allow ?? [];
+  const allowOut = [...new Set([...allowHosts, ...subnetAllow])];
+
+  const network: E2bNetworkOpts = {
+    // Default-deny: only `allowOut` passes (E2B applies allow before deny).
+    denyOut: ({ allTraffic }) => [allTraffic],
+  };
+  if (allowOut.length > 0) network.allowOut = allowOut;
+
+  // Per-host header injection. Each of our `transform` entries (a
+  // `{ headers }` bag) becomes one E2B rule. `requestRules` is intentionally
+  // dropped — see the divergence note above.
+  if (!Array.isArray(policy.allow) && policy.allow) {
+    const rules: Record<string, E2bNetworkRule[]> = {};
+    for (const [host, hostRules] of Object.entries(policy.allow)) {
+      const hostTransforms = hostRules.flatMap((rule) =>
+        (rule.transform ?? [])
+          .filter((t) => t.headers && Object.keys(t.headers).length > 0)
+          .map((t): E2bNetworkRule => ({ transform: { headers: t.headers } })),
+      );
+      if (hostTransforms.length > 0) rules[host] = hostTransforms;
+    }
+    if (Object.keys(rules).length > 0) network.rules = rules;
+  }
+
+  return network;
+}
+
 /** 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
@@ -417,16 +635,11 @@ function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>)
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const handle: any = 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));
-        // Reconnect to the already-running command on transient stream failures (e.g. BrotliDecompressionError).
-        // `h.logs()` replays from the start on reconnect, so reset accumulators per
-        // attempt to avoid double-counting. The streaming callbacks may still fire
-        // for duplicate chunks during retries — an acceptable tradeoff for resilience.
-        //
-        // A failure here (mid-stream / on `wait`) is NOT safe to retry: the
-        // runner already launched, so user code may have produced side
-        // effects. Surface it as a terminal `SandboxUnavailableError` so it's
-        // classified honestly but not auto-replayed.
-        try {
+        // Stream + wait. Reconnect to the already-running command on transient
+        // stream failures (e.g. BrotliDecompressionError). `h.logs()` replays
+        // from the start on reconnect, so reset accumulators per attempt to
+        // avoid double-counting.
+        const collect = async () => {
           await pRetry(async (attempt) => {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const h: any = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
@@ -438,17 +651,34 @@ function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>)
           }, { retries: 3, minTimeout: 1_000, factor: 2 });
           const finished = await handle.wait();
           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 caller-requested timeout (opts.timeoutMs → AbortSignal) is a
-          // COMMAND timing out, not the sandbox dying — the VM is alive and
-          // answering; one command overran its budget. Classifying it as
-          // terminal sandbox-unavailable failed whole runs over a single
-          // slow mount probe (observed live). Surface it as a plain error
-          // so the caller's own retry/deadline policy decides.
-          if (signal?.aborted) {
-            throw new Error(`command timed out after ${opts?.timeoutMs}ms: ${cmd.slice(0, 200)}`);
-          }
+          // 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);
         }
       },
     },
@@ -486,8 +716,7 @@ function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>)
     // @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 leaves this undefined: its enforcement (iron-proxy) lives inside
-    // the VM and is configured at boot.
+    // E2B implements the same seam via `sb.updateNetwork(toE2bNetwork(...))`.
     async updateNetworkPolicy(policy) {
       await sb.update({ networkPolicy: toVercelNetworkPolicy(policy) });
     },
@@ -528,6 +757,57 @@ export function makeLocalSandboxProvider(): SandboxProvider {
           proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
         });
       },
+      // Duplex spawn — the in-VM `child_process` pipe the ACP client needs.
+      // `commands.run` buffers to completion and gives stdout only via a
+      // callback; this keeps the process alive and exposes stdin AND stdout as
+      // byte web-streams so `ndJsonStream(stdin, stdout)` can carry JSON-RPC
+      // both ways. Only the local provider has this (the runner spawns CLIs
+      // in-VM); vercel/e2b leave it undefined.
+      spawnDuplex(cmd, opts) {
+        // `detached: true` puts the `sh` and everything it spawns (the
+        // `npx`-launched ACP binary) into a NEW process group whose pgid is the
+        // `sh` pid. Without it `kill()` would SIGTERM only `sh`, orphaning the
+        // grandchild ACP agent (still holding the provider's creds + CPU) until
+        // the sandbox VM is torn down. Mirrors the Vercel `run()` detached
+        // pattern. We don't `unref()` — the parent stays attached so `exited`
+        // fires on close.
+        const proc = spawn("sh", ["-c", cmd], {
+          ...(opts?.cwd ? { cwd: opts.cwd } : {}),
+          env: { ...process.env, ...(opts?.envs ?? {}) },
+          stdio: ["pipe", "pipe", "pipe"],
+          detached: true,
+        });
+        // Capture stderr for the exit result (diagnostics on a failed CLI),
+        // but don't expose it as a stream — only stdin/stdout carry the ACP wire.
+        let stderr = "";
+        proc.stderr.setEncoding("utf8");
+        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 }));
+        });
+
+        return {
+          stdin: Writable.toWeb(proc.stdin) as WritableStream<Uint8Array>,
+          // `Readable.toWeb` is typed `ReadableStream<any>`; the double-cast
+          // through `unknown` is the standard workaround for the generic
+          // variance tsc flags on the direct cast.
+          stdout: Readable.toWeb(proc.stdout) as unknown as ReadableStream<Uint8Array>,
+          exited,
+          // Process-GROUP kill: negate the pid to signal the whole group (`sh`
+          // + the npx-spawned ACP binary), so the grandchild dies with its
+          // parent instead of being orphaned. Guarded against ESRCH — the
+          // group is already gone if the process exited first, which is benign.
+          kill() {
+            if (proc.pid === undefined) return;
+            try { process.kill(-proc.pid, "SIGTERM"); }
+            catch (err) {
+              if ((err as NodeJS.ErrnoException).code !== "ESRCH") throw err;
+            }
+          },
+        };
+      },
     },
     files: {
       async write(path, content) {
@@ -567,14 +847,19 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
       // 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, ...np, ...creds }
-        : { runtime: "node24" as const, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, ...np, ...creds },
+        ? { 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.)
@@ -646,15 +931,40 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
       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;
+      }
+    },
   },
   "e2b": {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, timeoutMs, networkPolicy: _np, ...rest }) => {
-      // `template` is an E2B template id, a snapshot id (a valid create source
-      // that persists beyond its origin sandbox — bootFrom parity), or absent →
-      // E2B's default base (Debian + node + npm/python/git), mirroring Vercel's
-      // node24 default. With no explicit template/bootFrom, fall back to
-      // E2B_DEFAULT_TEMPLATE if set (a prebuilt base — e.g. one with the claude CLI
+    // E2B has no create-time resource knob (specs are baked into the
+    // template/snapshot), so honouring `size` on E2B = picking a PRE-SIZED
+    // template, not passing the field through. We resolve the boot template
+    // from `size` below (`e2bBaseTemplate(size)`) when the caller gave no
+    // explicit template/bootFrom; the field itself is never forwarded to E2B.
+    create: async ({ template, timeoutMs, networkPolicy, size, ...rest }) => {
+      // `template` is an E2B template id/alias, a snapshot id (a valid create
+      // source that persists beyond its origin sandbox — bootFrom parity), or
+      // absent. When absent we pick the SIZE-MATCHED platform base alias
+      // (`agent-compose-base-<size>`) so `resources.size` gives the same
+      // machine spec on E2B as on Vercel — the cross-provider parity this whole
+      // change exists for. Only when no size is resolvable at all do we fall
+      // back to E2B_DEFAULT_TEMPLATE if set (a prebuilt base — e.g. one with the claude CLI
       // + chromium baked in and more RAM than the stock 482MB base), the
       // per-deployment analogue of Vercel's node24; else E2B's stock base.
       // Self-provisioning runtimes (claude/codex/amp via bootFrom:"reuse") install
@@ -663,11 +973,11 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
       // E2B's per-plan cap (see e2bMaxSandboxMs) so a 4.5h AC_SANDBOX_DEADLINE
       // doesn't 400 on smaller plans.
       //
-      // `networkPolicy` is deliberately NOT passed to E2B's API. E2B has no
-      // header-injecting firewall; enforcement happens INSIDE the VM via
-      // the embedded iron-proxy started at sandbox boot, which pulls the
-      // identical resolved policy from the server. One policy shape, two
-      // enforcement points. See server/src/sandbox/iron-proxy.ts.
+      // The resolved policy — host allowlist + per-host header injection — is
+      // enforced natively by E2B's firewall, configured at create via the
+      // `network` field (toE2bNetwork). Connector tokens ride in the rule
+      // transforms and never enter the sandbox env. One policy shape, two
+      // native enforcement points (Vercel firewall, E2B firewall).
       const maxMs = e2bMaxSandboxMs();
       if (timeoutMs > maxMs) {
         // The clamp turns E2B's explicit create-time 400 into a silent mid-run
@@ -678,8 +988,26 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
           `the sandbox dies at the cap, not the requested deadline. Raise E2B_MAX_SANDBOX_MS on plans that allow more.`,
         );
       }
-      const sandboxOpts = { ...rest, timeoutMs: Math.min(timeoutMs, maxMs) };
-      const tmpl = template ?? process.env.E2B_DEFAULT_TEMPLATE;
+      const sandboxOpts = {
+        ...rest,
+        timeoutMs: Math.min(timeoutMs, maxMs),
+        ...(networkPolicy ? { network: toE2bNetwork(networkPolicy) } : {}),
+      };
+      // Boot template resolution, in priority order:
+      //   1. explicit `template`/bootFrom (a pinned snapshot or alias),
+      //   2. else the SIZE-MATCHED base alias `agent-compose-base-<size>`
+      //      (`size` resolved to DEFAULT_SANDBOX_SIZE when unset) — this is the
+      //      cross-provider parity path,
+      //   3. else E2B_DEFAULT_TEMPLATE as an ultimate per-deployment fallback,
+      //   4. else E2B's stock base.
+      // `32vcpu-64gb` has no base-<size> template (Pro caps ~8 vCPU); the
+      // register + invoke guards reject it before a run reaches here, so we
+      // never synthesize a non-existent `agent-compose-base-32vcpu-64gb` alias.
+      const resolvedSize = size ?? DEFAULT_SANDBOX_SIZE;
+      const tmpl =
+        template ??
+        (isE2bSupportedSize(resolvedSize) ? e2bBaseTemplate(resolvedSize) : undefined) ??
+        process.env.E2B_DEFAULT_TEMPLATE;
       return makeE2bSandboxProvider(
         await (tmpl ? Sandbox.create(tmpl, sandboxOpts) : Sandbox.create(sandboxOpts)),
       );
@@ -718,14 +1046,31 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
   },
   "e2b-desktop": {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    // Mirror "e2b": `networkPolicy` is deliberately NOT passed to the SDK —
-    // its transforms carry live connector tokens, and a credential-bearing
-    // object must never cross into a third-party library's option bag.
-    // Lifetime is clamped to E2B's per-plan cap the same way.
-    create: async ({ template, timeoutMs, networkPolicy: _np, ...rest }) => {
+    // `size` dropped here: E2B has no create-time resource knob (specs are
+    // baked into the template/snapshot), so sizing on E2B = a pre-sized
+    // template, not this field. Honoured only on Vercel.
+    //
+    // NO native firewall on this path: `@e2b/desktop` bundles its own (older)
+    // `e2b` whose `SandboxOpts` predates the `network` field, so there is no
+    // way to enforce an egress policy natively here — unlike the "e2b" and
+    // "vercel" providers. Rather than SILENTLY dropping a policy (fail-open —
+    // the exact leak the native-firewall migration closed), we refuse to create
+    // a desktop sandbox under any non-empty policy. In practice this never
+    // fires: e2b-desktop is registry-only, never a workflow's runtime (see
+    // `workflow-metadata.ts`), so it is only ever provisioned with no policy.
+    create: async ({ template, timeoutMs, networkPolicy, size: _size, ...rest }) => {
       if (!template) throw new Error("E2B Desktop provider requires an explicit `template` (Dockerfile-based — no default base image)");
+      if (networkPolicy && networkPolicy !== "allow-all") {
+        throw new Error(
+          "E2B Desktop provider cannot enforce an egress network policy — `@e2b/desktop` bundles an e2b version that predates the native firewall. " +
+          "e2b-desktop is registry-only and must not run with a confined policy.",
+        );
+      }
       return makeDesktopSandboxProvider(
-        await Desktop.create(template, { ...rest, timeoutMs: Math.min(timeoutMs, e2bMaxSandboxMs()) }),
+        await Desktop.create(template, {
+          ...rest,
+          timeoutMs: Math.min(timeoutMs, e2bMaxSandboxMs()),
+        }),
       );
     },
   },
@@ -774,6 +1119,23 @@ export async function deleteSandboxSnapshot(provider: SandboxProviderName, snaps
   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