@songtonyli/dsh-cli 0.1.59 → 0.1.61

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 (24) hide show
  1. package/README.md +1 -1
  2. package/bin/dsh.mjs +1 -1
  3. package/node_modules/@deepseek-ai/dsh-client-ui-primitives/package.json +2 -2
  4. package/node_modules/@deepseek-ai/dsh-client-ui-sidebar/lib/client.js +1 -1
  5. package/node_modules/@deepseek-ai/dsh-experimental-auto-review/README.i18n.yaml +4 -4
  6. package/node_modules/@deepseek-ai/dsh-experimental-auto-review/README.md +2 -2
  7. package/node_modules/@deepseek-ai/dsh-experimental-auto-review/README.zh.md +2 -2
  8. package/node_modules/@deepseek-ai/dsh-experimental-auto-review/lib/index.js +33 -8
  9. package/node_modules/@deepseek-ai/dsh-sandbox/lib/index.js +13 -2
  10. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.i18n.yaml +2 -2
  11. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.md +2 -2
  12. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.zh.md +2 -2
  13. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/lib/index.js +1 -1
  14. package/node_modules/@deepseek-ai/dsh-tool-fs/README.i18n.yaml +2 -2
  15. package/node_modules/@deepseek-ai/dsh-tool-fs/README.md +1 -1
  16. package/node_modules/@deepseek-ai/dsh-tool-fs/README.zh.md +1 -1
  17. package/node_modules/@deepseek-ai/dsh-tool-fs/lib/index.js +108 -13
  18. package/node_modules/@deepseek-ai/dsh-tui-app/README.i18n.yaml +8 -8
  19. package/node_modules/@deepseek-ai/dsh-tui-app/README.md +11 -8
  20. package/node_modules/@deepseek-ai/dsh-tui-app/README.zh.md +11 -8
  21. package/node_modules/@deepseek-ai/dsh-tui-app/lib/index.js +1864 -1781
  22. package/node_modules/@types/node/README.md +1 -1
  23. package/node_modules/@types/node/package.json +2 -2
  24. package/package.json +2 -2
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.59; `dsh --version`
29
+ Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.61; `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.59 (deepseek-harness 0.2.0-rc.2)')
21
+ console.log('@songtonyli/dsh-cli 0.1.61 (deepseek-harness 0.2.0-rc.2)')
22
22
  process.exit(0)
23
23
  }
24
24
 
@@ -48,9 +48,9 @@
48
48
  "micromark-util-sanitize-uri": "^2.0.1",
49
49
  "simple-icons": "16.31.0",
50
50
  "@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
51
+ "@deepseek-ai/cordis": "~4.0.4",
51
52
  "@deepseek-ai/dsh-util-code-language": "0.2.0-rc.2",
52
- "@deepseek-ai/dsh-util-workspace-path": "0.2.0-rc.2",
53
- "@deepseek-ai/cordis": "~4.0.4"
53
+ "@deepseek-ai/dsh-util-workspace-path": "0.2.0-rc.2"
54
54
  },
55
55
  "files": [
56
56
  "lib/index.js",
@@ -167,7 +167,7 @@ window.__ModuleLoader__.load({
167
167
  const SCROLLBAR_LINGER_MS = 2e3;
168
168
  /** Format complete-build metadata for the local brand badge. */
169
169
  function localBuildVersion() {
170
- return `0.2.0-rc.2-a2eb428` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
170
+ return `0.2.0-rc.2-8b8be23` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
171
171
  }
172
172
  /** Each panel row subscribes only to its own selection state. */
173
173
  function PanelRow({ id, label, wide, usePanelInfo, selectPanel, renderSlot }) {
@@ -39,8 +39,8 @@
39
39
  en: f77cfa836d8f9aef
40
40
  zh: fd93d0afcac4fb64
41
41
  /deepseek-ai-dsh-experimental-auto-review/model-experience/per-call-reviewer/token-effect:
42
- en: 9c3e575c061d53fe
43
- zh: 74db1c5a77b2d2a7
42
+ en: 0477fcb8eda9767f
43
+ zh: 76d5b56acb2942da
44
44
  /deepseek-ai-dsh-experimental-auto-review/model-experience/per-call-reviewer/kv-cache-effect:
45
45
  en: 67b73d97f22f3c75
46
46
  zh: 4dd263e571043cf4
@@ -57,8 +57,8 @@
57
57
  en: 8da1089dee147f94
58
58
  zh: 87361347bfd10c6c
59
59
  /deepseek-ai-dsh-experimental-auto-review/known-limitations-and-deferred-work:
60
- en: cf0c266006daf9a0
61
- zh: a29542f770947bfd
60
+ en: def1bd5ef705d4de
61
+ zh: c02672d92e6df455
62
62
  /deepseek-ai-dsh-experimental-auto-review/known-limitations-and-deferred-work/dev-note:
63
63
  en: e67f633dc6fe7773
64
64
  zh: 3bb0c20c93f16f98
@@ -88,7 +88,7 @@ The reviewer uses the latest `request/header.config` provider and model with the
88
88
 
89
89
  #### Token effect
90
90
 
91
- One additional model request per supported call, without caching, retries, truncation, compaction, or a separate small output budget. An oversized request fails the call with the provider error.
91
+ One additional model request per supported call. When a completed text response is invalid JSON, `maxJsonRetries` permits additional requests (default `1`, non-negative safe integer; `0` disables retries). Each retry reuses the frozen action facts and appends a fixed formatting reminder to the policy without including the malformed response. Valid denials, invalid risk/decision objects, provider or stream failures, and cancelled reviews are not retried. Exhausted JSON retries fail the call without executing its body. Requests have no caching, truncation, compaction, or separate small output budget; an oversized request fails with the provider error.
92
92
 
93
93
  #### KV Cache effect
94
94
 
@@ -114,7 +114,7 @@ The denial appends an ordinary tool result; it does not rewrite earlier context
114
114
 
115
115
  - The shipped TUI profile includes Auto review. Default Web, Headless, General settings, and new-session defaults omit it until this layer is switched on.
116
116
  - Auto provides no file sandbox. The outer `run_code` transport and direct Node effects inside a PTC program do not pass through inner-tool review.
117
- - Model classification can be wrong. There are no deterministic tool exemptions, persistent grants, configurable policy, or retry layer.
117
+ - Model classification can be wrong. There are no deterministic tool exemptions, persistent grants, or configurable policy. Formatting retries cannot correct a valid but mistaken classification.
118
118
  - In-process Auto children review their own calls. Out-of-process children retain their native permission systems after the parent delegation call is allowed.
119
119
  - The reviewer reads the Session action history through the deprecated synchronous `snapshotEvents()` reader under a line-scoped waiver. Prior calls, PTC starts, and the direct parent's initial prompt have no projection or paged reader yet, so the migration stays deferred by [the synchronous-read decision](../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
120
120
 
@@ -88,7 +88,7 @@ Reviewer 使用最新 `request/header.config` 的 provider 与模型,并沿用
88
88
 
89
89
  #### Token 影响
90
90
 
91
- 每个受支持调用额外产生一次模型请求,不缓存、重试、截断、压缩,也不设单独的小型输出预算。超窗请求以 provider 错误使调用失败。
91
+ 每个受支持调用额外产生一次模型请求。完整 text 响应不是有效 JSON 时,`maxJsonRetries` 允许额外请求(默认 `1`,非负安全整数;`0` 禁用重试)。每次重试复用冻结的动作事实,并在策略后追加固定格式提醒,不包含格式错误的响应。有效拒绝、非法 risk/decision 对象、provider 或 stream 失败以及已取消的 review 不重试。JSON 重试耗尽后调用失败,不执行 body。请求不缓存、截断、压缩,也不设单独的小型输出预算;超窗请求以 provider 错误使调用失败。
92
92
 
93
93
  #### KV Cache 影响
94
94
 
@@ -114,7 +114,7 @@ Reviewer 使用最新 `request/header.config` 的 provider 与模型,并沿用
114
114
 
115
115
  - 随附的 TUI profile 包含 Auto review。默认 Web、Headless、通用设置与新会话默认值在开启此层之前都不包含它。
116
116
  - Auto 不提供文件沙箱。外层 `run_code` transport 及PTC 程序内直接 Node 效果不经过 inner-tool review。
117
- - 模型分类可能出错。不提供确定性工具豁免、持久 grant、可配置策略或重试层。
117
+ - 模型分类可能出错。不提供确定性工具豁免、持久 grant 或可配置策略。格式重试无法纠正有效但错误的分类。
118
118
  - 进程内 Auto child 独立审查自身调用。进程外 child 在父委派调用获准后保留原生权限系统。
119
119
  - reviewer 在带行级豁免的情况下,通过已废弃的同步 `snapshotEvents()` 读取 Session 动作历史。此前的调用、PTC start 与直接父级的初始 prompt 目前都没有投影或分页读取方,因此迁移按[同步读取决策](../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.zh.md)继续延期。
120
120
 
@@ -40,6 +40,10 @@ Every retained history item has one source role. "human-instruction" text define
40
40
  Judge the pending action by what its tool and arguments will actually do. The exact session-created cleanup exception does not cover pre-existing objects or broader deletion. Listed medium and high effects take precedence over ordinary low-risk project work; a production read is medium even though it is read-only, and sensitive exfiltration is high even with explicit authorization. Fail closed when actual effects are ambiguous or broader than established scope. Deny a medium action if authorization of its action, target, scope, effect, count or duration is missing, conflicting, ambiguous, broader than the active instructions, or based only on constraints, checkpoints or facts. A later human or direct-parent instruction resolves an earlier conflict only when it explicitly revokes or replaces it; direct-parent instructions never override human restrictions.
41
41
 
42
42
  For any allow, end with exactly the applicable two-member object and nothing else. In particular, when a medium action is allowed, the complete text must be exactly {"risk":"medium","decision":"allow"}. Do not add reason, explanation, labels, Markdown, or surrounding prose. Stop immediately after the closing brace.`;
