@deepseek-ai/dsh-e2b 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/e2b/e2b/README.md
+README.md: 7ade7c3d6522d8fa6d54d7011766238451b17c9a
+README.zh.md: b683f33d2211106cf422e780b2b37904b0c640ad

package/README.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-e2b
+
+English | [中文](README.zh.md)
+
+Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`; the [family map](../README.md) lists the opt-in composition.
+
+## Configuration
+
+```yaml
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
+```
+
+`apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes and controls the sandbox lifetime; expiry deletes the sandbox.
+
+## Lifecycle and ownership
+
+Construction starts one sandbox creation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command.
+
+Disposal first prevents new handle acquisition, then awaits setup and deletes the sandbox. A `SandboxNotFoundError` means expiry or another owner already deleted it and is accepted as quiescence. Initial directory setup failure makes one deletion attempt; the configured E2B timeout bounds a second failure. Provider plugins must load after this owner and dispose before it.
+
+## Model Experience
+
+None, as this shared runtime owner registers no model-visible context; provider adapters and their consumers own any rendered effects.
+
+#### KV Cache effect
+
+No direct invalidation; this package does not contribute request tokens.
+
+## Known Limitations and Deferred Work
+
+- **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
+- **Sandbox state is ephemeral** — disposal and timeout delete the sandbox; reconnect, pause/leave retention, templates, volumes, and snapshots are outside this POC.
+- **No deployment platform is configured** — network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
+- **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access retains the base image's policy.

package/README.zh.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-e2b
+
+[English](README.md) | 中文
+
+一个 E2B 沙箱的共享生命周期所有者。文件系统与进程管理适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`；可选组合见[包族索引](../README.md)。
+
+## 配置
+
+```yaml
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
+```
+
+`apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟并控制沙箱生命周期；超时会删除沙箱。
+
+## 生命周期与所有权
+
+构造阶段会启动一次沙箱创建。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。
+
+资源释放会先阻止继续获取新句柄，再等待初始化完成，然后删除沙箱。`SandboxNotFoundError` 表示沙箱已因超时或被另一个所有者删除，因此可视为完全停稳。初始目录设置失败时会尝试删除一次；若该尝试也失败，则由已配置的 E2B 超时约束沙箱的存活时间。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+
+## 模型体验
+
+无。本共享运行时所有者不注册模型可见上下文；提供方适配器及其消费方拥有所有渲染效果。
+
+#### KV Cache 影响
+
+不会直接失效；本包不会贡献请求 token。
+
+## 已知限制与延后工作
+
+- **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
+- **沙箱状态是短暂的**：资源释放和超时都会删除沙箱；重新连接、pause/leave 保留、模板、卷和快照均不在本 POC 范围内。
+- **没有配置部署平台**：网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
+- **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用基础镜像的策略。

package/lib/index.js

