@deepseek-ai/dsh-sandbox 0.1.5-rc.1 → 0.1.6-alpha.1

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/sandbox/sandbox/README.md
-README.md: b80e923e3dc6d5fd95f79546cdfa39a9ef82055f
-README.zh.md: 9d80a3621be0533bf31294702da7f6b9c9292ae2
+README.md: 88e873428115eb7a3880253b668a4de5b42d6e6d
+README.zh.md: b0144d12395cf01667ef7c2045a1d5f722936a4d

package/README.md

@@ -81,9 +81,9 @@ This section explains the design decisions behind the contract and points at the
 
 ### Design philosophy
 
-- **Same-world by contract.** `ctx.sandbox` wraps argv under a host-path file policy; containers, microVMs, and remote execution replace the surrounding capability seam instead.
+- **One execution world.** The filesystem, subprocess and sandbox providers operate on the same filesystem and kernel. Remote compositions replace all three providers; confinement resolves asynchronously in that world.
 - **Policy rides the call.** `SandboxPolicy` is carried per call, never fixed on the provider: two consumers may confine under different policies at the same instant, and an escalated retry is a new call with a wider policy. Defaulting and resolution are explicit consumer steps.
-- **Fail closed.** `confine()` returns enforcing argv or throws `SandboxUnavailableError`; silent unconfined passthrough is forbidden, and functional probes arbitrate multi-runner chains.
+- **Fail closed.** `confine()` resolves to enforcing argv or rejects with `SandboxUnavailableError`; silent unconfined passthrough is forbidden, and functional probes arbitrate multi-runner chains.
 - **One vocabulary for denial and escalation.** The marker and hint texts and the strictly-wider ladder live here so the bash and fs families cannot drift apart.
 
 ### Source map
@@ -141,7 +141,7 @@ Conditional error text is visible for that call and retained in history until co
 
 #### KV Cache effect
 
-Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV Cache entries.
 
 ### Escalation request and outcome
 

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "进程沙箱服务约定：面向组合、使用或扩展同世界子进程隔离的用户与维护者。"
+description: "面向用户与维护者的进程沙箱服务约定，用于组合、使用或扩展与宿主共享文件系统和内核的子进程限制机制。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-使用 `dsh-sandbox`，可以让子进程及其派生的所有进程在逐调用文件访问策略下运行。命令可以禁止写入（`read-only`）、只写入工作区（`workspace-write`），或不受限制地运行（`danger-full-access`）。无法强制执行所请求的模式时，调用以 `SANDBOX_UNAVAILABLE` 失败，绝不会不受限制地运行。调用被拒绝后，模型可以请求一个严格更宽的模式，交由人类批准一次。这是同世界隔离：进程仍与宿主共享内核和文件系统；需要隔离整个环境时，请使用容器、microVM 或远程执行器。
+使用 `dsh-sandbox`，可以让子进程及其派生的所有进程在逐调用文件访问策略下运行。命令可以禁止写入（`read-only`）、只写入工作区（`workspace-write`），或不受限制地运行（`danger-full-access`）。无法强制执行所请求的模式时，调用以 `SANDBOX_UNAVAILABLE` 失败，绝不会不受限制地运行。调用被拒绝后，模型可以请求一个严格更宽的模式，交由人类批准一次。这种限制只适用于与宿主共享内核和文件系统的进程；需要隔离整个环境时，请使用容器、microVM 或远程执行器。
 
 ## 目录
 
@@ -29,11 +29,11 @@ kind: "package-reference"
 
 ### 何时选择
 