43
+ /** A completed reviewer text response that cannot be parsed as JSON. */
44
+ var ReviewerJsonError = class extends Error {};
45
+ /** Formatting correction for a fresh review of the same frozen action. */
46
+ const JSON_RETRY_REMINDER = "Your previous response was not valid JSON. Review the same pending action under REVIEW_POLICY. Return exactly one JSON object matching its risk/decision rules. Do not include analysis, Markdown, or surrounding prose.";
43
47
  /** Cordis plugin name used by loader diagnostics. */
44
48
  const name = "experimental-auto-review";
45
49
  /** Complete host services required before Auto may be advertised. */
@@ -50,11 +54,17 @@ const inject = [
50
54
  "sessions",
51
55
  "tools"
52
56
  ];
53
- /** Validate reviewer sampling configuration. */
54
- const Config = z.object({ temperature: z.union([z.transform(z.number().min(0).max(2), (value) => {
55
- if (!Number.isFinite(value)) throw new Error("reviewer temperature must be finite");
56
- return value;
57
- }), z.const("provider-default")]).default(0) });
57
+ /** Validate reviewer generation and JSON retry settings. */
58
+ const Config = z.object({
59
+ temperature: z.union([z.transform(z.number().min(0).max(2), (value) => {
60
+ if (!Number.isFinite(value)) throw new Error("reviewer temperature must be finite");
61
+ return value;
62
+ }), z.const("provider-default")]).default(0),
63
+ maxJsonRetries: z.transform(z.number().min(0).step(1), (value) => {
64
+ if (!Number.isSafeInteger(value)) throw new Error("reviewer JSON retry limit must be a non-negative safe integer");
65
+ return value;
66
+ }).default(1)
67
+ });
58
68
  /** Return JSON text for one immutable logged value. */
