@x1a0f3n9/dsh-e2b 0.1.5-rc.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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: 09c23e4540b708ada5fc6d485806058793937a09
+README.zh.md: 4bf1c6f220242b366b8f09118a6fd0fee6151d11

package/README.md

@@ -0,0 +1,145 @@
+---
+description: "One shared remote Linux sandbox for E2B-backed file and command work: configuration, lifetime, and what happens at startup and shutdown."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-e2b
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-e2b` runs the agent's file operations, shell commands, and terminals in one shared remote Linux sandbox instead of on your machine. The sandbox is created at startup and deleted when its configured lifetime expires or the app shuts down, so everything it holds is ephemeral. Configure an API key, an absolute remote working directory, and the sandbox lifetime. Use it with `dsh-fs-e2b` and `dsh-subprocess-e2b`; by itself it adds no user-visible capability. It sends nothing to the model, and no shipped composition enables E2B by default.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Use this package when you want the agent's file and command work to run in a remote Linux sandbox rather than on your machine. It is the foundation of the E2B family: with the filesystem and subprocess packages mounted, all of that work shares one remote working directory and process world.
+
+### When to choose it
+
+Choose the E2B family when work should be isolated from the host machine — for example, when you want the agent's file edits and command runs to happen somewhere disposable. Choose the local filesystem and subprocess packages when running on the host is fine. This package is invisible to the model and adds no request cost.
+
+### Minimal configuration
+
+Three settings matter: an API key (or the `E2B_API_KEY` environment variable), an absolute remote working directory, and the sandbox lifetime. A bad key, a relative working directory, or an invalid lifetime rejects startup before any remote work happens.
+
+```yaml
+- name: '@x1a0f3n9/dsh-e2b'
+  config:
+    apiKey: <E2B API key>
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+
+- name: '@x1a0f3n9/dsh-subprocess-e2b'
+- name: '@x1a0f3n9/dsh-fs-e2b'
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `apiKey` | `E2B_API_KEY` | API key for the host SDK connection; never installed in the sandbox |
+| `cwd` | `/home/user/workspace` | Remote working directory the family shares; absolute POSIX path |
+| `timeoutMs` | `300,000` | Sandbox lifetime in milliseconds; the sandbox is deleted when it expires |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-e2b) is the exhaustive source for every accepted field and its JSDoc.
+
+### What you get
+
+With this package mounted, file reads and writes, shell commands, and terminals all operate inside the sandbox's working directory, so the agent sees one consistent remote world: what it writes with the file features is what its commands can read, and vice versa. The remote working directory is created if it does not exist yet.
+
+### Starting and stopping the sandbox
+
+Loading the plugin starts the sandbox in the background; the filesystem and subprocess features are ready once it is up. The sandbox lives for the configured lifetime (default five minutes) unless the app stops first — in both cases it is deleted, so save anything you still need before then. If the sandbox disappears while running (expired or removed elsewhere), the family treats that as a clean end rather than an error.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the owner and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+- **One sandbox, one handle.** All adapters await the same `getSandbox()` promise, so filesystem and process operations share one remote Linux world.
+- **Secure by construction.** The sandbox is created with `secure: true` and `lifecycle: { onTimeout: 'kill' }`, so expiry always deletes it.
+- **Isolated control shells.** `e2bControlEnvs()` gives every internal command shell a fresh randomized `HOME`, and `quoteE2BShellArg()` preserves opaque arguments through the SDK's unavoidable `/bin/bash -l -c` layer.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `E2BRuntime` service, `Config` schema, validation, sandbox open and teardown |
+| — | No runtime invariant companion is published; sandbox creation and teardown have one SDK promise and no independent event or mutable-data relationship to cross-check. |
+
+### Lifecycle
+
+`open()` creates the sandbox, prepares `cwd` and the private runtime root, rejects a non-directory or symlink runtime root, and applies `chmod 700`. Disposal prevents new handle acquisition, awaits setup, and deletes the sandbox, accepting `SandboxNotFoundError` as quiescence. `getSandbox()` re-checks the disposed flag after awaiting readiness, so disposal racing readiness still rejects acquisition; an eager connection failure stays observed but does not reject plugin load, and `getSandbox()` surfaces it.
+
+### Setup failure handling
+
+Any directory-setup failure makes one deletion attempt and preserves the original error; a failed rollback is bounded by E2B's configured sandbox timeout (see the Dev Note). Provider plugins must load after this owner and dispose before it, because every adapter awaits the same handle.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the family composition to the subprocess seam surface and the decision evidence behind the remote execution world.
+
+- [E2B provider family map](../README.md) — the three packages and the opt-in composition.
+- [Subprocess subsystem](../../../docs/subsystems/subprocess.md) — the subprocess seam contract and the generated Cordis surface, including `ctx.e2b`.
+- [Portable execution-world decision](../../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) — why consumers delegate to `ctx.fs` and `ctx.subprocess`, and what stays in the host.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-e2b) — every accepted config field and its source declaration.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the shared remote-runtime owner registers no model context; provider adapters and consumers own rendered effects.
+
+#### KV Cache effect
+
+No direct invalidation: the owner contributes no request tokens and never mutates a request prefix, so provider cache reuse is unaffected.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the E2B family is a poor fit or needs special operational care. They are current package constraints, not a task backlog.
+
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open questions and directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above and the package code.
+
+#### Open: sandbox setup rollback
+
+The `open()` failure path makes a single deletion attempt and preserves the original setup failure. Retry state stays deferred unless a real double failure outlives E2B's configured sandbox timeout (TODO(e2b-setup-rollback)).
+
+</details>

