@agent-compose/sdk 0.6.0 → 0.8.0

package/src/sandbox.ts

@@ -1,1269 +1,65 @@
 /**
- * Sandbox provider registry — creates and manages isolated execution environments.
+ * Sandbox module — public surface.
  *
- * Providers: "vercel" (Vercel Sandbox), "e2b" (E2B), "e2b-desktop" (E2B Desktop).
- * Each provider validates its required env vars at creation time.
+ * Implementation lives in `sandbox/`:
+ *   - `sandbox/network-policy.ts` — egress policy shape + per-provider translators
+ *   - `sandbox/sizes.ts`          — machine sizes + E2B template aliases
+ *   - `sandbox/devbox.ts`         — the ADR-0038 per-member desktop machine alias
+ *   - `sandbox/provider-def.ts`   — provider contract, create opts, fleet tag
+ *   - `sandbox/exec-stream.ts`    — SSE exec-stream parser (broker clients)
+ *   - `sandbox/providers/*`       — vercel / e2b / e2b-desktop / local providers
+ *   - `sandbox/registry.ts`       — provider registry + fleet management
  */
 
-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, 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, SandboxDuplexProcess, SandboxSpawnDuplexOptions } from "./types/sandbox.js";
 
-export type SandboxProviderName = "vercel" | "e2b" | "e2b-desktop";
-
-// Fleet-wide tag, NOT machine-scoped. Previously we embedded FLY_MACHINE_ID
-// so each replica scoped its own E2B sandboxes at boot, but that made
-// cross-replica orphan reconciliation impossible: when a replica hard-died,
-// its E2B sandboxes became invisible to every surviving replica and stayed
-// running until E2B's own lifetime cap. With a fleet-wide tag the provider
-// reconciler (`listOwned` + DB cross-ref) handles cleanup correctly across
-// all replicas. Boot-time `killAllSandboxes` was deliberately removed when
-// this changed — killing at boot with a shared tag would nuke live sandboxes
-// owned by other replicas.
-export const AGENT_COMPOSE_TAG = process.env.AGENT_COMPOSE_TAG ??
-  `agent-compose-${process.env.AGENT_COMPOSE_ENV ?? "dev"}`;
-
-/** Upper bound for how old a live Vercel sandbox can be: Pro/Enterprise plan
- *  cap (5h) + 1h slack for clock skew and `extendTimeout()` calls. */
-const VERCEL_VM_LIFETIME_WINDOW_MS = 6 * 60 * 60 * 1000;
-
-/**
- * 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. 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>;
-}
-
-export interface SandboxNetworkAllowRule {
-  transform?: SandboxNetworkHeaderTransform[];
-  /** 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;
-}
-
-export interface SandboxNetworkSubnetPolicy {
-  allow?: string[];
-  deny?: string[];
-}
-
-export type SandboxNetworkPolicy =
-  | "allow-all"
-  | "deny-all"
-  | {
-      allow?: string[] | Record<string, SandboxNetworkAllowRule[]>;
-      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>;
-  timeoutMs:      number;
-  /** 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. 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;
-}
-
-/**
- * What the provider reports as "currently alive" — the single input to orphan
- * reconciliation. `metadata` is best-effort: E2B populates it from sandbox
- * labels, Vercel from sandbox tags (max 5, stamped at create). Callers
- * that need runId correlation cross-reference `sandboxId` against their own
- * state (server: `workflow_runs.sandbox_id` + `run_agent_sandboxes.provider_sandbox_id`).
- */
-export interface OwnedSandbox {
-  sandboxId: string;
-  createdAt: Date;
-  metadata:  Record<string, string>;
-}
-
-interface SandboxProviderDef {
-  requiredEnv: Record<string, string>;
-  create:      (opts: SandboxCreateOpts, env: Record<string, string>) => Promise<SandboxProvider>;
-  reconnect?:  (sandboxId: string) => Promise<SandboxProvider>;
-  killAll?:    (env: Record<string, string>) => Promise<void>;
-  /**
-   * Returns the number of sandboxes currently running against this provider.
-   * Used for quota observability — account-wide, not per-instance.
-   *
-   * Both providers scope by our AGENT_COMPOSE_TAG (E2B metadata labels,
-   * Vercel tags) so each fleet only reports its own sandboxes; DD aggregates
-   * across instances with `sum by {provider}`.
-   */
-  getActiveCount?: (env: Record<string, string>) => Promise<number>;
-  /**
-   * Provider's view of what's currently alive for our account/fleet.
-   * The reconciliation SoT — a sandbox missing from this list IS dead,
-   * regardless of what our DB says. Implemented by listing the provider's
-   * running sandboxes; E2B filters by metadata tag, Vercel by the `executor`
-   * sandbox tag.
-   */
-  listOwned?: (env: Record<string, string>) => Promise<OwnedSandbox[]>;
-  /**
-   * Delete a snapshot by id. Called from the customer-initiated
-   * `DELETE /workflows/:runId/snapshot` route. Best-effort — the DB is
-   * source of truth; an orphan on the provider side is benign and cleaned
-   * 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 ───────────────────────────────────────────────────────────────
-
-export function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider {
-  const commands = sb.commands as { run: (cmd: string, opts?: unknown) => Promise<{ exitCode: number; stdout: string; stderr?: string }> };
-  return {
-    sandboxId: sb.sandboxId,
-    commands: {
-      async run(cmd, opts) {
-        let stderr = "";
-        // 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);
-          },
-        };
-        // 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: {
-      // 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);
-      },
-    },
-    // e2b 2.30 `kill()` returns Promise<boolean>; our provider contract is
-    // Promise<void>, so discard the result.
-    async kill() { await sb.kill(); },
-  };
-}
-
-/** E2B caps a sandbox's lifetime per plan (Hobby 1h, Pro 24h) and 400s when the
- *  create timeout exceeds it — and our `AC_SANDBOX_DEADLINE` (4.5h) tops Hobby.
- *  Clamp the E2B create timeout to this max (raise on Pro via `E2B_MAX_SANDBOX_MS`).
- *  Read at call time so the workflow bundle stays env-free. */
-function e2bMaxSandboxMs(): number {
-  return Number(process.env.E2B_MAX_SANDBOX_MS) || 60 * 60 * 1000;
-}
-
-/** Is this a FLEETING sandbox-provider race worth retrying — the sandbox being
- *  paused / reclaimed / stopped under load, an upstream 5xx/429, or a dropped
- *  connection — vs a PERMANENT failure that must fail fast?
- *
- *  E2B raises TYPED errors, so prefer `instanceof` (upgrade-stable — survives any
- *  message rewording): a reconnect/snapshot that hits a sandbox mid-pause throws
- *  `SandboxNotFoundError`, rate limits throw `RateLimitError`. (Permanent
- *  template/snapshot-not-found only occurs on CREATE, which is no longer retried.)
- *  The message regex is the FALLBACK for the untyped Vercel transport + raw socket
- *  errors — and deliberately omits bare "timeout"/"network": E2B's permanent
- *  plan-cap 400 ("timeout … exceeds the maximum sandbox lifetime") contains
- *  "timeout" and must fail fast, not retry 4×. */
-function isTransientSandboxError(error: unknown): boolean {
-  if (error instanceof SandboxNotFoundError || error instanceof RateLimitError) return true;
-  const message = error instanceof Error ? error.message : String(error ?? "");
-  // The 5xx match is anchored to a status-code context ("status 503",
-  // "502 Bad Gateway", …) — a bare \b5\d\d\b would classify ANY standalone
-  // 500-599 number in a message (durations, row counts) as retryable.
-  return /paus|stopp|resum|transition|status(?:\s+code)?[:\s]+5\d\d\b|\b5\d\d\s+(?:internal|bad gateway|service|gateway)|\b429\b|ECONNRESET|ECONNREFUSED|ETIMEDOUT|socket hang up|fetch failed/i
-    .test(message);
-}
-
-/** The ONE place the sandbox retry policy lives. Provisioning, reconnecting, and
- *  snapshotting all race with the sandbox being paused/reclaimed; this runs the call
- *  through p-retry's generic backoff, retrying ONLY the transient race (and failing
- *  fast otherwise). reconnectSandbox and provider.snapshot() all go through it, so
- *  no provider re-implements the pattern or can forget it. `shouldRetry` is
- *  overridable for call sites where the default classification is wrong (see
- *  reconnectSandbox's SandboxNotFoundError handling). */
-function withSandboxRetry<T>(
-  fn: () => Promise<T>,
-  shouldRetry: (error: FailedAttemptError) => boolean = isTransientSandboxError,
-): Promise<T> {
-  return pRetry(fn, { retries: 4, minTimeout: 400, factor: 2, shouldRetry });
-}
-
-/** Add snapshot-retry to a freshly-obtained provider. create/reconnect are retried at
- *  the registry call (`createSandbox`/`reconnectSandbox`); snapshot is a method, so it
- *  gets the same `withSandboxRetry` here. `commands.run` is deliberately NOT wrapped —
- *  retrying user-code execution could double-apply side effects, so step execution
- *  relies on the engine's pre-step sandbox recovery instead. No-op without a snapshot. */
-function withSnapshotRetry(p: SandboxProvider): SandboxProvider {
-  if (!p.snapshot) return p;
-  const snapshot = p.snapshot.bind(p);
-  return { ...p, snapshot: () => withSandboxRetry(snapshot) };
-}
-
-/** 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 {
-    ...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
-      // withSandboxRetry (via withSnapshotRetry). create itself is deliberately
-      // NOT retried — see createSandbox.
-      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));
-    },
-  };
-}
-
-export function makeDesktopSandboxProvider(sb: Desktop): DesktopSandboxProvider {
-  return {
-    ...makeSandboxProvider(sb),
-    screenshot:  ()           => sb.screenshot() as Promise<Buffer>,
-    leftClick:   (x, y)       => sb.leftClick(x, y),
-    doubleClick: (x, y)       => sb.doubleClick(x, y),
-    rightClick:  (x, y)       => sb.rightClick(x, y),
-    middleClick: (x, y)       => sb.middleClick(x, y),
-    moveMouse:   (x, y)       => sb.moveMouse(x, y),
-    write:       (text)       => sb.write(text),
-    press:       (key)        => sb.press(key),
-    scroll:      (dir, ticks) => sb.scroll(dir, ticks),
-    drag:        (from, to)   => sb.drag(from, to),
-  };
-}
-
-// ── SSE helper (used by broker clients in runner.ts) ─────────────────────────
-
-type SseEvent = { type: string; data?: string; exitCode?: number };
-
-export interface ParseSseExecStreamOptions {
-  onStdout?: (data: string) => void;
-  onStderr?: (data: string) => void;
-}
-
-/**
- * Parse an SSE exec stream from a ReadableStream.
- * Used by the agent sandbox broker in runner.ts.
- */
-export async function parseSseExecStream(
-  body: ReadableStream<Uint8Array>,
-  opts?: ParseSseExecStreamOptions,
-): Promise<SandboxCommandResult> {
-  let stdout = "", stderr = "", exitCode = 0, exited = false;
-  const reader = body.getReader(), decoder = new TextDecoder();
-  let buf = "";
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    buf += decoder.decode(value, { stream: true });
-    const lines = buf.replace(/\r\n/g, "\n").split("\n");
-    buf = lines.pop() ?? "";
-    for (const line of lines) {
-      if (!line.startsWith("data: ")) continue;
-      let event: SseEvent;
-      try { event = JSON.parse(line.slice(6)) as SseEvent; }
-      catch (err) { throw new Error(`Malformed sandbox exec event: ${err instanceof Error ? err.message : String(err)}`); }
-      if (event.type === "stdout")       { stdout += event.data ?? ""; opts?.onStdout?.(event.data ?? ""); }
-      else if (event.type === "stderr")  { stderr += event.data ?? ""; opts?.onStderr?.(event.data ?? ""); }
-      else if (event.type === "exit")    { exitCode = event.exitCode ?? 0; exited = true; }
-      else if (event.type === "error")   { throw new Error(`Sandbox exec error: ${event.data}`); }
-    }
-    // Stop reading as soon as the exit event is received — don't wait for stream close.
-    // QUIC tunnels can delay the stream-end signal even after all data has arrived.
-    if (exited) break;
-  }
-  if (!exited) throw new Error("Sandbox exec stream ended without an exit event");
-  return { exitCode, stdout, stderr };
-}
-
-// ── Vercel helpers ────────────────────────────────────────────────────────────
-
-/** Matches a path containing a dot-dot segment — literal (`/../`) or
- *  percent-encoded (`%2e%2e`, `%2f` boundaries). `DOT_SEGMENT_PATH_RE2` is
- *  the RE2 form handed to Vercel's matcher: wrapped in `.*` so it behaves
- *  identically under search and full-match semantics (RE2 has no lookaround,
- *  so the guard is a positive match on the traversal pattern, used as a
- *  credential-stripping first rule). `DOT_SEGMENT_RE` is the local JS twin
- *  used to validate DECLARED prefixes. */
-export const DOT_SEGMENT_PATH_RE2 = ".*(?:^|/|%2[fF])(?:\\.|%2[eE]){2}(?:/|%2[fF]|$).*";
-const DOT_SEGMENT_RE = /(?:^|\/|%2f)(?:\.|%2e){2}(?:\/|%2f|$)/i;
-
-/** A Tier-2 path gate decides where a brokered credential may ride, so a
- *  malformed declared prefix is a config bug that must fail closed, not a
- *  string we forward verbatim to a third-party matcher. */
-function assertSafePathPrefix(domain: string, prefix: string): void {
-  if (!prefix.startsWith("/") || DOT_SEGMENT_RE.test(prefix)) {
-    throw new Error(
-      `Invalid Tier-2 pathPrefix ${JSON.stringify(prefix)} for "${domain}": prefixes must start with "/" and contain no dot-segments`,
-    );
-  }
-}
-
-/**
- * Translate our policy shape into Vercel's native `NetworkPolicy`.
- *
- * The shapes are identical except for Tier-2: our `requestRules`
- * (`{ methods, pathPrefixes }`) become Vercel `match` rules
- * (`{ method, path: { startsWith } }`) — one rule per path prefix, since a
- * Vercel matcher carries a single path.
- *
- * Dot-segment defense: prefix matching is raw — `/repos/acme/../../user`
- * starts with `/repos/acme/` but the origin normalizes it to `/user`, riding
- * the credential outside its declared scope. We don't get to assume the
- * enforcer RFC-3986-normalizes before matching, so every domain with a path
- * gate gets a transform-free FIRST rule matching dot-segment paths
- * (first-match-wins ⇒ such requests go out credential-free), and declared
- * prefixes themselves are validated (must start with "/", no dot-segments).
- *
- * Accepted divergence from iron-proxy (E2B): off-gate requests to an allowed
- * domain pass WITHOUT the transform (Vercel terminates TLS only for
- * transform-bearing domains and applies first-match-wins) — iron-proxy
- * REFUSES them instead. Reachability differs; the property that matters is
- * preserved on both substrates: the brokered credential rides only declared
- * method/path combinations. Pinned by vercel-network-policy.test.ts.
- */
-export function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): VercelNetworkPolicy {
-  if (typeof policy === "string" || !policy.allow || Array.isArray(policy.allow)) {
-    return policy as VercelNetworkPolicy;
-  }
-  const allow: Record<string, VercelNetworkPolicyRule[]> = {};
-  for (const [domain, rules] of Object.entries(policy.allow)) {
-    const translated = rules.flatMap((rule): VercelNetworkPolicyRule[] => {
-      const { requestRules, ...rest } = rule;
-      const methods = requestRules?.methods ?? [];
-      const prefixes = requestRules?.pathPrefixes ?? [];
-      if (methods.length === 0 && prefixes.length === 0) return [rest];
-      const methodMatch = methods.length > 0 ? { method: methods } : {};
-      if (prefixes.length === 0) return [{ ...rest, match: methodMatch }];
-      for (const prefix of prefixes) assertSafePathPrefix(domain, prefix);
-      return prefixes.map((prefix) => ({ ...rest, match: { ...methodMatch, path: { startsWith: prefix } } }));
-    });
-    const hasPathGate = rules.some((rule) => (rule.requestRules?.pathPrefixes?.length ?? 0) > 0);
-    allow[domain] = hasPathGate
-      ? [{ match: { path: { regex: DOT_SEGMENT_PATH_RE2 } } }, ...translated]
-      : translated;
-  }
-  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
- *  makes the sandbox invisible to cleanup. When metadata overflows the cap,
- *  keep executor + the lexicographically-first 4 metadata keys, so what gets
- *  dropped is deterministic rather than dependent on object insertion order. */
-export const VERCEL_MAX_TAGS = 5;
-export function buildVercelTags(metadata: Record<string, string>): Record<string, string> {
-  const tags: Record<string, string> = { ...metadata, executor: AGENT_COMPOSE_TAG };
-  const extras = Object.keys(tags).filter((k) => k !== "executor").sort();
-  for (const key of extras.slice(VERCEL_MAX_TAGS - 1)) delete tags[key];
-  return tags;
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>): SandboxProvider {
-  // Vercel's Sandbox.create({ env }) does NOT flow to runCommand subprocesses — they start fresh shells.
-  // Capture the sandbox-level envs and merge them into every runCommand call so that env vars like
-  // ANTHROPIC_API_KEY (placeholder for network policy injection) are actually visible to subprocesses.
-  const mergeEnvs = (cmdEnvs?: Record<string, string>) =>
-    globalEnvs ? { ...globalEnvs, ...cmdEnvs } : cmdEnvs;
-
-  // Wrap a sandbox-side failure as `SandboxUnavailableError`. `retryable` is
-  // decided purely by *where* the error was caught, not by inspecting its
-  // shape: true before the runner launched any user code (file write / command
-  // launch / reconnect — safe to re-provision and retry), false once the
-  // runner streamed (user code may have run). The original message is
-  // preserved for server-side diagnostics.
-  const asUnavailable = (err: unknown, retryable: boolean): never => {
-    throw new SandboxUnavailableError(err instanceof Error ? err.message : String(err), { retryable, sandboxId: sb.name });
-  };
-
-  return {
-    // @vercel/sandbox 2.x is name-keyed: `name` is the stable identifier
-    // (`Sandbox.get({ name })`); the v1 `sandboxId` getter is gone. Our
-    // provider-facing field keeps its name — it's "the provider-native id".
-    sandboxId: sb.name,
-    commands: {
-      async run(cmd, opts) {
-        const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
-        let stdout = "";
-        let stderr = "";
-        // `sudo: true` is Vercel's native root flag — applied to the `sh`
-        // invocation so the whole shell (and its children) runs as root.
-        // A launch failure means the command never started — nothing
-        // user-side ran, so any error here is safe to re-provision + retry.
-        // 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));
-        // 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);
-            if (attempt > 1) { stdout = ""; stderr = ""; }
-            for await (const log of h.logs()) {
-              if (log.stream === "stdout") { stdout += log.data; opts?.onStdout?.(log.data); }
-              else { stderr += log.data; opts?.onStderr?.(log.data); }
-            }
-          }, { 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 timeout (hard deadline or AbortSignal) is a COMMAND overrunning
-          // its budget, not the sandbox dying — the VM is alive. Surface it as
-          // a plain error so the caller's own retry/deadline policy decides
-          // (classifying it as terminal sandbox-unavailable failed whole runs
-          // over a single slow mount probe, observed live).
-          if (err instanceof Error && err.message.startsWith("command timed out after")) throw err;
-          if (signal?.aborted) throw new Error(`command timed out after ${opts?.timeoutMs}ms: ${cmd.slice(0, 200)}`);
-          return asUnavailable(err, false);
-        } finally {
-          if (timer) clearTimeout(timer);
-        }
-      },
-    },
-    files: {
-      async write(path: string, content: string) {
-        // File writes happen before the runner launches (step input / pause
-        // resolution files), so a failure here means nothing ran — retryable.
-        await sb.writeFiles([{ path, content }]).catch((err: unknown) => asUnavailable(err, true));
-      },
-    },
-    // Propagate errors — `killAllRunSandboxes` relies on kill failures being
-    // observable so it can leave `sandbox_id` set for `findOrphanedSandboxes`
-    // to retry on next boot. Swallowing here makes the orphan retry loop blind.
-    //
-    // kill must DESTROY: in @vercel/sandbox 2.x stop() only halts the VM — the
-    // name-keyed sandbox record persists (reserving the name; commands against
-    // a stale handle can transparently resume a stopped VM). delete() is the
-    // destroying call ("after deletion the instance becomes inert"), so stop
-    // then delete.
-    async kill() { await sb.stop(); await sb.delete(); },
-    // Vercel native snapshot — used by sandbox-environments to capture the
-    // configured VM after the customer's `setup()` completes. `expiration: 0`
-    // is Vercel's "never expires" value; env snapshots are long-lived by
-    // design (they ARE the env) so we always pass it.
-    async snapshot() {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const res: any = await sb.snapshot({ expiration: 0 });
-      const sizeBytes = typeof res.sizeBytes === "number" ? res.sizeBytes : undefined;
-      return {
-        snapshotId: res.snapshotId as string,
-        ...(sizeBytes !== undefined ? { sizeBytes } : {}),
-      };
-    },
-    // Push a freshly-resolved egress policy onto the live sandbox —
-    // @vercel/sandbox 2.x `update({ networkPolicy })`. Lets the server
-    // re-resolve the run policy (re-minting connector access tokens)
-    // before each step instead of living with the policy baked at create.
-    // E2B implements the same seam via `sb.updateNetwork(toE2bNetwork(...))`.
-    async updateNetworkPolicy(policy) {
-      await sb.update({ networkPolicy: toVercelNetworkPolicy(policy) });
-    },
-  };
-}
-
-// ── Local provider (runner's own VM) ──────────────────────────────────────────
-
-/** Minimal SandboxProvider that targets the current process's host VM.
- *  `commands.run` → `child_process.spawn`; `files.write` → `fs.writeFile`;
- *  `kill` is a no-op because the caller IS the VM. Used by
- *  `defineSandboxEnvironment` so setup recipes read like imperative
- *  provisioning scripts. Uses `node:child_process` — works under both Node
- *  (the runner executes `node /tmp/runner.bundle.js`) and Bun. */
-export function makeLocalSandboxProvider(): SandboxProvider {
-  return {
-    sandboxId: "local",
-    commands: {
-      run(cmd, opts) {
-        // Prepend `sudo` so the command runs as root. The local provider
-        // targets the runner's own host VM (used by defineSandboxEnvironment
-        // recipes); harmless when the host is already root or has passwordless
-        // sudo, which is the only context it runs in.
-        const finalCmd = opts?.sudo ? `sudo ${cmd}` : cmd;
-        return new Promise((resolve, reject) => {
-          const proc = spawn("sh", ["-c", finalCmd], {
-            ...(opts?.cwd ? { cwd: opts.cwd } : {}),
-            env: { ...process.env, ...(opts?.envs ?? {}) },
-            stdio: ["ignore", "pipe", "pipe"],
-          });
-          let stdout = "";
-          let stderr = "";
-          proc.stdout?.setEncoding("utf8");
-          proc.stderr?.setEncoding("utf8");
-          proc.stdout?.on("data", (chunk: string) => { stdout += chunk; opts?.onStdout?.(chunk); });
-          proc.stderr?.on("data", (chunk: string) => { stderr += chunk; opts?.onStderr?.(chunk); });
-          proc.on("error", reject);
-          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
-        });
-      },
-      // 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) {
-        await fs.mkdir(dirname(path), { recursive: true });
-        await fs.writeFile(path, content);
-      },
-    },
-    async kill() { /* caller IS the sandbox — killing it is the server's job */ },
-  };
-}
-
-// ── Provider registry ─────────────────────────────────────────────────────────
-
-const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
-  "vercel": {
-    requiredEnv: {
-      VERCEL_ACCESS_TOKEN: "Vercel access token — vercel.com/account/tokens",
-      VERCEL_TEAM_ID:      "Vercel team ID — vercel.com/account/settings",
-      VERCEL_PROJECT_ID:   "Vercel project ID — vercel.com/[team]/[project]/settings",
-    },
-    create: async (opts, env) => {
-      // Dynamic import keeps @vercel/sandbox out of runner.bundle.js (runner never calls this path)
-      const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
-      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
-      // `template` is a snapshot id (runtime is baked in); absent → fresh node24.
-      const np = opts.networkPolicy ? { networkPolicy: toVercelNetworkPolicy(opts.networkPolicy) } : {};
-      // Caller metadata rides as Vercel tags — `listOwned` filters on the
-      // `executor` key, mirroring E2B's metadata-tag scoping. buildVercelTags
-      // guarantees executor wins over metadata and survives the 5-tag cap.
-      const tags = buildVercelTags(opts.metadata);
-      // No explicit template/bootFrom → VERCEL_DEFAULT_SNAPSHOT if set (the
-      // platform agent-env base: claude, archil, rtk, bun, agentc CLI, the
-      // SDK in /workspace/node_modules, /ac:* skills, AGENTS.md — built by
-      // .agentc/environments/agent-env.ts), else raw node24. The E2B
-      // analogue is E2B_DEFAULT_TEMPLATE below. Because `saveLatest`/
-      // `reuse` captures snapshot the whole filesystem, everything a run
-      // bakes on top of this base chains from it — the base tools are in
-      // every derived snapshot for free.
-      const tmpl = opts.template ?? process.env.VERCEL_DEFAULT_SNAPSHOT;
-      // Machine size → vCPUs (RAM auto-follows at 2048 MB/vCPU). Always sent
-      // explicitly so the spec is deterministic and self-documenting rather
-      // than riding Vercel's implicit default; "small" maps to that default
-      // anyway, so existing runs are unchanged.
-      const resources = { vcpus: SANDBOX_VCPUS[opts.size ?? DEFAULT_SANDBOX_SIZE] };
-      // `persistent: false` — @vercel/sandbox 2.x creates persistent-by-default
-      // sandboxes: stop() auto-snapshots (and keeps billing storage), commands
-      // transparently resume a stopped VM, and kill no longer destroys. Our
-      // sandboxes are single-run and lifecycle-managed by the engine (explicit
-      // snapshot() / kill()), so opt out in BOTH branches.
-      const sb = await VercelSandbox.create(tmpl
-        ? { source: { type: "snapshot" as const, snapshotId: tmpl }, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds }
-        : { runtime: "node24" as const, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds },
-      );
-      // Pass envs as globalEnvs so they're injected into every runCommand subprocess.
-      // (Vercel's Sandbox.create env parameter does not flow to runCommand subprocesses.)
-      return makeVercelSandboxProvider(sb, opts.envs);
-    },
-    reconnect: async (sandboxId) => {
-      const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
-      const creds = {
-        token:     process.env.VERCEL_ACCESS_TOKEN ?? "",
-        teamId:    process.env.VERCEL_TEAM_ID ?? "",
-        projectId: process.env.VERCEL_PROJECT_ID ?? "",
-      };
-      // Reconnecting happens before any user code runs, so any failure here
-      // (sandbox already stopping, API blip) is a retryable sandbox-unavailable
-      // — the workflow re-provisions a fresh one rather than failing the run.
-      // 2.x is name-keyed: the id we persisted IS the sandbox name.
-      const sb = await VercelSandbox.get({ name: sandboxId, ...creds }).catch((err: unknown) => {
-        throw new SandboxUnavailableError(err instanceof Error ? err.message : String(err), { retryable: true, sandboxId });
-      });
-      return makeVercelSandboxProvider(sb);
-    },
-    getActiveCount: async (env) => (await SANDBOX_PROVIDERS.vercel.listOwned!(env)).length,
-    listOwned: async (env) => {
-      const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
-      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
-      // Scoped to our fleet by the `executor` tag (stamped at create) and
-      // bounded to `VERCEL_VM_LIFETIME_WINDOW_MS` — Pro/Enterprise caps VM
-      // lifetime at 5h, +1h slack for clock skew and `extendTimeout()`. The
-      // sort is pinned to createdAt-desc explicitly — the early-stop below is
-      // only correct under that order, and the server's default sort is not a
-      // contract we can rely on — so we stop at the first item older than the
-      // window instead of paging through thousands of historical terminal
-      // sandboxes (10k+ in v0.6.28). Truncating silently would hide orphans,
-      // so we throw at the page cap instead — 200 pages × the API's 50-item
-      // limit preserves the previous 10k scan bound (v1 paged 200 × 50). Each
-      // page is wrapped in pRetry so a transient 5xx/429/network blip doesn't
-      // cost a reconcile tick.
-      //
-      // 2.x cutover caveat: sandboxes created by the pre-2.x code carry no
-      // tags, so for up to VERCEL_VM_LIFETIME_WINDOW_MS after a deploy they
-      // are invisible here (and their persisted v1 sandbox ids don't resolve
-      // via `Sandbox.get({ name })`). Self-limiting — the provider's 5h
-      // lifetime cap expires them — but drain in-flight Vercel runs before
-      // deploying if losing their sandbox state matters.
-      const since = Date.now() - VERCEL_VM_LIFETIME_WINDOW_MS;
-      const out: OwnedSandbox[] = [];
-      let cursor: string | undefined;
-      for (let page = 0; page < 200; page++) {
-        const result = await pRetry(
-          // limit is capped at 50 by the v2 list API — 51+ answers 400
-          // (probed live 2026-06-10; not documented in the SDK types).
-          () => VercelSandbox.list({ ...creds, limit: 50, sortBy: "createdAt", sortOrder: "desc", tags: { executor: AGENT_COMPOSE_TAG }, ...(cursor !== undefined ? { cursor } : {}) }),
-          { retries: 3, minTimeout: 500, factor: 2 },
-        );
-        for (const sb of result.sandboxes) {
-          if (sb.createdAt < since) return out;
-          if (sb.status === "running") {
-            out.push({ sandboxId: sb.name, createdAt: new Date(sb.createdAt), metadata: sb.tags ?? {} });
-          }
-        }
-        if (result.pagination.next === null) return out;
-        cursor = result.pagination.next;
-      }
-      throw new Error("Vercel listSandboxes exceeded 200 pages (10k sandboxes) within the lifetime window — refuse to silently truncate");
-    },
-    deleteSnapshot: async (snapshotId, env) => {
-      const { Snapshot } = await import("@vercel/sandbox");
-      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
-      const snap = await Snapshot.get({ snapshotId, ...creds });
-      await snap.delete();
-    },
-    snapshotExists: async (snapshotId, env) => {
-      const { Snapshot } = await import("@vercel/sandbox");
-      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
-      // Metadata-only lookup (no sandbox provisioned). A clean fetch ⇒ resolves.
-      // A 404 / not-found ⇒ definitively absent (false). Anything else (auth,
-      // 5xx, network) is INDETERMINATE and must propagate — never reported as
-      // "missing", which would falsely alert on a transient blip.
-      try {
-        await Snapshot.get({ snapshotId, ...creds });
-        return true;
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err ?? "");
-        const status = (err as { status?: number; statusCode?: number })?.status
-          ?? (err as { statusCode?: number })?.statusCode;
-        if (status === 404 || /\b404\b|not[\s_-]?found|no such snapshot/i.test(message)) return false;
-        throw err;
-      }
-    },
-  },
-  "e2b": {
-    requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    // 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
-      // their CLI on the base and cache it in the captured snapshot, so a
-      // template-less first run boots, installs, snapshots. Clamp the lifetime to
-      // E2B's per-plan cap (see e2bMaxSandboxMs) so a 4.5h AC_SANDBOX_DEADLINE
-      // doesn't 400 on smaller plans.
-      //
-      // 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
-        // sandbox death at the cap — say so up front instead of letting a run
-        // budgeted past the cap discover it as a terminal infra failure.
-        console.warn(
-          `[sandbox] e2b create timeout clamped: requested ${timeoutMs}ms exceeds the plan cap ${maxMs}ms — ` +
-          `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),
-        ...(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)),
-      );
-    },
-    reconnect: async (sandboxId) => makeE2bSandboxProvider(
-      await Sandbox.connect(sandboxId, { apiKey: process.env.E2B_API_KEY ?? "", timeoutMs: 60 * 60 * 1000 }),
-    ),
-    killAll: async () => {
-      const paginator = Sandbox.list({ query: { metadata: { executor: AGENT_COMPOSE_TAG } } });
-      const sandboxes = [];
-      while (paginator.hasNext) sandboxes.push(...await paginator.nextItems());
-      if (sandboxes.length === 0) return;
-      await Promise.all(sandboxes.map(s => Sandbox.kill(s.sandboxId)));
-      console.info(`[sandbox] killed ${sandboxes.length} stale E2B sandboxes (tag: ${AGENT_COMPOSE_TAG})`);
-    },
-    getActiveCount: async () => (await SANDBOX_PROVIDERS.e2b.listOwned!({})).length,
-    listOwned: async () => {
-      const paginator = Sandbox.list({ query: { metadata: { executor: AGENT_COMPOSE_TAG }, state: ["running"] } });
-      const out: OwnedSandbox[] = [];
-      while (paginator.hasNext) {
-        const items = await pRetry(() => paginator.nextItems(), { retries: 3, minTimeout: 500, factor: 2 });
-        for (const sb of items) {
-          out.push({
-            sandboxId: sb.sandboxId,
-            createdAt: new Date(sb.startedAt),
-            metadata:  sb.metadata ?? {},
-          });
-        }
-      }
-      return out;
-    },
-    deleteSnapshot: async (snapshotId, env) => {
-      // E2B snapshots are team-scoped; delete by id. Best-effort like Vercel's.
-      await Sandbox.deleteSnapshot(snapshotId, { apiKey: env.E2B_API_KEY });
-    },
-  },
-  "e2b-desktop": {
-    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.
-    //
-    // 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()),
-        }),
-      );
-    },
-  },
-};
-
-/** Provision a sandbox for the named provider. */
-export async function createSandbox(provider: SandboxProviderName, opts: SandboxCreateOpts): Promise<SandboxProvider> {
-  const def = SANDBOX_PROVIDERS[provider];
-  if (!def) throw new Error(`Unknown sandbox provider: "${provider}". Known: ${Object.keys(SANDBOX_PROVIDERS).join(", ")}`);
-  const missing = Object.entries(def.requiredEnv)
-    .filter(([key]) => !process.env[key])
-    .map(([key, desc]) => `  ${key}  — ${desc}`);
-  if (missing.length > 0) throw new Error(`Sandbox provider "${provider}" requires env vars:\n${missing.join("\n")}`);
-  const env = Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]!]));
-  // Provision once — do NOT wrap create in withSandboxRetry: a create whose RESPONSE
-  // is lost (client-side timeout after the provider already provisioned) would, on
-  // retry, mint a SECOND billed sandbox and orphan the first. Provision failures are
-  // re-attempted at the workflow layer. The result is still wrapped so snapshot()
-  // retries the transient pause/reclaim race (which is where the race actually lives).
-  return withSnapshotRetry(await def.create(opts, env));
-}
-
-/** Reconnect to an existing sandbox by provider + provider-native sandbox ID. */
-export async function reconnectSandbox(provider: SandboxProviderName, sandboxId: string): Promise<SandboxProvider> {
-  const def = SANDBOX_PROVIDERS[provider];
-  if (!def?.reconnect) throw new Error(`Provider "${provider}" does not support reconnect`);
-  // Retry the transient reconnect/resume race, then add snapshot-retry to the
-  // result. On RECONNECT, SandboxNotFoundError usually means the sandbox is
-  // genuinely gone (killed / lifetime-expired) — permanent — but it can also
-  // be the transient mid-pause race, so it gets exactly ONE retry instead of
-  // burning the full 4-attempt backoff before surfacing.
-  return withSnapshotRetry(await withSandboxRetry(
-    () => def.reconnect!(sandboxId),
-    (error) => error instanceof SandboxNotFoundError ? error.attemptNumber <= 1 : isTransientSandboxError(error),
-  ));
-}
-
-/** Delete a snapshot by id on the named provider. No live sandbox needed. */
-export async function deleteSandboxSnapshot(provider: SandboxProviderName, snapshotId: string): Promise<void> {
-  const def = SANDBOX_PROVIDERS[provider];
-  if (!def?.deleteSnapshot) throw new Error(`Provider "${provider}" does not support deleteSnapshot`);
-  const missing = Object.entries(def.requiredEnv)
-    .filter(([k]) => !process.env[k])
-    .map(([k, desc]) => `  ${k} — ${desc}`);
-  if (missing.length > 0) throw new Error(`Sandbox provider "${provider}" requires env vars:\n${missing.join("\n")}`);
-  return def.deleteSnapshot(snapshotId, Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!])));
-}
-
-/**
- * Does `snapshotId` resolve on the named provider for this account? A cheap
- * metadata lookup — never provisions a sandbox. `true` = resolves, `false` =
- * provider says it does not exist. Transport/credential errors propagate (an
- * indeterminate result is not "missing"). Used at server boot to validate the
- * platform base snapshots the default templates boot from.
- */
-export async function snapshotResolves(provider: SandboxProviderName, snapshotId: string): Promise<boolean> {
-  const def = SANDBOX_PROVIDERS[provider];
-  if (!def?.snapshotExists) throw new Error(`Provider "${provider}" does not support snapshotExists`);
-  const missing = Object.entries(def.requiredEnv)
-    .filter(([k]) => !process.env[k])
-    .map(([k, desc]) => `  ${k} — ${desc}`);
-  if (missing.length > 0) throw new Error(`Sandbox provider "${provider}" requires env vars:\n${missing.join("\n")}`);
-  return def.snapshotExists(snapshotId, Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!])));
-}
-
-/**
- * Current active-sandbox count per configured provider, for quota gauges.
- * Skips providers whose required env isn't set or which don't implement
- * `getActiveCount`. Errors are surfaced per-provider so one flaky provider
- * doesn't silence the rest.
- */
-export type SandboxQuotaResult = Partial<Record<SandboxProviderName, number | Error>>;
-
-export async function getSandboxQuotas(): Promise<SandboxQuotaResult> {
-  const out: SandboxQuotaResult = {};
-  await Promise.all(
-    (Object.entries(SANDBOX_PROVIDERS) as Array<[SandboxProviderName, SandboxProviderDef]>).map(async ([name, def]) => {
-      if (!def.getActiveCount) return;
-      if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return;
-      const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!]));
-      try { out[name] = await def.getActiveCount(env); }
-      catch (err) { out[name] = err instanceof Error ? err : new Error(String(err)); }
-    }),
-  );
-  return out;
-}
-
-/**
- * List every alive sandbox owned by this fleet, across all configured
- * providers — the orphan-reconciler SoT. Providers without `listOwned`
- * or missing env are skipped. Errors propagate per-provider so one flaky
- * provider doesn't silence the rest.
- */
-export type OwnedSandboxResult = Partial<Record<SandboxProviderName, OwnedSandbox[] | Error>>;
-
-export async function listOwnedSandboxes(): Promise<OwnedSandboxResult> {
-  const out: OwnedSandboxResult = {};
-  await Promise.all(
-    (Object.entries(SANDBOX_PROVIDERS) as Array<[SandboxProviderName, SandboxProviderDef]>).map(async ([name, def]) => {
-      if (!def.listOwned) return;
-      if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return;
-      const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k]!]));
-      try { out[name] = await def.listOwned(env); }
-      catch (err) { out[name] = err instanceof Error ? err : new Error(String(err)); }
-    }),
-  );
-  return out;
-}
-
-/** Kill a sandbox by provider + native ID. Used by the orphan reconciler. */
-export async function killSandboxById(provider: SandboxProviderName, sandboxId: string): Promise<void> {
-  const def = SANDBOX_PROVIDERS[provider];
-  if (!def?.reconnect) throw new Error(`Provider "${provider}" does not support reconnect (required for kill-by-id)`);
-  const sb = await def.reconnect(sandboxId);
-  await sb.kill();
-}
-
-/** Kill all sandboxes across all registered providers. Call at startup to clean up after crashes. */
-export async function killAllSandboxes(
-  onError?: (provider: SandboxProviderName, err: unknown) => void,
-): Promise<void> {
-  await Promise.allSettled(
-    (Object.entries(SANDBOX_PROVIDERS) as Array<[SandboxProviderName, SandboxProviderDef]>)
-      .filter(([, def]) => def.killAll)
-      .map(([name, def]) => {
-        const env = Object.fromEntries(Object.keys(def.requiredEnv).map(k => [k, process.env[k] ?? ""]));
-        if (Object.keys(def.requiredEnv).some(k => !process.env[k])) return Promise.resolve();
-        return def.killAll!(env).catch(err => onError?.(name, err));
-      }),
-  );
-}
-
-export { SANDBOX_PROVIDERS };
+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 {
+  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";
+
+export { parseSseExecStream } from "./sandbox/exec-stream.js";
+export type { ParseSseExecStreamOptions } from "./sandbox/exec-stream.js";
+
+export { makeSandboxProvider } from "./sandbox/providers/e2b.js";
+export { makeDesktopSandboxProvider } from "./sandbox/providers/desktop.js";
+export { VERCEL_MAX_TAGS, buildVercelTags } from "./sandbox/providers/vercel.js";
+export { makeLocalSandboxProvider } from "./sandbox/providers/local.js";
+
+export {
+  SANDBOX_PROVIDERS,
+  createSandbox,
+  reconnectSandbox,
+  deleteSandboxSnapshot,
+  snapshotResolves,
+  getSandboxQuotas,
+  listOwnedSandboxes,
+  killSandboxById,
+  killAllSandboxes,
+} from "./sandbox/registry.js";
+export type { SandboxProviderName, SandboxQuotaResult, OwnedSandboxResult } from "./sandbox/registry.js";