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

package/dist/index.js

@@ -32,21 +32,20 @@
  * const provider = createProvider({
  *   templateId: 'molecule-superset',
  *   defaultPreviewPort: 5173,
- *   defaultNetworkRules: [
- *     { domain: 'registry.npmjs.org', action: 'allow' },
- *     { domain: '*.npmjs.org', action: 'allow' },
- *     { domain: 'github.com', action: 'allow' },
- *     { domain: '*', action: 'deny' },
- *   ],
+ *   // Deny-by-default egress: everything not listed here is blocked, raw IPs
+ *   // included. An empty/omitted list applies NO policy at all.
+ *   defaultAllowOut: ['registry.npmjs.org', '*.npmjs.org', 'github.com'],
  * })
  * ```
  *
  * @remarks
- * **`verifyEgress` is intentionally not implemented yet.** The control plane
- * treats an absent `verifyEgress` as an `inconclusive` verdict and refuses to
- * boot sandboxes in production — the correct safe default until egress
- * observation is proven against E2B's `updateNetwork` policy (Rule 18: never
- * trade cost for security). Do not stub it with a fabricated `filtered`.
+ * **`verifyEgress` OBSERVES, it never attests.** It boots a throwaway sandbox,
+ * applies `{ allowOut: [npm], denyOut: [ALL_TRAFFIC] }`, and curls an
+ * allow-listed host, a non-allow-listed host AND a raw IP from inside it;
+ * `filtered` requires the last two to be blocked while the first answers. Any
+ * failure to run that probe is `inconclusive` — never `filtered`, because "I
+ * could not look" must not reach a control plane as "I looked, and it is safe"
+ * (Rule 18: never trade cost for security).
  *
  * **E2B pauses, it does not stop.** `sleep()`/`stop()` both map to E2B pause
  * (FS + memory snapshot); `wake()`/`start()` reconnect by id. `hibernate()`/
@@ -54,6 +53,94 @@
  * restores the process tree — unlike a Docker stop, a resumed E2B sandbox's
  * dev servers are still running.
  *
+ * **`get()` RESUMES a paused sandbox — use `describe()` to look at one.**
+ * Obtaining a handle is `POST /sandboxes/{id}/connect`, which resumes a paused
+ * sandbox and extends its deadline. That is right for a caller about to USE the
+ * sandbox and wrong for every status check: polling `get()` every few seconds
+ * silently un-hibernates every sleeping project and bills for the compute while
+ * the UI still says "asleep". `describe(id)` reads the record instead, reports
+ * `sleeping` for a paused sandbox, and changes nothing.
+ *
+ * **`get()` returns `null` ONLY for a sandbox that does not exist.** Every other
+ * failure throws. A control plane reads `null` as "gone", detaches the project
+ * and rebuilds it from a template — and since an E2B microVM is the only copy of
+ * a project's files, answering a transient 5xx with `null` destroys the user's
+ * code. "I could not look" must never be delivered as "I looked, and it is not
+ * there". The same rule governs `describe()`.
+ *
+ * **`hibernate()`/`stop()`/`sleep()` pause or THROW.** They never resolve a
+ * success-shaped outcome for a sandbox that is still running: a 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 — with the kill timeout — watches it die at
+ * its deadline instead of hibernating. Note the converse trap: a pause is undone by
+ * the very next `get()`, since obtaining a handle connects. Anything that polls a
+ * stopped sandbox (status, logs, files) must go through `describe()`.
+ *
+ * **`exec()` starts the command and waits on its HANDLE, never inline.** E2B's
+ * inline `commands.run` waits for the whole process GROUP, so any command that
+ * leaves a detached child behind — `nohup … >log 2>&1 &`, i.e. every dev-server
+ * launch — blocks until the request deadline and then throws while the child is
+ * running perfectly. Starting in the background and awaiting the handle returns
+ * the STARTED process's real exit code in milliseconds, so a launcher learns
+ * whether its command was accepted. Do not reintroduce the old shortcut of
+ * sniffing the command string for a trailing `&`: it classified shell text
+ * instead of observing the process, and got both halves wrong — a launch shaped
+ * `… & fi` did not match and hung, while a user's `npm run build &` was answered
+ * with a fabricated empty success.
+ *
+ * **`spawn()` is what an editor and a terminal need, and `exec()` cannot give.**
+ * It returns a live process: streaming stdout/stderr, writable stdin, `kill()`.
+ * Pass `pty: { cols, rows }` for a real controlling terminal — then Ctrl-C
+ * (`0x03`) becomes SIGINT for the foreground job and `handle.resize({cols,rows})`
+ * renegotiates the width. Omit it for a language server, whose framed JSON-RPC a
+ * PTY would corrupt with echo and CR translation. A PTY request is REJECTED
+ * rather than downgraded when the SDK build has no `pty` module, because a
+ * terminal that silently got pipes is a terminal whose Ctrl-C does nothing.
+ *
+ * **Two ways to make a project outlive its sandbox, and they are not the same
+ * strength.** A **volume** (`SandboxConfig.volumeName` + `volumeMountPath`) is
+ * continuous: every write already lives outside the microVM, so losing the
+ * sandbox loses nothing. A **snapshot** (`commitTemplate`, restored by
+ * `create({ templateId })`) is point-in-time: a persistent image that survives
+ * the sandbox, at the cost of everything written since the capture. Prefer the
+ * volume; take snapshots when the account has no volumes, or as restore points
+ * alongside one.
+ *
+ * **A volume needs a mount path, and `create()` refuses without one.** E2B
+ * mounts shadow whatever the image had at that path, and this bond's superset
+ * template keeps a multi-GB `/workspace/node_modules` there — so the obvious
+ * default (the workspace root) is the one value that boots a project unable to
+ * resolve a single import. Mount the app directory instead
+ * (`/workspace/<appDir>`): the durable source lands on the volume and the
+ * regenerable tooling stays on the faster image-backed rootfs.
+ *
+ * **A volume can only be attached when the sandbox is created.** There is no
+ * attach-to-a-running-sandbox call, so a sandbox claimed from a pre-warmed pool
+ * can never be given a project's volume afterwards — a project that needs one
+ * must be booted fresh with it.
+ *
+ * **Volumes are a private beta on E2B.** An account without them answers
+ * `403 use of volumes is not enabled` (measured on the production account,
+ * 2026-08-16); ask E2B support to enable them. Every volume method throws in
+ * that state rather than no-op-ing, because a control plane that believes it has
+ * durable storage and does not is the failure this bond exists to prevent.
+ *
+ * **Snapshots ARE available and they do survive a kill** — verified live: a
+ * sandbox was killed and a new one created from its snapshot came up with the
+ * same files, in ~2.3 s. Capturing takes well under a second, leaves the sandbox
+ * running, and re-using a name replaces that snapshot rather than adding one, so
+ * a per-project restore point is a fixed-size resource. It BRIEFLY pauses the
+ * sandbox and drops open connections (PTYs, command streams, websockets), so
+ * capture when a project goes quiet — never underneath a live terminal.
+ *
+ * **Sandboxes are created to PAUSE at their timeout, not to be killed.** E2B's
+ * default is `onTimeout: 'kill'`, so a sandbox nothing touched for its lifetime
+ * would be destroyed with its files. This bond creates every sandbox with
+ * `lifecycle: { onTimeout: { action: 'pause', keepMemory: true } }`; the memory
+ * snapshot is what lets `resume()` truthfully report `processesPreserved: true`.
+ * Extending the deadline is `keepAlive(ms)` — call it from a real activity
+ * signal (an open editor's heartbeat), never as a side effect of polling.
+ *
  * @module
  */
 export * from './provider.js';

package/dist/provider.d.ts

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { EgressVerdict, Sandbox, SandboxConfig, SandboxProvider } from '@molecule/api-code-sandbox';
+import type { CommitTemplateOptions, EgressVerdict, ListTemplatesOptions, ListVolumesOptions, Sandbox, SandboxConfig, SandboxDescriptor, SandboxProvider, SandboxTemplate, VolumeInfo } from '@molecule/api-code-sandbox';
 import type { E2BConfig, E2BSandboxClientLike } from './types.js';
 /**
  * E2B implementation of {@link SandboxProvider}.
@@ -41,7 +41,26 @@ export declare class E2BSandboxProvider implements SandboxProvider {
     /**
      * 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.
      */
     create(config: SandboxConfig): Promise<Sandbox>;
@@ -52,6 +71,23 @@ export declare class E2BSandboxProvider implements SandboxProvider {
      * @returns A live handle, or `null` if no sandbox has that id.
      */
     get(id: string): Promise<Sandbox | null>;
+    /**
+     * 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.
+     */
+    describe(id: string): Promise<SandboxDescriptor | null>;
     /**
      * List the caller's live sandboxes.
      *
@@ -65,6 +101,129 @@ export declare class E2BSandboxProvider implements SandboxProvider {
      * @param id - The sandbox id.
      */
     destroy(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    private liveSandboxes;
+    /**
+     * 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.
+     */
+    private findVolume;
+    /**
+     * 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.
+     */
+    createVolume(name: string): Promise<void>;
+    /**
+     * Remove a named volume. Removing one that does not exist is a success.
+     *
+     * @param name - The volume name.
+     */
+    removeVolume(name: string): Promise<void>;
+    /**
+     * 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.
+     */
+    volumeExists(name: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    listVolumes(options?: ListVolumesOptions): Promise<VolumeInfo[]>;
+    /**
+     * 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.
+     */
+    commitTemplate(options: CommitTemplateOptions): Promise<SandboxTemplate>;
+    /**
+     * 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.
+     */
+    getTemplate(templateId: string): Promise<SandboxTemplate | null>;
+    /**
+     * 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.
+     */
+    listTemplates(options?: ListTemplatesOptions): Promise<SandboxTemplate[]>;
+    /**
+     * 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.
+     */
+    removeTemplate(templateId: string): Promise<void>;
     /**
      * PROVE egress is deny-by-default by OBSERVING it on a throwaway sandbox.
      *

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAEV,aAAa,EAKb,OAAO,EACP,aAAa,EACb,eAAe,EAChB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAkB,MAAM,YAAY,CAAA;AAqYjF;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,IAAI,SAAQ;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0D;IACjF,OAAO,CAAC,aAAa,CAA6C;IAClE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsB;IAEtD;;;;;OAKG;gBACS,MAAM,GAAE,SAAc,EAAE,cAAc,CAAC,EAAE,oBAAoB;IAYzE;;;;OAIG;YACW,MAAM;IASpB;;;;;OAKG;IACG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAmBrD;;;;;OAKG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAgB9C;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAY/C;;;;OAIG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;;;;;;;;OAWG;IACG,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC;CAyD7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,GAAE,SAAc,EACtB,cAAc,CAAC,EAAE,oBAAoB,GACpC,kBAAkB,CAEpB;AAED,kEAAkE;AAClE,eAAO,MAAM,QAAQ,EAAE,eAAkC,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,qBAAqB,EAErB,aAAa,EAKb,oBAAoB,EACpB,kBAAkB,EAClB,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,eAAe,EAGf,UAAU,EACX,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAGV,SAAS,EACT,oBAAoB,EAMrB,MAAM,YAAY,CAAA;AAkvBnB;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,IAAI,SAAQ;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0D;IACjF,OAAO,CAAC,aAAa,CAA6C;IAClE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsB;IAEtD;;;;;OAKG;gBACS,MAAM,GAAE,SAAc,EAAE,cAAc,CAAC,EAAE,oBAAoB;IAYzE;;;;OAIG;YACW,MAAM;IASpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IA+BrD;;;;;OAKG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAoB9C;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkC7D;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAgB/C;;;;OAIG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;;;;;;OASG;YACW,aAAa;IAM3B;;;;;OAKG;YACW,UAAU;IASxB;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlD;;;;;;;;;;OAUG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAmBtE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B9E;;;;;;;;;OASG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAoBtE;;;;;;;;;OASG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAmB/E;;;;;;;;;;OAUG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAevD;;;;;;;;;;;OAWG;IACG,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC;CAyD7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,GAAE,SAAc,EACtB,cAAc,CAAC,EAAE,oBAAoB,GACpC,kBAAkB,CAEpB;AAED,kEAAkE;AAClE,eAAO,MAAM,QAAQ,EAAE,eAAkC,CAAA"}