@deepseek-ai/dsh-subprocess-e2b 0.1.2-rc.1 → 0.1.3-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/subprocess-e2b/README.md
-README.md: 28f1b3410781fd87e40527d70e823bd9111d57e7
-README.zh.md: 3d9a35dea74126ae4cc5d381944b2fb5a86f61ee
+README.md: 8222f81e3b077aabf5c4dd4f2c4d58e501b2846a
+README.zh.md: 449ca331f96cb7799535a94c7b4d7583c2447ead

package/README.md

@@ -29,7 +29,7 @@ Use this package when the agent's shell commands and terminals should run inside
 
 ### When to choose it
 
-Choose it when a composition already uses the E2B sandbox and you want commands and terminals to run there. Choose the local subprocess package for host execution. Tooling that needs a process id immediately — for example the ACP child backend — cannot use this package.
+Choose it when a composition already uses the E2B sandbox and you want commands and terminals to run there. Choose the local subprocess package for host execution.
 
 ### Configuration
 
@@ -71,7 +71,7 @@ This section explains the design decisions behind the provider and points at the
 
 ### Design philosophy
 
-- **Deferred remote identity.** The synchronous seam never blocks on the network: the handle publishes its real process-group id asynchronously, and the wrapper's private files are the authority for pid, exit code, and spill validity.
+- **Provider-private remote identity.** The synchronous seam never blocks on the network. Private wrapper files asynchronously publish a process-group identity for stdin, observation, termination, and quiescence checks, together with the direct exit code and spill validity; that identity is not the requested target PID.
 - **One teardown ladder.** Termination, rollback, and disposal share one process-group signal path — `SIGTERM`, then `SIGKILL` plus the SDK kill fallback — and treat proven quiescence as final.
 - **Environment is explicit.** Nothing from the host and nothing credential-shaped enters the sandbox implicitly; every ambient value is scrubbed and every `spec.env` entry is an explicit opt-in.
 
@@ -91,9 +91,9 @@ This section explains the design decisions behind the provider and points at the
 
 The bootstrap resolves its own tools from the sandbox PATH, refuses any missing or non-executable path, execs through `env -i` and `setsid --wait`, publishes the process-group id and exit code to private files beneath `ctx.e2b.runtimeRoot/processes`, and redirects stdout and stderr through base64 encoders that emit a reserved completion frame; `tee` and `head -c` bound optional spill files.
 
-### Process identity and publication
+### Private process identity and publication
 
-The synchronous seam returns a handle immediately while the command starts asynchronously; `pid` stays `-1` until the wrapper publishes its process-group id and the adapter validates it, and stdin plus ordinary observation wait for that publication. A startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
+The synchronous seam returns a handle immediately while the command starts asynchronously. The wrapper publishes a private process-group ID for stdin, observation, termination, and quiescence checks, but that ID is not the requested target PID. A startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 
 ### Environment boundary
 
@@ -142,7 +142,6 @@ No direct invalidation: the consumer seams own any request-prefix changes; this
 These limits define when the provider is a poor fit or needs special operational care. They are current package constraints, not a task backlog.
 
 - **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate the base64 transport even when this adapter exposes bounded raw-byte tails, so the subprocess seam's normal host-memory bound is not achieved and transport retention is larger than the source stream.
-- **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Private state lives for the sandbox lifetime** — process directories and valid spill files remain under `.dsh-e2b` until the owner deletes the sandbox; this POC supplies no in-sandbox sweep.
 - **Control state shares the sandbox user's UID** — E2B runs every command as the same default user, so `0700`/`0600` modes cannot isolate `.dsh-e2b` control files from concurrently running sandbox processes; real isolation needs an E2B per-command user or an out-of-band control channel.
 - **Numeric process identities are not reuse-fenced** — E2B exposes numeric PID/PGID input, signalling, and cleanup operations but no atomic identity-bound alternative; replacement is deferred until E2B adds an identity primitive or a failure demonstrates a narrower protocol.

package/README.zh.md

@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 何时选择
 
-当组合已经使用 E2B 沙箱且希望命令与终端在其中运行时，选择本包。宿主执行请选择本地子进程包。需要立即获得进程 ID 的工具——例如 ACP（Agent Client Protocol）子进程后端——无法使用本包。
+当组合已经使用 E2B 沙箱且希望命令与终端在其中运行时，选择本包。宿主执行请选择本地子进程包。
 
 ### 配置
 
@@ -71,7 +71,7 @@ agent 可以在沙箱中打开交互式终端、发送输入、读取输出，
 
 ### 设计理念
 
-- **延后的远程身份。** 同步 seam 从不阻塞在网络请求上：句柄异步发布真实进程组 ID，包装层的私有文件是 pid、退出码与 spill 有效性的权威来源。
+- **提供方私有的远程身份。** 同步 seam 从不阻塞在网络请求上。包装层的私有文件会异步发布进程组身份，供 stdin、观察、终止与完全停稳检查使用，同时发布直接退出码与 spill 有效性；该身份不是请求目标的 PID。
 - **单一终止阶梯。** 终止、回滚与资源释放共享同一条进程组信号路径——先 `SIGTERM`，再 `SIGKILL` 加 SDK kill 回退——并把已证明的完全停稳视为最终状态。
 - **环境必须显式。** 宿主内容与形似凭据的内容都不会隐式进入沙箱；每个环境值都会被清理，每个 `spec.env` 条目都是显式选择。
 
