@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.
- package/README.md +1 -1
- package/bin/dsh.mjs +1 -1
- package/node_modules/@deepseek-ai/dsh-client-ui-primitives/package.json +2 -2
- package/node_modules/@deepseek-ai/dsh-client-ui-sidebar/lib/client.js +1 -1
- package/node_modules/@deepseek-ai/dsh-experimental-auto-review/README.i18n.yaml +4 -4
- package/node_modules/@deepseek-ai/dsh-experimental-auto-review/README.md +2 -2
- package/node_modules/@deepseek-ai/dsh-experimental-auto-review/README.zh.md +2 -2
- package/node_modules/@deepseek-ai/dsh-experimental-auto-review/lib/index.js +33 -8
- package/node_modules/@deepseek-ai/dsh-sandbox/lib/index.js +13 -2
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.i18n.yaml +2 -2
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.md +2 -2
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.zh.md +2 -2
- package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/lib/index.js +1 -1
- package/node_modules/@deepseek-ai/dsh-tool-fs/README.i18n.yaml +2 -2
- package/node_modules/@deepseek-ai/dsh-tool-fs/README.md +1 -1
- package/node_modules/@deepseek-ai/dsh-tool-fs/README.zh.md +1 -1
- package/node_modules/@deepseek-ai/dsh-tool-fs/lib/index.js +108 -13
- package/node_modules/@deepseek-ai/dsh-tui-app/README.i18n.yaml +4 -4
- package/node_modules/@deepseek-ai/dsh-tui-app/README.md +6 -9
- package/node_modules/@deepseek-ai/dsh-tui-app/README.zh.md +6 -9
- package/node_modules/@deepseek-ai/dsh-tui-app/lib/index.js +533 -820
- package/node_modules/@types/node/README.md +1 -1
- package/node_modules/@types/node/package.json +2 -2
- 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.
|
|
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.
|
|
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-
|
|
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:
|
|
43
|
-
zh:
|
|
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:
|
|
61
|
-
zh:
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
54
|
-
const Config = z.object({
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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:
|
|
31
|
-
zh:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
31
|
-
zh:
|
|
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
|
|
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`
|
|
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
|
|
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.
|
|
198
|
-
*
|
|
199
|
-
*
|
|
200
|
-
* the
|
|
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
|
|
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
|
|
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:
|
|
25
|
-
zh:
|
|
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:
|
|
58
|
-
zh:
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
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 |
|