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

package/dist/provider.d.ts

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { EgressVerdict, Sandbox, SandboxConfig, SandboxDescriptor, 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}.
@@ -50,7 +50,17 @@ export declare class E2BSandboxProvider implements SandboxProvider {
      * `processesPreserved: true`. A filesystem-only snapshot would cold-boot
      * instead, leaving a sandbox that is running with every dev server dead.
      *
-     * @param config - Project id, env, optional per-boot templateId + labels.
+     * `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>;
@@ -91,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,iBAAiB,EACjB,eAAe,EAChB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EACV,SAAS,EACT,oBAAoB,EAGrB,MAAM,YAAY,CAAA;AAwdnB;;;;;;;;;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;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBrD;;;;;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;;;;;;;;;;;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"}