@agent-compose/sdk 0.5.8 → 0.6.0

package/src/sandbox.ts

@@ -8,16 +8,18 @@
 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, CommandHandle } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
 import type { FailedAttemptError } from "p-retry";
 import { SandboxUnavailableError } from "./sandbox-errors.js";
-import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult } from "./types/sandbox.js";
+import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult, SandboxCommandRunOptions, SandboxBackgroundProcess } from "./types/sandbox.js";
 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;
 }
 
@@ -93,13 +99,76 @@ export const SANDBOX_VCPUS: Record<SandboxSize, number> = {
 };
 
 /** SDK fallback size when neither the caller nor the deployment specifies one.
- *  Deliberately conservative — the OPERATIONAL default is chosen per-environment
- *  by the server via the `SANDBOX_DEFAULT_SIZE` env var (prod = Enterprise →
- *  `32vcpu-64gb`; dev = `8vcpu-16gb`, since the dev account caps at 8 vCPU).
- *  TODO(sandbox-size): the prod default is temporarily `32vcpu-64gb` for a
- *  memory-hungry workload — lower it back when no longer needed. */
+ *  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>;
@@ -111,12 +180,10 @@ export interface SandboxCreateOpts {
    *  (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;
 }
 
@@ -162,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 ───────────────────────────────────────────────────────────────
@@ -173,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(); },
   };
 }
 
@@ -251,14 +363,69 @@ function withSnapshotRetry(p: SandboxProvider): SandboxProvider {
   return { ...p, snapshot: () => withSandboxRetry(snapshot) };
 }
 
+/** Wrap an E2B `CommandHandle` as a provider-agnostic background process.
+ *  `wait()` is normalised NOT to throw on a non-zero exit (mirroring the
+ *  `commands.run` contract in `makeSandboxProvider`) so callers branch on
+ *  `exitCode` instead of catching. */
+function wrapE2bBackgroundProcess(handle: CommandHandle): SandboxBackgroundProcess {
+  return {
+    pid: handle.pid,
+    async wait() {
+      try {
+        const r = await handle.wait();
+        return { exitCode: r.exitCode ?? 0, stdout: r.stdout, stderr: r.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 : "",
+          };
+        }
+        throw e;
+      }
+    },
+    async kill() { await handle.kill(); },
+  };
+}
+
 /** E2B base provider + live-filesystem snapshot. E2B's `createSnapshot()` captures
  *  the running sandbox as a persistent snapshot whose id is usable as a
  *  `Sandbox.create()` source and outlives the origin sandbox — so E2B reaches
  *  snapshot / `bootFrom` parity with Vercel, and snapshot-backed `ctx.pause` works
  *  on E2B. (Desktop intentionally omits this — it is registry-only, not selectable.) */
 function makeE2bSandboxProvider(sb: Sandbox): SandboxProvider {
+  const base = makeSandboxProvider(sb);
   return {
-    ...makeSandboxProvider(sb),
+    ...base,
+    commands: {
+      ...base.commands,
+      // ADR-0028: background launch + reconnect-by-pid. The step runner runs as
+      // a background command so a server-driven pause can freeze it mid-turn
+      // (pauseProcess) and the resume activity can re-attach by pid and await
+      // its exit — continuing the SAME process, no re-run. E2B-only; Vercel's
+      // provider omits these and pauses via snapshot + re-run.
+      async runBackground(cmd, opts) {
+        const { sudo, onStdout, onStderr, ...rest } = (opts ?? {}) as SandboxCommandRunOptions;
+        const handle = await sb.commands.run(cmd, {
+          ...rest,
+          background: true,
+          ...(sudo ? { user: "root" } : {}),
+          ...(onStdout ? { onStdout } : {}),
+          ...(onStderr ? { onStderr } : {}),
+        });
+        return wrapE2bBackgroundProcess(handle);
+      },
+      async connectProcess(pid, opts) {
+        const handle = await sb.commands.connect(pid, {
+          ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+          ...(opts?.onStdout ? { onStdout: opts.onStdout } : {}),
+          ...(opts?.onStderr ? { onStderr: opts.onStderr } : {}),
+        });
+        return wrapE2bBackgroundProcess(handle);
+      },
+    },
     async snapshot() {
       // Raw capture — the transient pause/reclaim race is retried centrally:
       // createSandbox/reconnectSandbox wrap every provider's snapshot() in
@@ -267,6 +434,24 @@ function makeE2bSandboxProvider(sb: Sandbox): SandboxProvider {
       const { snapshotId } = await sb.createSnapshot();
       return { snapshotId };
     },
+    // ADR-0027: native VM-suspend. Freezes the live process in place (zero
+    // compute) and returns the sandbox id as the resume handle — resume is
+    // `reconnectSandbox(...)` (Sandbox.connect), which auto-resumes a paused VM.
+    // Distinct from snapshot(): no FS image, no kill, no re-run from the top.
+    async pauseProcess() {
+      await sb.pause();
+      return { resumeHandle: sb.sandboxId };
+    },
+    // 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));
+    },
   };
 }
 
@@ -400,6 +585,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
@@ -530,8 +779,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) });
     },
@@ -572,6 +820,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) {
@@ -695,18 +994,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" },
-    // `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.
-    create: async ({ template, timeoutMs, networkPolicy: _np, size: _size, ...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
@@ -715,11 +1036,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
@@ -730,8 +1051,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)),
       );
@@ -770,17 +1109,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.
     // `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.
-    create: async ({ template, timeoutMs, networkPolicy: _np, size: _size, ...rest }) => {
+    //
+    // 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()),
+        }),
       );
     },
   },
@@ -829,6 +1182,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

package/src/step-invocation/index.ts

@@ -27,7 +27,8 @@ export {
   stepInputPath,
   requestContextPath,
 } from "./protocol.js";
-export { invokeStep, parseStepResult, buildStepEnvs } from "./invoker.js";
+export { invokeStep, launchStep, reconnectStep, parseStepResult, buildStepEnvs } from "./invoker.js";
+export type { RunningStep, InvokeStepOptions } from "./invoker.js";
 export { serveStep } from "./server.js";
 export type { StepHandler, ServeStepRequest, StepHandlerResult } from "./server.js";
 export { StepExecutionError } from "./types.js";