@songtonyli/dsh-cli 0.1.96 → 0.1.97

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/README.md +1 -1
  2. package/bin/dsh.mjs +1 -1
  3. package/node_modules/@deepseek-ai/dsh-client-modules/lib/index.js +1 -1
  4. package/node_modules/@deepseek-ai/dsh-client-ui-sidebar/lib/client.js +1 -1
  5. package/node_modules/@deepseek-ai/dsh-ptc-runtime-node/README.i18n.yaml +2 -2
  6. package/node_modules/@deepseek-ai/dsh-ptc-runtime-node/README.md +1 -1
  7. package/node_modules/@deepseek-ai/dsh-ptc-runtime-node/README.zh.md +1 -1
  8. package/node_modules/@deepseek-ai/dsh-ptc-runtime-node/lib/index.js +41 -16
  9. package/node_modules/@deepseek-ai/dsh-sandbox/README.i18n.yaml +5 -2
  10. package/node_modules/@deepseek-ai/dsh-sandbox/README.md +4 -0
  11. package/node_modules/@deepseek-ai/dsh-sandbox/README.zh.md +4 -0
  12. package/node_modules/@deepseek-ai/dsh-sandbox/lib/index.js +23 -3
  13. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.i18n.yaml +17 -14
  14. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.md +12 -6
  15. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.zh.md +12 -6
  16. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/lib/exec-shim.js +3 -1
  17. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/lib/index.js +54 -9
  18. package/node_modules/@deepseek-ai/dsh-sandbox-local/README.i18n.yaml +2 -2
  19. package/node_modules/@deepseek-ai/dsh-sandbox-local/README.md +2 -0
  20. package/node_modules/@deepseek-ai/dsh-sandbox-local/README.zh.md +2 -0
  21. package/node_modules/@deepseek-ai/dsh-sandbox-local/lib/index.js +74 -18
  22. package/node_modules/@deepseek-ai/dsh-tool-cordis/lib/types/api-catalog.js +11 -1
  23. package/node_modules/@deepseek-ai/dsh-tui-app/README.i18n.yaml +2 -2
  24. package/node_modules/@deepseek-ai/dsh-tui-app/README.md +3 -1
  25. package/node_modules/@deepseek-ai/dsh-tui-app/README.zh.md +3 -1
  26. package/node_modules/@deepseek-ai/dsh-tui-app/lib/index.js +20 -5
  27. package/package.json +1 -1
package/README.md CHANGED
@@ -26,7 +26,7 @@ workspace and no build step. Native packages that ship one build per platform
26
26
  ripgrep, the PTY backend's addons, sharp, koffi, and the Landlock launcher — are
27
27
  ordinary optional dependencies, so npm resolves the right one for your machine.
28
28
 
29
- Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.96; `dsh --version`
29
+ Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.97; `dsh --version`
30
30
  also reports the harness build the package was assembled from.
31
31
 
32
32
  ## License
package/bin/dsh.mjs CHANGED
@@ -18,7 +18,7 @@ const argv = process.argv.slice(2)
18
18
  // version this package publishes. Reporting only one of the two would make an
19
19
  // ordinary `npm install @songtonyli/dsh-cli@x` look like it installed something else.
20
20
  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-V')) {
21
- console.log('@songtonyli/dsh-cli 0.1.96 (deepseek-harness 0.2.2-rc.1)')
21
+ console.log('@songtonyli/dsh-cli 0.1.97 (deepseek-harness 0.2.2-rc.1)')
22
22
  process.exit(0)
23
23
  }
24
24
 