59
69
  function json(value) {
60
70
  const rendered = JSON.stringify(value, null, 2);
@@ -360,7 +370,12 @@ function topLevelMemberCount(text) {
360
370
  }
361
371
  /** Parse the closed risk/decision protocol and its fixed safety combinations. */
362
372
  function parseDecision(text) {
363
- const value = JSON.parse(text);
373
+ let value;
374
+ try {
375
+ value = JSON.parse(text);
376
+ } catch (error) {
377
+ throw new ReviewerJsonError("auto-review: reviewer output must be valid JSON", { cause: error });
378
+ }
364
379
  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("auto-review: reviewer output must be one JSON object");
365
380
  const record = value;
366
381
  const keys = Object.keys(record);
@@ -404,7 +419,7 @@ async function readDecision(stream) {
404
419
  if (final?.type !== "text" || blocks.slice(0, -1).some((block) => block.type !== "reasoning")) throw new Error("auto-review: reviewer must emit zero or more reasoning blocks followed by exactly one text block");
405
420
  return parseDecision(final.text);
406
421
  }
407
- /** Review one frozen pending action with the fixed policy and current LLM route. */
422
+ /** Review one frozen action; retry JSON syntax failures within the configured limit. */
408
423
  async function classifyRisk(ctx, agent, exec, signal, config) {
409
424
  const snapshot = snapshotAutoReview(agent, exec);
410
425
  const options = deepFreeze({
@@ -421,7 +436,17 @@ async function classifyRisk(ctx, agent, exec, signal, config) {
421
436
  ...config.temperature === "provider-default" ? {} : { temperature: config.temperature },
422
437
  signal
423
438
  });
424
- return readDecision(ctx.llm.stream(options));
439
+ for (let retries = 0;; retries += 1) {
440
+ const request = retries === 0 ? options : deepFreeze({
441
+ ...options,
442
+ system: `${REVIEW_POLICY}\n\n${JSON_RETRY_REMINDER}`
443
+ });
444
+ try {
445
+ return await readDecision(ctx.llm.stream(request));
446
+ } catch (error) {
447
+ if (!(error instanceof ReviewerJsonError) || retries >= config.maxJsonRetries || signal.aborted) throw error;
448
+ }
449
+ }
425
450
  }
426
451
  /** Materialize the fixed model-facing final Auto denial plus optional UI detail. */
427
452
  function denied(exec, reason) {
@@ -198,6 +198,17 @@ function matchesNameGlob(name, glob) {
198
198
  return new RegExp(`^${pattern}$`, "iu").test(name);
199
199
  }
200
200
  /**
201
+ * Whether the canonical file name of `path` matches a hidden-name glob of
202
+ * `scope`, so a symlink cannot rename a hidden target into view.
203
+ * @param path - the host path a reader is about to open or search.
204
+ * @param scope - the read scope from `SandboxProvider.readScope`.
205
+ * @returns true when the path is hidden regardless of its root.
206
+ */
207
+ function isHiddenIn(path, scope) {
208
+ const name = basename(canonicalTarget(path));
209
+ return scope.hiddenNames.some((glob) => matchesNameGlob(name, glob));
210
+ }
211
+ /**
201
212
  * Whether `path` is readable within `scope`: it lies inside a root after both
202
213
  * are canonicalized (so neither `..` nor a symlink can leave the roots), and
203
214
  * its file name matches no hidden-name glob.
@@ -206,8 +217,8 @@ function matchesNameGlob(name, glob) {
206
217
  * @returns true when the path may be read.
207
218
  */
208
219
  function isReadableIn(path, scope) {
220
+ if (isHiddenIn(path, scope)) return false;
209
221
  const target = canonicalTarget(path);
210
- if (scope.hiddenNames.some((glob) => matchesNameGlob(basename(target), glob))) return false;
211
222
  return scope.roots.some((root) => {
212
223
  const canonicalRoot = canonicalTarget(root);
213
224
  return target === canonicalRoot || target.startsWith(canonicalRoot.endsWith(sep) ? canonicalRoot : `${canonicalRoot}${sep}`);
@@ -341,4 +352,4 @@ var SandboxProvider = class extends Service {
341
352
  readScope(_policy) {}
342
353
  };
343
354
  //#endregion
344
- export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, classifyRunnerFailure, escalationHintMarker, isReadableIn, isRunnerSpawnFailure, matchesNameGlob, matchesSignature, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs, writableRoots };
355
+ export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, classifyRunnerFailure, escalationHintMarker, isHiddenIn, isReadableIn, isRunnerSpawnFailure, matchesNameGlob, matchesSignature, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs, writableRoots };
@@ -27,8 +27,8 @@
27
27
  en: fe0f7d5ac6160763
28
28
  zh: 4e1455a8559d46ca
29
29
  /deepseek-ai-dsh-sandbox-apple-container/use-this-package/what-confinement-covers:
30
- en: db58fc9ee37b3ac9
31
- zh: c4d7f44c9209a61e
30
+ en: 48bdafd0dee1a723
31
+ zh: a6a0ab45272bdc4f
32
32
  /deepseek-ai-dsh-sandbox-apple-container/use-this-package/failures-and-recovery:
33
33
  en: 79782500f91b1f06
34
34
  zh: a132d680acb85edc
@@ -67,7 +67,7 @@ The fields of `@deepseek-ai/dsh-sandbox-local` also apply to the `local` backend
67
67
  | Threat | Behavior under the container backend |
68
68
  |---|---|
69
69
  | A command reads host files outside the workspace | The path does not exist in the guest |
70
- | A file tool reads outside the workspace | `read`, `edit`, `write`, `str_replace_editor`, `grep`, and `glob` refuse it through the read scope |
70
+ | A file tool reads outside the workspace | `read` and `read_image` ask the user once per call before any host file access; `edit`, `write`, `str_replace_editor`, `grep`, and `glob` refuse it through the read scope |
71
71
  | A command or tool reads a secret file in the workspace | Masked to `/dev/null` in the guest; refused by file tools; excluded from `grep` |
72
72
  | A credential reaches the guest environment | Denied names and URLs carrying `user:password@` are never forwarded |
73
73
  | A command plants a Git hook or config the host later runs | `.git` is read-only under `workspace-write`; writes fail with `Read-only file system` and use the normal escalation |
@@ -132,7 +132,7 @@ One `sandbox:backend` contribution in the runtime-context snapshot when the sess
132
132
  ##### Container backend
133
133
 
134
134
  ```markdown
135
- Commands confined by the DSH file sandbox run inside a Linux container from image <image>. Only the session workspace <workspace root> is shared with the host; files written elsewhere stay inside the container and are not visible to file tools. File tools cannot read host paths outside the workspace, and secret files such as `.env` and private keys are hidden from commands and file tools.
135
+ Commands confined by the DSH file sandbox run inside a Linux container from image <image>. Only the session workspace <workspace root> is shared with the host; files written elsewhere stay inside the container and are not visible to file tools. File tools ask the user before reading a host path outside the workspace; secret files such as `.env` and private keys stay hidden from commands and file tools.
136
136
  ```
137
137
 
138
138
  #### Token effect
@@ -67,7 +67,7 @@ kind: "package-reference"
67
67
  | 威胁 | container 后端下的行为 |
68
68
  |---|---|
69
69
  | 命令读取工作区之外的宿主机文件 | 该路径在客户机中不存在 |
70
- | 文件工具读取工作区之外的内容 | `read`、`edit`、`write`、`str_replace_editor`、`grep` 与 `glob` 通过读取范围拒绝 |
70
+ | 文件工具读取工作区之外的内容 | `read` 与 `read_image` 在访问任何宿主机文件之前,每次调用都会先征求用户同意;`edit`、`write`、`str_replace_editor`、`grep` 与 `glob` 通过读取范围拒绝 |
71
71
  | 命令或工具读取工作区中的密钥文件 | 在客户机中被遮蔽为 `/dev/null`;被文件工具拒绝;从 `grep` 中排除 |
72
72
  | 凭据进入客户机环境 | 被拒绝的名称以及带有 `user:password@` 的 URL 永不转发 |
73
73
  | 命令植入宿主机之后会执行的 Git hook 或配置 | 在 `workspace-write` 下 `.git` 为只读;写入以 `Read-only file system` 失败,并走常规提权流程 |
@@ -132,7 +132,7 @@ CLI 缺失、已停止且无法启动的 API 服务器,或 `container run` 失
132
132
  ##### container 后端
133
133
 
134
134
  ```markdown
135
- Commands confined by the DSH file sandbox run inside a Linux container from image <image>. Only the session workspace <workspace root> is shared with the host; files written elsewhere stay inside the container and are not visible to file tools. File tools cannot read host paths outside the workspace, and secret files such as `.env` and private keys are hidden from commands and file tools.
135
+ Commands confined by the DSH file sandbox run inside a Linux container from image <image>. Only the session workspace <workspace root> is shared with the host; files written elsewhere stay inside the container and are not visible to file tools. File tools ask the user before reading a host path outside the workspace; secret files such as `.env` and private keys stay hidden from commands and file tools.
136
136
  ```
137
137
 
138
138
  #### Token 影响
@@ -594,7 +594,7 @@ var AppleContainerSandboxProvider = class extends LocalSandboxProvider {
594
594
  if (session === void 0 || this.backendFor(session) !== "container") return "";
595
595
  const policy = scope.sandboxPolicy.resolve({ session });
596
596
  if (policy.mode === "danger-full-access") return "";
597
- return `Commands confined by the DSH file sandbox run inside a Linux container from image ${JSON.stringify(this.image)}. Only the session workspace ${JSON.stringify(policy.workspaceRoot)} is shared with the host; files written elsewhere stay inside the container and are not visible to file tools. File tools cannot read host paths outside the workspace, and secret files such as \`.env\` and private keys are hidden from commands and file tools.`;
597
+ return `Commands confined by the DSH file sandbox run inside a Linux container from image ${JSON.stringify(this.image)}. Only the session workspace ${JSON.stringify(policy.workspaceRoot)} is shared with the host; files written elsewhere stay inside the container and are not visible to file tools. File tools ask the user before reading a host path outside the workspace; secret files such as \`.env\` and private keys stay hidden from commands and file tools.`;
598
598
  }
599
599
  });
600
600
  });
@@ -27,8 +27,8 @@
27
27
  en: 7eb705e3b132fcba
28
28
  zh: 883207b13d381f9e
29
29
  /deepseek-ai-dsh-tool-fs/use-this-package/policy-and-sandbox-behavior:
30
- en: 97152a766158d6c1
31
- zh: 0bd315b51de3a8f8
30
+ en: c2204f715202afd1
31
+ zh: 89062d6b3e2b5c3c
32
32
  /deepseek-ai-dsh-tool-fs/use-this-package/failures-and-recovery:
33
33
  en: 962b09e21305a04b
34
34
  zh: 382d2b8cce217569
@@ -65,7 +65,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
65
65
 
66
66
  ### Policy and sandbox behavior
67
67
 
68
- Path authorization for `read` and `read_image` belongs to `ctx.fs`, narrowed by the sandbox read scope: when the mounted `ctx.sandbox` provider confines reads (the Apple container backend does), `read`, `read_image`, `edit`, and `write` refuse a path outside the scope or a hidden secret file with `FS_SANDBOX_DENIED` before observing it. Media-type declarations and file signatures only decide whether `read_image` accepts the bytes returned by that backend.
68
+ Path authorization for `read` and `read_image` belongs to `ctx.fs`, narrowed by the sandbox read scope: when the mounted `ctx.sandbox` provider confines reads (the Apple container backend does), `read`, `read_image`, `edit`, and `write` refuse a hidden secret file with `FS_SANDBOX_DENIED` before observing it. For any other path outside the scope, `read` and `read_image` ask the user through `ctx.approval`, and only an allowed-once answer lets that one call read it; the grant widens neither later reads nor confined commands. A path spelled outside the scope roots, or containing `..`, is asked about before any filesystem call; a workspace symlink leading outside is asked about after resolution. Rejection, cancellation, and a missing approval channel fail with `FS_SANDBOX_DENIED`. `edit` and `write` refuse outside paths unless a `danger-full-access` escalation applies. Media-type declarations and file signatures only decide whether `read_image` accepts the bytes returned by that backend.
69
69
 
70
70
  With the policy plugin mounted, `write` and `edit` obtain their guard from the `fs/*` intent slots, so an unread target or a stale observation fails with `FS_NOT_OBSERVED` or `FS_STALE_VERSION` and a recovery instruction. Under a confining backend (`fs-sandbox`), `write`/`edit` additionally advertise `sandbox_permissions` and `justification`; a denied mutation returns the `[sandbox: file access denied under <mode> mode]` marker with the same-turn escalation hint, and an approved retry may stamp a strictly wider mode for that one call. The justification asks the model to use the language of the current user request.
71
71
 
@@ -65,7 +65,7 @@ kind: "package-reference"
65
65
 
66
66
  ### 策略与沙箱行为
67
67
 
68
- `read` 与 `read_image` 的路径授权由 `ctx.fs` 负责,并受沙箱读取范围收窄:当挂载的 `ctx.sandbox` 提供方限制读取时(Apple container 后端即如此),`read`、`read_image`、`edit` 与 `write` 会在观察路径之前,以 `FS_SANDBOX_DENIED` 拒绝范围之外的路径或被隐藏的密钥文件。媒体类型声明和文件签名只决定 `read_image` 是否接受该后端返回的字节。
68
+ `read` 与 `read_image` 的路径授权由 `ctx.fs` 负责,并受沙箱读取范围收窄:当挂载的 `ctx.sandbox` 提供方限制读取时(Apple container 后端即如此),`read`、`read_image`、`edit` 与 `write` 会在观察路径之前,以 `FS_SANDBOX_DENIED` 拒绝被隐藏的密钥文件。对于范围之外的其他路径,`read` 与 `read_image` 会通过 `ctx.approval` 询问用户,只有“仅允许一次”的答复才允许该次调用读取它;该授权既不放宽后续读取,也不放宽受限命令。拼写在范围根目录之外或包含 `..` 的路径会在任何文件系统调用之前询问;通向外部的工作区符号链接则在解析之后询问。拒绝、取消和缺少审批通道都会以 `FS_SANDBOX_DENIED` 失败。除非应用了 `danger-full-access` 升级,`edit` 与 `write` 会拒绝外部路径。媒体类型声明和文件签名只决定 `read_image` 是否接受该后端返回的字节。
69
69
 
70
70
  挂载策略插件后,`write` 与 `edit` 从 `fs/*` 意图槽位取得防护,因此未读目标或陈旧观察会以 `FS_NOT_OBSERVED` 或 `FS_STALE_VERSION` 及恢复指令失败。使用施加沙箱限制的后端(`fs-sandbox`)时,`write`/`edit` 还会公开 `sandbox_permissions` 与 `justification`;被拒绝的变更返回 `[sandbox: file access denied under <mode> mode]` 标记与同轮次升级提示,获批的重试可以在该次调用中加盖严格更宽的模式。理由字段提示模型使用用户当前提问的语言。
71
71
 
@@ -2,10 +2,10 @@ import z from "@deepseek-ai/schemastery";
2
2
  import { defineTool } from "@deepseek-ai/dsh-tools";
3
3
  import { FsError } from "@deepseek-ai/dsh-fs";
4
4
  import { readLangHintForPath as langFromPath } from "@deepseek-ai/dsh-util-code-language";
5
+ import { basename, extname, isAbsolute, relative, resolve } from "node:path";
6
+ import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, isHiddenIn, isReadableIn, matchesNameGlob, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
5
7
  import { structuredPatch } from "diff";
6
- import { basename, extname } from "node:path";
7
8
  import { AttachmentError, AttachmentId } from "@deepseek-ai/dsh-attachment";
8
- import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
9
9
  //#region lib/types/read-render.js
10
10
  /**
11
11
  * Pure read presentation: turn provider-decoded text into a bounded, line-numbered window and
@@ -189,15 +189,16 @@ function sessionResolveOptions(exec, policyWorkspaceRoot) {
189
189
  //#endregion
190
190
  //#region lib/types/read-target.js
191
191
  /**
192
- * Shared path resolution and regular-file validation for model-facing read tools.
192
+ * Shared path resolution, sandbox read authorization, and regular-file
193
+ * validation for model-facing read tools.
193
194
  * @module @deepseek-ai/dsh-tool-fs/src/read-target
194
195
  */
195
196
  /**
196
197
  * Refuse a target the calling session's sandbox hides from reads: a path
197
- * outside the read scope of `ctx.sandbox`, or a hidden secret file. Tools
198
- * that read, edit, or overwrite (and so present) existing content call it
199
- * after resolution and before any stat, so a refusal reveals nothing about
200
- * the file.
198
+ * outside the read scope of `ctx.sandbox`, or a hidden secret file. `edit`
199
+ * and `write`, which present existing content, call it after resolution and
200
+ * before any stat, so a refusal reveals nothing about the file; reaching
201
+ * outside the workspace there takes a `danger-full-access` escalation.
201
202
  * @param ctx - the plugin context; reads are unconfined without `ctx.sandboxPolicy`.
202
203
  * @param exec - the current tool execution, supplying the session.
203
204
  * @param target - the resolved target.
@@ -213,16 +214,110 @@ function assertSandboxReadable(ctx, exec, target, mode) {
213
214
  })) return;
214
215
  throw new FsError(`cannot read "${target.displayPath}": the sandbox hides this path from this session`, "FS_SANDBOX_DENIED");
215
216
  }
217
+ /** The model-facing refusal for a path the sandbox read scope excludes. */
218
+ function hiddenMessage(displayPath) {
219
+ return `cannot read "${displayPath}": the sandbox hides this path from this session`;
220
+ }
221
+ /**
222
+ * Whether `path` lies under `root` by spelling alone. No filesystem call
223
+ * runs, so a path that only symlinks or `..` traversal would place under the
224
+ * root reads as outside.
225
+ */
226
+ function isLexicallyUnder(path, root) {
227
+ const rel = relative(root, path);
228
+ return rel === "" || !isAbsolute(rel) && rel.split(/[\\/]/u)[0] !== "..";
229
+ }
230
+ /**
231
+ * Ask the user once to let this call read a path outside the sandbox read
232
+ * scope. Only `allowed-once` returns; every other outcome, a missing approval
233
+ * service, and an agentless call throw before the path is read.
234
+ * @param ctx - the plugin context resolving the optional `approval` service.
235
+ * @param exec - the current tool execution, supplying the agent, call id, and signal.
236
+ * @param path - the host path shown to the user and recorded in the audit reason.
237
+ * @param displayPath - the path rendered in model-facing refusals.
238
+ * @param toolName - the reading tool's name, recorded on the approval request.
239
+ */
240
+ async function approveOutsideRead(ctx, exec, path, displayPath, toolName) {
241
+ const approval = ctx.get("approval");
242
+ const unavailable = `${hiddenMessage(displayPath)}, and no user approval is available to read it`;
243
+ if (approval === void 0 || exec.agent === void 0) throw new FsError(unavailable, "FS_SANDBOX_DENIED");
244
+ const outcome = await approval.request({
245
+ agent: exec.agent,
246
+ toolName,
247
+ callId: exec.callId,
248
+ reason: `read outside the sandbox read scope: ${path}`,
249
+ displayReason: {
250
+ en: `Allow reading this file outside the session workspace once: ${path}`,
251
+ zh: `允许本次读取会话工作区之外的文件:${path}`
252
+ },
253
+ signal: exec.signal
254
+ });
255
+ switch (outcome) {
256
+ case "allowed-once": return;
257
+ case "rejected": throw new FsError(`cannot read "${displayPath}": the user declined access to this path outside the session workspace; do not retry or work around it`, "FS_SANDBOX_DENIED");
258
+ case "cancelled": throw new FsError(`cannot read "${displayPath}": approval to read this path outside the session workspace was cancelled`, "FS_SANDBOX_DENIED");
259
+ case "unavailable": throw new FsError(unavailable, "FS_SANDBOX_DENIED");
260
+ /* v8 ignore next 4 -- ApprovalOutcome is a typed same-process closed union; this branch is only the static exhaustiveness guard. */
261
+ default: throw new Error(`unreachable approval outcome: ${String(outcome)}`);
262
+ }
263
+ }
264
+ /**
265
+ * Resolve a model-supplied path and authorize one read of it under the
266
+ * calling session's sandbox read scope. A path inside the scope reads without
267
+ * asking, and a hidden secret file is refused without asking. Any other path
268
+ * asks the user through `ctx.approval`; only `allowed-once` lets this one call
269
+ * read it, and the grant widens neither the session's read scope nor what
270
+ * confined commands can see.
271
+ *
272
+ * A path whose spelling leaves the scope roots, or that contains a `..`
273
+ * segment, is asked about before `ctx.fs.resolve` canonicalizes it, so the
274
+ * Harness makes no filesystem call on an external path the user has not
275
+ * approved. A path spelled inside the roots resolves first; when its
276
+ * canonical identity leaves the scope (a symlink in the workspace), the ask
277
+ * follows resolution. Either way the hidden-name check repeats on the
278
+ * canonical path, and the ask precedes every stat and read.
279
+ * @param ctx - the plugin context; reads are unconfined without `ctx.sandboxPolicy`.
280
+ * @param exec - the current tool execution, supplying the session, agent, call id, and signal.
281
+ * @param requestedPath - the raw path supplied to the tool.
282
+ * @param toolName - the reading tool's name, recorded on the approval request.
283
+ * @returns the resolved target, authorized for this call.
284
+ * @throws {FsError} `FS_SANDBOX_DENIED` when the path is hidden, the user does
285
+ * not grant the outside read, or no approval channel can ask.
286
+ */
287
+ async function resolveAuthorizedReadTarget(ctx, exec, requestedPath, toolName) {
288
+ const options = sessionResolveOptions(exec);
289
+ const policy = ctx.get("sandboxPolicy");
290
+ const session = exec.agent?.session;
291
+ const request = session === void 0 ? {} : { session };
292
+ const scope = policy?.readScope(request);
293
+ if (policy === void 0 || scope === void 0) return ctx.fs.resolve(requestedPath, options);
294
+ const spelled = resolve(options.cwd ?? policy.resolve(request).workspaceRoot, requestedPath);
295
+ const spelledInside = !requestedPath.split(/[\\/]/u).includes("..") && scope.roots.some((root) => isLexicallyUnder(spelled, root));
296
+ let approved = false;
297
+ if (!spelledInside) {
298
+ if (scope.hiddenNames.some((glob) => matchesNameGlob(basename(spelled), glob))) throw new FsError(hiddenMessage(requestedPath), "FS_SANDBOX_DENIED");
299
+ await approveOutsideRead(ctx, exec, spelled, requestedPath, toolName);
300
+ approved = true;
301
+ }
302
+ const target = await ctx.fs.resolve(requestedPath, options);
303
+ const path = ctx.fs.processPath(target);
304
+ if (isReadableIn(path, scope)) return target;
305
+ if (isHiddenIn(path, scope)) throw new FsError(hiddenMessage(target.displayPath), "FS_SANDBOX_DENIED");
306
+ if (!approved) await approveOutsideRead(ctx, exec, path, target.displayPath, toolName);
307
+ return target;
308
+ }
216
309
  /**
217
- * Resolve a model-supplied path, observe absence, and require a regular file.
310
+ * Resolve and authorize a model-supplied path (see
311
+ * {@link resolveAuthorizedReadTarget}), observe absence, and require a
312
+ * regular file.
218
313
  * @param ctx - the plugin context providing filesystem resolution and observation events.
219
314
  * @param exec - the current tool execution, including session cwd and cancellation.
220
315
  * @param requestedPath - the raw path supplied to the tool.
316
+ * @param toolName - the reading tool's name, recorded on an approval request.
221
317
  * @returns the resolved target and its single stat result.
222
318
  */
223
- async function resolveRegularReadTarget(ctx, exec, requestedPath) {
224
- const target = await ctx.fs.resolve(requestedPath, sessionResolveOptions(exec));
225
- assertSandboxReadable(ctx, exec, target);
319
+ async function resolveRegularReadTarget(ctx, exec, requestedPath, toolName) {
320
+ const target = await resolveAuthorizedReadTarget(ctx, exec, requestedPath, toolName);
226
321
  const info = await ctx.fs.stat(target, exec.signal);
227
322
  if (info === void 0) {
228
323
  ctx.emit("fs/observed", target, { kind: "absent" }, exec);
@@ -366,7 +461,7 @@ function applyReadTool(ctx, caps) {
366
461
  isConcurrencySafe: () => true,
367
462
  async execute(args, exec) {
368
463
  const input = parseReadArgs(args, caps.limit);
369
- const { target, info } = await resolveRegularReadTarget(ctx, exec, input.filePath);
464
+ const { target, info } = await resolveRegularReadTarget(ctx, exec, input.filePath, "read");
370
465
  const window = await buildWindow(info.size === void 0 || info.size >= caps.streamMinSize ? await ctx.fs.streamText(target, exec.signal) : [await ctx.fs.readText(target, exec.signal)], {
371
466
  offset: input.offset,
372
467
  limit: input.limit,
@@ -1043,7 +1138,7 @@ function applyReadImageTool(ctx) {
1043
1138
  if (attachments === void 0) throw new Error(`cannot read "${args.file_path}" as an image: no attachment service is mounted`);
1044
1139
  if (declared !== void 0) assertDeploymentAccepts(attachments, declared, args.file_path);
1045
1140
  await assertImageCapableRoute(ctx, exec, args.file_path);
1046
- const { target, info } = await resolveRegularReadTarget(ctx, exec, args.file_path);
1141
+ const { target, info } = await resolveRegularReadTarget(ctx, exec, args.file_path, "read_image");
1047
1142
  const byteCap = Math.min(attachments.imageLimits.maxImageBytes, attachments.imageLimits.maxMessageImageBytes);
1048
1143
  const data = await ctx.fs.readBytes(target, exec.signal, byteCap);
1049
1144
  const mediaType = declared ?? sniffImageMediaType(data);
@@ -21,11 +21,11 @@
21
21
  en: be0e9f07314547a5
22
22
  zh: e55e8e668b3f703f
23
23
  /deepseek-ai-dsh-tui-app/use-this-package/the-screen:
24
- en: 72239fe0910bcdd9
25
- zh: 340ecc0b963e1df6
24
+ en: 213c25fabac4f8ac
25
+ zh: 22116a7ed4c12964
26
26
  /deepseek-ai-dsh-tui-app/use-this-package/keys-and-commands:
27
- en: 3a651c81edcb2222
28
- zh: 435b1962a6ec9700
27
+ en: 4b81a1e381bbdea0
28
+ zh: d9eb5777b342c23f
29
29
  /deepseek-ai-dsh-tui-app/use-this-package/background-tool-calls:
30
30
  en: 322ae3c6d76383ec
31
31
  zh: 8c38eee4b57ed8dd
@@ -39,8 +39,8 @@
39
39
  en: 23ba736da2686f52
40
40
  zh: d30ce253dd934750
41
41
  /deepseek-ai-dsh-tui-app/use-this-package/configuration:
42
- en: 8d0892cbaf2caa7b
43
- zh: b824f3aa896161b4
42
+ en: f333f22f997c927e
43
+ zh: 35adeca2a4b12e15
44
44
  /deepseek-ai-dsh-tui-app/understand-the-implementation:
45
45
  en: f124d406565fef39
46
46
  zh: 90344b5eec319cad
@@ -54,8 +54,8 @@
54
54
  en: 142f04bf29e981dd
55
55
  zh: a1689297b06c9ca6
56
56
  /deepseek-ai-dsh-tui-app/understand-the-implementation/source-map:
57
- en: 872f627af74722f0
58
- zh: bc844b20ee2f49f7
57
+ en: 0dc1cf4197c715ab
58
+ zh: 052f74af12f5afc7
59
59
  /deepseek-ai-dsh-tui-app/understand-the-implementation/invariant-ownership:
60
60
  en: 0ddf6de8928026d5
61
61
  zh: 24feedcbb9e9d676