-当组合需要在宿主机上隔离子进程时选择本包：本地后端与受限执行器都实现这个约定，因此在 `ctx.sandbox` 后挂载 `sandbox-local`、在 `ctx.shell` 后挂载受限执行器，就能让每次 bash 或 pwsh 调用都有受限默认值。当进程必须在隔离环境中运行时请另选方案——容器、microVM 或远程执行器会替换整个 `ctx.shell`/`ctx.fs` 能力，而不是在这里添加后端。
+当组合需要在宿主机上隔离子进程时选择本包：本地后端与受限执行器都实现这个约定，因此在 `ctx.sandbox` 后挂载 `sandbox-local`、在 `ctx.shell` 后挂载受限执行器，就能使每次 bash 或 pwsh 调用默认在限制下运行。当进程必须在隔离环境中运行时请另选方案——容器、microVM 或远程执行器会替换整个 `ctx.shell`/`ctx.fs` 能力，而不是在这里添加后端。
 
 ### 隔离命令
 
-挂载服务、后端与受限执行器；[base bundle](../../bundle/base/cordis.patch.yml)拥有随附组合。
+挂载服务、后端与受限执行器；随附的组合由[基础组合包（base bundle）](../../bundle/base/cordis.patch.yml)定义。
 
 ```yaml
 - id: sandbox
@@ -81,9 +81,9 @@ kind: "package-reference"
 
 ### 设计理念
 
-- **按约定限同世界。** `ctx.sandbox` 在宿主路径文件策略下包装 argv；容器、microVM 与远程执行会替换周边能力 seam。
+- **同一执行环境。** 文件系统、子进程与沙箱提供方使用同一文件系统和内核。远端组合替换这三个提供方，并在该环境中异步解析限制。
 - **策略随调用传递。** `SandboxPolicy` 逐调用携带，绝不在提供方上固定：两个消费方可以同时按不同策略隔离，获批的升权重试只是用更宽策略发起的新调用。默认与解析是消费方显式步骤。
-- **故障关闭。** `confine()` 返回受强制的 argv，或抛出 `SandboxUnavailableError`；绝不允许静默无限制放行，功能探测用于仲裁多 runner 链。
+- **故障关闭。** `confine()` 异步返回用于强制执行限制的 argv，或以 `SandboxUnavailableError` 拒绝；绝不允许静默无限制放行，功能探测用于仲裁多 runner 链。
 - **统一的拒绝与升权词汇。** 标记与提示文本以及严格更宽阶梯都放在这里，使 bash 与 fs 家族不会漂移。
 
 ### 源码地图
@@ -93,7 +93,7 @@ kind: "package-reference"
 | [`src/index.ts`](src/index.ts) | 插件入口：`SandboxProvider` 服务、模式/强制执行/策略类型、故障关闭错误 |
 | [`src/escalation.ts`](src/escalation.ts) | 升权词汇：更宽模式阶梯、参数校验、拒绝与提示标记、审批编排 |
 | [`src/roots.ts`](src/roots.ts) | 可写根目录推导，Seatbelt profile 与进程内 fs 栅栏共享 |
-| — | 不发布运行时不变式伴生入口；抽象 seam 不注册事件或数据关系。 |
+| — | 不发布运行时不变式伴生入口；除所属 seam 强制执行的约定外，本包不公开独立的事件序列或可变数据关系。 |
 
 ### 升权编排
 
@@ -165,7 +165,7 @@ sandbox mode "<mode>" is requested but no sandbox backend is usable on this host
 这些限制说明该 seam 何时不合适，或何时需要特别运维。它们是当前包约束，不是通用沙箱对比或任务积压。
 
 - **文件操作是完整的策略词汇**——该 seam 不表达网络、进程、系统调用、设备或凭据限制。
-- **仅限同世界隔离**——容器、microVM 与远程执行需要替换能力实现，而不是在此添加提供方。
+- **只支持与宿主共享文件系统和内核的限制**——容器、microVM 与远程执行需要替换能力实现，而不是在此添加提供方。
 - **拒绝报告是一种 stderr 方言**——该 seam 返回后端签名，而非类型化运行时拒绝通道，需要分类的消费方必须从子进程输出推断。
 - **Runner 诊断使用带内通道**——退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此故意模仿 runner 的受限子进程可能造成错误的可用性或诊断归因；这无法绕过隔离，带外 runner 状态通道暂缓实现。
 - **每个上下文只有一个提供方**——同时组合不同沙箱机制需要提供方级阶梯或独立 Cordis 上下文；调用方逐调用选择策略，而非后端标识。

package/lib/index.js

@@ -1,7 +1,7 @@
 import { Service } from "@deepseek-ai/cordis";
 import { HarnessError } from "@deepseek-ai/dsh-llm";
 import { assertNever } from "@deepseek-ai/dsh-util-values";
-import { realpathSync } from "node:fs";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 //#region lib/types/escalation.js
 /**
@@ -161,6 +161,82 @@ function writableRoots(policy) {
 	].map(canonicalPath))];
 }
 //#endregion
+//#region lib/types/diagnostics.js
+/** Classify observed sandbox runner failures and file-effect denials. */
+/** Node-local spawn codes proven to identify executable resolution or permission failure. */
+const EXECUTABLE_SPAWN_CODES = new Set(["EACCES", "ENOENT"]);
+/** Whether the caller-owned spawn cwd can be entered. */
+function isUsableWorkdir(path) {
+	try {
+		if (!statSync(path).isDirectory()) return false;
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Attribute only Node ENOENT/EACCES failures whose error path equals argv[0]
+* after independently ruling out the caller-owned cwd. A supplied error path
+* must exactly identify the runner; without one, the syscall must. With a
+* usable cwd, these codes describe resolution or execute permission for that
+* argv[0] or its shebang interpreter.
+* The workdir is checked at classification time, not atomically with spawn;
+* concurrent path replacement may change attribution but cannot permit an
+* unconfined execution.
+* @param error - the original spawn rejection.
+* @param runnerProgram - provider argv[0], the executable that establishes confinement.
+* @param workdir - the caller-owned spawn cwd, checked independently for usability.
+* @returns whether the rejection has executable-specific runner evidence.
+*/
+function isRunnerSpawnFailure(error, runnerProgram, workdir) {
+	if (runnerProgram === void 0 || !isUsableWorkdir(workdir)) return false;
+	if (typeof error !== "object" || error === null) return false;
+	const { code, path, syscall } = error;
+	if (typeof code !== "string" || !EXECUTABLE_SPAWN_CODES.has(code)) return false;
+	if (typeof syscall !== "string") return false;
+	const exactSyscall = `spawn ${runnerProgram}`;
+	if (path === void 0) return syscall === exactSyscall;
+	if (typeof path !== "string" || path.length === 0 || path !== runnerProgram) return false;
+	return syscall === "spawn" || syscall === exactSyscall;
+}
+/**
+* Classify one settled process against the selected backend's structured
+* runner-failure rules. Each rule requires a nonzero exit, its optional
+* exit-code gate, and a fatal signature on one stderr line after exact
+* informational lines are excluded.
+* @param exitCode - process exit code; null means signal termination.
+* @param stderr - collected stderr text, left unchanged.
+* @param rules - structured runner-failure rules from the active wrap.
+* @returns the first matching fatal line, or undefined when evidence is insufficient.
+*/
+function classifyRunnerFailure(exitCode, stderr, rules) {
+	if (exitCode === null || exitCode === 0) return void 0;
+	const lines = stderr.split(/\r?\n/);
+	for (const rule of rules) {
+		if (rule.allowedExitCodes !== void 0 && !rule.allowedExitCodes.includes(exitCode)) continue;
+		const informationalLines = new Set((rule.informationalLines ?? []).map((line) => line.toLowerCase()));
+		const fatalSignatures = rule.fatalSignatures.filter((signature) => signature.trim().length > 0).map((signature) => signature.toLowerCase());
+		for (const line of lines) {
+			const lowered = line.toLowerCase();
+			if (informationalLines.has(lowered)) continue;
+			if (fatalSignatures.some((signature) => lowered.includes(signature))) return { detail: line };
+		}
+	}
+}
+/**
+* Match a non-zero exit against case-insensitive stderr signatures.
+* @param exitCode - process exit code; null means signal termination.
+* @param stderr - collected stderr text.
+* @param signatures - substrings identifying the selected backend's dialect.
+* @returns whether this is a non-zero exit whose stderr matches a signature.
+*/
+function matchesSignature(exitCode, stderr, signatures) {
+	if (exitCode === null || exitCode === 0) return false;
+	const lowered = stderr.toLowerCase();
+	return signatures.some((signature) => lowered.includes(signature.toLowerCase()));
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Service Definition for the same-world process-confinement capability seam: wrap exact subprocess argv under a
@@ -199,4 +275,4 @@ var SandboxProvider = class extends Service {
 	}
 };
 //#endregion
-export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs, writableRoots };
+export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, classifyRunnerFailure, escalationHintMarker, isRunnerSpawnFailure, matchesSignature, sandboxDenialMarker, validateEscalationArgs, writableRoots };

package/lib/types/diagnostics.d.ts

@@ -0,0 +1,42 @@
+import type { RunnerFailureRule } from './index.ts';
+/**
+ * Attribute only Node ENOENT/EACCES failures whose error path equals argv[0]
+ * after independently ruling out the caller-owned cwd. A supplied error path
+ * must exactly identify the runner; without one, the syscall must. With a
+ * usable cwd, these codes describe resolution or execute permission for that
+ * argv[0] or its shebang interpreter.
+ * The workdir is checked at classification time, not atomically with spawn;
+ * concurrent path replacement may change attribution but cannot permit an
+ * unconfined execution.
+ * @param error - the original spawn rejection.
+ * @param runnerProgram - provider argv[0], the executable that establishes confinement.
+ * @param workdir - the caller-owned spawn cwd, checked independently for usability.
+ * @returns whether the rejection has executable-specific runner evidence.
+ */
+export declare function isRunnerSpawnFailure(error: unknown, runnerProgram: string | undefined, workdir: string): boolean;
+/** Fatal runner evidence retained for infrastructure-error detail. */
+interface RunnerFailureMatch {
+    /** The original stderr line that matched a fatal signature. */
+    detail: string;
+}
+/**
+ * Classify one settled process against the selected backend's structured
+ * runner-failure rules. Each rule requires a nonzero exit, its optional
+ * exit-code gate, and a fatal signature on one stderr line after exact
+ * informational lines are excluded.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text, left unchanged.
+ * @param rules - structured runner-failure rules from the active wrap.
+ * @returns the first matching fatal line, or undefined when evidence is insufficient.
+ */
+export declare function classifyRunnerFailure(exitCode: number | null, stderr: string, rules: readonly RunnerFailureRule[]): RunnerFailureMatch | undefined;
+/**
+ * Match a non-zero exit against case-insensitive stderr signatures.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text.
+ * @param signatures - substrings identifying the selected backend's dialect.
+ * @returns whether this is a non-zero exit whose stderr matches a signature.
+ */
+export declare function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/types/index.d.ts

@@ -134,10 +134,12 @@ export declare abstract class SandboxProvider extends Service {
      *   `['bash', '-c', command]`.
      * @param policy - the file-effect policy this execution runs under,
      *   carried per call (see {@link SandboxPolicy}).
+     * @param signal - cancellation while the provider resolves the policy and runner.
      * @returns the argv to spawn instead, plus the enforcement completeness
      *   the selected backend achieves for it.
      */
-    abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv;
+    abstract confine(argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): Promise<ConfinedArgv>;
 }
 export default SandboxProvider;
+export { classifyRunnerFailure, isRunnerSpawnFailure, matchesSignature } from './diagnostics.ts';
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sandbox",
   "description": "Abstract process-sandbox seam (ctx.sandbox) for the DeepSeek Harness: same-world confinement vocabulary and the SandboxProvider contract",
-  "version": "0.1.5-rc.1",
+  "version": "0.1.6-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,16 +27,16 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-util-values": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-util-values": "^0.1.6-alpha.1"
   }
 }