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

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-11T00:53:00.606Z
+Generated: 2026-08-15T18:25:48.482Z
 -->
 
 # @molecule/api-code-sandbox-e2b
@@ -45,12 +45,9 @@ import { createProvider } from '@molecule/api-code-sandbox-e2b'
 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'],
 })
 ```
 
@@ -61,7 +58,7 @@ const provider = createProvider({
 ## Installation
 
 ```bash
-npm install @molecule/api-code-sandbox-e2b e2b @molecule/api-bond @molecule/api-code-sandbox @molecule/api-i18n
+npm install @molecule/api-code-sandbox-e2b @bufbuild/protobuf @molecule/api-bond @molecule/api-code-sandbox @molecule/api-i18n e2b
 ```
 
 ## API
@@ -125,6 +122,10 @@ interface E2BConfig {
   /**
    * Default sandbox lifetime before E2B auto-pauses it, in milliseconds. The
    * control plane extends this per-heartbeat; this is only the initial ceiling.
+   *
+   * E2B caps this per account: 1 hour on Hobby, 24 hours on Pro. A value above
+   * the account's cap is rejected at create time, so raising it is a decision
+   * about the account, not just the config.
    */
   defaultTimeoutMs?: number
   /**
@@ -168,8 +169,48 @@ interface E2BSandboxClientLike {
   connect(sandboxId: string, opts?: Record<string, unknown>): Promise<E2BSandboxLike>
   list(
     opts?: Record<string, unknown>,
-  ): Promise<Array<{ sandboxId: string }> | { sandboxes?: Array<{ sandboxId: string }> }>
+  ): Promise<
+    | Array<{ sandboxId: string; state?: string }>
+    | { sandboxes?: Array<{ sandboxId: string; state?: string }> }
+  >
   kill?(sandboxId: string, opts?: Record<string, unknown>): Promise<boolean>
+  /**
+   * Read a sandbox's record WITHOUT connecting to it — the only lookup that does
+   * not resume a paused sandbox. Throws `SandboxNotFoundError` on a 404.
+   */
+  getInfo?(sandboxId: string, opts?: Record<string, unknown>): Promise<E2BSandboxInfoLike>
+  /**
+   * Whether an error means "this sandbox does not exist", as opposed to "the
+   * lookup failed". The distinction cannot be recovered from the error's shape by
+   * a consumer, and getting it wrong is what makes a control plane treat a
+   * provider outage as a destroyed sandbox.
+   */
+  isNotFound?(error: unknown): boolean
+}
+```
+
+#### `E2BSandboxInfoLike`
+
+Subset of the SDK's `SandboxInfo` the bond reads.
+
+This is what a sandbox looks like when you only LOOK at it. `connect` — which
+is how a handle is obtained — RESUMES a paused sandbox and extends its
+deadline, so it can never be used to answer "is this thing asleep?".
+
+```typescript
+interface E2BSandboxInfoLike {
+  sandboxId: string
+  templateId?: string
+  /** `'running'` or `'paused'`; anything else is treated as running. */
+  state?: string
+  /** Caller metadata supplied at create (the bond puts `projectId` here). */
+  metadata?: Record<string, string>
+  /** When the sandbox last started running. */
+  startedAt?: Date | string
+  /** When the sandbox's current deadline expires. */
+  endAt?: Date | string
+  /** Volumes mounted into the sandbox, when the account uses them. */
+  volumeMounts?: Array<{ name: string; path: string }>
 }
 ```
 
@@ -272,10 +313,11 @@ Peer dependencies:
 
 ### Runtime Dependencies
 
-- `e2b`
+- `@bufbuild/protobuf`
 - `@molecule/api-bond`
 - `@molecule/api-code-sandbox`
 - `@molecule/api-i18n`
+- `e2b`
 
 **`verifyEgress` is intentionally not implemented yet.** The control plane
 treats an absent `verifyEgress` as an `inconclusive` verdict and refuses to
@@ -288,3 +330,26 @@ trade cost for security). Do not stub it with a fabricated `filtered`.
 `resume()` report `processesPreserved: true` because the memory snapshot
 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()`.
+
+**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.

package/dist/index.d.ts

@@ -32,12 +32,9 @@
  * 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'],
  * })
  * ```
  *
@@ -54,6 +51,29 @@
  * 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()`.
+ *
+ * **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/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -32,12 +32,9 @@
  * 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'],
  * })
  * ```
  *
