@termbridge/sandbox-e2b 1.0.7

package/dist/e2b-provider.d.ts

@@ -0,0 +1,54 @@
+import type { ExecResult, SandboxProvider } from "@termbridge/core";
+interface SandboxCreateOpts {
+    template?: string;
+    envs?: Record<string, string>;
+    apiKey?: string;
+    timeoutMs?: number;
+    metadata?: Record<string, string>;
+}
+interface E2BSandboxLike {
+    readonly sandboxId: string;
+    commands: {
+        run(cmd: string, opts?: {
+            timeoutMs?: number;
+        }): Promise<{
+            exitCode: number;
+            stdout: string;
+            stderr: string;
+            error?: string;
+        }>;
+    };
+    kill(): Promise<boolean>;
+}
+export interface E2BSandboxProviderOptions {
+    /** E2B API key. Defaults to E2B_API_KEY env. Required for a real cloud call. */
+    apiKey?: string;
+    /** E2B sandbox template (must permit tmux). Defaults to "base". */
+    template?: string;
+    /** Sandbox lifetime in ms. Defaults to 3_600_000 (1h). */
+    timeoutMs?: number;
+    /** Injectable sandbox factory (for tests). Defaults to the real E2B Sandbox.create. */
+    sandboxFactory?: (opts: SandboxCreateOpts) => Promise<E2BSandboxLike>;
+}
+export declare class E2BSandboxProvider implements SandboxProvider {
+    readonly name = "e2b";
+    private readonly apiKey;
+    private readonly template;
+    private readonly timeoutMs;
+    private readonly sandboxFactory;
+    private sandbox;
+    constructor(opts?: E2BSandboxProviderOptions);
+    ensure(opts: {
+        name: string;
+        cwd: string;
+        image?: string;
+        env?: Record<string, string>;
+    }): Promise<void>;
+    exec(args: string[]): Promise<ExecResult>;
+    /** Run a raw shell command string; map CommandExitError → non-zero result. */
+    private execRaw;
+    destroy(): Promise<void>;
+    /** Cloud sandbox id if one is currently provisioned (for smoke/logging). */
+    get sandboxId(): string | undefined;
+}
+export {};

package/dist/e2b-provider.js

