@agent-compose/sdk 0.6.0 → 0.8.0

package/src/sandbox/providers/e2b.ts

@@ -0,0 +1,354 @@
+/**
+ * E2B sandbox provider — the generic E2B command/file wrapper
+ * (`makeSandboxProvider`, shared with the desktop provider), the E2B-specific
+ * provider with background launch + native VM-suspend, and the "e2b"
+ * registry entry.
+ */
+
+import { Sandbox } from "e2b";
+import type { CommandHandle } from "e2b";
+import type { Sandbox as Desktop } from "@e2b/desktop";
+import pRetry from "p-retry";
+import type {
+  SandboxProvider, SandboxCommandRunOptions, SandboxBackgroundProcess, SandboxPtyHandle,
+} from "../../types/sandbox.js";
+import { toE2bNetwork } from "../network-policy.js";
+import { DEFAULT_SANDBOX_SIZE, e2bBaseTemplate, isE2bSupportedSize } from "../sizes.js";
+import { AGENT_COMPOSE_TAG } from "../provider-def.js";
+import type { OwnedSandbox, SandboxProviderDef } from "../provider-def.js";
+
+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);
+      },
+      // Read over the envd HTTP API (`Sandbox.files.read` → `GET /files`), a
+      // DIFFERENT transport from `commands` (the connect-web gRPC stream). A large
+      // readback over HTTP is decoded by `fetch`'s native `Content-Encoding`
+      // handling, so it is immune to the connect-web "received unsupported
+      // compressed output" failure that can abort `commands.run` output on a big
+      // frame — the property `launchStep` relies on to recover full logs.
+      async read(path) {
+        return await (sb.files.read as (p: string) => Promise<string>)(path);
+      },
+    },
+    // e2b 2.30 `kill()` returns Promise<boolean>; our provider contract is
+    // Promise<void>, so discard the result.
+    async kill() { await sb.kill(); },
+    // ADR-0052 §4.1: E2B natively forwards a port to a public `*.e2b.app`
+    // host. Pure string op (no network round-trip, no retry). This host is
+    // the RAW capability — the server's member-gated preview proxy resolves
+    // it server-side and never hands it to a browser.
+    getHost(port) { return sb.getHost(port); },
+  };
+}
+
+/** 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. */
+export function e2bMaxSandboxMs(): number {
+  return Number(process.env.E2B_MAX_SANDBOX_MS) || 60 * 60 * 1000;
+}
+
+/** 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(); },
+  };
+}
+
+/** Wrap an E2B PTY `CommandHandle` as a provider-agnostic PTY handle, wiring
+ *  `onExit` off `wait()` — which settles when the PTY process ends, however
+ *  it ends (resolve and reject both mean "gone"). A `disconnect()`ed handle's
+ *  `wait()` also settles, but by then the broker's socket is closed and its
+ *  `onExit` is a guarded no-op. Shared by `createPty` and `connectPty` so the
+ *  two attach paths return identical handles. */
+function wrapE2bPtyHandle(
+  sb: Sandbox, handle: CommandHandle, onExit: (() => void) | undefined,
+): SandboxPtyHandle {
+  void handle.wait().catch(() => undefined).finally(() => onExit?.());
+  return {
+    pid: handle.pid,
+    sendInput: (data) => sb.pty.sendInput(handle.pid, data),
+    resize: (size) => sb.pty.resize(handle.pid, size),
+    kill: async () => { await sb.pty.kill(handle.pid); },
+    // Stream detach WITHOUT killing: the guest PTY keeps running (and
+    // survives a VM pause); `sb.pty.connect(pid)` re-attaches later.
+    disconnect: async () => { await handle.disconnect(); },
+  };
+}
+
+/** 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);
+      },
+    },
+    // ADR-0055: the brokered session terminal. E2B's native `sb.pty` opens a
+    // real PTY in the guest; the server's pty broker splices it to a browser
+    // WebSocket. E2B-only — presence is the capability flag (like
+    // runBackground); Vercel/local leave it undefined.
+    async createPty(opts) {
+      const handle = await sb.pty.create({
+        cols: opts.cols,
+        rows: opts.rows,
+        ...(opts.cwd ? { cwd: opts.cwd } : {}),
+        envs: { TERM: "xterm-256color", ...(opts.envs ?? {}) },
+        onData: opts.onData,
+        // No provider-side lifetime cap — the PTY lives until an explicit
+        // kill (it survives handle disconnects), or freezes/thaws with the
+        // VM's pause.
+        timeoutMs: 0,
+      });
+      return wrapE2bPtyHandle(sb, handle, opts.onExit);
+    },
+    // ADR-0055 §7 rework: silent terminal reattach. `sb.pty.connect(pid)`
+    // resumes the output stream of a PTY an earlier handle disconnected
+    // from. PtyConnectOpts accepts only onData/timeoutMs (+ request
+    // plumbing) — the process already exists, so cols/rows/cwd/envs from
+    // SandboxPtyOpts don't apply here; the server re-asserts geometry via
+    // `resize` after connect (the repaint jiggle). Throws when no PTY with
+    // that pid is running — the caller's alive-probe races are its problem.
+    async connectPty(pid, opts) {
+      const handle = await sb.pty.connect(pid, {
+        onData: opts.onData,
+        timeoutMs: 0,
+      });
+      return wrapE2bPtyHandle(sb, handle, opts.onExit);
+    },
+    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 };
+    },
+    // The provider kill-clock seam: e2b's `setTimeout` REPLACES the deadline
+    // (extend or reduce) relative to now. The server's session lifecycle
+    // keeps this behind its own suspend clock so the deferred pause always
+    // wins the race against the create-time timeout.
+    async extendLifetime(ms) {
+      await sb.setTimeout(ms);
+    },
+    // 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));
+    },
+  };
+}
+
+async function listOwned(): Promise<OwnedSandbox[]> {
+  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;
+}
+
+export const e2bProviderDef: SandboxProviderDef = {
+  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 listOwned()).length,
+  listOwned,
+  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 });
+  },
+};

package/src/sandbox/providers/local.ts

@@ -0,0 +1,106 @@
+/**
+ * Local provider (runner's own VM).
+ */
+
+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 type { SandboxProvider } from "../../types/sandbox.js";
+
+/** 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 read(path) {
+        return await fs.readFile(path, "utf8");
+      },
+    },
+    async kill() { /* caller IS the sandbox — killing it is the server's job */ },
+  };
+}