@molecule/api-code-sandbox-e2b 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,281 @@
+<!--
+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-10T23:56:44.341Z
+-->
+
+# @molecule/api-code-sandbox-e2b
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+E2B (e2b.dev) code sandbox provider.
+
+E2B runs isolated Firecracker microVMs purpose-built for agent/dev workloads:
+a sandbox spawns from a golden **template** (a Dockerfile-built image with the
+whole dependency set baked in) in ~1s, exposes every internal port at
+`https://<port>-<id>.e2b.app`, pauses/resumes with filesystem + memory state
+preserved in ~1s, and governs outbound traffic by a DNS network policy. This
+bond maps that platform onto the `@molecule/api-code-sandbox` contract through
+the official `e2b` SDK.
+
+The design that makes it fast: a single golden SUPERSET template carries the
+entire `@molecule` fleet node_modules + postgres + warmed Vite deps, so a boot
+only copies the ONE selected app's source in and starts the dev servers — no
+per-boot `npm install`. The 133 flagship template sources are NOT baked into
+the image; they are copied from the control plane at boot, so templates and
+`mlcl` stay private.
+
+## Quick Start
+
+```typescript
+import { bond } from '@molecule/api-bond'
+import { provider } from '@molecule/api-code-sandbox-e2b'
+
+bond('codeSandbox', provider)
+// Requires E2B_API_KEY (and E2B_TEMPLATE_ID for the golden superset template).
+```
+
+```typescript
+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' },
+  ],
+})
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-code-sandbox-e2b e2b @molecule/api-bond @molecule/api-code-sandbox @molecule/api-i18n
+```
+
+## API
+
+### Interfaces
+
+#### `E2BCommandResultLike`
+
+Result of an E2B command run (subset of the SDK's `CommandResult`).
+
+```typescript
+interface E2BCommandResultLike {
+  stdout: string
+  stderr: string
+  exitCode: number
+}
+```
+
+#### `E2BCommandsLike`
+
+Subset of the SDK's `Commands` the bond uses.
+
+```typescript
+interface E2BCommandsLike {
+  run(
+    cmd: string,
+    opts?: { cwd?: string; timeoutMs?: number; envs?: Record<string, string> },
+  ): Promise<E2BCommandResultLike>
+}
+```
+
+#### `E2BConfig`
+
+Bond configuration. All fields have safe defaults; see {@link createProvider}.
+
+```typescript
+interface E2BConfig {
+  /**
+   * E2B API key. Falls back to `E2B_API_KEY` in the environment. Required — the
+   * provider throws on first use if neither is set.
+   */
+  apiKey?: string
+  /**
+   * The golden template id every sandbox boots from. Falls back to
+   * `E2B_TEMPLATE_ID`, then E2B's `base` template. This is the caller's OWN
+   * identifier for the superset template (fleet node_modules + postgres +
+   * warmed vite deps), built out of band by the template pipeline.
+   */
+  templateId?: string
+  /**
+   * Default port the preview URL points at (the app's Vite dev server).
+   * `getPreviewUrl()` uses this when no port is given.
+   */
+  defaultPreviewPort?: number
+  /**
+   * Default sandbox lifetime before E2B auto-pauses it, in milliseconds. The
+   * control plane extends this per-heartbeat; this is only the initial ceiling.
+   */
+  defaultTimeoutMs?: number
+  /**
+   * Egress allow-list (domains / CIDRs) applied to every sandbox at create
+   * time; everything else is denied (`denyOut: [ALL_TRAFFIC]`). Wildcards like
+   * `*.npmjs.org` are supported. Empty/omitted means the bond does NOT
+   * constrain egress — prod must supply this or `verifyEgress` observes `open`
+   * and the control plane refuses to boot (Rule 18).
+   *
+   * Verified against a live E2B sandbox: with `denyOut: [ALL_TRAFFIC]`, a
+   * non-allowlisted host AND a raw destination IP are both blocked — a stronger
+   * boundary than a DNS-only policy.
+   */
+  defaultAllowOut?: string[]
+}
+```
+
+#### `E2BFilesystemLike`
+
+Subset of the SDK's `Filesystem` the bond uses.
+
+```typescript
+interface E2BFilesystemLike {
+  read(path: string): Promise<string>
+  write(path: string, data: string): Promise<unknown>
+  list(path: string): Promise<Array<{ name: string; type?: string; size?: number }>>
+  remove(path: string): Promise<void>
+}
+```
+
+#### `E2BSandboxClientLike`
+
+Subset of the SDK's `Sandbox` static surface the bond uses.
+
+```typescript
+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 }> | { sandboxes?: Array<{ sandboxId: string }> }>
+  kill?(sandboxId: string, opts?: Record<string, unknown>): Promise<boolean>
+}
+```
+
+#### `E2BSandboxLike`
+
+Subset of the SDK's `Sandbox` instance the bond uses.
+
+```typescript
+interface E2BSandboxLike {
+  sandboxId: string
+  commands: E2BCommandsLike
+  files: E2BFilesystemLike
+  getHost(port: number): string
+  setTimeout(ms: number): Promise<void>
+  kill(): Promise<void>
+  pause?(): Promise<string>
+  betaPause?(): Promise<string>
+  isRunning(): Promise<boolean>
+  updateNetwork?(opts: { allowOut?: string[]; denyOut?: string[] }): Promise<void>
+}
+```
+
+### Classes
+
+#### `E2BSandboxProvider`
+
+E2B implementation of {@link SandboxProvider}.
+
+Only the required surface (`create`/`get`/`list`/`destroy`) plus the boot-path
+optionals are wired here; `verifyEgress` and `commitTemplate`/`getTemplate`
+land in follow-up steps. Leaving `verifyEgress` UNimplemented is deliberate:
+the control plane treats "unsupported" as `inconclusive` and refuses to boot
+in prod, which is the correct safe default until egress observation is proven
+(Rule 18 — never trade cost for security).
+
+### Functions
+
+#### `createProvider(config, clientOverride)`
+
+Create an E2B provider with the given configuration.
+
+```typescript
+function createProvider(
+  config?: E2BConfig,
+  clientOverride?: E2BSandboxClientLike,
+): E2BSandboxProvider
+```
+
+- `config` — Bond configuration; API key falls back to `E2B_API_KEY`.
+- `clientOverride` — Inject a fake client (tests).
+
+**Returns:** A configured provider ready to `bond('codeSandbox', provider)`.
+
+### Constants
+
+#### `provider`
+
+Default provider instance, configured from the environment.
+
+```typescript
+const provider: SandboxProvider
+```
+
+## Core Interface
+
+Implements `@molecule/api-code-sandbox` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/api-code-sandbox'
+import { provider } from '@molecule/api-code-sandbox-e2b'
+
+export function setupCodeSandboxE2b(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-bond` ^1.0.1
+- `@molecule/api-code-sandbox` ^1.0.1
+- `@molecule/api-i18n` ^1.0.1
+
+### Environment Variables
+
+- `E2B_API_KEY` _(required)_ — E2B API key
+  - Setup: Create an API key in the E2B dashboard.
+  - Get it here: [https://e2b.dev/dashboard](https://e2b.dev/dashboard)
+  - Example: `e2b_...`
+- `E2B_TEMPLATE_ID` _(optional)_ — E2B golden template id
+  - Setup: The superset template id every sandbox boots from; defaults to E2B base.
+  - Example: `molecule-superset`
+
+### Runtime Dependencies
+
+- `e2b`
+- `@molecule/api-bond`
+- `@molecule/api-code-sandbox`
+- `@molecule/api-i18n`
+
+**`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`.
+
+**E2B pauses, it does not stop.** `sleep()`/`stop()` both map to E2B pause
+(FS + memory snapshot); `wake()`/`start()` reconnect by id. `hibernate()`/
+`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.

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * E2B (e2b.dev) code sandbox provider.
+ *
+ * E2B runs isolated Firecracker microVMs purpose-built for agent/dev workloads:
+ * a sandbox spawns from a golden **template** (a Dockerfile-built image with the
+ * whole dependency set baked in) in ~1s, exposes every internal port at
+ * `https://<port>-<id>.e2b.app`, pauses/resumes with filesystem + memory state
+ * preserved in ~1s, and governs outbound traffic by a DNS network policy. This
+ * bond maps that platform onto the `@molecule/api-code-sandbox` contract through
+ * the official `e2b` SDK.
+ *
+ * The design that makes it fast: a single golden SUPERSET template carries the
+ * entire `@molecule` fleet node_modules + postgres + warmed Vite deps, so a boot
+ * only copies the ONE selected app's source in and starts the dev servers — no
+ * per-boot `npm install`. The 133 flagship template sources are NOT baked into
+ * the image; they are copied from the control plane at boot, so templates and
+ * `mlcl` stay private.
+ *
+ * @example
+ * ```typescript
+ * import { bond } from '@molecule/api-bond'
+ * import { provider } from '@molecule/api-code-sandbox-e2b'
+ *
+ * bond('codeSandbox', provider)
+ * // Requires E2B_API_KEY (and E2B_TEMPLATE_ID for the golden superset template).
+ * ```
+ *
+ * @example
+ * ```typescript
+ * 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' },
+ *   ],
+ * })
+ * ```
+ *
+ * @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`.
+ *
+ * **E2B pauses, it does not stop.** `sleep()`/`stop()` both map to E2B pause
+ * (FS + memory snapshot); `wake()`/`start()` reconnect by id. `hibernate()`/
+ * `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.
+ *
+ * @module
+ */
+export * from './provider.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,60 @@
+/**
+ * E2B (e2b.dev) code sandbox provider.
+ *
+ * E2B runs isolated Firecracker microVMs purpose-built for agent/dev workloads:
+ * a sandbox spawns from a golden **template** (a Dockerfile-built image with the
+ * whole dependency set baked in) in ~1s, exposes every internal port at
+ * `https://<port>-<id>.e2b.app`, pauses/resumes with filesystem + memory state
+ * preserved in ~1s, and governs outbound traffic by a DNS network policy. This
+ * bond maps that platform onto the `@molecule/api-code-sandbox` contract through
+ * the official `e2b` SDK.
+ *
+ * The design that makes it fast: a single golden SUPERSET template carries the
+ * entire `@molecule` fleet node_modules + postgres + warmed Vite deps, so a boot
+ * only copies the ONE selected app's source in and starts the dev servers — no
+ * per-boot `npm install`. The 133 flagship template sources are NOT baked into
+ * the image; they are copied from the control plane at boot, so templates and
+ * `mlcl` stay private.
+ *
+ * @example
+ * ```typescript
+ * import { bond } from '@molecule/api-bond'
+ * import { provider } from '@molecule/api-code-sandbox-e2b'
+ *
+ * bond('codeSandbox', provider)
+ * // Requires E2B_API_KEY (and E2B_TEMPLATE_ID for the golden superset template).
+ * ```
+ *
+ * @example
+ * ```typescript
+ * 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' },
+ *   ],
+ * })
+ * ```
+ *
+ * @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`.
+ *
+ * **E2B pauses, it does not stop.** `sleep()`/`stop()` both map to E2B pause
+ * (FS + memory snapshot); `wake()`/`start()` reconnect by id. `hibernate()`/
+ * `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.
+ *
+ * @module
+ */
+export * from './provider.js';
+export * from './types.js';

package/dist/provider.d.ts

@@ -0,0 +1,92 @@
+/**
+ * E2B code-sandbox provider implementation.
+ *
+ * Maps the `@molecule/api-code-sandbox` contract onto E2B's Firecracker microVM
+ * platform via the official `e2b` SDK. The SDK is reached through the structural
+ * {@link E2BSandboxClientLike} shim so the provider is unit-testable with a fake
+ * client; {@link defaultClient} adapts the real `Sandbox` class.
+ *
+ * @module
+ */
+import type { EgressVerdict, Sandbox, SandboxConfig, SandboxProvider } from '@molecule/api-code-sandbox';
+import type { E2BConfig, E2BSandboxClientLike } from './types.js';
+/**
+ * E2B implementation of {@link SandboxProvider}.
+ *
+ * Only the required surface (`create`/`get`/`list`/`destroy`) plus the boot-path
+ * optionals are wired here; `verifyEgress` and `commitTemplate`/`getTemplate`
+ * land in follow-up steps. Leaving `verifyEgress` UNimplemented is deliberate:
+ * the control plane treats "unsupported" as `inconclusive` and refuses to boot
+ * in prod, which is the correct safe default until egress observation is proven
+ * (Rule 18 — never trade cost for security).
+ */
+export declare class E2BSandboxProvider implements SandboxProvider {
+    readonly name = "e2b";
+    private readonly config;
+    private clientPromise;
+    private readonly clientOverride?;
+    /**
+     * Construct the provider from config, resolving the API key and template id.
+     *
+     * @param config - Bond configuration; API key falls back to `E2B_API_KEY`.
+     * @param clientOverride - Inject a fake client (tests).
+     */
+    constructor(config?: E2BConfig, clientOverride?: E2BSandboxClientLike);
+    /**
+     * Resolve the SDK client, memoized. Throws when no API key is configured.
+     *
+     * @returns The E2B client (injected override or real SDK adapter).
+     */
+    private client;
+    /**
+     * Create a new sandbox from the golden template and apply the egress policy.
+     *
+     * @param config - Project id, env, optional per-boot templateId + labels.
+     * @returns A live sandbox handle.
+     */
+    create(config: SandboxConfig): Promise<Sandbox>;
+    /**
+     * Resolve an existing sandbox by id.
+     *
+     * @param id - The sandbox id.
+     * @returns A live handle, or `null` if no sandbox has that id.
+     */
+    get(id: string): Promise<Sandbox | null>;
+    /**
+     * List the caller's live sandboxes.
+     *
+     * @param _userId - Unused; E2B scopes by API key, not per-user labels here.
+     * @returns Live handles for every running sandbox.
+     */
+    list(_userId: string): Promise<Sandbox[]>;
+    /**
+     * Destroy a sandbox, freeing its resources.
+     *
+     * @param id - The sandbox id.
+     */
+    destroy(id: string): Promise<void>;
+    /**
+     * PROVE egress is deny-by-default by OBSERVING it on a throwaway sandbox.
+     *
+     * Creates a sandbox, applies `{ allowOut: [npm], denyOut: [ALL_TRAFFIC] }`,
+     * then curls an allow-listed host, a non-allow-listed host, AND a raw IP from
+     * inside. `filtered` requires BOTH the non-allow-listed host and the raw IP to
+     * be blocked while the allow-listed host is reachable — never an attestation.
+     * Any failure to run the probe is `inconclusive`, never `filtered` ("could not
+     * look" must not read as "safe"). Verified live: E2B blocks raw IPs too.
+     *
+     * @returns The observed egress verdict.
+     */
+    verifyEgress(): Promise<EgressVerdict>;
+}
+/**
+ * Create an E2B provider with the given configuration.
+ *
+ * @param config - Bond configuration; API key falls back to `E2B_API_KEY`.
+ * @param clientOverride - Inject a fake client (tests).
+ * @returns A configured provider ready to `bond('codeSandbox', provider)`.
+ */
+export declare function createProvider(config?: E2BConfig, clientOverride?: E2BSandboxClientLike): E2BSandboxProvider;
+/** Default provider instance, configured from the environment. */
+export declare const provider: SandboxProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +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;AAoRjF;;;;;;;;;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"}

package/dist/provider.js

@@ -0,0 +1,465 @@
+/**
+ * E2B code-sandbox provider implementation.
+ *
+ * Maps the `@molecule/api-code-sandbox` contract onto E2B's Firecracker microVM
+ * platform via the official `e2b` SDK. The SDK is reached through the structural
+ * {@link E2BSandboxClientLike} shim so the provider is unit-testable with a fake
+ * client; {@link defaultClient} adapts the real `Sandbox` class.
+ *
+ * @module
+ */
+/** Default Vite dev-server port the preview URL points at. */
+const DEFAULT_PREVIEW_PORT = 5173;
+/** Default sandbox lifetime before E2B auto-pauses (control plane extends per heartbeat). */
+const DEFAULT_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 —
+ * E2B REQUIRES this pairing (a bare `allowOut` is a 400) and it blocks raw IPs
+ * too, not just DNS names. Inlined as the literal to avoid importing the SDK at
+ * module load (the provider imports `e2b` lazily).
+ */
+const ALL_TRAFFIC = '0.0.0.0/0';
+/** Hosts the egress probe treats as the canonical allow/deny witnesses. */
+const EGRESS_PROBE_ALLOW = 'registry.npmjs.org';
+const EGRESS_PROBE_DENY = 'example.com';
+/**
+ * Adapt the real `e2b` SDK `Sandbox` class to {@link E2BSandboxClientLike}.
+ * Imported lazily so the SDK is only required when the bond is actually used.
+ */
+async function defaultClient(apiKey) {
+    const { Sandbox } = 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 }),
+        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
+            // a minor SDK change does not silently return nothing.
+            const result = S.list({ apiKey, ...opts });
+            const out = [];
+            const push = (items) => {
+                for (const it of items)
+                    if (it?.sandboxId)
+                        out.push({ sandboxId: it.sandboxId });
+            };
+            const r = await Promise.resolve(result).catch(() => result);
+            if (Array.isArray(r)) {
+                push(r);
+            }
+            else if (r && typeof r.nextItems === 'function') {
+                const pager = r;
+                do {
+                    push(await pager.nextItems());
+                } while (pager.hasNext);
+            }
+            else if (r &&
+                typeof r[Symbol.asyncIterator] === 'function') {
+                for await (const it of r)
+                    push([it]);
+            }
+            else if (r && Array.isArray(r.sandboxes)) {
+                push(r.sandboxes);
+            }
+            return out;
+        },
+    };
+}
+/**
+ * Build a deny-by-default network update from an allow-list.
+ *
+ * @param allowOut - Domains/CIDRs permitted; everything else is denied.
+ * @returns The SDK `updateNetwork` payload (allowOut + denyOut ALL_TRAFFIC).
+ */
+function denyByDefault(allowOut) {
+    return { allowOut, denyOut: [ALL_TRAFFIC] };
+}
+/**
+ * A live E2B sandbox mapped onto the core `Sandbox` handle.
+ *
+ * E2B pauses/resumes rather than start/stop; a resume yields a NEW underlying
+ * SDK instance, so the handle re-resolves it by id on wake and swaps
+ * {@link E2BSandbox.sbx}. `getHost` is a pure string builder
+ * (`<port>-<id>.e2b.app`) so `previewUrl` is known the instant the id is.
+ */
+class E2BSandbox {
+    id;
+    status = 'running';
+    previewUrl;
+    sbx;
+    client;
+    previewPort;
+    timeoutMs;
+    /**
+     * Wrap a live E2B SDK sandbox as a core `Sandbox` handle.
+     *
+     * @param sbx - The live E2B SDK sandbox instance.
+     * @param client - The client used to reconnect the instance on resume.
+     * @param opts - Preview port and auto-pause timeout for this sandbox.
+     */
+    constructor(sbx, client, opts) {
+        this.sbx = sbx;
+        this.id = sbx.sandboxId;
+        this.client = client;
+        this.previewPort = opts.previewPort;
+        this.timeoutMs = opts.timeoutMs;
+        this.previewUrl = this.getPreviewUrl();
+    }
+    /**
+     * The public HTTPS URL for a port inside the sandbox.
+     *
+     * @param port - Sandbox port; defaults to the configured preview port.
+     * @returns `https://<port>-<id>.e2b.app`.
+     */
+    getPreviewUrl(port) {
+        return `https://${this.sbx.getHost(port ?? this.previewPort)}`;
+    }
+    /** Resume the sandbox (E2B has no separate cold start). */
+    async start() {
+        await this.wake();
+    }
+    /** Pause the sandbox (E2B has no stop distinct from pause). */
+    async stop() {
+        // E2B has no stop-without-losing-state distinct from pause; treat as pause.
+        await this.sleep();
+    }
+    /** Pause the sandbox, discarding the hibernation outcome. */
+    async sleep() {
+        await this.hibernate();
+    }
+    /** Resume the sandbox, discarding the hibernation outcome. */
+    async wake() {
+        await this.resume();
+    }
+    /**
+     * Pause the sandbox (E2B FS + memory snapshot).
+     *
+     * @returns The outcome; `processesPreserved` is true because the memory
+     *   snapshot restores the process tree on resume.
+     */
+    async hibernate() {
+        const pause = this.sbx.betaPause ?? this.sbx.pause;
+        if (!pause) {
+            // No pause available — nothing we can honestly suspend; report it.
+            return { processesPreserved: true, mechanism: 'noop', detail: 'pause not supported by SDK' };
+        }
+        await pause.call(this.sbx);
+        this.status = 'sleeping';
+        // E2B pause snapshots FS + memory, so the process tree survives resume.
+        return { processesPreserved: true, mechanism: 'pause' };
+    }
+    /**
+     * Resume the sandbox by reconnecting to a fresh live instance for its id.
+     *
+     * @returns The outcome; `processesPreserved` is true (memory snapshot).
+     */
+    async resume() {
+        // Reconnect resolves a fresh live instance for the same id (a no-op if it is
+        // already running); swap it in so subsequent calls hit the live sandbox.
+        this.sbx = await this.client.connect(this.id, { timeoutMs: this.timeoutMs });
+        this.status = 'running';
+        this.previewUrl = this.getPreviewUrl();
+        return { processesPreserved: true, mechanism: 'resume' };
+    }
+    /**
+     * Run a command to completion in the sandbox.
+     *
+     * @param command - The shell command to run.
+     * @param opts - Working directory, timeout (ms), and env vars.
+     * @returns stdout, stderr and the exit code.
+     */
+    async exec(command, opts) {
+        const r = await this.sbx.commands.run(command, {
+            cwd: opts?.cwd,
+            timeoutMs: opts?.timeout,
+            envs: opts?.env,
+        });
+        return { stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode };
+    }
+    /**
+     * Read a file's contents as text.
+     *
+     * @param path - Absolute path inside the sandbox.
+     * @returns The file contents.
+     */
+    async readFile(path) {
+        return this.sbx.files.read(path);
+    }
+    /**
+     * Write text to a file, creating parent directories as needed.
+     *
+     * @param path - Absolute path inside the sandbox.
+     * @param content - The text to write.
+     */
+    async writeFile(path, content) {
+        await this.sbx.files.write(path, content);
+    }
+    /**
+     * List a directory. Throws when the path does not exist (an empty array
+     * means "exists and is empty", never "missing").
+     *
+     * @param path - Absolute directory path inside the sandbox.
+     * @returns The directory entries.
+     */
+    async readDir(path) {
+        // E2B throws when the path is missing (contract: empty array ONLY means
+        // "exists and empty"), so we do not catch here.
+        const entries = await this.sbx.files.list(path);
+        return entries.map((e) => ({
+            name: e.name,
+            type: e.type === 'dir' || e.type === 'directory' ? 'directory' : 'file',
+            ...(typeof e.size === 'number' ? { size: e.size } : {}),
+        }));
+    }
+    /**
+     * Delete a file.
+     *
+     * @param path - Absolute path inside the sandbox.
+     */
+    async deleteFile(path) {
+        await this.sbx.files.remove(path);
+    }
+    /**
+     * Subscribe to filesystem changes. Not wired for E2B (the control plane polls
+     * the tree); returns a no-op unsubscribe so register-and-forget callers are safe.
+     *
+     * @param _cb - Ignored change callback.
+     * @returns A no-op unsubscribe function.
+     */
+    onFileChange(_cb) {
+        // E2B exposes filesystem watch via files.watchDir; the control plane polls
+        // the tree rather than subscribing, so this bond does not wire it yet.
+        // Returning a no-op unsubscribe keeps callers that register-and-forget safe.
+        return () => { };
+    }
+    /**
+     * Extend the sandbox's auto-pause deadline (heartbeat).
+     *
+     * @param ms - New lifetime in milliseconds from now.
+     */
+    async keepAlive(ms) {
+        await this.sbx.setTimeout(ms);
+    }
+    /**
+     * Apply a deny-by-default egress allow-list to this sandbox.
+     *
+     * @param allowOut - Domains/CIDRs to permit; everything else denied. A no-op
+     *   when empty or when the SDK build lacks `updateNetwork`.
+     */
+    async applyNetwork(allowOut) {
+        if (!this.sbx.updateNetwork || allowOut.length === 0)
+            return;
+        await this.sbx.updateNetwork(denyByDefault(allowOut));
+    }
+}
+/**
+ * E2B implementation of {@link SandboxProvider}.
+ *
+ * Only the required surface (`create`/`get`/`list`/`destroy`) plus the boot-path
+ * optionals are wired here; `verifyEgress` and `commitTemplate`/`getTemplate`
+ * land in follow-up steps. Leaving `verifyEgress` UNimplemented is deliberate:
+ * the control plane treats "unsupported" as `inconclusive` and refuses to boot
+ * in prod, which is the correct safe default until egress observation is proven
+ * (Rule 18 — never trade cost for security).
+ */
+export class E2BSandboxProvider {
+    name = 'e2b';
+    config;
+    clientPromise = null;
+    clientOverride;
+    /**
+     * Construct the provider from config, resolving the API key and template id.
+     *
+     * @param config - Bond configuration; API key falls back to `E2B_API_KEY`.
+     * @param clientOverride - Inject a fake client (tests).
+     */
+    constructor(config = {}, clientOverride) {
+        const apiKey = config.apiKey ?? process.env.E2B_API_KEY ?? '';
+        this.config = {
+            apiKey,
+            templateId: config.templateId ?? process.env.E2B_TEMPLATE_ID ?? 'base',
+            defaultPreviewPort: config.defaultPreviewPort ?? DEFAULT_PREVIEW_PORT,
+            defaultTimeoutMs: config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+            defaultAllowOut: config.defaultAllowOut ?? [],
+        };
+        this.clientOverride = clientOverride;
+    }
+    /**
+     * Resolve the SDK client, memoized. Throws when no API key is configured.
+     *
+     * @returns The E2B client (injected override or real SDK adapter).
+     */
+    async client() {
+        if (this.clientOverride)
+            return this.clientOverride;
+        if (!this.config.apiKey) {
+            throw new Error('E2B provider requires an API key (config.apiKey or E2B_API_KEY)');
+        }
+        if (!this.clientPromise)
+            this.clientPromise = defaultClient(this.config.apiKey);
+        return this.clientPromise;
+    }
+    /**
+     * Create a new sandbox from the golden template and apply the egress policy.
+     *
+     * @param config - Project id, env, optional per-boot templateId + labels.
+     * @returns A live sandbox handle.
+     */
+    async create(config) {
+        const client = await this.client();
+        const templateId = config.templateId ?? this.config.templateId;
+        const sbx = await client.create(templateId, {
+            timeoutMs: this.config.defaultTimeoutMs,
+            envs: config.env ?? {},
+            metadata: { projectId: config.projectId, ...(config.labels ?? {}) },
+        });
+        const handle = new E2BSandbox(sbx, client, {
+            previewPort: this.config.defaultPreviewPort,
+            timeoutMs: this.config.defaultTimeoutMs,
+        });
+        // Apply the egress allow-list immediately, before any user code runs.
+        if (this.config.defaultAllowOut.length > 0) {
+            await handle.applyNetwork(this.config.defaultAllowOut);
+        }
+        return handle;
+    }
+    /**
+     * Resolve an existing sandbox by id.
+     *
+     * @param id - The sandbox id.
+     * @returns A live handle, or `null` if no sandbox has that id.
+     */
+    async get(id) {
+        const client = await this.client();
+        try {
+            const sbx = await client.connect(id, { timeoutMs: this.config.defaultTimeoutMs });
+            return new E2BSandbox(sbx, client, {
+                previewPort: this.config.defaultPreviewPort,
+                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;
+        }
+    }
+    /**
+     * List the caller's live sandboxes.
+     *
+     * @param _userId - Unused; E2B scopes by API key, not per-user labels here.
+     * @returns Live handles for every running sandbox.
+     */
+    async list(_userId) {
+        const client = await this.client();
+        const running = await client.list({});
+        const items = Array.isArray(running) ? running : (running.sandboxes ?? []);
+        const handles = [];
+        for (const it of items) {
+            const h = await this.get(it.sandboxId);
+            if (h)
+                handles.push(h);
+        }
+        return handles;
+    }
+    /**
+     * Destroy a sandbox, freeing its resources.
+     *
+     * @param id - The sandbox id.
+     */
+    async destroy(id) {
+        const client = await this.client();
+        if (client.kill) {
+            await client.kill(id, {});
+            return;
+        }
+        const sbx = await client.connect(id, {}).catch((error) => {
+            // Already gone / unreachable — nothing to kill; destroy is idempotent.
+            void error;
+            return null;
+        });
+        if (sbx)
+            await sbx.kill();
+    }
+    /**
+     * PROVE egress is deny-by-default by OBSERVING it on a throwaway sandbox.
+     *
+     * Creates a sandbox, applies `{ allowOut: [npm], denyOut: [ALL_TRAFFIC] }`,
+     * then curls an allow-listed host, a non-allow-listed host, AND a raw IP from
+     * inside. `filtered` requires BOTH the non-allow-listed host and the raw IP to
+     * be blocked while the allow-listed host is reachable — never an attestation.
+     * Any failure to run the probe is `inconclusive`, never `filtered` ("could not
+     * look" must not read as "safe"). Verified live: E2B blocks raw IPs too.
+     *
+     * @returns The observed egress verdict.
+     */
+    async verifyEgress() {
+        let handle = null;
+        try {
+            handle = await this.create({ projectId: `egress-probe-${Date.now()}`, env: {} });
+        }
+        catch (error) {
+            return {
+                state: 'inconclusive',
+                detail: `Could not create a probe sandbox: ${error instanceof Error ? error.message : String(error)}`,
+                remediation: 'Check E2B_API_KEY and account capacity.',
+            };
+        }
+        try {
+            // Force a KNOWN deny-default policy for the probe regardless of config.
+            await handle.applyNetwork([
+                EGRESS_PROBE_ALLOW,
+                `*.${EGRESS_PROBE_ALLOW.split('.').slice(-2).join('.')}`,
+            ]);
+            const code = async (host) => (await handle.exec(`curl -s -o /dev/null -m 8 -w '%{http_code}' https://${host}/ || echo 000`)).stdout.trim();
+            const [allowed, deniedHost, deniedIp] = await Promise.all([
+                code(EGRESS_PROBE_ALLOW),
+                code(EGRESS_PROBE_DENY),
+                code('1.1.1.1'),
+            ]);
+            const blocked = (c) => c === '' || c.startsWith('000');
+            if (blocked(deniedHost) && blocked(deniedIp) && !blocked(allowed)) {
+                return {
+                    state: 'filtered',
+                    detail: `deny-by-default verified: ${EGRESS_PROBE_ALLOW}=${allowed} reachable; ${EGRESS_PROBE_DENY}=${deniedHost} and raw IP=${deniedIp} blocked.`,
+                };
+            }
+            return {
+                state: 'open',
+                detail: `Non-allow-listed egress was reachable (host=${deniedHost}, rawIP=${deniedIp}, allowed=${allowed}).`,
+                remediation: 'Ensure updateNetwork applies allowOut + denyOut:[0.0.0.0/0]; check the E2B account supports network policy.',
+            };
+        }
+        catch (error) {
+            return {
+                state: 'inconclusive',
+                detail: `Egress probe could not run: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        finally {
+            // Best-effort cleanup of the throwaway probe sandbox; a failed destroy
+            // must not mask the verdict (E2B auto-pauses idle sandboxes regardless).
+            if (handle) {
+                await this.destroy(handle.id).catch((_error) => {
+                    // intentional noop — probe teardown is best-effort; the sandbox
+                    // auto-pauses and the verdict is what matters.
+                });
+            }
+        }
+    }
+}
+/**
+ * Create an E2B provider with the given configuration.
+ *
+ * @param config - Bond configuration; API key falls back to `E2B_API_KEY`.
+ * @param clientOverride - Inject a fake client (tests).
+ * @returns A configured provider ready to `bond('codeSandbox', provider)`.
+ */
+export function createProvider(config = {}, clientOverride) {
+    return new E2BSandboxProvider(config, clientOverride);
+}
+/** Default provider instance, configured from the environment. */
+export const provider = createProvider();

package/dist/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Configuration + narrow structural shims for the E2B code-sandbox bond.
+ *
+ * The bond talks to E2B through the official `e2b` SDK; these types capture only
+ * the slice of that SDK surface the provider touches, plus the bond's own
+ * configuration. Keeping them structural (rather than importing the SDK's own
+ * types) keeps the provider testable with a fake client and documents exactly
+ * which SDK methods this bond depends on.
+ *
+ * @module
+ */
+/** Bond configuration. All fields have safe defaults; see {@link createProvider}. */
+export interface E2BConfig {
+    /**
+     * E2B API key. Falls back to `E2B_API_KEY` in the environment. Required — the
+     * provider throws on first use if neither is set.
+     */
+    apiKey?: string;
+    /**
+     * The golden template id every sandbox boots from. Falls back to
+     * `E2B_TEMPLATE_ID`, then E2B's `base` template. This is the caller's OWN
+     * identifier for the superset template (fleet node_modules + postgres +
+     * warmed vite deps), built out of band by the template pipeline.
+     */
+    templateId?: string;
+    /**
+     * Default port the preview URL points at (the app's Vite dev server).
+     * `getPreviewUrl()` uses this when no port is given.
+     */
+    defaultPreviewPort?: number;
+    /**
+     * Default sandbox lifetime before E2B auto-pauses it, in milliseconds. The
+     * control plane extends this per-heartbeat; this is only the initial ceiling.
+     */
+    defaultTimeoutMs?: number;
+    /**
+     * Egress allow-list (domains / CIDRs) applied to every sandbox at create
+     * time; everything else is denied (`denyOut: [ALL_TRAFFIC]`). Wildcards like
+     * `*.npmjs.org` are supported. Empty/omitted means the bond does NOT
+     * constrain egress — prod must supply this or `verifyEgress` observes `open`
+     * and the control plane refuses to boot (Rule 18).
+     *
+     * Verified against a live E2B sandbox: with `denyOut: [ALL_TRAFFIC]`, a
+     * non-allowlisted host AND a raw destination IP are both blocked — a stronger
+     * boundary than a DNS-only policy.
+     */
+    defaultAllowOut?: string[];
+}
+/** Result of an E2B command run (subset of the SDK's `CommandResult`). */
+export interface E2BCommandResultLike {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Subset of the SDK's `Filesystem` the bond uses. */
+export interface E2BFilesystemLike {
+    read(path: string): Promise<string>;
+    write(path: string, data: string): Promise<unknown>;
+    list(path: string): Promise<Array<{
+        name: string;
+        type?: string;
+        size?: number;
+    }>>;
+    remove(path: string): Promise<void>;
+}
+/** Subset of the SDK's `Commands` the bond uses. */
+export interface E2BCommandsLike {
+    run(cmd: string, opts?: {
+        cwd?: string;
+        timeoutMs?: number;
+        envs?: Record<string, string>;
+    }): Promise<E2BCommandResultLike>;
+}
+/** Subset of the SDK's `Sandbox` instance the bond uses. */
+export interface E2BSandboxLike {
+    sandboxId: string;
+    commands: E2BCommandsLike;
+    files: E2BFilesystemLike;
+    getHost(port: number): string;
+    setTimeout(ms: number): Promise<void>;
+    kill(): Promise<void>;
+    pause?(): Promise<string>;
+    betaPause?(): Promise<string>;
+    isRunning(): Promise<boolean>;
+    updateNetwork?(opts: {
+        allowOut?: string[];
+        denyOut?: string[];
+    }): Promise<void>;
+}
+/** 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;
+    }> | {
+        sandboxes?: Array<{
+            sandboxId: string;
+        }>;
+    }>;
+    kill?(sandboxId: string, opts?: Record<string, unknown>): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Configuration + narrow structural shims for the E2B code-sandbox bond.
+ *
+ * The bond talks to E2B through the official `e2b` SDK; these types capture only
+ * the slice of that SDK surface the provider touches, plus the bond's own
+ * configuration. Keeping them structural (rather than importing the SDK's own
+ * types) keeps the provider testable with a fake client and documents exactly
+ * which SDK methods this bond depends on.
+ *
+ * @module
+ */
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@molecule/api-code-sandbox-e2b",
+  "version": "1.0.0",
+  "description": "E2B (e2b.dev) code sandbox provider — Firecracker microVMs with golden templates, fork, and pause/resume",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "molecule",
+    "sandbox",
+    "e2b",
+    "firecracker",
+    "code-execution"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.1",
+    "@molecule/api-code-sandbox": "1.0.3",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.1",
+    "@molecule/api-code-sandbox": "^1.0.1",
+    "@molecule/api-i18n": "^1.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@molecule/api-code-sandbox": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/code-sandbox/e2b"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/code-sandbox/e2b",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "e2b": "2.38.3"
+  }
+}