@@ -91,9 +91,9 @@ agent 可以在沙箱中打开交互式终端、发送输入、读取输出，
 
 引导脚本会从沙箱 PATH 解析自身所需的工具，拒绝任何缺失或不可执行的路径，通过 `env -i` 与 `setsid --wait` 执行 exec，把进程组 ID 与退出码发布到 `ctx.e2b.runtimeRoot/processes` 下的私有文件，并把 stdout 与 stderr 重定向到带保留完成帧的 base64 编码器；`tee` 与 `head -c` 约束可选 spill 文件的大小。
 
-### 进程身份与发布
+### 私有进程身份与发布
 
-同步 seam 会立即返回句柄，同时命令异步启动；`pid` 在包装层发布进程组 ID 且适配器验证通过之前保持 `-1`，stdin 与常规观察都等待该发布。启动信号会在分配前中止环境与私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
+同步 seam 会立即返回句柄，同时命令异步启动。包装层会发布私有进程组 ID，供 stdin、观察、终止与完全停稳检查使用，但该 ID 不是请求目标的 PID。启动信号会在分配前中止环境与私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 
 ### 环境边界
 
@@ -142,7 +142,6 @@ agent 可以在沙箱中打开交互式终端、发送输入、读取输出，
 这些限制说明本提供方何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。
 
 - **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界原始字节尾部，E2B `CommandHandle.stdout` 与 `.stderr` 仍会累积 base64 传输内容，因此无法达到子进程 seam 通常提供的宿主内存边界，而且传输保留量大于源数据流。
-- **不支持需要同步 PID 的消费方**：远程启动期间 `pid` 保持 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **私有状态随沙箱生命周期存在**：进程目录与有效的 spill 文件会留在 `.dsh-e2b` 下，直到所有者删除沙箱；本 POC 不提供沙箱内清理。
 - **控制状态与沙箱用户同 UID**：E2B 以同一默认用户运行每条命令，因此 `0700`/`0600` 权限无法把 `.dsh-e2b` 控制文件与并发运行的沙箱进程隔离开；真正的隔离需要 E2B 提供按命令用户或带外控制通道。
 - **数值进程身份没有复用围栏**：E2B 公开基于数值 PID/PGID 的输入、信号发送与清理操作，却没有与身份原子绑定的替代方案；在 E2B 新增身份原语，或实际故障证明需要更窄的协议之前，替代方案继续延后。

package/lib/index.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { posix } from "node:path";
+import { inspect } from "node:util";
 import z from "@deepseek-ai/schemastery";
 import { SENSITIVE_ENV_PATTERN, SubprocessRuntime } from "@deepseek-ai/dsh-subprocess";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
@@ -399,7 +400,7 @@ function waitWithSignal(promise, signal) {
 		});
 	});
 }