package/README.zh.md

@@ -0,0 +1,145 @@
+---
+description: "E2B 文件与命令工作的共享远程 Linux 沙箱：配置、生命周期，以及启动与关闭时会发生什么。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-e2b
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-e2b` 让 agent（智能体）的文件操作、shell 命令与终端在一个共享的远程 Linux 沙箱内运行，而不是在你的机器上。应用启动时会创建沙箱，并在配置的生命周期到期或应用关闭时删除它，因此其中保存的一切都是短暂的。请配置 API 密钥、绝对远程工作目录与沙箱生命周期。请与 `dsh-fs-e2b`、`dsh-subprocess-e2b` 一起使用；单独使用它不会带来任何用户可见的能力。它不会向模型发送任何内容，而且任何已发布的组合都不会默认启用 E2B。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当你希望 agent 的文件操作与命令执行在远程 Linux 沙箱而非你的机器上进行时，使用本包。它是 E2B 家族的基础：挂载文件系统与子进程包之后，所有这些工作都会共享同一个远程工作目录与进程环境。
+
+### 何时选择
+
+当工作应与宿主机器隔离时——例如你希望 agent 的文件编辑与命令运行发生在某个可丢弃的环境中——选择 E2B 家族。当在宿主上运行没有问题的时候，选择本地的文件系统与子进程包。本包对模型不可见，也不增加任何请求成本。
+
+### 最小配置
+
+三个设置很重要：API 密钥（或 `E2B_API_KEY` 环境变量）、绝对远程工作目录与沙箱生命周期。密钥错误、相对工作目录或无效生命周期都会在任何远程工作开始前拒绝启动。
+
+```yaml
+- name: '@x1a0f3n9/dsh-e2b'
+  config:
+    apiKey: <E2B API key>
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+
+- name: '@x1a0f3n9/dsh-subprocess-e2b'
+- name: '@x1a0f3n9/dsh-fs-e2b'
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `apiKey` | `E2B_API_KEY` | 宿主 SDK 连接的 API 密钥；绝不会安装进沙箱 |
+| `cwd` | `/home/user/workspace` | 家族共享的远程工作目录；必须是绝对 POSIX 路径 |
+| `timeoutMs` | `300,000` | 沙箱生命周期（毫秒）；到期后沙箱被删除 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-e2b)完整列出了每个受支持字段及其 JSDoc，是这些信息的真源。
+
+### 你能得到什么
+
+挂载本包后，文件读写、shell 命令与终端都会在沙箱的工作目录内运行，因此 agent 看到的是一个一致的远程世界：它用文件功能写入的内容，正是它的命令能够读取的内容，反之亦然。远程工作目录若不存在，会自动创建。
+
+### 沙箱的启动与停止
+
+加载插件会在后台启动沙箱；文件系统与子进程功能在其就绪后即可使用。沙箱存活时间为配置的生命周期（默认五分钟），除非应用先停止——两种情况下沙箱都会被删除，因此请在此之前保存你仍需要的内容。如果运行期间沙箱消失（到期或被别处删除），家族会将其视为正常终止，而不是错误。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释所有者背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+- **一个沙箱，一个句柄。** 所有适配器都等待同一个 `getSandbox()` promise，因此文件系统与进程操作共享同一个远程 Linux 世界。
+- **构造即安全。** 沙箱以 `secure: true` 和 `lifecycle: { onTimeout: 'kill' }` 创建，因此超时必定删除它。
+- **隔离的控制 shell。** `e2bControlEnvs()` 为每个内部命令 shell 提供全新随机生成的 `HOME`，`quoteE2BShellArg()` 则通过 SDK 不可避免的 `/bin/bash -l -c` 层保留不透明参数。
+
+### 源码索引
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`E2BRuntime` 服务、`Config` schema、校验、沙箱创建与拆除 |
+| — | 不发布运行时不变式伴生入口；沙箱创建与拆除只有一个 SDK promise，没有可交叉核对的独立事件或可变数据关系。 |
+
+### 生命周期
+
+`open()` 创建沙箱、准备 `cwd` 与私有运行时根目录、拒绝非目录或符号链接的运行时根目录，并执行 `chmod 700`。dispose（资源释放）会阻止新的句柄获取、等待初始化完成并删除沙箱，把 `SandboxNotFoundError` 视为完全停稳。`getSandbox()` 在等待就绪后重新检查已释放标志，因此与就绪发生竞态的资源释放仍会拒绝获取句柄；预先发起的连接即使失败也会保持可观察状态，但不会导致插件加载失败；`getSandbox()` 会将该失败暴露给调用方。
+
+### 初始化失败处理
+
+任何目录初始化失败都会尝试删除一次并保留原始错误；回滚失败由 E2B 配置的沙箱超时约束（见开发备注）。提供方插件必须在该所有者之后加载、并在其之前 dispose，因为每个适配器都等待同一个句柄。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从家族组合逐步进入子进程 seam 表面，以及远程执行世界背后的决策证据。
+
+- [E2B 提供方家族地图](../README.zh.md)——三个包与可选组合。
+- [子进程子系统](../../../docs/subsystems/subprocess.zh.md)——子进程 seam 约定与生成的 Cordis 表面，包括 `ctx.e2b`。
+- [可移植执行世界决策](../../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md)——消费方为何委托给 `ctx.fs` 与 `ctx.subprocess`，以及留在宿主中的内容。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-e2b)——每个受支持配置字段及其源声明。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。本共享远程运行时所有者不注册任何模型上下文；提供方适配器与消费方拥有所有渲染效果。
+
+#### KV Cache 影响
+
+不会直接失效：所有者不贡献任何请求 token，也从不改变请求前缀，因此提供方缓存复用不受影响。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明 E2B 家族何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。
+
+- **不是完整的 harness 运行时**：Cordis 服务、agent／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
+- **沙箱状态是短暂的**：dispose 与超时都会删除沙箱；重新连接、pause/leave 保留、模板、卷和快照均不在本 POC 范围内。
+- **没有配置部署平台**：网络策略、宿主工作区同步与沙箱发现均不在本 POC 范围内。
+- **`cwd` 是解析约定，而不是包含边界**：适配器与命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用基础镜像的策略。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文和包代码为准。
+
+#### 开放：沙箱初始化回滚
+
+`open()` 的失败路径只会尝试删除一次，并保留原始初始化失败。除非真实的双重失败超出 E2B 配置的沙箱超时，否则重试状态保持延后（TODO(e2b-setup-rollback)）。
+
+</details>