@@ -0,0 +1,117 @@
+import { randomUUID } from "node:crypto";
+import { posix } from "node:path";
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { CommandExitError, FileNotFoundError, FileType, FileType as FileType$1, Sandbox, Sandbox as Sandbox$1, SandboxNotFoundError, SandboxNotFoundError as SandboxNotFoundError$1 } from "e2b";
+//#region lib/types/index.js
+/**
+* Shared ownership of one E2B sandbox. Capability adapters await the same SDK
+* handle, so filesystem and process operations inhabit one remote Linux world.
+* @module @deepseek-ai/dsh-e2b
+*/
+/**
+* Quote one opaque argument for the SDK's unavoidable `/bin/bash -l -c` layer.
+* @param value - Exact argument value to preserve.
+* @returns A single shell word with no interpolation.
+*/
+function quoteE2BShellArg(value) {
+	return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+/**
+* Isolate E2B's hard-coded login shell behind a fresh randomized home path.
+* @param overrides - Additional environment entries for the internal command.
+* @returns A fresh mutable map that the E2B SDK may extend.
+*/
+function e2bControlEnvs(overrides = {}) {
+	return {
+		...overrides,
+		HOME: `/.dsh-e2b-control-${randomUUID()}`
+	};
+}
+/**
+* Creates one lazily consumable E2B SDK handle and deletes the sandbox at
+* timeout or disposal. Creation begins at plugin construction; adapters await
+* {@link getSandbox} before their first operation.
+*/
+var E2BSandboxService = class extends Service {
+	static Config = z.object({
+		apiKey: z.string(),
+		cwd: z.string().default("/home/user/workspace"),
+		timeoutMs: z.number().default(3e5)
+	});
+	/** Validated remote working directory shared by provider adapters. */
+	cwd;
+	/** Remote directory reserved for adapter-owned process and terminal state. */
+	runtimeRoot;
+	config;
+	ready;
+	disposed = false;
+	constructor(ctx, config) {
+		super(ctx, "e2b");
+		const resolved = config;
+		const apiKey = config.apiKey ?? process.env.E2B_API_KEY;
+		this.config = {
+			apiKey: apiKey ?? "",
+			cwd: resolved.cwd,
+			timeoutMs: resolved.timeoutMs
+		};
+		this.validate();
+		this.cwd = this.config.cwd;
+		this.runtimeRoot = posix.join(this.cwd, ".dsh-e2b");
+		this.ready = this.open();
+		this.ready.catch(() => {});
+		ctx.effect(() => async () => {
+			this.disposed = true;
+			let sandbox;
+			try {
+				sandbox = await this.ready;
+			} catch (_sandboxSetupFailure) {
+				return;
+			}
+			try {
+				await sandbox.kill();
+			} catch (error) {
+				if (!(error instanceof SandboxNotFoundError$1)) throw error;
+			}
+		}, "e2b sandbox teardown");
+	}
+	/**
+	* Return the shared live SDK handle.
+	* @returns the created sandbox after the configured cwd exists.
+	* @throws when E2B rejects creation or the service is disposing.
+	*/
+	async getSandbox() {
+		if (this.disposed) throw new Error("E2B sandbox service is disposing");
+		const sandbox = await this.ready;
+		if (this.disposed) throw new Error("E2B sandbox service is disposing");
+		return sandbox;
+	}
+	validate() {
+		if (this.config.apiKey.length === 0) throw new Error("dsh-e2b: configure apiKey or set E2B_API_KEY");
+		if (!posix.isAbsolute(this.config.cwd)) throw new Error(`dsh-e2b: cwd must be an absolute Linux path: ${this.config.cwd}`);
+		if (!Number.isFinite(this.config.timeoutMs) || this.config.timeoutMs <= 0) throw new Error("dsh-e2b: timeoutMs must be a positive finite number");
+	}
+	async open() {
+		const sandbox = await Sandbox$1.create({
+			apiKey: this.config.apiKey,
+			timeoutMs: this.config.timeoutMs,
+			secure: true,
+			lifecycle: { onTimeout: "kill" }
+		});
+		try {
+			await sandbox.files.makeDir(this.cwd);
+			await sandbox.files.makeDir(this.runtimeRoot);
+			const runtimeRoot = await sandbox.files.getInfo(this.runtimeRoot);
+			if (runtimeRoot.type !== FileType$1.DIR || runtimeRoot.symlinkTarget !== void 0) throw new Error(`dsh-e2b: runtime root must be a real directory: ${this.runtimeRoot}`);
+			await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`, { envs: e2bControlEnvs() });
+			return sandbox;
+		} catch (error) {
+			try {
+				await sandbox.kill();
+			} catch (_sandboxSetupRollbackFailure) {}
+			throw error;
+		}
+	}
+};
+//#endregion
+export { CommandExitError, E2BSandboxService, E2BSandboxService as default, FileNotFoundError, FileType, Sandbox, SandboxNotFoundError, e2bControlEnvs, quoteE2BShellArg };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-e2b`.
+* @module @deepseek-ai/dsh-e2b/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-e2b";
+/** Cordis companion plugin name. */
+const name = "e2b-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: sandbox creation and teardown have one SDK promise and
+* no independent event or mutable-data relationship to cross-check.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared ownership of one E2B sandbox. Capability adapters await the same SDK
+ * handle, so filesystem and process operations inhabit one remote Linux world.
+ * @module @deepseek-ai/dsh-e2b
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { Sandbox } from 'e2b';
+export { CommandExitError, FileNotFoundError, FileType, Sandbox, SandboxNotFoundError, } from 'e2b';
+export type { CommandHandle, CommandResult, EntryInfo } from 'e2b';
+/**
+ * Quote one opaque argument for the SDK's unavoidable `/bin/bash -l -c` layer.
+ * @param value - Exact argument value to preserve.
+ * @returns A single shell word with no interpolation.
+ */
+export declare function quoteE2BShellArg(value: string): string;
+/**
+ * Isolate E2B's hard-coded login shell behind a fresh randomized home path.
+ * @param overrides - Additional environment entries for the internal command.
+ * @returns A fresh mutable map that the E2B SDK may extend.
+ */
+export declare function e2bControlEnvs(overrides?: Readonly<Record<string, string>>): Record<string, string>;
+/** Configuration for the shared E2B sandbox owner. */
+export interface Config {
+    /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
+    apiKey?: string;
+    /** Shared remote working directory, created before adapters receive the sandbox. */
+    cwd?: string;
+    /** E2B sandbox lifetime in milliseconds; expiry always deletes the sandbox. */
+    timeoutMs?: number;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        e2b: E2BSandboxService;
+    }
+}
+/**
+ * Creates one lazily consumable E2B SDK handle and deletes the sandbox at
+ * timeout or disposal. Creation begins at plugin construction; adapters await
+ * {@link getSandbox} before their first operation.
+ */
+export declare class E2BSandboxService extends Service {
+    static Config: z<Config>;
+    /** Validated remote working directory shared by provider adapters. */
+    readonly cwd: string;
+    /** Remote directory reserved for adapter-owned process and terminal state. */
+    readonly runtimeRoot: string;
+    private readonly config;
+    private readonly ready;
+    private disposed;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Return the shared live SDK handle.
+     * @returns the created sandbox after the configured cwd exists.
+     * @throws when E2B rejects creation or the service is disposing.
+     */
+    getSandbox(): Promise<Sandbox>;
+    private validate;
+    private open;
+}
+export default E2BSandboxService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-e2b`.
+ * @module @deepseek-ai/dsh-e2b/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "e2b-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@deepseek-ai/dsh-e2b",
+  "description": "Shared E2B sandbox lifecycle for DeepSeek Harness provider adapters",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/e2b/e2b"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "e2b": "2.29.1",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-loader-smoke": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}