@@ -0,0 +1,114 @@
+// E2BSandboxProvider — a concrete SandboxProvider backed by the E2B cloud sandbox
+// SDK. One instance provisions/execs/destroys exactly one E2B sandbox (one sandbox
+// == one termbridge session). Every SDK call is behind an injectable
+// `sandboxFactory` so the unit is tested with a recording mock and never touches a
+// real cloud (D3: this package owns the SDK; @termbridge/core stays dependency-free).
+//
+// exec() maps an argv to the SDK's commands.run, which takes a SHELL COMMAND STRING
+// (not an argv) — so each arg is shell-quoted. The SDK throws CommandExitError on
+// non-zero exit; we catch it and return {stdout, stderr, code} verbatim so exec
+// NEVER rejects on non-zero (the ExecFn contract DockerEnvironment + tmux helpers
+// honour). Genuine SDK errors (network/auth) propagate.
+import { Sandbox } from "e2b";
+const DEFAULT_TIMEOUT_MS = 3_600_000;
+/** Shell-quote a single argv token (single-quote wrap if it has spaces/metachars). */
+function shellQuote(arg) {
+    if (arg.length === 0)
+        return "''";
+    if (/^[\w@%+=:,./-]+$/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+export class E2BSandboxProvider {
+    name = "e2b";
+    apiKey;
+    template;
+    timeoutMs;
+    sandboxFactory;
+    sandbox;
+    constructor(opts = {}) {
+        this.apiKey = opts.apiKey ?? process.env.E2B_API_KEY;
+        this.template = opts.template ?? "base";
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.sandboxFactory =
+            opts.sandboxFactory ??
+                ((o) => Sandbox.create(o));
+    }
+    async ensure(opts) {
+        // Tear down any previous sandbox this instance owned (one instance == one sandbox).
+        await this.destroy();
+        this.sandbox = await this.sandboxFactory({
+            ...(opts.image ? { template: opts.image } : { template: this.template }),
+            envs: opts.env,
+            apiKey: this.apiKey,
+            timeoutMs: this.timeoutMs,
+            metadata: { name: opts.name },
+        });
+        try {
+            // The E2B `base` template does NOT ship tmux, and the default user is
+            // non-root (uid 1000, in the sudo group). Install with passwordless sudo
+            // so SandboxEnvironment.ensureSession can run tmux new-session.
+            const install = await this.execRaw("command -v tmux >/dev/null 2>&1 || (sudo -n apt-get update -y && sudo -n apt-get install -y tmux)");
+            if (install.code !== 0) {
+                throw new Error(`E2BSandboxProvider: failed to install tmux (exit ${install.code}): ${install.stderr || install.stdout}`);
+            }
+            const probe = await this.execRaw("command -v tmux");
+            if (probe.code !== 0) {
+                throw new Error("E2BSandboxProvider: tmux still missing after install");
+            }
+        }
+        catch (err) {
+            // Cloud sandbox is already billed/running — always kill on setup failure
+            // so a failed smoke/open cannot leave orphans on the E2B dashboard.
+            await this.destroy();
+            throw err;
+        }
+    }
+    async exec(args) {
+        return this.execRaw(args.map(shellQuote).join(" "));
+    }
+    /** Run a raw shell command string; map CommandExitError → non-zero result. */
+    async execRaw(cmd) {
+        if (!this.sandbox) {
+            throw new Error("E2BSandboxProvider.exec called before ensure");
+        }
+        try {
+            const r = await this.sandbox.commands.run(cmd, { timeoutMs: this.timeoutMs });
+            return { stdout: r.stdout, stderr: r.stderr, code: r.exitCode };
+        }
+        catch (err) {
+            const e = err;
+            if (typeof e.exitCode === "number") {
+                return { stdout: e.stdout ?? "", stderr: e.stderr ?? "", code: e.exitCode };
+            }
+            throw err;
+        }
+    }
+    async destroy() {
+        const sb = this.sandbox;
+        this.sandbox = undefined;
+        if (!sb)
+            return;
+        const id = sb.sandboxId;
+        // Prefer instance kill, then static Sandbox.kill as a belt-and-suspenders
+        // path so a hung instance handle cannot leave a dashboard orphan.
+        try {
+            await sb.kill();
+        }
+        catch {
+            /* try static kill below */
+        }
+        if (id) {
+            try {
+                await Sandbox.kill(id, this.apiKey ? { apiKey: this.apiKey } : undefined);
+            }
+            catch {
+                // Swallow: destroy must never throw (mirrors SandboxEnvironment.destroySession).
+            }
+        }
+    }
+    /** Cloud sandbox id if one is currently provisioned (for smoke/logging). */
+    get sandboxId() {
+        return this.sandbox?.sandboxId;
+    }
+}

package/dist/from-env.d.ts

@@ -0,0 +1,8 @@
+import type { SandboxProvider } from "@termbridge/core";
+/**
+ * Returns an `E2BSandboxProvider` when `E2B_API_KEY` is set (or `apiKey` is
+ * passed), otherwise `undefined`. Never throws for a missing key.
+ */
+export declare function sandboxProviderFromEnv(opts?: {
+    apiKey?: string;
+}): SandboxProvider | undefined;

package/dist/from-env.js

@@ -0,0 +1,11 @@
+import { E2BSandboxProvider } from "./e2b-provider.js";
+/**
+ * Returns an `E2BSandboxProvider` when `E2B_API_KEY` is set (or `apiKey` is
+ * passed), otherwise `undefined`. Never throws for a missing key.
+ */
+export function sandboxProviderFromEnv(opts) {
+    const apiKey = opts?.apiKey ?? process.env.E2B_API_KEY;
+    if (!apiKey)
+        return undefined;
+    return new E2BSandboxProvider({ apiKey });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { E2BSandboxProvider, type E2BSandboxProviderOptions } from "./e2b-provider.js";
+export { sandboxProviderFromEnv } from "./from-env.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// Public barrel for @termbridge/sandbox-e2b — a concrete SandboxProvider backed
+// by the E2B cloud sandbox SDK. @termbridge/core stays dependency-free (D3);
+// this package owns the only `e2b` import.
+export { E2BSandboxProvider } from "./e2b-provider.js";
+export { sandboxProviderFromEnv } from "./from-env.js";

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@termbridge/sandbox-e2b",
+	"version": "1.0.7",
+	"type": "module",
+	"license": "MIT",
+	"description": "E2B SandboxProvider for termbridge — env:\"sandbox\" isolation via the E2B cloud SDK",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check ."
+	},
+	"dependencies": {
+		"@termbridge/core": "^1.0.7",
+		"e2b": "^2.32.0"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts"
+}