package/lib/index.js

@@ -0,0 +1,145 @@
+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";
+import { proxyRouteFor } from "@x1a0f3n9/dsh-http-proxy";
+//#region lib/types/api-url.js
+/**
+* The E2B control-plane URL, derived the way the SDK derives it.
+* @module @x1a0f3n9/dsh-e2b/src/api-url.ts
+*/
+/** The SDK's own default control-plane domain; `E2B_DOMAIN` overrides it there and here alike. */
+const E2B_DEFAULT_DOMAIN = "e2b.app";
+/** The debug control plane the SDK substitutes, on loopback and plain HTTP. */
+const E2B_DEBUG_API_URL = "http://localhost:3000";
+/**
+* The control-plane URL the SDK will actually call, derived the way the SDK derives it: an explicit
+* `E2B_API_URL` first, then the debug substitute, then the domain default. Choosing a proxy for
+* anything else would pick the wrong scheme's proxy, ignore a bypass entry naming the real host, and
+* — for the loopback debug plane — hand a proxy the control-plane traffic and its API key.
+*
+* @param env - the process environment to read; overridable so tests need no ambient state.
+* @returns the absolute control-plane URL.
+*/
+function e2bApiUrl(env = process.env) {
+	const explicit = env.E2B_API_URL;
+	if (explicit !== void 0 && explicit !== "") return explicit;
+	if ((env.E2B_DEBUG ?? "false").toLowerCase() === "true") return E2B_DEBUG_API_URL;
+	return `https://api.${env.E2B_DOMAIN ?? E2B_DEFAULT_DOMAIN}`;
+}
+//#endregion
+//#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 @x1a0f3n9/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 E2BRuntime = 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 route = proxyRouteFor(new URL(e2bApiUrl()));
+		const sandbox = await Sandbox$1.create({
+			apiKey: this.config.apiKey,
+			timeoutMs: this.config.timeoutMs,
+			secure: true,
+			lifecycle: { onTimeout: "kill" },
+			...route.proxied ? { proxy: route.proxy } : {}
+		});
+		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, E2BRuntime, E2BRuntime as default, FileNotFoundError, FileType, Sandbox, SandboxNotFoundError, e2bControlEnvs, quoteE2BShellArg };