-/** E2B-backed subprocess handle with deferred remote PID acquisition. */
+/** E2B-backed subprocess handle with private remote process-group tracking. */
 var E2BSubprocessHandle = class {
 	runtime;
 	spec;
@@ -421,7 +422,7 @@ var E2BSubprocessHandle = class {
 	stderrReader;
 	paths;
 	controlEnvs = {};
-	remotePid = -1;
+	remoteProcessGroupId;
 	outputTransportError;
 	outputDrainExpired = false;
 	stateDirectoryCreated = false;
@@ -465,10 +466,6 @@ var E2BSubprocessHandle = class {
 		this.done.catch(() => {});
 		if (spec.signal?.aborted === true) this.terminate();
 	}
-	/** Remote process id after start; `-1` while E2B startup is pending or after it fails. */
-	get pid() {
-		return this.remotePid;
-	}
 	/** @inheritdoc */
 	terminate() {
 		if (this.quiescenceProven || this.terminationAttempt !== void 0) return;
@@ -497,7 +494,7 @@ var E2BSubprocessHandle = class {
 				this.markQuiescent();
 				return true;
 			}
-			if (this.remotePid <= 0) {
+			if (this.remoteProcessGroupId === void 0) {
 				const attempt = this.terminationAttempt;
 				if (attempt !== void 0 && await waitWithSignal(attempt.catch(() => void 0), signal) === WAIT_ABORTED) return false;
 				this.throwTerminationFailure();
@@ -524,7 +521,7 @@ var E2BSubprocessHandle = class {
 			}
 			throw error;
 		}
-		const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid;
+		const processGroupId = this.remoteProcessGroupId ?? handle.pid;
 		while (await this.groupAlive(sandbox, processGroupId, signal)) {
 			this.throwTerminationFailure();
 			if (!await waitTick(this.pollMs, signal)) return false;
@@ -577,7 +574,7 @@ var E2BSubprocessHandle = class {
 			}
 			this.commandState.resolve(handle);
 			try {
-				this.remotePid = await this.waitForProcessGroupId(sandbox, completion);
+				this.remoteProcessGroupId = await this.waitForProcessGroupId(sandbox, completion);
 			} catch (error) {
 				try {
 					await this.rollbackUnpublishedGroup(sandbox, handle);
@@ -779,7 +776,7 @@ var E2BSubprocessHandle = class {
 		throw settlement.error;
 	}
 	async rollbackPublishedFailure(error) {
-		if (this.remotePid <= 0 || this.quiescenceProven) return error;
+		if (this.remoteProcessGroupId === void 0 || this.quiescenceProven) return error;
 		this.terminate();
 		try {
 			await this.waitForExit();
@@ -809,13 +806,13 @@ var E2BSubprocessHandle = class {
 			this.markQuiescent();
 			return;
 		}
-		if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
+		if (!isValidProcessId(handle.pid) && this.remoteProcessGroupId === void 0) {
 			await handle.kill();
 			this.markQuiescent();
 			return;
 		}
 		const sandbox = await this.runtime.getSandbox();
-		const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid;
+		const processGroupId = this.remoteProcessGroupId ?? handle.pid;
 		await this.terminateGroup(sandbox, handle, processGroupId);
 	}
 	async terminateGroup(sandbox, handle, processGroupId) {
@@ -1322,6 +1319,12 @@ async function spawnE2BTerminal(runtime, spec, stateDir, pollMs) {
 function requireRepresentableGrace(graceMs) {
 	if (!Number.isFinite(graceMs) || graceMs <= 0 || graceMs > MAX_TIMER_DELAY_MS) throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
 }
+function validateNoNullByte(subject, value) {
+	if (!value.includes("\0")) return;
+	const error = /* @__PURE__ */ new TypeError(`${subject} must be a string without null bytes. Received ${inspect(value)}`);
+	Object.assign(error, { code: "ERR_INVALID_ARG_VALUE" });
+	throw error;
+}
 /** E2B command manager registered as `ctx.subprocess`. */
 var E2BSubprocessRuntime = class extends SubprocessRuntime {
 	static inject = ["e2b"];
@@ -1391,7 +1394,22 @@ var E2BSubprocessRuntime = class extends SubprocessRuntime {
 		const program = spec.argv[0];
 		if (program === void 0 || program.length === 0) throw new Error("invalid argv: expected a non-empty program name at argv[0]");
 		requireRepresentableGrace(spec.graceMs);
-		if (spec.signal?.aborted === true) throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`);
+		if (spec.signal?.aborted === true) {
+			let reason = "aborted";
+			try {
+				reason = String(spec.signal.reason ?? reason);
+			} catch {}
+			throw new Error(`aborted before spawn: ${reason}`);
+		}
+		spec.argv.forEach((value, index) => {
+			validateNoNullByte(index === 0 ? "The argument 'file'" : `The argument 'args[${String(index - 1)}]'`, value);
+		});
+		validateNoNullByte("The property 'options.cwd'", spec.cwd);
+		for (const [key, value] of Object.entries(spec.env ?? {})) {
+			if (value === void 0) continue;
+			validateNoNullByte(`The property 'options.env['${key}']'`, key);
+			validateNoNullByte(`The property 'options.env['${key}']'`, value);
+		}
 		const stateDir = posix.join(this.ctx.e2b.runtimeRoot, "processes", randomUUID());
 		const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir, this.pollMs);
 		this.live.add(handle);

package/lib/types/process.d.ts

@@ -2,7 +2,7 @@
 import { PassThrough, Writable } from 'node:stream';
 import type { SubprocessHandle, SubprocessOutcome, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
 import type E2BRuntime from '@deepseek-ai/dsh-e2b';
-/** E2B-backed subprocess handle with deferred remote PID acquisition. */
+/** E2B-backed subprocess handle with private remote process-group tracking. */
 export declare class E2BSubprocessHandle implements SubprocessHandle {
     private readonly runtime;
     private readonly spec;
@@ -24,7 +24,7 @@ export declare class E2BSubprocessHandle implements SubprocessHandle {
     private readonly stderrReader;
     private readonly paths;
     private controlEnvs;
-    private remotePid;
+    private remoteProcessGroupId;
     private outputTransportError;
     private outputDrainExpired;
     private stateDirectoryCreated;
@@ -40,8 +40,6 @@ export declare class E2BSubprocessHandle implements SubprocessHandle {
      * @param pollMs - Remote status/liveness poll cadence.
      */
     constructor(runtime: E2BRuntime, spec: SubprocessSpawnSpec, stateDir: string, pollMs: number);
-    /** Remote process id after start; `-1` while E2B startup is pending or after it fails. */
-    get pid(): number;
     /** @inheritdoc */
     terminate(): void;
     /** @inheritdoc */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subprocess-e2b",
   "description": "E2B subprocess implementation for DeepSeek Harness",
-  "version": "0.1.2-rc.1",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,18 +27,18 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-rc.1",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-e2b": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-e2b": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.3-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-e2b": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-e2b": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   }
 }