@@ -594,7 +594,7 @@ var ClientModuleRegistry = class extends Service {
594
594
  constructor(ctx) {
595
595
  super(ctx, "clientModules");
596
596
  const { version } = createRequire(import.meta.url)("../package.json");
597
- const commit = "e253cdf";
597
+ const commit = "c66208c";
598
598
  this.release = {
599
599
  version,
600
600
  commit
@@ -279,7 +279,7 @@ window.__ModuleLoader__.load({
279
279
  const SCROLLBAR_LINGER_MS = 2e3;
280
280
  /** Format complete-build metadata for the local brand badge. */
281
281
  function localBuildVersion() {
282
- return `0.2.2-rc.1-e253cdf-dirty`;
282
+ return `0.2.2-rc.1-c66208c` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
283
283
  }
284
284
  /** Analytics category of an official panel; other panels are never reported. */
285
285
  function officialEntry(id) {
@@ -36,8 +36,8 @@
36
36
  en: 50e6cd38e298da31
37
37
  zh: c8b252b3acf59147
38
38
  /deepseek-ai-dsh-ptc-runtime-node/understand-the-implementation/launch-and-control:
39
- en: f27d477e3ccb10de
40
- zh: 0f14a4899bae6c39
39
+ en: a23d94dbbd71b054
40
+ zh: 4d2526e7d262402e
41
41
  /deepseek-ai-dsh-ptc-runtime-node/understand-the-implementation/source-and-built-bootstraps:
42
42
  en: 93c117a1e404ddca
43
43
  zh: 6902de0d96efb03b
@@ -125,7 +125,7 @@ The host owns policy, deadlines, binding lookup and process cleanup. The child o
125
125
 
126
126
  ### Launch and control
127
127
 
128
- The host strips erasable types and, when starting a process, resolves the executable and bootstrap in the configured execution world, awaits argv confinement through `ctx.sandbox`, then spawns through `ctx.subprocess`. Cancellation is checked again after confinement, so a provider returning after cancellation cannot start the program. After adopting the inherited control channel, the child retains only executable-search, Windows system, and temporary paths in its OS environment and replaces the program-visible `process.env` with an empty dictionary. Named `node:process` exports are refreshed so imports also receive the empty environment. Windows ACL setup receives the parent's distinct `TEMP` and `TMP` values for shared grant locks, then replaces both with its private directory before starting the program. These native paths keep nested process creation and native temporary-file APIs functional. The host preserves `ELECTRON_RUN_AS_NODE` only for child startup so the Desktop executable runs the Node bootstrap; the bootstrap removes the selector before evaluating model code. The heap limit uses Node argv or a provider-created `NODE_OPTIONS` value for packaged executables; ambient loader and inspector flags are discarded.
128
+ The host strips erasable types and, when starting a process, resolves the executable and bootstrap in the configured execution world, awaits argv confinement through `ctx.sandbox.confineHostBound`, then spawns through `ctx.subprocess`. The process is host-bound: it runs that world's executable and bootstrap and inherits the control descriptor, so it names the executable and the bootstrap's script directory, or the source checkout, as runtime paths a read-restricting provider keeps readable. Cancellation is checked again after confinement, so a provider returning after cancellation cannot start the program. After adopting the inherited control channel, the child retains only executable-search, Windows system, and temporary paths in its OS environment and replaces the program-visible `process.env` with an empty dictionary. Named `node:process` exports are refreshed so imports also receive the empty environment. Windows ACL setup receives the parent's distinct `TEMP` and `TMP` values for shared grant locks, then replaces both with its private directory before starting the program. These native paths keep nested process creation and native temporary-file APIs functional. The host preserves `ELECTRON_RUN_AS_NODE` only for child startup so the Desktop executable runs the Node bootstrap; the bootstrap removes the selector before evaluating model code. The heap limit uses Node argv or a provider-created `NODE_OPTIONS` value for packaged executables; ambient loader and inspector flags are discarded.
129
129
 
130
130
  Control traffic uses newline-delimited JSON on an inherited pipe separate from stdout/stderr. The RPC adapter bounds each message and queued native writes, rejects pending transport calls on closure, and runs no further methods after closure. Unsupported methods receive error replies. The host validates binding names and lossless JSON before dispatch.
131
131
 
@@ -125,7 +125,7 @@ Host 负责策略、截止时间、绑定查找和进程清理。子进程负责
125
125
 
126
126
  ### 启动与控制
127
127
 
128
- Host 擦除可擦除类型;需要启动进程时,在配置的执行世界中解析可执行文件与 bootstrap,通过 `ctx.sandbox` 等待 argv 限制准备完成,再通过 `ctx.subprocess` 启动。限制准备完成后会再次检查取消状态,因此提供方在取消后返回也无法启动程序。接管继承的控制通道后,子进程在 OS 环境中只保留可执行文件搜索路径、Windows 系统路径和临时路径,并将程序可见的 `process.env` 替换为空字典。`node:process` 的具名导出同步更新,因此导入也会获得空环境。Windows ACL 初始化接收父进程各自的 `TEMP` 和 `TMP` 值以使用共享授权锁,然后在启动程序前将二者替换为私有目录。这些原生路径使嵌套进程创建和原生临时文件 API 仍可正常工作。Host 仅在子进程启动时保留 `ELECTRON_RUN_AS_NODE`,使桌面端可执行文件运行 Node bootstrap;bootstrap 在求值模型代码前删除该选择变量。堆上限通过 Node argv 或为打包可执行文件由提供方构造的 `NODE_OPTIONS` 值传递;环境中的加载器和调试器标志会被丢弃。
128
+ Host 擦除可擦除类型;需要启动进程时,在配置的执行世界中解析可执行文件与 bootstrap,通过 `ctx.sandbox.confineHostBound` 等待 argv 限制准备完成,再通过 `ctx.subprocess` 启动。该进程是宿主机绑定执行:它运行该世界中的可执行文件与 bootstrap,并继承控制描述符,因此会把可执行文件以及 bootstrap 的脚本目录(或源码检出目录)声明为运行时路径,由限制读取的提供方保持可读。限制准备完成后会再次检查取消状态,因此提供方在取消后返回也无法启动程序。接管继承的控制通道后,子进程在 OS 环境中只保留可执行文件搜索路径、Windows 系统路径和临时路径,并将程序可见的 `process.env` 替换为空字典。`node:process` 的具名导出同步更新,因此导入也会获得空环境。Windows ACL 初始化接收父进程各自的 `TEMP` 和 `TMP` 值以使用共享授权锁,然后在启动程序前将二者替换为私有目录。这些原生路径使嵌套进程创建和原生临时文件 API 仍可正常工作。Host 仅在子进程启动时保留 `ELECTRON_RUN_AS_NODE`,使桌面端可执行文件运行 Node bootstrap;bootstrap 在求值模型代码前删除该选择变量。堆上限通过 Node argv 或为打包可执行文件由提供方构造的 `NODE_OPTIONS` 值传递;环境中的加载器和调试器标志会被丢弃。
129
129
 
130
130
  控制通信使用继承管道上的逐行 JSON,与 stdout/stderr 分离。RPC 适配层限制每条消息和原生写入队列的大小,在通道关闭时拒绝待完成的传输调用,关闭后不再执行方法。不支持的方法会收到错误回复。Host 在分派前校验绑定名称和无损 JSON。
131
131
 
@@ -31,34 +31,57 @@ function resolveLaunch(config) {
31
31
  * @param config - resolved worker invocation.
32
32
  * @param maxMessageBytes - Validated frame and queued-write limit.
33
33
  * @param persistent - Whether the selected mode requires retained-process launch support.
34
- * @returns Arguments following the resolved Node executable.
34
+ * @returns Arguments following the resolved Node executable, and the paths they make the worker read.
35
35
  */
36
- function bootstrapArgs(fs, config, maxMessageBytes, persistent = false) {
36
+ function workerBootstrap(fs, config, maxMessageBytes, persistent = false) {
37
37
  switch (config.kind) {
38
38
  case "embedded":
39
39
  if (persistent) throw new Error("Persistent PTC requires a node-script launch");
40
- return [String(maxMessageBytes)];
41
- case "node-script": return ["--experimental-vm-modules", ...scriptBootstrapArgs(fs, config.bootstrapPath, maxMessageBytes)];
40
+ return {
41
+ args: [String(maxMessageBytes)],
42
+ readPaths: []
43
+ };
44
+ case "node-script": {
45
+ const script = scriptBootstrap(fs, config.bootstrapPath, maxMessageBytes);
46
+ return {
47
+ args: ["--experimental-vm-modules", ...script.args],
48
+ readPaths: script.readPaths
49
+ };
50
+ }
42
51
  /* v8 ignore next -- Callers supply the resolved, closed LaunchConfig union. */
43
52
  default: return assertNever(config);
44
53
  }
45
54
  }
46
- function scriptBootstrapArgs(fs, bootstrapPath, maxMessageBytes) {
47
- if (bootstrapPath !== void 0) return [bootstrapPath, String(maxMessageBytes)];
55
+ function scriptBootstrap(fs, bootstrapPath, maxMessageBytes) {
56
+ if (bootstrapPath !== void 0) return {
57
+ args: [bootstrapPath, String(maxMessageBytes)],
58
+ readPaths: [dirname(bootstrapPath)]
59
+ };
48
60
  const mapped = (path) => {
49
61
  const result = fs.processPathFromHostPath(path);
50
62
  if (result === void 0) throw new Error(`PTC runtime bootstrap is unavailable in the subprocess execution world: ${path}`);
51
63
  return result;
52
64
  };
53
- /* v8 ignore next 3 -- built-lib.e2e.ts executes the bundled provider and sibling process.js under plain Node. */
54
- if (!new URL(import.meta.url).pathname.endsWith(".ts")) return [mapped(fileURLToPath(new URL("./process.js", import.meta.url))), String(maxMessageBytes)];
65
+ /* v8 ignore next 4 -- built-lib.e2e.ts executes the bundled provider and sibling process.js under plain Node. */
66
+ if (!new URL(import.meta.url).pathname.endsWith(".ts")) {
67
+ const script = mapped(fileURLToPath(new URL("./process.js", import.meta.url)));
68
+ return {
69
+ args: [script, String(maxMessageBytes)],
70
+ readPaths: [dirname(script)]
71
+ };
72
+ }
55
73
  const entry = mapped(fileURLToPath(new URL("./process.ts", import.meta.url)));
56
74
  const helper = mapped(resolve(dirname(fileURLToPath(import.meta.resolve("@deepseek-ai/dsh-subprocess/package.json"))), "src/control.ts"));
57
- return [
58
- "--input-type=module",
59
- "--eval",
60
- `const {openInheritedControlChannel}=await import(${JSON.stringify(pathToFileURL(helper).href)});const {runNodeMain}=await import(${JSON.stringify(pathToFileURL(entry).href)});await runNodeMain(openInheritedControlChannel(),${maxMessageBytes},process);`
61
- ];
75
+ const source = `const {openInheritedControlChannel}=await import(${JSON.stringify(pathToFileURL(helper).href)});const {runNodeMain}=await import(${JSON.stringify(pathToFileURL(entry).href)});await runNodeMain(openInheritedControlChannel(),${maxMessageBytes},process);`;
76
+ const checkout = mapped(resolve(fileURLToPath(new URL("../../../../", import.meta.url))));
77
+ return {
78
+ args: [
79
+ "--input-type=module",
80
+ "--eval",
81
+ source
82
+ ],
83
+ readPaths: [checkout]
84
+ };
62
85
  }
63
86
  //#endregion
64
87
  //#region lib/types/config.js
@@ -1140,16 +1163,18 @@ var ProgramWorker = class {
1140
1163
  if (this.closed) return;
1141
1164
  const packaged = this.config.launch.kind === "embedded";
1142
1165
  const heapFlag = `--max-old-space-size=${this.config.maxOldGenerationSizeMb}`;
1166
+ const bootstrap = workerBootstrap(this.ctx.fs, this.config.launch, this.config.maxMessageBytes, this.retainsState);
1143
1167
  const argv = [
1144
1168
  executable,
1145
1169
  ...packaged ? [] : [heapFlag],
1146
- ...bootstrapArgs(this.ctx.fs, this.config.launch, this.config.maxMessageBytes, this.retainsState)
1170
+ ...bootstrap.args
1147
1171
  ];
1148
1172
  const policy = this.policy;
1149
- this.confined = policy.mode === "danger-full-access" ? void 0 : await this.ctx.sandbox.confine(argv, {
1173
+ const runtimePaths = [executable, ...bootstrap.readPaths];
1174
+ this.confined = policy.mode === "danger-full-access" ? void 0 : await this.ctx.sandbox.confineHostBound(argv, {
1150
1175
  ...policy,
1151
1176
  mode: policy.mode
1152
- }, this.controller.signal);
1177
+ }, { runtimePaths }, this.controller.signal);
1153
1178
  if (this.closed) return;
1154
1179
  const env = Object.fromEntries(Object.keys(process.env).filter((key) => !STARTUP_ENVIRONMENT_NAMES.has(key.toUpperCase()) && key.toUpperCase() !== "ELECTRON_RUN_AS_NODE").map((key) => [key, void 0]));
1155
1180
  if (packaged) {
@@ -30,8 +30,11 @@
30
30
  en: d036634ef210c950
31
31
  zh: baa168c74a478106
32
32
  /deepseek-ai-dsh-sandbox/use-this-package/fail-closed-behavior:
33
- en: 6bf240632a7a6bf5
34
- zh: ebf414f5cf435875
33
+ en: 534ed17f3900402b
34
+ zh: b2523ee2e2e678e6
35
+ /deepseek-ai-dsh-sandbox/use-this-package/host-bound-executions:
36
+ en: 24b989d549f611eb
37
+ zh: 8b5de3a94fc83e8b
35
38
  /deepseek-ai-dsh-sandbox/understand-the-implementation:
36
39
  en: 7e13d669ecc96d59
37
40
  zh: b5fe7ae65812d926
@@ -69,6 +69,10 @@ When a confined call is denied, the operation reports a denial marker naming the
69
69
 
70
70
  When no backend can enforce the requested mode, the call fails with `SANDBOX_UNAVAILABLE` rather than running unconfined; the error text names the missing platform runner. A backend that fails after starting also reports a structured runner-failure signature, so a broken sandbox is distinguishable from a command failure.
71
71
 
72
+ ### Host-bound executions
73
+
74
+ A consumer whose process must stay in the subprocess provider's execution world calls `confineHostBound(argv, policy, { runtimePaths })` instead of `confine`. Such a process starts an executable or files of that world outside the shared workspace, or inherits descriptors beyond stdin, stdout, and stderr; the Node code-execution worker that runs workflows is one. `runtimePaths` names the files and directories it reads to start. A provider that confines on the host returns the same wrap as `confine`. A provider whose `confine` relocates execution, such as the [Apple container backend](../sandbox-apple-container/README.md), confines the process in place under a read restriction it documents and keeps `runtimePaths` readable, or fails closed.
75
+
72
76
  -----
73
77
 
74
78
  <a id="understand-the-implementation"></a>
@@ -69,6 +69,10 @@ kind: "package-reference"
69
69
 
70
70
  没有后端能强制执行所请求的模式时,调用以 `SANDBOX_UNAVAILABLE` 失败,而不是不受限制地运行;错误文本会指明缺失的平台 runner。启动后失败的后端还会报告结构化的 runner 失败签名,因此损坏的沙箱可以与命令失败区分开。
71
71
 
72
+ ### 宿主机绑定执行
73
+
74
+ 进程必须留在子进程提供方自身执行世界中的消费方,调用 `confineHostBound(argv, policy, { runtimePaths })` 而不是 `confine`。这类宿主机绑定执行(host-bound execution)会启动该世界中位于共享工作区之外的可执行文件或文件,或者继承 stdin、stdout、stderr 之外的描述符;运行工作流的 Node 代码执行 worker 就是其中之一。`runtimePaths` 列出它启动时读取的文件和目录。在宿主机上隔离的提供方返回与 `confine` 相同的包装结果。`confine` 会把执行迁移到别处的提供方,例如 [Apple container 后端](../sandbox-apple-container/README.zh.md),会在原处用自身记载的读取限制隔离该进程,并保持 `runtimePaths` 可读;做不到时故障关闭。
75
+
72
76
  -----
73
77
 
74
78
  <a id="understand-the-implementation"></a>
@@ -382,8 +382,9 @@ function matchesSignature(exitCode, stderr, signatures) {
382
382
  * subprocess argv under a host-path file policy, and report the host read
383
383
  * scope that model-facing file tools must share. Providers either confine on
384
384
  * the host kernel or, like the Apple container backend, run the argv in a VM
385
- * that mounts the workspace at its host path; remote execution replaces the
386
- * surrounding capability seam instead.
385
+ * that mounts the workspace at its host path; a host-bound execution that
386
+ * cannot move into such a VM confines in place instead. Remote execution
387
+ * replaces the surrounding capability seam.
387
388
  * @module @deepseek-ai/dsh-sandbox
388
389
  */
389
390
  /**
@@ -423,7 +424,26 @@ var SandboxProvider = class extends Service {
423
424
  super(ctx, "sandbox");
424
425
  }
425
426
  /**
426
- * What a process confined under `policy` can read on the host, or
427
+ * Wrap `argv` for a host-bound execution: one that must run in the
428
+ * subprocess provider's own execution world because its executable or
429
+ * runtime files are paths there outside the shared workspace, or because it
430
+ * inherits descriptors beyond stdin, stdout, and stderr. The base
431
+ * implementation is {@link confine}, which already confines in that world.
432
+ * A provider whose `confine` relocates execution, such as the Apple
433
+ * container backend, overrides this to confine in place under a read
434
+ * restriction it documents, or fails closed.
435
+ * @param argv - the exact argv the caller is about to spawn.
436
+ * @param policy - the file-effect policy this execution runs under.
437
+ * @param _execution - the runtime paths the process must read.
438
+ * @param signal - cancellation while the provider resolves the policy and runner.
439
+ * @returns the argv to spawn instead, plus the enforcement completeness
440
+ * the selected backend achieves for it.
441
+ */
442
+ confineHostBound(argv, policy, _execution, signal) {
443
+ return this.confine(argv, policy, signal);
444
+ }
445
+ /**
446
+ * What a process wrapped by {@link confine} under `policy` can read on the host, or
427
447
  * `undefined` when this backend does not confine reads. Model-facing tools
428
448
  * that read the host for the same session must refuse paths outside the
429
449
  * scope, so their view never exceeds the confined processes'. The base
@@ -9,8 +9,8 @@
9
9
  en: fd474288bb2dac31
10
10
  zh: e0e109692d3df1c4
11
11
  /deepseek-ai-dsh-sandbox-apple-container/summary:
12
- en: 20f21185b9538294
13
- zh: f421f10616852e8f
12
+ en: 2b49aa0572118385
13
+ zh: 6df5e09fa75518bc
14
14
  /deepseek-ai-dsh-sandbox-apple-container/table-of-contents:
15
15
  en: d152484eb41ac6b4
16
16
  zh: 09388d293f9be9cb
@@ -21,26 +21,29 @@
21
21
  en: d49845cf75f81420
22
22
  zh: 331b90bec2afb896
23
23
  /deepseek-ai-dsh-sandbox-apple-container/use-this-package/minimal-configuration:
24
- en: 1a7a36bfc29d9f18
25
- zh: 1769b4d7bfae4f95
24
+ en: 947e75a2de3eea1c
25
+ zh: 82e7531b03d027eb
26
26
  /deepseek-ai-dsh-sandbox-apple-container/use-this-package/switching-a-session:
27
27
  en: fe0f7d5ac6160763
28
28
  zh: 4e1455a8559d46ca
29
29
  /deepseek-ai-dsh-sandbox-apple-container/use-this-package/what-confinement-covers:
30
30
  en: 36ce4366173e0544
31
31
  zh: 4f7537ee5c9c78c0
32
+ /deepseek-ai-dsh-sandbox-apple-container/use-this-package/host-bound-processes:
33
+ en: b19111c9ae73776f
34
+ zh: 3e411f7aac3314e3
32
35
  /deepseek-ai-dsh-sandbox-apple-container/use-this-package/failures-and-recovery:
33
- en: 79782500f91b1f06
34
- zh: a132d680acb85edc
36
+ en: 37392f91404d44ac
37
+ zh: 3cc24a6c811c7361
35
38
  /deepseek-ai-dsh-sandbox-apple-container/understand-the-implementation:
36
39
  en: 42b15ac6321706aa
37
40
  zh: c8011788e17a2cd6
38
41
  /deepseek-ai-dsh-sandbox-apple-container/understand-the-implementation/containers:
39
- en: 9d22cd4f279e3c98
40
- zh: b401fea7af29a453
42
+ en: 41ec5e057f28e234
43
+ zh: 73b6531f4730b74e
41
44
  /deepseek-ai-dsh-sandbox-apple-container/understand-the-implementation/execution-shim:
42
- en: 98ef17c4b9975fa3
43
- zh: 223994718947d592
45
+ en: 87bae2dfa3bdf8bb
46
+ zh: 51c2912c28fbe319
44
47
  /deepseek-ai-dsh-sandbox-apple-container/understand-the-implementation/source-map:
45
48
  en: 866bf8dec1ab38ba
46
49
  zh: af875a19b5ceb7b9
@@ -66,8 +69,8 @@
66
69
  en: 3ab9e835ea38981a
67
70
  zh: 4839ebd84726eca0
68
71
  /deepseek-ai-dsh-sandbox-apple-container/known-limitations-and-deferred-work:
69
- en: 774a7b78c802da01
70
- zh: 920961d8b70297ba
72
+ en: cdab1654fd6954d9
73
+ zh: c95356a7f1e64dfd
71
74
  /deepseek-ai-dsh-sandbox-apple-container/known-limitations-and-deferred-work/dev-note:
72
- en: d96c06feb419a24e
73
- zh: d8c3b5781c9c1690
75
+ en: 0e092923f2ad3d54
76
+ zh: b52b737777585237
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
9
9
 
10
10
  ## Summary
11
11
 
12
- Use this package to confine bash, terminal, and PTC commands in an [Apple `container`](https://github.com/apple/container) Linux VM on macOS with Apple silicon and CLI 1.5.0 or newer. The VM mounts only the session workspace, limits model file tools to the same read scope, masks `.env` files, excludes credential-shaped environment variables, and makes `.git` read-only. Other hosts and sessions switched with `/sandbox local` use the inherited local sandbox chain.
12
+ Use this package to confine bash and terminal commands in an [Apple `container`](https://github.com/apple/container) Linux VM on macOS with Apple silicon and CLI 1.5.0 or newer. The VM mounts only the session workspace, limits model file tools to the same read scope, masks `.env` files, excludes credential-shaped environment variables, and makes `.git` read-only. Host-bound processes, such as the Node code-execution worker that runs workflows, stay on the host under Seatbelt with a matching read fence. Other hosts and sessions switched with `/sandbox local` use the inherited local sandbox chain.
13
13
 
14
14
  ## Table of Contents
15
15
 
@@ -55,6 +55,7 @@ Choose it when confined commands should not see the user's home directory, keys,
55
55
  | `protectedPaths` | `['.git']` | Workspace-relative directories mounted read-only under `workspace-write` |
56
56
  | `hiddenFiles` | `.env`, `.env.*`, `.envrc`, private-key and certificate names, `.npmrc`, `.pypirc`, `.netrc`, `.git-credentials` | File-name globs masked in the guest and refused by file tools |
57
57
  | `hiddenFilesMaxDepth`, `hiddenFilesSkipDirs` | `8`, `['node_modules', '.git']` | Bounds of the workspace scan that finds files to mask when a container starts |
58
+ | `hostBoundUnreadableRoots` | `['/Users', '/Volumes']` | Absolute host directories whose file contents host-bound processes of container sessions cannot read, apart from the read scope, the writable roots, and the process's runtime files |
58
59
 
59
60
  The fields of `@deepseek-ai/dsh-sandbox-local` also apply to the `local` backend. The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-sandbox-apple-container) is the exhaustive source for every field and its JSDoc.
60
61
 
@@ -75,9 +76,13 @@ The fields of `@deepseek-ai/dsh-sandbox-local` also apply to the `local` backend
75
76
 
76
77
  `danger-full-access` bypasses `confine`, so it runs on the host under either backend. The approval prompt for an escalation to `danger-full-access` from a container session adds that the command runs directly on the Mac, outside the container. The Auto permission does not write it while a session runs on this backend: it writes `workspace-write`, and the reviewer, not a prompt, approves a one-shot escalation that leaves the container ([Auto review](../../experimental/auto-review/README.md)). On the `local` backend Auto still writes `danger-full-access`.
77
78
 
79
+ ### Host-bound processes
80
+
81
+ The Node code-execution worker that runs workflows starts the host Node executable and its bootstrap, and it talks to the host over an inherited control descriptor, so it cannot run in the guest. Its `confineHostBound` call confines it on the host with the inherited Seatbelt chain under the session's write rules plus a read fence. File contents under `hostBoundUnreadableRoots` stay unreadable except the workspace, the read-only mounts, the policy's writable roots, and the runtime files the process names. Files matching `hiddenFiles` stay unreadable everywhere. Host paths outside those roots, such as `/etc`, `/opt`, and the temp areas, remain readable, unlike in the guest. Work the process starts keeps its own confinement: a workflow child runs its commands in the container.
82
+
78
83
  ### Failures and recovery
79
84
 
80
- Missing CLI, a stopped API server that cannot start, or a failed `container run` rejects the confined call with `SANDBOX_UNAVAILABLE`, and the message names `/sandbox local`. A `read-only` write denial reports `Read-only file system`, which the tool layer offers for the standard one-time escalation. Invalid `envDenylist`, `readOnlyMounts`, `protectedPaths`, or `cpus` values fail at load.
85
+ Missing CLI, a stopped API server that cannot start, or a failed `container run` rejects the confined call with `SANDBOX_UNAVAILABLE`, and the message names `/sandbox local`. A `read-only` write denial reports `Read-only file system`, which the tool layer offers for the standard one-time escalation. A host-bound call of a container session fails with `SANDBOX_UNSUPPORTED_POLICY` when a configured `runnerCommand` replaces the Seatbelt chain, because only Seatbelt expresses the read fence. Invalid `envDenylist`, `readOnlyMounts`, `protectedPaths`, `hostBoundUnreadableRoots`, or `cpus` values fail at load.
81
86
 
82
87
  -----
83
88
 
@@ -89,11 +94,11 @@ Missing CLI, a stopped API server that cannot start, or a failed `container run`
89
94
 
90
95
  ### Containers
91
96
 
92
- The provider owns one container per canonical workspace root and confined mode, shared by every session and subagent in that workspace and mode. It starts with `container run --detach --init --rm`, labelled with the owning process id, bind-mounted with `--mount type=bind,…` (the `-v src:dst:ro` form is not used because `container` 1.5.0 misparses it), and idles on `sleep infinity`. Each container also mounts a private host run directory, `<os tmpdir>/dsh-container-run/<container name>`, writable at `/run/dsh` under every confined mode. A cached container is re-inspected with one `container inspect` at most once per `recheckMs` and restarted when it is gone or its run directory was deleted; disposal deletes every owned container and its run directory, and load deletes containers and run directories whose process has exited. When the default backend is `container` and the deployment default mode is confined, the default-mode container starts in the background at load.
97
+ The provider owns one container per canonical workspace root and confined mode, shared by every session and subagent in that workspace and mode. It starts with `container run --detach --init --rm`, labelled with the owning process id, bind-mounted with `--mount type=bind,…`, which 1.5.0 and 1.6.1 both parse while 1.5.0 misparses `-v src:dst:ro`, and idles on `sleep infinity`. Each container also mounts a private host run directory, `<os tmpdir>/dsh-container-run/<container name>`, writable at `/run/dsh` under every confined mode. A cached container is re-inspected with one `container inspect` at most once per `recheckMs` and restarted when it is gone or its run directory was deleted; disposal deletes every owned container and its run directory, and load deletes containers and run directories whose process has exited. When the default backend is `container` and the deployment default mode is confined, the default-mode container starts in the background at load.
93
98
 
94
99
  ### Execution shim
95
100
 
96
- `confine` returns `[node, exec-shim.js, <executable>, <container>, <run dir>, <denylist>, '--', ...argv]`. The shim runs on the host with the caller's working directory and environment, writes the filtered environment to a private `--env-file`, and runs `container exec -i [-t] -w <cwd>` with the argv under `setsid -w` in the guest. Before the argv starts, the guest wrapper writes its process-group id to `/run/dsh/<token>.pid`; when that write fails, the argv does not run. Because `container exec` does not forward signals, the shim signals that process group itself; a forwarded signal exits `128 + n`. The pid file doubles as the start sentinel: after `container exec` exits, the shim removes it from the host run directory, and a missing file marks a runtime failure, reported as `dsh-container-exec: …` with exit 125 and classified by the runner-failure rule, rather than a command that ran and failed. Each command therefore costs one `container exec`. The built `lib/exec-shim.js` depends only on Node built-ins and runs under plain Node in the npm-installed CLI; a source checkout launches `src/exec-shim.ts` through tsx.
101
+ `confine` returns `[node, exec-shim.js, <executable>, <container>, <run dir>, <denylist>, '--', ...argv]`. The shim runs on the host with the caller's working directory and environment, writes the filtered environment to a private `--env-file`, and runs `container exec -i [-t] -w <cwd>` with the argv under `setsid -w` in the guest. Before the argv starts, the guest wrapper writes its process-group id to `/run/dsh/<token>.pid`; when that write fails, the argv does not run. `container exec` never signals that process group: 1.5.0 forwards no signal, and 1.6.1 forwards it only to the `setsid` process, whose exit closes `container exec` while the group keeps running. The shim therefore signals the group itself through one more `container exec`, and a forwarded signal exits `128 + n`. The pid file doubles as the start sentinel: after `container exec` exits and every group signal has run, the shim removes it from the host run directory, and a missing file marks a runtime failure, reported as `dsh-container-exec: …` with exit 125 and classified by the runner-failure rule, rather than a command that ran and failed. Each command therefore costs one `container exec`. The built `lib/exec-shim.js` depends only on Node built-ins and runs under plain Node in the npm-installed CLI; a source checkout launches `src/exec-shim.ts` through tsx.
97
102
 
98
103
  ### Source map
99
104
 
@@ -148,7 +153,8 @@ The stable system prompt is unchanged. A changed context snapshot is appended af
148
153
  <a id="known-limitations-and-deferred-work"></a>
149
154
 
150
155
  - **Masks cover files present at container start** — `container` masks only paths that exist at creation, so a secret file created later is readable by commands in the running container until it restarts; file tools refuse it immediately.
151
- - **Single-file mounts are unsupported** — `container` 1.5.0 binds only directories, so protection works per directory (`.git`), not per file (`.git/config`).
156
+ - **Single-file mounts are unsupported** — `container` 1.5.0 and 1.6.1 bind only directories, so protection works per directory (`.git`), not per file (`.git/config`).
157
+ - **Host-bound processes read more of the host than commands** — outside `hostBoundUnreadableRoots`, a host-bound process can read system and temp paths that the guest never mounts, and file metadata stays readable everywhere.
152
158
  - **Subagents start on the default backend** — a child session does not inherit its parent's `/sandbox` choice.
153
159
  - **Terminal resizes do not reach the guest** — `container exec` does not forward `SIGWINCH`.
154
160
  - **Host and guest toolchains differ** — Darwin-native binaries in the workspace do not run in the Linux guest; use `/sandbox local` for those projects.
@@ -161,6 +167,6 @@ The stable system prompt is unchanged. A changed context snapshot is appended af
161
167
 
162
168
  No invariant companion is published: the `sandboxBackend` projection validates every folded `sandbox/backend` value against its two-value state schema, so a forged value fails at replay without a separate observation.
163
169
 
164
- Revisit the `-v` parsing, signal-forwarding, and single-file-mount workarounds when upgrading `container`; its releases are product versions, not semantic versions.
170
+ Revisit the mount syntax, signal-forwarding, and single-file-mount workarounds when upgrading `container`; its releases are product versions, not semantic versions. On 1.6.1, `-v src:dst:ro` parses correctly, a file mount source is still refused, and `container exec` forwards a signal to the process it started.
165
171
 
166
172
  </details>
@@ -9,7 +9,7 @@ kind: "package-reference"
9
9
 
10
10
  ## 概述
11
11
 
12
- 使用本包可在搭载 Apple 芯片、运行 Apple `container` CLI 1.5.0 或更高版本的 macOS 上,将 bash、终端和 PTC 命令限制在 [Apple `container`](https://github.com/apple/container) Linux 虚拟机中。虚拟机只挂载会话工作区,模型文件工具也受相同读取范围限制;`.env` 文件会被遮蔽,类似凭据的环境变量不会传入客户机,`.git` 保持只读。其他主机和通过 `/sandbox local` 切换的会话使用继承的本地沙箱链。
12
+ 使用本包可在搭载 Apple 芯片、运行 Apple `container` CLI 1.5.0 或更高版本的 macOS 上,将 bash 和终端命令限制在 [Apple `container`](https://github.com/apple/container) Linux 虚拟机中。虚拟机只挂载会话工作区,模型文件工具也受相同读取范围限制;`.env` 文件会被遮蔽,类似凭据的环境变量不会传入客户机,`.git` 保持只读。宿主机绑定进程(例如运行工作流的 Node 代码执行 worker)留在宿主机上,在 Seatbelt 下受与之对应的读取围栏限制。其他主机和通过 `/sandbox local` 切换的会话使用继承的本地沙箱链。
13
13
 
14
14
  ## 目录
15
15
 
@@ -55,6 +55,7 @@ kind: "package-reference"
55
55
  | `protectedPaths` | `['.git']` | 在 `workspace-write` 下以只读方式挂载的工作区相对目录 |
56
56
  | `hiddenFiles` | `.env`、`.env.*`、`.envrc`、私钥与证书文件名、`.npmrc`、`.pypirc`、`.netrc`、`.git-credentials` | 在客户机中被遮蔽、并被文件工具拒绝的文件名通配模式 |
57
57
  | `hiddenFilesMaxDepth`、`hiddenFilesSkipDirs` | `8`、`['node_modules', '.git']` | 容器启动时查找待遮蔽文件的工作区扫描范围 |
58
+ | `hostBoundUnreadableRoots` | `['/Users', '/Volumes']` | 容器会话的宿主机绑定进程不能读取其文件内容的宿主机绝对目录;读取范围、可写根目录以及进程的运行时文件除外 |
58
59
 
59
60
  `@deepseek-ai/dsh-sandbox-local` 的字段同样适用于 `local` 后端。生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-sandbox-apple-container)是每个字段及其 JSDoc 的完整来源。
60
61
 
@@ -75,9 +76,13 @@ kind: "package-reference"
75
76
 
76
77
  `danger-full-access` 绕过 `confine`,因此在任一后端下都在宿主机上运行。从容器会话升权到 `danger-full-access` 时,审批提示会补充说明该命令将直接在 Mac 上运行,而不是在容器内。会话运行在此后端时,Auto 权限不会写入它:而是写入 `workspace-write`,并由 reviewer 而不是提示批准离开容器的一次性提权([Auto review](../../experimental/auto-review/README.zh.md))。在 `local` 后端上,Auto 仍写入 `danger-full-access`。
77
78
 
79
+ ### 宿主机绑定进程
80
+
81
+ 运行工作流的 Node 代码执行 worker 会启动宿主机的 Node 可执行文件及其 bootstrap,并通过继承的控制描述符与宿主机通信,因此无法在客户机中运行。它的 `confineHostBound` 调用会在宿主机上用继承的 Seatbelt 链隔离它:沿用会话的写入规则,再加一道读取围栏。`hostBoundUnreadableRoots` 下的文件内容保持不可读,但工作区、只读挂载、策略的可写根目录以及进程声明的运行时文件除外。匹配 `hiddenFiles` 的文件在任何位置都不可读。这些根目录之外的宿主机路径,例如 `/etc`、`/opt` 和临时区域,仍然可读,这一点与客户机不同。该进程启动的工作保持各自的隔离:工作流子智能体的命令在容器中运行。
82
+
78
83
  ### 失败与恢复
79
84
 
80
- CLI 缺失、已停止且无法启动的 API 服务器,或 `container run` 失败,都会以 `SANDBOX_UNAVAILABLE` 拒绝受限调用,消息中会提到 `/sandbox local`。`read-only` 下被拒绝的写入报告 `Read-only file system`,工具层会为此提供标准的一次性提权。无效的 `envDenylist`、`readOnlyMounts`、`protectedPaths` 或 `cpus` 值在加载时失败。
85
+ CLI 缺失、已停止且无法启动的 API 服务器,或 `container run` 失败,都会以 `SANDBOX_UNAVAILABLE` 拒绝受限调用,消息中会提到 `/sandbox local`。`read-only` 下被拒绝的写入报告 `Read-only file system`,工具层会为此提供标准的一次性提权。配置的 `runnerCommand` 取代 Seatbelt 链时,容器会话的宿主机绑定调用以 `SANDBOX_UNSUPPORTED_POLICY` 失败,因为只有 Seatbelt 能表达读取围栏。无效的 `envDenylist`、`readOnlyMounts`、`protectedPaths`、`hostBoundUnreadableRoots` 或 `cpus` 值在加载时失败。
81
86
 
82
87
  -----
83
88
 
@@ -89,11 +94,11 @@ CLI 缺失、已停止且无法启动的 API 服务器,或 `container run` 失
89
94
 
90
95
  ### 容器
91
96
 
92
- 提供方为每个规范化的工作区根目录与受限模式各持有一个容器,由该工作区与模式下的所有会话和子智能体共享。容器以 `container run --detach --init --rm` 启动,带有所属进程 id 的标签,使用 `--mount type=bind,…` 绑定挂载(不使用 `-v src:dst:ro` 形式,因为 `container` 1.5.0 会错误解析它),并以 `sleep infinity` 空转。每个容器还挂载一个私有的宿主机运行目录 `<os tmpdir>/dsh-container-run/<container name>`,在所有受限模式下都以可写方式挂载到 `/run/dsh`。缓存的容器每 `recheckMs` 至多以一次 `container inspect` 重新检查,在容器消失或其运行目录被删除时重新启动;销毁时删除所有自有容器及其运行目录,加载时删除所属进程已退出的容器与运行目录。当默认后端为 `container` 且部署默认模式为受限模式时,默认模式的容器会在加载时于后台启动。
97
+ 提供方为每个规范化的工作区根目录与受限模式各持有一个容器,由该工作区与模式下的所有会话和子智能体共享。容器以 `container run --detach --init --rm` 启动,带有所属进程 id 的标签,使用 `--mount type=bind,…` 绑定挂载,1.5.0 与 1.6.1 都能正确解析这种形式,而 1.5.0 会错误解析 `-v src:dst:ro`;容器以 `sleep infinity` 空转。每个容器还挂载一个私有的宿主机运行目录 `<os tmpdir>/dsh-container-run/<container name>`,在所有受限模式下都以可写方式挂载到 `/run/dsh`。缓存的容器每 `recheckMs` 至多以一次 `container inspect` 重新检查,在容器消失或其运行目录被删除时重新启动;销毁时删除所有自有容器及其运行目录,加载时删除所属进程已退出的容器与运行目录。当默认后端为 `container` 且部署默认模式为受限模式时,默认模式的容器会在加载时于后台启动。
93
98
 
94
99
  ### 执行 shim
95
100
 
96
- `confine` 返回 `[node, exec-shim.js, <executable>, <container>, <run dir>, <denylist>, '--', ...argv]`。shim 以调用方的工作目录与环境在宿主机上运行,将过滤后的环境写入私有的 `--env-file`,并在客户机中通过 `setsid -w` 以 `container exec -i [-t] -w <cwd>` 运行 argv。argv 启动前,客户机包装脚本将其进程组 id 写入 `/run/dsh/<token>.pid`;写入失败时 argv 不会运行。由于 `container exec` 不转发信号,shim 自行向该进程组发送信号;被转发的信号以 `128 + n` 退出。该 pid 文件同时充当启动哨兵:`container exec` 退出后,shim 从宿主机运行目录中删除它,文件缺失即表示运行时失败(以 `dsh-container-exec: …` 报告、退出码 125,并由运行器失败规则分类),而非已运行但失败的命令。因此每条命令只需一次 `container exec`。构建后的 `lib/exec-shim.js` 只依赖 Node 内置模块,可在 npm 安装的 CLI 中以纯 Node 运行;源码检出则通过 tsx 启动 `src/exec-shim.ts`。
101
+ `confine` 返回 `[node, exec-shim.js, <executable>, <container>, <run dir>, <denylist>, '--', ...argv]`。shim 以调用方的工作目录与环境在宿主机上运行,将过滤后的环境写入私有的 `--env-file`,并在客户机中通过 `setsid -w` 以 `container exec -i [-t] -w <cwd>` 运行 argv。argv 启动前,客户机包装脚本将其进程组 id 写入 `/run/dsh/<token>.pid`;写入失败时 argv 不会运行。`container exec` 从不向该进程组发送信号:1.5.0 不转发任何信号,1.6.1 只把信号转发给它启动的 `setsid` 进程,该进程退出会让 `container exec` 结束,而进程组仍在运行。因此 shim 通过再一次 `container exec` 自行向进程组发送信号,被转发的信号以 `128 + n` 退出。该 pid 文件同时充当启动哨兵:`container exec` 退出且所有进程组信号都执行完毕后,shim 从宿主机运行目录中删除它,文件缺失即表示运行时失败(以 `dsh-container-exec: …` 报告、退出码 125,并由运行器失败规则分类),而非已运行但失败的命令。因此每条命令只需一次 `container exec`。构建后的 `lib/exec-shim.js` 只依赖 Node 内置模块,可在 npm 安装的 CLI 中以纯 Node 运行;源码检出则通过 tsx 启动 `src/exec-shim.ts`。
97
102
 
98
103
  ### 源码地图
99
104
 
@@ -148,7 +153,8 @@ Commands confined by the DSH file sandbox run inside a Linux container from imag
148
153
  <a id="known-limitations-and-deferred-work"></a>
149
154
 
150
155
  - **遮蔽只覆盖容器启动时已存在的文件** — `container` 只遮蔽创建时存在的路径,因此之后创建的密钥文件在容器重启前可被运行中容器内的命令读取;文件工具会立即拒绝它。
151
- - **不支持单文件挂载** — `container` 1.5.0 只能绑定目录,因此保护以目录(`.git`)为单位,而非文件(`.git/config`)。
156
+ - **不支持单文件挂载** — `container` 1.5.0 与 1.6.1 只能绑定目录,因此保护以目录(`.git`)为单位,而非文件(`.git/config`)。
157
+ - **宿主机绑定进程能读取的宿主机范围大于命令** — 在 `hostBoundUnreadableRoots` 之外,宿主机绑定进程可以读取客户机从未挂载的系统路径和临时路径,文件元数据在任何位置都保持可读。
152
158
  - **子智能体从默认后端开始** — 子会话不继承父会话的 `/sandbox` 选择。
153
159
  - **终端尺寸变化不会传到客户机** — `container exec` 不转发 `SIGWINCH`。
154
160
  - **宿主机与客户机工具链不同** — 工作区中的 Darwin 原生二进制无法在 Linux 客户机中运行;此类项目请使用 `/sandbox local`。
@@ -161,6 +167,6 @@ Commands confined by the DSH file sandbox run inside a Linux container from imag
161
167
 
162
168
  未发布 `./invariant` 配套模块:`sandboxBackend` 投影会用其二值状态 schema 校验每个折叠的 `sandbox/backend` 值,因此伪造的值会在回放时失败,无需额外的独立观察。
163
169
 
164
- 升级 `container` 时,请重新评估 `-v` 解析、信号转发与单文件挂载这几项绕行措施;其版本号是产品版本,而非语义化版本。
170
+ 升级 `container` 时,请重新评估挂载语法、信号转发与单文件挂载这几项绕行措施;其版本号是产品版本,而非语义化版本。在 1.6.1 上,`-v src:dst:ro` 已能正确解析,文件挂载源仍会被拒绝,`container exec` 会把信号转发给它启动的进程。
165
171
 
166
172
  </details>
@@ -124,9 +124,10 @@ function signalExit(signal) {
124
124
  async function runShim(args, deps) {
125
125
  const envFile = deps.writeEnvFile(envFileText(deps.env, args.denylist));
126
126
  let forwarded;
127
+ const kills = [];
127
128
  const unsubscribe = deps.onSignal((signal) => {
128
129
  forwarded ??= signal;
129
- deps.run(args.executable, killArgs(args.container, deps.token, signal));
130
+ kills.push(deps.run(args.executable, killArgs(args.container, deps.token, signal)));
130
131
  });
131
132
  try {
132
133
  const child = deps.spawn(args.executable, execArgs(args, {
@@ -141,6 +142,7 @@ async function runShim(args, deps) {
141
142
  resolve(code ?? signalExit(signal));
142
143
  });
143
144
  });
145
+ for (const kill of kills) await kill;
144
146
  const started = deps.consumeFile(join(args.runDir, pidFileName(deps.token)));
145
147
  if (forwarded !== void 0) return signalExit(forwarded);
146
148
  if (exit === 0 || started) return exit;
@@ -6,7 +6,7 @@ import { Service } from "@deepseek-ai/cordis";
6
6
  import z from "@deepseek-ai/schemastery";
7
7
  import { z as z$1 } from "zod";
8
8
  import { CommandDefinitionId } from "@deepseek-ai/dsh-commands/brand";
9
- import { SandboxUnavailableError, canonicalPath, nameGlobMatcher } from "@deepseek-ai/dsh-sandbox";
9
+ import { SandboxUnavailableError, canonicalPath, nameGlobMatcher, writableRoots } from "@deepseek-ai/dsh-sandbox";
10
10
  import { LocalSandboxProvider } from "@deepseek-ai/dsh-sandbox-local";
11
11
  import { createHash } from "node:crypto";
12
12
  import { mkdir, readdir, rm } from "node:fs/promises";
@@ -450,7 +450,9 @@ function setSandboxBackend(session, backend) {
450
450
  * local platform chain, while `container` runs the argv through an exec shim
451
451
  * inside a Linux container VM that bind-mounts the workspace at its own
452
452
  * absolute path (read-only under `read-only`). Host file effects stay inside
453
- * the workspace, and the guest cannot read unmounted host paths.
453
+ * the workspace, and the guest cannot read unmounted host paths. A host-bound
454
+ * execution, which the guest cannot run, confines in place under the local
455
+ * Seatbelt chain with a read fence instead.
454
456
  *
455
457
  * Each session's backend is the last `sandbox/backend` event in its log,
456
458
  * otherwise the configured default; the shared `/sandbox` command reports and
@@ -506,6 +508,11 @@ const DEFAULT_HIDDEN_FILES = [
506
508
  ".netrc",
507
509
  ".git-credentials"
508
510
  ];
511
+ /**
512
+ * Host directories whose file contents host-bound executions of container
513
+ * sessions cannot read by default: user homes and attached volumes.
514
+ */
515
+ const DEFAULT_HOST_BOUND_UNREADABLE_ROOTS = ["/Users", "/Volumes"];
509
516
  /** Stderr text of a write the read-only workspace mount refused. */
510
517
  const CONTAINER_DENIAL_SIGNATURES = ["read-only file system"];
511
518
  /** The shim's own failure line, emitted only when the command never started. */
@@ -571,7 +578,8 @@ var AppleContainerSandboxProvider = class extends LocalSandboxProvider {
571
578
  protectedPaths: z.array(z.string()).default([".git"]),
572
579
  hiddenFiles: z.array(z.string()).default([...DEFAULT_HIDDEN_FILES]),
573
580
  hiddenFilesMaxDepth: z.natural().default(8),
574
- hiddenFilesSkipDirs: z.array(z.string()).default(["node_modules", ".git"])
581
+ hiddenFilesSkipDirs: z.array(z.string()).default(["node_modules", ".git"]),
582
+ hostBoundUnreadableRoots: z.array(z.string()).default([...DEFAULT_HOST_BOUND_UNREADABLE_ROOTS])
575
583
  })]);
576
584
  static inject = ["sessions", "sessionProjections"];
577
585
  /** The backend for sessions without a recorded choice, after `auto` resolution. */
@@ -583,6 +591,7 @@ var AppleContainerSandboxProvider = class extends LocalSandboxProvider {
583
591
  envDenylist;
584
592
  readOnlyMounts;
585
593
  hiddenFiles;
594
+ hostBoundUnreadableRoots;
586
595
  runtime;
587
596
  pool;
588
597
  /** Reader for the `sandboxBackend` projection, registered during activation. */
@@ -615,6 +624,9 @@ var AppleContainerSandboxProvider = class extends LocalSandboxProvider {
615
624
  const protectedPaths = config.protectedPaths;
616
625
  if (protectedPaths.some((path) => path === "" || isAbsolute(path) || path.includes(",") || path.split(/[\\/]/u).includes(".."))) throw new Error("sandbox-apple-container: protectedPaths entries must be workspace-relative paths without `..` or a comma");
617
626
  this.hiddenFiles = config.hiddenFiles;
627
+ const unreadable = config.hostBoundUnreadableRoots;
628
+ if (unreadable.some((path) => !isAbsolute(path))) throw new Error("sandbox-apple-container: hostBoundUnreadableRoots entries must be absolute paths");
629
+ this.hostBoundUnreadableRoots = [...new Set(unreadable.map(canonicalPath))];
618
630
  this.runtime = new ContainerRuntime({
619
631
  executable: this.executable,
620
632
  image: this.image,
@@ -727,6 +739,35 @@ var AppleContainerSandboxProvider = class extends LocalSandboxProvider {
727
739
  };
728
740
  }
729
741
  /**
742
+ * Confine a host-bound execution in place. The local backend wraps it like
743
+ * any other call. The container guest cannot run host executables or receive
744
+ * descriptors beyond stdio, so the container backend confines it with the
745
+ * local Seatbelt chain under the policy's write rules and a read fence: file
746
+ * contents under `hostBoundUnreadableRoots` stay unreadable except the read
747
+ * scope, the policy's writable roots, and the runtime paths, and hidden files
748
+ * stay unreadable everywhere. Host paths outside those roots stay readable.
749
+ * @param argv - the exact argv the caller is about to spawn.
750
+ * @param policy - the file-effect policy this execution runs under.
751
+ * @param execution - the runtime paths the process must read.
752
+ * @param signal - cancellation before policy resolution.
753
+ * @returns the wrapped argv; a container session whose local chain is not
754
+ * Seatbelt fails closed with `SANDBOX_UNSUPPORTED_POLICY`.
755
+ */
756
+ async confineHostBound(argv, policy, execution, signal) {
757
+ signal?.throwIfAborted();
758
+ if (this.policyBackend(policy) === "local") return super.confine(argv, policy, signal);
759
+ const readable = [
760
+ ...this.containerReadRoots(policy),
761
+ ...writableRoots(policy),
762
+ ...execution.runtimePaths
763
+ ];
764
+ return this.confineWithReadFence(argv, policy, {
765
+ deniedRoots: this.hostBoundUnreadableRoots,
766
+ readableRoots: [...new Set(readable.map(canonicalPath))],
767
+ hiddenNames: this.hiddenFiles
768
+ }, signal);
769
+ }
770
+ /**
730
771
  * Tells the user that `danger-full-access` leaves the container.
731
772
  * @param policy - the calling session's resolved policy.
732
773
  * @param target - the wider mode the call asks for.
@@ -749,14 +790,18 @@ var AppleContainerSandboxProvider = class extends LocalSandboxProvider {
749
790
  readScope(policy) {
750
791
  if (policy.mode === "danger-full-access" || this.policyBackend(policy) === "local") return void 0;
751
792
  return {
752
- roots: [...new Set([
753
- policy.workspaceRoot,
754
- canonicalPath(policy.workspaceRoot),
755
- ...this.readOnlyMounts
756
- ])],
793
+ roots: this.containerReadRoots(policy),
757
794
  hiddenNames: this.hiddenFiles
758
795
  };
759
796
  }
797
+ /** The host directories a container session's guest can read: the workspace as spelled and canonical, and the extra mounts. */
798
+ containerReadRoots(policy) {
799
+ return [...new Set([
800
+ policy.workspaceRoot,
801
+ canonicalPath(policy.workspaceRoot),
802
+ ...this.readOnlyMounts
803
+ ])];
804
+ }
760
805
  /** The backend of the session a policy names; agentless and unknown sessions use the default. */
761
806
  policyBackend(policy) {
762
807
  return this.backendFor(policy.sessionId === void 0 ? void 0 : this.ctx.sessions.get(policy.sessionId));
@@ -780,4 +825,4 @@ var AppleContainerSandboxProvider = class extends LocalSandboxProvider {
780
825
  }
781
826
  };
782
827
  //#endregion
783
- export { AppleContainerSandboxProvider, AppleContainerSandboxProvider as default, DEFAULT_ENV_DENYLIST, DEFAULT_HIDDEN_FILES, SANDBOX_BACKENDS, containerSupported, executableResolves, isSandboxBackend, resolveBackend, setSandboxBackend, shimInvocation };
828
+ export { AppleContainerSandboxProvider, AppleContainerSandboxProvider as default, DEFAULT_ENV_DENYLIST, DEFAULT_HIDDEN_FILES, DEFAULT_HOST_BOUND_UNREADABLE_ROOTS, SANDBOX_BACKENDS, containerSupported, executableResolves, isSandboxBackend, resolveBackend, setSandboxBackend, shimInvocation };
@@ -36,8 +36,8 @@
36
36
  en: f0c44248c2ca6acc
37
37
  zh: 554e9f706671d222
38
38
  /deepseek-ai-dsh-sandbox-local/understand-the-implementation/platform-profiles:
39
- en: 008967ee30fbbe46
40
- zh: 9e5c6a3e97851a69
39
+ en: ed15f305683568b8
40
+ zh: 6f34d5433a2fa9c5
41
41
  /deepseek-ai-dsh-sandbox-local/understand-the-implementation/denial-and-runner-failure-dialects:
42
42
  en: 62adfc9229c656cc
43
43
  zh: 11b1534b6d61e5de
@@ -80,6 +80,8 @@ The `@deepseek-ai/node-addon-system/landlock-run` API supplies the platform laun
80
80
 
81
81
  The Seatbelt profile is allow-default with `(deny file-write*)` plus write allow-lists derived from the shared `writableRoots` helper, so exactly the mode's promised file effects are governed; every root is canonicalized because Seatbelt matches resolved paths (`/tmp` IS `/private/tmp`).
82
82
 
83
+ A subclass can add a read fence through the protected `confineWithReadFence`: the profile then denies `file-read-data` under the fence's denied roots, allows it again under its readable roots, and denies it for files whose name matches a hidden-name glob. Seatbelt applies the last matching rule, so the forms follow that order. Metadata reads stay allowed. Resolved-path matching keeps symlinks and firmlinked `/System/Volumes/Data` spellings inside the fence, and Seatbelt refuses a new hard link to a file the fence denies. Only the Seatbelt rung expresses a fence; another selected runner or a configured `runnerCommand` fails closed with `SANDBOX_UNSUPPORTED_POLICY`. The [Apple container backend](../sandbox-apple-container/README.md) uses it for host-bound executions.
84
+
83
85
  The Windows rung keeps one deterministic write SID and standing ACE per workspace, while every live session/workspace pair gets a random private temp directory with a distinct SID and revocable ACE — sessions sharing a workspace share its intended write authority without inheriting one another's temp authority. A fresh provider always chooses a new temp path and SID, so crash residue cannot block or authorize a resumed session. The rung reports `partial` enforcement because NTFS hard links alias one file object across paths, reads stay unconfined, and a tree another AppContainer tool has ACL'd with a package SID is unreadable to the Low-integrity child.
84
86
 
85
87
  With the built-in Windows runner and a skill registry, this provider registers the [ACL diagnosis skill](../sandbox-windows-acl/README.md#failures-and-recovery). An operator-supplied `runnerCommand` does not register it; provider disposal removes the skill and its extracted resources.
@@ -80,6 +80,8 @@ bwrap profile 组合只读宿主根目录、全新 `/dev` 与私有 PID 命名
80
80
 
81
81
  Seatbelt profile 默认允许,带 `(deny file-write*)` 与来自共享 `writableRoots` 辅助函数的写入 allow-list,因此恰好管辖模式承诺的文件操作;每个根目录都经过规范化,因为 Seatbelt 匹配解析后的路径(`/tmp` 就是 `/private/tmp`)。
82
82
 
83
+ 子类可以通过受保护的 `confineWithReadFence` 添加读取围栏:profile 随后在围栏的拒绝根目录下拒绝 `file-read-data`,在其可读根目录下重新允许,并对名称匹配隐藏名 glob 的文件拒绝读取。Seatbelt 采用最后一条匹配规则,因此这些形式按此顺序排列。元数据读取仍然允许。按解析后路径匹配,使符号链接以及经 firmlink 的 `/System/Volumes/Data` 写法都留在围栏之内,Seatbelt 也会拒绝为围栏所拒绝的文件新建硬链接。只有 Seatbelt 档能表达围栏;选中的其他 runner 或配置的 `runnerCommand` 会以 `SANDBOX_UNSUPPORTED_POLICY` 故障关闭。[Apple container 后端](../sandbox-apple-container/README.zh.md)用它处理宿主机绑定执行。
84
+
83
85
  Windows 档为每个工作区保留一个确定性写入 SID 和常驻 ACE,同时为每个活跃的会话/工作区对分配一个随机私有临时目录,以及不同的 SID 和可撤销 ACE——共享工作区的会话共享其预期写权限,却不会继承彼此的临时目录权限。新的提供方总会选择新的临时路径和 SID,因此崩溃残留既无法阻止恢复的会话,也无法向其授权。该档报告 `partial` 强制执行,因为 NTFS 硬链接会把同一文件对象别名为多个路径、读取仍不受限,且被其他 AppContainer 工具以包 SID 标记过的目录树对 Low 完整性子进程不可读。
84
86
 
85
87
  当内置 Windows runner 与技能注册表同时可用时,此提供方会注册 [ACL 诊断技能](../sandbox-windows-acl/README.zh.md#failures-and-recovery)。自定义 `runnerCommand` 不注册该技能;提供方释放时移除技能及其提取的资源。
@@ -50,9 +50,41 @@ function landlockProfileArgs(policy) {
50
50
  readWrite
51
51
  });
52
52
  }
53
- /** Quote one path as an SBPL string literal. */
54
- function sbplString(path) {
55
- return `"${path.replaceAll("\\", String.raw`\\`).replaceAll("\"", String.raw`\"`)}"`;
53
+ /** Quote one path or regular expression as an SBPL string literal. */
54
+ function sbplString(text) {
55
+ return `"${text.replaceAll("\\", String.raw`\\`).replaceAll("\"", String.raw`\"`)}"`;
56
+ }
57
+ /**
58
+ * Translate a file-name glob into an SBPL regular expression for the last
59
+ * path component, matching `nameGlobMatcher` for ASCII names. An empty glob
60
+ * or one containing `/` matches no file name and yields no expression.
61
+ * @param glob - one hidden-name glob.
62
+ * @returns the expression, or `undefined` when the glob cannot match a name.
63
+ */
64
+ function hiddenNameRegex(glob) {
65
+ if (glob === "" || glob.includes("/")) return void 0;
66
+ let body = "";
67
+ for (const char of glob) if (char === "*") body += "[^/]*";
68
+ else if (/^[A-Za-z]$/u.test(char)) body += `[${char.toLowerCase()}${char.toUpperCase()}]`;
69
+ else if (char === "^" || char === "\\") body += `[\\${char}]`;
70
+ else body += `[${char}]`;
71
+ return `/${body}$`;
72
+ }
73
+ /**
74
+ * The SBPL forms of one read fence, in the order Seatbelt's last-match rule
75
+ * needs: the denial, the readable exceptions, then hidden names.
76
+ * @param fence - the restriction to express.
77
+ * @returns forms appended after the write rules.
78
+ */
79
+ function readFenceForms(fence) {
80
+ const forms = [];
81
+ if (fence.deniedRoots.length > 0) {
82
+ forms.push(`(deny file-read-data ${fence.deniedRoots.map((root) => `(subpath ${sbplString(root)})`).join(" ")})`);
83
+ if (fence.readableRoots.length > 0) forms.push(`(allow file-read-data ${fence.readableRoots.map((root) => `(subpath ${sbplString(root)})`).join(" ")})`);
84
+ }
85
+ const hidden = fence.hiddenNames.map(hiddenNameRegex).filter((regex) => regex !== void 0);
86
+ if (hidden.length > 0) forms.push(`(deny file-read-data ${hidden.map((regex) => `(regex ${sbplString(regex)})`).join(" ")})`);
87
+ return forms;
56
88
  }
57
89
  /**
58
90
  * Build the sandbox-exec arguments and SBPL profile for one policy. The
@@ -62,9 +94,10 @@ function sbplString(path) {
62
94
  * (`@deepseek-ai/dsh-fs-sandbox`) can never drift apart; the helper adds the
63
95
  * documented Seatbelt temp areas.
64
96
  * @param policy - file-effect policy to express as an SBPL profile.
97
+ * @param fence - optional read restriction appended after the write rules.
65
98
  * @returns sandbox-exec arguments before the trailing separator and command argv.
66
99
  */
67
- function seatbeltProfileArgs(policy) {
100
+ function seatbeltProfileArgs(policy, fence) {
68
101
  const forms = [
69
102
  "(version 1)",
70
103
  "(allow default)",
@@ -73,6 +106,7 @@ function seatbeltProfileArgs(policy) {
73
106
  ];
74
107
  const roots = writableRoots(policy);
75
108
  if (roots.length > 0) forms.push(`(allow file-write* ${roots.map((root) => `(subpath ${sbplString(root)})`).join(" ")})`);
109
+ if (fence !== void 0) forms.push(...readFenceForms(fence));
76
110
  return ["-p", forms.join(" ")];
77
111
  }
78
112
  //#endregion
@@ -305,24 +339,46 @@ var LocalSandboxProvider = class extends SandboxProvider {
305
339
  * `SANDBOX_UNAVAILABLE` error when the platform has no usable runner.
306
340
  */
307
341
  async confine(argv, policy, signal) {
342
+ return this.wrap(argv, policy, void 0, signal);
343
+ }
344
+ /**
345
+ * Wrap `argv` like {@link confine} and add a read fence to the profile. Only
346
+ * the Seatbelt rung expresses a read fence; another selected runner or a
347
+ * configured `runnerCommand` fails closed with `SANDBOX_UNSUPPORTED_POLICY`.
348
+ * @param argv - the exact argv the caller is about to spawn.
349
+ * @param policy - the file-effect policy this execution runs under.
350
+ * @param fence - the read restriction, with canonical paths.
351
+ * @param signal - cancellation before policy resolution.
352
+ * @returns the wrapped argv plus the Seatbelt rung's enforcement, denial
353
+ * signatures, and runner-failure rules.
354
+ */
355
+ async confineWithReadFence(argv, policy, fence, signal) {
356
+ return this.wrap(argv, policy, fence, signal);
357
+ }
358
+ /** The shared wrap of {@link confine} and {@link confineWithReadFence}. */
359
+ wrap(argv, policy, fence, signal) {
308
360
  signal?.throwIfAborted();
309
361
  policy = {
310
362
  ...policy,
311
363
  workspaceRoot: canonicalPath(policy.workspaceRoot)
312
364
  };
313
- if (this.runnerCommand !== void 0) return Promise.resolve({
314
- argv: [
315
- ...this.runnerCommand,
316
- ...bwrapProfileArgs(policy),
317
- "--",
318
- ...argv
319
- ],
320
- enforcement: "full",
321
- denialSignatures: DENIAL_SIGNATURES.runnerCommand,
322
- runnerFailureRules: [{ fatalSignatures: this.configuredRunnerFailureSignatures }]
323
- });
365
+ if (this.runnerCommand !== void 0) {
366
+ if (fence !== void 0) throw new SandboxUnsupportedPolicyError("sandbox-local: a configured runnerCommand cannot restrict reads");
367
+ return Promise.resolve({
368
+ argv: [
369
+ ...this.runnerCommand,
370
+ ...bwrapProfileArgs(policy),
371
+ "--",
372
+ ...argv
373
+ ],
374
+ enforcement: "full",
375
+ denialSignatures: DENIAL_SIGNATURES.runnerCommand,
376
+ runnerFailureRules: [{ fatalSignatures: this.configuredRunnerFailureSignatures }]
377
+ });
378
+ }
324
379
  const selected = this.selectRunner(policy.mode);
325
- const runnerArgv = this.runnerArgv(selected.runner, policy);
380
+ if (fence !== void 0 && selected.runner !== "seatbelt") throw new SandboxUnsupportedPolicyError(`sandbox-local: the ${selected.runner} runner cannot restrict reads`);
381
+ const runnerArgv = this.runnerArgv(selected.runner, policy, fence);
326
382
  return Promise.resolve({
327
383
  argv: [
328
384
  ...runnerArgv,
@@ -335,11 +391,11 @@ var LocalSandboxProvider = class extends SandboxProvider {
335
391
  });
336
392
  }
337
393
  /** The selected rung's runner invocation (program + profile arguments) for one policy. */
338
- runnerArgv(runner, policy) {
394
+ runnerArgv(runner, policy, fence) {
339
395
  switch (runner) {
340
396
  case "bwrap": return ["bwrap", ...bwrapProfileArgs(policy)];
341
397
  case "landlock": return [this.landlockLauncher(), ...landlockProfileArgs(policy)];
342
- case "seatbelt": return [this.seatbeltExec(), ...seatbeltProfileArgs(policy)];
398
+ case "seatbelt": return [this.seatbeltExec(), ...seatbeltProfileArgs(policy, fence)];
343
399
  case "windows-acl": return this.windowsAclRunnerArgv(policy);
344
400
  default: return assertNever(runner);
345
401
  }
@@ -2542,9 +2542,15 @@ export const SERVICE_API = [
2542
2542
  parameters: [{ name: 'argv', description: 'the exact argv the caller is about to spawn (program plus arguments), NOT a shell string — a shell-shaped consumer passes `[\'bash\', \'-c\', command]`.' }, { name: 'policy', description: 'the file-effect policy this execution runs under, carried per call (see {@link SandboxPolicy}).' }, { name: 'signal', description: 'cancellation while the provider resolves the policy and runner.' }],
2543
2543
  returns: 'the argv to spawn instead, plus the enforcement completeness the selected backend achieves for it.',
2544
2544
  },
2545
+ {
2546
+ signature: 'confineHostBound( argv: readonly string[], policy: SandboxPolicy, _execution: HostBoundExecution, signal?: AbortSignal, ): Promise<ConfinedArgv>',
2547
+ description: 'Wrap `argv` for a host-bound execution: one that must run in the subprocess provider\'s own execution world because its executable or runtime files are paths there outside the shared workspace, or because it inherits descriptors beyond stdin, stdout, and stderr. The base implementation is confine, which already confines in that world. A provider whose `confine` relocates execution, such as the Apple container backend, overrides this to confine in place under a read restriction it documents, or fails closed.',
2548
+ parameters: [{ name: 'argv', description: 'the exact argv the caller is about to spawn.' }, { name: 'policy', description: 'the file-effect policy this execution runs under.' }, { name: '_execution', description: 'the runtime paths the process must read.' }, { name: 'signal', description: 'cancellation while the provider resolves the policy and runner.' }],
2549
+ returns: 'the argv to spawn instead, plus the enforcement completeness the selected backend achieves for it.',
2550
+ },
2545
2551
  {
2546
2552
  signature: 'readScope(_policy: SandboxExecutionPolicy): SandboxReadScope | undefined',
2547
- description: 'What a process confined under `policy` can read on the host, or `undefined` when this backend does not confine reads. Model-facing tools that read the host for the same session must refuse paths outside the scope, so their view never exceeds the confined processes\'. The base implementation confines no reads.',
2553
+ description: 'What a process wrapped by confine under `policy` can read on the host, or `undefined` when this backend does not confine reads. Model-facing tools that read the host for the same session must refuse paths outside the scope, so their view never exceeds the confined processes\'. The base implementation confines no reads.',
2548
2554
  parameters: [{ name: '_policy', description: 'the file-effect policy of the calling session.' }],
2549
2555
  returns: 'the read scope, or `undefined` for unconfined reads.',
2550
2556
  },
@@ -6760,6 +6766,10 @@ export const TYPE_API = [
6760
6766
  name: 'HookRegistration',
6761
6767
  declaration: 'export interface HookRegistration {\n catch(handler: AnyHook): void;\n}',
6762
6768
  },
6769
+ {
6770
+ name: 'HostBoundExecution',
6771
+ declaration: 'export interface HostBoundExecution {\n readonly runtimePaths: readonly string[];\n}',
6772
+ },
6763
6773
  {
6764
6774
  name: 'HostConnectionFetch',
6765
6775
  declaration: 'export interface HostConnectionFetch {\n register(route: ConnectionFetchRoute): () => Promise<void>;\n}',
@@ -24,8 +24,8 @@
24
24
  en: 8798852e763b4558
25
25
  zh: 6bb6768ee7186709
26
26
  /deepseek-ai-dsh-tui-app/use-this-package/keys-and-commands:
27
- en: 688e10e22846d3b5
28
- zh: 028366a1ef17688d
27
+ en: d2122e0739be9cb2
28
+ zh: cca31f6569716a8c
29
29
  /deepseek-ai-dsh-tui-app/use-this-package/background-tool-calls:
30
30
  en: 322ae3c6d76383ec
31
31
  zh: 8c38eee4b57ed8dd
@@ -68,6 +68,8 @@ The conversation, input, subagent panel, and status bar form the vertical arrow-
68
68
 
69
69
  Every key the screen names is drawn as a chip, italic in the accent color apart from the words around it: in the status bar, the region legends, the pickers and prompts, the transient line, fold markers, notices, `/help`, and the reader. With `mouse: true`, a left click on a chip presses that key exactly as typing it would, so `Shift+↓` in the status bar walks to the bar, `Esc` on the armed-stop line stops the turn, and each arrow of a pair such as `↑↓` presses its own key. Turning it on turns the terminal's mouse reports on: the wheel opens the full-screen reader at the newest section and scrolls it up or down, but does nothing while an approval or question is open. The wheel and plain click-drag reach the application instead of scrolling the terminal's scrollback or selecting text; most terminals still scroll and select with `Shift` held (`Option` in iTerm2).
70
70
 
71
+ The input colors its leading `/command` token with the accent color and leaves arguments plain; `NO_COLOR` disables this styling.
72
+
71
73
  While the input has the keyboard:
72
74
 
73
75
  | Key | Effect |
@@ -190,7 +192,7 @@ Typing `/` at the start of the editor completes the terminal's own commands and
190
192
  | `/attach <path>` | Attach an image or file to the next prompt or a shared command that accepts attachments; `/attach` lists them and `/attach clear` drops them |
191
193
  | `/queue` | Show the messages queued for the next turn and step; `/queue clear` drops them, and the rows above the editor with them |
192
194
  | `/retry` | Continue an eligible failed turn without a new prompt; pending human input or active work prevents admission, and staged attachments remain pending |
193
- | `/skills` | List the skills the agent can load |
195
+ | `/skills` | List skills available to the current agent and working directory, including global skills |
194
196
  | `/signin` | Sign in to a provider through its notices and prompts; `/signin <key>` skips the picker |
195
197
  | `/login` | Sign in with a provider subscription (hides key-collecting logins); `/login <key>` skips the picker |
196
198
  | `/export [dir]` | Write this session's log ZIP (sub-sessions and attachments included) into `dir`, default the workspace |
@@ -68,6 +68,8 @@ dsh tui --no-open # print sign-in URLs without opening a
68
68
 
69
69
  屏幕上写出的每个按键都画成一枚徽标,以强调色的斜体与周围文字区分开:出现在状态栏、各区域的按键提示、选择器与提示、临时提示行、折叠标记、通知、`/help` 与阅读器中。设置 `mouse: true` 后,左键点击一枚徽标就按下该键,与键入它完全相同:点击状态栏中的 `Shift+↓` 会走到状态栏,点击已布防的停止提示行中的 `Esc` 会停止轮次,`↑↓` 这类成对箭头中的每个箭头各自按下自己的键。开启它会打开终端的鼠标报告:滚轮在最新小节打开全屏阅读器并向上或向下滚动,但审批或提问打开期间不响应滚轮。滚轮与普通的点击拖动交给应用,而不再滚动终端的回滚缓冲区或选择文本;大多数终端在按住 `Shift`(iTerm2 中为 `Option`)时仍可滚动与选择。
70
70
 
71
+ 编辑器以强调色显示开头的 `/command`,参数保持普通文本;`NO_COLOR` 会禁用此样式。
72
+
71
73
  编辑器持有键盘时:
72
74
 
73
75
  | 按键 | 效果 |
@@ -190,7 +192,7 @@ follow-ups 面板持有键盘时:
190
192
  | `/attach <path>` | 把图片或文件附加到下一条提示,或附加到接受附件的共享命令;`/attach` 列出,`/attach clear` 丢弃 |
191
193
  | `/queue` | 显示为下一轮次与下一步排队的消息;`/queue clear` 丢弃它们,编辑器上方的对应行也随之消失 |
192
194
  | `/retry` | 不添加新提示,继续符合条件的失败轮次;待处理的人类输入或正在进行的工作会阻止提交,暂存附件保持待发送 |
193
- | `/skills` | 列出 agent 可加载的技能 |
195
+ | `/skills` | 列出当前 agent 和工作目录可用的技能,包括全局技能 |
194
196
  | `/signin` | 通过提供方的通知与提示登录;`/signin <key>` 跳过选择器 |
195
197
  | `/login` | 用提供方订阅登录(隐藏仅收集密钥的登录);`/login <key>` 跳过选择器 |
196
198
  | `/export [dir]` | 把本会话的日志 ZIP(含子会话与附件)写入 `dir`,默认 workspace |
@@ -8789,7 +8789,7 @@ function streamText(output) {
8789
8789
  //#endregion
8790
8790
  //#region lib/types/editor.js
8791
8791
  /**
8792
- * The prompt editor's caret, word navigation, and live `!` / `!!` syntax
8792
+ * The prompt editor's caret, word navigation, and live `/`, `!` / `!!` syntax
8793
8793
  * colour. pi-tui draws the caret cell itself in reverse video; this module
8794
8794
  * takes that block off the rendered lines, names the DECSCUSR sequences for a
8795
8795
  * blinking bar, maps Shift+Left/Right to pi-tui's word movement, and paints a
@@ -8858,8 +8858,12 @@ function stripBlockCursor(line) {
8858
8858
  function paintShellEditorLines(lines, text, width, paint) {
8859
8859
  const draft = parseUserShellDraft(text);
8860
8860
  if (draft === void 0) return [...lines];
8861
- const visual = visualChunks(text, paintDraftLines(draft, paint), editorLayoutWidth(width, paint.paddingX));
8862
- const pad = editorPad(width, paint.paddingX);
8861
+ return paintEditorLines(lines, text, paintDraftLines(draft, paint), width, paint.paddingX);
8862
+ }
8863
+ /** Overlay styled logical lines while preserving editor chrome and cursor placement. */
8864
+ function paintEditorLines(lines, text, paintedLogical, width, paddingX) {
8865
+ const visual = visualChunks(text, paintedLogical, editorLayoutWidth(width, paddingX));
8866
+ const pad = editorPad(width, paddingX);
8863
8867
  const out = [...lines];
8864
8868
  const bottom = out.findIndex((line, index) => index > 0 && isEditorRule(line));
8865
8869
  const end = bottom === -1 ? out.length : bottom;
@@ -9146,6 +9150,8 @@ var BarCursorEditor = class extends Editor {
9146
9150
  * drew it.
9147
9151
  */
9148
9152
  shellPaint;
9153
+ /** Colours the leading `/command` token without changing editor text or arguments. */
9154
+ commandColor;
9149
9155
  /**
9150
9156
  * Handle Shift+Left and Shift+Right as pi-tui's word movements.
9151
9157
  * @param data - the bytes the terminal sent.
@@ -9179,8 +9185,11 @@ var BarCursorEditor = class extends Editor {
9179
9185
  const next = stripBlockCursor(line);
9180
9186
  return focused ? next : next.replaceAll(CURSOR_MARKER, "");
9181
9187
  });
9188
+ const text = this.getText();
9189
+ const command = /^\/\S*/u.exec(text)?.[0];
9190
+ if (command !== void 0 && this.commandColor !== void 0) return paintEditorLines(stripped, text, `${this.commandColor(command)}${text.slice(command.length)}`.split("\n"), width, this.getPaddingX());
9182
9191
  const paint = this.shellPaint;
9183
- return paint === void 0 ? stripped : paintShellEditorLines(stripped, this.getText(), width, {
9192
+ return paint === void 0 ? stripped : paintShellEditorLines(stripped, text, width, {
9184
9193
  ...paint,
9185
9194
  paddingX: this.getPaddingX()
9186
9195
  });
@@ -16421,6 +16430,7 @@ var TuiApp = class {
16421
16430
  this.loader = new Loader(this.tui, palette.accent, (message) => this.paintLoaderMessage(message), "thinking", { frames: [] });
16422
16431
  this.compactions = new CompactionLedger((message) => deps.ctx.get("tokenMeter")?.estimateMessage(message));
16423
16432
  this.editor = new BarCursorEditor(this.tui, editorTheme(palette), { paddingX: 1 });
16433
+ this.editor.commandColor = palette.enabled ? palette.accent : void 0;
16424
16434
  this.editor.shellPaint = {
16425
16435
  highlight: this.codeHighlight,
16426
16436
  warning: palette.warning,
@@ -20366,7 +20376,12 @@ var TuiApp = class {
20366
20376
  return;
20367
20377
  }
20368
20378
  const palette = this.deps.palette;
20369
- const summaries = await skills.list();
20379
+ const agent = this.agent;
20380
+ const cwd = this.deps.ctx.get("workingDirectory")?.get(agent.session) ?? agent.session.header.cwd ?? this.deps.cwd;
20381
+ const summaries = await skills.list({
20382
+ cwd,
20383
+ scope: agent
20384
+ });
20370
20385
  if (summaries.length === 0) {
20371
20386
  this.notice("no skills are available");
20372
20387
  return;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@songtonyli/dsh-cli",
3
- "version": "0.1.96",
3
+ "version": "0.1.97",
4
4
  "description": "The dsh terminal agent: an interactive TUI over the DeepSeek Harness, with its whole Node runtime bundled in one install.",
5
5
  "license": "MIT",
6
6
  "type": "module",