package/lib/types/api-url.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The E2B control-plane URL, derived the way the SDK derives it.
+ * @module @x1a0f3n9/dsh-e2b/src/api-url.ts
+ */
+/**
+ * The control-plane URL the SDK will actually call, derived the way the SDK derives it: an explicit
+ * `E2B_API_URL` first, then the debug substitute, then the domain default. Choosing a proxy for
+ * anything else would pick the wrong scheme's proxy, ignore a bypass entry naming the real host, and
+ * — for the loopback debug plane — hand a proxy the control-plane traffic and its API key.
+ *
+ * @param env - the process environment to read; overridable so tests need no ambient state.
+ * @returns the absolute control-plane URL.
+ */
+export declare function e2bApiUrl(env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=api-url.d.ts.map

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 @x1a0f3n9/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: E2BRuntime;
+    }
+}
+/**
+ * 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 E2BRuntime 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 E2BRuntime;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@x1a0f3n9/dsh-e2b",
+  "description": "Shared E2B sandbox lifecycle for DeepSeek Harness provider adapters",
+  "version": "0.1.5-rc.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-http-proxy": "^0.1.5-rc.3"
+  },
+  "dependencies": {
+    "e2b": "2.29.1",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-agent": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-agent-loop-testkit": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-app-boot": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-bash-local": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-fs-e2b": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-loader-smoke": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-lsp": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-lsp-stdio": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-sandbox-policy": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-session": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-session-projection": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-subprocess-e2b": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-terminal": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-terminal-bash": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-http-proxy": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-launch-environment": "^0.1.5-rc.3"
+  }
+}