@songtonyli/dsh-cli 0.1.60 → 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 +4 -4
  19. package/node_modules/@deepseek-ai/dsh-tui-app/README.md +6 -9
  20. package/node_modules/@deepseek-ai/dsh-tui-app/README.zh.md +6 -9
  21. package/node_modules/@deepseek-ai/dsh-tui-app/lib/index.js +533 -820
  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.60; `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.60 (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-b920c06` + ({}.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,8 +21,8 @@
21
21
  en: be0e9f07314547a5
22
22
  zh: e55e8e668b3f703f
23
23
  /deepseek-ai-dsh-tui-app/use-this-package/the-screen:
24
- en: 64fe4edd6c2977ce
25
- zh: 6117e895e3ab9d66
24
+ en: 213c25fabac4f8ac
25
+ zh: 22116a7ed4c12964
26
26
  /deepseek-ai-dsh-tui-app/use-this-package/keys-and-commands:
27
27
  en: 4b81a1e381bbdea0
28
28
  zh: d9eb5777b342c23f
@@ -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: 669f3f5ebc7bd9d7
58
- zh: 95d0e12122478042
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
@@ -40,9 +40,7 @@ On quit the app prints `dsh: session <id> saved; resume with: dsh --profile tui
40
40
 
41
41
  ### The screen
42
42
 
43
- Every frame is drawn one column in from each edge of the terminal, so no line of the conversation or of the docked chrome touches either side. The header names the session by its title once one is generated or set, with the id beside it. The transcript grows in the terminal's own scrollback: your prompts start with `❯` on a tinted full-width band while colour is on (attachments listed under them), and a prompt steered or injected into a turn that already had a model step draws dim on a darker band so it recedes behind the turn it joined, assistant reasoning is dim italic under a `✻ Thinking` header above the Markdown reply, and each tool call is a card with a status glyph — a yellow spinner in the tool family's animation while it runs, a green `◆` once done, a red `◆` on failure — the bold tool name, the presenter headline in violet — without the tool name a presenter repeated, so `Read src/app.ts` draws as `read src/app.ts`, and for a shell card the call's own summary, never the command, which the card draws once as its `$` row — a loading row while it runs, and a body folded to `toolPreviewLines` rows. The card appears when the model starts the call, its header first and its rows unrolling beneath it over about `toolRevealFrames` frames; the result rows unroll and float out the same way when the tool answers. An `edit` or `write` diff card fills each added row edge to edge with a green background and each removed row with a red one, the removed rows above the added ones, and paints the `+` and `-` in their own lighter colour so each sign reads against the fill rather than in it; a wrapped row carries the fill on without a second sign; once the tool applied the change, the applied hunks replace the diff the call carried and lead every row with its file line number, the new file's for added and unchanged rows and the old file's for removed rows. A `subagent` or `subagent_*` card draws folded as one row behind the same status glyph, spinning while it runs and a dim `◆` for a child handed to the background: while it runs, the tool name, the task description, and the requested model and `background` when the call names them; once settled, the description dimmed with `[done]`, `[started]` for a child handed to the background, or `[failed]` at the right edge. `Space` on the marked row, or `Ctrl+O`, unfolds the full card. A nonempty system prompt and each injected context — instructions, catalogs, snapshots, notices, relays, and recalls — draw as a dim `⬡` title over the first `contextPreviewLines` rows of their model-facing text, with each snapshot contribution named above its own rows; an empty system prompt is omitted. A compaction, from `/compact` or automatic, draws as one context block whose accent `⬡` title names its origin and the estimated tokens it replaced and its summary costs, as in `context compacted by /compact · ~6.4k → ~0.9k tokens` or `context compacted automatically in turn 12 · …`; under the title, `compressed` names the item count and turns the summary replaced, each prompt among them (five at most, one row each), and a count of the replies, tool results by tool, context blocks, and earlier summaries, and `preserved` names the system prompt and what each later turn still holds verbatim; both stay drawn while the summary under them folds to `contextPreviewLines` rows like any context block. The checkpoint message itself is not drawn again. A `/compact` attempt the log closes with an error prints `/compact failed · <error>` when the session is redrawn, since the live command reports its own failure; a failed automatic attempt changes nothing and draws nothing, as in the browser. A tool card and a context block that carry more rows than they draw end on one marker: `… <n> more rows · Space expands` while the conversation's focus holds that block, and `… <n> more rows · Ctrl+O expands` otherwise. Fenced code in a reply, the file rows of a `read` card, the changed rows of an `edit` or `write` diff card — with `+` additions marked green, `-` removals red, and source text behind those signs drawn in the language the file's extension names — and the shell command of a `!` / `!!` draft, a `$ command` user-shell row (its `$` in the accent colour), and a terminal tool card, use syntax colours from a theme the terminal's own background picks, light or dark; the grammar of a language loads on the first block that asks for it, so that block draws plain and is repainted in colour a moment later, and a language with no grammar here, a terminal that reports neither 24-bit nor 256 colours, and `codeHighlight: false` each draw every block plain. Headings and list markers use warm orange, links and inline code use violet, and quotes stay dim. Streamed reasoning, reply text, and tool arguments are queued as they arrive and drawn a share per frame, about 60 frames per second by default, so a network burst spreads over `streamPaceFrames` frames instead of landing at once, and the queue never holds the model call back. Streamed reply text fades in and every word keeps its own clock: a word enters near the terminal's background color and brightens to the color it settles in over `streamFadeSteps` ticks of `streamFadeStepMs` each, so a fast stream leaves a longer trail of brightening words rather than a darker one. Streamed reasoning and a tool card float out over the same duration: they appear at a lifted color and recede to the dim italic or palette colors they settle in; a card redrawn from persisted history carries no fade, and text that has settled is never dimmed again.
44
-
45
- Once the newest prompt of the session on screen has scrolled above the terminal, a bar on the terminal's first row, tinted while colour is on, names it: `❯` and the prompt collapsed to one line, ellipsized to the width between the margins, as the reader pins it over a scrolled turn. The bar covers the conversation row beneath it rather than taking a row of its own, and never reaches your scrollback: that row is written back before the terminal scrolls it away. It disappears once the prompt is back in view, never covers the header or the docked chrome, and stays on the terminal's first row when what is drawn below it gets shorter, as when a turn ends and the working spinner goes away.
43
+ Every frame is drawn one column in from each edge of the terminal, so no line of the conversation or of the docked chrome touches either side. The header names the session by its title once one is generated or set, with the id beside it. The transcript grows in the terminal's own scrollback: your prompts start with `❯` on a tinted full-width band while colour is on (attachments listed under them), and a prompt steered or injected into a turn that already had a model step draws dim on a darker band so it recedes behind the turn it joined, assistant reasoning is dim italic under a `✻ Thinking` header above the Markdown reply, and each tool call is a card with a status glyph — a yellow blooming-star spinner while it runs, a green `◆` once done, a red `◆` on failure — the bold tool name, the presenter headline in violet — without the tool name a presenter repeated, so `Read src/app.ts` draws as `read src/app.ts`, and for a shell card the call's own summary, never the command, which the card draws once as its `$` row — a loading row while it runs, and a body folded to `toolPreviewLines` rows. The card appears when the model starts the call, its header first and its rows unrolling beneath it over about `toolRevealFrames` frames; the result rows unroll and float out the same way when the tool answers. An `edit` or `write` diff card fills each added row edge to edge with a green background and each removed row with a red one, the removed rows above the added ones, and paints the `+` and `-` in their own lighter colour so each sign reads against the fill rather than in it; a wrapped row carries the fill on without a second sign; once the tool applied the change, the applied hunks replace the diff the call carried and lead every row with its file line number, the new file's for added and unchanged rows and the old file's for removed rows. A `subagent` or `subagent_*` card draws folded as one row behind the same status glyph, spinning while it runs and a dim `◆` for a child handed to the background: while it runs, the tool name, the task description, and the requested model and `background` when the call names them; once settled, the description dimmed with `[done]`, `[started]` for a child handed to the background, or `[failed]` at the right edge. `Space` on the marked row, or `Ctrl+O`, unfolds the full card. A nonempty system prompt and each injected context — instructions, catalogs, snapshots, notices, relays, and recalls — draw as a dim `⬡` title over the first `contextPreviewLines` rows of their model-facing text, with each snapshot contribution named above its own rows; an empty system prompt is omitted. A compaction, from `/compact` or automatic, draws as one context block whose accent `⬡` title names its origin and the estimated tokens it replaced and its summary costs, as in `context compacted by /compact · ~6.4k → ~0.9k tokens` or `context compacted automatically in turn 12 · …`; under the title, `compressed` names the item count and turns the summary replaced, each prompt among them (five at most, one row each), and a count of the replies, tool results by tool, context blocks, and earlier summaries, and `preserved` names the system prompt and what each later turn still holds verbatim; both stay drawn while the summary under them folds to `contextPreviewLines` rows like any context block. The checkpoint message itself is not drawn again. A `/compact` attempt the log closes with an error prints `/compact failed · <error>` when the session is redrawn, since the live command reports its own failure; a failed automatic attempt changes nothing and draws nothing, as in the browser. A tool card and a context block that carry more rows than they draw end on one marker: `… <n> more rows · Space expands` while the conversation's focus holds that block, and `… <n> more rows · Ctrl+O expands` otherwise. Fenced code in a reply, the file rows of a `read` card, the changed rows of an `edit` or `write` diff card — with `+` additions marked green, `-` removals red, and source text behind those signs drawn in the language the file's extension names — and the shell command of a `!` / `!!` draft, a `$ command` user-shell row (its `$` in the accent colour), and a terminal tool card, use syntax colours from a theme the terminal's own background picks, light or dark; the grammar of a language loads on the first block that asks for it, so that block draws plain and is repainted in colour a moment later, and a language with no grammar here, a terminal that reports neither 24-bit nor 256 colours, and `codeHighlight: false` each draw every block plain. Headings and list markers use warm orange, links and inline code use violet, and quotes stay dim. Streamed reasoning, reply text, and tool arguments are queued as they arrive and drawn a share per frame, about 60 frames per second by default, so a network burst spreads over `streamPaceFrames` frames instead of landing at once, and the queue never holds the model call back. Streamed reply text fades in and every word keeps its own clock: a word enters near the terminal's background color and brightens to the color it settles in over `streamFadeSteps` ticks of `streamFadeStepMs` each, so a fast stream leaves a longer trail of brightening words rather than a darker one. Streamed reasoning and a tool card float out over the same duration: they appear at a lifted color and recede to the dim italic or palette colors they settle in; a card redrawn from persisted history carries no fade, and text that has settled is never dimmed again.
46
44
 
47
45
  Below the transcript sit a spinner while the agent works — `thinking`, `writing`, `calling <tool>`, a retry, or `compacting`, each beside its own braille animation: circling dots, filling lines, an orbiting dot, a sliding bar, or a settling cell — with a bright highlight sweeping across the word, plus live `↑` send and `↓` receive tokens for the current model call, as compact `k` / `M` / `B` counts, growing as the stream arrives and settling on the provider usage chunk — any open prompt, a boxed follow-ups list while messages wait, an activity board of the open turn's todos and latest descendant line while either has a row — completed todo content scratched out and status glyphs colored green, yellow, or cyan, the in-progress one a spinner, at most four todo rows then `+<n> more`, not a focus region, gone on `turn/end` and bind — the editor, the subagent panel, and the footer: a status bar that, unfocused, is one line built from both ends inward. The editor's caret is the terminal's own blinking bar: the app asks for that shape at start, gives your default back on quit, and draws no caret at all while the status bar or the panel holds the keyboard. The model and entry keys are colored; live turn, context, and todo facts use yellow, violet, and green. The model is anchored at the left edge and is never dropped — past 20 columns it falls back to the bare model name, and only a label still too wide for that is ellipsized — and the two keys that leave the input are anchored at the right edge as `Shift+↑ read · Shift+↓ status`, or `Shift+↑ select · Shift+↓ status` while follow-ups wait, narrowing to `Shift+↑↓ nav` and dropped below 40 columns. The key facts fill whatever middle is left, in bar order: effort (`effort default` when the selection leaves reasoning to the model), the running turn's elapsed time, the context window percentage, the todo counts, and the workspace path (shortened with `~` and `…/` when long). Every segment that middle cannot hold folds into a trailing `+N`, together with the segments the unfocused line never draws — the permission preset, token usage (session totals plus the in-flight call), the goal and plan-mode markers from the projection seam, and the count of pending attachments. Model-request retries appear as notices, the same facts the browser's markers carry.
48
46
 
@@ -54,7 +52,7 @@ The focused block is also marked where it stands, with a two-column gutter that
54
52
 
55
53
  Transient key feedback floats as a dim framed line in the top-right corner of the viewport: `press Esc again to stop turn <n>`, `press Ctrl+C again to quit`, and `nothing in the transcript to read yet`. It holds at full strength for `toastMs`, fades out, costs the conversation no row of its own, and takes no keyboard; where the renderer can no longer repaint the top of the viewport it is printed into the conversation instead, which keeps it. Facts worth keeping are notices in the conversation: `stopping the turn…`, `wait for the session switch to finish`, `above the repaint window · opened in the reader`, and every command result.
56
54
 
57
- Motion reaches past streamed text: every lift and float rides the same fade tick, and every working animation one spinner tick. The keyboard landing on the conversation, the subagent panel, or the status bar lifts that surface's frame, its chip, and the mark it holds for twelve ticks of `streamFadeStepMs`; a step of the conversation walk lifts the newly focused gutter for six; and a step along the bar lifts the selected label for eight. A new or status-changed activity-board todo row, and a replaced descendant line, float out on the fade tick the same way a tool card does; replay and `reducedMotion` draw the settled board. Every working animation has eight frames, takes the one it draws from the clock, and steps on the spinner tick of `spinnerMs`, 100 ms by default, so everything that spins advances at the same instant and speed, a label change keeps the beat, and the tick is armed only while one of them is drawn. The working spinner alone draws braille, its animation following its status, so it never repeats a card's glyph. Running tool cards cycle their family's glyphs — commands turn a block, edits set a diamond, reads focus a lens, delegation turns a pointer, plan tools raise a bar, waits on an answer breathe a shade, and tools with no family bloom a star — folded subagent rows turn that pointer, and the in-progress todo raises the plan tools' bar. No two families share a glyph, and an indicator that starts while others of its family spin takes a phase at which it never draws their glyph at the same instant; the diamond, bar, and shade, whose frames repeat, manage that for at most two spinning together. A card whose header has scrolled above the part of the screen the renderer can repaint draws the static `◆` from then on, and `reducedMotion` draws every one of them still — the card's `◆`, the todo's `▸`, and the working spinner's label without a glyph — with no spinner tick. The reader arrives complete on the screen it owns, and what it newly shows floats out on the fade tick the way a tool card does: opening it and showing another turn float out the whole turn, and stepping the list to another section of the same turn floats out that section, over `streamFadeSteps` ticks; scrolling, live growth, and a rewrap float nothing out. No lift changes how many lines anything draws, and `reducedMotion` — like `NO_COLOR`, a disabled palette, and `TERM=dumb` — turns every lift and float off and arms no repaint for them.
55
+ Motion reaches past streamed text: every lift and float rides the same fade tick, and every working animation one spinner tick. The keyboard landing on the conversation, the subagent panel, or the status bar lifts that surface's frame, its chip, and the mark it holds for twelve ticks of `streamFadeStepMs`; a step of the conversation walk lifts the newly focused gutter for six; and a step along the bar lifts the selected label for eight. A new or status-changed activity-board todo row, and a replaced descendant line, float out on the fade tick the same way a tool card does; replay and `reducedMotion` draw the settled board. Every working animation has eight frames, takes the one it draws from the clock, and steps on the spinner tick of `spinnerMs`, 100 ms by default, so everything that spins advances at the same instant and speed, a label change keeps the beat, and the tick is armed only while one of them is drawn. The working spinner alone draws braille, its animation following its status, so it never repeats a card's glyph. Every running tool card, folded subagent row, and in-progress todo row draws one animation whatever the tool, a star blooming from `✧` to `✻`. An indicator that starts while others spin takes a phase at which it never draws their glyph at the same instant, for up to eight spinning together; beyond eight, it takes the phase the fewest indicators hold. A card whose header has scrolled above the part of the screen the renderer can repaint draws the static `◆` from then on, and `reducedMotion` draws every one of them still — the card's `◆`, the todo's `▸`, and the working spinner's label without a glyph — with no spinner tick. The reader arrives complete on the screen it owns, and what it newly shows floats out on the fade tick the way a tool card does: opening it and showing another turn float out the whole turn, and stepping the list to another section of the same turn floats out that section, over `streamFadeSteps` ticks; scrolling, live growth, and a rewrap float nothing out. No lift changes how many lines anything draws, and `reducedMotion` — like `NO_COLOR`, a disabled palette, and `TERM=dumb` — turns every lift and float off and arms no repaint for them.
58
56
 
59
57
  The subagent panel is drawn while a subagent session under the bound one is resident, or the listing carries a candidate it could not read. Unfocused it is one summary line with the listed count and the first child's key label; focused, its heading counts what it lists and ends on the keys it answers, `↑↓ children · Enter opens · Tab regions · Esc input`, narrowed to `↑↓ children · Esc input` and then to `Esc input` on a terminal that cannot hold them, and each row gives the child's depth indent, its label or id, its mode (`one-shot` or `continuable`), `resident`, whether its agent is `running` or `idle`, its elapsed time — the open turn's, else the total its settled turns took — and its token usage, as far as this process's own view of that child and the composed projections carry them. Six rows are drawn at most, with `+<n> more · /subagents lists them all` under them; a candidate the listing could not interpret draws as `unreadable: <reason>` and opens nothing, and a failed listing keeps the rows the last good one produced with `listing failed: <reason>` beneath. The panel disappears with its last row. `Enter` or `Right` on a readable row, like `Enter` on a readable `/subagents` row, opens that child as a subagent view: the terminal draws the child session in place of the bound one — its transcript, live stream, conversation walk, inspector, reader, and its own subagent panel — while the session it was entered from stays open. A resident child is read live, and any other is resumed. The entry's detail rows print as notices under `subagent <label> · Ctrl+P or /parent returns to session <id>`, the header ends on `◆ subagent view ›` with one `›` per level entered and `· Ctrl+P returns`, a shaded line directly above the input reads `◆ subagent view · main › <label> · Ctrl+P back to <parent>` for as long as the view is open, whatever the transcript has scrolled to, and `Ctrl+P` or `/parent` goes back one level, redrawing the parent from its log as it stands then. `/new`, `/clear`, `/resume`, `/sessions`, and `/fork` refuse while any session in that chain runs a turn, and otherwise release every view with the session they leave; quitting releases every view and saves the root session.
60
58
 
@@ -308,10 +306,10 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
308
306
  | [`src/fade.ts`](src/fade.ts) | The streamed-text fade: the wall-clock tail tracker, the block-fade clock and registry, the fade-in ramp, the float-out mix, and the recolor of rendered lines |
309
307
  | [`src/pace.ts`](src/pace.ts) | The stream pacer: the ordered queue between the assistant stream and the transcript, drained a backlog share per frame; and the row reveal that unrolls a tool card the same way |
310
308
  | [`src/motion.ts`](src/motion.ts) | The chrome motion clock and the three-level lift its call sites draw with: the landing, the section step, and the bar walk |
311
- | [`src/spinner.ts`](src/spinner.ts) | The working animations: the activity line's braille status animations, the tool-family animations of running cards and in-progress todos, the frame each draws at one instant, the phase that keeps indicators of one family apart, and the shimmer the activity label carries |
309
+ | [`src/spinner.ts`](src/spinner.ts) | The working animations: the activity line's braille status animations, the star animation of running cards, subagent rows, and in-progress todos, the frame each draws at one instant, the phase that keeps star indicators apart, and the shimmer the activity label carries |
312
310
  | [`src/prompts.ts`](src/prompts.ts) | Approval, question, picker, and read-only detail prompts plus the modal queue |
313
311
  | [`src/toast.ts`](src/toast.ts) | The transient key-feedback line: its overlay, its clock, and the lines it carries |
314
- | [`src/pinned-prompt.ts`](src/pinned-prompt.ts) | The pinned prompt: the one-row bar naming a prompt, when the main screen floats it and on which viewport row, the first row the terminal shows, and its overlay pane |
312
+ | [`src/pinned-prompt.ts`](src/pinned-prompt.ts) | The prompt row the reader pins over a scrolled turn: the glyph, the prompt collapsed to one line, and the band |
315
313
  | [`src/transcript.ts`](src/transcript.ts) | Pure text folding of presentation views, usage, and turn-end reasons, the `$ command` span, and the one fold grammar every marker is written in |
316
314
  | [`src/diff.ts`](src/diff.ts) | Line diff, hunk selection, and the addition and removal marks diff cards box |
317
315
  | [`src/style.ts`](src/style.ts) | The palette, including the cool dark-mode heading and link hues a Markdown reply uses, the strikethrough role completed todo content uses, the background band a prompt is drawn on and the darker one a steered or injected prompt is drawn on, the green and red fills and sign colours of a diff card's changed rows, whether key chips are clickable, and the derived pi-tui themes |
@@ -340,13 +338,12 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
340
338
  | [`tests/editor.spec.ts`](tests/editor.spec.ts) | The terminal caret, `Shift+Left` / `Shift+Right` word navigation, and `!` / `!!` draft colour against pi-tui's editor behavior |
341
339
  | [`tests/frame.spec.ts`](tests/frame.spec.ts) | The rules, the chip, the body rows, and the legend a width holds |
342
340
  | [`tests/motion.spec.ts`](tests/motion.spec.ts) | The motion clock's levels, its repaint demand, and the lift each level draws |
343
- | [`tests/spinner.spec.ts`](tests/spinner.spec.ts) | The animation sets (eight one-column frames, braille only on the activity line, disjoint tool families), tool and activity mapping, the wall-clock frame step, the phase stagger, and the shimmer's sweep, rest, and disabled-palette output |
341
+ | [`tests/spinner.spec.ts`](tests/spinner.spec.ts) | The animation sets (eight one-column frames, braille only on the activity line, eight different star frames), activity mapping, the wall-clock frame step, the phase stagger, and the shimmer's sweep, rest, and disabled-palette output |
344
342
  | [`tests/pace.spec.ts`](tests/pace.spec.ts) | The pacer's per-frame share, grapheme cuts, arrival order, flush, per-channel flush, and clear, and the row reveal's per-frame share, settle, and clamp |
345
343
  | [`tests/stream-pace.spec.ts`](tests/stream-pace.spec.ts) | Paced reply text and tool arguments in stream order, thinking drawn when its block ends, the flush at stream end and before a logged event, reduced motion, and tool cards unrolling on the frame tick |
346
344
  | [`tests/view-banner.spec.ts`](tests/view-banner.spec.ts) | The subagent-view line's trail, back target, width, and absence at the main session |
347
345
  | [`tests/toast.spec.ts`](tests/toast.spec.ts) | The transient line's box, its hold, its fade, and its early settlement |
348
- | [`tests/pinned-prompt.spec.ts`](tests/pinned-prompt.spec.ts) | The pinned row, when the main screen draws it and on which viewport row, the overlay layout, and the keys under the bar |
349
- | [`tests/pinned-prompt-app.spec.ts`](tests/pinned-prompt-app.spec.ts) | The pinned bar on the running main screen: when it shows and leaves, the prompt it follows, the first row it keeps when the frame shrinks or is redrawn in full, and the scrollback it never reaches |
346
+ | [`tests/pinned-prompt.spec.ts`](tests/pinned-prompt.spec.ts) | The prompt row the reader pins: the glyph, collapsed whitespace, the ellipsis, and the band |
350
347
  | [`tests/reader.spec.ts`](tests/reader.spec.ts) | The reader's geometry, its state machine, its filter, and the rows it returns |
351
348
  | [`tests/reader-screen.spec.ts`](tests/reader-screen.spec.ts) | The reader pane: its key map, the screen it fills, its re-anchoring, and its exit |
352
349
  | [`tests/alt-screen.spec.ts`](tests/alt-screen.spec.ts) | The alternate screen: its balanced switches, its per-row drawing, the rows a shorter frame clears, and the keys a paint keeps |