@@ -54,6 +51,29 @@
  * 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()`.
+ *
+ * **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 { EgressVerdict, Sandbox, SandboxConfig, SandboxDescriptor, SandboxProvider } from '@molecule/api-code-sandbox';
 import type { E2BConfig, E2BSandboxClientLike } from './types.js';
 /**
  * E2B implementation of {@link SandboxProvider}.
@@ -41,6 +41,15 @@ export declare class E2BSandboxProvider implements SandboxProvider {
     /**
      * Create a new sandbox from the golden template and apply the egress policy.
      *
+     * 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.
+     *
      * @param config - Project id, env, optional per-boot templateId + labels.
      * @returns A live sandbox handle.
      */
@@ -52,6 +61,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.
      *

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,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"}

package/dist/provider.js

@@ -28,12 +28,18 @@ 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 } = await import('e2b');
     const S = Sandbox;
     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 }),
+        // 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 +47,11 @@ 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.
                 for (const it of items)
                     if (it?.sandboxId)
-                        out.push({ sandboxId: it.sandboxId });
+                        out.push({ sandboxId: it.sandboxId, state: it.state });
             };
             const r = await Promise.resolve(result).catch(() => result);
             if (Array.isArray(r)) {
@@ -67,6 +75,15 @@ async function defaultClient(apiKey) {
         },
     };
 }
+/**
+ * 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 +93,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.
  *
@@ -316,7 +376,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 +386,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.
+     *
+     * 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.
+     * @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,6 +491,15 @@ export class E2BSandboxProvider {
     /**
      * Create a new sandbox from the golden template and apply the egress policy.
      *
+     * 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.
+     *
      * @param config - Project id, env, optional per-boot templateId + labels.
      * @returns A live sandbox handle.
      */
@@ -425,6 +510,7 @@ export class E2BSandboxProvider {
             timeoutMs: this.config.defaultTimeoutMs,
             envs: config.env ?? {},
             metadata: { projectId: config.projectId, ...(config.labels ?? {}) },
+            lifecycle: { onTimeout: { action: 'pause', keepMemory: true } },
         });
         const handle = new E2BSandbox(sbx, client, {
             previewPort: this.config.defaultPreviewPort,
@@ -451,12 +537,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 +612,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);

package/dist/types.d.ts

@@ -31,6 +31,10 @@ export interface E2BConfig {
     /**
      * Default sandbox lifetime before E2B auto-pauses it, in milliseconds. The
      * control plane extends this per-heartbeat; this is only the initial ceiling.
+     *
+     * E2B caps this per account: 1 hour on Hobby, 24 hours on Pro. A value above
+     * the account's cap is rejected at create time, so raising it is a decision
+     * about the account, not just the config.
      */
     defaultTimeoutMs?: number;
     /**
@@ -94,17 +98,55 @@ export interface E2BSandboxLike {
         denyOut?: string[];
     }): Promise<void>;
 }
+/**
+ * Subset of the SDK's `SandboxInfo` the bond reads.
+ *
+ * This is what a sandbox looks like when you only LOOK at it. `connect` — which
+ * is how a handle is obtained — RESUMES a paused sandbox and extends its
+ * deadline, so it can never be used to answer "is this thing asleep?".
+ */
+export interface E2BSandboxInfoLike {
+    sandboxId: string;
+    templateId?: string;
+    /** `'running'` or `'paused'`; anything else is treated as running. */
+    state?: string;
+    /** Caller metadata supplied at create (the bond puts `projectId` here). */
+    metadata?: Record<string, string>;
+    /** When the sandbox last started running. */
+    startedAt?: Date | string;
+    /** When the sandbox's current deadline expires. */
+    endAt?: Date | string;
+    /** Volumes mounted into the sandbox, when the account uses them. */
+    volumeMounts?: Array<{
+        name: string;
+        path: string;
+    }>;
+}
 /** Subset of the SDK's `Sandbox` static surface the bond uses. */
 export interface E2BSandboxClientLike {
     create(templateId: string, opts?: Record<string, unknown>): Promise<E2BSandboxLike>;
     connect(sandboxId: string, opts?: Record<string, unknown>): Promise<E2BSandboxLike>;
     list(opts?: Record<string, unknown>): Promise<Array<{
         sandboxId: string;
+        state?: string;
     }> | {
         sandboxes?: Array<{
             sandboxId: string;
+            state?: string;
         }>;
     }>;
     kill?(sandboxId: string, opts?: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Read a sandbox's record WITHOUT connecting to it — the only lookup that does
+     * not resume a paused sandbox. Throws `SandboxNotFoundError` on a 404.
+     */
+    getInfo?(sandboxId: string, opts?: Record<string, unknown>): Promise<E2BSandboxInfoLike>;
+    /**
+     * Whether an error means "this sandbox does not exist", as opposed to "the
+     * lookup failed". The distinction cannot be recovered from the error's shape by
+     * a consumer, and getting it wrong is what makes a control plane treat a
+     * provider outage as a destroyed sandbox.
+     */
+    isNotFound?(error: unknown): boolean;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-e2b",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "E2B (e2b.dev) code sandbox provider — Firecracker microVMs with golden templates, fork, and pause/resume",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@molecule/api-bond": "1.0.1",
-    "@molecule/api-code-sandbox": "1.0.3",
+    "@molecule/api-code-sandbox": "1.1.1",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.10"