@molecule/api-code-sandbox-e2b 1.0.4 → 1.2.0

package/dist/provider.js

@@ -12,6 +12,22 @@
 const DEFAULT_PREVIEW_PORT = 5173;
 /** Default sandbox lifetime before E2B auto-pauses (control plane extends per heartbeat). */
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
+/**
+ * Default lifetime for a spawned process. The SDK's own default is 60 s, which
+ * is a sane cap for a one-shot command and useless for the things `spawn` is
+ * for — a language server or a terminal session that must survive as long as the
+ * editor tab does.
+ */
+const DEFAULT_SPAWN_TIMEOUT_MS = 60 * 60 * 1000;
+/**
+ * How long to wait for a started command before ASKING whether it is still
+ * running. Long enough that an ordinary command simply finishes first; short
+ * enough that a launch whose stream is held open by a stranded descendant costs
+ * this instead of the caller's whole timeout.
+ */
+const SETTLE_PROBE_MS = 1_500;
+/** Default lifetime for a PTY session; same reasoning as {@link DEFAULT_SPAWN_TIMEOUT_MS}. */
+const DEFAULT_PTY_TIMEOUT_MS = 60 * 60 * 1000;
 /**
  * E2B's "all destinations" selector (`0.0.0.0/0`, the SDK's `ALL_TRAFFIC`).
  * Put in `denyOut` alongside an `allowOut` list to make egress deny-by-default —
@@ -28,12 +44,32 @@ const EGRESS_PROBE_DENY = 'example.com';
  * Imported lazily so the SDK is only required when the bond is actually used.
  */
 async function defaultClient(apiKey) {
-    const { Sandbox } = await import('e2b');
+    const { Sandbox, SandboxNotFoundError, Volume: VolumeClass } = await import('e2b');
     const S = Sandbox;
+    const V = VolumeClass;
     return {
         create: (templateId, opts) => S.create(templateId, { apiKey, ...opts }),
         connect: (id, opts) => S.connect(id, { apiKey, ...opts }),
         kill: (id, opts) => S.kill(id, { apiKey, ...opts }),
+        getInfo: (id, opts) => S.getInfo(id, { apiKey, ...opts }),
+        createVolume: (name) => V.create(name, { apiKey }),
+        listVolumes: () => V.list({ apiKey }),
+        destroyVolume: (volumeId) => V.destroy(volumeId, { apiKey }),
+        createSnapshot: (sandboxId, name) => S.createSnapshot(sandboxId, { apiKey, name }),
+        async listSnapshots(opts) {
+            const pager = S.listSnapshots({ apiKey, ...opts });
+            const out = [];
+            do {
+                out.push(...(await pager.nextItems()));
+            } while (pager.hasNext && !opts?.limit);
+            return out;
+        },
+        deleteSnapshot: (snapshotId) => S.deleteSnapshot(snapshotId, { apiKey }),
+        // The SDK raises `SandboxNotFoundError` from `getInfo`/`connect` for exactly
+        // one condition — the API answered 404 — and routes every other failure to a
+        // different class. That makes it a POSITIVE not-found, which is the whole
+        // basis for `get()` returning null.
+        isNotFound: (error) => error instanceof SandboxNotFoundError,
         async list(opts) {
             // Sandbox.list returns a paginator; normalize to a flat array of running
             // sandboxes. Support the async-iterator, nextItems(), and array shapes so
@@ -41,9 +77,19 @@ async function defaultClient(apiKey) {
             const result = S.list({ apiKey, ...opts });
             const out = [];
             const push = (items) => {
+                // Carry the listed state through: it is the only way a caller can skip a
+                // PAUSED sandbox, and building a handle for one would resume it. `name`
+                // (the SDK's template alias) and `volumeMounts` come along for the same
+                // reason: they are how "is this snapshot/volume still in use?" is
+                // OBSERVED rather than assumed, and a wrong answer there is data loss.
                 for (const it of items)
                     if (it?.sandboxId)
-                        out.push({ sandboxId: it.sandboxId });
+                        out.push({
+                            sandboxId: it.sandboxId,
+                            state: it.state,
+                            name: it.name,
+                            volumeMounts: it.volumeMounts,
+                        });
             };
             const r = await Promise.resolve(result).catch(() => result);
             if (Array.isArray(r)) {
@@ -67,6 +113,30 @@ async function defaultClient(apiKey) {
         },
     };
 }
+/**
+ * The caller's own name for a snapshot, recovered from E2B's namespaced form.
+ *
+ * E2B answers with `<team-slug>/<name>:<tag>` — a reference the caller never
+ * supplied and must never have to parse. This is the one place that translation
+ * lives, so `templateId` means the same string going in and coming out.
+ *
+ * @param snapshot - The snapshot as E2B reported it.
+ * @returns The bare name.
+ */
+function bareSnapshotName(snapshot) {
+    const full = snapshot.names?.[0] ?? snapshot.snapshotId;
+    const withoutTag = full.includes(':') ? full.slice(0, full.lastIndexOf(':')) : full;
+    return withoutTag.includes('/') ? withoutTag.slice(withoutTag.lastIndexOf('/') + 1) : withoutTag;
+}
+/**
+ * Single-quote a value for POSIX `sh` so an arbitrary path is one argument.
+ *
+ * @param value - The raw string.
+ * @returns The quoted string.
+ */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
 /**
  * Build a deny-by-default network update from an allow-list.
  *
@@ -76,6 +146,49 @@ async function defaultClient(apiKey) {
 function denyByDefault(allowOut) {
     return { allowOut, denyOut: [ALL_TRAFFIC] };
 }
+/**
+ * Whether an error means the sandbox POSITIVELY does not exist.
+ *
+ * Asks the client (the real one compares against the SDK's own
+ * `SandboxNotFoundError` class), and falls back to the error's `name` so an
+ * injected/duck-typed client — or an SDK loaded twice under different module
+ * instances, where `instanceof` silently fails — is still classified correctly.
+ * Everything else is a failure to LOOK and must propagate.
+ *
+ * @param client - The client the error came from.
+ * @param error - The thrown value.
+ * @returns True only for a not-found.
+ */
+function isNotFound(client, error) {
+    if (client.isNotFound?.(error))
+        return true;
+    return error?.name === 'SandboxNotFoundError';
+}
+/**
+ * Map an E2B sandbox record onto the core's coarse lifecycle status.
+ *
+ * E2B has exactly two states. `paused` is a filesystem + memory snapshot, which
+ * is what the core calls `sleeping` — NOT `stopped`, because a resume brings the
+ * process tree back with it and callers branch on that.
+ *
+ * @param state - The SDK's `state` field.
+ * @returns The core status.
+ */
+function toCoreStatus(state) {
+    return state === 'paused' ? 'sleeping' : 'running';
+}
+/**
+ * Normalize an SDK date field (a `Date`, an ISO string, or absent) to ISO.
+ *
+ * @param value - The SDK value.
+ * @returns An ISO 8601 string, or `null`.
+ */
+function toIso(value) {
+    if (!value)
+        return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
 /**
  * A live E2B sandbox mapped onto the core `Sandbox` handle.
  *
@@ -136,19 +249,33 @@ class E2BSandbox {
     /**
      * Pause the sandbox (E2B FS + memory snapshot).
      *
+     * Either the sandbox ends up suspended or this THROWS. It must never return a
+     * success-shaped outcome for a sandbox that is still running: the caller's next
+     * act is to record the sandbox as stopped, and a control plane that believes a
+     * running sandbox is asleep bills for it and — where the timeout kills rather
+     * than pauses — watches it die at its deadline instead of hibernating.
+     *
      * @returns The outcome; `processesPreserved` is true because the memory
      *   snapshot restores the process tree on resume.
+     * @throws {Error} When the SDK exposes no pause at all, or the pause call fails.
      */
     async hibernate() {
-        const pause = this.sbx.betaPause ?? this.sbx.pause;
+        // Prefer the supported method; `betaPause` is its deprecated alias and
+        // delegates to the same endpoint.
+        const pause = this.sbx.pause ?? this.sbx.betaPause;
         if (!pause) {
-            // No pause available — nothing we can honestly suspend; report it.
-            return { processesPreserved: true, mechanism: 'noop', detail: 'pause not supported by SDK' };
+            throw new Error('hibernate: this e2b SDK build exposes neither pause() nor betaPause(); the sandbox is still running');
         }
-        await pause.call(this.sbx);
+        // `false` means the API answered 409 — it was already paused. That is the
+        // requested end state, so it is a success, just not one this call caused.
+        const paused = await pause.call(this.sbx);
         this.status = 'sleeping';
         // E2B pause snapshots FS + memory, so the process tree survives resume.
-        return { processesPreserved: true, mechanism: 'pause' };
+        return {
+            processesPreserved: true,
+            mechanism: 'pause',
+            ...(paused === false ? { detail: 'the sandbox was already paused' } : {}),
+        };
     }
     /**
      * Resume the sandbox by reconnecting to a fresh live instance for its id.
@@ -163,6 +290,66 @@ class E2BSandbox {
         this.previewUrl = this.getPreviewUrl();
         return { processesPreserved: true, mechanism: 'resume' };
     }
+    /**
+     * Wait for a started command, and stop waiting once the command is OVER.
+     *
+     * `wait()` resolves when the output STREAM ends, which is not the same event
+     * as the command finishing: a launch that leaves anything behind holding the
+     * inherited stdio — a mis-composed `guard && nohup … &`, a daemon that does not
+     * close its descriptors, a user's `npm run dev &` — keeps that stream open long
+     * after the process exited, and the caller then blocks for its whole timeout on
+     * a command that finished in milliseconds. Three sidecar launches per boot cost
+     * 15 s that way.
+     *
+     * So when the wait outlives a short settle window, this ASKS the sandbox
+     * whether the started pid is still there. Gone means the command is over and
+     * the accumulated output is the whole of it; alive means it is genuinely still
+     * running and the caller's own timeout is the right bound. Never a guess from
+     * the shape of the command.
+     *
+     * @param handle - The started command.
+     * @returns The command's result.
+     */
+    async waitForCommand(handle) {
+        let settled = false;
+        const finished = handle.wait().finally(() => {
+            settled = true;
+        });
+        const raced = await Promise.race([
+            finished,
+            new Promise((resolve) => setTimeout(() => resolve(null), SETTLE_PROBE_MS)),
+        ]);
+        if (raced)
+            return raced;
+        if (settled)
+            return finished;
+        const alive = await this.isProcessAlive(handle.pid);
+        if (alive)
+            return finished;
+        // The process is gone; whatever still holds the stream is not it.
+        return {
+            stdout: handle.stdout ?? '',
+            stderr: handle.stderr ?? '',
+            exitCode: handle.exitCode ?? 0,
+        };
+    }
+    /**
+     * Ask the sandbox whether a pid is still running.
+     *
+     * @param pid - The process id to check.
+     * @returns True when the process exists; true also when the check itself could
+     *   not run, because "I could not look" must never be reported as "it is gone".
+     */
+    async isProcessAlive(pid) {
+        try {
+            const probe = await this.sbx.commands.run(`kill -0 ${Math.floor(pid)} 2>/dev/null && echo MOL_ALIVE || echo MOL_GONE`, { timeoutMs: 10_000, background: true });
+            const result = await probe.wait();
+            return !result.stdout.includes('MOL_GONE');
+        }
+        catch (_error) {
+            return true;
+        }
+    }
     /**
      * Run a command to completion in the sandbox.
      *
@@ -178,27 +365,37 @@ class E2BSandbox {
      * @returns stdout, stderr and the exit code (even when non-zero).
      */
     async exec(command, opts) {
-        // A shell-backgrounded command (`… &` / `… & true`) must NOT block exec —
-        // that is the whole point of `&`. E2B's `commands.run` waits for the process
-        // group anyway (a detached `nohup`/`setsid` dev-server launch times out the
-        // request), so route backgrounded commands through the SDK's native
-        // `background: true`, which returns immediately. The control plane launches
-        // every dev server this way (`nohup sh -c '…' >log 2>&1 & true`), so this
-        // makes the provider-agnostic launch code work unchanged on E2B.
-        if (/&\s*(?:true\s*)?$/.test(command)) {
-            await this.sbx.commands.run(command, {
-                cwd: opts?.cwd,
-                envs: opts?.env,
-                background: true,
-            });
-            return { stdout: '', stderr: '', exitCode: 0 };
-        }
+        // START the command, then wait on its HANDLE — never `run()` inline.
+        //
+        // Inline `run()` waits for the process GROUP, so any command that leaves a
+        // detached child behind (`nohup … & true`, and every dev-server launch on
+        // this platform) blocks until the request deadline and then throws, while
+        // the child is in fact running fine. The bond used to dodge that by
+        // sniffing the command string for a trailing `&` and returning a fabricated
+        // `exitCode: 0` — which classified the shell text instead of observing the
+        // process, so it lied twice: a launch shaped `… & fi` (an `if` guard around
+        // the `&`) did not match and hung for the full timeout, and a user's
+        // `npm run build &` in the terminal reported instant success with no output
+        // whether or not it started.
+        //
+        // The handle removes the guesswork: `wait()` resolves when the STARTED
+        // process exits, so a detached launch returns in milliseconds WITH its real
+        // exit code, and an ordinary command still returns its full stdout/stderr.
+        // Verified live against E2B: a `nohup … >log 2>&1 &` launch returns in
+        // ~200 ms with the child still running, and its deadline does not kill it.
         try {
-            const r = await this.sbx.commands.run(command, {
+            const handle = await this.sbx.commands.run(command, {
                 cwd: opts?.cwd,
                 timeoutMs: opts?.timeout,
                 envs: opts?.env,
+                background: true,
             });
+            // The core contract is RETURN, not throw: a non-zero exit is data
+            // (`exitCode`), not an error — control-plane code reads it to decide
+            // (install sentinels, health probes, existence checks). E2B raises
+            // `CommandExitError` for that, so it is caught and mapped below; only a
+            // genuine infrastructure failure (no `.result`) rethrows.
+            const r = await this.waitForCommand(handle);
             return { stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode };
         }
         catch (error) {
@@ -210,6 +407,132 @@ class E2BSandbox {
             throw error;
         }
     }
+    /**
+     * Spawn a long-running process with streaming I/O, optionally on a PTY.
+     *
+     * This is the capability an interactive terminal and a language server need
+     * and `exec` cannot provide: a process that outlives the call, streams as it
+     * runs, takes input, and can be killed. Without it the IDE has no editor
+     * intelligence at all (the LSP socket closes 4003 "Sandbox does not support
+     * spawn") and no cancellable terminal.
+     *
+     * With {@link SpawnOptions.pty} the process gets a real controlling terminal,
+     * so Ctrl-C (`0x03`) becomes SIGINT for the foreground job and `resize()`
+     * renegotiates the width. Without it, stdio is plain pipes — which is what a
+     * language server requires, since a PTY would echo input and translate
+     * newlines straight through its framed JSON-RPC.
+     *
+     * A PTY request is REJECTED rather than downgraded when the SDK build has no
+     * `pty` module: a terminal that silently got pipes is a terminal whose Ctrl-C
+     * does nothing, and the caller must be able to tell.
+     *
+     * @param command - The command to run. Ignored when a PTY is requested — E2B
+     *   starts the user's login shell on the PTY, which is the point.
+     * @param opts - Working directory, env, timeout, and optional PTY size.
+     * @returns A handle with streaming I/O, stdin, kill, and (on a PTY) resize.
+     */
+    async spawn(command, opts) {
+        const stdoutListeners = [];
+        const stderrListeners = [];
+        const closeListeners = [];
+        let closed = false;
+        const fireClose = () => {
+            if (closed)
+                return;
+            closed = true;
+            for (const cb of closeListeners)
+                cb();
+        };
+        const emit = (listeners, data) => {
+            for (const cb of listeners)
+                cb(data);
+        };
+        let handle;
+        let resize;
+        if (opts?.pty) {
+            const pty = this.sbx.pty;
+            if (!pty) {
+                throw new Error('E2B SDK build does not expose a pty module; cannot spawn a terminal');
+            }
+            const decoder = new TextDecoder();
+            handle = await pty.create({
+                cols: opts.pty.cols,
+                rows: opts.pty.rows,
+                cwd: opts.cwd,
+                envs: opts.env,
+                // A terminal must outlive the default 60 s command deadline; the caller
+                // decides how long a session may sit idle.
+                timeoutMs: opts.timeout ?? DEFAULT_PTY_TIMEOUT_MS,
+                // A PTY merges stderr into the terminal stream by definition — there is
+                // one file descriptor, which is why a terminal shows them interleaved.
+                onData: (data) => emit(stdoutListeners, decoder.decode(data, { stream: true })),
+            });
+            const pid = handle.pid;
+            resize = (size) => {
+                void pty.resize(pid, size).catch((_error) => {
+                    // Best-effort: a resize races the process exiting, and a failed one
+                    // only means the remote width is stale — never a reason to tear down
+                    // a live session.
+                });
+            };
+        }
+        else {
+            handle = await this.sbx.commands.run(command, {
+                cwd: opts?.cwd,
+                envs: opts?.env,
+                timeoutMs: opts?.timeout ?? DEFAULT_SPAWN_TIMEOUT_MS,
+                background: true,
+                stdin: true,
+                onStdout: (data) => emit(stdoutListeners, data),
+                onStderr: (data) => emit(stderrListeners, data),
+            });
+        }
+        // `wait()` settles when the process exits, however it exited (including the
+        // deadline), so it is the one signal that covers every close path.
+        handle
+            .wait()
+            .then(fireClose)
+            .catch((_error) => {
+            // A non-zero exit / timeout rejects here; for a spawn the only fact that
+            // matters is that the process is over, and the caller learns it the same
+            // way either way.
+            fireClose();
+        });
+        const encoder = new TextEncoder();
+        const ptyPid = opts?.pty ? handle.pid : null;
+        const pty = this.sbx.pty;
+        return {
+            write: (data) => {
+                const write = ptyPid !== null && pty
+                    ? pty.sendInput(ptyPid, encoder.encode(data))
+                    : handle.sendStdin(data);
+                void write.catch((_error) => {
+                    // The process may have exited between the caller's check and this
+                    // write; `onClose` is what tells them, so a lost keystroke on a dead
+                    // process must not throw into an event handler.
+                });
+            },
+            onStdout: (cb) => {
+                stdoutListeners.push(cb);
+            },
+            onStderr: (cb) => {
+                stderrListeners.push(cb);
+            },
+            onClose: (cb) => {
+                closeListeners.push(cb);
+                if (closed)
+                    cb();
+            },
+            kill: () => {
+                const killed = ptyPid !== null && pty ? pty.kill(ptyPid) : handle.kill();
+                void killed.catch((_error) => {
+                    // Already gone / unreachable — kill is idempotent from the caller's
+                    // point of view, and `onClose` still fires from `wait()`.
+                });
+            },
+            ...(resize ? { resize } : {}),
+        };
+    }
     /**
      * Read a file's contents as text.
      *
@@ -316,7 +639,7 @@ class E2BSandbox {
             chunks.push(chunk);
         const tarPath = `/tmp/mol-import-${Date.now().toString(36)}.tar`;
         await this.sbx.files.write(tarPath, new Blob([Buffer.concat(chunks)]));
-        const r = await this.sbx.commands.run(`mkdir -p ${path} && tar xf ${tarPath} -C ${path} --no-same-owner --no-same-permissions && rm -f ${tarPath}`, { timeoutMs: 300_000 });
+        const r = await this.sbx.commands.run(`mkdir -p ${shellQuote(path)} && tar xf ${tarPath} -C ${shellQuote(path)} --no-same-owner --no-same-permissions && rm -f ${tarPath}`, { timeoutMs: 300_000 });
         if (r.exitCode !== 0) {
             throw new Error(`importFiles: tar extract failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
         }
@@ -326,14 +649,30 @@ class E2BSandbox {
      *
      * Tars the tree in-sandbox, reads it back as bytes, and yields it as a single
      * chunk. Sufficient for archive/migrate (whole-workspace capture); not a
-     * chunked pipe.
+     * chunked pipe — the whole archive is held in this process's memory once, so
+     * callers moving large trees must bound what they export.
      *
-     * @param path - Absolute path inside the sandbox to archive.
+     * Entries are rooted at the LAST SEGMENT of `path` (`tar -C <parent>
+     * <name>`), so `exportFiles('/workspace/my-app')` yields `my-app/…` — the
+     * shape Docker's archive endpoint produces and the shape every consumer
+     * (`importFiles(<parent>)`, host-side unpackers with `strip: 1`) expects.
+     * The previous `tar -C <path> .` rooting yielded `./…`, which
+     * `importFiles('/')` extracted at the filesystem root instead of the
+     * directory it was taken from.
+     *
+     * @param path - Absolute path inside the sandbox to archive (not `/`).
      * @returns A POSIX tar byte stream of that path's contents.
      */
     async exportFiles(path) {
+        const trimmed = path.replace(/\/+$/, '');
+        const slash = trimmed.lastIndexOf('/');
+        const parent = slash <= 0 ? '/' : trimmed.slice(0, slash);
+        const name = trimmed.slice(slash + 1);
+        if (!trimmed.startsWith('/') || !name) {
+            throw new Error(`exportFiles: path must be an absolute directory below "/" (got "${path}")`);
+        }
         const tarPath = `/tmp/mol-export-${Date.now().toString(36)}.tar`;
-        const r = await this.sbx.commands.run(`tar cf ${tarPath} -C ${path} .`, { timeoutMs: 300_000 });
+        const r = await this.sbx.commands.run(`tar cf ${tarPath} -C ${shellQuote(parent)} ${shellQuote(name)}`, { timeoutMs: 300_000 });
         if (r.exitCode !== 0) {
             throw new Error(`exportFiles: tar create failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
         }
@@ -415,16 +754,45 @@ export class E2BSandboxProvider {
     /**
      * Create a new sandbox from the golden template and apply the egress policy.
      *
-     * @param config - Project id, env, optional per-boot templateId + labels.
+     * The sandbox is created to PAUSE at its timeout, not to be killed. E2B's
+     * default is `onTimeout: 'kill'`, which means a sandbox nothing has touched for
+     * its lifetime is destroyed — and on this platform the sandbox is the only copy
+     * of the project, so the default turns "the tab was closed over lunch" into
+     * permanent data loss. `keepMemory` stays on: the pause snapshot restores the
+     * process tree, which is what makes `resume()` honest when it reports
+     * `processesPreserved: true`. A filesystem-only snapshot would cold-boot
+     * instead, leaving a sandbox that is running with every dev server dead.
+     *
+     * `config.volumeName` mounts a persistent volume, which E2B can only attach at
+     * CREATE time — there is no attach-to-a-running-sandbox call — so a sandbox
+     * claimed from a pre-warmed pool can never be given one afterwards. A mount
+     * path is REQUIRED alongside it: E2B mounts shadow whatever the image had at
+     * that path, and this bond's superset template keeps a 2.4 GB
+     * `/workspace/node_modules` there, so defaulting to the workspace root would
+     * hide the entire dependency fleet behind an empty volume and boot a project
+     * that cannot resolve a single import.
+     *
+     * @param config - Project id, env, optional per-boot templateId + labels, and
+     *   an optional `volumeName` + `volumeMountPath` pair.
      * @returns A live sandbox handle.
      */
     async create(config) {
         const client = await this.client();
         const templateId = config.templateId ?? this.config.templateId;
+        if (config.volumeName && !config.volumeMountPath) {
+            // Refusing beats guessing: the only default that could be picked here is
+            // the workspace root, and that is the one value which silently breaks the
+            // sandbox it was meant to protect.
+            throw new Error(`E2B requires a volumeMountPath alongside volumeName ("${config.volumeName}"): a volume mounted at the workspace root would shadow the template's node_modules`);
+        }
         const sbx = await client.create(templateId, {
             timeoutMs: this.config.defaultTimeoutMs,
             envs: config.env ?? {},
             metadata: { projectId: config.projectId, ...(config.labels ?? {}) },
+            lifecycle: { onTimeout: { action: 'pause', keepMemory: true } },
+            ...(config.volumeName
+                ? { volumeMounts: { [config.volumeMountPath]: config.volumeName } }
+                : {}),
         });
         const handle = new E2BSandbox(sbx, client, {
             previewPort: this.config.defaultPreviewPort,
@@ -451,12 +819,68 @@ export class E2BSandboxProvider {
                 timeoutMs: this.config.defaultTimeoutMs,
             });
         }
-        catch (_error) {
-            // connect throws SandboxNotFoundError for a genuinely absent id → null.
-            // A transient error also lands here; get() is used as an existence probe,
-            // and the callers re-resolve, so returning null is the safe answer.
-            return null;
+        catch (error) {
+            // `null` means the sandbox is GONE, and nothing else. Every other failure
+            // THROWS. This used to swallow all of them, and the cost of that is not
+            // hypothetical: a control plane reads `null` as "the container is gone",
+            // detaches the project, and rebuilds it from a template — so one 5xx from
+            // this API destroyed a user's only copy of their code. "I could not look"
+            // must never be delivered as "I looked, and it is not there".
+            if (isNotFound(client, error))
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * Read a sandbox's record WITHOUT connecting to it.
+     *
+     * The lookup a control plane polls with. `get()` cannot serve that purpose on
+     * E2B: obtaining a handle is `POST /sandboxes/{id}/connect`, which RESUMES a
+     * paused sandbox and extends its deadline — so a status poll every few seconds
+     * silently un-hibernates every sleeping project, bills for the compute, and
+     * leaves the UI showing "asleep". This reads the record instead, so `paused`
+     * stays paused and is reported as `sleeping`.
+     *
+     * `null` means the sandbox positively does not exist. A failed lookup throws,
+     * for the same reason `get()` does.
+     *
+     * @param id - The sandbox id.
+     * @returns The descriptor, or `null` when no sandbox has that id.
+     */
+    async describe(id) {
+        const client = await this.client();
+        if (!client.getInfo) {
+            // Refusing is the point: answering `null` here would report "no such
+            // sandbox" for a client that simply cannot look.
+            throw new Error('E2B client does not expose getInfo(); cannot describe a sandbox');
+        }
+        let info;
+        try {
+            info = await client.getInfo(id);
+        }
+        catch (error) {
+            if (isNotFound(client, error))
+                return null;
+            throw error;
         }
+        const startedAt = toIso(info.startedAt);
+        return {
+            id: info.sandboxId ?? id,
+            projectId: info.metadata?.projectId ?? null,
+            status: toCoreStatus(info.state),
+            labels: info.metadata ?? {},
+            // E2B has no created-but-never-started state — a sandbox exists only once
+            // it has run — so both timestamps are the same fact, and neither is ever
+            // the `null` that marks wreckage on a provider that does have one.
+            createdAt: startedAt,
+            startedAt,
+            templateRef: info.templateId ?? null,
+            volumeName: info.volumeMounts?.[0]?.name ?? null,
+            // E2B publishes every internal port at `<port>-<id>.e2b.app` rather than
+            // mapping it to a host port, so there are no mappings to report. The
+            // reachable URL comes from `getPreviewUrl(port)`.
+            ports: [],
+        };
     }
     /**
      * List the caller's live sandboxes.
@@ -470,6 +894,11 @@ export class E2BSandboxProvider {
         const items = Array.isArray(running) ? running : (running.sandboxes ?? []);
         const handles = [];
         for (const it of items) {
+            // A PAUSED sandbox is deliberately skipped: building its handle means
+            // connecting, and connecting resumes it. Enumerating an account would
+            // otherwise wake — and start billing — every hibernated project on it.
+            if (it.state === 'paused')
+                continue;
             const h = await this.get(it.sandboxId);
             if (h)
                 handles.push(h);
@@ -495,6 +924,249 @@ export class E2BSandboxProvider {
         if (sbx)
             await sbx.kill();
     }
+    /**
+     * Every sandbox that currently EXISTS, running or paused.
+     *
+     * The basis for both "is this volume attached?" and "is this snapshot in use?".
+     * Paused sandboxes are included deliberately — a paused sandbox still owns its
+     * volume and still boots from its template, and treating it as absent is how a
+     * reclamation sweep deletes the storage under a hibernated project.
+     *
+     * @returns The raw listing rows.
+     */
+    async liveSandboxes() {
+        const client = await this.client();
+        const listed = await client.list({});
+        return Array.isArray(listed) ? listed : (listed.sandboxes ?? []);
+    }
+    /**
+     * Resolve a volume by the caller's name.
+     *
+     * @param name - The volume name.
+     * @returns The volume, or `null` when the account has no volume by that name.
+     */
+    async findVolume(name) {
+        const client = await this.client();
+        if (!client.listVolumes) {
+            throw new Error('E2B client does not expose the volume API');
+        }
+        const volumes = await client.listVolumes();
+        return volumes.find((v) => v.name === name) ?? null;
+    }
+    /**
+     * Create a named volume, idempotently.
+     *
+     * Callers create the volume on EVERY boot (they cannot know whether a previous
+     * sandbox already made it), so an existing volume is a success and must not be
+     * re-created — re-creating would either fail the boot or, worse, hand back an
+     * empty volume in place of the user's files.
+     *
+     * Volumes are a private beta on E2B: an account without them answers
+     * `403 use of volumes is not enabled`, which surfaces here as a throw rather
+     * than a silent no-op, because a caller that believes it has a durable volume
+     * and does not is exactly the failure this method exists to prevent.
+     *
+     * @param name - The volume name.
+     */
+    async createVolume(name) {
+        const client = await this.client();
+        if (!client.createVolume) {
+            throw new Error('E2B client does not expose the volume API');
+        }
+        if (await this.findVolume(name))
+            return;
+        await client.createVolume(name);
+    }
+    /**
+     * Remove a named volume. Removing one that does not exist is a success.
+     *
+     * @param name - The volume name.
+     */
+    async removeVolume(name) {
+        const client = await this.client();
+        if (!client.destroyVolume) {
+            throw new Error('E2B client does not expose the volume API');
+        }
+        const volume = await this.findVolume(name);
+        if (!volume)
+            return;
+        await client.destroyVolume(volume.volumeId);
+    }
+    /**
+     * Whether a named volume exists.
+     *
+     * THROWS when it cannot look. A control plane asks this to decide whether a
+     * project's files survived losing its sandbox, and answering `false` for a
+     * failed lookup tells it the user's work is gone — the same "could not look
+     * delivered as looked-and-empty" confusion that `get()` returning `null` used
+     * to be.
+     *
+     * @param name - The volume name.
+     * @returns `true` when the account has a volume by that name.
+     */
+    async volumeExists(name) {
+        return (await this.findVolume(name)) !== null;
+    }
+    /**
+     * Enumerate volumes, reporting which ones a sandbox currently holds.
+     *
+     * `attached` is OBSERVED from the sandbox listing (running and paused alike),
+     * not assumed, because the only reason to enumerate volumes is to delete the
+     * unattached ones. E2B reports neither a creation time nor a size for a volume,
+     * so both are `null` rather than invented.
+     *
+     * @param options - Narrowing by name prefix and attachment.
+     * @returns Every matching volume.
+     */
+    async listVolumes(options) {
+        const client = await this.client();
+        if (!client.listVolumes) {
+            throw new Error('E2B client does not expose the volume API');
+        }
+        const [volumes, sandboxes] = await Promise.all([client.listVolumes(), this.liveSandboxes()]);
+        const attachedNames = new Set();
+        for (const sbx of sandboxes)
+            for (const m of sbx.volumeMounts ?? [])
+                attachedNames.add(m.name);
+        return volumes
+            .filter((v) => !options?.namePrefix || v.name.startsWith(options.namePrefix))
+            .map((v) => ({
+            name: v.name,
+            attached: attachedNames.has(v.name),
+            createdAt: null,
+            sizeBytes: null,
+        }))
+            .filter((v) => options?.attached === undefined || v.attached === options.attached);
+    }
+    /**
+     * Capture a sandbox as a reusable template, using E2B snapshots.
+     *
+     * A snapshot is a persistent image of the sandbox's filesystem AND memory that
+     * outlives the sandbox itself — verified against production: a sandbox was
+     * killed and a new one created from its snapshot came up with the same files.
+     * Re-committing the same `templateId` assigns a new build to the same snapshot
+     * rather than accumulating a second one, so a per-project restore point stays
+     * one resource no matter how often it is refreshed.
+     *
+     * Snapshotting BRIEFLY PAUSES the sandbox and drops its open connections
+     * (PTYs, command streams, websockets). Take one when the project is going
+     * quiet, not underneath a user's terminal.
+     *
+     * `capturePaths` inside a MOUNTED VOLUME are refused rather than silently
+     * omitted: E2B's snapshot images the sandbox's own disk, and a volume is
+     * storage attached from outside it. Committing anyway would produce a template
+     * that boots perfectly into a workspace missing exactly the files it was asked
+     * to preserve.
+     *
+     * @param options - The sandbox, the caller's template id, optional capture paths and label.
+     * @returns The template as it now exists.
+     */
+    async commitTemplate(options) {
+        const client = await this.client();
+        if (!client.createSnapshot) {
+            throw new Error('E2B client does not expose the snapshot API');
+        }
+        if (options.capturePaths?.length && client.getInfo) {
+            const info = await client.getInfo(options.sandboxId);
+            for (const mount of info.volumeMounts ?? []) {
+                const shadowed = options.capturePaths.find((path) => path === mount.path || path.startsWith(`${mount.path}/`));
+                if (shadowed) {
+                    throw new Error(`Cannot capture "${shadowed}" into an E2B snapshot: it is on the mounted volume "${mount.name}", which the snapshot does not image`);
+                }
+            }
+        }
+        const snapshot = await client.createSnapshot(options.sandboxId, options.templateId);
+        return {
+            id: options.templateId,
+            ref: snapshot.snapshotId,
+            createdAt: new Date().toISOString(),
+            sizeBytes: null,
+            ...(options.label === undefined ? {} : { label: options.label }),
+            inUse: true,
+        };
+    }
+    /**
+     * Look up one template by the caller's identifier.
+     *
+     * `null` means E2B has no snapshot by that name. A failed lookup throws: a
+     * caller reads `null` as "there is no restore point" and scaffolds a fresh
+     * project over the user's, so a transient API error must never wear that shape.
+     *
+     * @param templateId - The caller's identifier.
+     * @returns The template, or `null` when it does not exist.
+     */
+    async getTemplate(templateId) {
+        const client = await this.client();
+        if (!client.listSnapshots) {
+            throw new Error('E2B client does not expose the snapshot API');
+        }
+        const found = await client.listSnapshots({ name: templateId, limit: 1 });
+        const snapshot = found[0];
+        if (!snapshot)
+            return null;
+        const sandboxes = await this.liveSandboxes();
+        return {
+            id: templateId,
+            ref: snapshot.snapshotId,
+            // E2B reports neither a build time nor a size for a snapshot; `''` is the
+            // fleet's existing "unknown template timestamp" spelling (see the flyio bond).
+            createdAt: '',
+            sizeBytes: null,
+            inUse: sandboxes.some((sbx) => sbx.name === templateId),
+        };
+    }
+    /**
+     * Enumerate templates so a caller can enforce its retention policy.
+     *
+     * Throws rather than answering `[]` when it cannot enumerate — an eviction
+     * loop that reads "nothing exists" from a failed listing stops evicting, and a
+     * reconciler that reads it stops reconciling.
+     *
+     * @param options - Narrowing by id prefix.
+     * @returns Every matching template.
+     */
+    async listTemplates(options) {
+        const client = await this.client();
+        if (!client.listSnapshots) {
+            throw new Error('E2B client does not expose the snapshot API');
+        }
+        const [snapshots, sandboxes] = await Promise.all([client.listSnapshots(), this.liveSandboxes()]);
+        const inUseNames = new Set(sandboxes.map((sbx) => sbx.name).filter(Boolean));
+        return snapshots
+            .map((snapshot) => ({ id: bareSnapshotName(snapshot), snapshot }))
+            .filter(({ id }) => !options?.idPrefix || id.startsWith(options.idPrefix))
+            .map(({ id, snapshot }) => ({
+            id,
+            ref: snapshot.snapshotId,
+            createdAt: '',
+            sizeBytes: null,
+            inUse: inUseNames.has(id),
+        }));
+    }
+    /**
+     * Delete a template. Deleting one that does not exist is a success.
+     *
+     * Refuses when a sandbox still boots from it, by CHECKING the sandbox listing
+     * rather than trusting the caller. E2B enforces the same rule server-side (a
+     * `400` naming the template), which is left to surface as a throw — two
+     * independent refusals for an operation whose failure mode is destroying a
+     * running project.
+     *
+     * @param templateId - The caller's identifier.
+     */
+    async removeTemplate(templateId) {
+        const client = await this.client();
+        if (!client.deleteSnapshot) {
+            throw new Error('E2B client does not expose the snapshot API');
+        }
+        const template = await this.getTemplate(templateId);
+        if (!template)
+            return;
+        if (template.inUse) {
+            throw new Error(`Refusing to delete template "${templateId}": a sandbox is currently running from it`);
+        }
+        await client.deleteSnapshot(template.ref);
+    }
     /**
      * PROVE egress is deny-by-default by OBSERVING it on a throwaway sandbox.
      *