diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
index a3e8c3ad8a..3c005a6deb 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
@@ -1,6 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write
-2026-07-19-package-owned-invariant-service.md: 2443a8f7d04b96f51bb798130078a7457f78b2a1
-2026-07-19-package-owned-invariant-service.zh.md: 3c71d3b7f99a507d4c0236b7ef6dc0794814cdc8
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
+2026-07-19-package-owned-invariant-service.md: e32efe9f6b3ce6b782c61db56d928e87c160dc9a
+2026-07-19-package-owned-invariant-service.zh.md: 60edaa3f6009acc516017683232ca0c07f64ec0d
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
index 2443a8f7d0..e32efe9f6b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-19-package-owned-invariant-service.zh.md)
Runtime invariant checks span session traces, agent state, scoped dispatch, and request reconstruction. Putting all checks in one diagnostics package makes that package import product vocabularies from unrelated domains, centralizes tests away from their owners, and requires the central package to change whenever a product package adds or removes a check.
-Deployments also need more than presence or absence of one plugin. A standard composition should carry the known invariant contributions while permitting a global off switch and package-selective diagnostics. Selection must remain stable when a package loads later or reloads under HMR, and disabled contributions must not allow two plugins to claim the same package name silently.
+Deployments that opt into diagnostics need more than presence or absence of one plugin. Such a composition carries the known invariant contributions while permitting a global off switch and package-selective diagnostics. Selection must remain stable when a package loads later or reloads under HMR, and disabled contributions must not allow two plugins to claim the same package name silently.
Package ownership must also be exhaustive. Without a mechanical repository rule, a new package can omit the companion, dependency, or publication wiring and remain invisible to diagnostics until a maintainer notices the gap.
@@ -72,9 +72,9 @@ These four owners supplied the initial stateful checks. The follow-up runtime-co
The generated scoped-event subject resolver lives in `dsh-scope`, beside the contract and invariant that consume it. `gen-scoped-events` uses the root TypeScript Program to enumerate `this: Scoped` bounded by `max-height: 320px` and `overflow-y: auto`, so a list taller than that scrolls vertically in place rather than growing the card ([source scroll](2026-08-03-web-search-source-scroll.md)). A source list is prose rather than column-aligned output, so it wraps normally instead of scrolling horizontally the way a terminal card's output does — that is the one deliberate divergence from TerminalBlock.
-The card is **resident** under the summary row in the chat rows, capped at `CHAT_WEB_MAX_SOURCES` (8) — half the primitive's own default of 16, which the details panel keeps — the same summary-surface-versus-reading-surface split `CHAT_TERMINAL_MAX_LINES` draws for the terminal card, and the same resident posture `BashRow` uses. The keyed rows register one `WebRow` component under both `web_search` and `web_fetch`; the row discriminates on the tool name only to pick its icon (search vs. browse) and its title (`Search`/`Fetch`). A web-declaring tool without its own keyed row lands on `GenericToolCard`, which grows the same resident card. The details panel renders the card at the primitive's full source allowance and, below it, the flattened model-visible result content: a `web_fetch` card carries only the URL and status, so its fetched body is readable only here.
+The card is **resident** under the summary row in the chat rows, the same resident posture `BashRow` uses. Both render sites show the same complete source list, bounded only by the card's own scroll height rather than by a row-versus-panel source cap. The keyed rows register one `WebRow` component under both `web_search` and `web_fetch`; the row discriminates on the tool name only to pick its icon (search vs. browse) and its title (`Search`/`Fetch`). A web-declaring tool without its own keyed row lands on `GenericToolCard`, which grows the same resident card. The details panel renders the card and, below it, the flattened model-visible result content: a `web_fetch` card carries only the URL and status, so its fetched body is readable only here.
## Consequences
@@ -36,14 +36,15 @@ A separate later PR unifies the whole-row collapse/expand interaction and will f
## Testing
-`packages/client/ui-primitives/tests/web-block.spec.tsx` pins the component per-file to the 100% gate: both kinds; the title-or-hostname-or-raw-URL label fallback; the safe-link attributes on both kinds (an http(s) URL becoming an external anchor with `target`/`rel`, a `javascript:`/`file:`/unparseable URL rendering as a plain span with no href); the snippet and date shown or omitted on present/empty/absent; the truncation indicator gated on the flag; and the source-list height cap with its head/tail slice and expand/collapse control including the default cap.
+`packages/client/ui-primitives/tests/web-block.spec.tsx` pins the component per-file to the 100% gate: both kinds; the title-or-hostname-or-raw-URL label fallback; the safe-link attributes on both kinds (an http(s) URL becoming an external anchor with `target`/`rel`, a `javascript:`/`file:`/unparseable URL rendering as a plain span with no href); the snippet and date shown or omitted on present/empty/absent; the truncation indicator gated on the flag; and the full source list rendering inside one scroll container with no expand control and `` numbering every source contiguously from 1.
-`packages/client/ui-conversation/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring seam: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds capped tighter than the panel, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-conversation/src/*`), so a coverage run measures none of it.
+`packages/client/ui-conversation/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring seam: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-conversation/src/*`), so a coverage run measures none of it.
The fixture (`packages/client/connection/src/client/fixture.ts`) adds turns 66 (`web_search`) and 67 (`web_fetch`), authored inline because the client-side fixture cannot import the web tool: turn 66's result view carries an answer and three sources exercising the citation list (a titled source with a snippet and date, a source with no title so its hostname labels the link, and a source with a date but no snippet) with the capped indicator on; turn 67's carries the fetched URL and a 200 status. Both keep a generic pending call view and add the `web` card only at result time, matching the contract's result-only web shape, and are named after the real tools so they hit the keyed `WebRow`. They are ordered before the todo turn (renumbered to 68) for the same reason the terminal turn is: the standing plan retires at the next `turn/start`, so a turn appended after it would empty the dock's plan strip. This drives the built-boot snapshot and a live `?fixture` server.
## Related
- [Web result card](2026-07-30-web-result-card.md) — the backend PR that added the `card: 'web'` result arm and made the two tools emit it; this is its deferred frontend consumer.
+- [Web search source card scrolls instead of collapsing](2026-08-03-web-search-source-scroll.md) — replaces this note's source-list head/tail collapse with a fixed-height scroll container and removes `CHAT_WEB_MAX_SOURCES` and the primitive's own source cap; every other decision here still holds.
- [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent this mirrors: a `ui-primitives` block, a single card-model derivation, keyed and fallback chat rows, and a details-panel arm, for the `terminal` render intent.
- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary; the Web client is now a full consumer of the `web` arm.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index ed95cbe39f..5fa53c4ecb 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -16,9 +16,9 @@ Status: implemented
**链接的安全性沿用 MarkdownText 对不受信任的 assistant 链接所用 allowlist 的 http(s) 子集。** MarkdownText 还允许 `mailto:`，此处刻意排除，因为检索 URL 绝不会是邮件地址。一个 source 或 fetch URL 仅当其协议为 `http:` 或 `https:` 时才成为可导航锚点，带 `target="_blank"` 和 `rel="noopener noreferrer"`；`javascript:`/`data:`/`file:`/`mailto:` URL 或无法解析的字符串渲染为纯文本、无 href。web 工具返回的 result content 是模型创作的,未经验证抵达本组件,因此像 assistant markdown 一样被当作不受信任处理。标签从标题回退到主机名再回退到原始 URL,因此即便标题缺失且 URL 无法解析,source 也总能读作某个东西。
-**几何镜像 CodeBlock/TerminalBlock**（12px 圆角、code-block 表面、16px 垂直外边距）,使 web 卡片与它们读作一家。长 source 列表在 `maxSources` 处折叠,用 TerminalBlock 完全相同的分割算术做头/尾折叠（`ceil(max/2)` 头部行加剩余尾部）,使长正文的切片在两张卡之间一致。source 列表是散文而非按列对齐的输出,所以它正常换行,而不像终端卡片的输出那样横向滚动 —— 这是与 TerminalBlock 唯一刻意的分歧。
+**几何镜像 CodeBlock/TerminalBlock**（12px 圆角、code-block 表面、16px 垂直外边距）,使 web 卡片与它们读作一家。整份 source 列表渲染在单个 `` 里,由 `max-height: 320px` 与 `overflow-y: auto` 约束,因此高于该值的列表在原地纵向滚动,而不是把卡片撑高（[来源滚动](2026-08-03-web-search-source-scroll.md)）。source 列表是散文而非按列对齐的输出,所以它正常换行,而不像终端卡片的输出那样横向滚动 —— 这是与 TerminalBlock 唯一刻意的分歧。
-卡片在 chat 行中**常驻**于摘要行之下,上限 `CHAT_WEB_MAX_SOURCES`（8）—— 原语自身默认 16 的一半,面板保留 16 —— 与 `CHAT_TERMINAL_MAX_LINES` 为终端卡片所画的摘要面对阅读面的同一划分,以及 `BashRow` 所用的同一常驻姿态。键控行把一个 `WebRow` 组件注册在 `web_search` 与 `web_fetch` 两个键下;行仅根据工具名判别以选取其图标（search 对 browse）与标题（`Search`/`Fetch`）。没有自己键控行的 web 声明工具落到 `GenericToolCard`,它长出同一张常驻卡片。详情面板以原语的完整 source 额度渲染卡片,并在其下方渲染摊平的模型可见结果内容:`web_fetch` 卡片只携带 URL 与状态,因此其抓取正文只在此处可读。
+卡片在 chat 行中**常驻**于摘要行之下,与 `BashRow` 所用的同一常驻姿态。两个渲染点展示同一份完整的 source 列表,仅由卡片自身的滚动高度约束,而没有行与面板两级的 source 上限。键控行把一个 `WebRow` 组件注册在 `web_search` 与 `web_fetch` 两个键下;行仅根据工具名判别以选取其图标（search 对 browse）与标题（`Search`/`Fetch`）。没有自己键控行的 web 声明工具落到 `GenericToolCard`,它长出同一张常驻卡片。详情面板渲染该卡片,并在其下方渲染摊平的模型可见结果内容:`web_fetch` 卡片只携带 URL 与状态,因此其抓取正文只在此处可读。
## Consequences
@@ -36,14 +36,15 @@ Status: implemented
## Testing
-`packages/client/ui-primitives/tests/web-block.spec.tsx` 把组件钉到 per-file 100% 门槛:两种 kind;标题-或-主机名-或-原始 URL 的标签回退;两种 kind 上的安全链接属性（http(s) URL 成为带 `target`/`rel` 的外链,`javascript:`/`file:`/无法解析的 URL 渲染为无 href 的纯 span）;snippet 与日期在存在/为空/缺失时的显示或省略;由标志位控制的截断提示;以及 source 列表高度上限及其头/尾切片与展开/收起控件,含默认上限。
+`packages/client/ui-primitives/tests/web-block.spec.tsx` 把组件钉到 per-file 100% 门槛:两种 kind;标题-或-主机名-或-原始 URL 的标签回退;两种 kind 上的安全链接属性（http(s) URL 成为带 `target`/`rel` 的外链,`javascript:`/`file:`/无法解析的 URL 渲染为无 href 的纯 span）;snippet 与日期在存在/为空/缺失时的显示或省略;由标志位控制的截断提示;以及完整 source 列表渲染在单个滚动容器内、无展开控件、`` 从 1 起为每条 source 连续编号。
-`packages/client/ui-conversation/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、比面板收得更紧、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-conversation/src/*`）,因此覆盖率运行不度量它。
+`packages/client/ui-conversation/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-conversation/src/*`）,因此覆盖率运行不度量它。
fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配契约的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
## Related
- [Web result card](2026-07-30-web-result-card.md) —— 添加 `card: 'web'` result 支路并让两个工具发出它的后端 PR;本条是它推迟的前端消费者。
+- [Web search 来源卡片改为滚动而非折叠](2026-08-03-web-search-source-scroll.md) —— 用定高滚动容器替换本笔记的 source 列表头/尾折叠,并移除 `CHAT_WEB_MAX_SOURCES` 与原语自身的 source 上限;本笔记的其余决策依然成立。
- [Web terminal card](2026-07-28-web-terminal-card.md) —— 本条所镜像的先例:一个 `ui-primitives` block、一处 card-model 派生、键控与兜底 chat 行、以及一个详情面板支路,用于 `terminal` 渲染意图。
- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— `card` 标签词汇;Web 客户端现在是 `web` 支路的完整消费者。
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
index 1dbc06f8fa..4502aa230f 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
-2026-07-31-even-out-shipped-tool-rosters.md: fe2ed54a70934918b739ac466dc4b0e8f4a93115
-2026-07-31-even-out-shipped-tool-rosters.zh.md: 14cf6e891aa368bcaee8d977fbf5263f36a39dc6
+2026-07-31-even-out-shipped-tool-rosters.md: e325f4614f8d7305ce2c6199a25afd56b51fad61
+2026-07-31-even-out-shipped-tool-rosters.zh.md: a9b49c454d78387583aa7dd9e25f5d5c850a15ae
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
index fe2ed54a70..e325f4614f 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
@@ -12,7 +12,7 @@ The result was a user-visible difference nobody had decided: the same model, ask
## Decision
-The rows that are not surface-specific move into [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml), and three more join them: `tool-session-query`, `tool-str-replace-editor`, and `repeat-tool-guard`. Web search moves there too; its [deployment decision](2026-07-31-web-default-search.md) owns the security boundary while the shared base owns its surface-neutral mount. Both surfaces assemble the same roster: twenty tools on every host, plus `glob` and `grep` when ripgrep is available. `tool-session-query` joined and then left again — the [session-search-not-shipped-default decision](2026-08-02-session-search-not-shipped-default.md) keeps the model-facing consumer opt-in — while the rest of this roster stands.
+The rows that are not surface-specific move into [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml), and three more join them: `tool-session-query`, `tool-str-replace-editor`, and `repeat-tool-guard`. Web search moves there too; its [deployment decision](2026-07-31-web-default-search.md) owns the security boundary while the shared base owns its surface-neutral mount. Both surfaces assemble the same roster: twenty-two tools on every host — the twenty shared rows plus `glob` and `grep`, which are fixed members because `dsh-tool-fs-search` spawns the [packaged ripgrep binary](../architecture/2026-08-01-packaged-ripgrep-search.md). `tool-session-query` joined and then left again — the [session-search-not-shipped-default decision](2026-08-02-session-search-not-shipped-default.md) keeps the model-facing consumer opt-in — while the rest of this roster stands.
Two rows stay surface-specific. `tmux-context` is TUI-only because a browser surface has no terminal multiplexer to describe. `session-reference` is TUI-only because it drives the shared session-query index from the launcher's process-local path, and the browser sidebar reconciles that index on its own first search.
@@ -46,7 +46,7 @@ The same smoke also pins the TUI execution posture from the same artifact. Those
[`apps/web/tests/shipped-composition.e2e.ts`](../../../../apps/web/tests/shipped-composition.e2e.ts) covers the Web surface in the built lane, asserting its catalog, that its access default is untouched, and that `workspace-write`'s writable roots include the temp directories — a trap that makes sandbox tests lie when the workspace sits under `/tmp` ([`roots.ts`](../../../../packages/sandbox/sandbox/src/roots.ts)).
-`glob` and `grep` are asserted as an all-or-nothing pair rather than fixed members: `dsh-tool-fs-search` probes `command -v rg` at load and registers neither tool without ripgrep, which is a host dependency.
+`glob` and `grep` are asserted as fixed members rather than a host-dependent pair: `dsh-tool-fs-search` spawns the packaged ripgrep binary and registers both tools unconditionally, so the pair is always present.
Beyond the committed tests, both surfaces were driven against a real key from the built `apps/cli/lib/bin.js` under plain Node. Every mounted tool executed successfully, including `ralph` and `web_search`; the model never reached `cordis_*` or `mcp_*`, fell back to `grep` when asked for LSP navigation, and used a background `bash` task when asked for a persistent terminal.
@@ -62,7 +62,7 @@ Beyond the committed tests, both surfaces were driven against a real key from th
## Consequences
-The same model gets the same tools on both surfaces, and the difference that existed for no recorded reason is gone. The tests assert the twenty unconditional names exactly and require the ripgrep-dependent pair to be either present together or absent together on both sides, so a later change that alters only one surface fails a check instead of shipping quietly; the [session-search-not-shipped-default decision](2026-08-02-session-search-not-shipped-default.md) is exactly such a later change, and both tests moved with it.
+The same model gets the same tools on both surfaces, and the difference that existed for no recorded reason is gone. The tests assert the twenty unconditional names exactly and pin `glob` and `grep` as fixed members on both sides, so a later change that alters only one surface fails a check instead of shipping quietly; the [session-search-not-shipped-default decision](2026-08-02-session-search-not-shipped-default.md) is exactly such a later change, and both tests moved with it.
`apps/cli` gained five workspace dependencies: four the shipped tree mounted, plus `dsh-mcp-client`, which it does not mount and which exists so an installed `dsh` can. Four remain — the [session-search-not-shipped-default decision](2026-08-02-session-search-not-shipped-default.md) removed `@deepseek-ai/dsh-tool-session-query` along with its row.
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
index 14cf6e891a..a9b49c454d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
@@ -12,7 +12,7 @@ Status: implemented
## 决策
-那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml),另有三行加入:`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单：每台宿主上都有二十个工具，ripgrep 可用时再加上 `glob` 和 `grep`。`tool-session-query` 加入后又退出了——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)让面向模型的消费方保持需显式启用——而这份清单的其余部分保持不变。
+那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml),另有三行加入:`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单：每台宿主上都有二十二个工具——二十个共享行加上 `glob` 和 `grep`，它们成为固定成员，因为 `dsh-tool-fs-search` 直接 spawn [打包的 ripgrep 二进制](../architecture/2026-08-01-packaged-ripgrep-search.md)。`tool-session-query` 加入后又退出了——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)让面向模型的消费方保持需显式启用——而这份清单的其余部分保持不变。
有两行仍是 surface 专属。`tmux-context` 只在 TUI,因为浏览器 surface 没有终端复用器可描述。`session-reference` 只在 TUI,因为它以 launcher 的进程本地路径驱动共享的 session-query 索引,而浏览器侧边栏会在自己的首次搜索里重建该索引。
@@ -46,7 +46,7 @@ Status: implemented
[`apps/web/tests/shipped-composition.e2e.ts`](../../../../apps/web/tests/shipped-composition.e2e.ts) 在构建产物 lane 中覆盖 Web surface,断言它的工具目录、它的访问默认值未被触碰,以及 `workspace-write` 的可写根包含临时目录——一个会让沙箱测试说谎的陷阱,当工作区落在 `/tmp` 下时([`roots.ts`](../../../../packages/sandbox/sandbox/src/roots.ts))。
-`glob` 与 `grep` 被作为全有或全无的一对断言,而不是固定成员:`dsh-tool-fs-search` 在加载时探测 `command -v rg`,没有 ripgrep 就两个工具都不注册,这是宿主依赖。
+`glob` 与 `grep` 被作为固定成员断言，而不是一对宿主依赖：`dsh-tool-fs-search` spawn 打包的 ripgrep 二进制并无条件注册两个工具，因此这一对始终在场。
除入库测试外,两个 surface 都以 plain Node 从构建产物 `apps/cli/lib/bin.js` 出发、用真实密钥驱动过。每一个已挂载的工具都执行成功,包括 `ralph` 与 `web_search`;模型从未触达 `cordis_*` 或 `mcp_*`,被要求做 LSP 跳转时退化到 `grep`,被要求开持久终端时用了后台 `bash` 任务。
@@ -62,7 +62,7 @@ Status: implemented
## 后果
-同一个模型在两个 surface 上拿到同样的工具,那处没有记录理由的差异消失了。测试会精确断言二十个无条件提供的名称，并要求依赖 ripgrep 的一对工具在两侧要么同时存在、要么同时缺席，因此日后只改一个 surface 都会让检查失败而不是悄悄发出去；[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)正是这样一次后来的改动，两个测试也随之移动。
+同一个模型在两个 surface 上拿到同样的工具,那处没有记录理由的差异消失了。测试会精确断言二十个无条件提供的名称，并把 `glob` 与 `grep` 作为固定成员钉在两侧，因此日后只改一个 surface 都会让检查失败而不是悄悄发出去；[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)正是这样一次后来的改动，两个测试也随之移动。
`apps/cli` 增加了五个 workspace 依赖:四个是交付树当时挂载的,外加 `dsh-mcp-client`——它并不被挂载,存在的意义是让已安装的 `dsh` 能挂。四个保留了下来——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)把 `@deepseek-ai/dsh-tool-session-query` 连同它的行一起移除了。
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
new file mode 100644
index 0000000000..80f7ed4ab4
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
+2026-08-03-web-search-source-scroll.md: c11bb2317b6ae6cad8017a4b76cb0b9ccebd6fc0
+2026-08-03-web-search-source-scroll.zh.md: add012216589b33cf244d8a14053a5b6d60631a6
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
new file mode 100644
index 0000000000..c11bb2317b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
@@ -0,0 +1,46 @@
+# Agent Note: Web search source card scrolls instead of collapsing
+
+Status: implemented
+
+English | [中文](2026-08-03-web-search-source-scroll.zh.md)
+
+## Problem
+
+The `web_search` result card (`WebBlock`, `packages/client/ui-primitives/src/WebBlock.tsx`) rendered its source list with a head/tail collapse: past a `maxSources` count (16 in the details panel, 8 in the chat row via `CHAT_WEB_MAX_SOURCES`) it drew the first `ceil(max/2)` sources, an `… 其余 N 条来源` expand button, then the last `max - ceil(max/2)`, mirroring `TerminalBlock`'s output cap. A user reading the card saw `来源列表已截断` and assumed the frontend had dropped sources it was holding.
+
+It had not. The seam (`capSources`, `packages/web/web/src/index.ts`) cuts the provider's sources to the tool's `searchMaxResults` bound (default 8) and sets `truncated`, and that one capped list feeds both the model-facing render text and the card's `presentationMeta`. The card never holds more sources than that one cut produced. So the collapse was hiding sources the user was entitled to see in full — and, with the default bound at 8 and the panel cap at 16, it almost never even triggered, leaving only the `truncated` note with no way to reveal anything.
+
+## Decision
+
+`WebBlock`'s search arm renders every source it receives in one ``, with no head/tail slicing, no expand button, and no `maxSources` prop. `.sources` (`WebBlock.module.css`) gets a fixed `max-height` and `overflow-y: auto`, so a list longer than the card height scrolls in place rather than growing the card or hiding rows. The height is a design constant of the card geometry, so it lives in CSS, not a plugin config field.
+
+The model side is unchanged: the seam still caps sources at `searchMaxResults`, the model-facing render text is untouched, and the `truncated` flag and its `来源列表已截断` indicator stay. The card draws the list the seam produced, in full and scrollable, instead of collapsing its middle.
+
+That list is the one the model reads as long as nothing downstream of the tool rewrites the result content alone. A deployment mounting `dsh-spill-policy` breaks that correspondence for an oversized result: `tools/post-execute` replaces the model-facing `content` with a preview plus a spill locator and leaves `presentationMeta` whole, so the card still draws every source while the model reads a bounded excerpt. The card's contract is therefore the view it receives, not the model's context.
+
+`CHAT_WEB_MAX_SOURCES` and the primitive's `DEFAULT_WEB_MAX_SOURCES` are removed: with scroll, the chat row and the details panel show the same full list, differentiated only by their container height. `` still pins each source's 1-based citation index; without the collapse gap the ordinals are now simply contiguous.
+
+Making the list a scroll container also makes its `padding-left` a correctness constraint, not spacing. A scroll container clips inline-start overflow and offers no way to scroll it back, and `::marker` is right-aligned to the content edge, so a marker wider than the padding silently loses its leading digits — at the list's 20px the two-digit markers rendered as `0.` and `1.` where `10.` and `11.` belonged. `searchMaxResults` is an unbounded positive integer, so the padding is sized in `em` against the list's own font — the one a marker inherits — to hold a three-digit marker (`999. ` measures 2.35em in the app font stack) and keeps the gap the one-digit case already had.
+
+## Alternatives considered
+
+**Raise `searchMaxResults` (or make it unbounded) so more sources reach both the model and the card.** Rejected by the user: it changes model-side behavior (more sources into every request's context, more tokens) and widens the gap between what the model reads and what the card draws. The instruction was explicit — keep the cap and the truncation, add a scrollbar.
+
+**Keep the head/tail collapse and add scroll only to the expanded region.** Rejected: two overlapping mechanisms for one concern. Once the whole list is always rendered, the collapse arithmetic, the expand/collapse state, and the button are dead weight; scroll alone bounds the height.
+
+**Make the scroll height a plugin config field.** Rejected: the height bounds the card's on-screen geometry, not a deployment policy, so it belongs in `WebBlock.module.css` alongside the radius, surface, and margin that [the web result card frontend note](2026-07-30-web-result-card-frontend.md) already fixes there as this card's geometry.
+
+## Consequences
+
+Every source the tool returned is always in the DOM, so no source the view carries is hidden behind an interaction. The card's height is bounded regardless of source count, and a list taller than the container scrolls in place. The cost is that the scroll affordance depends on the platform's scrollbar rendering: an overlay-scrollbar system (macOS default) shows no persistent bar when the pointer is away, so a capped list relies on the `来源列表已截断` note plus a clipped last row to signal there is more. `WebSearchBlockProps`/`WebFetchBlockProps` lose their `maxSources` prop and the primitive loses `DEFAULT_WEB_MAX_SOURCES`, so any future caller renders the full list by construction rather than by passing a large cap.
+
+## Testing
+
+`packages/client/ui-primitives/tests/web-block.spec.tsx` drops the collapse cases (head/tail slice, expand-on-click, collapsed-tail numbering, expander-out-of-numbering, head-alone, default cap) and adds: a 30-source card renders all 30 ` ` with no `[aria-expanded]` and no ``, every `` child is a source ``, and ` ` numbers 1..N contiguously. `packages/client/ui-conversation/tests/web-card.spec.tsx` drops the `CHAT_WEB_MAX_SOURCES` cap assertion; the WebRow expansion test still asserts the card shows every source field. The `packages/web/tool-web` tests are unchanged — the model side did not move.
+
+jsdom resolves no CSS Modules layout, so it reports `scrollHeight === clientHeight` for every element and cannot witness the scroll at all. The geometry is pinned in the assembled browser instead, by `apps/web/tests/web-search-round.e2e.ts`: its deterministic search double returns 12 provider results, each with a title, a citation snippet, and a date. That first pins the seam's cap end to end in a real composition — the shipped `searchMaxResults` keeps 8, the model-visible render text carries the 8 kept titles and none of the 4 dropped URLs plus `(Showing the first 8 sources. Refine the query for more.)`, and `meta.truncated` is true. A case after the aria golden then expands the `web_search` row and asserts on the card's ``: 8 ``, no `` anywhere in the card, the `来源列表已截断` indicator visible, and computed `max-height: 320px` with `overflow-y: auto` over `scrollHeight` 574 against `clientHeight` 320. A further case measures a `999. ` marker in the list's own inherited font and requires the computed `padding-left` to be at least that wide, so the marker room the scroll container cannot clip back is pinned against the widest marker rather than against one fixture's source count. Neither the recorded stream nor the aria golden moved: replay is a positional cursor over the fixture's `assistant/chunk` entries and the search double is a separate local endpoint the provider reaches by `fetch`, while the card is collapsed at capture time so its `` is out of the DOM and the summary row carries no source count.
+
+## Related
+
+- [Web result card](2026-07-30-web-result-card.md) — the `card: 'web'` render-intent arm and `presentationMeta` route this card consumes; the source of the capped-once list.
+- [Web result card frontend](2026-07-30-web-result-card-frontend.md) — owns `WebBlock`, the single `web-card-model` derivation, and the render sites that draw the card; this note replaces the source-list collapse it specified, and its other decisions (one component for both kinds, the http(s) link allowlist, the single derivation, the resident posture) stand.
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
new file mode 100644
index 0000000000..add0122165
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
@@ -0,0 +1,46 @@
+# Agent Note: Web search source card scrolls instead of collapsing
+
+Status: implemented
+
+[English](2026-08-03-web-search-source-scroll.md) | 中文
+
+## Problem
+
+`web_search` 结果卡片（`WebBlock`，`packages/client/ui-primitives/src/WebBlock.tsx`）此前用首尾折叠渲染它的来源列表：超过 `maxSources` 数量（详情面板为 16，聊天行经由 `CHAT_WEB_MAX_SOURCES` 为 8）时，它画出前 `ceil(max/2)` 条来源、一个 `… 其余 N 条来源` 展开按钮，再画出末尾 `max - ceil(max/2)` 条，与 `TerminalBlock` 的输出上限一致。用户阅读该卡片时看到 `来源列表已截断`，会以为前端丢弃了它正持有的来源。
+
+其实并没有。seam（`capSources`，`packages/web/web/src/index.ts`）把 provider 的来源裁剪到工具的 `searchMaxResults` 上限（默认 8）并置位 `truncated`，而这一份被裁剪过一次的列表同时喂给面向模型的 render 文本与卡片的 `presentationMeta`。卡片持有的来源绝不会多于这一次裁剪的产物。因此这个折叠隐藏的正是用户本有权完整查看的来源——并且在默认上限为 8、面板上限为 16 时，它几乎从不触发，只留下 `truncated` 提示，却无从展开任何内容。
+
+## Decision
+
+`WebBlock` 的 search 分支把它收到的每一条来源都渲染进单个 ``，不做首尾切片、不设展开按钮、也不带 `maxSources` prop。`.sources`（`WebBlock.module.css`）获得一个固定的 `max-height` 与 `overflow-y: auto`，因此长于卡片高度的列表在原地滚动，而非撑大卡片或隐藏行。该高度是卡片几何形状的一个设计常量，因此放在 CSS 里，而非插件配置字段。
+
+模型侧不变：seam 仍在 `searchMaxResults` 处封顶来源，面向模型的 render 文本未动，`truncated` 标志及其 `来源列表已截断` 指示保留。卡片完整且可滚动地画出 seam 产出的这份列表，而非折叠其中段。
+
+只要工具下游没有单独改写结果 content，这份列表就是模型读到的那份。挂载了 `dsh-spill-policy` 的部署会对超限结果打破这一对应：`tools/post-execute` 把面向模型的 `content` 替换为预览加 spill 定位符，而 `presentationMeta` 原样保留，因此卡片仍画出全部来源，模型读到的却是一段有界摘录。所以卡片的契约是它收到的 view，不是模型的上下文。
+
+`CHAT_WEB_MAX_SOURCES` 与该 primitive 的 `DEFAULT_WEB_MAX_SOURCES` 被移除：有了滚动，聊天行与详情面板展示同一份完整列表，仅以各自的容器高度区分。`` 仍钉住每条来源从 1 起算的引用序号；没有了折叠造成的间断，这些序号如今就是连续的。
+
+把列表变成滚动容器，也把它的 `padding-left` 从间距变成了正确性约束。滚动容器裁掉 inline-start 方向的溢出且无从滚回，而 `::marker` 右对齐到内容边缘，因此宽于 padding 的序号会静默丢掉前导数字——在列表原本的 20px 下，两位数序号被画成 `0.` 与 `1.`，而本该是 `10.` 与 `11.`。`searchMaxResults` 是无上界的正整数，因此该 padding 以 `em` 计量——相对列表自身的字体，也就是序号所继承的那个——装得下三位数序号（`999. ` 在应用字体栈下量得 2.35em），并保留一位数情形原有的间隙。
+
+## Alternatives considered
+
+**提高 `searchMaxResults`（或让它无上限），使更多来源同时抵达模型与卡片。** 被用户否决：它改变了模型侧行为（每个请求的上下文纳入更多来源、更多 token），并拉大模型读到的内容与卡片画出的内容之间的差距。指令很明确——保留上限与截断，加一个滚动条。
+
+**保留首尾折叠，仅对展开区域加滚动。** 否决：一个关注点上两套重叠机制。一旦整份列表始终渲染，折叠的算术、展开/折叠状态与那个按钮都是死重；仅靠滚动即可约束高度。
+
+**把滚动高度做成插件配置字段。** 否决：该高度约束的是卡片在屏幕上的几何形状，而非部署策略，因此它属于 `WebBlock.module.css`，与 [Web result 卡片前端笔记](2026-07-30-web-result-card-frontend.md) 已作为本卡片几何固定在那里的圆角、表面与外边距并列。
+
+## Consequences
+
+工具返回的每一条来源始终存在于 DOM 中，因此 view 携带的来源没有一条被藏在交互之后。无论来源数量多少，卡片高度都受限；高于容器的列表在原地滚动。代价是滚动提示依赖平台的滚动条渲染：overlay 滚动条系统（macOS 默认）在指针离开时不显示常驻滚动条，因此被裁剪的列表依靠 `来源列表已截断` 提示加上被裁切的最后一行来表明还有更多内容。`WebSearchBlockProps`/`WebFetchBlockProps` 失去 `maxSources` prop，primitive 失去 `DEFAULT_WEB_MAX_SOURCES`，因此未来任何调用方都从构造上渲染完整列表，而不是靠传入一个很大的上限值。
+
+## Testing
+
+`packages/client/ui-primitives/tests/web-block.spec.tsx` 删去折叠相关用例（首尾切片、点击展开、折叠尾部编号、展开器不计入编号、仅首部、默认上限），并新增：一个 30 条来源的卡片渲染出全部 30 个 ` `，无 `[aria-expanded]`、无 ``，每个 `` 子元素都是一条来源 ``，且 ` ` 从 1 到 N 连续编号。`packages/client/ui-conversation/tests/web-card.spec.tsx` 删去 `CHAT_WEB_MAX_SOURCES` 上限断言；WebRow 展开测试仍断言卡片展示每一个来源字段。`packages/web/tool-web` 的测试不变——模型侧未曾移动。
+
+jsdom 不解析 CSS Modules 布局，对任何元素都报 `scrollHeight === clientHeight`，因此它根本无从见证这次滚动。几何改由组装态浏览器钉住，位于 `apps/web/tests/web-search-round.e2e.ts`：其确定性 search double 返回 12 条 provider 结果，每条带标题、引用摘录与日期。这首先在真实组合里端到端钉住 seam 的裁剪——出厂 `searchMaxResults` 保留 8 条，面向模型的 render 文本含这 8 条标题、不含被丢弃的 4 条 URL，并含 `(Showing the first 8 sources. Refine the query for more.)`，`meta.truncated` 为 true。随后位于 aria golden 之后的一个用例展开 `web_search` 行，对卡片的 `` 断言：8 个 ``、卡片内任何位置都没有 ``、`来源列表已截断` 指示可见，以及计算样式 `max-height: 320px` 与 `overflow-y: auto`，`scrollHeight` 为 574、`clientHeight` 为 320。再后一个用例在列表自身继承的字体下量出 `999. ` 序号的宽度，要求计算后的 `padding-left` 不小于该宽度，从而把滚动容器无从滚回的那段序号空间钉在最宽序号上，而非钉在某一份 fixture 的来源条数上。录制的模型流与 aria golden 都未变动：replay 是对 fixture 中 `assistant/chunk` 条目的位置游标，而 search double 是 provider 经 `fetch` 抵达的另一个本地端点；捕获时卡片处于折叠状态，其 `` 不在 DOM 中，摘要行也不携带来源数量。
+
+## Related
+
+- [Web result card](2026-07-30-web-result-card.md) —— 本卡片消费的 `card: 'web'` 渲染意图分支与 `presentationMeta` 路由；那份裁剪过一次的列表的来源。
+- [Web result 卡片前端](2026-07-30-web-result-card-frontend.md) —— `WebBlock`、唯一的 `web-card-model` 派生，以及绘制该卡片的各渲染点由它拥有；本笔记替换掉它所规定的来源列表折叠，它的其余决策（一个组件绘制两种 kind、http(s) 链接 allowlist、单一派生、常驻姿态）依然成立。
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
new file mode 100644
index 0000000000..91b9e6a0c0
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
+2026-08-03-omit-invariants-from-shipped-config.md: ff9a3b0ab2b4797ca4e96bea9e6b961b2e38501f
+2026-08-03-omit-invariants-from-shipped-config.zh.md: 526ce0756e69b36b6f54b46b23e1814322d6a1fd
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
new file mode 100644
index 0000000000..ff9a3b0ab2
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
@@ -0,0 +1,30 @@
+# Agent Note: Omit runtime invariants from shipped dsh config
+
+Status: implemented
+
+English | [中文](2026-08-03-omit-invariants-from-shipped-config.zh.md)
+
+## Problem
+
+`@deepseek-ai/dsh-invariants` and package-owned `./invariant` companions are optional development diagnostics. The shipped TUI mounted the service and four stateful companions while the shipped Web tree omitted them, so the two product surfaces had different diagnostic cost and failure behavior. A relational assertion failure could terminate an ordinary TUI run even though the always-on product boundary remained responsible for session validation and immutable history.
+
+## Decision
+
+The shipped `dsh` configuration trees under `apps/cli/config/` mount neither `@deepseek-ai/dsh-invariants` nor any package-owned `./invariant` companion. The CLI package therefore carries no direct dependency on the invariant service.
+
+Invariant support remains available for focused tests, example bundles, generated SDK compositions, and custom deployments that opt into diagnostics explicitly. Session validation, snapshotting, freezing, and provenance remain always on and do not depend on the optional service, as defined by the [source-owned immutability decision](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
+
+The built CLI config-dump test checks both shipped surfaces and rejects either the service entry or any `@deepseek-ai/dsh-*/invariant` entry.
+
+## Alternatives considered
+
+- **Mount the service with `enabled: false`.** Rejected because the shipped tree and CLI dependency would still carry diagnostics that install no checks.
+- **Keep the TUI-only mount.** Rejected because the shipped surfaces would retain different diagnostic and failure behavior.
+- **Remove invariant support from the repository.** Rejected because package-owned checks remain useful in tests, examples, generated SDKs, and explicit development compositions; only the default product config is out of scope.
+
+## Consequences
+
+- Ordinary `dsh` TUI and Web runs install no invariant listeners or trace state and cannot fail through `InvariantError`.
+- Development and custom compositions retain explicit access to the invariant service and companions.
+- The shipped config absence is verified from the built CLI's composed output for both surfaces.
+- Always-on session integrity remains unchanged.
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
new file mode 100644
index 0000000000..526ce0756e
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
@@ -0,0 +1,30 @@
+# Agent Note: 从交付的 dsh 配置中省略运行时不变式
+
+Status: implemented
+
+[English](2026-08-03-omit-invariants-from-shipped-config.md) | 中文
+
+## 问题
+
+`@deepseek-ai/dsh-invariants` 与各包（package）拥有的 `./invariant` 伴随插件是可选的开发诊断。交付的 TUI 挂载了该服务和四个有状态伴随插件，而交付的 Web 配置树省略了这些条目，导致两个产品 surface 的诊断成本和失败行为不同。即使始终启用的产品边界仍负责会话验证与不可变历史，关系断言失败也可能终止普通的 TUI 运行。
+
+## 决策
+
+`apps/cli/config/` 下交付的 `dsh` 配置树既不挂载 `@deepseek-ai/dsh-invariants`，也不挂载任何包拥有的 `./invariant` 伴随插件。因此，CLI 包不再直接依赖不变式服务。
+
+不变式支持仍可供聚焦测试、示例组合包、生成的 SDK 组合，以及显式选择诊断的自定义部署使用。会话验证、快照、冻结和 provenance 始终启用，且不依赖可选服务，具体由[源端拥有的不可变性决策](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md)规定。
+
+构建后 CLI 的配置转储测试会检查两个交付的 surface，并拒绝服务条目或任何 `@deepseek-ai/dsh-*/invariant` 条目。
+
+## 已考虑的替代方案
+
+- **挂载服务并设置 `enabled: false`。** 不予采纳，因为交付的配置树和 CLI 依赖仍会携带不安装任何检查的诊断。
+- **保留仅由 TUI 挂载的方案。** 不予采纳，因为两个交付的 surface 仍会保留不同的诊断和失败行为。
+- **从仓库中移除不变式支持。** 不予采纳，因为包拥有的检查在测试、示例、生成的 SDK 及显式开发组合中仍然有用；只有默认产品配置不在其范围内。
+
+## 后果
+
+- 普通的 `dsh` TUI 与 Web 运行不安装不变式监听器或 trace 状态，也不会因 `InvariantError` 失败。
+- 开发和自定义组合仍可显式使用不变式服务及伴随插件。
+- 构建后 CLI 的组合输出会验证两个 surface 的交付配置中均不存在这些条目。
+- 始终启用的会话完整性保持不变。
diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs
index bc8c881eda..4c9242bab5 100644
--- a/.github/issue-management/policy.mjs
+++ b/.github/issue-management/policy.mjs
@@ -180,6 +180,20 @@ export function parseReferences({ body, repository }) {
}
}
+/**
+ * Retain only references that resolve to Issues rather than pull requests.
+ * @param {{all: number[], resolving: number[], related: number[]}} references Parsed references.
+ * @param {Map} issues Resolved same-repository Issues.
+ * @returns {{all: number[], resolving: number[], related: number[]}} Issue-only references.
+ */
+export function retainIssueReferences(references, issues) {
+ return {
+ all: references.all.filter((number) => issues.has(number)),
+ resolving: references.resolving.filter((number) => issues.has(number)),
+ related: references.related.filter((number) => issues.has(number)),
+ }
+}
+
/**
* Validate one Issue with its Project status.
* @param {{title: string, body: string, assignees: string[], labels: string[], type: string|null, priority: string|null, status: string|null, state: string, stateReason: string|null}} issue Issue snapshot.
@@ -472,7 +486,7 @@ async function pullRequestSnapshot(number) {
reviewRequestCount: reviewRequests.users.length + reviewRequests.teams.length,
reviewCount: reviews.length,
labels: pull.labels.map((label) => label.name),
- references,
+ references: retainIssueReferences(references, issues),
issues,
}
}
diff --git a/.github/issue-management/policy.test.mjs b/.github/issue-management/policy.test.mjs
index 890247db29..8e0c253796 100644
--- a/.github/issue-management/policy.test.mjs
+++ b/.github/issue-management/policy.test.mjs
@@ -4,6 +4,7 @@ import test from 'node:test'
import {
countVisibleUnits,
parseReferences,
+ retainIssueReferences,
requiresPullRequestPolicy,
validateBody,
validateIssue,
@@ -117,6 +118,24 @@ test('separates resolving and informational references', () => {
)
})
+test('does not treat pull request references as Issue associations', () => {
+ const references = {
+ all: [123, 1180, 1181],
+ resolving: [123, 1180],
+ related: [1181],
+ }
+ const issues = new Map([
+ [1180, {}],
+ [1181, {}],
+ ])
+
+ assert.deepEqual(retainIssueReferences(references, issues), {
+ all: [1180, 1181],
+ resolving: [1180],
+ related: [1181],
+ })
+})
+
test('allows informational references without cross-object constraints', () => {
const errors = validatePullRequest({
isDraft: false,
diff --git a/.github/workflows/issue-lifecycle.yml b/.github/workflows/issue-lifecycle.yml
new file mode 100644
index 0000000000..4dc6869e27
--- /dev/null
+++ b/.github/workflows/issue-lifecycle.yml
@@ -0,0 +1,58 @@
+name: Issue lifecycle
+
+on:
+ issues:
+ types:
+ - opened
+ - edited
+ - assigned
+ - unassigned
+ - labeled
+ - unlabeled
+ - closed
+ - reopened
+ - field_added
+ - field_removed
+ pull_request:
+ types:
+ - opened
+ - edited
+ - synchronize
+ - reopened
+ - labeled
+ - unlabeled
+ - ready_for_review
+ - review_requested
+ pull_request_review:
+ types:
+ - submitted
+
+permissions:
+ contents: read
+
+concurrency:
+ group: issue-lifecycle-${{ github.event.issue.number || github.event.pull_request.number || github.run_id }}
+ cancel-in-progress: false
+
+jobs:
+ lifecycle:
+ name: Issue lifecycle
+ runs-on: ubuntu-latest
+ steps:
+ - name: Check out trusted policy
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+ with:
+ ref: ${{ github.event.repository.default_branch }}
+ persist-credentials: false
+ - name: Create project token
+ id: app-token
+ uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1
+ with:
+ client-id: ${{ vars.DSH_ISSUE_APP_CLIENT_ID }}
+ private-key: ${{ secrets.DSH_ISSUE_APP_PRIVATE_KEY }}
+ owner: deepseek-harness
+ repositories: deepseek-harness
+ - name: Handle repository event
+ env:
+ GH_TOKEN: ${{ steps.app-token.outputs.token }}
+ run: node .github/issue-management/policy.mjs lifecycle
diff --git a/.github/workflows/issue-policy.yml b/.github/workflows/issue-policy.yml
new file mode 100644
index 0000000000..dde9462c33
--- /dev/null
+++ b/.github/workflows/issue-policy.yml
@@ -0,0 +1,27 @@
+name: Issue policy
+
+on:
+ pull_request:
+ types: [opened, edited, synchronize, reopened, labeled, unlabeled, ready_for_review, review_requested]
+ pull_request_review:
+ types: [submitted]
+
+permissions:
+ contents: read
+ issues: read
+ pull-requests: read
+
+jobs:
+ policy:
+ name: Issue policy
+ runs-on: ubuntu-latest
+ steps:
+ - name: Check out trusted policy
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+ with:
+ ref: ${{ github.event.repository.default_branch }}
+ persist-credentials: false
+ - name: Validate pull request
+ env:
+ GITHUB_TOKEN: ${{ github.token }}
+ run: node .github/issue-management/policy.mjs pr
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 92ea0d2406..03fd24e5b7 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -47,6 +47,7 @@ External packages that a workspace package resolves at runtime. `scripts/install
| [`@opentelemetry/sdk-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
| [`@shikijs/langs`](https://github.com/shikijs/shiki) | MIT |
| [`@standard-schema/spec`](https://github.com/standard-schema/standard-schema) | MIT |
+| [`@vscode/ripgrep`](https://github.com/microsoft/vscode-ripgrep) | MIT |
| [`anser`](https://github.com/IonicaBizau/anser) | MIT |
| [`chokidar`](https://github.com/paulmillr/chokidar) | MIT |
| [`clsx`](https://github.com/lukeed/clsx) | MIT |
diff --git a/apps/cli/config/tui.cordis.yml b/apps/cli/config/tui.cordis.yml
index 02d8649447..ba1ae7f697 100644
--- a/apps/cli/config/tui.cordis.yml
+++ b/apps/cli/config/tui.cordis.yml
@@ -58,25 +58,34 @@
# ── TUI-only rows ───────────────────────────────────────────────────────────
- insert:
- # Relational runtime checks over the authoritative event streams; each
- # companion registers the assertions its own package owns.
- - id: invariants
- name: '@deepseek-ai/dsh-invariants'
- - id: session-invariant
- name: '@deepseek-ai/dsh-session/invariant'
- - id: agent-invariant
- name: '@deepseek-ai/dsh-agent/invariant'
- - id: scope-invariant
- name: '@deepseek-ai/dsh-scope/invariant'
- - id: agent-loop-invariant
- name: '@deepseek-ai/dsh-agent-loop/invariant'
-
# The derived query index behind `/resume`. The launcher provides a unique
# process-local path because this SQLite backend has one writer owner; the
# project-local fallback applies when no launcher sets the typed slot.
- id: session-reference
name: '@deepseek-ai/dsh-session-reference'
+ # The projection registry plus its durable checkpoint cache (over the same
+ # storage root the web surface uses): `/resume` reads titles from the
+ # zero-I/O checkpoint row or a tail-only cold read instead of scanning
+ # whole logs, and checkpoints written by either surface serve both.
+ - id: session-projection
+ name: '@deepseek-ai/dsh-session-projection'
+ - id: storage
+ name: '@deepseek-ai/dsh-storage'
+ - id: storage-json
+ name: '@deepseek-ai/dsh-storage-json'
+ config:
+ root: !!js dshHomePath('storages')
+ - id: storage-domain
+ name: '@deepseek-ai/dsh-storage-domain'
+ config:
+ backend: json
+ - id: session-projection-cache
+ name: '@deepseek-ai/dsh-session-projection-cache'
+ config:
+ writeEveryEvents: 200
+ writeIntervalMs: 5000
+
# Terminal-multiplexer context, mounted only where a terminal exists.
- id: tmux-context
name: '@deepseek-ai/dsh-tmux-context'
diff --git a/apps/cli/package.json b/apps/cli/package.json
index 8c482ac3e2..9bba751b27 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -65,7 +65,6 @@
"@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^",
"@deepseek-ai/dsh-host-directory-picker-native": "workspace:^",
"@deepseek-ai/dsh-host-webserver": "workspace:^",
- "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-llm-deepseek": "workspace:^",
"@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 3592d438dd..88f8178fba 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -94,6 +94,8 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
expect(stdout).toContain('model: deepseek-v4-pro')
expect(stdout).toContain('cwd: !!js process.cwd()')
expect(stdout).toContain("name: '@deepseek-ai/dsh-tui'")
+ expect(stdout).not.toMatch(/name: ['"]@deepseek-ai\/dsh-invariants['"]/)
+ expect(stdout).not.toMatch(/name: ['"]@deepseek-ai\/dsh-[^'"]+\/invariant['"]/)
expect(stdout).toContain([
'- id: tool-web',
" name: '@deepseek-ai/dsh-tool-web'",
@@ -140,6 +142,8 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
expect(code).toBe(0)
expect(stdout).toContain("name: '@deepseek-ai/dsh-host-webserver'")
expect(stdout).not.toContain("name: '@deepseek-ai/dsh-tui'")
+ expect(stdout).not.toMatch(/name: ['"]@deepseek-ai\/dsh-invariants['"]/)
+ expect(stdout).not.toMatch(/name: ['"]@deepseek-ai\/dsh-[^'"]+\/invariant['"]/)
}, 30_000)
})
})
diff --git a/apps/cli/tests/shipped-composition.e2e.ts b/apps/cli/tests/shipped-composition.e2e.ts
index 2460a7927e..b7ba80daed 100644
--- a/apps/cli/tests/shipped-composition.e2e.ts
+++ b/apps/cli/tests/shipped-composition.e2e.ts
@@ -52,10 +52,10 @@ const EXPECTED_TUI_TOOLS = [
]
/**
- * `glob` and `grep` come from `dsh-tool-fs-search`, which probes `command -v rg`
- * through the mounted bash executor at load and registers neither tool when
- * ripgrep is absent. That is a host dependency, not a composition decision, so the
- * pair is asserted separately — present together or absent together.
+ * `glob` and `grep` come from `dsh-tool-fs-search`, which spawns the PACKAGED
+ * ripgrep binary (`@vscode/ripgrep`) through the subprocess seam, so the pair
+ * is always present on every host — asserted as fixed members, not a host
+ * dependency.
*/
const RIPGREP_TOOLS = ['glob', 'grep']
@@ -123,7 +123,9 @@ describe('shipped dsh composition (real Loader tree in a PTY)', () => {
expect(output).toContain(COMPOSITION_REPLY_TEXT)
expect(output).toContain(PERMISSION_SUMMARY)
expect(observed?.names.filter(name => !RIPGREP_TOOLS.includes(name))).toEqual(EXPECTED_TUI_TOOLS)
- expect([[], RIPGREP_TOOLS]).toContainEqual(observed?.names.filter(name => RIPGREP_TOOLS.includes(name)))
+ // The packaged ripgrep binary ships with the dependency, so the pair is a
+ // fixed roster member on every host.
+ expect(observed?.names.filter(name => RIPGREP_TOOLS.includes(name))).toEqual(RIPGREP_TOOLS)
expect(observed?.bashArguments).toHaveProperty('sandbox_permissions')
expect(observed?.bashArguments).toHaveProperty('justification')
expect(observed?.permissionEvents).toEqual([
diff --git a/apps/web/tests/remote-welcome.e2e.ts b/apps/web/tests/remote-welcome.e2e.ts
new file mode 100644
index 0000000000..483d6c369c
--- /dev/null
+++ b/apps/web/tests/remote-welcome.e2e.ts
@@ -0,0 +1,53 @@
+// Trusted non-loopback Web access must not wedge on the loopback-only
+// settings API while the mandatory product notice owns the viewport.
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import {
+ acknowledgeReloadConnectionLoss, launchWebScaffold, watchConsole, webSnapshotMode,
+ type WebScaffold,
+} from './scaffold.ts'
+import { ZH_BROWSER_LOCALE } from './support.ts'
+import { WELCOME_NOTICE_COPY } from '@deepseek-ai/dsh-client-ui-settings-general'
+
+const MODE = webSnapshotMode()
+
+describe.skipIf(MODE === 'record')('web e2e: remote welcome notice', () => {
+ let scaffold: WebScaffold
+ let browser: Browser
+ let page: Page
+ let tripwire: ReturnType
+
+ beforeAll(async () => {
+ scaffold = await launchWebScaffold({ remoteAuthority: 'remote.localhost', welcomeNoticePending: true })
+ browser = await chromium.launch()
+ page = await browser.newPage({ viewport: { width: 1440, height: 960 }, locale: ZH_BROWSER_LOCALE })
+ tripwire = watchConsole(page)
+ await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+ await page.waitForSelector('#root', { timeout: 30_000 })
+ }, 120_000)
+
+ afterAll(async () => {
+ await browser?.close()
+ await scaffold?.close()
+ })
+
+ it('advances process-locally and presents the notice again after reload', async () => {
+ const welcome = page.getByRole('region', { name: WELCOME_NOTICE_COPY.zh.title })
+ await welcome.waitFor({ timeout: 15_000 })
+ expect(await page.locator('#root').evaluate(root => (root as HTMLElement).inert)).toBe(true)
+
+ await welcome.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }).click()
+ await welcome.waitFor({ state: 'detached', timeout: 15_000 })
+ await expect.poll(
+ () => page.locator('#root').evaluate(root => (root as HTMLElement).inert),
+ { timeout: 15_000 },
+ ).toBe(false)
+ const reloadWarnings = tripwire.warnings.length
+ await page.reload({ waitUntil: 'load' })
+ acknowledgeReloadConnectionLoss(tripwire, reloadWarnings)
+ await welcome.waitFor({ timeout: 15_000 })
+ expect(tripwire.warnings).toEqual([])
+ expect(tripwire.pageErrors).toEqual([])
+ }, 60_000)
+})
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 8a0c965a78..8316e75e3d 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -89,7 +89,7 @@ const REPLAY_PROVIDERS = [{
export interface WebScaffold {
/** The active snapshot mode this scaffold booted under. */
mode: WebSnapshotMode
- /** Browser-facing origin (http://127.0.0.1:). */
+ /** Browser-facing origin for the bound test server. */
baseUrl: string
/** Settled root context (the in-process barrier seam; headless event subscription is its sanctioned use). */
ctx: Context
@@ -166,6 +166,12 @@ export interface LaunchOptions {
}
/** Leave the current welcome notice unacknowledged; ordinary scenarios publish it as complete before browser boot. */
welcomeNoticePending?: boolean
+ /**
+ * Browse through a trusted non-loopback hostname that the browser resolves
+ * to loopback (for example `*.localhost`). The test server stays bound to
+ * 127.0.0.1; a non-resolving authority fails before Host trust is exercised.
+ */
+ remoteAuthority?: string
}
/** Dispose the booted tree and remove both owned temp roots, reporting every independent cleanup failure. */
@@ -185,6 +191,7 @@ async function cleanupScaffoldWorld(ctx: Context, workspaceCwd: string, persiste
export async function launchWebScaffold(options: LaunchOptions = {}): Promise {
requireDist()
const mode = webSnapshotMode()
+ const browserHost = options.remoteAuthority ?? '127.0.0.1'
if (mode === 'record') {
// Both owning vitest configs (web unconditionally, snapshot in record
// mode) load the repo-root .env before this file runs.
@@ -261,7 +268,13 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise schema.name).sort()
expect(names.filter(name => !RIPGREP_TOOLS.includes(name))).toEqual(EXPECTED_TOOLS)
- expect([[], RIPGREP_TOOLS]).toContainEqual(names.filter(name => RIPGREP_TOOLS.includes(name)))
+ // The packaged ripgrep binary ships with the dependency, so the pair is a
+ // fixed roster member on every host.
+ expect(names.filter(name => RIPGREP_TOOLS.includes(name))).toEqual(RIPGREP_TOOLS)
// `workspace-write` is not "the workspace and nothing else": the shared roots
// helper always admits the temp directories too. Pinning it against an
// explicit mode keeps the claim independent of this surface's default, and
diff --git a/apps/web/tests/web-search-round.e2e.ts b/apps/web/tests/web-search-round.e2e.ts
index e887fb8e35..fd395ac1ca 100644
--- a/apps/web/tests/web-search-round.e2e.ts
+++ b/apps/web/tests/web-search-round.e2e.ts
@@ -11,6 +11,7 @@ import { chromium } from 'playwright'
import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
import { credentialRef } from '@deepseek-ai/dsh-credentials'
import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { WEB_SEARCH_MAX_RESULTS } from '@deepseek-ai/dsh-tool-web'
import {
assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts,
launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold,
@@ -25,7 +26,37 @@ const QUERY = 'DeepSeek Harness snapshot search'
const PROMPT = `Use web_search to search exactly "${QUERY}". Then reply exactly SEARCH_DONE and stop.`
const SEARCH_CREDENTIAL_REF = credentialRef('DSH_WEB_SEARCH_E2E_KEY')
const SEARCH_CREDENTIAL = 'snapshot-search-key'
-const RESULT_URL = 'https://docs.example.test/search'
+
+/**
+ * Provider results the double returns, exceeding the shipped `searchMaxResults`
+ * so the seam's cap and the card's scroll container are both exercised. Each row
+ * carries a title, a snippet, and a date, so 8 kept rows exceed the `.sources`
+ * 320px max-height.
+ */
+const PROVIDER_RESULT_COUNT = 12
+
+/** One provider result's URL, by 1-based provider order. */
+function resultUrl(ordinal: number): string {
+ return `https://docs.example.test/search/${ordinal}`
+}
+
+/** One provider result's title, by 1-based provider order. */
+function resultTitle(ordinal: number): string {
+ return `Snapshot Search Result ${ordinal}`
+}
+
+/** One provider result's citation excerpt, by 1-based provider order. */
+function resultSnippet(ordinal: number): string {
+ return `Snapshot search excerpt ${ordinal}: the harness replays this source list from a local endpoint.`
+}
+
+/** One provider result's `page_age`, by 1-based provider order (July 2026 days 01..12). */
+function resultPageAge(ordinal: number): string {
+ return `2026-07-${String(ordinal).padStart(2, '0')}`
+}
+
+/** The 1-based provider ordinals, in provider order. */
+const RESULT_ORDINALS = Array.from({ length: PROVIDER_RESULT_COUNT }, (_value, index) => index + 1)
interface CapturedSearchRequest {
path: string
@@ -50,21 +81,21 @@ async function startSearchServer(captured: CapturedSearchRequest[]): Promise<{ s
content: [
{
type: 'text',
- text: 'Found one source.',
- citations: [{
+ text: `Found ${PROVIDER_RESULT_COUNT} sources.`,
+ citations: RESULT_ORDINALS.map(ordinal => ({
type: 'web_search_result_location',
- url: RESULT_URL,
- cited_text: 'Snapshot search excerpt.',
- }],
+ url: resultUrl(ordinal),
+ cited_text: resultSnippet(ordinal),
+ })),
},
{
type: 'web_search_tool_result',
- content: [{
+ content: RESULT_ORDINALS.map(ordinal => ({
type: 'web_search_result',
- url: RESULT_URL,
- title: 'Snapshot Search Result',
- page_age: '2026-07-31',
- }],
+ url: resultUrl(ordinal),
+ title: resultTitle(ordinal),
+ page_age: resultPageAge(ordinal),
+ })),
},
],
}))
@@ -141,7 +172,7 @@ describe('web e2e: shipped default web search', () => {
if (MODE === 'record') await recordFixture(scaffold, sessionId, FIXTURE)
}, 200_000)
- it.skipIf(MODE === 'record')('uses the real provider and persists the structured result', () => {
+ it.skipIf(MODE === 'record')('uses the real provider and persists the capped structured result', () => {
expect(searchRequests).toHaveLength(1)
expect(searchRequests[0]).toMatchObject({
path: '/messages',
@@ -177,16 +208,27 @@ describe('web e2e: shipped default web search', () => {
if (searchResult === undefined) throw new Error('web_search produced no durable result')
const content = searchResult.data.message.content[0]
expect(content.isError).toBe(false)
- expect(content.content.filter(block => block.type === 'text').map(block => block.text).join(''))
- .toContain(`[Snapshot Search Result](${RESULT_URL})`)
+ const rendered = content.content.filter(block => block.type === 'text').map(block => block.text).join('')
+ // The seam caps the provider's list at the shipped searchMaxResults before
+ // the tool renders it, so the kept prefix is model-visible and the dropped
+ // suffix is not.
+ for (const ordinal of RESULT_ORDINALS.slice(0, WEB_SEARCH_MAX_RESULTS)) {
+ expect(rendered).toContain(`[${resultTitle(ordinal)}](${resultUrl(ordinal)})`)
+ }
+ for (const ordinal of RESULT_ORDINALS.slice(WEB_SEARCH_MAX_RESULTS)) {
+ expect(rendered).not.toContain(resultUrl(ordinal))
+ }
+ expect(rendered).toContain(
+ `(Showing the first ${WEB_SEARCH_MAX_RESULTS} sources. Refine the query for more.)`,
+ )
expect(searchResult.data.meta).toMatchObject({
- sources: [{
- url: RESULT_URL,
- title: 'Snapshot Search Result',
- snippet: 'Snapshot search excerpt.',
- publishedAt: '2026-07-31',
- }],
- truncated: false,
+ sources: RESULT_ORDINALS.slice(0, WEB_SEARCH_MAX_RESULTS).map(ordinal => ({
+ url: resultUrl(ordinal),
+ title: resultTitle(ordinal),
+ snippet: resultSnippet(ordinal),
+ publishedAt: resultPageAge(ordinal),
+ })),
+ truncated: true,
})
})
@@ -199,6 +241,55 @@ describe('web e2e: shipped default web search', () => {
await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
})
+ it.skipIf(MODE === 'record')('scrolls the capped source list inside the fixed-height container', async () => {
+ onTestFailed(() => saveFailureShot(page, 'web-e2e-search-sources-scroll'))
+ const row = page.locator('[data-tool="web_search"] [data-expandable]').first()
+ await row.click()
+ await expect.poll(() => row.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('true')
+
+ const card = page.locator('[data-web="search"]')
+ const sources = card.locator('ol')
+ await sources.waitFor({ timeout: 10_000 })
+ // The card draws exactly the sources the model saw: the seam's cap, not the
+ // provider's list length.
+ expect(await sources.locator('li').count()).toBe(WEB_SEARCH_MAX_RESULTS)
+ // The list is complete in the DOM, so the card carries no expand control.
+ expect(await card.locator('button').count()).toBe(0)
+ expect(await card.getByText('来源列表已截断').isVisible()).toBe(true)
+
+ const geometry = await sources.evaluate((element) => {
+ const computed = getComputedStyle(element)
+ return {
+ maxHeight: computed.maxHeight,
+ overflowY: computed.overflowY,
+ scrollHeight: element.scrollHeight,
+ clientHeight: element.clientHeight,
+ }
+ })
+ expect(geometry.maxHeight).toBe('320px')
+ expect(geometry.overflowY).toBe('auto')
+ expect(geometry.scrollHeight).toBeGreaterThan(geometry.clientHeight)
+ })
+
+ it.skipIf(MODE === 'record')('reserves marker room a scroll container cannot clip back', async () => {
+ onTestFailed(() => saveFailureShot(page, 'web-e2e-search-marker-room'))
+ // `overflow-y: auto` clips inline-start overflow with no way to scroll it
+ // back, and markers are right-aligned to the content edge, so a marker wider
+ // than `padding-left` silently loses its leading digits. `searchMaxResults`
+ // is an unbounded positive integer, so measure the widest three-digit marker
+ // in the list's own font and require the shipped padding to hold it.
+ const marker = await page.locator('[data-web="search"] ol').evaluate((element) => {
+ const probe = document.createElement('span')
+ probe.style.cssText = 'position:absolute;visibility:hidden;white-space:pre;font:inherit'
+ probe.textContent = '999. '
+ element.append(probe)
+ const widest = probe.getBoundingClientRect().width
+ probe.remove()
+ return { widest, paddingLeft: parseFloat(getComputedStyle(element).paddingLeft) }
+ })
+ expect(marker.paddingLeft).toBeGreaterThanOrEqual(marker.widest)
+ })
+
it.skipIf(MODE === 'record')('stayed clean and kept the exact fixture inventory', async () => {
expect(tripwire.pageErrors).toEqual([])
expect(tripwire.warnings).toEqual([])
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index e224bb6f91..7a244ff454 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -36,6 +36,7 @@
"tests/settings-chrome.e2e.ts",
"tests/models-settings.e2e.ts",
"tests/onboarding-deepseek-config.e2e.ts",
+ "tests/remote-welcome.e2e.ts",
"tests/workspace-management.e2e.ts",
"tests/replay-round-trip.e2e.ts",
"tests/hmr-live.e2e.ts",
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 617cfb82be..f07a12f4a8 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1736,7 +1736,7 @@ Source: [`packages/fs/tool-fs/src/index.ts:24`](../packages/fs/tool-fs/src/index
## `@deepseek-ai/dsh-tool-fs-search`
-Requires: `tools` · `systemPrompt` · `bash`
+Requires: `tools` · `systemPrompt` · `subprocess`
```ts config-catalog
/** Plugin config; over-cap glob sampling is an explicit deployment choice and the remaining fields have defaults. */
@@ -1753,12 +1753,16 @@ export interface Config {
searchMetaMaxBytes?: number
/** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
rawOutputMaxBytes?: number
+ /** Terminate-escalation grace period (ms) for one search process, handed to the subprocess seam. */
+ graceMs?: number
+ /** Max bytes retained for one search's stderr tail; the excerpt is embedded in `SEARCH_*` error messages, never shown on success. */
+ stderrMaxBytes?: number
/** Cooperative tool-call timeout budget (ms) on both tools, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`. */
timeoutMs?: number
}
```
-Source: [`packages/fs/tool-fs-search/src/index.ts:71`](../packages/fs/tool-fs-search/src/index.ts)
+Source: [`packages/fs/tool-fs-search/src/index.ts:72`](../packages/fs/tool-fs-search/src/index.ts)
## `@deepseek-ai/dsh-tool-goal`
@@ -2075,6 +2079,8 @@ export interface TuiConfig {
maxModelOptions?: number
/** Maximum sessions visible at once in the resume selector. */
maxResumeOptions?: number
+ /** Maximum concurrent cold projection reads in one resume scan. */
+ resumeScanConcurrency?: number
/** User-question panel width in terminal columns, clamped to the terminal. */
questionDialogWidth?: number
/** User-question panel maximum height in terminal rows. */
@@ -2116,7 +2122,7 @@ export interface TuiThemeConfig {
}
```
-Source: [`packages/ui/tui/src/config.ts:125`](../packages/ui/tui/src/config.ts)
+Source: [`packages/ui/tui/src/config.ts:129`](../packages/ui/tui/src/config.ts)
## `@deepseek-ai/dsh-typert-loader`
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index b518f37876..6180984b3c 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2451,7 +2451,7 @@ The concrete provider retains pi-tui, focus, and terminal lifecycle state. Plugi
abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession
```
-Source: [`packages/ui/tui/src/index.ts:245`](../../packages/ui/tui/src/index.ts)
+Source: [`packages/ui/tui/src/index.ts:246`](../../packages/ui/tui/src/index.ts)
## `ctx.typert` — `TypertRegistry`
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 8419646dca..93b12fa5de 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -712,12 +712,12 @@ flowchart TD
pkg_tool_fs --> pkg_system_prompt
pkg_tool_fs --> pkg_tools
pkg_tool_fs --> pkg_user_approval
- pkg_tool_fs_search --> pkg_bash
pkg_tool_fs_search --> pkg_invariants
pkg_tool_fs_search --> pkg_llm
pkg_tool_fs_search --> pkg_retention
pkg_tool_fs_search --> pkg_session
pkg_tool_fs_search --> pkg_spill
+ pkg_tool_fs_search --> pkg_subprocess
pkg_tool_fs_search --> pkg_system_prompt
pkg_tool_fs_search --> pkg_tools
pkg_tool_str_replace_editor --> pkg_fs
@@ -939,6 +939,8 @@ flowchart TD
pkg_tui --> pkg_llm_retry
pkg_tui --> pkg_session
pkg_tui --> pkg_session_persistence
+ pkg_tui --> pkg_session_projection
+ pkg_tui --> pkg_session_projection_cache
pkg_tui --> pkg_session_query
pkg_tui --> pkg_session_reference
pkg_tui --> pkg_session_title
@@ -1201,7 +1203,7 @@ flowchart TD
| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
-| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
| [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-query`](../packages/session-query/session-query), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
@@ -1237,7 +1239,7 @@ flowchart TD
| [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
| [`repository-plugin`](../packages/cordis/repository-plugin) | `cordis` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/ui/permission) |
| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index c7754a076d..f93aedd658 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -23,7 +23,7 @@ This table connects model-visible tool names to the plugin package and service s
| `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`, `ctx.pty`, `an owning Agent at execution time` | `tool/call`, `PTY shell state`, `tool/result` | - | One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description. |
| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after successful file operations`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
| `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
-| `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. |
+| `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.subprocess`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess as ordinary foreground calls (never background tasks) — no host `rg` install and no shell layer. The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. |
| `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. |
| `@deepseek-ai/dsh-tool-goal` | `create_goal`, `get_goal`, `update_goal` | `ctx.tools`, `ctx.agents`, `ctx.goals`, `ctx.systemPrompt`, `a calling Agent in an authorized open turn` | `tool/call`, `user/message goal snapshot for mutations`, `tool/result` | - | create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds. |
| `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`, `ctx.lsp`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-local`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the schema. |
@@ -526,7 +526,7 @@ Search file contents with a ripgrep regular expression. Returns matching lines w
Source: [`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts)
-glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.
+glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess as ordinary foreground calls (never background tasks) — no host `rg` install and no shell layer. The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.
## `@deepseek-ai/dsh-tool-pty`
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index 166e0cf0fe..198daf015d 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -1,6 +1,6 @@
import { fileURLToPath } from 'node:url'
import { readFileSync } from 'node:fs'
-import { mkdir, writeFile } from 'node:fs/promises'
+import { mkdir, utimes, writeFile } from 'node:fs/promises'
import { dirname, join } from 'node:path'
import { homedir } from 'node:os'
import { expect, it } from 'vitest'
@@ -47,7 +47,6 @@ const SUBAGENT_DURABILITY_FAILURE_CONFIG = fileURLToPath(
const LSP_CONFIG = fileURLToPath(new URL('./lsp.cordis.yml', import.meta.url))
const WEB_CONFIG = fileURLToPath(new URL('../web.cordis.yml', import.meta.url))
const FS_SEARCH_CONFIG = fileURLToPath(new URL('./fs-search.cordis.yml', import.meta.url))
-const FS_SEARCH_BIN = fileURLToPath(new URL('./fixtures/fs-search-bin', import.meta.url))
const SNAPSHOTS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'snapshots')
const PACKED_CHUNKS_SOURCE = 'hook-cc-pretool-deny'
@@ -60,6 +59,33 @@ async function prepareDelimiterPathWorkspace(cwd: string): Promise {
])
}
+/**
+ * Seed the over-cap glob fixture: eight files under `tree/` with fixed mtimes,
+ * so the packaged ripgrep's `--sort=modified` order is deterministic — three
+ * files under `archive/`, one each under `docs/`, `src/`, and `test/`, plus
+ * two flat files (six top-level entries). Scoping the search to `tree/` keeps
+ * the harness's own session artifacts out of the listing.
+ */
+async function prepareFsSearchWorkspace(cwd: string): Promise {
+ const tree = join(cwd, 'tree')
+ const files: Array<[relative: string, mtime: Date]> = [
+ [join('archive', 'a.ts'), new Date(2000, 0, 1, 0, 0, 0, 1)],
+ [join('archive', 'b.ts'), new Date(2000, 0, 1, 0, 0, 0, 2)],
+ [join('archive', 'c.ts'), new Date(2000, 0, 1, 0, 0, 0, 3)],
+ [join('docs', 'guide.md'), new Date(2000, 0, 1, 0, 0, 0, 4)],
+ [join('src', 'index.ts'), new Date(2000, 0, 1, 0, 0, 0, 5)],
+ [join('test', 'spec.ts'), new Date(2000, 0, 1, 0, 0, 0, 6)],
+ ['top.txt', new Date(2000, 0, 1, 0, 0, 0, 7)],
+ ['notes.md', new Date(2000, 0, 1, 0, 0, 0, 8)],
+ ]
+ for (const [relative, mtime] of files) {
+ const target = join(tree, relative)
+ await mkdir(dirname(target), { recursive: true })
+ await writeFile(target, 'fixture\n')
+ await utimes(target, mtime, mtime)
+ }
+}
+
// FIXME: Migrate backend-oriented scenarios to the headless stream-json suite;
// this ACP suite should eventually retain only automation-protocol contracts.
@@ -153,18 +179,28 @@ const SCENARIOS: Scenario[] = [
hasModelTurn: true,
recorded: true,
},
- // The real Loader/app/bash path executes a deterministic rg stand-in at the
- // external-process seam, pinning over-cap glob sampling without depending on
- // a host-installed ripgrep binary.
+ // The real Loader/app/subprocess path executes the PACKAGED ripgrep binary
+ // against a prepared workspace whose fixed mtimes pin the
+ // `--sort=modified` order, pinning over-cap glob sampling without depending
+ // on a host-installed ripgrep binary or a PATH stand-in. POSIX-only because
+ // the displayed paths carry `/` separators the session-log comparison
+ // cannot normalize. Recorded (not authored): the assistant turn is a real
+ // model transcript; re-record with `test:snapshot:record -t fs-glob-sampling`
+ // and then `migrate:packed-session-fixtures`, which canonicalizes the live
+ // log's eager-drain-packed rows into the maximal-run layout replay produces.
+ // The recorded fixture's `request/header` config and `request/context` are
+ // normalized to the replay-produced minimal shape (the live adapter logs
+ // model capabilities like maxTokens/reasoningEffort that llm-replay has no
+ // data for), and its tool-result paths are canonicalized to `/` separators.
{
name: 'fs-glob-sampling',
hasModelTurn: true,
- recorded: false,
+ recorded: true,
+ posixOnly: true,
pinsHeader: true,
headerClass: 'fs-search',
configPath: FS_SEARCH_CONFIG,
- env: { PATH: `${FS_SEARCH_BIN}:${process.env.PATH ?? ''}` },
- posixOnly: true,
+ prepareWorkspace: prepareFsSearchWorkspace,
},
{ name: 'fs-read', hasModelTurn: true, recorded: true },
{ name: 'fs-write', hasModelTurn: true, recorded: true },
diff --git a/examples/acp-agent/tests/fixtures/fs-search-bin/rg b/examples/acp-agent/tests/fixtures/fs-search-bin/rg
deleted file mode 100755
index 181ad68837..0000000000
--- a/examples/acp-agent/tests/fixtures/fs-search-bin/rg
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/bin/sh
-printf '%s\n' \
- 'archive/a.ts' \
- 'archive/b.ts' \
- 'archive/c.ts' \
- 'old\one' \
- 'old\two' \
- 'src/index.ts' \
- 'docs/guide.md' \
- 'test/spec.ts'
diff --git a/examples/acp-agent/tests/fs-search.cordis.snapshot.yml b/examples/acp-agent/tests/fs-search.cordis.snapshot.yml
index 141691a087..0db692f5bd 100644
--- a/examples/acp-agent/tests/fs-search.cordis.snapshot.yml
+++ b/examples/acp-agent/tests/fs-search.cordis.snapshot.yml
@@ -3,7 +3,7 @@
name: '@deepseek-ai/dsh-llm-replay'
config:
providers:
- - id: deepseek
+ - id: deepseek-official
name: DeepSeek
models:
- id: deepseek-v4-pro
@@ -17,7 +17,7 @@
- id: acp-agent
name: '@deepseek-ai/dsh-acp-demo'
config:
- provider: deepseek
+ provider: deepseek-official
model: deepseek-v4-pro
persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
persistenceCompression: none
diff --git a/examples/acp-agent/tests/fs-search.cordis.yml b/examples/acp-agent/tests/fs-search.cordis.yml
index 153128f914..c86b34b8aa 100644
--- a/examples/acp-agent/tests/fs-search.cordis.yml
+++ b/examples/acp-agent/tests/fs-search.cordis.yml
@@ -16,9 +16,10 @@
- id: acp-agent
name: '@deepseek-ai/dsh-acp-demo'
config:
- provider: deepseek
+ provider: deepseek-official
model: deepseek-v4-pro
persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
+ persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'"
workspaceContext: false
skills:
enabled: false
diff --git a/examples/acp-agent/tests/goal-snapshots/goal-session/input.json b/examples/acp-agent/tests/goal-snapshots/goal-session/input.json
index 1301b9d264..f81a96af7c 100644
--- a/examples/acp-agent/tests/goal-snapshots/goal-session/input.json
+++ b/examples/acp-agent/tests/goal-snapshots/goal-session/input.json
@@ -2,13 +2,10 @@
"steps": [
{ "op": "initialize" },
{ "op": "newSession" },
- {
- "op": "promptAndWaitForAgentMessage",
- "text": "Create a durable two-round goal for the ACP snapshot, inspect it, then report readiness.",
- "waitForText": "GOAL ROUND ONE"
- },
+ { "op": "promptAndWaitForAgentMessage", "text": "Create a durable two-round goal for the ACP snapshot, inspect it, then report readiness.", "waitForText": "GOAL ROUND ONE" },
{ "op": "waitForTurnStart", "minimumTurn": 3 },
{ "op": "cancel", "waitForFile": { "path": ".dsh-snapshot-goal-cancel-ready" } },
- { "op": "waitForTurnEnd" }
+ { "op": "waitForTurnEnd" },
+ { "op": "waitForEventAfterTurnEnd", "type": "user/message" }
]
}
diff --git a/examples/acp-agent/tests/snapshots/fs-glob-sampling/input.json b/examples/acp-agent/tests/snapshots/fs-glob-sampling/input.json
index cc5fc95e59..d615bd4840 100644
--- a/examples/acp-agent/tests/snapshots/fs-glob-sampling/input.json
+++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/input.json
@@ -2,6 +2,6 @@
"steps": [
{ "op": "initialize" },
{ "op": "newSession" },
- { "op": "prompt", "text": "Call glob exactly once with pattern * and no path. Then reply with exactly GLOB_SAMPLED and nothing else." }
+ { "op": "prompt", "text": "Call glob exactly once with pattern * and path tree. Then reply with exactly GLOB_SAMPLED and nothing else." }
]
}
diff --git a/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl b/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl
index b66ffc36b4..d85c0ea447 100644
--- a/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl
@@ -1,25 +1,31 @@
-{"type":"session","version":0,"id":"f5a99d52-3eaa-4ce7-858d-61d4fd77df2a","createdAt":1785218400000,"cwd":"{{cwd}}","delegationDepth":0}
-{"type":"turn/start","seq":0,"time":1785218400001,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
-{"type":"user/message","seq":1,"time":1785218400002,"data":{"content":[{"type":"text","text":"Call glob exactly once with pattern * and no path. Then reply with exactly GLOB_SAMPLED and nothing else."}],"source":{"kind":"user"},"role":"user","id":"6790985f-1de2-42f8-a7f1-24e46d6439c7"},"surfaceOp":"append"}
-{"type":"session/title","seq":2,"time":1785218400003,"data":{"title":"Call glob exactly once with","messageSeqs":[1],"source":{"kind":"fallback"}}}
-{"type":"step/start","seq":3,"time":1785218400004,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":4,"time":1785218400005,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
-{"type":"request/context","seq":5,"time":1785483397569,"data":{"provider":"deepseek","model":"deepseek-v4-pro"}}
-{"type":"assistant/chunk","seq":6,"time":1785218400007,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":7,"time":1785218400008,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"glob-sampling-call","name":"glob","argumentsDelta":"{\"pattern\":\"*\"}"}}}
-{"type":"assistant/chunk","seq":8,"time":1785218400009,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"glob-sampling-call","name":"glob","arguments":"{\"pattern\":\"*\"}"}}}}
-{"type":"assistant/chunk","seq":9,"time":1785218400010,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":1,"outputTokens":1}}}}
-{"type":"assistant/chunk","seq":10,"time":1785483397579,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":11,"time":1785483397579,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"glob-sampling-call","name":"glob","arguments":"{\"pattern\":\"*\"}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-pro"},"id":"a127cfe5-39fb-462c-8e5a-a8c79bd0e52b"},"usage":{"inputTokens":1,"outputTokens":1}},"sourceEventSeqs":[6,7,8,9,10],"surfaceOp":"append"}
-{"type":"tool/call","seq":12,"time":1785483397579,"data":{"turn":1,"step":1,"callId":"glob-sampling-call","name":"glob","arguments":"{\"pattern\":\"*\"}"}}
-{"type":"tool/result","seq":13,"time":1785483398062,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"glob-sampling-call"},"content":[{"type":"tool-result","toolCallId":"glob-sampling-call","content":[{"type":"text","text":"archive/a.ts\nold\\one\nold\\two\nsrc/index.ts\n\n(Showing 4 of 8 paths, sampled across 4 of the 6 top-level entries this pattern matched instead of taken in modification-time order. Narrow path to inspect a specific subtree. The complete result could not be saved; narrow pattern or path to see more.)"}],"isError":false}],"role":"user","id":"2beecb2e-627d-43dc-a936-03e1dc874093"},"meta":{"shape":"paths","paths":["archive/a.ts","old\\one","old\\two","src/index.ts"],"truncated":true,"total":8}},"sourceEventSeqs":[12],"surfaceOp":"append"}
-{"type":"step/end","seq":14,"time":1785483398062,"data":{"turn":1,"step":1}}
-{"type":"step/start","seq":15,"time":1785483398072,"data":{"turn":1,"step":2}}
-{"type":"assistant/chunk","seq":16,"time":1785218400017,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":17,"time":1785218400018,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"GLOB_SAMPLED"}}}
-{"type":"assistant/chunk","seq":18,"time":1785218400019,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"GLOB_SAMPLED"}}}}
-{"type":"assistant/chunk","seq":19,"time":1785218400020,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":1,"outputTokens":1}}}}
-{"type":"assistant/chunk","seq":20,"time":1785483398078,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":21,"time":1785483398078,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"GLOB_SAMPLED"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-pro"},"id":"ce2334a4-be71-490b-a502-29186a9ced5c"},"usage":{"inputTokens":1,"outputTokens":1}},"sourceEventSeqs":[16,17,18,19,20],"surfaceOp":"append"}
-{"type":"step/end","seq":22,"time":1785483398078,"data":{"turn":1,"step":2}}
-{"type":"turn/end","seq":23,"time":1785483398079,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session","version":0,"id":"4428b809-66d5-4ea2-9a03-89de742fcda1","createdAt":1785591986068,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"turn/start","seq":0,"time":1785591986072,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1785591986073,"data":{"content":[{"type":"text","text":"Call glob exactly once with pattern * and path tree. Then reply with exactly GLOB_SAMPLED and nothing else."}],"source":{"kind":"user"},"role":"user","id":"3d05fb76-4185-460b-9c6a-8c1b2495bc9f"},"surfaceOp":"append"}
+{"type":"session/title","seq":2,"time":1785591986074,"data":{"title":"Call glob exactly once with","messageSeqs":[1],"source":{"kind":"fallback"}}}
+{"type":"step/start","seq":3,"time":1785591986092,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":4,"time":1785591986093,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":5,"time":1785591986094,"data":{"provider":"deepseek-official","model":"deepseek-v4-pro"}}
+{"type":"assistant/chunk","seq":6,"time":1785591987500,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"reasoning-chunks","seq0":7,"time0":1785591987500,"data":{"turn":1,"step":1,"index":0,"dt":[29,58,1,0,0,0,51,0,0,46,0,191,1,0,0,0,0,0,0,0,1,0,0,0,0,0,99],"texts":["The"," user"," wants"," me"," to"," call"," glob"," exactly"," once"," with"," pattern"," *"," and"," path"," tree",","," then"," reply"," with"," exactly"," \"","G","LOB","_S","AM","PL","ED","\"."]}}
+{"type":"assistant/chunk","seq":35,"time":1785591988034,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":36,"time0":1785591988035,"data":{"turn":1,"step":1,"index":1,"dt":[55,0,0,1,45,0,0,57,14,0,0,0,0,77,0,0,54],"id":"call_00_1cLZjkCW0vxVw0e3xVfh3430","name":"glob","args":["","{","\"","pattern","\"",": ","\"","*","\"",", ","\"","path","\"",": ","\"","tree","\"","}"]}}
+{"type":"assistant/chunk","seq":54,"time":1785591988427,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call glob exactly once with pattern * and path tree, then reply with exactly \"GLOB_SAMPLED\"."}}}}
+{"type":"assistant/chunk","seq":55,"time":1785591988427,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_1cLZjkCW0vxVw0e3xVfh3430","name":"glob","arguments":"{\"pattern\": \"*\", \"path\": \"tree\"}"}}}}
+{"type":"assistant/chunk","seq":56,"time":1785591988427,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":1286,"outputTokens":87,"cacheReadTokens":0,"reasoningTokens":28}}}}
+{"type":"assistant/chunk","seq":57,"time":1785591988427,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":58,"time":1785591988430,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to call glob exactly once with pattern * and path tree, then reply with exactly \"GLOB_SAMPLED\"."},{"type":"tool-call","id":"call_00_1cLZjkCW0vxVw0e3xVfh3430","name":"glob","arguments":"{\"pattern\": \"*\", \"path\": \"tree\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-pro"},"id":"b74cbab2-c017-4e44-8c09-a7745d8b274a"},"usage":{"inputTokens":1286,"outputTokens":87,"cacheReadTokens":0,"reasoningTokens":28}},"sourceEventSeqs":[6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"surfaceOp":"append"}
+{"type":"tool/call","seq":59,"time":1785591988431,"data":{"turn":1,"step":1,"callId":"call_00_1cLZjkCW0vxVw0e3xVfh3430","name":"glob","arguments":"{\"pattern\": \"*\", \"path\": \"tree\"}"}}
+{"type":"tool/result","seq":60,"time":1785591988476,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_1cLZjkCW0vxVw0e3xVfh3430"},"content":[{"type":"tool-result","toolCallId":"call_00_1cLZjkCW0vxVw0e3xVfh3430","content":[{"type":"text","text":"tree/archive/a.ts\ntree/docs/guide.md\ntree/src/index.ts\ntree/test/spec.ts\n\n(Showing 4 of 8 paths, sampled across 4 of the 6 top-level entries this pattern matched instead of taken in modification-time order. Narrow path to inspect a specific subtree. The complete result could not be saved; narrow pattern or path to see more.)"}],"isError":false}],"role":"user","id":"10284f88-4890-49ed-9a17-56edbd6bfaa7"},"meta":{"shape":"paths","paths":["tree/archive/a.ts","tree/docs/guide.md","tree/src/index.ts","tree/test/spec.ts"],"truncated":true,"total":8}},"sourceEventSeqs":[59],"surfaceOp":"append"}
+{"type":"step/end","seq":61,"time":1785591988476,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":62,"time":1785591988482,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":63,"time":1785591989939,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"reasoning-chunks","seq0":64,"time0":1785591989939,"data":{"turn":1,"step":2,"index":0,"dt":[0,0,0,49,36,103,1,0,0,326,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,14],"texts":["The"," glob"," result"," shows"," it"," was"," sampled"," -"," ","4"," of"," ","8"," paths"," across"," ","4"," of"," ","6"," top","-level"," entries","."," I"," need"," to"," reply"," with"," exactly"," \"","G","LOB","_S","AM","PL","ED","\""," as"," instructed","."]}}
+{"type":"assistant/chunk","seq":105,"time":1785591990470,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"text-chunks","seq0":106,"time0":1785591990470,"data":{"turn":1,"step":2,"index":1,"dt":[0,0,0,48,0],"texts":["G","LOB","_S","AM","PL","ED"]}}
+{"type":"assistant/chunk","seq":112,"time":1785591990526,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The glob result shows it was sampled - 4 of 8 paths across 4 of 6 top-level entries. I need to reply with exactly \"GLOB_SAMPLED\" as instructed."}}}}
+{"type":"assistant/chunk","seq":113,"time":1785591990527,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"GLOB_SAMPLED"}}}}
+{"type":"assistant/chunk","seq":114,"time":1785591990527,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":188,"outputTokens":48,"cacheReadTokens":1280,"reasoningTokens":41}}}}
+{"type":"assistant/chunk","seq":115,"time":1785591990527,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":116,"time":1785591990527,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The glob result shows it was sampled - 4 of 8 paths across 4 of 6 top-level entries. I need to reply with exactly \"GLOB_SAMPLED\" as instructed."},{"type":"text","text":"GLOB_SAMPLED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-pro"},"id":"dd3a9c28-43b2-4fdc-8089-1547309a71c0"},"usage":{"inputTokens":188,"outputTokens":48,"cacheReadTokens":1280,"reasoningTokens":41}},"sourceEventSeqs":[63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115],"surfaceOp":"append"}
+{"type":"step/end","seq":117,"time":1785591990527,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":118,"time":1785591990528,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/knip.json b/knip.json
index f1a6efef71..71ee4faa3c 100644
--- a/knip.json
+++ b/knip.json
@@ -567,9 +567,6 @@
"project": [
"src/**/*.ts",
"tests/**/*.ts"
- ],
- "ignoreBinaries": [
- "rg"
]
},
"packages/mcp/mcp-client": {
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 974e3014d6..a636d8bc49 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/README.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/client/connection/README.md
-README.md: c8b7c4787cbcbf6a202fb944459a589fcadd7c8d
-README.zh.md: 693420183ffa4fb20e1fecbff523a12261a45d45
+README.md: f537fee3273e3b5d2411197cf1a1a6e0d34af5f9
+README.zh.md: a29d2c00e7df3f6290a03ffdad59b70b43702aca
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index c8b7c4787c..f537fee327 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,7 +2,7 @@
English | [中文](README.zh.md)
-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`, reads included, since describing returns the exposed configuration and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. Loopback hostname classification stays package-internal: the `/api` Host fence uses it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`, reads included, since describing returns the exposed configuration and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.
## /api browser-trust fence
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index 693420183f..a29d2c00e7 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@
[English](README.md) | 中文
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`，读取也在内，因为 describe 会返回已暴露的配置，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`，读取也在内，因为 describe 会返回已暴露的配置，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。
## /api 浏览器信任栅栏
diff --git a/packages/client/connection/src/api-request-trust.ts b/packages/client/connection/src/api-request-trust.ts
index 8c1bddd631..ecb180dca7 100644
--- a/packages/client/connection/src/api-request-trust.ts
+++ b/packages/client/connection/src/api-request-trust.ts
@@ -14,6 +14,7 @@
*/
import type { IncomingHttpHeaders } from 'node:http'
+import { isLoopbackHostname } from './loopback-hostname.ts'
/** The request facts the fence reads (structural subset of IncomingMessage). */
interface ApiTrustRequest {
@@ -25,14 +26,6 @@ function header(headers: IncomingHttpHeaders, name: string): string | undefined
return typeof value === 'string' ? value : undefined
}
-function isLoopbackHostname(hostname: string): boolean {
- if (hostname === 'localhost' || hostname === '[::1]') return true
- const parts = hostname.split('.')
- return parts.length === 4
- && parts[0] === '127'
- && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
-}
-
/** Normalized URL of a Host-header authority (hostname lowercased, default port stripped, IPv6 bracketed), or undefined when unparsable. */
function parseAuthority(authority: string): URL | undefined {
try {
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index a7ebfbbd86..9e33e63ce2 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -8,6 +8,7 @@ import type { IApiClient } from './api.ts'
import { ConnectionController, type ConnectionConfig, type ConnectionSinks, type ConnectionState } from './connection.ts'
import { FixtureApiClient } from './fixture.ts'
import { WebApiClient } from './web-api-client.ts'
+import { isLoopbackHostname } from '../loopback-hostname.ts'
// ---- Contract re-exports (browser-safe apiproxy channels + core types) ----
export type {
@@ -48,6 +49,8 @@ export const inject: string[] = []
export interface ConnectionHandle {
/** Shared api client (fixture or real, decided at boot from the page URL). */
readonly api: IApiClient
+ /** Whether the current page authority is loopback; non-browser contexts default to true. */
+ readonly isLoopback: boolean
/**
* Start the connect/pump/reconnect loop with the consumer's frame sinks.
* One consumer owns the streams (the runtime object layer); a second call
@@ -64,11 +67,13 @@ export interface ConnectionHandle {
* @param ctx - client cordis context.
*/
export function apply(ctx: Context): void {
- const fixture = typeof location !== 'undefined' && new URLSearchParams(location.search).has('fixture')
+ const pageLocation = typeof location === 'undefined' ? undefined : location
+ const fixture = pageLocation !== undefined && new URLSearchParams(pageLocation.search).has('fixture')
const api: IApiClient = fixture ? new FixtureApiClient() : new WebApiClient()
let started = false
const handle: ConnectionHandle = {
api,
+ isLoopback: pageLocation === undefined || isLoopbackHostname(pageLocation.hostname),
start(sinks, config) {
if (started) throw new Error('connection: the stream loop is already owned by another consumer')
started = true
diff --git a/packages/client/connection/src/loopback-hostname.ts b/packages/client/connection/src/loopback-hostname.ts
new file mode 100644
index 0000000000..fe2fe93fc9
--- /dev/null
+++ b/packages/client/connection/src/loopback-hostname.ts
@@ -0,0 +1,18 @@
+/**
+ * Browser-safe, zero-dependency loopback classification shared by the `/api`
+ * Host fence and the package's `ctx.connection` state. The predicate stays
+ * package-internal; client plugins consume the derived state through Cordis.
+ */
+
+/**
+ * Whether a normalized URL hostname names the local loopback authority.
+ * @param hostname - WHATWG URL hostname (IPv6 literals retain brackets).
+ * @returns true for localhost, IPv6 loopback, or any IPv4 address in 127/8.
+ */
+export function isLoopbackHostname(hostname: string): boolean {
+ if (hostname === 'localhost' || hostname === '[::1]') return true
+ const parts = hostname.split('.')
+ return parts.length === 4
+ && parts[0] === '127'
+ && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index 6892dc7721..43c71dffb7 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -8,7 +8,7 @@ import { apply, type ConnectionHandle } from '../src/client/index.ts'
import { FixtureApiClient } from '../src/client/fixture.ts'
import { WebApiClient } from '../src/client/web-api-client.ts'
-type Win = { location?: { search: string } }
+type Win = { location?: { hostname: string; search: string } }
afterEach(() => {
delete (globalThis as Win).location
@@ -24,20 +24,28 @@ async function mount(): Promise {
describe('connection client apply', () => {
it('mounts ctx.connection with the real client when no ?fixture switch is present', async () => {
- ;(globalThis as Win).location = { search: '' }
+ ;(globalThis as Win).location = { hostname: 'localhost', search: '' }
const handle = await mount()
expect(handle.api).toBeInstanceOf(WebApiClient)
+ expect(handle.isLoopback).toBe(true)
})
it('selects the fixture client under ?fixture (and with no location at all stays real)', async () => {
- ;(globalThis as Win).location = { search: '?fixture' }
+ ;(globalThis as Win).location = { hostname: '127.0.0.1', search: '?fixture' }
expect((await mount()).api).toBeInstanceOf(FixtureApiClient)
delete (globalThis as Win).location
- expect((await mount()).api).toBeInstanceOf(WebApiClient)
+ const handle = await mount()
+ expect(handle.api).toBeInstanceOf(WebApiClient)
+ expect(handle.isLoopback).toBe(true)
+ })
+
+ it('reports non-loopback page authority through the connection handle', async () => {
+ ;(globalThis as Win).location = { hostname: '192.0.2.20', search: '' }
+ expect((await mount()).isLoopback).toBe(false)
})
it('start() hands out one loop, rejects a second consumer, and stop() aborts the streams', async () => {
- ;(globalThis as Win).location = { search: '?fixture' }
+ ;(globalThis as Win).location = { hostname: 'localhost', search: '?fixture' }
const handle = await mount()
// config omitted: the `config ?? {}` default arm is part of the surface.
const loop = handle.start({})
@@ -46,7 +54,7 @@ describe('connection client apply', () => {
})
it('WebApiClient carries requests over globalThis.fetch', async () => {
- ;(globalThis as Win).location = { search: '' }
+ ;(globalThis as Win).location = { hostname: 'localhost', search: '' }
const handle = await mount()
const original = globalThis.fetch
const seen: string[] = []
diff --git a/packages/client/connection/tests/loopback-hostname.spec.ts b/packages/client/connection/tests/loopback-hostname.spec.ts
new file mode 100644
index 0000000000..d0eaf3e0c4
--- /dev/null
+++ b/packages/client/connection/tests/loopback-hostname.spec.ts
@@ -0,0 +1,18 @@
+/** Shared loopback-hostname semantics for the Host fence and browser UI. */
+
+import { describe, expect, it } from 'vitest'
+import { isLoopbackHostname } from '../src/loopback-hostname.ts'
+
+describe('isLoopbackHostname', () => {
+ it('accepts localhost, IPv6 loopback, and the whole IPv4 127/8 block', () => {
+ for (const hostname of ['localhost', '[::1]', '127.0.0.1', '127.8.9.10', '127.255.255.255']) {
+ expect(isLoopbackHostname(hostname)).toBe(true)
+ }
+ })
+
+ it('refuses malformed and non-loopback hostnames', () => {
+ for (const hostname of ['remote.localhost', '::1', '128.0.0.1', '127.0.0', '127.0.0.256', '127.0.0.-1']) {
+ expect(isLoopbackHostname(hostname)).toBe(false)
+ }
+ })
+})
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index d389efe319..e5691a0619 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -26,6 +26,7 @@ async function mount(): Promise {
const bench: Bench = { ctx, api, sinks: undefined, stopped: 0 }
const handle: ConnectionHandle = {
api,
+ isLoopback: true,
start: (sinks) => {
bench.sinks = sinks
return { stop: () => { bench.stopped += 1 } }
diff --git a/packages/client/runtime/tests/wire-events.spec.ts b/packages/client/runtime/tests/wire-events.spec.ts
index fd7858d60c..21e7f1fc06 100644
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -20,6 +20,7 @@ async function mount(): Promise {
const bench: Bench = { ctx, sinks: undefined }
const handle: ConnectionHandle = {
api,
+ isLoopback: true,
start: (sinks) => {
bench.sinks = sinks
return { stop: () => {} }
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index da6ea1a597..bf1e21a541 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
-README.md: 78572ba0ab3ce9475dba31dee8844017564e2a18
-README.zh.md: 7708e980e24f4ea4365fbbacd641a5be6c61b138
+README.md: 7d3a4b5fe07cc8858c2f2059e6f65b6e27602b4d
+README.zh.md: d93af91381157bb4e8e4b6a14ad00edecd505246
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 78572ba0ab..7d3a4b5fe0 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -22,7 +22,7 @@ Generic tool rows classify the built-in bash, read, search, write, edit, and run
A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card resident below its summary row; since tool rows are no longer details-panel click targets, the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which is what keeps a summary surface bounded — the panel stays the single-call reading surface. Inline output is licensed per render intent — the terminal and web cards, each with its own bound. A Bash execution failure that settles on the generic path instead exposes its original arguments and full error through the same bounded IN/OUT disclosure, while successful generic results such as a background-start acknowledgement remain summary-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)).
-A tool call declaring the `web` render intent renders its web retrieval inline, at both conversation render sites, through ui-primitives' `WebBlock`. `contract/web-card-model.ts` is the single derivation from the snapshot's `resultView`, mirroring the terminal card, so the sites cannot disagree about what a web call shows; it yields null — the generic path — for a running call, a non-web result view, a generic result view, a `card` tag this client version does not know, or a web card whose `kind` this client version does not know (a newer host's value, which the wire cannot be trusted to be `search` or `fetch`). The keyed `WebRow` registers one component under both `web_search` and `web_fetch`, discriminating on the tool name only for its icon and title; it composes the shared `ToolRow`, feeding the card as ToolRow's `web` body, so the retrieval is the row's collapsed-by-default expanded card (the same unified expand every card row has). A web-declaring tool without a keyed row lands on the `GenericToolCard` fallback, which routes the card through ToolRow the same way, and the details panel renders it at the primitive's full source allowance and, below the card, the flattened model-visible result content — a fetch body is readable only there, since its card carries only the URL and status. Rows cap at `CHAT_WEB_MAX_SOURCES` (8) against the panel's 16, the same summary-versus-reading split the terminal card draws ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)).
+A tool call declaring the `web` render intent renders its web retrieval inline, at both conversation render sites, through ui-primitives' `WebBlock`. `contract/web-card-model.ts` is the single derivation from the snapshot's `resultView`, mirroring the terminal card, so the sites cannot disagree about what a web call shows; it yields null — the generic path — for a running call, a non-web result view, a generic result view, a `card` tag this client version does not know, or a web card whose `kind` this client version does not know (a newer host's value, which the wire cannot be trusted to be `search` or `fetch`). The keyed `WebRow` registers one component under both `web_search` and `web_fetch`, discriminating on the tool name only for its icon and title; it composes the shared `ToolRow`, feeding the card as ToolRow's `web` body, so the retrieval is the row's collapsed-by-default expanded card (the same unified expand every card row has). A web-declaring tool without a keyed row lands on the `GenericToolCard` fallback, which routes the card through ToolRow the same way, and the details panel renders it and, below the card, the flattened model-visible result content — a fetch body is readable only there, since its card carries only the URL and status. Both render sites show the same complete source list — the one the tool returned and the model saw — bounded only by the card's own scroll container height, with no row-versus-panel cap ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md), [source scroll](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)).
A `read` call declaring the `read` render intent renders the returned file window inline, at both conversation render sites, through ui-primitives' `ReadBlock` — the line-numbered, syntax-highlighted content the tool projects. `contract/read-card-model.ts` is the single derivation from the snapshot's `resultView`; the read card is result-side only (a call carries no file content until `execute` returns), so a running read shows its summary alone and it yields null — the generic path — for a non-read result view or a `card` tag this client version does not know. The keyed `ReadRow` composes the shared `ToolRow`, feeding the card as ToolRow's `read` body, so it is the row's collapsed-by-default expanded card; the summary stays a path link that opens the file through the host. The render-site fallback and the details panel are read-aware too. Rows cap at `CHAT_READ_MAX_LINES` (8) against the panel's 16 ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)).
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 7708e980e2..d93af91381 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -20,7 +20,7 @@ Think 行默认保持折叠，并在不展开思维链的情况下暴露实时
声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片常驻在摘要行下方；由于工具行已不再是详情面板的点击目标，卡片的复制与展开控件就是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，正是这一点让摘要面保持有界——面板仍是单次调用的阅读面。内联输出按渲染意图开放——终端卡片与 web 卡片，各有自己的上限。若 Bash 执行失败时落在通用路径，则改用同样有界的 IN/OUT 展开区暴露原始参数和完整错误；后台启动确认等成功的通用结果仍只显示摘要（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。
-声明 `web` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `WebBlock` 内联渲染其 web 检索。`contract/web-card-model.ts` 是从快照的 `resultView` 推导的唯一位置，镜像终端卡片，因此两个渲染点不可能对一次 web 调用的显示产生分歧；对运行中的调用、非 web 的 result view、generic result view、本客户端版本不认识的 `card` 标签，或本客户端版本不认识 `kind` 的 web 卡片（更新的 host 发来的值，wire 上不可信其为 `search` 或 `fetch`），它返回 null，落回通用路径。键控的 `WebRow` 把一个组件注册在 `web_search` 与 `web_fetch` 两个键下，仅根据工具名判别以选取图标与标题；它组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `web` body 传入，因此检索成为该行默认折叠的展开卡片（与每个卡片行相同的统一展开交互）。没有自己键控行的 web 声明工具落到 `GenericToolCard` 兜底，它以同样方式经 ToolRow 渲染卡片，详情面板则以原语的完整 source 额度渲染它，并在卡片下方渲染摊平的模型可见结果内容——fetch 正文只在此处可读，因为其卡片只携带 URL 和状态。行的上限是 `CHAT_WEB_MAX_SOURCES`（8），面板为 16，与终端卡片所画的摘要面对阅读面的同一划分（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)）。
+声明 `web` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `WebBlock` 内联渲染其 web 检索。`contract/web-card-model.ts` 是从快照的 `resultView` 推导的唯一位置，镜像终端卡片，因此两个渲染点不可能对一次 web 调用的显示产生分歧；对运行中的调用、非 web 的 result view、generic result view、本客户端版本不认识的 `card` 标签，或本客户端版本不认识 `kind` 的 web 卡片（更新的 host 发来的值，wire 上不可信其为 `search` 或 `fetch`），它返回 null，落回通用路径。键控的 `WebRow` 把一个组件注册在 `web_search` 与 `web_fetch` 两个键下，仅根据工具名判别以选取图标与标题；它组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `web` body 传入，因此检索成为该行默认折叠的展开卡片（与每个卡片行相同的统一展开交互）。没有自己键控行的 web 声明工具落到 `GenericToolCard` 兜底，它以同样方式经 ToolRow 渲染卡片，详情面板渲染它，并在卡片下方渲染摊平的模型可见结果内容——fetch 正文只在此处可读，因为其卡片只携带 URL 和状态。两个渲染点显示同一份完整来源列表——工具返回、模型看到的那一份——仅受卡片自身滚动容器的高度约束，不存在行与面板的两级上限（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)、[来源滚动](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)）。
声明 `read` 渲染意图的 `read` 调用，会在两个对话渲染点上都通过 ui-primitives 的 `ReadBlock` 内联渲染返回的文件窗口——工具投影出的带行号、语法高亮的内容。`contract/read-card-model.ts` 是从快照的 `resultView` 推导的唯一位置；read 卡片是仅结果侧的(调用在 `execute` 返回前不携带文件内容)，所以运行中的 read 只显示摘要，且对非 read 的 result view 或本客户端版本不认识的 `card` 标签返回 null，落回通用路径。键控的 `ReadRow` 组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `read` body 传入，因此它是该行默认折叠的展开卡片；摘要仍是一个经 host 打开文件的路径链接。渲染点兜底行与详情面板同样感知 read。行的上限是 `CHAT_READ_MAX_LINES`（8），面板为 16（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)）。
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
index fa4be6179a..c299f43bda 100644
--- a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
@@ -30,7 +30,6 @@ import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
import { CHAT_DIFF_MAX_LINES, type DiffCardModel } from '../contract/diff-card-model.ts'
import { CHAT_READ_MAX_LINES, type ReadCardModel } from '../contract/read-card-model.ts'
import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../contract/search-card-model.ts'
-import { CHAT_WEB_MAX_SOURCES } from '../contract/web-card-model.ts'
import { terminalBlockLabels, type TerminalCardModel } from '../contract/terminal-card-model.ts'
import type { ToolRowState, ToolRowVariant } from '../contract/tool-call-model.ts'
import { DisclosureRow } from './DisclosureRow.tsx'
@@ -276,7 +275,7 @@ export function ToolRow({
)
: webBody !== null
- ? {body}
: (
diff --git a/packages/client/ui-conversation/src/client/contract/web-card-model.ts b/packages/client/ui-conversation/src/client/contract/web-card-model.ts
index f2b15e023a..270b387e62 100644
--- a/packages/client/ui-conversation/src/client/contract/web-card-model.ts
+++ b/packages/client/ui-conversation/src/client/contract/web-card-model.ts
@@ -15,16 +15,6 @@
import type { WebBlockProps } from '@deepseek-ai/dsh-client-ui-primitives'
import type { ToolCallBlock } from './tool-call-model.ts'
-/**
- * Sources the chat row's web body shows before collapsing the middle — half
- * the primitive's own default, which the details panel keeps. A chat row is a
- * summary surface inside the message flow: the flow must stay scannable across
- * many calls, while the details panel is the single-call reading surface. A
- * design constant of this UI's row geometry, not a deployment choice, so it is
- * fixed here rather than a plugin Config field.
- */
-export const CHAT_WEB_MAX_SOURCES = 8
-
/**
* Derive the web-card props for a tool call, or null when this call is not a
* web card and belongs on the generic path.
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index 01c55c5fae..1114236143 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -180,13 +180,12 @@ function OutputBody({ material, cwd, t }: { material: CallMaterial; cwd: string
)
}
const web = webCardModel(material.block)
- // Full source-list allowance here (the panel is the single-call reading
- // surface); the chat rows cap it at CHAT_WEB_MAX_SOURCES. Below the card the
- // panel also renders the flattened result content — the model-visible text
- // the card does not carry verbatim (a web_fetch card shows only the URL and
- // status, so its fetched body lives only here; a search card's answer and
- // sources are structured, so the flattened form repeats them as the raw text
- // the model saw).
+ // The card shows every source the tool returned (the same list the model saw),
+ // scrolling within its own capped height. Below the card the panel also renders
+ // the flattened result content — the model-visible text the card does not carry
+ // verbatim (a web_fetch card shows only the URL and status, so its fetched body
+ // lives only here; a search card's answer and sources are structured, so the
+ // flattened form repeats them as the raw text the model saw).
if (web !== null) {
const settled = 'kind' in material.block ? material.block : null
const body = settled === null ? '' : resultText(settled)
diff --git a/packages/client/ui-conversation/tests/web-card.spec.tsx b/packages/client/ui-conversation/tests/web-card.spec.tsx
index 974df2264a..bf4228f346 100644
--- a/packages/client/ui-conversation/tests/web-card.spec.tsx
+++ b/packages/client/ui-conversation/tests/web-card.spec.tsx
@@ -17,7 +17,7 @@ import type {
import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
import type { SelectionTarget, ToolRowOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { CHAT_WEB_MAX_SOURCES, webCardModel } from '../src/client/contract/web-card-model.ts'
+import { webCardModel } from '../src/client/contract/web-card-model.ts'
import { createChatStore } from '../src/client/stores.ts'
import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx'
import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
@@ -135,8 +135,7 @@ describe('chat row web body', () => {
fireEvent.click(view.container.querySelector('[data-expandable]')!)
}
- it('the WebRow collapses to the summary row, expanding to the search card capped tighter than the panel', () => {
- expect(CHAT_WEB_MAX_SOURCES).toBeLessThan(16)
+ it('the WebRow collapses to the summary row, expanding to the full search card', () => {
const view = render(`, and the expand control is a marker-less ` ` so the `` stays valid HTML. When a search legitimately returns no answer and no sources, the card shows an explicit empty-state note rather than a blank `` (the chat row does not surface the raw result content). A `fetch` shows a compact summary: the linked final URL and its HTTP status. Both mark a capped retrieval. Rationale: [the web result card note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md).
+`WebBlock` renders a completed web retrieval, one component for both kinds of the `web` render intent (discriminated by `kind`). A `search` shows an optional provider answer (through `MarkdownText`) above an ordered citation list: each source is a safe external link labelled by its title, or its hostname, falling back to the raw URL when the URL does not parse or has no hostname (a `file:`/`data:` URL) so a label is never blank; its snippet and publication date render below it. Only http(s) URLs become anchors (`target`/`rel` set) — the http(s) subset of the allowlist `MarkdownText` applies to untrusted links (it also permits `mailto:`, excluded here); any other URL renders as plain text. The whole list renders in one fixed-height scroll container (`max-height: 320px`, `overflow-y: auto`), so a list taller than that scrolls vertically in place instead of growing the card; `` pins each source's citation number, contiguous from 1, rather than leaving it to the ``'s implicit count. When a search legitimately returns no answer and no sources, the card shows an explicit empty-state note rather than a blank `` (the chat row does not surface the raw result content). A `fetch` shows a compact summary: the linked final URL and its HTTP status. Both mark a capped retrieval. Rationale: [the web result card note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) and [the source scroll note](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md).
## Model Experience
@@ -45,5 +45,5 @@ None; this package neither assembles nor sends a provider request.
- **Glyph-level icons are redrawn approximations** — the fish logo (and the sparkle held by ui-conversation) come from font glyphs whose vector geometry is not exportable from the local design data; hand-authored recreations stand in until an exact export path exists.
- **Pill and Input have no design source** — both atoms are self-defined; the sidebar search field and view-tab strip that resemble them are consumer-owned compositions, not these atoms.
- **StateDot `Active` variant is a hidden placeholder in the design** — not implemented; the four shipped states (done/warning/ongoing/error) are the complete P-I surface.
-- **User-facing copy localizes through label props, defaulting to the original Chinese literals** — the atoms are zero-cordis and cannot reach `ctx.locale`, so `HoverCard` (`copyLabel`/`copiedLabel`), `TerminalBlock` (`labels`), `JsonTree` (`labels`), `CodeBlock` (`copyLabel`/`copiedLabel`), `MarkdownText` (`codeLabels`), `JsonBlock` (`truncatedLabel`), `ConnectionBanner` (`label`), and `Modal` (`closeLabel`) take their copy as optional props with the previous hardcoded strings as defaults. Localized plugins pass dictionary-driven labels from their own `t` seat; a consumer that passes nothing renders exactly the pre-localization output. `WebBlock` does not yet follow this pattern: its source expand/collapse controls, source-list and fetch truncation notes, and empty-search note stay inline Chinese, pending the same label-prop treatment.
+- **User-facing copy localizes through label props, defaulting to the original Chinese literals** — the atoms are zero-cordis and cannot reach `ctx.locale`, so `HoverCard` (`copyLabel`/`copiedLabel`), `TerminalBlock` (`labels`), `JsonTree` (`labels`), `CodeBlock` (`copyLabel`/`copiedLabel`), `MarkdownText` (`codeLabels`), `JsonBlock` (`truncatedLabel`), `ConnectionBanner` (`label`), and `Modal` (`closeLabel`) take their copy as optional props with the previous hardcoded strings as defaults. Localized plugins pass dictionary-driven labels from their own `t` seat; a consumer that passes nothing renders exactly the pre-localization output. `WebBlock` does not yet follow this pattern: its source-list and fetch truncation notes and its empty-search note stay inline Chinese, pending the same label-prop treatment.
- **`TerminalBlock` is not a terminal emulator** — it renders settled or still-running command output, not an interactive session: SGR color and attributes are honored, and so are the in-line cursor movements a progress line uses — carriage return, backspace, erase-in-line, tab stops and character width. Absolute cursor positioning, screen clearing, and alternate-screen sequences are stripped. Basic-16 magenta and cyan have no token equivalent and stay literal rgb.
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index e326846dc2..21226ab211 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -30,7 +30,7 @@
## Web 检索
-`WebBlock` 渲染一次已完成的 web 检索，用一个组件绘制 `web` 渲染意图的两种 kind（由 `kind` 判别）。`search` 在有序引用列表上方显示可选的 provider answer（通过 `MarkdownText`）：每个 source 是一个安全外链，以其标题为标签，或以其主机名为标签，当 URL 无法解析或没有主机名（`file:`/`data:` URL）时回退到原始 URL，因此标签绝不为空；其下渲染 snippet 与发布日期。只有 http(s) URL 会成为锚点（设置 `target`/`rel`）——这是 `MarkdownText` 对不受信任链接所用 allowlist 的 http(s) 子集（该 allowlist 还允许 `mailto:`，此处排除）；任何其他 URL 渲染为纯文本。长列表在 `maxSources`（默认 16，即 TerminalBlock 的切分算术）处折叠为头部/尾部；折叠的尾部通过 `` 保留每个 source 原始的引用编号，展开控件是无 marker 的 ` `，使 `` 保持为合法 HTML。当一次 search 合法地返回无 answer 且无 source 时，卡片显示一个明确的空状态提示，而不是空的 ``（chat 行不呈现原始 result content）。`fetch` 显示一个紧凑摘要：带链接的最终 URL 及其 HTTP 状态。两者都会标记一次被截断的检索。原理：[Web result 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)。
+`WebBlock` 渲染一次已完成的 web 检索，用一个组件绘制 `web` 渲染意图的两种 kind（由 `kind` 判别）。`search` 在有序引用列表上方显示可选的 provider answer（通过 `MarkdownText`）：每个 source 是一个安全外链，以其标题为标签，或以其主机名为标签，当 URL 无法解析或没有主机名（`file:`/`data:` URL）时回退到原始 URL，因此标签绝不为空；其下渲染 snippet 与发布日期。只有 http(s) URL 会成为锚点（设置 `target`/`rel`）——这是 `MarkdownText` 对不受信任链接所用 allowlist 的 http(s) 子集（该 allowlist 还允许 `mailto:`，此处排除）；任何其他 URL 渲染为纯文本。整份列表渲染在一个定高滚动容器里（`max-height: 320px`、`overflow-y: auto`），因此超出该高度的列表在原地纵向滚动，而不是把卡片撑高；`` 固定每个 source 的引用编号，从 1 起连续，而不依赖 `` 的隐式计数。当一次 search 合法地返回无 answer 且无 source 时，卡片显示一个明确的空状态提示，而不是空的 ``（chat 行不呈现原始 result content）。`fetch` 显示一个紧凑摘要：带链接的最终 URL 及其 HTTP 状态。两者都会标记一次被截断的检索。原理：[Web result 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)与[来源滚动笔记](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)。
## 模型体验
@@ -45,5 +45,5 @@
- **字形级图标是重新绘制的近似版本**：鱼形标志（以及 ui-conversation 持有的闪光图标）来自字体字形，而本地设计数据无法导出其矢量几何；在获得精确导出路径前，使用手工重建版本代替。
- **Pill 与 Input 没有设计来源**：两个原子组件均自行定义；与其相似的侧边栏搜索字段和视图标签条由消费方组合，不是这些原子组件。
- **StateDot 的 `Active` 变体是设计中的隐藏占位符**：尚未实现；已交付的四种状态（done/warning/ongoing/error）构成完整的 P-I 表层。
-- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源展开/收起控件、来源列表与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
+- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源列表与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
- **`TerminalBlock` 不是终端模拟器**：它渲染已结束或仍在运行的命令输出，而不是交互式会话：SGR 颜色与属性会被遵循，进度行所用的行内光标移动同样被遵循——回车、退格、行内擦除、制表位与字符宽度。绝对光标定位、清屏与备用屏幕序列会被剥离。基础 16 色中的洋红与青色没有对应 token，保持字面 rgb。
diff --git a/packages/client/ui-primitives/src/WebBlock.module.css b/packages/client/ui-primitives/src/WebBlock.module.css
index 8aad5872ba..9f1a57be1d 100644
--- a/packages/client/ui-primitives/src/WebBlock.module.css
+++ b/packages/client/ui-primitives/src/WebBlock.module.css
@@ -1,7 +1,8 @@
/* Geometry mirrors CodeBlock/TerminalBlock (12px radius, code-block surface,
16px vertical margin) so a web card, a terminal card, and a fenced code block
- read as one family. A source list is prose, not aligned output, so it wraps
- normally rather than scrolling horizontally like a terminal card's output. */
+ read as one family. A source list is prose, not aligned output, so each row
+ wraps horizontally rather than scrolling sideways like a terminal card; the
+ list as a whole scrolls vertically within a capped height (see .sources). */
.block {
--dsl-web-radius: 12px;
@@ -27,13 +28,29 @@
margin-bottom: 0;
}
-/* The citation list: ordered so each source reads as a numbered reference. */
+/* The citation list: ordered so each source reads as a numbered reference. The
+ whole list — the sources the tool returned, matching what the model saw —
+ renders here; a max-height caps the card so a long list scrolls in place
+ rather than growing the card unbounded. The height is a design constant of the
+ card's geometry, not a deployment choice, so it lives here rather than a plugin
+ config field.
+
+ `overflow-y` makes this a scroll container, which also clips inline-start
+ overflow: a marker wider than `padding-left` loses its leading digits with no
+ way to scroll them back. Markers are right-aligned to the content edge, so the
+ padding must fit the widest one the list can produce. `searchMaxResults` is an
+ unbounded positive integer, so the padding is sized in `em` — against this
+ element's own font, the one a marker inherits — to hold a three-digit marker
+ (`999. ` measures 2.35em in the app font stack) plus the gap the one-digit
+ case already had. */
.sources {
margin: 0;
- padding-left: 20px;
+ padding-left: 2.5em;
display: flex;
flex-direction: column;
gap: 10px;
+ max-height: 320px;
+ overflow-y: auto;
}
.source {
@@ -65,26 +82,6 @@
font: var(--dsw-font-xs-13);
}
-.expandItem {
- list-style: none;
-}
-
-.expand {
- display: block;
- width: 100%;
- padding: 0;
- border: none;
- background-color: transparent;
- color: var(--dsw-alias-label-tertiary);
- cursor: pointer;
- font: inherit;
- text-align: left;
-}
-
-.expand:hover {
- color: var(--dsw-alias-label-secondary);
-}
-
.truncated {
margin-top: 8px;
color: var(--dsw-alias-label-tertiary);
diff --git a/packages/client/ui-primitives/src/WebBlock.tsx b/packages/client/ui-primitives/src/WebBlock.tsx
index 804ff17dfa..f13220f56c 100644
--- a/packages/client/ui-primitives/src/WebBlock.tsx
+++ b/packages/client/ui-primitives/src/WebBlock.tsx
@@ -9,22 +9,20 @@
// allowlist MarkdownText applies to untrusted assistant-authored links (it also
// permits mailto, excluded here); an unparseable or non-http URL renders as
// plain text. Geometry, radius, and fonts mirror CodeBlock/TerminalBlock so a
-// web card reads as one family with them; a long source list caps at maxSources
-// with a head/tail collapse using the same arithmetic as TerminalBlock's output
-// cap.
+// web card reads as one family with them; the whole source list renders inside a
+// fixed-height scroll container (its `.sources` max-height), so a long list
+// scrolls in place rather than growing the card — and that container's
+// `padding-left` must stay wide enough for the widest `` marker, since a
+// scroll container clips inline-start overflow irrecoverably. The card draws every source the
+// view carries: the tool already cut the list to its source cap, and `truncated`
+// reports that cut. A content-only transform downstream of the tool — spill-policy
+// replacing an oversized result's text while leaving its presentationMeta whole —
+// can still narrow what the model reads below this list.
-import { useCallback, useState } from 'react'
import clsx from 'clsx'
import { MarkdownText } from './markdown/MarkdownText.tsx'
import css from './WebBlock.module.css'
-/**
- * Sources shown before the height cap collapses the middle of a citation list.
- * Matches TerminalBlock's default output budget so both cards cut a long body
- * at the same place; the chat row narrows it through the maxSources prop.
- */
-export const DEFAULT_WEB_MAX_SOURCES = 16
-
/**
* One citeable source drawn in a search card: the projection of the contract's
* `WebSource`, with the optional fields kept optional so a provider that
@@ -50,8 +48,6 @@ export interface WebSearchBlockProps {
sources: WebSourceView[]
/** True when the tool cut the source list to its result cap. */
truncated: boolean
- /** Sources shown before the middle collapses (default {@link DEFAULT_WEB_MAX_SOURCES}). */
- maxSources?: number | undefined
/** Extra class merged onto the wrapper (callers position; this component draws). */
className?: string | undefined
}
@@ -65,13 +61,6 @@ export interface WebFetchBlockProps {
statusCode: number
/** True when the provider or the output cap cut the fetched content. */
truncated: boolean
- /**
- * Accepted and ignored, so both card kinds take one uniform prop set (a fetch
- * card has no source list to cap) — the same way TerminalBlock accepts one
- * `maxLines` across its arms. Lets a render site spread `maxSources` onto
- * either kind without a per-kind conditional.
- */
- maxSources?: number | undefined
/** Extra class merged onto the wrapper (callers position; this component draws). */
className?: string | undefined
}
@@ -137,9 +126,9 @@ function SafeLink({ url, label, className }: { url: string; label: string; class
/**
* One source row in a search card: the safe link plus its snippet and date. The
- * ` ` pins the source's original 1-based position, so a collapsed list
- * whose tail is drawn after the head still numbers each source by its real
- * citation index rather than by its position in the visible subset.
+ * ` ` pins the source's 1-based citation index explicitly rather than
+ * relying on the ``'s implicit numbering, so a row reads by its real index
+ * even inside the scroll container.
* @param props.source - the source to render.
* @param props.ordinal - the source's 1-based position in the full list.
* @returns the source list item.
@@ -159,21 +148,12 @@ function SourceItem({ source, ordinal }: { source: WebSourceView; ordinal: numbe
}
/**
- * The search card body: the answer over the capped source list.
+ * The search card body: the answer over the full source list, which scrolls in
+ * place once it exceeds the `.sources` container height.
* @param props - see {@link WebSearchBlockProps}.
* @returns the search card element.
*/
-function WebSearchBlock({ answer, sources, truncated, maxSources = DEFAULT_WEB_MAX_SOURCES, className }: WebSearchBlockProps) {
- const [expanded, setExpanded] = useState(false)
- const onToggle = useCallback(() => { setExpanded(value => !value) }, [])
- const hidden = sources.length - maxSources
- const capped = hidden > 0 && !expanded
- // Same split arithmetic as TerminalBlock's output cap, so a long body's head
- // and tail slices agree between the two cards.
- const headCount = Math.ceil(maxSources / 2)
- const tailCount = maxSources - headCount
- const head = capped ? sources.slice(0, headCount) : sources
- const tail = capped ? sources.slice(sources.length - tailCount) : []
+function WebSearchBlock({ answer, sources, truncated, className }: WebSearchBlockProps) {
// A provider may legitimately return no answer and no sources; the chat WebRow
// does not show the raw result content, so without this the user would see an
// empty card. Mirror the backend's `No results found.` render text.
@@ -187,27 +167,7 @@ function WebSearchBlock({ answer, sources, truncated, maxSources = DEFAULT_WEB_M
未找到结果
) : (
- {head.map((source, index) =>
-
- {expanded ? '收起' : `… 其余 ${hidden} 条来源`}
-
-
- )}
- {tail.map((source, index) => (
-
)}
{truncated && 来源列表已截断
}
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index b19147a1cc..79bae60c36 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -32,7 +32,7 @@ export { SearchBlock, DEFAULT_SEARCH_MAX_LINES } from './SearchBlock.tsx'
export type {
SearchBlockProps, SearchMatchesBlockProps, SearchPathsBlockProps, SearchFileGroup, SearchBlockLineMatch,
} from './SearchBlock.tsx'
-export { WebBlock, DEFAULT_WEB_MAX_SOURCES } from './WebBlock.tsx'
+export { WebBlock } from './WebBlock.tsx'
export type { WebBlockProps, WebSearchBlockProps, WebFetchBlockProps, WebSourceView } from './WebBlock.tsx'
export { CodeBlock } from './markdown/CodeBlock.tsx'
export type { CodeBlockProps } from './markdown/CodeBlock.tsx'
diff --git a/packages/client/ui-primitives/tests/web-block.spec.tsx b/packages/client/ui-primitives/tests/web-block.spec.tsx
index d681ce753b..69ff1bf609 100644
--- a/packages/client/ui-primitives/tests/web-block.spec.tsx
+++ b/packages/client/ui-primitives/tests/web-block.spec.tsx
@@ -1,19 +1,19 @@
// @vitest-environment jsdom
// WebBlock: both kinds of the web card. The search card's answer, its citation
// list with the title-or-hostname label fallback and optional snippet/date, the
-// source-list height cap and its expand control, and the truncated indicator;
-// the fetch card's linked URL, status, and truncation. Safe-link attributes on
-// both kinds: an http(s) URL becomes an external anchor (target/rel), any other
-// URL renders as plain text with no href.
+// full source list under one , and the truncated indicator; the fetch
+// card's linked URL, status, and truncation. Safe-link
+// attributes on both kinds: an http(s) URL becomes an external anchor
+// (target/rel), any other URL renders as plain text with no href.
import { afterEach, describe, expect, it } from 'vitest'
-import { cleanup, fireEvent, render } from '@testing-library/react'
-import { DEFAULT_WEB_MAX_SOURCES, WebBlock } from '../src/index.ts'
+import { cleanup, render } from '@testing-library/react'
+import { WebBlock } from '../src/index.ts'
import type { WebSourceView } from '../src/index.ts'
afterEach(cleanup)
-/** `count` sources with sequential hostnames, so the cap slices read distinctly. */
+/** `count` sources with sequential hostnames, so each row reads distinctly. */
function sources(count: number): WebSourceView[] {
return Array.from({ length: count }, (_value, index) => ({
url: `https://site-${index}.example.com/page`,
@@ -123,58 +123,25 @@ describe('WebBlock search card', () => {
expect(off.queryByText('来源列表已截断')).toBeNull()
})
- it('renders every source and no expand control under the cap', () => {
- const view = render( with no expand control', () => {
+ // The card shows the whole list the tool returned, with no head/tail
+ // collapse and no expand button. jsdom does not resolve the CSS Modules
+ // layout, so the scroll geometry the `.sources` max-height produces is
+ // pinned by the assembled browser case in apps/web/tests/web-search-round.e2e.ts,
+ // not here.
+ const view = render(), not renumbered 3 and 4.
- const view = render( , so it is valid inside and does not
- // consume a citation number between the head and tail sources.
- const view = render( is a source (no marker-less expander).
const ol = view.container.querySelector('ol')!
- // Every direct child is an (no bare child — invalid HTML).
expect([...ol.children].every(child => child.tagName === 'LI')).toBe(true)
})
- it('renders the head slice alone when the cap leaves no tail', () => {
- const view = render(', () => {
+ const view = render( = createSnapshotStore({
@@ -33,12 +33,22 @@ export class WelcomeNoticeStore {
private generation = 0
- /** @param api - settings wire face used for durable reads and writes. */
- constructor(private readonly api: Pick) {}
+ /**
+ * @param api - settings wire face used for durable reads and writes.
+ * @param persistence - remote browsers use memory because settings is loopback-only.
+ */
+ constructor(
+ private readonly api: Pick,
+ private readonly persistence: 'host' | 'memory' = 'host',
+ ) {}
- /** Load the current acknowledgement from the Host settings document. */
+ /** Load the acknowledgement from Host settings or initialize process-local state. */
async load(): Promise {
const generation = ++this.generation
+ if (this.persistence === 'memory') {
+ this.store.update((state) => { state.status = 'ready'; state.error = null })
+ return
+ }
this.store.update((state) => { state.status = 'loading'; state.error = null })
try {
const response = await this.api.settings.describe({})
@@ -64,12 +74,20 @@ export class WelcomeNoticeStore {
}
/**
- * Persist this copy version. The path mutation is idempotent across tabs and
- * preserves every sibling setting; failure leaves the step unacknowledged.
- * @returns true only when the Host committed the acknowledgement.
+ * Acknowledge this copy version. The Host path mutation is idempotent across
+ * tabs and preserves sibling settings; remote fallback changes only this store.
+ * @returns true when the selected persistence mode accepted the acknowledgement.
*/
async acknowledge(): Promise {
const generation = ++this.generation
+ if (this.persistence === 'memory') {
+ this.store.update((state) => {
+ state.status = 'ready'
+ state.acknowledged = true
+ state.error = null
+ })
+ return true
+ }
this.store.update((state) => { state.status = 'saving'; state.error = null })
try {
const response = await this.api.settings.mutate({
@@ -99,7 +117,9 @@ export class WelcomeNoticeStore {
}
/**
- * Refresh only after the welcome step has begun reading durable state.
+ * Refresh only after welcome state has left idle. A memory-mode load retains
+ * acknowledgement so reconnect and settings-change refreshes do not reopen a
+ * process-local notice.
* @param controller - welcome state owner whose current status decides whether to load.
*/
export function refreshWelcomeIfLoaded(controller: WelcomeNoticeStore): void {
diff --git a/packages/client/ui-settings-general/tests/apply.spec.ts b/packages/client/ui-settings-general/tests/apply.spec.ts
index 81a56a9a4a..73f6d8207e 100644
--- a/packages/client/ui-settings-general/tests/apply.spec.ts
+++ b/packages/client/ui-settings-general/tests/apply.spec.ts
@@ -25,7 +25,7 @@ const SEATS = [
['settings.onboarding', WelcomeNotice],
] as const
-async function bench() {
+async function bench(isLoopback = true) {
const ctx = new Context()
await ctx.plugin(SlotsService).await()
const locale = new LocaleService(ctx)
@@ -47,7 +47,7 @@ async function bench() {
},
},
}))
- ctx.provide('connection', { api: { settings: { describe: settingsDescribe } } } as never)
+ ctx.provide('connection', { api: { settings: { describe: settingsDescribe } }, isLoopback } as never)
return { ctx, slots: ctx.get('slots') as SlotsService, locale, settingsDescribe }
}
@@ -159,6 +159,19 @@ describe('ui-settings-general apply', () => {
await vi.waitFor(() => { expect(b.settingsDescribe).toHaveBeenCalledTimes(3) })
})
+ it('keeps remote welcome acknowledgement process-local', async () => {
+ const b = await bench(false)
+ declare(b.slots)
+ await b.ctx.plugin({ inject: [...inject], apply }).await()
+ const entry = b.slots.entries('settings.onboarding')[0]!
+ const { controller } = (entry.inject as unknown as () => WelcomeNoticeInjected)()
+
+ await controller.load()
+ await expect(controller.acknowledge()).resolves.toBe(true)
+ expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: true })
+ expect(b.settingsDescribe).not.toHaveBeenCalled()
+ })
+
it('re-registers after an HMR collapse of the declaring chain (stale disposers must not block)', async () => {
const b = await bench()
const redeclare = declare(b.slots)
diff --git a/packages/client/ui-settings-general/tests/welcome-store.spec.ts b/packages/client/ui-settings-general/tests/welcome-store.spec.ts
index 28c7b0509c..45e4ca5590 100644
--- a/packages/client/ui-settings-general/tests/welcome-store.spec.ts
+++ b/packages/client/ui-settings-general/tests/welcome-store.spec.ts
@@ -30,6 +30,21 @@ function deferred() {
}
describe('WelcomeNoticeStore', () => {
+ it('acknowledges in memory without calling loopback-only settings APIs', async () => {
+ const describe = vi.fn()
+ const mutate = vi.fn()
+ const controller = new WelcomeNoticeStore({ settings: { describe, mutate } } as never, 'memory')
+
+ await controller.load()
+ expect(controller.store.getSnapshot()).toEqual({ status: 'ready', acknowledged: false, error: null })
+ await expect(controller.acknowledge()).resolves.toBe(true)
+ expect(controller.store.getSnapshot()).toEqual({ status: 'ready', acknowledged: true, error: null })
+ await controller.load()
+ expect(controller.store.getSnapshot()).toEqual({ status: 'ready', acknowledged: true, error: null })
+ expect(describe).not.toHaveBeenCalled()
+ expect(mutate).not.toHaveBeenCalled()
+ })
+
it('acknowledges only the exact current copy version', async () => {
for (const [version, acknowledged] of [
[undefined, false],
diff --git a/packages/fs/tool-fs-search/README.i18n.yaml b/packages/fs/tool-fs-search/README.i18n.yaml
index bedb8289c1..a8e2222998 100644
--- a/packages/fs/tool-fs-search/README.i18n.yaml
+++ b/packages/fs/tool-fs-search/README.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/fs/tool-fs-search/README.md
-README.md: b12ffda9869c7d6bef5ea5b54594781ecf555ff4
-README.zh.md: 7dd6cdf9a209f2fe357b4ffe48d20d574266ce60
+README.md: 78ffa069e56da5fc987913acf761eb5c6ae15b1a
+README.zh.md: 42b123d5c47d8f48bc21b6f9bed4905372ca8625
diff --git a/packages/fs/tool-fs-search/README.md b/packages/fs/tool-fs-search/README.md
index b12ffda986..78ffa069e5 100644
--- a/packages/fs/tool-fs-search/README.md
+++ b/packages/fs/tool-fs-search/README.md
@@ -2,21 +2,21 @@
English | [中文](README.zh.md)
-The **model-facing filesystem discovery tools**—`glob`, `grep`—are backed by the **bash executor seam**, not by `ctx.fs` provider methods. At load, the package probes `command -v rg` through `ctx.bash`; if the executor cannot find ripgrep on its `PATH`, it logs a warning and registers no tools or prompt sections. Each call assembles a fixed ripgrep command (every model-controlled value through one package-private shell-quoting helper), runs it via `ctx.bash.resolve(request)` → `ctx.bash.run(spec)` as an ordinary foreground tool call, parses the raw `rg` output, and returns a workdir-relative canonical value. The package injects `tools`, `systemPrompt`, and `bash`—deliberately **not** `fs`; `ctx.spillStore` is read opportunistically with `ctx.get()` because formatted-result spill is optional.
+The **model-facing filesystem discovery tools**—`glob`, `grep`—are backed by the **packaged ripgrep binary** (`@vscode/ripgrep`), not by `ctx.fs` provider methods and not by a system `rg` install. Registration is unconditional: the binary ships inside the npm dependency, so there is no load-time availability probe. Each call spawns the binary through the `ctx.subprocess` seam with a fixed argv vector (`--no-config` prepended so a host `RIPGREP_CONFIG_PATH` cannot inject a `--pre` preprocessor into the unconfined spawn; model-controlled values are plain argv elements — no shell layer exists, so no quoting applies), parses the raw `rg` output, and returns a workdir-relative canonical value. The package injects `tools`, `systemPrompt`, and `subprocess`—deliberately **not** `fs`; `ctx.spillStore` is read opportunistically with `ctx.get()` because formatted-result spill is optional.
```ts ignore-check
// A deployment chooses how over-cap glob pages are selected.
-await ctx.plugin(LocalBashExecutor, { cwd: process.cwd() }) // @deepseek-ai/dsh-bash-local
+await ctx.plugin(LocalSubprocessService) // @deepseek-ai/dsh-subprocess-local
await ctx.plugin(ToolFsSearch, { sampleOverCapGlobResults: false })
// Optional: a spill backend makes capped results fully recoverable.
await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh-spill-local
```
-Why bash-backed: local workspace discovery is naturally a process-backed `rg` workflow, and putting search on `ctx.fs` would force every filesystem backend to grow a search API. The bash executor owns request defaulting/capping, subprocess execution, process-group termination, environment scrubbing, raw output capture, and backend substitution (local, sandboxed, remote); this package owns schemas, argument validation, shell quoting, parsing, retention, formatted-result spill, and timeout declaration. The tools never call `ctx.bash.start()` and never expose a bash task id — the call returns only after `rg` exits, times out, is aborted, or fails.
+Why spawn-backed: local workspace discovery is naturally a process-backed `rg` workflow, and putting search on `ctx.fs` would force every filesystem backend to grow a search API. The subprocess seam owns spawn execution, process-tree termination, environment scrubbing, and bounded output capture; this package owns schemas, argument validation, argv construction, parsing, retention, formatted-result spill, and timeout declaration. The tools never expose a background task — the call returns only after `rg` exits, is terminated by the cooperative timeout, is aborted, or fails.
-## Deployment requirement: rg + co-located bash/filesystem
+## Deployment requirement: no host rg, co-located workdir/filesystem
-The mounted bash executor must be able to resolve `rg` from its `PATH` at plugin load; otherwise `glob` and `grep` are absent from the model-visible tool schema. Returned paths are displayed relative to the resolved bash workdir (the calling agent's session cwd when present, else the executor's configured default) and are follow-up-readable with `read` only when the bash workdir and the filesystem root are the same workspace. v1 documents that co-location requirement and performs no runtime cross-service validation; remote or virtual filesystem search waits for a shared workspace contract or a provider-specific search backend.
+The binary ships with the package on every supported platform (macOS/Linux/Windows, x64/arm64), so no host `rg` install is required and the tools register on every deployment. Returned paths are displayed relative to the resolved workdir (the calling agent's session cwd when present, else `process.cwd()`) and are follow-up-readable with `read` only when that workdir and the filesystem root are the same workspace. v1 documents that co-location requirement and performs no runtime cross-service validation; remote or virtual filesystem search waits for a shared workspace contract or a provider-specific search backend.
## Config
@@ -29,24 +29,26 @@ The mounted bash executor must be able to resolve `rg` from its `PATH` at plugin
| `grepMaxMatches` | `250` | Max flat matches one `grep` call retains inline (matches Claude Code's `GrepTool` `head_limit`); later matches go to the formatted spill artifact. |
| `grepMaxLineBytes` | `2000` | Byte cap per matched-line preview; the cut preserves UTF-8 boundaries and is marked `(line truncated)`. |
| `rawOutputMaxBytes` | `20000000` | Max complete raw `rg` stdout a search will parse (matches Claude Code's ripgrep raw buffer); larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. |
-| `timeoutMs` | `30000` | Cooperative tool-call budget attached to both tool definitions, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`; the bash backend's own timeout stays a second safety cap. |
+| `timeoutMs` | `30000` | Cooperative tool-call budget attached to both tool definitions, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`; the subprocess seam's terminate escalation is the hard kill. |
+| `graceMs` | `3000` | Terminate-escalation grace period the subprocess seam grants past `timeoutMs` before the search fails as `SEARCH_ABORTED`. |
+| `stderrMaxBytes` | `65536` | Diagnostic-tail budget for `rg` stderr, captured through the subprocess seam's collect disposition; a lossy read keeps only the tail (marked `[stderr truncated]`). |
## Tools
| Tool | Arguments | Behavior |
|---|---|---|
-| `glob` | `pattern`, `path?` | `rg --files --glob --sort=modified --no-ignore --hidden` plus VCS metadata excludes (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`). `path` is an optional **directory** search root; omitted means the resolved bash workdir. Returns one FILE path per line; `rg --files` never emits directory entries. The pattern keeps ripgrep semantics: without a `/` it matches the basename at any depth, so `*` matches the whole tree. Complete results stay modification-time ordered; over-cap presentation follows `sampleOverCapGlobResults`. |
+| `glob` | `pattern`, `path?` | `rg --files --glob --sort=modified --no-ignore --hidden` plus VCS metadata excludes (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`). `path` is an optional **directory** search root; omitted means the resolved workdir. Returns one FILE path per line; `rg --files` never emits directory entries. The pattern keeps ripgrep semantics: without a `/` it matches the basename at any depth, so `*` matches the whole tree. Complete results stay modification-time ordered; over-cap presentation follows `sampleOverCapGlobResults`. |
| `grep` | `pattern`, `path?`, `include?` | Line-oriented `rg --json` parse (no colon-splitting ambiguity). `pattern` is a ripgrep regex; `path` is an optional **file or directory** target; `include` is ONE positive glob filter — a comma-separated list or a negated (`!…`) value is rejected up front (brace alternation like `*.{ts,tsx}` is fine). Returns matches grouped by file as `Line N: `. |
Routine budgets stay out of the model-facing schema (no `head_limit`/`offset`/`case_insensitive`/output modes): a model that needs surrounding context reads the matched file with `read`; one that needs later results follows the returned spill locator's retrieval hint.
## Two budgets, two artifacts
-Raw `rg` stdout is an internal transport detail. Each search requests `stdoutMaxBytes: rawOutputMaxBytes` from the bash seam and parses only complete retained stdout; if the executor still returns `stdout.truncated`, the search fails with `SEARCH_RAW_OUTPUT_OVERFLOW` and tells the model to narrow the query. A successful `glob` keeps the displayed search root and every acquired path in `{ root, paths }`; when sampling is enabled, `root` lets the Native renderer group an explicit relative or absolute search path by entries beneath that root rather than by its workdir prefix. `grep` keeps every acquired `{ path, lineNumber, line }` in `{ matches }`. Inline item and per-line preview caps apply only in the Native renderer. For a direct surface call with more logical results than the inline cap, post-policy best-effort saves the complete formatted preview through `ctx.spillStore.saveText()` and replaces only presentation with the configured page plus locator. Nested Code dispatches skip that spill because their full canonical value does not enter model context. Missing/failed spill keeps the inline page and reports that the complete result could not be saved—never an `isError`.
+Raw `rg` stdout and stderr are internal transport details. Each search requests collect-mode budgets from the subprocess seam — complete stdout within `rawOutputMaxBytes` and a `stderrMaxBytes` diagnostic tail — with no spill files on either stream (the tool never reads a raw spill path). If the seam still reports a lossy stdout read, the search fails with `SEARCH_RAW_OUTPUT_OVERFLOW` and tells the model to narrow the query; a lossy stderr read only marks the diagnostic excerpt `[stderr truncated]`. A successful `glob` keeps the displayed search root and every acquired path in `{ root, paths }`; when sampling is enabled, `root` lets the Native renderer group an explicit relative or absolute search path by entries beneath that root rather than by its workdir prefix. `grep` keeps every acquired `{ path, lineNumber, line }` in `{ matches }`. Inline item and per-line preview caps apply only in the Native renderer. For a direct surface call with more logical results than the inline cap, post-policy best-effort saves the complete formatted preview through `ctx.spillStore.saveText()` and replaces only presentation with the configured page plus locator. Nested Code dispatches skip that spill because their full canonical value does not enter model context. Missing/failed spill keeps the inline page and reports that the complete result could not be saved—never an `isError`.
## Errors
-Search failures carry the package-owned `SearchError` (a `HarnessError` subclass), surfaced as `{ name, code }` on `isError` results: `SEARCH_INVALID_PATTERN` (ripgrep rejected the regex/glob), `SEARCH_FAILED` (runtime `rg` disappearance after registration, inaccessible target, signal kill, malformed `--json` output), `SEARCH_RAW_OUTPUT_OVERFLOW` (raw output over `rawOutputMaxBytes`, or still truncated after the requested stdout capture budget), and `SEARCH_ABORTED` (tool timeout, caller cancellation, or the bash executor's own timeout). ripgrep exit semantics are tool-owned: exit 0 is success with results, exit 1 is a successful empty search (`No files found` / `No matches found`), and only other exits are failures. Model argument mistakes (blank pattern, a list-valued `include`) stay ordinary tool argument errors.
+Search failures carry the package-owned `SearchError` (a `HarnessError` subclass), surfaced as `{ name, code }` on `isError` results: `SEARCH_INVALID_PATTERN` (ripgrep rejected the regex/glob), `SEARCH_FAILED` (a failed `rg` launch, inaccessible target, signal kill, malformed `--json` output), `SEARCH_RAW_OUTPUT_OVERFLOW` (raw output over `rawOutputMaxBytes`, or still lossy after the requested stdout capture budget), and `SEARCH_ABORTED` (cooperative tool timeout or caller cancellation). ripgrep exit semantics are tool-owned: exit 0 is success with results, exit 1 is a successful empty search (`No files found` / `No matches found`), and only other exits are failures. Model argument mistakes (blank pattern, a list-valued `include`) stay ordinary tool argument errors.
## Model Experience
@@ -54,7 +56,7 @@ Search failures carry the package-owned `SearchError` (a `HarnessError` subclass
#### What the model sees
-After the load-time `rg` probe succeeds, every request in this plugin's registration scope contains the independently registered glob and grep guidance below. Agent-scoped tool restrictions can hide either schema without removing its prompt section.
+Every request in this plugin's registration scope contains the independently registered glob and grep guidance below. Agent-scoped tool restrictions can hide either schema without removing its prompt section.
##### Glob guidance with `sampleOverCapGlobResults: true`
@@ -86,7 +88,7 @@ Prefix-stable while the plugin scope, sampling choice, and guidance text are unc
#### What the model sees
-The glob description states the configured over-cap ordering. The generated [`glob` and `grep` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search) use `sampleOverCapGlobResults: true`; schemas are visible only after the load-time `rg` probe succeeds.
+The glob description states the configured over-cap ordering. The generated [`glob` and `grep` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search) use `sampleOverCapGlobResults: true`; the tools are registered unconditionally.
#### Token effect
@@ -126,7 +128,7 @@ Append-only; newly visible content follows the reusable request prefix and does
## Known Limitations and Deferred Work
-- **Search and file access have no shared-workspace proof** — returned paths are follow-up-readable only when the bash workdir and filesystem root denote the same workspace; the package performs no runtime cross-service validation.
-- **Ripgrep is a deployment dependency** — a missing `rg` executable makes the package register no tools or guidance; an incompatible executable or one that disappears after registration fails calls with `SEARCH_FAILED`. Remote or virtual filesystems need a co-located executor or another search consumer.
+- **Search and file access have no shared-workspace proof** — returned paths are follow-up-readable only when the workdir and filesystem root denote the same workspace; the package performs no runtime cross-service validation.
+- **The packaged binary is fixed at dependency version** — `@vscode/ripgrep` covers the platforms it ships (macOS/Linux/Windows, x64/arm64); an unsupported platform or a corrupted install fails calls with `SEARCH_FAILED`. Remote or virtual filesystems need a co-located workspace or another search consumer.
- **The schemas expose one bounded page** — offset pagination, case-mode switches, alternate output modes, and provider-backed discovery remain outside this package; capped complete output requires a spill backend.
- **Sampling, when enabled, groups by first path segment beneath the search root only** — an over-cap `glob` page balances across those top-level entries, so a result concentrated deeper (one busy directory inside an otherwise even tree) is still shown unevenly below that level; recursive balancing is deferred.
diff --git a/packages/fs/tool-fs-search/README.zh.md b/packages/fs/tool-fs-search/README.zh.md
index 7dd6cdf9a2..42b123d5c4 100644
--- a/packages/fs/tool-fs-search/README.zh.md
+++ b/packages/fs/tool-fs-search/README.zh.md
@@ -2,21 +2,21 @@
[English](README.md) | 中文
-**面向模型的文件系统发现工具**（`glob`、`grep`）由 **bash 执行器 seam** 支持，而不是由 `ctx.fs` 提供方方法支持。加载时，本包（package）探测 `command -v rg`，探测通过 `ctx.bash` 进行；如果执行器无法在其 `PATH` 上找到 ripgrep，就记录警告，并且不注册工具或提示词段。每次调用都会组装固定的 ripgrep 命令（所有模型控制的值都经过同一个包私有 shell 引用辅助函数），通过 `ctx.bash.resolve(request)` → `ctx.bash.run(spec)` 作为普通前台工具调用运行，解析原始 `rg` 输出，并返回相对于工作目录的规范值。本包注入 `tools`、`systemPrompt` 和 `bash`，有意**不**注入 `fs`；格式化结果 spill 为可选功能，因此机会性读取 `ctx.spillStore`，调用方式为 `ctx.get()`。
+**面向模型的文件系统发现工具**（`glob`、`grep`）由 **打包的 ripgrep 二进制**（`@vscode/ripgrep`）支持，而不是由 `ctx.fs` 提供方方法或系统 `rg` 安装支持。注册是无条件的：二进制随 npm 依赖一起交付，因此没有加载期可用性探针。每次调用都通过 `ctx.subprocess` seam 以固定 argv 向量 spawn 该二进制（前缀 `--no-config`，使宿主的 `RIPGREP_CONFIG_PATH` 无法向不受约束的 spawn 注入 `--pre` 预处理器；模型控制的值是普通 argv 元素——不存在 shell 层，因此无需引号），解析原始 `rg` 输出，并返回相对于工作目录的规范值。本包注入 `tools`、`systemPrompt` 和 `subprocess`，有意**不**注入 `fs`；格式化结果 spill 为可选功能，因此机会性读取 `ctx.spillStore`，调用方式为 `ctx.get()`。
```ts ignore-check
// A deployment chooses how over-cap glob pages are selected.
-await ctx.plugin(LocalBashExecutor, { cwd: process.cwd() }) // @deepseek-ai/dsh-bash-local
+await ctx.plugin(LocalSubprocessService) // @deepseek-ai/dsh-subprocess-local
await ctx.plugin(ToolFsSearch, { sampleOverCapGlobResults: false })
// Optional: a spill backend makes capped results fully recoverable.
await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh-spill-local
```
-采用 bash 支持的原因：本地工作区发现天然是由进程支持的 `rg` 工作流；如果把搜索放到 `ctx.fs` 上，就会迫使每个文件系统后端扩展搜索 API。bash 执行器负责请求默认值/上限、子进程执行、进程组终止、环境清理、原始输出捕获和后端替换（本地、沙箱化、远程）；本包负责 schema、参数校验、shell 引用、解析、保留、格式化结果 spill 和超时声明。工具绝不调用 `ctx.bash.start()`，也不公开 bash task id；只有在 `rg` 退出、超时、中止或失败后，调用才会返回。
+采用 spawn 支持的原因：本地工作区发现天然是由进程支持的 `rg` 工作流；如果把搜索放到 `ctx.fs` 上，就会迫使每个文件系统后端扩展搜索 API。subprocess seam 负责 spawn 执行、进程树终止、环境清理和有界输出捕获；本包负责 schema、参数校验、argv 构造、解析、保留、格式化结果 spill 和超时声明。工具绝不暴露后台任务——只有在 `rg` 退出、被协作式超时终止、被中止或失败后，调用才会返回。
-## 部署要求：rg 与共置的 bash/文件系统
+## 部署要求：无需宿主 rg，但工作目录与文件系统需共置
-已挂载的 bash 执行器必须能在插件加载时解析 `rg`，其来源是执行器的 `PATH`；否则面向模型的工具 schema 中不会出现 `glob` 和 `grep`。返回路径会相对于解析后的 bash 工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用执行器配置的默认值）；只有 bash 工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区契约或特定提供方的搜索后端。
+二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区契约或特定提供方的搜索后端。
## 配置
@@ -29,24 +29,26 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh-
| `grepMaxMatches` | `250` | 一次 `grep` 调用内联保留的最大平铺匹配数（与 Claude Code 的 `GrepTool` `head_limit` 相同）；后续匹配写入格式化 spill 产物。 |
| `grepMaxLineBytes` | `2000` | 每条匹配行预览的字节上限；截断会保留 UTF-8 边界，并标记为 `(line truncated)`。 |
| `rawOutputMaxBytes` | `20000000` | 搜索将解析的完整原始 `rg` stdout 上限（与 Claude Code 的 ripgrep 原始 buffer 相同）；更大的原始输出以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败。 |
-| `timeoutMs` | `30000` | 附加到两个工具定义上的协作式工具调用预算，由 `@deepseek-ai/dsh-timeout-policy` 通过 `exec.signal` 强制执行；bash 后端自身的超时仍作为第二道安全上限。 |
+| `timeoutMs` | `30000` | 附加到两个工具定义上的协作式工具调用预算，由 `@deepseek-ai/dsh-timeout-policy` 通过 `exec.signal` 强制执行；subprocess seam 的终止升级提供硬终止。 |
+| `graceMs` | `3000` | subprocess seam 在 `timeoutMs` 之外授予的终止升级宽限期；超过后搜索以 `SEARCH_ABORTED` 失败。 |
+| `stderrMaxBytes` | `65536` | `rg` stderr 的诊断尾部预算，经 subprocess seam 的 collect 形态捕获；lossy 读取只保留尾部（标记 `[stderr truncated]`）。 |
## 工具
| 工具 | 参数 | 行为 |
|---|---|---|
-| `glob` | `pattern`、`path?` | 运行 `rg --files --glob --sort=modified --no-ignore --hidden`，并排除 VCS 元数据（`.git`、`.svn`、`.hg`、`.bzr`、`.jj`、`.sl`）。`path` 是可选的**目录**搜索根；省略时使用解析后的 bash 工作目录。每行返回一个**文件**路径；`rg --files` 从不输出目录条目。pattern 保留 ripgrep 语义：不含 `/` 时匹配任意深度的基名，因此 `*` 匹配整棵树。完整结果保持按修改时间排序；超过上限时的呈现方式遵循 `sampleOverCapGlobResults`。 |
+| `glob` | `pattern`、`path?` | 运行 `rg --files --glob --sort=modified --no-ignore --hidden`，并排除 VCS 元数据（`.git`、`.svn`、`.hg`、`.bzr`、`.jj`、`.sl`）。`path` 是可选的**目录**搜索根；省略时使用解析后的工作目录。每行返回一个**文件**路径；`rg --files` 从不输出目录条目。pattern 保留 ripgrep 语义：不含 `/` 时匹配任意深度的基名，因此 `*` 匹配整棵树。完整结果保持按修改时间排序；超过上限时的呈现方式遵循 `sampleOverCapGlobResults`。 |
| `grep` | `pattern`、`path?`、`include?` | 按行解析 `rg --json`，避免按冒号拆分的歧义。`pattern` 是 ripgrep 正则表达式；`path` 是可选的**文件或目录**目标；`include` 是一个正向 glob 过滤器，前置拒绝逗号分隔列表或否定值（`!…`），但允许 `*.{ts,tsx}` 等花括号交替。返回按文件分组、形如 `Line N: ` 的匹配。 |
常规预算不进入面向模型的 schema（没有 `head_limit`/`offset`/`case_insensitive`/输出模式）：模型需要周边上下文时，用 `read` 读取匹配文件；需要后续结果时，遵循返回的 spill locator 检索提示。
## 两类预算、两类产物
-原始 `rg` stdout 是内部传输细节。每次搜索从 bash seam 请求 `stdoutMaxBytes: rawOutputMaxBytes`，且只解析完整保留的 stdout；如果执行器仍返回 `stdout.truncated`，搜索会以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败，并要求模型缩小查询。成功的 `glob` 在 `{ root, paths }` 中保留所显示的搜索根及所有已取得路径；启用采样时，借助 `root`，原生渲染器能以显式的相对或绝对搜索路径为根，按该根下的条目分组，而不是按其工作目录前缀分组。`grep` 保留所有已取得的 `{ path, lineNumber, line }`，并将其存入 `{ matches }`。内联条目和每行预览上限只应用于原生渲染器。直接接口调用的逻辑结果超过内联上限时，后置策略会尽力通过 `ctx.spillStore.saveText()` 保存完整格式化预览，并只把呈现替换为配置指定的页面与 locator。嵌套 Code 分派会跳过 spill，因为其完整规范值不会进入模型上下文。spill 缺失/失败时保留内联页面，并报告完整结果无法保存，绝不会成为 `isError`。
+原始 `rg` stdout 与 stderr 是内部传输细节。每次搜索从 subprocess seam 请求 collect 模式预算——`rawOutputMaxBytes` 内的完整 stdout 与 `stderrMaxBytes` 的诊断尾部——两条流都不产生 spill 文件（工具从不读取原始 spill 路径）。如果 seam 仍报告 lossy stdout 读取，搜索会以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败，并要求模型缩小查询；lossy stderr 读取只把诊断摘录标记为 `[stderr truncated]`。成功的 `glob` 在 `{ root, paths }` 中保留所显示的搜索根及所有已取得路径；启用采样时，借助 `root`，原生渲染器能以显式的相对或绝对搜索路径为根，按该根下的条目分组，而不是按其工作目录前缀分组。`grep` 保留所有已取得的 `{ path, lineNumber, line }`，并将其存入 `{ matches }`。内联条目和每行预览上限只应用于原生渲染器。直接接口调用的逻辑结果超过内联上限时，后置策略会尽力通过 `ctx.spillStore.saveText()` 保存完整格式化预览，并只把呈现替换为配置指定的页面与 locator。嵌套 Code 分派会跳过 spill，因为其完整规范值不会进入模型上下文。spill 缺失/失败时保留内联页面，并报告完整结果无法保存，绝不会成为 `isError`。
## 错误
-搜索失败携带本包拥有的 `SearchError`（`HarnessError` 子类），以 `{ name, code }` 公开在 `isError` 结果上：`SEARCH_INVALID_PATTERN`（ripgrep 拒绝正则/glob）、`SEARCH_FAILED`（注册后 `rg` 在运行时消失、目标不可访问、信号终止、`--json` 输出格式错误）、`SEARCH_RAW_OUTPUT_OVERFLOW`（原始输出超过 `rawOutputMaxBytes`，或在请求 stdout 捕获预算后仍被截断）和 `SEARCH_ABORTED`（工具超时、调用方取消或 bash 执行器自身超时）。ripgrep 退出语义由工具拥有：退出 0 表示成功且有结果，退出 1 表示成功的空搜索（`No files found` / `No matches found`），只有其他退出值表示失败。模型参数错误（空白 pattern、列表值 `include`）仍是普通工具参数错误。
+搜索失败携带本包拥有的 `SearchError`（`HarnessError` 子类），以 `{ name, code }` 公开在 `isError` 结果上：`SEARCH_INVALID_PATTERN`（ripgrep 拒绝正则/glob）、`SEARCH_FAILED`（`rg` 启动失败、目标不可访问、信号终止、`--json` 输出格式错误）、`SEARCH_RAW_OUTPUT_OVERFLOW`（原始输出超过 `rawOutputMaxBytes`，或在请求 stdout 捕获预算后仍 lossy）和 `SEARCH_ABORTED`（协作式工具超时或调用方取消）。ripgrep 退出语义由工具拥有：退出 0 表示成功且有结果，退出 1 表示成功的空搜索（`No files found` / `No matches found`），只有其他退出值表示失败。模型参数错误（空白 pattern、列表值 `include`）仍是普通工具参数错误。
## 模型体验
@@ -54,7 +56,7 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh-
#### 模型看到的内容
-加载时 `rg` 探测成功后，该插件注册作用域内的每个请求都包含下方独立注册的 glob 与 grep 指导。agent 作用域的工具限制可以隐藏任一 schema，而不移除其提示词段。
+该插件注册作用域内的每个请求都包含下方独立注册的 glob 与 grep 指导。agent 作用域的工具限制可以隐藏任一 schema，而不移除其提示词段。
##### 启用 `sampleOverCapGlobResults: true` 时的 Glob 指导
@@ -76,57 +78,57 @@ Use the grep tool — not shell grep or rg — to search file contents. Use read
#### Token 影响
-工具注册期间，每个请求支付固定指导成本；必填的采样选项决定采用哪个 glob 变体。
+工具注册期间每个请求有固定的指导成本；必填的采样选择决定采用哪一个 glob 变体。
#### KV Cache 影响
-只要插件作用域、采样选项和指导文本不变，前缀就保持稳定。启用、dispose（资源释放）或更改该选项，可能从该提示词段开始使复用失效。
+插件作用域、采样选择与指导文本不变时前缀稳定。激活、销毁或改变选择可能使该提示词段的复用失效。
### 工具 schema
#### 模型看到的内容
-glob 描述会说明配置所指定的超限结果排序方式。已生成的 [`glob` 和 `grep` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search) 使用 `sampleOverCapGlobResults: true`；只有加载时 `rg` 探测成功后，这些 schema 才可见。
+glob 描述声明了配置的超过上限排序方式。生成的 [`glob` 和 `grep` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search) 使用 `sampleOverCapGlobResults: true`；工具无条件注册。
#### Token 影响
-工具可见的每个请求都支付固定 schema 成本。
+工具可见时每个请求有固定的 schema 成本。
#### KV Cache 影响
-只要工具可见性和定义不变，前缀就保持稳定。注册生命周期或作用域限制可能从首个变化的 schema token 开始使复用失效。
+工具可见性与定义不变时前缀稳定。注册生命周期或作用域限制可能从第一个改变的 schema token 起使复用失效。
-### 结果与 spill 通知
+### 结果与 spill 提示
#### 模型看到的内容
-`glob` 每行返回一个路径；`grep` 在每个路径下对 `Line : ` 匹配分组。空搜索返回 `No files found` 或 `No matches found`。达到上限的结果末尾会附加省略数量、spill locator 和后端检索提示，或说明完整结果无法保存。`sampleOverCapGlobResults: true` 时，超过上限的 `glob` 页面会在实际搜索根正下方的条目之间按轮转方式取路径，footer 会说明采样依据和触达的顶层条目数；若无法触达全部条目，footer 会要求模型缩小 `path`。设为 `false` 时，页面保留按修改时间排序的前部，并沿用通常用于达到上限结果的 footer。未超过上限的结果原样不动；扁平的采样结果也沿用普通 footer，因为其样本等同于按修改时间排序的前部。spill 产物始终保存按修改时间排序的完整列表。
+`glob` 每行返回一个路径；`grep` 在每个路径下分组展示 `Line : ` 匹配。空搜索返回 `No files found` 或 `No matches found`。达到上限的结果以省略计数结尾，并附 spill locator 与后端检索提示；否则说明完整结果无法保存。启用 `sampleOverCapGlobResults: true` 时，超过上限的 `glob` 页面按实际搜索根正下方的条目轮转取路径，页脚说明采样依据及其覆盖的顶层条目数；无法覆盖全部条目时，页脚提示模型收窄 `path`。`false` 时页面是按修改时间排序的前部，并保留普通的上限结果页脚。未超过上限的结果原样呈现；扁平采样的结果也保留普通页脚，因为其采样等于按修改时间排序的前部。spill 产物始终持有按修改时间排序的完整列表。
#### Token 影响
-内联路径和匹配受 `globMaxResults`、`grepMaxMatches` 与 `grepMaxLineBytes` 限制；调用和保留结果会留在历史中，直到上下文压缩（compaction）。
+内联路径与匹配受 `globMaxResults`、`grepMaxMatches` 与 `grepMaxLineBytes` 约束；调用与保留结果在压缩前留在历史中。
#### KV Cache 影响
-仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+只追加；新可见内容跟在可复用请求前缀之后，不会使既有 KV-cache 条目失效。
### 工具错误
#### 模型看到的内容
-失败会规范化为 `Error: `，并向调用方提供结构化的 `SEARCH_INVALID_PATTERN`、`SEARCH_FAILED`、`SEARCH_RAW_OUTPUT_OVERFLOW` 或 `SEARCH_ABORTED` 元数据。
+失败被规范化为 `Error: `，并携带结构化 `SEARCH_INVALID_PATTERN`、`SEARCH_FAILED`、`SEARCH_RAW_OUTPUT_OVERFLOW` 或 `SEARCH_ABORTED` 元数据供调用方使用。
#### Token 影响
-只有失败调用会添加这些保留 token。
+只有失败的调用会增加这些保留 token。
#### KV Cache 影响
-仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+只追加；新可见内容跟在可复用请求前缀之后，不会使既有 KV-cache 条目失效。
-## 已知限制与暂缓事项
+## 已知局限与延期工作
-- **搜索和文件访问没有共享工作区证明**：只有 bash 工作目录和文件系统根目录表示同一工作区时，返回路径才能继续读取；本包不执行运行时跨服务校验。
-- **Ripgrep 是部署依赖**：缺失 `rg` 可执行文件时，本包不注册工具或指导；可执行文件不兼容或注册后消失时，调用以 `SEARCH_FAILED` 失败。远程或虚拟文件系统需要共置执行器或其他搜索消费方。
-- **schema 只公开一个有界页面**：offset 分页、大小写模式开关、其他输出模式和提供方支持的发现均不在本包内；达到上限的完整输出需要 spill 后端。
-- **启用采样时，只按搜索根下的路径首段分组**：超过上限的 `glob` 页面在这些顶层条目之间做均衡，因此集中在更深层的结果（一棵总体均匀的树里某个特别庞大的子目录）在该层级以下仍然分布不均；递归均衡已延期。
+- **搜索与文件访问没有共享工作区证明**——只有当工作目录与文件系统根目录指向同一工作区时，返回路径才保证可继续读取；本包不执行运行时跨服务校验。
+- **打包二进制固定在依赖版本上**——`@vscode/ripgrep` 覆盖其随附的平台（macOS/Linux/Windows，x64/arm64）；不支持的平台或损坏的安装会以 `SEARCH_FAILED` 使调用失败。远程或虚拟文件系统需要共置的工作区或另一个搜索消费方。
+- **schema 只暴露一个有界页面**——偏移分页、大小写开关、替代输出模式与提供方支撑的发现仍不在本包范围内；达到上限的完整输出需要 spill 后端。
+- **启用采样时仅按搜索根正下方的第一段路径分组**——超过上限的 `glob` 页面在这些顶层条目之间平衡，因此集中在更深处的结果（一棵均匀树里某个繁忙目录）在该层级之下仍会呈现不均；递归平衡被延期。
diff --git a/packages/fs/tool-fs-search/package.json b/packages/fs/tool-fs-search/package.json
index bf9cf15aa0..8953aea77a 100644
--- a/packages/fs/tool-fs-search/package.json
+++ b/packages/fs/tool-fs-search/package.json
@@ -1,6 +1,6 @@
{
"name": "@deepseek-ai/dsh-tool-fs-search",
- "description": "Model-facing filesystem discovery tools (glob, grep) backed by the DeepSeek Harness bash seam (ctx.bash)",
+ "description": "Model-facing filesystem discovery tools (glob, grep) backed by the packaged ripgrep binary (@vscode/ripgrep)",
"version": "0.0.1",
"private": true,
"type": "module",
@@ -27,23 +27,23 @@
],
"license": "BSD-3-Clause",
"dependencies": {
+ "@vscode/ripgrep": "^1.18.0",
"schemastery": "^3.18.0"
},
"peerDependencies": {
- "@deepseek-ai/dsh-bash": "^0.0.1",
"@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-retention": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-spill": "^0.0.1",
+ "@deepseek-ai/dsh-subprocess": "^0.0.1",
"@deepseek-ai/dsh-system-prompt": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
"cordis": "^4.0.0-rc.6"
},
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
- "@deepseek-ai/dsh-bash": "workspace:^",
- "@deepseek-ai/dsh-bash-local": "workspace:^",
+ "@deepseek-ai/dsh-subprocess": "workspace:^",
"@deepseek-ai/dsh-subprocess-local": "workspace:^",
"@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts
index 2670ab57c4..3eeea9c75c 100644
--- a/packages/fs/tool-fs-search/src/glob.ts
+++ b/packages/fs/tool-fs-search/src/glob.ts
@@ -1,10 +1,11 @@
/**
* The model-facing `glob` tool: discover files whose paths match a glob
- * pattern, sorted by modification time. Execution goes through the bash seam
- * (`ctx.bash`) with a fixed `rg --files` command — this module owns the
- * model-facing schema, argument validation, shell-safe command construction,
- * result parsing, inline sampling, and formatting; process concerns (defaulting,
- * scrubbing, kill, backend substitution) stay behind `ctx.bash`.
+ * pattern, sorted by modification time. Execution spawns the packaged
+ * ripgrep binary (`@vscode/ripgrep`) directly through the subprocess seam
+ * with a plain argv vector — this module owns the model-facing schema,
+ * argument validation, argv construction, result parsing, inline sampling,
+ * and formatting; process concerns (spawn execution, tree termination,
+ * environment scrubbing, output capture) stay behind `ctx.subprocess`.
* @module @deepseek-ai/dsh-tool-fs-search/glob
*/
@@ -13,11 +14,9 @@ import { sep } from 'node:path'
import { defineTool } from '@deepseek-ai/dsh-tools'
import type { GenericCallView, SearchResultView, ToolResult } from '@deepseek-ai/dsh-tools'
import type { SpillRef } from '@deepseek-ai/dsh-spill'
-import type {} from '@deepseek-ai/dsh-bash'
import type {} from '@deepseek-ai/dsh-system-prompt'
import { runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
import { globSearchMeta, searchViewFromMeta } from './presentation.ts'
-import { singleQuote } from './shell-quote.ts'
import { acceptedSurfaceValue } from './surface.ts'
/**
@@ -48,6 +47,10 @@ export interface GlobToolCaps {
maxMetaBytes: number
/** Cap on the complete raw `rg` stdout the tool will parse. */
rawOutputMaxBytes: number
+ /** Terminate-escalation grace period (ms) for the search process. */
+ graceMs: number
+ /** Cap on the retained stderr diagnostic tail. */
+ stderrMaxBytes: number
/** Cooperative tool-call budget (ms) attached as `ToolDefinition.timeoutMs`. */
timeoutMs: number
}
@@ -73,32 +76,35 @@ export function parseGlobArgs(args: { pattern: string; path?: string }): GlobInp
}
/**
- * Build the fixed `rg --files` command for one `glob` call. Every
+ * Build the fixed `rg --files` argv for one `glob` call. Every
* model-controlled value ({@link GlobInput.pattern}, {@link GlobInput.path})
- * passes through {@link singleQuote}; the search root rides behind `--` so a
- * leading-dash path can never be parsed as a flag. `--sort=modified` orders by
- * modification time, `--no-ignore --hidden` searches ignored and hidden files,
- * and {@link GLOB_VCS_EXCLUDES} keeps VCS metadata out.
+ * is a plain argv element — no shell layer exists, so no quoting applies; the
+ * search root rides behind `--` so a leading-dash path can never be parsed as
+ * a flag. `--sort=modified` orders by modification time, `--no-ignore
+ * --hidden` searches ignored and hidden files, and
+ * {@link GLOB_VCS_EXCLUDES} keeps VCS metadata out.
*
* @param input - the validated arguments.
- * @returns the complete, shell-safe command string.
+ * @returns the complete ripgrep argument vector (excluding the binary itself).
*/
-export function buildGlobCommand(input: GlobInput): string {
+export function buildGlobCommand(input: GlobInput): string[] {
const parts = [
- 'rg --files',
- `--glob=${singleQuote(input.pattern)}`,
- '--sort=modified --no-ignore --hidden',
+ '--files',
+ `--glob=${input.pattern}`,
+ '--sort=modified',
+ '--no-ignore',
+ '--hidden',
// Two negated globs per VCS name: the bare form prunes the directory
// during traversal; the /** form still excludes the contents when the
// search root is AT or INSIDE the directory (where the bare form,
// matched against root-prefixed paths, never fires).
...GLOB_VCS_EXCLUDES.flatMap(name => [
- `--glob=${singleQuote(`!**/${name}`)}`,
- `--glob=${singleQuote(`!**/${name}/**`)}`,
+ `--glob=!**/${name}`,
+ `--glob=!**/${name}/**`,
]),
]
- if (input.path !== undefined) parts.push('--', singleQuote(input.path))
- return parts.join(' ')
+ if (input.path !== undefined) parts.push('--', input.path)
+ return parts
}
/**
@@ -285,7 +291,7 @@ export function presentGlobResult(_args: { pattern: string; path?: string }, res
* Register the `glob` tool and its system-prompt guidance.
*
* @param ctx - the plugin context; registrations are effects scoped to it, and
- * execution uses its `bash` service.
+ * execution uses its `subprocess` service.
* @param caps - the deployment's resolved glob caps (plugin config after defaulting).
*/
export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void {
@@ -335,7 +341,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void {
},
async execute(args, exec) {
const input = parseGlobArgs(args)
- const run = await runRipgrep(ctx, exec, 'glob', buildGlobCommand(input), caps.rawOutputMaxBytes)
+ const run = await runRipgrep(ctx, exec, 'glob', buildGlobCommand(input), caps.rawOutputMaxBytes, caps.graceMs, caps.stderrMaxBytes)
const root = input.path === undefined ? '.' : toWorkdirRelative(input.path, run.workdir)
if (run.noMatches) return { root, paths: [] }
diff --git a/packages/fs/tool-fs-search/src/grep.ts b/packages/fs/tool-fs-search/src/grep.ts
index b7e67ea153..49548499ac 100644
--- a/packages/fs/tool-fs-search/src/grep.ts
+++ b/packages/fs/tool-fs-search/src/grep.ts
@@ -1,11 +1,12 @@
/**
* The model-facing `grep` tool: search file contents with a ripgrep regular
- * expression. Execution goes through the bash seam (`ctx.bash`) with a fixed
- * line-oriented `rg --json` command so file path, line number, and line text
- * parse without colon-splitting ambiguity — this module owns the model-facing
- * schema, argument validation, shell-safe command construction, `--json`
- * record parsing, per-line preview retention, match retention, grouping, and
- * formatting; process concerns stay behind `ctx.bash`.
+ * expression. Execution spawns the packaged ripgrep binary
+ * (`@vscode/ripgrep`) directly through the subprocess seam with a plain argv
+ * vector using a fixed line-oriented `rg --json` command so file path, line
+ * number, and line text parse without colon-splitting ambiguity — this module
+ * owns the model-facing schema, argument validation, argv construction,
+ * `--json` record parsing, per-line preview retention, match retention,
+ * grouping, and formatting; process concerns stay behind `ctx.subprocess`.
*
* @module @deepseek-ai/dsh-tool-fs-search/grep
*/
@@ -15,12 +16,10 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
import type { GenericCallView, SearchResultView, ToolResult } from '@deepseek-ai/dsh-tools'
import type { RetainedItems } from '@deepseek-ai/dsh-retention'
import type { SpillRef } from '@deepseek-ai/dsh-spill'
-import type {} from '@deepseek-ai/dsh-bash'
import type {} from '@deepseek-ai/dsh-system-prompt'
import type { GrepMatch } from './search-core.ts'
import { SearchError, previewLine, retainGrepMatches, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
import { grepSearchMeta, searchViewFromMeta } from './presentation.ts'
-import { singleQuote } from './shell-quote.ts'
import { acceptedSurfaceValue } from './surface.ts'
/**
@@ -46,6 +45,10 @@ export interface GrepToolCaps {
maxMetaBytes: number
/** Cap on the complete raw `rg` stdout the tool will parse. */
rawOutputMaxBytes: number
+ /** Terminate-escalation grace period (ms) for the search process. */
+ graceMs: number
+ /** Cap on the retained stderr diagnostic tail. */
+ stderrMaxBytes: number
/** Cooperative tool-call budget (ms) attached as `ToolDefinition.timeoutMs`. */
timeoutMs: number
}
@@ -96,20 +99,21 @@ export function parseGrepArgs(args: { pattern: string; path?: string; include?:
}
/**
- * Build the fixed line-oriented `rg --json` command for one `grep` call. Every
+ * Build the fixed line-oriented `rg --json` argv for one `grep` call. Every
* model-controlled value ({@link GrepInput.pattern}, {@link GrepInput.path},
- * {@link GrepInput.include}) passes through {@link singleQuote}; the pattern
- * and include ride in `--flag=value` form and the target behind `--`, so a
- * leading-dash value can never be parsed as a flag.
+ * {@link GrepInput.include}) is a plain argv element — no shell layer exists,
+ * so no quoting applies; the pattern and include ride in `--flag=value` form
+ * and the target behind `--`, so a leading-dash value can never be parsed as
+ * a flag.
*
* @param input - the validated arguments.
- * @returns the complete, shell-safe command string.
+ * @returns the complete ripgrep argument vector (excluding the binary itself).
*/
-export function buildGrepCommand(input: GrepInput): string {
- const parts = ['rg --json', `--regexp=${singleQuote(input.pattern)}`]
- if (input.include !== undefined) parts.push(`--glob=${singleQuote(input.include)}`)
- if (input.path !== undefined) parts.push('--', singleQuote(input.path))
- return parts.join(' ')
+export function buildGrepCommand(input: GrepInput): string[] {
+ const parts = ['--json', `--regexp=${input.pattern}`]
+ if (input.include !== undefined) parts.push(`--glob=${input.include}`)
+ if (input.path !== undefined) parts.push('--', input.path)
+ return parts
}
/**
@@ -265,7 +269,7 @@ export function presentGrepResult(
* Register the `grep` tool and its system-prompt guidance.
*
* @param ctx - the plugin context; registrations are effects scoped to it, and
- * execution uses its `bash` service.
+ * execution uses its `subprocess` service.
* @param caps - the deployment's resolved grep caps (plugin config after defaulting).
*/
export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void {
@@ -315,7 +319,7 @@ export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void {
},
async execute(args, exec) {
const input = parseGrepArgs(args)
- const run = await runRipgrep(ctx, exec, 'grep', buildGrepCommand(input), caps.rawOutputMaxBytes)
+ const run = await runRipgrep(ctx, exec, 'grep', buildGrepCommand(input), caps.rawOutputMaxBytes, caps.graceMs, caps.stderrMaxBytes)
if (run.noMatches) return { matches: [] }
const all: GrepMatch[] = []
diff --git a/packages/fs/tool-fs-search/src/index.ts b/packages/fs/tool-fs-search/src/index.ts
index 072865d568..7f8e43cb73 100644
--- a/packages/fs/tool-fs-search/src/index.ts
+++ b/packages/fs/tool-fs-search/src/index.ts
@@ -1,28 +1,27 @@
/**
* The model-facing filesystem discovery tool suite (`glob`, `grep`) over the
- * bash executor seam (`ctx.bash`). This single plugin registers both tools
- * only when the mounted bash executor can find `rg` on its `PATH`.
+ * packaged ripgrep binary (`@vscode/ripgrep`). This single plugin registers
+ * both tools; the binary ships inside the npm dependency, so no system `rg`
+ * install and no shell layer is involved.
*
- * ## Bash-backed, not a `ctx.fs` provider method
+ * ## Spawn-backed, not a `ctx.fs` provider method
*
* Local workspace discovery is a process-backed `rg` workflow, so these tools
- * execute through `ctx.bash.resolve(request)` → `ctx.bash.run(spec)` with fixed
- * ripgrep command templates — never `ctx.bash.start()`, never a model-visible
- * background task. The tool layer owns schemas, argument validation, shell
- * quoting ({@link module:@deepseek-ai/dsh-tool-fs-search/shell-quote}), result
- * parsing, retention, formatted-result spill, and timeout declaration; the
- * bash executor owns request defaulting/capping, subprocess execution,
- * process-group termination, environment scrubbing, raw output capture, and
- * backend substitution. At load, the package probes `command -v rg` through the
- * same bash seam; if ripgrep is absent, `glob` / `grep` and their prompt
- * sections are not registered. The package injects `tools`, `systemPrompt`,
- * and `bash` — deliberately NOT `fs`, and `ctx.spillStore` is read
+ * execute through `ctx.subprocess.spawn()` with fixed ripgrep argv templates —
+ * never `ctx.bash`, never `ctx.bash.start()`, never a model-visible background
+ * task. The tool layer owns schemas, argument validation, argv construction
+ * ({@link module:@deepseek-ai/dsh-tool-fs-search/glob} /
+ * {@link module:@deepseek-ai/dsh-tool-fs-search/grep}), result parsing,
+ * retention, formatted-result spill, and timeout declaration; the subprocess
+ * seam owns spawn execution, process-tree termination, environment scrubbing,
+ * and raw output capture. The package injects `tools`, `systemPrompt`, and
+ * `subprocess` — deliberately NOT `fs`, and `ctx.spillStore` is read
* opportunistically with `ctx.get()` because formatted-result spill is optional.
*
- * Returned paths are displayed relative to the resolved bash workdir and are
- * follow-up-readable only in co-located deployments where the bash workdir and
- * the filesystem `read` root are the same workspace — a documented v1
- * deployment requirement, not runtime-validated.
+ * Returned paths are displayed relative to the resolved workdir and are
+ * follow-up-readable only in co-located deployments where the workdir and the
+ * filesystem `read` root are the same workspace — a documented v1 deployment
+ * requirement, not runtime-validated.
*
* @module @deepseek-ai/dsh-tool-fs-search
*/
@@ -31,7 +30,7 @@ import type { Context } from 'cordis'
import z from 'schemastery'
import { GLOB_MAX_RESULTS, applyGlobTool } from './glob.ts'
import { GREP_MAX_LINE_BYTES, GREP_MAX_MATCHES, applyGrepTool } from './grep.ts'
-import { RAW_OUTPUT_MAX_BYTES, SEARCH_META_MAX_BYTES, SEARCH_TIMEOUT_MS } from './search-core.ts'
+import { RAW_OUTPUT_MAX_BYTES, SEARCH_GRACE_MS, SEARCH_META_MAX_BYTES, SEARCH_STDERR_MAX_BYTES, SEARCH_TIMEOUT_MS } from './search-core.ts'
export { GLOB_MAX_RESULTS, GLOB_VCS_EXCLUDES, applyGlobTool, buildGlobCommand, formatGlobOutput, parseGlobArgs, presentGlobCall, presentGlobResult, sampleAcrossTopLevel } from './glob.ts'
export type { GlobInput, GlobSample, GlobToolCaps } from './glob.ts'
@@ -50,22 +49,24 @@ export {
export type { GrepInput, GrepToolCaps } from './grep.ts'
export {
RAW_OUTPUT_MAX_BYTES,
+ SEARCH_GRACE_MS,
SEARCH_META_MAX_BYTES,
+ SEARCH_STDERR_MAX_BYTES,
SEARCH_TIMEOUT_MS,
SearchError,
previewLine,
+ resolveRgPath,
runRipgrep,
toWorkdirRelative,
trySaveFormattedResult,
} from './search-core.ts'
export type { GrepMatch, RipgrepRun, SearchErrorCode } from './search-core.ts'
-export { singleQuote } from './shell-quote.ts'
/** Cordis plugin name used by loader diagnostics. */
export const name = 'tool-fs-search'
/** Services required by the search tool suite (`spillStore` is optional, read via `ctx.get()`). */
-export const inject = ['tools', 'systemPrompt', 'bash']
+export const inject = ['tools', 'systemPrompt', 'subprocess']
/** Plugin config; over-cap glob sampling is an explicit deployment choice and the remaining fields have defaults. */
export interface Config {
@@ -81,6 +82,10 @@ export interface Config {
searchMetaMaxBytes?: number
/** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
rawOutputMaxBytes?: number
+ /** Terminate-escalation grace period (ms) for one search process, handed to the subprocess seam. */
+ graceMs?: number
+ /** Max bytes retained for one search's stderr tail; the excerpt is embedded in `SEARCH_*` error messages, never shown on success. */
+ stderrMaxBytes?: number
/** Cooperative tool-call timeout budget (ms) on both tools, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`. */
timeoutMs?: number
}
@@ -92,15 +97,14 @@ export const Config: z = z.object({
grepMaxLineBytes: z.number().default(GREP_MAX_LINE_BYTES),
searchMetaMaxBytes: z.number().default(SEARCH_META_MAX_BYTES),
rawOutputMaxBytes: z.number().default(RAW_OUTPUT_MAX_BYTES),
+ graceMs: z.number().default(SEARCH_GRACE_MS),
+ stderrMaxBytes: z.number().default(SEARCH_STDERR_MAX_BYTES),
timeoutMs: z.number().default(SEARCH_TIMEOUT_MS),
})
/** The shape after schemastery applied the defaults. */
type ResolvedConfig = Required
-/** POSIX-shell builtin probe for the ripgrep binary in the bash executor environment. */
-const RG_PROBE_COMMAND = 'command -v rg >/dev/null 2>&1'
-
/** Every search cap counts items/bytes/milliseconds — a positive integer, or retention and timeout arithmetic misbehaves silently. */
function assertPositiveInteger(name: string, value: number): void {
if (!Number.isInteger(value) || value < 1) {
@@ -109,36 +113,14 @@ function assertPositiveInteger(name: string, value: number): void {
}
/**
- * Check whether the mounted bash executor can find `rg`.
- *
- * Nonzero exit means "not available" and disables this optional tool suite.
- * Infrastructure failures stay loud: a deployment with a broken bash executor
- * should not silently lose tools in a way that looks like a deliberate skip.
- *
- * @param ctx - plugin context whose `bash` service is the executor the tools will use.
- * @returns true when `command -v rg` exits 0, false when it exits nonzero.
- */
-async function ripgrepAvailable(ctx: Context): Promise {
- const spec = ctx.bash.resolve({ command: RG_PROBE_COMMAND })
- let result
- try {
- result = await ctx.bash.run(spec)
- } catch (error: unknown) {
- throw new Error(`tool-fs-search: ripgrep availability probe could not start: ${String(error)}`, { cause: error })
- }
- if (result.aborted || result.timedOut || result.signal !== null || result.exitCode === null) {
- throw new Error('tool-fs-search: ripgrep availability probe did not complete')
- }
- return result.exitCode === 0
-}
-
-/**
- * Register the `glob`/`grep` filesystem discovery tool suite when `rg` exists.
+ * Register the `glob`/`grep` filesystem discovery tool suite. The packaged
+ * ripgrep binary is always available (an npm dependency), so registration is
+ * unconditional.
*
* @param ctx - plugin context; registrations are effects scoped to this plugin.
* @param config - resolved plugin configuration from schemastery.
- * @returns when ripgrep is unavailable, resolves without registering any tools.
*/
+// oxlint-disable-next-line typescript/require-await -- async keeps a load-time config rejection a rejection, not a synchronous throw
export async function apply(ctx: Context, config: Config): Promise {
// schemastery (Config) has already filled every defaulted field.
const resolved = config as ResolvedConfig
@@ -147,16 +129,16 @@ export async function apply(ctx: Context, config: Config): Promise {
assertPositiveInteger('grepMaxLineBytes', resolved.grepMaxLineBytes)
assertPositiveInteger('searchMetaMaxBytes', resolved.searchMetaMaxBytes)
assertPositiveInteger('rawOutputMaxBytes', resolved.rawOutputMaxBytes)
+ assertPositiveInteger('graceMs', resolved.graceMs)
+ assertPositiveInteger('stderrMaxBytes', resolved.stderrMaxBytes)
assertPositiveInteger('timeoutMs', resolved.timeoutMs)
- if (!await ripgrepAvailable(ctx)) {
- ctx.logger.warn('tool-fs-search: ripgrep (rg) not found on the bash executor PATH; glob/grep tools not registered')
- return
- }
applyGlobTool(ctx, {
sampleOverCapGlobResults: resolved.sampleOverCapGlobResults,
maxResults: resolved.globMaxResults,
maxMetaBytes: resolved.searchMetaMaxBytes,
rawOutputMaxBytes: resolved.rawOutputMaxBytes,
+ graceMs: resolved.graceMs,
+ stderrMaxBytes: resolved.stderrMaxBytes,
timeoutMs: resolved.timeoutMs,
})
applyGrepTool(ctx, {
@@ -164,6 +146,8 @@ export async function apply(ctx: Context, config: Config): Promise {
maxLineBytes: resolved.grepMaxLineBytes,
maxMetaBytes: resolved.searchMetaMaxBytes,
rawOutputMaxBytes: resolved.rawOutputMaxBytes,
+ graceMs: resolved.graceMs,
+ stderrMaxBytes: resolved.stderrMaxBytes,
timeoutMs: resolved.timeoutMs,
})
}
diff --git a/packages/fs/tool-fs-search/src/ripgrep.d.ts b/packages/fs/tool-fs-search/src/ripgrep.d.ts
new file mode 100644
index 0000000000..25d268471e
--- /dev/null
+++ b/packages/fs/tool-fs-search/src/ripgrep.d.ts
@@ -0,0 +1,12 @@
+/**
+ * Minimal type surface for the `@vscode/ripgrep` package: an ESM module that
+ * resolves the platform ripgrep binary (`@vscode/ripgrep--`
+ * optional dependency) and exports its absolute path as the named export
+ * `rgPath` (no bundled type declarations).
+ * @module @deepseek-ai/dsh-tool-fs-search/ripgrep-types
+ */
+
+declare module '@vscode/ripgrep' {
+ /** Absolute path to the packaged ripgrep executable for the current platform. */
+ export const rgPath: string
+}
diff --git a/packages/fs/tool-fs-search/src/search-core.ts b/packages/fs/tool-fs-search/src/search-core.ts
index 402fc9d655..854c593190 100644
--- a/packages/fs/tool-fs-search/src/search-core.ts
+++ b/packages/fs/tool-fs-search/src/search-core.ts
@@ -1,16 +1,19 @@
/**
* Shared execution plumbing for the `glob` / `grep` search tools: the
- * package-owned `SEARCH_*` error vocabulary, one bash-seam run helper that
- * turns a fixed `rg` command into complete raw stdout, the best-effort
- * formatted-result spill handoff, and workdir-relative path display.
+ * package-owned `SEARCH_*` error vocabulary, one spawn helper that runs the
+ * PACKAGED ripgrep binary (`@vscode/ripgrep`) with a plain argv vector and
+ * returns complete raw stdout, the best-effort formatted-result spill handoff,
+ * and workdir-relative path display.
*
- * Both tools execute through `ctx.bash.resolve(request)` → `ctx.bash.run(spec)`
- * as ordinary foreground tool calls — never `ctx.bash.start()`, never a
- * model-visible background task. Raw `rg` stdout is an internal transport
- * detail: the tools request a per-run stdout capture budget from the bash seam,
- * parse only complete in-memory stdout within `rawOutputMaxBytes`, and never
- * read executor spill files. The model-facing recovery artifact is the
- * formatted result saved through `ctx.spillStore.saveText()`
+ * Both tools execute as ordinary foreground spawns through `ctx.subprocess` —
+ * never `ctx.bash`, never `ctx.bash.start()`, never a model-visible background
+ * task. The ripgrep binary ships inside the npm package, so no system `rg`
+ * install is required, and no shell layer exists between the argv vector and
+ * ripgrep, so no shell quoting is involved. Raw `rg` stdout is an internal
+ * transport detail: the tools request a per-run stdout capture budget from the
+ * subprocess seam, parse only complete in-memory stdout within
+ * `rawOutputMaxBytes`, and never read spill files. The model-facing recovery
+ * artifact is the formatted result saved through `ctx.spillStore.saveText()`
* ({@link trySaveFormattedResult}).
*
* @module @deepseek-ai/dsh-tool-fs-search/search-core
@@ -21,7 +24,7 @@ import type { Context } from 'cordis'
import { HarnessError } from '@deepseek-ai/dsh-llm'
import { ItemRetainer, TextRetainer } from '@deepseek-ai/dsh-retention'
import type { RetainedItems } from '@deepseek-ai/dsh-retention'
-import type { BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type { SubprocessHandle, SubprocessOutcome, SubprocessOutputRead, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
import type { ToolExecution } from '@deepseek-ai/dsh-tools'
@@ -38,6 +41,16 @@ export const RAW_OUTPUT_MAX_BYTES = 20_000_000
*/
export const SEARCH_TIMEOUT_MS = 30_000
+/**
+ * Default cap in bytes on the retained stderr tail of one search run — a
+ * diagnostic excerpt only (the tool never reads a stderr spill path, and the
+ * collect disposition requests none).
+ */
+export const SEARCH_STDERR_MAX_BYTES = 64 * 1024
+
+/** Default terminate grace period for a search process (ms). */
+export const SEARCH_GRACE_MS = 3_000
+
/**
* Default cap in bytes on one search's serialized `presentationMeta` (the
* `searchMetaMaxBytes` config). The inline match/path caps already bound the item
@@ -52,14 +65,14 @@ export const SEARCH_META_MAX_BYTES = 65_536
/**
* Stable, machine-routable codes for search failures. Package-owned (not
- * `FsErrorCode`) because these tools are bash-backed discovery, not `ctx.fs`
+ * `FsErrorCode`) because these tools are spawn-backed discovery, not `ctx.fs`
* provider operations: `SEARCH_INVALID_PATTERN` — ripgrep rejected the regex or
* glob; `SEARCH_FAILED` — the search could not run or its output could not be
- * parsed (missing `rg`, inaccessible target, signal kill, malformed `--json`);
- * `SEARCH_RAW_OUTPUT_OVERFLOW` — raw `rg` output exceeded `rawOutputMaxBytes`
- * or stayed truncated after that requested stdout budget; `SEARCH_ABORTED` — the tool
- * timeout, caller cancellation, or the bash executor's own timeout cut the
- * search short.
+ * parsed (a failed `rg` launch, inaccessible target, signal kill, malformed
+ * `--json`); `SEARCH_RAW_OUTPUT_OVERFLOW` — raw `rg` output exceeded
+ * `rawOutputMaxBytes` or stayed truncated after that requested stdout budget;
+ * `SEARCH_ABORTED` — the cooperative tool timeout or caller cancellation cut
+ * the search short.
*/
export type SearchErrorCode =
| 'SEARCH_INVALID_PATTERN'
@@ -84,7 +97,7 @@ export class SearchError extends HarnessError {
/** The completed acquisition of one `rg` run: complete stdout plus the resolved workdir. */
export interface RipgrepRun {
- /** Complete raw stdout retained by the bash executor within the requested cap. */
+ /** Complete raw stdout retained by the subprocess seam within the requested cap. */
stdout: string
/** True when ripgrep exited 1: a successful search with zero results. */
noMatches: boolean
@@ -94,128 +107,183 @@ export interface RipgrepRun {
/**
* The retained stderr tail as a diagnostic excerpt, with a truncation note when
- * the executor dropped bytes (the tool never reads `stderr.spillPath`).
+ * the subprocess seam dropped bytes.
*/
-function stderrExcerpt(stderr: CollectedOutput): string {
- const text = stderr.text.trim()
+function stderrExcerpt(stderrText: string, truncated: boolean): string {
+ const text = stderrText.trim()
if (text.length === 0) return ''
- return stderr.truncated ? `${text} [stderr truncated]` : text
+ return truncated ? `${text} [stderr truncated]` : text
}
-/** Classify a nonzero-exit `rg` run into the search error vocabulary (invalid pattern vs missing `rg` vs everything else). */
-function classifyRunFailure(toolName: string, result: BashRunResult): SearchError {
- const stderr = stderrExcerpt(result.stderr)
+/**
+ * Classify a nonzero-exit `rg` run into the search error vocabulary. There is
+ * no shell layer, so an exit 127 or shell "command not found" text cannot
+ * occur — a launch failure rejects at spawn (see {@link runRipgrep}).
+ */
+function classifyRunFailure(toolName: string, exitCode: number, stderrText: string, stderrTruncated: boolean): SearchError {
+ const stderr = stderrExcerpt(stderrText, stderrTruncated)
if (/regex parse error|error parsing glob/i.test(stderr)) {
return new SearchError(`${toolName} pattern rejected by ripgrep: ${stderr}`, 'SEARCH_INVALID_PATTERN')
}
- if (result.exitCode === 127 || /command not found/i.test(stderr)) {
- return new SearchError(`${toolName} requires ripgrep (rg) on the bash executor's PATH${stderr.length > 0 ? `: ${stderr}` : ''}`, 'SEARCH_FAILED')
- }
- return new SearchError(`${toolName} search failed (exit ${result.exitCode})${stderr.length > 0 ? `: ${stderr}` : ''}`, 'SEARCH_FAILED')
+ return new SearchError(`${toolName} search failed (exit ${exitCode})${stderr.length > 0 ? `: ${stderr}` : ''}`, 'SEARCH_FAILED')
}
/**
* Acquire the COMPLETE raw stdout of a finished run, enforcing
* `rawOutputMaxBytes` on the in-memory transport. A truncated result means the
- * bash backend could not retain complete stdout within the requested budget, so
- * the tool fails clearly instead of parsing a silently-partial stream.
+ * subprocess seam could not retain complete stdout within the requested
+ * budget, so the tool fails clearly instead of parsing a silently-partial
+ * stream.
*/
-function completeStdout(toolName: string, result: BashRunResult, rawOutputMaxBytes: number): string {
+function completeStdout(toolName: string, stdout: SubprocessOutputRead, rawOutputMaxBytes: number): string {
const narrow = 'narrow pattern, path, or include and retry'
- if (!result.stdout.truncated) {
- const inlineBytes = Buffer.byteLength(result.stdout.text, 'utf8')
+ if (!stdout.lossy) {
+ const inlineBytes = Buffer.byteLength(stdout.text, 'utf8')
if (inlineBytes > rawOutputMaxBytes) {
throw new SearchError(
`${toolName} produced ${inlineBytes} bytes of raw output, over the ${rawOutputMaxBytes}-byte cap; ${narrow}`,
'SEARCH_RAW_OUTPUT_OVERFLOW',
)
}
- return result.stdout.text
+ return stdout.text
}
throw new SearchError(
- `${toolName} produced more raw output than the bash executor retained within the ${rawOutputMaxBytes}-byte cap; ${narrow}`,
+ `${toolName} produced more raw output than the subprocess seam retained within the ${rawOutputMaxBytes}-byte cap; ${narrow}`,
'SEARCH_RAW_OUTPUT_OVERFLOW',
)
}
+let rgPathPromise: Promise | undefined
+
/**
- * Run one fixed `rg` command through the bash seam and return its complete raw
- * stdout. The bash request workdir is the calling agent's session cwd
- * (`exec.agent.session.header.cwd`) when available — mirroring `dsh-tool-bash` /
- * `dsh-tool-fs` — else omitted so the implementation's `resolve()` applies its
- * configured default. `exec.signal` is forwarded so the cooperative tool
- * timeout (`@deepseek-ai/dsh-timeout-policy`) and caller cancellation kill the
- * command; the bash backend's own timeout stays a second safety cap.
+ * The packaged ripgrep binary path, resolved lazily once per process.
+ *
+ * `@vscode/ripgrep` resolves its platform package (`@vscode/ripgrep-
+ * -`) at module evaluation, so a static import would turn a missing or
+ * corrupt platform package (`pnpm install --omit=optional`, partial install)
+ * into a failure of the whole Loader composition. Resolving at the call
+ * boundary keeps that failure at the first search call as `SEARCH_FAILED` —
+ * the package's documented no-load-time-probe contract.
+ *
+ * @returns the packaged binary's absolute path; the memoized promise rejects
+ * when the platform package cannot be resolved.
+ */
+export function resolveRgPath(): Promise {
+ rgPathPromise ??= import('@vscode/ripgrep').then(module => module.rgPath)
+ return rgPathPromise
+}
+
+/**
+ * Run the packaged ripgrep binary with a plain argv vector and return its
+ * complete raw stdout. The working directory is the calling agent's session
+ * cwd (`exec.agent.session.header.cwd`) when available, else
+ * `process.cwd()`. `exec.signal` is forwarded so the cooperative tool timeout
+ * (`@deepseek-ai/dsh-timeout-policy`) and caller cancellation terminate the
+ * process tree.
+ *
+ * The spawn is unconfined (a plain `ctx.subprocess` call), so `--no-config`
+ * is prepended: a host `RIPGREP_CONFIG_PATH` (or `rg.conf` next to the
+ * binary) can otherwise inject `--pre` and make ripgrep execute an arbitrary
+ * preprocessor for every matched file. The collect dispositions are the
+ * seam's diagnostic-tail shape (no spill files): the tools never read a raw
+ * spill path, and truncated stdout fails as `SEARCH_RAW_OUTPUT_OVERFLOW`.
*
* Exit semantics are tool-owned: exit 0 is success with results, exit 1 is
* success with zero results (`noMatches`), anything else throws a
* {@link SearchError} (abort/timeout → `SEARCH_ABORTED`, invalid pattern →
* `SEARCH_INVALID_PATTERN`, the rest → `SEARCH_FAILED` /
- * `SEARCH_RAW_OUTPUT_OVERFLOW`). A `run()` REJECTION — the seam's
- * infrastructure failures (pre-aborted signal, unusable workdir, missing
- * shell) — is translated into the same taxonomy: a pre-aborted signal becomes
- * `SEARCH_ABORTED`, everything else `SEARCH_FAILED`, with the original as
- * `cause`.
+ * `SEARCH_RAW_OUTPUT_OVERFLOW`). Both launch-time failure domains are
+ * classified: a synchronous throw at spawn CREATION (a NUL in argv, an abort
+ * racing the pre-check, a rejected `@vscode/ripgrep` resolution) and a
+ * rejection of `handle.done` (the seam's infrastructure failures) both become
+ * `SEARCH_FAILED` with the original as `cause` — an abort already observed by
+ * creation time becomes `SEARCH_ABORTED` instead.
*
- * @param ctx - the plugin context; execution uses its `bash` service.
+ * @param ctx - the plugin context; execution uses its `subprocess` service.
* @param exec - the tool-execution context; supplies the session cwd and the abort signal.
* @param toolName - `glob` or `grep`, used in error messages.
- * @param command - the fully-quoted `rg` command string (every model value already through `singleQuote`).
+ * @param argv - the ripgrep arguments (every model value an unquoted argv element; no shell layer exists).
* @param rawOutputMaxBytes - cap on the complete raw stdout the tool will parse.
+ * @param graceMs - the seam's terminate-escalation grace period.
+ * @param stderrMaxBytes - cap on the retained stderr diagnostic tail.
* @returns the complete stdout, the zero-result flag, and the resolved workdir.
*/
export async function runRipgrep(
ctx: Context,
exec: ToolExecution,
toolName: string,
- command: string,
+ argv: readonly string[],
rawOutputMaxBytes: number,
+ graceMs: number,
+ stderrMaxBytes: number,
): Promise {
- const cwd = exec.agent?.session.header.cwd
- const spec = ctx.bash.resolve({
- command,
- stdoutMaxBytes: rawOutputMaxBytes,
- ...cwd !== undefined ? { workdir: cwd } : {},
- signal: exec.signal,
- })
- let result: BashRunResult
- try {
- result = await ctx.bash.run(spec)
- } catch (error: unknown) {
- // The seam contract: run() REJECTS only for infrastructure failures — a
- // pre-aborted signal, an unusable workdir, a missing shell. Translate them
- // so these failures stay machine-routable under the SEARCH_* taxonomy.
- if (spec.signal?.aborted === true) {
- throw new SearchError(`${toolName} was aborted before completion (tool timeout or caller cancellation)`, 'SEARCH_ABORTED', { cause: error })
- }
- throw new SearchError(`${toolName} could not start its search command (unusable working directory or missing shell)`, 'SEARCH_FAILED', { cause: error })
- }
- if (result.aborted) {
+ if (exec.signal.aborted) {
throw new SearchError(`${toolName} was aborted before completion (tool timeout or caller cancellation)`, 'SEARCH_ABORTED')
}
- if (result.timedOut) {
- throw new SearchError(`${toolName} timed out after ${result.timeoutMs}ms in the bash executor; narrow pattern, path, or include and retry`, 'SEARCH_ABORTED')
+ const cwd = exec.agent?.session.header.cwd
+ const workdir = cwd ?? process.cwd()
+ let handle: SubprocessHandle
+ try {
+ handle = ctx.subprocess.spawn({
+ argv: [await resolveRgPath(), '--no-config', ...argv],
+ cwd: workdir,
+ stdio: {
+ stdin: 'ignore',
+ stdout: { maxBytes: rawOutputMaxBytes },
+ stderr: { maxBytes: stderrMaxBytes },
+ },
+ graceMs,
+ signal: exec.signal,
+ } satisfies SubprocessSpawnSpec)
+ } catch (error: unknown) {
+ // Node's spawn() throws synchronously for a NUL in argv, and the local
+ // impl can throw synchronously when the signal aborts between the check
+ // above and this call (or when the platform-package resolution rejects).
+ // The static narrowing that proves this re-check "always false" cannot
+ // see AbortSignal state changes.
+ // oxlint-disable-next-line typescript/no-unnecessary-condition
+ if (exec.signal.aborted) {
+ throw new SearchError(`${toolName} was aborted before completion (tool timeout or caller cancellation)`, 'SEARCH_ABORTED')
+ }
+ throw new SearchError(`${toolName} could not start its search command (ripgrep launch failed)`, 'SEARCH_FAILED', { cause: error })
}
- if (result.signal !== null || result.exitCode === null) {
- throw new SearchError(`${toolName} search command was killed by signal ${result.signal ?? '(unknown)'}`, 'SEARCH_FAILED')
+ let outcome: SubprocessOutcome
+ try {
+ outcome = await handle.done
+ } catch (error: unknown) {
+ throw new SearchError(`${toolName} could not start its search command (ripgrep launch failed)`, 'SEARCH_FAILED', { cause: error })
}
- if (result.exitCode !== 0 && result.exitCode !== 1) {
- throw classifyRunFailure(toolName, result)
+ const stdout = handle.collected.stdout?.readFrom(0)
+ const stderr = handle.collected.stderr?.readFrom(0)
+ if (stdout === undefined || stderr === undefined) {
+ throw new SearchError(`${toolName} search command produced no collected output streams`, 'SEARCH_FAILED')
}
- const stdout = completeStdout(toolName, result, rawOutputMaxBytes)
- return { stdout, noMatches: result.exitCode === 1, workdir: spec.workdir }
+ // The signal can abort while the spawn is awaited; the static narrowing that
+ // proves this re-check "always false" cannot see AbortSignal state changes.
+ // oxlint-disable-next-line typescript/no-unnecessary-condition
+ if (exec.signal.aborted) {
+ throw new SearchError(`${toolName} was aborted before completion (tool timeout or caller cancellation)`, 'SEARCH_ABORTED')
+ }
+ if (outcome.signal !== null || outcome.exitCode === null) {
+ throw new SearchError(`${toolName} search command was killed by signal ${outcome.signal ?? '(unknown)'}`, 'SEARCH_FAILED')
+ }
+ if (outcome.exitCode !== 0 && outcome.exitCode !== 1) {
+ throw classifyRunFailure(toolName, outcome.exitCode, stderr.text, stderr.lossy)
+ }
+ const text = completeStdout(toolName, stdout, rawOutputMaxBytes)
+ return { stdout: text, noMatches: outcome.exitCode === 1, workdir }
}
/**
* Map an `rg` output path to its display form: absolute paths inside the
- * resolved bash workdir become workdir-relative; everything else (relative
- * output, paths outside the workdir) passes through unchanged. Display-only —
- * returned paths are follow-up-readable in co-located bash/filesystem
+ * resolved workdir become workdir-relative; everything else (relative output,
+ * paths outside the workdir) passes through unchanged. Display-only —
+ * returned paths are follow-up-readable in co-located workdir/filesystem
* deployments where both resolve the same workspace (the documented v1
* deployment requirement).
*
* @param path - one path as ripgrep printed it.
- * @param workdir - the resolved bash workdir the command ran in.
+ * @param workdir - the resolved workdir the command ran in.
* @returns the workdir-relative display path when possible, else `path` unchanged.
*/
export function toWorkdirRelative(path: string, workdir: string): string {
diff --git a/packages/fs/tool-fs-search/src/shell-quote.ts b/packages/fs/tool-fs-search/src/shell-quote.ts
deleted file mode 100644
index 9453b8e255..0000000000
--- a/packages/fs/tool-fs-search/src/shell-quote.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-/**
- * The one shell-quoting helper both search tools MUST route every
- * model-controlled value through before it enters an `rg` command string. The
- * bash seam (`ctx.bash`) accepts a command STRING, not an argv vector, so this
- * is the safety boundary that stops a `pattern`, `path`, or `include` from
- * breaking out of its argument and injecting shell syntax.
- *
- * Command builders in `glob.ts` / `grep.ts` must never hand-roll quoting or
- * concatenate an unquoted model value — they call {@link singleQuote}.
- *
- * @module @deepseek-ai/dsh-tool-fs-search/shell-quote
- */
-
-/**
- * POSIX single-quote a string for safe use as ONE shell word. Wraps the value
- * in single quotes and rewrites every embedded single quote as `'\''` (close
- * quote, an escaped literal quote, reopen quote). Inside single quotes the shell
- * treats every other byte literally — spaces, newlines, `$`, backticks, `;`,
- * `|`, `&`, glob metacharacters, and a leading `-` are all inert — so the result
- * is a single, injection-safe argument regardless of the input.
- *
- * @param value - the raw, possibly model-controlled string to quote.
- * @returns the value wrapped as one safe single-quoted shell word.
- */
-export function singleQuote(value: string): string {
- return `'${value.replaceAll("'", "'\\''")}'`
-}
diff --git a/packages/fs/tool-fs-search/tests/integration.spec.ts b/packages/fs/tool-fs-search/tests/integration.spec.ts
index 8cb96e7e66..dc7a88b30f 100644
--- a/packages/fs/tool-fs-search/tests/integration.spec.ts
+++ b/packages/fs/tool-fs-search/tests/integration.spec.ts
@@ -1,15 +1,16 @@
/**
- * Integration tests: the REAL local bash executor (`dsh-bash-local`) plus a
- * REAL ripgrep binary, exercised through `ctx.tools.execute()`. These verify
- * the WORLD — actual files on disk are discovered and grepped, hostile
- * patterns stay inert in a real shell, and real `rg` stderr classifies into
- * the `SEARCH_*` vocabulary. The whole suite self-skips when `rg` is not on
- * PATH (a CI accommodation mirroring the keyless e2e skip); the fake-executor
- * suite (tools.spec.ts) carries the coverage gate.
+ * Integration tests: the REAL local subprocess service plus the PACKAGED
+ * ripgrep binary (`@vscode/ripgrep`), exercised through `ctx.tools.execute()`.
+ * These verify the WORLD — actual files on disk are discovered and grepped,
+ * hostile patterns stay inert (they are plain argv elements; there is no
+ * shell layer to escape), and real `rg` stderr classifies into the
+ * `SEARCH_*` vocabulary. The binary ships inside the npm dependency, so the
+ * suite runs on every platform without a system `rg` install; the
+ * fake-service suite (tools.spec.ts) carries the coverage gate.
*/
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
import { mkdir, mkdtemp, rm, utimes, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
@@ -17,14 +18,11 @@ import { Context } from 'cordis'
import { CallId } from '@deepseek-ai/dsh-llm'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry, { TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools'
-import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
import * as ToolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
const testToolSignal = new AbortController().signal
-const hasRg = spawnSync('rg', ['--version'], { encoding: 'utf8' }).status === 0
-
let dir: string
let ctx: Context
@@ -43,7 +41,10 @@ function text(result: { content: { type: string; text?: string }[] }): string {
return result.content.filter(b => b.type === 'text').map(b => b.text).join('')
}
-describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', () => {
+/** The fixture workspace as a session cwd, so relative paths resolve inside `dir`. */
+const agent = () => ({ session: { header: { id: 'session-int', cwd: dir } } })
+
+describe('search tools over the real subprocess service + the packaged rg', () => {
beforeEach(async () => {
dir = await mkdtemp(join(tmpdir(), 'dsh-search-int-'))
await mkdir(join(dir, 'src'), { recursive: true })
@@ -54,7 +55,7 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', ()
await writeFile(join(dir, 'notes.md'), 'alpha appears here too\n')
await writeFile(join(dir, '.hidden.ts'), 'export const hidden = 3\n')
await writeFile(join(dir, '.git', 'config.ts'), 'never listed\n')
- await writeFile(join(dir, 'spaced dir', "wei'rd \"name\".ts"), 'const inside = true\n')
+ await writeFile(join(dir, 'spaced dir', "wei'rd name.ts"), 'const inside = true\n')
// Deterministic --sort=modified order: alpha oldest, beta newest.
await utimes(join(dir, 'src', 'alpha.ts'), new Date(2000, 0, 1), new Date(2000, 0, 1))
await utimes(join(dir, 'src', 'beta.ts'), new Date(2020, 0, 1), new Date(2020, 0, 1))
@@ -63,7 +64,6 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', ()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(LocalSubprocessService)
- await ctx.plugin(LocalBashExecutor, { cwd: dir, timeoutMs: 20_000 })
await ctx.plugin(ToolFsSearch, { sampleOverCapGlobResults: true })
})
@@ -73,33 +73,33 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', ()
describe('glob', () => {
it('discovers files by pattern, sorted by modification time, hidden included, .git excluded', async () => {
- const result = await call('glob', { pattern: '**/*.ts' })
+ const result = await call('glob', { pattern: '**/*.ts' }, agent())
expect(result.isError).toBe(false)
const paths = text(result).split('\n')
- expect(paths.indexOf('src/alpha.ts')).toBeLessThan(paths.indexOf('src/beta.ts'))
+ expect(paths.indexOf(join('src', 'alpha.ts'))).toBeLessThan(paths.indexOf(join('src', 'beta.ts')))
expect(paths).toContain('.hidden.ts')
- expect(paths).toContain("spaced dir/wei'rd \"name\".ts")
- expect(paths).not.toContain('.git/config.ts')
+ expect(paths).toContain(join('spaced dir', "wei'rd name.ts"))
+ expect(paths).not.toContain(join('.git', 'config.ts'))
expect(paths).not.toContain('notes.md')
})
it('scopes to a directory search root (path arg)', async () => {
- const result = await call('glob', { pattern: '*.ts', path: 'src' })
- expect(text(result).split('\n').sort()).toEqual(['src/alpha.ts', 'src/beta.ts'])
+ const result = await call('glob', { pattern: '*.ts', path: 'src' }, agent())
+ expect(text(result).split('\n').sort()).toEqual([join('src', 'alpha.ts'), join('src', 'beta.ts')])
})
it('reports zero discoveries as No files found', async () => {
- expect(text(await call('glob', { pattern: '*.nomatch' }))).toBe('No files found')
+ expect(text(await call('glob', { pattern: '*.nomatch' }, agent()))).toBe('No files found')
})
it('excludes VCS internals even when the search root IS the VCS directory', async () => {
// The prune glob alone never matches root-prefixed paths when rg is
// rooted at .git; the paired contents glob keeps the exclusion airtight.
- expect(text(await call('glob', { pattern: '*', path: '.git' }))).toBe('No files found')
+ expect(text(await call('glob', { pattern: '*', path: '.git' }, agent()))).toBe('No files found')
})
it('classifies an invalid glob as SEARCH_INVALID_PATTERN', async () => {
- const result = await call('glob', { pattern: '[' })
+ const result = await call('glob', { pattern: '[' }, agent())
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_INVALID_PATTERN' } })
})
@@ -107,37 +107,42 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', ()
describe('grep', () => {
it('greps a directory tree with grouped, line-numbered output', async () => {
- const result = await call('grep', { pattern: 'alpha' })
+ const result = await call('grep', { pattern: 'alpha' }, agent())
expect(result.isError).toBe(false)
const output = text(result)
expect(output).toContain('Found 3 matches')
- expect(output).toContain('src/alpha.ts\nLine 1: export const alpha = 1\nLine 2: // TODO: refit alpha')
+ expect(output).toContain(`${join('src', 'alpha.ts')}\nLine 1: export const alpha = 1\nLine 2: // TODO: refit alpha`)
expect(output).toContain('notes.md\nLine 1: alpha appears here too')
})
it('greps a single FILE target', async () => {
- const result = await call('grep', { pattern: 'alpha', path: 'notes.md' })
+ const result = await call('grep', { pattern: 'alpha', path: 'notes.md' }, agent())
expect(text(result)).toBe('Found 1 match\n\nnotes.md\nLine 1: alpha appears here too')
})
it('greps a directory target with an include filter', async () => {
- const result = await call('grep', { pattern: 'alpha', path: '.', include: '*.ts' })
+ const result = await call('grep', { pattern: 'alpha', path: '.', include: '*.ts' }, agent())
const output = text(result)
expect(output).toContain('alpha.ts')
expect(output).not.toContain('notes.md')
})
- it('a hostile pattern stays inert (no command substitution, the world untouched)', async () => {
+ it('a hostile pattern stays inert (a plain argv element, the world untouched)', async () => {
+ // There is no shell layer between the argv vector and rg, so the pattern
+ // is a literal regex — but the world-untouched guarantee is the shipped
+ // contract, and a future shell-wrapping change must not reintroduce it.
+ // The canary name carries no path so the regex stays valid on every
+ // platform (a Windows path's backslashes would be regex escapes).
const canary = join(dir, 'pwned')
- const result = await call('grep', { pattern: `$(touch ${canary})` })
+ const result = await call('grep', { pattern: '$(touch pwned)' }, agent())
expect(result.isError).toBe(false) // exit 1: found nothing, executed nothing
expect(text(result)).toBe('No matches found')
- expect(spawnSync('test', ['-e', canary]).status).not.toBe(0)
+ expect(existsSync(canary)).toBe(false)
})
it('a leading-dash pattern is a pattern, not a flag', async () => {
await writeFile(join(dir, 'dashes.txt'), 'value --flag value\n')
- const result = await call('grep', { pattern: '--flag', path: 'dashes.txt' })
+ const result = await call('grep', { pattern: '--flag', path: 'dashes.txt' }, agent())
expect(text(result)).toBe('Found 1 match\n\ndashes.txt\nLine 1: value --flag value')
})
@@ -155,7 +160,7 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', ()
})
describe('per-session cwd', () => {
- it('resolves the search in the SESSION workspace, not the executor config cwd', async () => {
+ it('resolves the search in the SESSION workspace, not the process cwd', async () => {
const sessionDir = await mkdtemp(join(tmpdir(), 'dsh-search-session-'))
try {
await writeFile(join(sessionDir, 'only-here.ts'), 'const sessionFile = true\n')
@@ -170,7 +175,7 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', ()
})
})
- describe('pre-dispatch cancellation and bash-start failures', () => {
+ describe('pre-dispatch cancellation and spawn failures', () => {
it('a pre-aborted registry call is ABORTED_BEFORE_DISPATCH', async () => {
const controller = new AbortController()
controller.abort()
diff --git a/packages/fs/tool-fs-search/tests/load-path.spec.ts b/packages/fs/tool-fs-search/tests/load-path.spec.ts
index 71022720fc..1d1e348c09 100644
--- a/packages/fs/tool-fs-search/tests/load-path.spec.ts
+++ b/packages/fs/tool-fs-search/tests/load-path.spec.ts
@@ -3,14 +3,15 @@
* a NAMESPACE plugin with `inject` — so a stray `export default apply` would
* make the cordis Loader's `unwrapExports` (`exports.default ?? exports`)
* collapse the module to the bare `apply` function, DROPPING `inject`. The
- * plugin would then read `ctx.bash` without having injected it and throw
+ * plugin would then read `ctx.subprocess` without having injected it and throw
* `cannot get property … without inject` the moment it loads (postmortem 0001).
*
* A hand-built `ctx.plugin({ apply, inject })` mount CANNOT catch that — it
* bypasses `unwrapExports`. So this test unwraps the module through the REAL
- * `Loader.prototype.unwrapExports` and mounts the result over a bash executor,
- * exercising the exact path the Loader uses. Prove the guard bites: add
- * `export default apply` to `src/index.ts`, watch this go red, revert.
+ * `Loader.prototype.unwrapExports` and mounts the result over the real local
+ * subprocess service, exercising the exact path the Loader uses. Prove the
+ * guard bites: add `export default apply` to `src/index.ts`, watch this go
+ * red, revert.
*/
import { describe, expect, it } from 'vitest'
@@ -18,48 +19,9 @@ import { Context } from 'cordis'
import Loader from '@cordisjs/plugin-loader'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry from '@deepseek-ai/dsh-tools'
-import { BashExecutor } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
import * as toolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
-const RG_PROBE_COMMAND = 'command -v rg >/dev/null 2>&1'
-
-/**
- * Deterministic bash service for this Loader guard: the test wants to exercise
- * the real unwrap/inject path, not depend on whether the host image has rg.
- */
-class ProbeSuccessBashExecutor extends BashExecutor {
- override resolve(request: BashExecRequest): BashExecSpec {
- return {
- command: request.command,
- workdir: request.workdir ?? '/work',
- timeoutMs: request.timeoutMs ?? 60_000,
- stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
- signal: request.signal,
- sandboxPolicy: request.sandboxPolicy,
- }
- }
-
- override run(spec: BashExecSpec): Promise {
- if (spec.command !== RG_PROBE_COMMAND) {
- throw new Error(`unexpected command in load-path guard: ${spec.command}`)
- }
- return Promise.resolve({
- exitCode: 0,
- signal: null,
- timedOut: false,
- aborted: false,
- timeoutMs: spec.timeoutMs,
- stdout: { text: '', truncated: false },
- stderr: { text: '', truncated: false },
- })
- }
-
- override start(): BashProcess {
- throw new Error('load-path guard must not start background processes')
- }
-}
-
describe('dsh-tool-fs-search real-load-path guard', () => {
it('has no default export and keeps name/inject/Config through unwrapExports', () => {
expect('default' in toolFsSearch).toBe(false)
@@ -68,16 +30,16 @@ describe('dsh-tool-fs-search real-load-path guard', () => {
const unwrapped = loader.unwrapExports(toolFsSearch) as Record
expect(unwrapped).toBe(toolFsSearch)
expect(unwrapped.name).toBe('tool-fs-search')
- expect(unwrapped.inject).toEqual(['tools', 'systemPrompt', 'bash'])
+ expect(unwrapped.inject).toEqual(['tools', 'systemPrompt', 'subprocess'])
expect(typeof unwrapped.Config).toBe('function')
expect(typeof unwrapped.apply).toBe('function')
})
- it('boots over ctx.bash through the unwrapped module without an inject error', async () => {
+ it('boots over ctx.subprocess through the unwrapped module without an inject error', async () => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
- await ctx.plugin(ProbeSuccessBashExecutor)
+ await ctx.plugin(LocalSubprocessService)
const loader = Object.create(Loader.prototype) as Loader
const unwrapped = loader.unwrapExports(toolFsSearch) as Parameters[0]
diff --git a/packages/fs/tool-fs-search/tests/rg-path.spec.ts b/packages/fs/tool-fs-search/tests/rg-path.spec.ts
new file mode 100644
index 0000000000..52888a3453
--- /dev/null
+++ b/packages/fs/tool-fs-search/tests/rg-path.spec.ts
@@ -0,0 +1,37 @@
+/**
+ * Failure-path tests for the lazy packaged-ripgrep resolution. The success
+ * path (the real `@vscode/ripgrep` module) is exercised throughout
+ * tools.spec.ts; here the module is mocked to throw at evaluation, proving a
+ * missing or corrupt platform package (`--omit=optional`, partial install)
+ * surfaces as a per-call `SEARCH_FAILED` — not a composition-load failure.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import { resolveRgPath, runRipgrep } from '@deepseek-ai/dsh-tool-fs-search'
+
+// Any access to the mocked module's surface throws — the shape a missing
+// platform package produces at module evaluation.
+vi.mock('@vscode/ripgrep', () => new Proxy({}, {
+ get() {
+ throw new Error('platform package @vscode/ripgrep-win32-x64 is not installed')
+ },
+}))
+
+describe('lazy packaged-ripgrep resolution', () => {
+ it('fails the first search call with SEARCH_FAILED instead of failing module load', async () => {
+ // The resolution rejects before any spawn, so no subprocess service is needed.
+ const controller = new AbortController()
+ const exec = { signal: controller.signal, name: 'glob', callId: CallId('missing-platform-package') } as unknown as ToolExecution
+
+ await expect(runRipgrep(new Context(), exec, 'glob', ['--files'], 1_000_000, 3_000, 64 * 1024))
+ .rejects.toMatchObject({ name: 'SearchError', code: 'SEARCH_FAILED' })
+ })
+
+ it('keeps failing every subsequent call (the resolution is memoized)', async () => {
+ await expect(resolveRgPath()).rejects.toThrow(/platform package/)
+ await expect(resolveRgPath()).rejects.toThrow(/platform package/)
+ })
+})
diff --git a/packages/fs/tool-fs-search/tests/shell-quote.spec.ts b/packages/fs/tool-fs-search/tests/shell-quote.spec.ts
deleted file mode 100644
index 84c8506be1..0000000000
--- a/packages/fs/tool-fs-search/tests/shell-quote.spec.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-/**
- * Unit tests for the shell-quoting safety boundary, plus a REAL round-trip:
- * every adversarial value, quoted, must survive `bash -c "printf '%s' "`
- * byte-for-byte — proving the quoting is inert in an actual shell, not just
- * against a mental model of one.
- */
-
-import { describe, expect, it } from 'vitest'
-import { spawnSync } from 'node:child_process'
-import { singleQuote } from '@deepseek-ai/dsh-tool-fs-search'
-
-/** Adversarial values a model could pass as pattern / path / include. */
-const HOSTILE: readonly string[] = [
- 'plain',
- 'with spaces',
- "it's got 'quotes'",
- '"double quoted"',
- '$(rm -rf /tmp/nope)',
- '`touch /tmp/nope`',
- '$HOME and ${PATH}',
- 'semi;colon && chain || pipe | bg &',
- 'newline\nin the middle',
- '-leading-dash',
- '--leading-double-dash',
- '*?[a-z]{x,y}',
- '!bang',
- '\\backslash\\',
- '~tilde',
- '# not a comment',
- '>redirect ): BashRunResult {
+/**
+ * Normalize a POSIX-style test path to the platform separator: the sampler and
+ * the workdir-relative display conversion group by `node:path.sep`, so
+ * `/`-literal paths would collapse into per-path groups on Windows.
+ */
+const w = (path: string): string => path.replaceAll('/', sep)
+
+/** One scripted collect-mode stream, returned by `readFrom(0)` after settlement. */
+interface ScriptedStream {
+ text: string
+ lossy?: boolean
+ spillPath?: string
+}
+
+/** One scripted spawn: exit facts plus the collected streams the tool reads. */
+interface ScriptedRun {
+ outcome: SubprocessOutcome
+ stdout: ScriptedStream
+ stderr: ScriptedStream
+}
+
+/** A successful run over the given stdout; overrides script the failure shapes. */
+function runResult(
+ stdout: string,
+ overrides?: Partial & { stdout?: Partial; stderr?: ScriptedStream },
+): ScriptedRun {
+ const { stdout: stdoutOverrides, stderr: stderrOverrides, ...outcome } = overrides ?? {}
return {
- exitCode: 0,
- signal: null,
- timedOut: false,
- aborted: false,
- timeoutMs: 60_000,
- stdout: { text: stdout, truncated: false },
- stderr: { text: '', truncated: false },
- ...overrides,
+ outcome: { exitCode: 0, signal: null, ...outcome },
+ stdout: { text: stdout, ...stdoutOverrides },
+ stderr: { text: '', ...stderrOverrides },
+ }
+}
+
+/** A fixed-response collect-mode reader: the tools read each stream once, from 0, after settlement. */
+class FakeReader implements SubprocessOutputReader {
+ constructor(private readonly read: ScriptedStream) {}
+
+ readFrom(_fromByte: number): SubprocessOutputRead {
+ return {
+ text: this.read.text,
+ nextOffset: 0,
+ lossy: this.read.lossy ?? false,
+ ...this.read.spillPath !== undefined ? { spillPath: this.read.spillPath } : {},
+ }
}
}
/**
- * A scriptable fake executor: `resolve()` mirrors the real request→spec
- * defaulting (workdir falls back to `/work`), `run()` returns whatever the
- * test armed via `handler`, and `start()` throws — the search tools must NEVER
- * create a background task.
+ * A scriptable subprocess handle: `done` resolves with the scripted outcome
+ * (or rejects with the scripted error), `terminate()` records the call, and
+ * the spec's abort signal marks the handle terminated — mirroring the seam's
+ * abort→terminate escalation.
*/
-class FakeBash extends BashExecutor {
- probeRequests: BashExecRequest[] = []
- probeSpecs: BashExecSpec[] = []
- requests: BashExecRequest[] = []
- specs: BashExecSpec[] = []
- startCalls = 0
- forwardSignal = true
- probeResult: BashRunResult = runResult('')
- probeError?: Error
- handler: (spec: BashExecSpec) => BashRunResult = () => runResult('')
+class FakeHandle implements SubprocessHandle {
+ readonly pid = 4242
+ readonly stdin = undefined
+ readonly stdout = undefined
+ readonly stderr = undefined
+ readonly collected: SubprocessCollectedOutputs
+ readonly done: Promise
+ /** True once `done` settled — the search tools must never leave a spawn running. */
+ settled = false
+ /** True when the handle's termination path ran (abort signal or explicit terminate). */
+ terminated = false
+ /** Scripted handle that drops one requested collect reader (the defensive branch). */
+ readonly dropReaders: boolean
- override resolve(request: BashExecRequest): BashExecSpec {
- if (request.command === RG_PROBE_COMMAND) this.probeRequests.push(request)
- else this.requests.push(request)
- return {
- command: request.command,
- workdir: request.workdir ?? '/work',
- timeoutMs: request.timeoutMs ?? 60_000,
- stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
- ...this.forwardSignal ? { signal: request.signal } : {},
- sandboxPolicy: request.sandboxPolicy,
+ constructor(spec: SubprocessSpawnSpec, script: () => ScriptedRun | { reject: Error }, dropReaders = false) {
+ this.dropReaders = dropReaders
+ // The abort listener attaches BEFORE the scripted run resolves, mirroring
+ // a real spawn: the escalation is armed when the process starts.
+ spec.signal?.addEventListener('abort', () => { this.terminated = true }, { once: true })
+ const scripted = script()
+ if ('reject' in scripted) {
+ // A spawn failure produces no process output, so no readers exist.
+ this.collected = {}
+ this.done = Promise.reject(scripted.reject)
+ } else {
+ this.collected = {
+ ...dropReaders ? {} : { stdout: new FakeReader(scripted.stdout), stderr: new FakeReader(scripted.stderr) },
+ }
+ this.done = Promise.resolve(scripted.outcome)
}
+ this.done.then(
+ () => { this.settled = true },
+ () => { this.settled = true },
+ )
}
- override async run(spec: BashExecSpec): Promise {
- if (spec.command === RG_PROBE_COMMAND) {
- this.probeSpecs.push(spec)
- if (this.probeError) throw this.probeError
- return this.probeResult
- }
- this.specs.push(spec)
- return this.handler(spec)
+
+ terminate(): void {
+ this.terminated = true
}
- override start(): BashProcess {
- this.startCalls++
- throw new Error('search tools must never start a background task')
+
+ waitForExit(_signal?: AbortSignal): Promise {
+ return Promise.resolve(true)
+ }
+}
+
+/**
+ * A scriptable fake subprocess service: `spawn()` records every spec and
+ * returns a handle scripted by the armed `handler`. The search tools must
+ * never spawn outside a single awaited foreground call, so every test can
+ * assert on the exact spawn specs and settled handles.
+ */
+class FakeSubprocess extends SubprocessService {
+ spawns: SubprocessSpawnSpec[] = []
+ handles: FakeHandle[] = []
+ /** Arms the per-spawn script; a `{ reject }` return scripts a spawn-level failure. */
+ handler: (spec: SubprocessSpawnSpec) => ScriptedRun | { reject: Error } = () => runResult('')
+ /** When true, spawned handles drop their collect readers (the defensive branch). */
+ dropReaders = false
+
+ override spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
+ this.spawns.push(spec)
+ const handle = new FakeHandle(spec, () => this.handler(spec), this.dropReaders)
+ this.handles.push(handle)
+ return handle
}
}
@@ -115,8 +180,6 @@ class FakeSpill extends SpillStore {
interface SetupOptions {
config?: Partial
spill?: boolean
- probeError?: Error
- probeResult?: BashRunResult
}
const DEFAULT_CONFIG = { sampleOverCapGlobResults: true } satisfies ToolFsSearch.Config
@@ -127,26 +190,12 @@ async function setup(options: SetupOptions = {}) {
ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
- await ctx.plugin(FakeBash)
- const bash = ctx.bash as FakeBash
- if (options.probeResult) bash.probeResult = options.probeResult
- if (options.probeError) bash.probeError = options.probeError
+ await ctx.plugin(FakeSubprocess)
+ const subprocess = ctx.subprocess as FakeSubprocess
if (options.spill === true) await ctx.plugin(FakeSpill)
const fiber = await ctx.plugin(ToolFsSearch, { ...DEFAULT_CONFIG, ...options.config })
const spill = options.spill === true ? ctx.get('spillStore') as FakeSpill : undefined
- return { ctx, bash, spill, fiber, warnings }
-}
-
-/** Assert plugin setup rejects without letting Vitest pretty-print a live Context on failure. */
-async function expectSetupRejects(options: SetupOptions, message: RegExp): Promise {
- let thrown: string | undefined
- try {
- const loaded = await setup(options)
- await loaded.fiber.dispose()
- } catch (error: unknown) {
- thrown = error instanceof Error ? error.message : String(error)
- }
- expect(thrown).toMatch(message)
+ return { ctx, subprocess, spill, fiber, warnings }
}
/** A stand-in agent whose session header carries the given cwd (and a stable id). */
@@ -180,11 +229,11 @@ function matchLine(path: string, lineNumber: number, lineText: string): string {
}
describe('registration', () => {
- it('registers glob and grep with their prompt sections', async () => {
- const { ctx, bash } = await setup()
- expect(bash.probeRequests).toHaveLength(1)
- expect(bash.probeRequests[0]?.command).toBe(RG_PROBE_COMMAND)
- expect(bash.probeRequests[0]).not.toHaveProperty('workdir')
+ it('registers glob and grep unconditionally with their prompt sections', async () => {
+ const { ctx, subprocess } = await setup()
+ // Registration performs NO load-time probe: the packaged binary is always
+ // available, so nothing spawns until a tool call.
+ expect(subprocess.spawns).toHaveLength(0)
expect(ctx.tools.schemas().map(s => s.name).sort()).toEqual(['glob', 'grep'])
const prompt = renderPrompt(await ctx.systemPrompt.assemble())
expect(prompt).toContain('Use the glob tool')
@@ -195,32 +244,11 @@ describe('registration', () => {
expect(glob?.description).toContain('sampled across top-level entries')
})
- it('does not register glob or grep when the bash executor cannot find rg', async () => {
- const { ctx, warnings } = await setup({ probeResult: runResult('', { exitCode: 1 }) })
- expect(ctx.tools.schemas()).toHaveLength(0)
- const sections = (await ctx.systemPrompt.assemble()).sections.map(s => s.name)
- expect(sections).not.toContain('tool:glob')
- expect(sections).not.toContain('tool:grep')
- expect(warnings).toEqual([
- 'tool-fs-search: ripgrep (rg) not found on the bash executor PATH; glob/grep tools not registered',
- ])
- })
-
- it('rejects plugin load when the rg availability probe cannot run', async () => {
- await expectSetupRejects({ probeError: new Error('spawn bash ENOENT') }, /spawn bash ENOENT/)
- })
-
- it('rejects plugin load when the rg availability probe is aborted or killed', async () => {
- await expectSetupRejects({
- probeResult: runResult('', { aborted: true, exitCode: null, signal: 'SIGTERM' }),
- }, /tool-fs-search: ripgrep availability probe did not complete/)
- })
-
- it('stays pending until ctx.bash exists (inject)', async () => {
+ it('stays pending until ctx.subprocess exists (inject)', async () => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
- await ctx.plugin(ToolFsSearch, DEFAULT_CONFIG) // no bash executor
+ await ctx.plugin(ToolFsSearch, DEFAULT_CONFIG) // no subprocess service
expect(ctx.tools.schemas()).toHaveLength(0)
})
@@ -271,144 +299,239 @@ describe('config validation', () => {
['grepMaxMatches', { grepMaxMatches: -1 }],
['grepMaxLineBytes', { grepMaxLineBytes: 1.5 }],
['rawOutputMaxBytes', { rawOutputMaxBytes: 0 }],
+ ['graceMs', { graceMs: 0 }],
+ ['stderrMaxBytes', { stderrMaxBytes: -1 }],
['timeoutMs', { timeoutMs: -100 }],
] as const)('rejects a non-positive or fractional %s at load', async (name, config) => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
- await ctx.plugin(FakeBash)
+ await ctx.plugin(FakeSubprocess)
await expect(ctx.plugin(ToolFsSearch, { ...DEFAULT_CONFIG, ...config })).rejects.toThrow(new RegExp(`tool-fs-search: ${name} must be a positive integer`))
})
})
-describe('command construction (shell-safe)', () => {
- it('glob: fixed rg --files template with quoted pattern and paired VCS excludes', () => {
- const command = buildGlobCommand({ pattern: '**/*.ts' })
- expect(command).toBe(
- "rg --files --glob='**/*.ts' --sort=modified --no-ignore --hidden "
- + "--glob='!**/.git' --glob='!**/.git/**' --glob='!**/.svn' --glob='!**/.svn/**' "
- + "--glob='!**/.hg' --glob='!**/.hg/**' --glob='!**/.bzr' --glob='!**/.bzr/**' "
- + "--glob='!**/.jj' --glob='!**/.jj/**' --glob='!**/.sl' --glob='!**/.sl/**'",
- )
+describe('command construction (plain argv)', () => {
+ it('glob: fixed rg --files argv with the pattern and paired VCS excludes', () => {
+ expect(buildGlobCommand({ pattern: '**/*.ts' })).toEqual([
+ '--files',
+ '--glob=**/*.ts',
+ '--sort=modified',
+ '--no-ignore',
+ '--hidden',
+ '--glob=!**/.git', '--glob=!**/.git/**',
+ '--glob=!**/.svn', '--glob=!**/.svn/**',
+ '--glob=!**/.hg', '--glob=!**/.hg/**',
+ '--glob=!**/.bzr', '--glob=!**/.bzr/**',
+ '--glob=!**/.jj', '--glob=!**/.jj/**',
+ '--glob=!**/.sl', '--glob=!**/.sl/**',
+ ])
})
- it('glob: the search root rides behind -- and is quoted', () => {
- const command = buildGlobCommand({ pattern: '*.md', path: 'docs dir' })
- expect(command).toContain("-- 'docs dir'")
+ it('glob: the search root rides behind -- as a plain element', () => {
+ expect(buildGlobCommand({ pattern: '*.md', path: 'docs dir' })).toEqual(['--files', '--glob=*.md', '--sort=modified', '--no-ignore', '--hidden',
+ '--glob=!**/.git', '--glob=!**/.git/**',
+ '--glob=!**/.svn', '--glob=!**/.svn/**',
+ '--glob=!**/.hg', '--glob=!**/.hg/**',
+ '--glob=!**/.bzr', '--glob=!**/.bzr/**',
+ '--glob=!**/.jj', '--glob=!**/.jj/**',
+ '--glob=!**/.sl', '--glob=!**/.sl/**',
+ '--', 'docs dir'])
})
- it('grep: fixed rg --json template with the pattern in --regexp= form', () => {
- expect(buildGrepCommand({ pattern: 'foo.*bar' })).toBe("rg --json --regexp='foo.*bar'")
+ it('grep: fixed rg --json argv with the pattern in --regexp= form', () => {
+ expect(buildGrepCommand({ pattern: 'foo.*bar' })).toEqual(['--json', '--regexp=foo.*bar'])
})
- it('grep: include and path are quoted, include in --glob= form, path behind --', () => {
- const command = buildGrepCommand({ pattern: 'x', path: '-leading-dash', include: '*.{ts,tsx}' })
- expect(command).toBe("rg --json --regexp='x' --glob='*.{ts,tsx}' -- '-leading-dash'")
+ it('grep: include in --glob= form, path behind --, both plain elements', () => {
+ expect(buildGrepCommand({ pattern: 'x', path: '-leading-dash', include: '*.{ts,tsx}' }))
+ .toEqual(['--json', '--regexp=x', '--glob=*.{ts,tsx}', '--', '-leading-dash'])
})
it.each([
- ['a command-substitution pattern', '$(rm -rf /)', "'$(rm -rf /)'"],
- ['a backtick pattern', '`touch pwned`', "'`touch pwned`'"],
- ['a pattern with double quotes and spaces', 'say "hi there"', '\'say "hi there"\''],
- ['a pattern with single quotes', "it's", '\'it\'\\\'\'s\''],
- ['a pattern with newlines', 'a\nb', "'a\nb'"],
- ['a leading-dash pattern', '--flag', "'--flag'"],
- ['glob metacharacters', '*?[a-z]{x,y}', "'*?[a-z]{x,y}'"],
- ])('quotes %s into one inert shell word', (_label, raw, quoted) => {
- expect(buildGrepCommand({ pattern: raw })).toBe(`rg --json --regexp=${quoted}`)
+ ['a command-substitution pattern', '$(rm -rf /)'],
+ ['a backtick pattern', '`touch pwned`'],
+ ['a pattern with double quotes and spaces', 'say "hi there"'],
+ ['a pattern with single quotes', "it's"],
+ ['a pattern with newlines', 'a\nb'],
+ ['a leading-dash pattern', '--flag'],
+ ['glob metacharacters', '*?[a-z]{x,y}'],
+ ])('keeps %s as ONE inert argv element (no shell layer to escape)', (_label, raw) => {
+ // The argv vector is handed to rg verbatim: hostile text cannot break out
+ // of its argument because there is no shell between the vector and rg.
+ expect(buildGrepCommand({ pattern: raw })).toEqual(['--json', `--regexp=${raw}`])
+ expect(buildGlobCommand({ pattern: raw })[1]).toBe(`--glob=${raw}`)
})
})
describe('workdir derivation and signal forwarding', () => {
- it('forwards the session cwd as the request workdir', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('a.ts\n')
+ it('forwards the session cwd as the spawn cwd', async () => {
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('a.ts\n')
await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/sessions/s1') })
- expect(bash.requests[0]?.workdir).toBe('/sessions/s1')
- expect(bash.specs[0]?.workdir).toBe('/sessions/s1')
+ expect(subprocess.spawns[0]?.cwd).toBe('/sessions/s1')
})
- it('omits the request workdir without a session cwd so resolve() defaults apply', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('a.ts\n')
+ it('defaults the spawn cwd to process.cwd() without a session cwd', async () => {
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('a.ts\n')
await call(ctx, 'glob', { pattern: '*' }, { agent: agent() })
- expect(bash.requests[0]).not.toHaveProperty('workdir')
- expect(bash.specs[0]?.workdir).toBe('/work')
- // A non-agent caller takes the same default path.
+ expect(subprocess.spawns[0]?.cwd).toBe(process.cwd())
+ // A non-agent caller takes the same default.
await call(ctx, 'grep', { pattern: 'x' })
- expect(bash.requests[1]).not.toHaveProperty('workdir')
+ expect(subprocess.spawns[1]?.cwd).toBe(process.cwd())
})
- it('forwards exec.signal into the bash spec', async () => {
- const { ctx, bash } = await setup()
+ it('spawns the packaged ripgrep binary with --no-config, the fixed argv, and budgeted collect streams', async () => {
+ const { ctx, subprocess } = await setup({
+ config: { rawOutputMaxBytes: 1234, graceMs: 5000, stderrMaxBytes: 4096 },
+ })
+ subprocess.handler = () => runResult('', { exitCode: 1 })
+ await call(ctx, 'grep', { pattern: 'needle' })
+ const spec = subprocess.spawns[0]
+ // --no-config keeps a host RIPGREP_CONFIG_PATH from injecting a
+ // preprocessor into this unconfined spawn.
+ expect(spec?.argv).toEqual([rgPath, '--no-config', '--json', '--regexp=needle'])
+ expect(spec?.stdio.stdin).toBe('ignore')
+ // stdout gets the tool's parse budget; stderr is a diagnostic excerpt;
+ // both are the seam's diagnostic-tail shape (no spill files requested).
+ expect((spec?.stdio.stdout as { maxBytes: number }).maxBytes).toBe(1234)
+ expect((spec?.stdio.stderr as { maxBytes: number }).maxBytes).toBe(4096)
+ expect(spec?.graceMs).toBe(5_000)
+ })
+
+ it('defaults the stderr tail budget and grace period when the config omits them', async () => {
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { exitCode: 1 })
+ await call(ctx, 'grep', { pattern: 'needle' })
+ const spec = subprocess.spawns[0]
+ expect((spec?.stdio.stderr as { maxBytes: number }).maxBytes).toBe(64 * 1024)
+ expect(spec?.graceMs).toBe(3_000)
+ })
+
+ it('forwards exec.signal into the spawn spec', async () => {
+ const { ctx, subprocess } = await setup()
const controller = new AbortController()
- bash.handler = () => runResult('')
+ subprocess.handler = () => runResult('')
const result = await call(ctx, 'grep', { pattern: 'x' }, { signal: controller.signal })
- expect(bash.specs[0]?.signal).toBe(controller.signal)
+ expect(subprocess.spawns[0]?.signal).toBe(controller.signal)
expect(result.isError).toBe(false)
})
- it('reports the bash executor timeout as SEARCH_ABORTED with the budget', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { timedOut: true, timeoutMs: 1234, exitCode: null, signal: 'SIGTERM' })
- const result = await call(ctx, 'glob', { pattern: '*' })
+ it('reports an abort fired during the run as SEARCH_ABORTED', async () => {
+ // The cooperative tool timeout or caller cancellation aborts exec.signal;
+ // the subprocess seam then kills the process tree. The tool classifies
+ // the first cause it owns: the abort.
+ const { ctx, subprocess } = await setup()
+ const controller = new AbortController()
+ subprocess.handler = () => {
+ controller.abort('timeout')
+ return runResult('', { exitCode: null, signal: 'SIGTERM' })
+ }
+ const result = await call(ctx, 'glob', { pattern: '*' }, { signal: controller.signal })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ info: { code: 'SEARCH_ABORTED' } })
- expect(text(result)).toContain('timed out after 1234ms')
+ expect(text(result)).toContain('aborted before completion')
+ expect(subprocess.handles[0]?.terminated).toBe(true)
})
- it('skips a pre-aborted registry call before run()', async () => {
- const { ctx, bash } = await setup()
+ it('skips a pre-aborted registry call before spawn()', async () => {
+ const { ctx, subprocess } = await setup()
const controller = new AbortController()
controller.abort()
- bash.handler = () => { throw new Error('aborted before spawn') }
+ subprocess.handler = () => { throw new Error('aborted before spawn') }
const result = await call(ctx, 'grep', { pattern: 'x' }, { signal: controller.signal })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } })
- expect(bash.specs).toHaveLength(0)
+ expect(subprocess.spawns).toHaveLength(0)
})
- it('translates a run() rejection after the forwarded signal aborts', async () => {
- const { ctx, bash } = await setup()
+ it('fails a pre-aborted exec.signal before spawn with SEARCH_ABORTED', async () => {
+ // Direct unit check of runRipgrep's own pre-spawn guard: the registry
+ // intercepts most pre-aborted calls, but a signal that aborts between the
+ // registry check and execute reaches this branch.
+ const { ctx } = await setup()
const controller = new AbortController()
- bash.handler = () => {
+ controller.abort()
+ const exec = { signal: controller.signal, name: 'glob', callId: CallId('direct-pre-abort') } as unknown as ToolExecution
+ await expect(runRipgrep(ctx, exec, 'glob', ['--files'], 1_000_000, 3_000, 64 * 1024)).rejects
+ .toMatchObject({ name: 'SearchError', code: 'SEARCH_ABORTED' })
+ })
+
+ it('translates a spawn rejection into SEARCH_FAILED even when the signal aborts concurrently', async () => {
+ // The seam rejects only for infrastructure failures (unusable workdir,
+ // missing binary); the abort happened after dispatch, so the launch
+ // failure is the reportable cause with the original error chained.
+ const { ctx, subprocess } = await setup()
+ const controller = new AbortController()
+ subprocess.handler = () => {
controller.abort('cancel search')
- throw new Error('executor stopped on abort')
+ return { reject: new Error('spawn ENOENT') }
}
const result = await call(ctx, 'grep', { pattern: 'x' }, { signal: controller.signal })
expect(result.isError).toBe(true)
- expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_ABORTED' } })
- expect(text(result)).toContain('aborted before completion')
+ expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_FAILED' } })
+ expect(text(result)).toContain('could not start')
})
- it('translates an aborted executor result after dispatch starts', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { aborted: true, exitCode: null })
+ it('classifies a synchronous spawn-creation throw as SEARCH_FAILED', async () => {
+ // Node's spawn() throws synchronously for a NUL in argv, and the local
+ // impl can throw synchronously for other invalid specs. Creation-time
+ // failures must join the error vocabulary instead of escaping raw.
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => { throw new Error('spawn ERR_INVALID_ARG_VALUE') }
- const result = await call(ctx, 'glob', { pattern: '*' })
+ const result = await call(ctx, 'grep', { pattern: 'x' })
- expect(result.isError).toBe(true)
- expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_ABORTED' } })
- expect(text(result)).toContain('aborted before completion')
- })
-
- it('translates a run() rejection without an abort (unusable workdir) into SEARCH_FAILED', async () => {
- const { ctx, bash } = await setup()
- bash.forwardSignal = false
- bash.handler = () => { throw new Error('spawn bash ENOENT') }
- const result = await call(ctx, 'glob', { pattern: '*' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_FAILED' } })
expect(text(result)).toContain('could not start')
})
+
+ it('classifies a synchronous spawn-creation throw after an abort as SEARCH_ABORTED', async () => {
+ // The local impl can throw synchronously when the signal aborts between
+ // the pre-spawn check and the spawn call; no process was launched, so the
+ // abort is the reportable cause.
+ const { ctx, subprocess } = await setup()
+ const controller = new AbortController()
+ subprocess.handler = () => {
+ controller.abort('timeout')
+ throw new Error('aborted during spawn')
+ }
+
+ const result = await call(ctx, 'glob', { pattern: '*' }, { signal: controller.signal })
+
+ expect(result.isError).toBe(true)
+ expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_ABORTED' } })
+ expect(text(result)).toContain('aborted before completion')
+ })
+
+ it('resolves the packaged ripgrep path lazily, once per process', async () => {
+ // The module must not touch @vscode/ripgrep at load (a missing platform
+ // package would otherwise fail the whole composition), and repeated
+ // resolution reuses the first result. The resolution-failure path is
+ // pinned separately in rg-path.spec.ts.
+ await setup()
+ expect(await resolveRgPath()).toBe(rgPath)
+ expect(resolveRgPath()).toBe(resolveRgPath())
+ })
+
+ it('rejects when the subprocess implementation drops a requested collect stream', async () => {
+ const { ctx, subprocess } = await setup()
+ subprocess.dropReaders = true
+ const result = await call(ctx, 'glob', { pattern: '*' })
+ expect(result.isError).toBe(true)
+ expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_FAILED' } })
+ expect(text(result)).toContain('no collected output streams')
+ })
})
describe('exit semantics and failure classification', () => {
it('exit 1 is a successful empty search', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { exitCode: 1 })
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { exitCode: 1 })
const glob = await call(ctx, 'glob', { pattern: '*.nope' })
expect(glob.isError).toBe(false)
expect(text(glob)).toBe('No files found')
@@ -418,108 +541,86 @@ describe('exit semantics and failure classification', () => {
})
it('a regex parse error classifies as SEARCH_INVALID_PATTERN', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: regex parse error:\n (\nerror: unclosed group', truncated: false } })
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: regex parse error:\n (\nerror: unclosed group' } })
const result = await call(ctx, 'grep', { pattern: '(' })
expect(result.error).toMatchObject({ info: { code: 'SEARCH_INVALID_PATTERN' } })
expect(text(result)).toContain('regex parse error')
})
it('a glob parse error classifies as SEARCH_INVALID_PATTERN', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: error parsing glob \'[\': unclosed character class', truncated: false } })
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: error parsing glob \'[\': unclosed character class' } })
const result = await call(ctx, 'glob', { pattern: '[' })
expect(result.error).toMatchObject({ info: { code: 'SEARCH_INVALID_PATTERN' } })
})
- it('a missing rg binary classifies as SEARCH_FAILED naming ripgrep', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { exitCode: 127, stderr: { text: 'bash: line 1: rg: command not found', truncated: false } })
- const result = await call(ctx, 'glob', { pattern: '*' })
- expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
- expect(text(result)).toContain('requires ripgrep (rg)')
- // The same classification holds from either evidence alone: the 127 exit
- // with silent stderr, or a shell's command-not-found text on another exit.
- bash.handler = () => runResult('', { exitCode: 127 })
- expect(text(await call(ctx, 'glob', { pattern: '*' }))).toContain('requires ripgrep (rg)')
- bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'sh: rg: command not found', truncated: false } })
- expect(text(await call(ctx, 'grep', { pattern: 'x' }))).toContain('requires ripgrep (rg)')
- })
-
it('other nonzero exits are SEARCH_FAILED carrying the stderr excerpt', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: missing.dir: IO error: no such file or directory', truncated: false } })
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: missing.dir: IO error: no such file or directory' } })
const result = await call(ctx, 'grep', { pattern: 'x', path: 'missing.dir' })
expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
expect(text(result)).toContain('IO error')
})
it('a nonzero exit with EMPTY stderr still reports the exit code', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { exitCode: 3 })
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { exitCode: 3 })
const result = await call(ctx, 'glob', { pattern: '*' })
expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
expect(text(result)).toContain('exit 3')
})
it('truncated stderr gains a truncation note and stderr.spillPath is never read', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', {
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', {
exitCode: 2,
- stderr: { text: 'tail of diagnostics', truncated: true, spillPath: '/does/not/exist-and-never-read' },
+ stderr: { text: 'tail of diagnostics', lossy: true, spillPath: '/does/not/exist-and-never-read' },
})
const result = await call(ctx, 'grep', { pattern: 'x' })
expect(text(result)).toContain('tail of diagnostics [stderr truncated]')
})
it('a signal kill (not timeout, not abort) is SEARCH_FAILED', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { exitCode: null, signal: 'SIGKILL' })
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { exitCode: null, signal: 'SIGKILL' })
const result = await call(ctx, 'grep', { pattern: 'x' })
expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
expect(text(result)).toContain('SIGKILL')
})
it('a null exit with no signal (defensive) is SEARCH_FAILED', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { exitCode: null, signal: null })
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { exitCode: null, signal: null })
const result = await call(ctx, 'glob', { pattern: '*' })
expect(result.error).toMatchObject({ info: { code: 'SEARCH_FAILED' } })
+ expect(text(result)).toContain('killed by signal (unknown)')
})
})
describe('raw output acquisition', () => {
- it('passes rawOutputMaxBytes to bash as the stdout capture budget', async () => {
- const { ctx, bash } = await setup({ config: { rawOutputMaxBytes: 1234 } })
- bash.handler = () => runResult('', { exitCode: 1 })
- await call(ctx, 'glob', { pattern: '*.ts' })
- await call(ctx, 'grep', { pattern: 'needle' })
- expect(bash.requests.map(request => request.stdoutMaxBytes)).toEqual([1234, 1234])
- expect(bash.specs.map(spec => spec.stdoutMaxBytes)).toEqual([1234, 1234])
- })
-
it('fails with SEARCH_RAW_OUTPUT_OVERFLOW when truncated stdout has a raw spill path', async () => {
- const { ctx, bash } = await setup({ config: { rawOutputMaxBytes: 16 } })
- bash.handler = () => runResult('', { stdout: { text: 'x', truncated: true, spillPath: '/does/not/get-read' } })
+ const { ctx, subprocess } = await setup({ config: { rawOutputMaxBytes: 16 } })
+ subprocess.handler = () => runResult('', { stdout: { text: 'x', lossy: true, spillPath: '/does/not/get-read' } })
const result = await call(ctx, 'glob', { pattern: '*' })
expect(result.error).toMatchObject({ info: { code: 'SEARCH_RAW_OUTPUT_OVERFLOW' } })
expect(text(result)).toContain('narrow pattern, path, or include')
})
it('fails with SEARCH_RAW_OUTPUT_OVERFLOW when UNTRUNCATED inline stdout exceeds the cap', async () => {
- // An executor retaining more inline than this package's cap (or a
- // deployment lowering rawOutputMaxBytes below the bash retention) must not
- // smuggle an over-cap parse through the untruncated path.
- const { ctx, bash } = await setup({ config: { rawOutputMaxBytes: 16 } })
- bash.handler = () => runResult(`${'x'.repeat(64)}\n`)
+ // A subprocess implementation retaining more inline than this package's
+ // cap (or a deployment lowering rawOutputMaxBytes below the retention
+ // budget) must not smuggle an over-cap parse through the untruncated path.
+ const { ctx, subprocess } = await setup({ config: { rawOutputMaxBytes: 16 } })
+ subprocess.handler = () => runResult(`${'x'.repeat(64)}\n`)
const result = await call(ctx, 'grep', { pattern: 'x' })
expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_RAW_OUTPUT_OVERFLOW' } })
expect(text(result)).toContain('narrow pattern, path, or include')
})
it('fails with SEARCH_RAW_OUTPUT_OVERFLOW when truncated stdout has no spill path', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { stdout: { text: 'partial', truncated: true } })
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { stdout: { text: 'partial', lossy: true } })
const result = await call(ctx, 'grep', { pattern: 'x' })
expect(result.error).toMatchObject({ info: { code: 'SEARCH_RAW_OUTPUT_OVERFLOW' } })
})
@@ -527,24 +628,24 @@ describe('raw output acquisition', () => {
describe('cross-directory sampling', () => {
it('gives every top-level entry a slot before any entry gets a second', () => {
- const paths = ['v/a', 'v/b', 'v/c', 'v/d', 'src/e', 'guide/f']
+ const paths = ['v/a', 'v/b', 'v/c', 'v/d', 'src/e', 'guide/f'].map(w)
// The head of 3 would be all `v/`; the sample reaches all three entries.
- expect(sampleAcrossTopLevel(paths, 3)).toEqual({ items: ['v/a', 'src/e', 'guide/f'], shown: 3, total: 3 })
+ expect(sampleAcrossTopLevel(paths, 3)).toEqual({ items: ['v/a', 'src/e', 'guide/f'].map(w), shown: 3, total: 3 })
// Extra slots go round again — to the only entry with paths left — and the
// page stays grouped by entry rather than interleaved.
- expect(sampleAcrossTopLevel(paths, 5)).toEqual({ items: ['v/a', 'v/b', 'v/c', 'src/e', 'guide/f'], shown: 3, total: 3 })
+ expect(sampleAcrossTopLevel(paths, 5)).toEqual({ items: ['v/a', 'v/b', 'v/c', 'src/e', 'guide/f'].map(w), shown: 3, total: 3 })
})
it('hands an exhausted entry the remaining slots go to entries that still have paths', () => {
- const paths = ['solo/a', 'many/b', 'many/c', 'many/d']
- expect(sampleAcrossTopLevel(paths, 3)).toEqual({ items: ['solo/a', 'many/b', 'many/c'], shown: 2, total: 2 })
+ const paths = ['solo/a', 'many/b', 'many/c', 'many/d'].map(w)
+ expect(sampleAcrossTopLevel(paths, 3)).toEqual({ items: ['solo/a', 'many/b', 'many/c'].map(w), shown: 2, total: 2 })
})
it('does not rescan exhausted entries while filling a skewed page', () => {
const singletonCount = 12_500
const paths = [
- ...Array.from({ length: singletonCount }, (_, index) => `group-${index}/only`),
- ...Array.from({ length: singletonCount }, (_, index) => `late/${index}`),
+ ...Array.from({ length: singletonCount }, (_, index) => `group-${index}${sep}only`),
+ ...Array.from({ length: singletonCount }, (_, index) => `late${sep}${index}`),
]
expect(sampleAcrossTopLevel(paths, paths.length - 1)).toMatchObject({
shown: singletonCount + 1,
@@ -554,15 +655,15 @@ describe('cross-directory sampling', () => {
}, 500)
it('reports the entries it could not reach when the page is smaller than the top level', () => {
- const paths = ['a/1', 'b/1', 'c/1', 'd/1']
- expect(sampleAcrossTopLevel(paths, 2)).toEqual({ items: ['a/1', 'b/1'], shown: 2, total: 4 })
+ const paths = ['a/1', 'b/1', 'c/1', 'd/1'].map(w)
+ expect(sampleAcrossTopLevel(paths, 2)).toEqual({ items: ['a/1', 'b/1'].map(w), shown: 2, total: 4 })
})
it('groups an absolute path by its first real name, not by its empty root segment', () => {
// Paths outside the workdir stay absolute; without stripping the leading
// separator every one of them would collapse into a single empty group.
- expect(sampleAcrossTopLevel(['/out/a', '/out/b', '/away/c', '/away/d'], 2))
- .toEqual({ items: ['/out/a', '/away/c'], shown: 2, total: 2 })
+ expect(sampleAcrossTopLevel(['/out/a', '/out/b', '/away/c', '/away/d'].map(w), 2))
+ .toEqual({ items: ['/out/a', '/away/c'].map(w), shown: 2, total: 2 })
})
it('reproduces the modification-time-ordered head for a flat result', () => {
@@ -575,15 +676,15 @@ describe('cross-directory sampling', () => {
'workspace/vendor/b.ts',
'workspace/source/c.ts',
'workspace/guides/d.md',
- ], 3, 'workspace')).toEqual({
- items: ['workspace/vendor/a.ts', 'workspace/source/c.ts', 'workspace/guides/d.md'],
+ ].map(w), 3, 'workspace')).toEqual({
+ items: ['workspace/vendor/a.ts', 'workspace/source/c.ts', 'workspace/guides/d.md'].map(w),
shown: 3,
total: 3,
})
- expect(sampleAcrossTopLevel(['./vendor/a.ts', './src/b.ts'], 2, '.'))
- .toEqual({ items: ['./vendor/a.ts', './src/b.ts'], shown: 2, total: 2 })
- expect(sampleAcrossTopLevel(['/vendor/a.ts', '/src/b.ts'], 2, '/'))
- .toEqual({ items: ['/vendor/a.ts', '/src/b.ts'], shown: 2, total: 2 })
+ expect(sampleAcrossTopLevel(['./vendor/a.ts', './src/b.ts'].map(w), 2, '.'))
+ .toEqual({ items: ['./vendor/a.ts', './src/b.ts'].map(w), shown: 2, total: 2 })
+ expect(sampleAcrossTopLevel(['/vendor/a.ts', '/src/b.ts'].map(w), 2, w('/')))
+ .toEqual({ items: ['/vendor/a.ts', '/src/b.ts'].map(w), shown: 2, total: 2 })
const rooted = [
['root', 'a', 'one'].join(sep),
['root', 'a', 'two'].join(sep),
@@ -591,8 +692,8 @@ describe('cross-directory sampling', () => {
]
expect(sampleAcrossTopLevel(rooted, 2, 'root'))
.toEqual({ items: [rooted[0], rooted[2]], shown: 2, total: 2 })
- expect(sampleAcrossTopLevel(['other/a.ts'], 1, 'src'))
- .toEqual({ items: ['other/a.ts'], shown: 1, total: 1 })
+ expect(sampleAcrossTopLevel(['other/a.ts'].map(w), 1, 'src'))
+ .toEqual({ items: ['other/a.ts'].map(w), shown: 1, total: 1 })
expect(sampleAcrossTopLevel(['src'], 1, 'src'))
.toEqual({ items: ['src'], shown: 1, total: 1 })
})
@@ -614,8 +715,8 @@ describe('cross-directory sampling', () => {
describe('glob results', () => {
it('lists workdir-relative paths (absolute output under the workdir is relativized)', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('/sessions/s1/src/a.ts\n/elsewhere/b.ts\nrel/c.ts\n')
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('/sessions/s1/src/a.ts\n/elsewhere/b.ts\nrel/c.ts\n')
const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/sessions/s1') })
if (result.isError) throw new Error('expected glob success')
expect(result.value).toEqual({ root: '.', paths: [join('src', 'a.ts'), '/elsewhere/b.ts', 'rel/c.ts'] })
@@ -628,23 +729,30 @@ describe('glob results', () => {
expect(text(await call(ctx, 'glob', { pattern: '*', path: ' ' }))).toContain('path must be a non-empty string')
})
- it('threads a valid path through to the command as the quoted search root', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('sub/a.ts\n')
+ it('threads a valid path through to the spawn as the plain search root element', async () => {
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('sub/a.ts\n')
const result = await call(ctx, 'glob', { pattern: '*.ts', path: 'sub' })
expect(result.isError).toBe(false)
- expect(bash.specs[0]?.command).toContain("-- 'sub'")
+ expect(subprocess.spawns[0]?.argv).toEqual([rgPath, '--no-config', '--files', '--glob=*.ts', '--sort=modified', '--no-ignore', '--hidden',
+ '--glob=!**/.git', '--glob=!**/.git/**',
+ '--glob=!**/.svn', '--glob=!**/.svn/**',
+ '--glob=!**/.hg', '--glob=!**/.hg/**',
+ '--glob=!**/.bzr', '--glob=!**/.bzr/**',
+ '--glob=!**/.jj', '--glob=!**/.jj/**',
+ '--glob=!**/.sl', '--glob=!**/.sl/**',
+ '--', 'sub'])
})
it('caps at globMaxResults and saves the FULL sorted list through spillStore', async () => {
- const { ctx, bash, spill } = await setup({ config: { globMaxResults: 2 }, spill: true })
+ const { ctx, subprocess, spill } = await setup({ config: { globMaxResults: 2 }, spill: true })
ctx.on('tools/post-execute', async () => ({
kind: 'accept',
additionalContexts: [createUserMessage({
content: [{ type: 'text', text: 'glob context' }], source: { kind: 'plugin', plugin: 'test' },
})],
}))
- bash.handler = () => runResult('a.ts\nb.ts\nc.ts\nd.ts\n')
+ subprocess.handler = () => runResult('a.ts\nb.ts\nc.ts\nd.ts\n')
const result = await call(ctx, 'glob', { pattern: '*.ts' }, { agent: agent('/w') })
expect(result.isError).toBe(false)
if (result.isError) throw new Error('expected glob success')
@@ -665,90 +773,90 @@ describe('glob results', () => {
// The shipped failure: `*` matches the whole tree, mtime order puts one
// freshly-unpacked subtree first, and a head-of-3 reads like the entire
// workspace. The sample reaches every top-level entry instead.
- const { ctx, bash } = await setup({ config: { globMaxResults: 3 } })
- bash.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts', 'guide/e.md', 'top.txt'].join('\n'))
+ const { ctx, subprocess } = await setup({ config: { globMaxResults: 3 } })
+ subprocess.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts', 'guide/e.md', 'top.txt'].map(w).join('\n'))
const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') })
- expect(text(result)).toBe('vendor/a.ts\nsrc/d.ts\nguide/e.md\n\n'
+ expect(text(result)).toBe(['vendor/a.ts', 'src/d.ts', 'guide/e.md'].map(w).join('\n') + '\n\n'
+ '(Showing 3 of 6 paths, sampled across 3 of the 4 top-level entries this pattern matched '
+ 'instead of taken in modification-time order. Narrow path to inspect a specific subtree. '
+ 'The complete result could not be saved; narrow pattern or path to see more.)')
})
it('keeps the modification-time head when over-cap sampling is disabled', async () => {
- const { ctx, bash } = await setup({
+ const { ctx, subprocess } = await setup({
config: { globMaxResults: 3, sampleOverCapGlobResults: false },
})
- bash.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts', 'guide/e.md'].join('\n'))
+ subprocess.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts', 'guide/e.md'].join('\n'))
expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') })))
.toBe('vendor/a.ts\nvendor/b.ts\nvendor/c.ts\n\n'
+ '(Showing 3 of 5 paths. The complete result could not be saved; narrow pattern or path to see more.)')
})
it('samples relative to the explicit search root instead of its workdir prefix', async () => {
- const { ctx, bash } = await setup({ config: { globMaxResults: 3 } })
- bash.handler = () => runResult([
+ const { ctx, subprocess } = await setup({ config: { globMaxResults: 3 } })
+ subprocess.handler = () => runResult([
'workspace/vendor/a.ts',
'workspace/vendor/b.ts',
'workspace/source/c.ts',
'workspace/guides/d.md',
- ].join('\n'))
- const result = await call(ctx, 'glob', { pattern: '*', path: 'workspace' }, { agent: agent('/w') })
- expect(text(result)).toContain('workspace/vendor/a.ts\nworkspace/source/c.ts\nworkspace/guides/d.md')
+ ].map(w).join('\n'))
+ const result = await call(ctx, 'glob', { pattern: '*', path: w('workspace') }, { agent: agent('/w') })
+ expect(text(result)).toContain(['workspace/vendor/a.ts', 'workspace/source/c.ts', 'workspace/guides/d.md'].map(w).join('\n'))
expect(text(result)).toContain('sampled across 3 of the 3 top-level entries')
})
it('samples relative to an absolute search root after workdir display conversion', async () => {
- const { ctx, bash } = await setup({ config: { globMaxResults: 3 } })
- bash.handler = () => runResult([
+ const { ctx, subprocess } = await setup({ config: { globMaxResults: 3 } })
+ subprocess.handler = () => runResult([
'/w/workspace/vendor/a.ts',
'/w/workspace/vendor/b.ts',
'/w/workspace/source/c.ts',
'/w/workspace/guides/d.md',
- ].join('\n'))
- const result = await call(ctx, 'glob', { pattern: '*', path: '/w/workspace' }, { agent: agent('/w') })
- expect(text(result)).toContain('workspace/vendor/a.ts\nworkspace/source/c.ts\nworkspace/guides/d.md')
+ ].map(w).join('\n'))
+ const result = await call(ctx, 'glob', { pattern: '*', path: w('/w/workspace') }, { agent: agent(w('/w')) })
+ expect(text(result)).toContain(['workspace/vendor/a.ts', 'workspace/source/c.ts', 'workspace/guides/d.md'].map(w).join('\n'))
expect(text(result)).toContain('sampled across 3 of the 3 top-level entries')
})
it('drops the narrowing hint when the sample reaches every top-level entry', async () => {
- const { ctx, bash } = await setup({ config: { globMaxResults: 3 } })
- bash.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts'].join('\n'))
+ const { ctx, subprocess } = await setup({ config: { globMaxResults: 3 } })
+ subprocess.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts'].map(w).join('\n'))
expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') })))
- .toBe('vendor/a.ts\nvendor/b.ts\nsrc/d.ts\n\n'
+ .toBe(['vendor/a.ts', 'vendor/b.ts', 'src/d.ts'].map(w).join('\n') + '\n\n'
+ '(Showing 3 of 4 paths, sampled across 2 of the 2 top-level entries this pattern matched '
+ 'instead of taken in modification-time order. '
+ 'The complete result could not be saved; narrow pattern or path to see more.)')
})
it('keeps modification-time order untouched when the whole result fits', async () => {
- const { ctx, bash } = await setup({ config: { globMaxResults: 4 } })
- bash.handler = () => runResult('vendor/a.ts\nvendor/b.ts\nsrc/c.ts\n')
+ const { ctx, subprocess } = await setup({ config: { globMaxResults: 4 } })
+ subprocess.handler = () => runResult('vendor/a.ts\nvendor/b.ts\nsrc/c.ts\n')
expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') })))
.toBe('vendor/a.ts\nvendor/b.ts\nsrc/c.ts')
})
it('keeps the plain footer for a flat result, where the sample is the modification-time head', async () => {
- const { ctx, bash } = await setup({ config: { globMaxResults: 2 } })
- bash.handler = () => runResult('a.ts\nb.ts\nc.ts\n')
+ const { ctx, subprocess } = await setup({ config: { globMaxResults: 2 } })
+ subprocess.handler = () => runResult('a.ts\nb.ts\nc.ts\n')
expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') })))
.toBe('a.ts\nb.ts\n\n(Showing 2 of 3 paths. The complete result could not be saved; narrow pattern or path to see more.)')
})
it('does not create a spill file when the result fits inline', async () => {
- const { ctx, bash, spill } = await setup({ spill: true })
- bash.handler = () => runResult('a.ts\nb.ts\n')
+ const { ctx, subprocess, spill } = await setup({ spill: true })
+ subprocess.handler = () => runResult('a.ts\nb.ts\n')
const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') })
expect(text(result)).toBe('a.ts\nb.ts')
expect(spill?.saves).toHaveLength(0)
})
it('preserves a downstream canonical value replacement instead of spilling the old value', async () => {
- const { ctx, bash, spill } = await setup({ config: { globMaxResults: 1 }, spill: true })
+ const { ctx, subprocess, spill } = await setup({ config: { globMaxResults: 1 }, spill: true })
ctx.on('tools/post-execute', async () => ({
kind: 'accept' as const,
value: { root: '.', paths: ['replacement-a.ts', 'replacement-b.ts'] },
}))
- bash.handler = () => runResult('old-a.ts\nold-b.ts\n')
+ subprocess.handler = () => runResult('old-a.ts\nold-b.ts\n')
const result = await call(ctx, 'glob', { pattern: '*.ts' }, { agent: agent('/w') })
@@ -760,8 +868,8 @@ describe('glob results', () => {
})
it('keeps the full nested Code value without creating a surface spill', async () => {
- const { ctx, bash, spill } = await setup({ config: { globMaxResults: 2 }, spill: true })
- bash.handler = () => runResult('a.ts\nb.ts\nc.ts\nd.ts\n')
+ const { ctx, subprocess, spill } = await setup({ config: { globMaxResults: 2 }, spill: true })
+ subprocess.handler = () => runResult('a.ts\nb.ts\nc.ts\nd.ts\n')
const result = await call(ctx, 'glob', { pattern: '*.ts' }, {
agent: agent('/w'),
parent: Symbol('run_code') as ToolExecutionToken,
@@ -777,9 +885,9 @@ describe('glob results', () => {
['saveText fails', { fail: true, spill: true, ownerless: false }],
['no session owner', { fail: false, spill: true, ownerless: true }],
])('keeps the inline page and reports the unsaved remainder when %s', async (_label, mode) => {
- const { ctx, bash, spill } = await setup({ config: { globMaxResults: 1 }, spill: mode.spill })
+ const { ctx, subprocess, spill } = await setup({ config: { globMaxResults: 1 }, spill: mode.spill })
if (mode.fail && spill) spill.failWith = new Error('disk full')
- bash.handler = () => runResult('a.ts\nb.ts\n')
+ subprocess.handler = () => runResult('a.ts\nb.ts\n')
const result = await call(ctx, 'glob', { pattern: '*' }, mode.ownerless ? {} : { agent: agent('/w') })
expect(result.isError).toBe(false) // spill unavailability never fails the search
expect(text(result)).toBe('a.ts\n\n(Showing 1 of 2 paths. The complete result could not be saved; narrow pattern or path to see more.)')
@@ -788,8 +896,8 @@ describe('glob results', () => {
describe('grep results', () => {
it('groups matches by file with line numbers', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult([
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult([
JSON.stringify({ type: 'begin', data: { path: { text: 'a.ts' } } }),
matchLine('a.ts', 3, 'const x = 1\n'),
matchLine('a.ts', 9, 'const y = 2\n'),
@@ -812,23 +920,23 @@ describe('grep results', () => {
})
it('reports a single match in the singular', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult(`${matchLine('a.ts', 1, 'hit')}\n`)
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult(`${matchLine('a.ts', 1, 'hit')}\n`)
expect(text(await call(ctx, 'grep', { pattern: 'hit' }))).toBe('Found 1 match\n\na.ts\nLine 1: hit')
})
it('relativizes absolute match paths against the resolved workdir', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult(`${matchLine('/sessions/s1/deep/a.ts', 2, 'hit')}\n`)
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult(`${matchLine('/sessions/s1/deep/a.ts', 2, 'hit')}\n`)
const result = await call(ctx, 'grep', { pattern: 'hit', path: '/sessions/s1' }, { agent: agent('/sessions/s1') })
expect(text(result)).toContain(`${join('deep', 'a.ts')}\nLine 2: hit`)
})
it('previews a long matched line at grepMaxLineBytes preserving UTF-8', async () => {
- const { ctx, bash } = await setup({ config: { grepMaxLineBytes: 7 } })
+ const { ctx, subprocess } = await setup({ config: { grepMaxLineBytes: 7 } })
// 'héllo wörld' cut at 7 bytes lands mid-'é'? h(1)é(2)l(1)l(1)o(1)=6, space=7 → clean cut at 7.
// Use a multibyte straddle instead: 'aé' repeated — cut at 7 bytes: a(1)é(2)a(1)é(2)=6 +a(1)=7 → next é straddles: trimmed.
- bash.handler = () => runResult(`${matchLine('a.txt', 1, 'aéaéaéaé')}\n`)
+ subprocess.handler = () => runResult(`${matchLine('a.txt', 1, 'aéaéaéaé')}\n`)
const result = await call(ctx, 'grep', { pattern: 'a' })
if (result.isError) throw new Error('expected grep success')
expect(result.value).toEqual({ matches: [{ path: 'a.txt', lineNumber: 1, line: 'aéaéaéaé' }] })
@@ -836,9 +944,9 @@ describe('grep results', () => {
})
it('renders a non-UTF-8 line (rg bytes form) as a placeholder instead of failing', async () => {
- const { ctx, bash } = await setup()
+ const { ctx, subprocess } = await setup()
const record = JSON.stringify({ type: 'match', data: { path: { text: 'bin.dat' }, lines: { bytes: 'AAECww==' }, line_number: 4 } })
- bash.handler = () => runResult(`${record}\n`)
+ subprocess.handler = () => runResult(`${record}\n`)
expect(text(await call(ctx, 'grep', { pattern: 'x' }))).toContain('Line 4: (line is not valid UTF-8)')
})
@@ -848,14 +956,14 @@ describe('grep results', () => {
})
it('caps at grepMaxMatches and spills the full formatted match list', async () => {
- const { ctx, bash, spill } = await setup({ config: { grepMaxMatches: 2 }, spill: true })
+ const { ctx, subprocess, spill } = await setup({ config: { grepMaxMatches: 2 }, spill: true })
ctx.on('tools/post-execute', async () => ({
kind: 'accept',
additionalContexts: [createUserMessage({
content: [{ type: 'text', text: 'grep context' }], source: { kind: 'plugin', plugin: 'test' },
})],
}))
- bash.handler = () => runResult([
+ subprocess.handler = () => runResult([
matchLine('a.ts', 1, 'one'),
matchLine('a.ts', 2, 'two'),
matchLine('b.ts', 3, 'three'),
@@ -880,7 +988,7 @@ describe('grep results', () => {
})
it('preserves a downstream canonical value replacement instead of spilling the old matches', async () => {
- const { ctx, bash, spill } = await setup({ config: { grepMaxMatches: 1 }, spill: true })
+ const { ctx, subprocess, spill } = await setup({ config: { grepMaxMatches: 1 }, spill: true })
ctx.on('tools/post-execute', async () => ({
kind: 'accept' as const,
value: {
@@ -890,7 +998,7 @@ describe('grep results', () => {
],
},
}))
- bash.handler = () => runResult(`${matchLine('old.ts', 1, 'old')}\n`)
+ subprocess.handler = () => runResult(`${matchLine('old.ts', 1, 'old')}\n`)
const result = await call(ctx, 'grep', { pattern: 'old' }, { agent: agent('/w') })
@@ -907,8 +1015,8 @@ describe('grep results', () => {
})
it('keeps every nested Code match in the value without creating a surface spill', async () => {
- const { ctx, bash, spill } = await setup({ config: { grepMaxMatches: 1 }, spill: true })
- bash.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n${matchLine('b.ts', 2, 'two')}\n`)
+ const { ctx, subprocess, spill } = await setup({ config: { grepMaxMatches: 1 }, spill: true })
+ subprocess.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n${matchLine('b.ts', 2, 'two')}\n`)
const result = await call(ctx, 'grep', { pattern: 'o' }, {
agent: agent('/w'),
parent: Symbol('run_code') as ToolExecutionToken,
@@ -925,8 +1033,8 @@ describe('grep results', () => {
})
it('reports the unsaved remainder when capped with no spill backend', async () => {
- const { ctx, bash } = await setup({ config: { grepMaxMatches: 1 } })
- bash.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n${matchLine('a.ts', 2, 'two')}\n`)
+ const { ctx, subprocess } = await setup({ config: { grepMaxMatches: 1 } })
+ subprocess.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n${matchLine('a.ts', 2, 'two')}\n`)
const result = await call(ctx, 'grep', { pattern: 'o' }, { agent: agent('/w') })
expect(result.isError).toBe(false)
expect(text(result)).toBe('Found 1 of 2 matches\n\na.ts\nLine 1: one\n\n(The complete result could not be saved; narrow pattern, path, or include to see more.)')
@@ -942,8 +1050,8 @@ describe('grep results', () => {
})
it('accepts a whitespace-only pattern (a legitimate regex) and brace alternation in include', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('', { exitCode: 1 })
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('', { exitCode: 1 })
const result = await call(ctx, 'grep', { pattern: ' ', include: '*.{ts,tsx}' })
expect(result.isError).toBe(false)
})
@@ -960,8 +1068,8 @@ describe('rg --json transport failures (SEARCH_FAILED)', () => {
['a match record with no line content', JSON.stringify({ type: 'match', data: { path: { text: 'a.ts' }, line_number: 1 } })],
['a match record with neither text nor bytes', JSON.stringify({ type: 'match', data: { path: { text: 'a.ts' }, lines: {}, line_number: 1 } })],
])('%s fails the search', async (_label, line) => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult(`${line}\n`)
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult(`${line}\n`)
const result = await call(ctx, 'grep', { pattern: 'x' })
expect(result.isError).toBe(true)
expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_FAILED' } })
@@ -969,13 +1077,16 @@ describe('rg --json transport failures (SEARCH_FAILED)', () => {
})
describe('the no-background-task invariant', () => {
- it('never calls ctx.bash.start() across successful and failed searches', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult('a.ts\n')
+ it('settles every spawned search handle across successful and failed searches', async () => {
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult('a.ts\n')
await call(ctx, 'glob', { pattern: '*' })
- bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'boom', truncated: false } })
+ subprocess.handler = () => runResult('', { exitCode: 2, stderr: { text: 'boom' } })
await call(ctx, 'grep', { pattern: 'x' })
- expect(bash.startCalls).toBe(0)
+ // One foreground spawn per call, each awaited to settlement before the
+ // tool returns — the searches never leave a background handle running.
+ expect(subprocess.spawns).toHaveLength(2)
+ expect(subprocess.handles.every(handle => handle.settled)).toBe(true)
})
})
@@ -991,8 +1102,8 @@ describe('presentation', () => {
})
it('grep projects a search card from a real execute, grouped by file with total and truncation', async () => {
- const { ctx, bash } = await setup({ config: { grepMaxMatches: 2 } })
- bash.handler = () => runResult([
+ const { ctx, subprocess } = await setup({ config: { grepMaxMatches: 2 } })
+ subprocess.handler = () => runResult([
matchLine('a.ts', 1, 'one'),
matchLine('a.ts', 2, 'two'),
matchLine('b.ts', 3, 'three'),
@@ -1018,8 +1129,8 @@ describe('presentation', () => {
})
it('glob projects a search card from a real execute, a flat path list with total and truncation', async () => {
- const { ctx, bash } = await setup({ config: { globMaxResults: 2 } })
- bash.handler = () => runResult('a.ts\nb.ts\nc.ts\n')
+ const { ctx, subprocess } = await setup({ config: { globMaxResults: 2 } })
+ subprocess.handler = () => runResult('a.ts\nb.ts\nc.ts\n')
const result = await call(ctx, 'glob', { pattern: '*.ts' }, { agent: agent('/w') })
if (result.isError) throw new Error('expected glob success')
expect(result.meta).toEqual({ shape: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3 })
@@ -1028,8 +1139,8 @@ describe('presentation', () => {
})
it('nested Code dispatch computes no meta, so presentResult falls back to the generic card', async () => {
- const { ctx, bash } = await setup()
- bash.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n`)
+ const { ctx, subprocess } = await setup()
+ subprocess.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n`)
const result = await call(ctx, 'grep', { pattern: 'o' }, {
agent: agent('/w'),
parent: Symbol('run_code') as ToolExecutionToken,
diff --git a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
index 1800b1c3fd..dae1bef59b 100644
--- a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
+++ b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
@@ -244,8 +244,10 @@ describe('tool-str-replace-editor', () => {
expect(listing).not.toContain('too-deep.txt')
expect(listing).not.toContain('index.js')
expect(listing).not.toContain('module.pyc')
- expect(listing).toContain('node_modules_old/kept.js')
- expect(listing).toContain('__pycache__backup/kept.py')
+ // The listing carries absolute display paths; the POSIX-style substrings
+ // only match on Linux, so assert with platform separators.
+ expect(listing).toContain(join('node_modules_old', 'kept.js'))
+ expect(listing).toContain(join('__pycache__backup', 'kept.py'))
const clipped = await setup({ maxOutputChars: 10 })
await writeFile(join(clipped.root, 'large.txt'), 'x'.repeat(100))
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index 4ef8e30ebf..4967010902 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -22,7 +22,7 @@ import {
encodeSegment, eventLines, logPath, logSuffix, parseHeaderMeta, projectDir, scanLog, sessionDir, toHeaderLine,
type JsonlCompression,
} from './format.ts'
-import { compressZstdFrame, decompressZstdFrame, scanZstdFrames } from './zstd.ts'
+import { compressZstdFrame, decompressZstdFrame, decompressZstdPrefix, scanZstdFrames } from './zstd.ts'
import { ensureDurableDirectoryWin32, publishNewFileWin32 } from './win32.ts'
export type { JsonlCompression } from './format.ts'
@@ -232,7 +232,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
let recoveredPlaintext: Buffer = Buffer.alloc(0)
try {
signal?.throwIfAborted()
- recoveredPlaintext = await decompressZstdFrame(buffer.subarray(tornStart))
+ recoveredPlaintext = await decompressZstdPrefix(buffer.subarray(tornStart))
} catch {
/* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent */
if (signal?.aborted) signal.throwIfAborted()
diff --git a/packages/session-persistence/session-persistence-jsonl/src/zstd.ts b/packages/session-persistence/session-persistence-jsonl/src/zstd.ts
index bba2ef6344..e29747e399 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/zstd.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/zstd.ts
@@ -14,6 +14,9 @@ const zstdDecompressAsync = promisify(zstdDecompress)
const CHECKSUM_OPTIONS: ZstdOptions = {
params: { [constants.ZSTD_c_checksumFlag]: 1 },
}
+const INCOMPLETE_FRAME_OPTIONS: ZstdOptions = {
+ finishFlush: constants.ZSTD_e_flush,
+}
/** Byte range occupied by one structurally complete Zstandard frame. */
export interface ZstdFrameRange {
@@ -106,11 +109,21 @@ export async function compressZstdFrame(input: Buffer | string): Promise
}
/**
- * Decompress one complete frame or the available prefix of a torn final frame.
- * Complete-frame checksums are validated by Node's decoder.
- * @param input - bytes beginning at a Zstandard frame boundary.
- * @returns plaintext produced from the available input.
+ * Decompress one complete frame and validate its checksum.
+ * @param input - one structurally complete Zstandard frame.
+ * @returns the frame plaintext.
*/
export async function decompressZstdFrame(input: Buffer): Promise {
return zstdDecompressAsync(input)
}
+
+/**
+ * Recover available plaintext from a structurally incomplete final frame.
+ * `ZSTD_e_flush` deliberately suppresses final-frame and checksum completion;
+ * callers must establish the torn frame boundary before using this helper.
+ * @param input - available bytes from a known incomplete Zstandard frame.
+ * @returns plaintext produced from the available input.
+ */
+export async function decompressZstdPrefix(input: Buffer): Promise {
+ return zstdDecompressAsync(input, INCOMPLETE_FRAME_OPTIONS)
+}
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts
index bd552e738e..697b95d58a 100644
--- a/packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest'
-import { compressZstdFrame, decompressZstdFrame, scanZstdFrames } from '../src/zstd.ts'
+import { compressZstdFrame, decompressZstdFrame, decompressZstdPrefix, scanZstdFrames } from '../src/zstd.ts'
describe('JSONL Zstandard compatibility', () => {
it('round-trips concatenated checksummed frames through the built-in Node API', async () => {
@@ -19,6 +19,6 @@ describe('JSONL Zstandard compatibility', () => {
const eventFrame = encoded.subarray(frames[1]!.start, frames[1]!.end)
const missingChecksumByte = eventFrame.subarray(0, -1)
expect(scanZstdFrames(missingChecksumByte)).toEqual({ frames: [], tornStart: 0 })
- expect((await decompressZstdFrame(missingChecksumByte)).toString()).toContain('"type":"turn/start"')
+ expect((await decompressZstdPrefix(missingChecksumByte)).toString()).toContain('"type":"turn/start"')
})
})
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
index cef1ff71e5..0baf0ca734 100644
--- a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
@@ -8,7 +8,7 @@ import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
import type { SessionEvent } from '@deepseek-ai/dsh-session'
import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
import { logPath, scanLog, sessionDir, toHeaderLine, type JsonlCompression } from '../src/format.ts'
-import { compressZstdFrame, decompressZstdFrame, scanZstdFrames } from '../src/zstd.ts'
+import { compressZstdFrame, decompressZstdFrame, decompressZstdPrefix, scanZstdFrames } from '../src/zstd.ts'
import { runPersistenceContract, meta, oneTurnLog } from '../../session-persistence/tests/contract.ts'
import { runCoordinatorContract, type CoordinatorFixture } from '../../session-persistence/tests/coordinator-contract.ts'
@@ -69,7 +69,7 @@ async function tornFrame(
const candidate = frame.subarray(0, end)
if (scanZstdFrames(candidate).tornStart !== 0) continue
try {
- const decoded = (await decompressZstdFrame(candidate)).toString('utf8')
+ const decoded = (await decompressZstdPrefix(candidate)).toString('utf8')
if (accepts(decoded)) return candidate
} catch {
// Some early cuts precede the first decodable block; keep searching for
diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts
index 950cf4097b..6771e788b8 100644
--- a/packages/support/acp-snapshot/src/harness.ts
+++ b/packages/support/acp-snapshot/src/harness.ts
@@ -43,16 +43,22 @@ const WAIT_POLL_INTERVAL_MS = 10
* reference, since a committed file cannot know the id in advance.
*
* `promptAndCancel` starts a prompt without awaiting completion, waits for a
- * readiness condition, then cancels and awaits completion. `waitForFile`
- * observes a cwd-relative marker; the default observes the durable turn start.
+ * readiness condition, then cancels and awaits completion. Its optional
+ * `waitForFile` observes a cwd-relative marker; otherwise it waits for the
+ * durable turn start. The standalone `waitForFile` holds the next script step
+ * behind the same marker.
* `promptAndWaitForAgentMessage` arms an exact text-chunk waiter before sending
* the prompt, then keeps the application live until that later update arrives.
* `waitForTurnStart` waits for an open durable turn, optionally at or beyond a
* specified turn number. `waitForTurnEnd` holds the subprocess open until the
* selected session's latest complete raw-JSONL turn boundary is `turn/end`.
+ * `waitForSubagentTurnEnd` waits until one background child has persisted a
+ * closed model-work turn after its own descriptor; child progress has no ACP
+ * update to wait on.
* `waitForTitleAfterTurnEnd` additionally waits for a later durable title.
- * `waitForSubagentTurnEnd` applies the same work-turn boundary to one
- * background child, whose progress has no ACP update to wait on.
+ * `waitForEventAfterTurnEnd` waits until a complete record of the given event
+ * type follows the latest closed turn — for scenarios whose asserted state
+ * (e.g. a goal pause) is appended only after cancellation reaches idle.
* A standalone `cancel` may also wait for a cwd-relative readiness marker.
* All wait timeouts default to 10s.
*/
@@ -73,6 +79,7 @@ export type InputStep =
| { op: 'waitForTurnEnd'; timeoutMs?: number }
| { op: 'waitForSubagentTurnEnd'; child?: number; timeoutMs?: number }
| { op: 'waitForTitleAfterTurnEnd'; timeoutMs?: number }
+ | { op: 'waitForEventAfterTurnEnd'; type: string; timeoutMs?: number }
| { op: 'cancel'; waitForFile?: { path: string; timeoutMs?: number } }
/** A scenario's `input.json`: an ordered list of input steps. */
@@ -296,6 +303,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
(id, timeoutMs) => waitForPersistedTurnEnd(sessionsRoot, id, timeoutMs),
(child, timeoutMs) => waitForPersistedChildTurnEnd(sessionsRoot, child, timeoutMs),
(id, timeoutMs) => waitForPersistedTitleAfterTurnEnd(sessionsRoot, id, timeoutMs),
+ (id, type, timeoutMs) => waitForPersistedEventAfterTurnEnd(sessionsRoot, id, type, timeoutMs),
)
// A permission exchange happens while a step's request is in flight, so
// by the time the step settles any script bug it exposed is captured —
@@ -371,6 +379,7 @@ async function runStep(
waitForTurnEnd: (sessionId: string, timeoutMs?: number) => Promise,
waitForChildTurnEnd: (child: number, timeoutMs?: number) => Promise,
waitForTitleAfterTurnEnd: (sessionId: string, timeoutMs?: number) => Promise,
+ waitForEventAfterTurnEnd: (sessionId: string, type: string, timeoutMs?: number) => Promise,
): Promise {
switch (step.op) {
case 'initialize':
@@ -460,6 +469,12 @@ async function runStep(
await waitForTitleAfterTurnEnd(sessionId, step.timeoutMs)
return
}
+ case 'waitForEventAfterTurnEnd': {
+ const sessionId = getSessionId()
+ if (sessionId === undefined) throw new Error('snapshot-harness: waitForEventAfterTurnEnd before newSession')
+ await waitForEventAfterTurnEnd(sessionId, step.type, step.timeoutMs)
+ return
+ }
case 'waitForTurnStart': {
const sessionId = getSessionId()
if (sessionId === undefined) throw new Error('snapshot-harness: waitForTurnStart before newSession')
@@ -576,6 +591,21 @@ async function waitForPersistedTitleAfterTurnEnd(
}, { interval: WAIT_POLL_INTERVAL_MS, timeout: timeoutMs })
}
+/** Wait until a complete record of `type` follows the latest closed turn. */
+async function waitForPersistedEventAfterTurnEnd(
+ root: string,
+ sessionId: string,
+ type: string,
+ timeoutMs = DEFAULT_WAIT_TIMEOUT_MS,
+): Promise {
+ await vi.waitFor(async () => {
+ const log = (await harvestSessionLogs(root)).find(candidate => candidate.id === sessionId)
+ if (log === undefined || !latestEventFollowsTurnEnd(log.content, type)) {
+ throw new Error(`snapshot-harness: session "${sessionId}" did not persist ${type} after turn/end within ${timeoutMs}ms`)
+ }
+ }, { interval: WAIT_POLL_INTERVAL_MS, timeout: timeoutMs })
+}
+
/** Wait for a cwd-relative marker proving an external action reached readiness. */
async function waitForWorkspaceFile(
cwd: string,
@@ -604,6 +634,13 @@ function latestTitleFollowsTurnEnd(content: string): boolean {
return turnEnd >= 0 && complete.lastIndexOf('\n{"type":"session/title",') > turnEnd
}
+/** Return whether a complete record of `type` occurs after the last complete turn end. */
+function latestEventFollowsTurnEnd(content: string, type: string): boolean {
+ const complete = content.slice(0, content.lastIndexOf('\n') + 1)
+ const turnEnd = complete.lastIndexOf('\n{"type":"turn/end",')
+ return turnEnd >= 0 && complete.lastIndexOf(`\n{"type":"${type}",`) > turnEnd
+}
+
/** Return the latest open turn number, validating the persisted boundary record. */
function latestOpenTurn(content: string): number | undefined {
const complete = content.slice(0, content.lastIndexOf('\n') + 1)
diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts
index 629392acad..58c6afd019 100644
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -844,6 +844,55 @@ describe('runScenario', () => {
)).rejects.toThrow(/did not persist session\/title after turn\/end within 20ms/)
})
+ it('waitForEventAfterTurnEnd holds the app for a typed post-boundary record and times out otherwise', { timeout: 20_000 }, async () => {
+ const late = await scenario({
+ prompt: 'hang-until-cancel',
+ persistLogsOnCancel: true,
+ logs: [{
+ file: 'project/main/session.jsonl',
+ lines: [
+ { type: 'session', version: 0, id: '{{SID}}', createdAt: 1, delegationDepth: 0 },
+ { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'aborted' } } },
+ { type: 'user/message', seq: 2, time: 3, data: { content: [{ type: 'text', text: 'late goal state' }], source: { kind: 'user' } } },
+ ],
+ }],
+ })
+ const result = await runScenario(
+ {
+ steps: [
+ ...boot,
+ { op: 'promptAndCancel', text: 'hang' },
+ { op: 'waitForEventAfterTurnEnd', type: 'user/message' },
+ ],
+ },
+ { agent: AGENT, mode: 'replay', fixtureFile: late.fixtureFile },
+ )
+ expect(result.sessionLogs[0]?.content).toMatch(/"turn\/end"[\s\S]*"user\/message"/)
+
+ const early = await scenario({
+ prompt: 'hang-until-cancel',
+ persistLogsOnCancel: true,
+ logs: [{
+ file: 'project/main/session.jsonl',
+ lines: [
+ { type: 'session', version: 0, id: '{{SID}}', createdAt: 1, delegationDepth: 0 },
+ { type: 'user/message', seq: 1, time: 1, data: { content: [{ type: 'text', text: 'early' }], source: { kind: 'user' } } },
+ { type: 'turn/end', seq: 2, time: 2, data: { turn: 1, reason: { kind: 'aborted' } } },
+ ],
+ }],
+ })
+ await expect(runScenario(
+ {
+ steps: [
+ ...boot,
+ { op: 'promptAndCancel', text: 'hang' },
+ { op: 'waitForEventAfterTurnEnd', type: 'user/message', timeoutMs: 20 },
+ ],
+ },
+ { agent: AGENT, mode: 'replay', fixtureFile: early.fixtureFile },
+ )).rejects.toThrow(/did not persist user\/message after turn\/end within 20ms/)
+ })
+
it('promptExpectError swallows a model-error response as the expected outcome', { timeout: 20_000 }, async () => {
const { fixtureFile } = await scenario({ prompt: 'error' })
const result = await runScenario(
@@ -963,6 +1012,7 @@ describe('runScenario', () => {
[{ op: 'waitForTurnStart' }, /waitForTurnStart before newSession/],
[{ op: 'waitForTurnEnd' }, /waitForTurnEnd before newSession/],
[{ op: 'waitForTitleAfterTurnEnd' }, /waitForTitleAfterTurnEnd before newSession/],
+ [{ op: 'waitForEventAfterTurnEnd', type: 'user/message' }, /waitForEventAfterTurnEnd before newSession/],
[{ op: 'cancel' }, /cancel before newSession/],
] as [InputStep, RegExp][])('rejects %j before newSession', { timeout: 20_000 }, async (step, message) => {
const { fixtureFile } = await scenario({})
diff --git a/packages/ui/tui/README.i18n.yaml b/packages/ui/tui/README.i18n.yaml
index de0cf52845..39aabe4da4 100644
--- a/packages/ui/tui/README.i18n.yaml
+++ b/packages/ui/tui/README.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/ui/tui/README.md
-README.md: 5199e75d732f384497b28518920cc2c775c600c2
-README.zh.md: 02d4431fdab575b5596152c985b72594a948b081
+README.md: 78d56a6cacd040fdd32b73f779bab3fb4c77fcce
+README.zh.md: c403605bb13d252eec00a2b0ebafb5f953c884f8
diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md
index 5199e75d73..78d56a6cac 100644
--- a/packages/ui/tui/README.md
+++ b/packages/ui/tui/README.md
@@ -32,11 +32,11 @@ The footer sums the session's reported usage as `↑ ↓
`/status` adds a point-in-time diagnostics card to the transcript and remains available while the agent runs. It reports the session id, title, working directory, selected provider/model, selected reasoning effort or default behavior, reasoning-block visibility, agent state, event/turn/step/tool-call counts, exact input/output/cache token buckets, KV-cache hit rate, token-meter context use and capacity, creation time, and latest event time. Missing titles, models, cache input, or context capacity are labeled instead of inferred. The card is terminal-only and does not duplicate the compact footer.
-`/resume` opens a full-viewport keyboard selector instead of a centered dialog. Two scopes cover the same candidate set: the current workspace, which it opens on, and all workspaces, which Tab toggles to. The scope line under the search field names the active scope and the count the other holds, and each row in the all-workspaces scope also reports its own workspace. Toggling clears the search and selection so the highlighted row always belongs to the visible list.
+`/resume` opens a full-viewport keyboard selector instead of a centered dialog. The selector opens as soon as the command runs and takes input focus while the session scan is still pending, showing a loading placeholder until the rows arrive; Escape cancels an in-flight scan the same way it cancels the loaded list. Two scopes cover the same candidate set: the current workspace, which it opens on, and all workspaces, which Tab toggles to. The scope line under the search field names the active scope and the count the other holds, and each row in the all-workspaces scope also reports its own workspace. Toggling clears the search and selection so the highlighted row always belongs to the visible list.
-Its focused search field starts immediately after the search glyph and emits pi-tui's cursor marker, so terminal IME composition remains anchored inside the field. Candidates are sorted by last logged activity and searchable by log-backed title or session id, and by workspace label in the all-workspaces scope; each row reports current/live/persisted state, last turn outcome, recent provider/model, and durable goal phase when present. Up/Down and Page Up/Page Down navigate, Enter resumes, Escape clears a non-empty search before a second Escape cancels, and Ctrl+C cancels directly. The current session, a session already live in this runtime, an unreadable log, a session with no recorded workspace to run in, or a session whose logged provider has no current adapter remains visible but disabled; a workspace other than the current one is a scope rather than a disabled reason, because resume enters that directory.
+Its focused search field starts immediately after the search glyph and emits pi-tui's cursor marker, so terminal IME composition remains anchored inside the field. Rows read no whole logs: when the optional projection cache is mounted, titles come from the live projection registry or the durable checkpoint row, with a cold read folding only the log tail since the checkpoint (written back so the next scan is zero-I/O, bounded by `resumeScanConcurrency`); a composition without the cache falls back to one bounded batch title read over the logs. Candidates are sorted by metadata activity — a live session's last in-memory event time, otherwise the persisted artifact's mtime, falling back to creation time — and searchable by title or session id, and by workspace label in the all-workspaces scope; each row reports that timestamp plus current/live/persisted state and the id. Up/Down and Page Up/Page Down navigate, Enter resumes, Escape clears a non-empty search before a second Escape cancels, and Ctrl+C cancels directly. The current session, a session already live in this runtime, an unreadable log, or a session with no recorded workspace to run in remains visible but disabled; a workspace other than the current one is a scope rather than a disabled reason, because resume enters that directory.
-Selection repeats those checks and requires the current agent to be idle before flushing the current session. The TUI then stops the terminal UI and calls the optional host-owned `TuiRuntime.handoffResume` with the selected id and the workspace re-read at preflight: process cwd, not the restored session header, is what filesystem and shell tools resolve against, so the host must enter that directory. Where `process.execve` is available, the shipped `dsh` host chdirs into it before disposing the app and replacing its process, and rejects an unreachable directory while the terminal can still be restored. Resume restores the same `SessionId`, transcript, title, todos, and durable goal; goal activation remains disarmed and the TUI asks for human confirmation or `/goal resume`.
+Selection repeats those checks, fully reads and replay-validates the one chosen log, rejects it when its logged provider has no current adapter, and requires the current agent to be idle before flushing the current session. The TUI then stops the terminal UI and calls the optional host-owned `TuiRuntime.handoffResume` with the selected id and the workspace re-read at preflight: process cwd, not the restored session header, is what filesystem and shell tools resolve against, so the host must enter that directory. Where `process.execve` is available, the shipped `dsh` host chdirs into it before disposing the app and replacing its process, and rejects an unreachable directory while the terminal can still be restored. Resume restores the same `SessionId`, transcript, title, todos, and durable goal; goal activation remains disarmed and the TUI asks for human confirmation or `/goal resume`.
The exit line is launcher-owned, not configurable. A launcher provides `TUI_GOODBYE_MESSAGE_KEY` on the boot context — for the shipped `dsh`, the command that resumes this session — and exiting prints it verbatim after the terminal is released; absent, exiting prints nothing. Only the launcher knows how it was invoked, so only it can name a command that works. The TUI escapes terminal controls before rendering and never executes the text. A launcher that also supplies `MAIN_SESSION_ID_KEY` fixes which session the mounted app binds to, so resume survives any config-level patch.
diff --git a/packages/ui/tui/README.zh.md b/packages/ui/tui/README.zh.md
index 02d4431fda..c403605bb1 100644
--- a/packages/ui/tui/README.zh.md
+++ b/packages/ui/tui/README.zh.md
@@ -32,11 +32,11 @@ Footer 将会话报告的用量汇总为 `↑ ↓`；任
`/status` 会向 transcript 添加一张时间点诊断卡片，并在 agent 运行时保持可用。它报告会话 id、标题、工作目录、所选提供方／模型、所选推理强度或默认行为、reasoning 块可见性、agent 状态、事件／轮次／步骤／工具调用计数、精确输入／输出／缓存 token bucket、KV-cache 命中率、token-meter 上下文用量与容量、创建时间和最新事件时间。缺失标题、模型、缓存输入或上下文容量时会明确标记，而非推断。该卡片只存在于终端，不会重复紧凑 footer。
-`/resume` 会打开全 viewport 键盘选择器，而非居中对话框。两个作用域覆盖同一候选项集合：打开时所处的当前工作区，以及按 Tab 切换到的所有工作区。搜索字段下方的作用域行会给出当前作用域的名称以及另一个作用域包含的数量，且在所有工作区作用域中每行还会报告自身所属的工作区。切换会清除搜索与选择，使高亮行始终属于可见列表。
+`/resume` 会打开全 viewport 键盘选择器，而非居中对话框。选择器在命令执行时立即打开并接管输入焦点，会话扫描仍在进行时显示加载占位符，直到行数据就绪；Escape 取消进行中的扫描，方式与取消已加载列表相同。两个作用域覆盖同一候选项集合：打开时所处的当前工作区，以及按 Tab 切换到的所有工作区。搜索字段下方的作用域行会给出当前作用域的名称以及另一个作用域包含的数量，且在所有工作区作用域中每行还会报告自身所属的工作区。切换会清除搜索与选择，使高亮行始终属于可见列表。
-获得焦点的搜索字段紧跟搜索 glyph 开始，并发出 pi-tui 的 cursor marker，使终端 IME 组合保持锚定在字段内。候选项按最近记录的活动排序，可按日志支持的标题或会话 id 搜索，在所有工作区作用域中还可按工作区标签搜索；每行报告 current/live/persisted 状态、上一轮次结果、近期提供方／模型，以及存在时的持久目标阶段。Up/Down 与 Page Up/Page Down 导航，Enter 恢复，Escape 会先清除非空搜索，再次按下才取消，Ctrl+C 则直接取消。当前会话、已在本运行时中活跃的会话、不可读日志、没有可运行的已记录工作区的会话，或日志所记提供方没有当前适配器的会话仍会显示，但不可选择；不同于当前工作区的工作区属于作用域而非禁用原因，因为恢复会进入该目录。
+获得焦点的搜索字段紧跟搜索 glyph 开始，并发出 pi-tui 的 cursor marker，使终端 IME 组合保持锚定在字段内。行数据不读取任何完整日志：挂载可选的投影缓存时，标题来自实时投影注册表或持久化 checkpoint 行，冷读取只折叠 checkpoint 之后的日志尾部（并写回，使下次扫描零 I/O，受 `resumeScanConcurrency` 约束）；未挂载缓存的组合回退到一次对日志的有界批量标题读取。候选项按元数据活动时间排序——实时会话取内存中最后一个事件的时间，否则取持久化产物的 mtime，再回退到创建时间——可按标题或会话 id 搜索，在所有工作区作用域中还可按工作区标签搜索；每行报告该时间戳、current/live/persisted 状态和 id。Up/Down 与 Page Up/Page Down 导航，Enter 恢复，Escape 会先清除非空搜索，再次按下才取消，Ctrl+C 则直接取消。当前会话、已在本运行时中活跃的会话、不可读日志，或没有可运行的已记录工作区的会话仍会显示，但不可选择；不同于当前工作区的工作区属于作用域而非禁用原因，因为恢复会进入该目录。
-选择时会重复这些检查，并要求当前 agent 空闲，随后 flush 当前会话。TUI 接着停止终端 UI，并以所选 id 和在预检时重新读取的工作区调用由宿主持有的可选 `TuiRuntime.handoffResume`：文件系统与 shell 工具解析所依据的是进程 cwd，而非恢复出的会话头部，因此宿主必须进入该目录。存在 `process.execve` 时，发布的 `dsh` 宿主会先 chdir 进入该目录，再对 app 执行 dispose 并替换自身进程，并在终端仍可恢复时拒绝不可达的目录。恢复操作保留相同的 `SessionId`、transcript、标题、todo 和持久目标；目标激活仍保持解除，TUI 会要求用户确认或执行 `/goal resume`。
+选择时会重复这些检查，完整读取并回放验证所选中的那一份日志，在其日志所记提供方没有当前适配器时拒绝，并要求当前 agent 空闲，随后 flush 当前会话。TUI 接着停止终端 UI，并以所选 id 和在预检时重新读取的工作区调用由宿主持有的可选 `TuiRuntime.handoffResume`：文件系统与 shell 工具解析所依据的是进程 cwd，而非恢复出的会话头部，因此宿主必须进入该目录。存在 `process.execve` 时，发布的 `dsh` 宿主会先 chdir 进入该目录，再对 app 执行 dispose 并替换自身进程，并在终端仍可恢复时拒绝不可达的目录。恢复操作保留相同的 `SessionId`、transcript、标题、todo 和持久目标；目标激活仍保持解除，TUI 会要求用户确认或执行 `/goal resume`。
退出时打印的行由启动器拥有，不可通过配置指定。启动器在启动上下文上提供 `TUI_GOODBYE_MESSAGE_KEY`（对于随附的 `dsh`，即恢复本会话的命令），释放终端后退出会原样打印它；未提供时退出不打印任何内容。只有启动器知道自己是如何被调用的，因此只有它能给出可用的命令。TUI 在渲染前会转义终端控制字符，且绝不执行该文本。若启动器同时提供 `MAIN_SESSION_ID_KEY`，则会固定已挂载应用绑定的会话，因此恢复功能不受配置层修补影响。
diff --git a/packages/ui/tui/package.json b/packages/ui/tui/package.json
index a68fe7968a..135774a846 100644
--- a/packages/ui/tui/package.json
+++ b/packages/ui/tui/package.json
@@ -42,6 +42,8 @@
"@deepseek-ai/dsh-goal": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-session-persistence": "^0.0.1",
+ "@deepseek-ai/dsh-session-projection": "^0.0.1",
+ "@deepseek-ai/dsh-session-projection-cache": "^0.0.1",
"@deepseek-ai/dsh-session-query": "^0.0.1",
"@deepseek-ai/dsh-session-reference": "^0.0.1",
"@deepseek-ai/dsh-session-title": "^0.0.1",
@@ -82,6 +84,8 @@
"@deepseek-ai/dsh-llm-retry": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-session-persistence": "workspace:^",
+ "@deepseek-ai/dsh-session-projection": "workspace:^",
+ "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
"@deepseek-ai/dsh-session-query": "workspace:^",
"@deepseek-ai/dsh-session-reference": "workspace:^",
"@deepseek-ai/dsh-session-title": "workspace:^",
diff --git a/packages/ui/tui/src/chat/resume.ts b/packages/ui/tui/src/chat/resume.ts
index 18f7944fc2..f2173862ae 100644
--- a/packages/ui/tui/src/chat/resume.ts
+++ b/packages/ui/tui/src/chat/resume.ts
@@ -1,16 +1,20 @@
/**
* Session-resume sub-controller for the interactive chat channel: the
- * `/resume` selector, per-candidate summary reads that tolerate a corrupt
+ * `/resume` selector, one metadata-plus-title scan that tolerates a corrupt
* neighbor, the pre-handoff preflight, and the terminal handoff itself.
* @module @deepseek-ai/dsh-tui/chat/resume
*/
+import { stat } from 'node:fs/promises'
import type { TUI } from '@earendil-works/pi-tui'
import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
import { errorChain } from '@deepseek-ai/dsh-llm'
-import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-persistence'
+import type {} from '@deepseek-ai/dsh-session-projection'
+import type { SessionProjectionCache } from '@deepseek-ai/dsh-session-projection-cache'
+import type {} from '@deepseek-ai/dsh-session-title'
import type {
- SessionLogSnapshot,
SessionQueryService,
SessionRecord,
} from '@deepseek-ai/dsh-session-query'
@@ -66,50 +70,137 @@ export function createResumeController(deps: ResumeControllerDeps): ResumeContro
const workspaceLabel = (cwd: string | undefined): string =>
runtime.formatCwd?.(cwd) ?? formatCwd(cwd)
- /** Build one display candidate without letting a corrupt neighbor abort the selector. */
- const readResumeCandidate = async (
+ /** Summarize one record from metadata and its batch-folded title. */
+ const summarize = (
record: SessionRecord,
- providers: ReadonlySet,
- ): Promise => {
+ title: string | undefined,
+ lastActivityAt: number | undefined,
+ ): ResumeCandidate => summarizeResumeCandidate(
+ record,
+ title,
+ lastActivityAt,
+ agent.session.id,
+ agent.session.header.cwd,
+ workspaceLabel,
+ )
+
+ /** The disabled fallback row for a session whose title read failed. */
+ const unreadableCandidate = (
+ record: SessionRecord,
+ lastActivityAt: number | undefined,
+ error: unknown,
+ ): ResumeCandidate => ({
+ record,
+ title: 'Unreadable session',
+ lastActivityAt: lastActivityAt ?? record.header.createdAt,
+ currentWorkspace: record.header.cwd === agent.session.header.cwd,
+ workspaceLabel: workspaceLabel(record.header.cwd),
+ disabledReason: `session cannot be loaded: ${errorChain(error)}`,
+ })
+
+ /**
+ * Metadata-only activity time: a live session's last in-memory event time,
+ * otherwise the persisted artifact's mtime. Never reads a log, so browsing
+ * cost stays independent of log size; any append (including bookkeeping)
+ * moves it.
+ */
+ const lastActivityAt = async (record: SessionRecord): Promise => {
+ const live = ctx.sessions.get(record.header.id)
+ if (live !== undefined) return live.events.at(-1)?.time
+ const location = ctx.get('sessionPersistence')?.locate(record.header)
+ if (location === undefined) return undefined
try {
- let snapshot: SessionLogSnapshot
- const live = ctx.sessions.get(record.header.id)
- if (live !== undefined) {
- snapshot = {
- session: structuredClone(live.header),
- events: live.events.map(event => structuredClone(event)),
- }
- } else {
- const readQuery = sessionQuery()
- /* v8 ignore start -- caller proves the optional service before mapping records */
- if (readQuery === undefined) throw new Error('session query is unavailable')
- /* v8 ignore stop */
- snapshot = await readQuery.readSession(record.header.id)
- }
- return summarizeResumeCandidate(
- record,
- snapshot,
- agent.session.id,
- agent.session.header.cwd,
- providers,
- workspaceLabel,
- )
- } catch (error: unknown) {
- return {
- record,
- title: 'Unreadable session',
- lastActivityAt: record.header.createdAt,
- lastTurn: 'log unavailable',
- currentWorkspace: record.header.cwd === agent.session.header.cwd,
- workspaceLabel: workspaceLabel(record.header.cwd),
- disabledReason: `session cannot be loaded: ${errorChain(error)}`,
- }
+ return (await stat(location.path)).mtimeMs
+ } catch {
+ // Only a just-deleted or never-materialized artifact fails stat; the row falls back to created-at.
+ return undefined
}
}
+ /**
+ * One persisted row's title through the projection-cache ladder: the
+ * zero-I/O checkpoint row when usable, otherwise a cold read that folds
+ * only the log tail since the checkpoint and writes the refreshed row
+ * back — so a store scanned once serves later scans without log reads.
+ */
+ const projectedTitle = async (
+ cache: SessionProjectionCache,
+ record: SessionRecord,
+ signal: AbortSignal,
+ ): Promise => {
+ const live = ctx.sessions.get(record.header.id)
+ if (live !== undefined) return ctx.get('sessionProjections')?.snapshot(live).values.title
+ const cached = cache.cachedSnapshot(record.header)
+ if (cached !== undefined && 'title' in cached.values) return cached.values.title
+ return (await cache.coldSnapshot(record.header.id, signal)).values.title
+ }
+
+ /** One per-record title resolution: a title (absent for untitled) or an isolated failure. */
+ type TitleResolution = { title?: string; failure?: unknown }
+
+ /**
+ * Resolve every row's title without reading whole logs when the projection
+ * cache is mounted (live registry snapshot / checkpoint row / tail-only
+ * cold read, bounded by `resumeScanConcurrency`); a composition without
+ * the cache falls back to one bounded raw-log title batch.
+ */
+ const resolveTitles = async (
+ listQuery: SessionQueryService,
+ records: readonly SessionRecord[],
+ signal: AbortSignal,
+ ): Promise => {
+ const cache = ctx.get('sessionProjectionCache')
+ if (cache === undefined) {
+ const results = await listQuery.readTitleSnapshots(records.map(record => record.header.id), signal)
+ return records.map((record, index): TitleResolution => {
+ const result = results[index]
+ /* v8 ignore next 2 -- readTitleSnapshots returns one result per unique listed id in input order */
+ if (result === undefined || result.sessionId !== record.header.id) throw new Error(`resume scan misaligned at "${record.header.id}"`)
+ if (result.status === 'rejected') return { failure: result.reason }
+ const title = result.value.title?.title
+ return title === undefined ? {} : { title }
+ })
+ }
+ const resolutions = new Array(records.length)
+ let cursor = 0
+ const worker = async (): Promise => {
+ for (;;) {
+ const index = cursor
+ if (index >= records.length) return
+ cursor += 1
+ const record = records[index] as SessionRecord
+ try {
+ const value = await projectedTitle(cache, record, signal)
+ resolutions[index] = typeof value === 'string' ? { title: value } : {}
+ } catch (failure: unknown) {
+ resolutions[index] = { failure }
+ }
+ }
+ }
+ await Promise.all(Array.from(
+ { length: Math.min(resolved.resumeScanConcurrency, records.length) },
+ () => worker(),
+ ))
+ return resolutions
+ }
+
+ /** The latest logged provider/model route, for the preflight availability check. */
+ const resumeRoute = (events: readonly SessionEvent[]): { provider: string; model: string } | undefined => {
+ const header = events.findLast(item => item.type === 'request/header')
+ if (header?.type === 'request/header') {
+ return { provider: header.data.header.config.provider, model: header.data.header.config.model }
+ }
+ const assistant = events.findLast(item => item.type === 'assistant/message')
+ return assistant?.type === 'assistant/message'
+ ? { provider: assistant.data.message.source.provider, model: assistant.data.message.source.model }
+ : undefined
+ }
+
/**
* Re-read every mutable precondition immediately before terminal handoff and
- * resolve the exact identity and workspace the host will re-exec into.
+ * resolve the exact identity and workspace the host will re-exec into. This
+ * is where the one chosen log is fully read, replay-validated, and checked
+ * for a currently-available route — the listing never does any of that.
*/
const preflightResume = async (sessionId: SessionId): Promise<{ id: SessionId; cwd: string }> => {
const query = sessionQuery()
@@ -120,17 +211,24 @@ export function createResumeController(deps: ResumeControllerDeps): ResumeContro
if (initialStatus !== 'idle') throw new Error(`Resume requires an idle agent (status: ${initialStatus}).`)
const record = (await query.listSessions()).find(candidate => candidate.header.id === sessionId)
if (record === undefined) throw new Error(`Session "${sessionId}" is no longer available.`)
- const candidate = await readResumeCandidate(
- record,
- new Set(ctx.llm.listProviders().map(provider => provider.id)),
- )
+ const candidate = summarize(record, undefined, undefined)
if (candidate.disabledReason !== undefined) throw new Error(candidate.disabledReason)
- const cwd = candidate.record.header.cwd
+ let events: readonly SessionEvent[]
+ try {
+ events = (await query.readSession(record.header.id)).events
+ } catch (error: unknown) {
+ throw new Error(`session cannot be loaded: ${errorChain(error)}`)
+ }
+ const route = resumeRoute(events)
+ if (route !== undefined && !ctx.llm.listProviders().some(provider => provider.id === route.provider)) {
+ throw new Error(`session is complete, but route is currently unavailable (${route.provider}/${route.model})`)
+ }
+ const cwd = record.header.cwd
/* v8 ignore next -- summarizeResumeCandidate disables a cwd-less record, so the check above already rejected it */
if (cwd === undefined) throw new Error(`Session "${sessionId}" has no recorded workspace to resume in.`)
const finalStatus = deps.agentStatus()
if (finalStatus !== 'idle') throw new Error(`Resume requires an idle agent (status: ${finalStatus}).`)
- return { id: candidate.record.header.id, cwd }
+ return { id: record.header.id, cwd }
}
const handoffResume = async (candidate: ResumeCandidate, overlay: TuiOverlaySession): Promise => {
@@ -194,40 +292,78 @@ export function createResumeController(deps: ResumeControllerDeps): ResumeContro
}
const scan = ++resumeScan
void resumeOverlay?.close()
- void listQuery.listSessions().then(async (records) => {
- if (deps.isDisposed() || scan !== resumeScan) return
- // Every workspace in the store is summarized; the picker owns the
- // current-workspace/all-workspaces scope split over the whole set.
- const providers = new Set(ctx.llm.listProviders().map(provider => provider.id))
- const candidates = await Promise.all(records.map(record => readResumeCandidate(record, providers)))
- candidates.sort((a, b) => b.lastActivityAt - a.lastActivityAt
- || a.record.header.id.localeCompare(b.record.header.id))
- if (deps.isDisposed() || scan !== resumeScan) return
- const session = overlayManager.open({
- create: host => new ResumePicker(
- candidates,
+ // The picker opens before the scan settles so the terminal stops feeding
+ // the editor immediately; a queued activation (the closing predecessor
+ // still holds the slot) receives an already-scanned set through
+ // `scanned` instead of a loading placeholder.
+ let picker: ResumePicker | undefined
+ let scanned: ResumeCandidate[] | undefined
+ const session = overlayManager.open({
+ create: (host) => {
+ picker = new ResumePicker(
+ scanned,
resolved.maxResumeOptions,
workspaceLabel(agent.session.header.cwd),
() => host.viewport.rows,
palette,
(candidate) => { void handoffResume(candidate, session) },
() => { void session.close() },
- ),
- options: {
- width: '100%',
- maxHeight: '100%',
- anchor: 'top-left',
- margin: 0,
- },
- })
- resumeOverlay = session
- void session.closed.then(() => {
- /* v8 ignore next -- overlay FIFO closes this session before a replacement can become the tracked resume overlay */
- if (resumeOverlay === session) resumeOverlay = undefined
+ )
+ return picker
+ },
+ options: {
+ width: '100%',
+ maxHeight: '100%',
+ anchor: 'top-left',
+ margin: 0,
+ },
+ })
+ resumeOverlay = session
+ // Closing the picker — Escape, supersession, disposal — aborts the scan:
+ // the borrowed-log pass over a large store must not outlive its overlay.
+ const scanAbort = new AbortController()
+ void session.closed.then(() => {
+ scanAbort.abort()
+ /* v8 ignore next -- overlay FIFO closes this session before a replacement can become the tracked resume overlay */
+ if (resumeOverlay === session) resumeOverlay = undefined
+ })
+ deps.requestRender()
+ /** Whether this scan's overlay, session generation, or TUI is gone. */
+ const scanStale = (): boolean =>
+ deps.isDisposed() || scan !== resumeScan || scanAbort.signal.aborted
+ const scanCandidates = async (): Promise => {
+ // Every workspace in the store is listed; the picker owns the
+ // current-workspace/all-workspaces scope split over the whole set.
+ const records = await listQuery.listSessions(scanAbort.signal)
+ if (scanStale()) return
+ // Rows need only metadata, an mtime, and a title — resolved without
+ // whole-log reads when the projection cache is mounted. A corrupt
+ // neighbor degrades to one disabled row.
+ const [titles, activity] = await Promise.all([
+ resolveTitles(listQuery, records, scanAbort.signal),
+ Promise.all(records.map(record => lastActivityAt(record))),
+ ])
+ const candidates = records.map((record, index) => {
+ const resolution = titles[index] as TitleResolution
+ return 'failure' in resolution
+ ? unreadableCandidate(record, activity[index], resolution.failure)
+ : summarize(record, resolution.title, activity[index])
})
+ candidates.sort((a, b) => b.lastActivityAt - a.lastActivityAt
+ || a.record.header.id.localeCompare(b.record.header.id))
+ if (scanStale()) return
+ scanned = candidates
+ picker?.setCandidates(candidates)
deps.requestRender()
- }, (error: unknown) => {
- if (!deps.isDisposed() && scan === resumeScan) deps.appendNotice(`Resume session scan failed: ${errorChain(error)}`, 'error')
+ }
+ // One catch covers listing, titles, and mtimes, so a scan failure
+ // cannot strand the overlay on its loading placeholder; an aborted
+ // scan's rejection stays silent because the user already dismissed the
+ // picker.
+ void scanCandidates().catch((error: unknown) => {
+ if (scanStale()) return
+ void session.close()
+ deps.appendNotice(`Resume session scan failed: ${errorChain(error)}`, 'error')
})
},
}
diff --git a/packages/ui/tui/src/chat/timing.ts b/packages/ui/tui/src/chat/timing.ts
index 2312aa49b6..5bd7e4082b 100644
--- a/packages/ui/tui/src/chat/timing.ts
+++ b/packages/ui/tui/src/chat/timing.ts
@@ -132,32 +132,58 @@ function timingTotalsAt(state: TimingState, at?: number): TimingTotals {
return totals
}
+function stepKey(position: StepPosition): string {
+ return `${position.turn}:${position.step}`
+}
+
+interface TrackedStep extends TimingState {
+ /** Set at the step's `step/end`; later same-coordinate events no longer advance the step. */
+ closed: boolean
+}
+
/**
- * Replay one step's accumulated per-phase timing up to clock `at`.
- * @param events - Session events to replay.
- * @param position - Turn/step coordinates of the step.
- * @param at - Render clock to accumulate the open bucket up to.
- * @returns The step's per-phase totals.
+ * Incremental per-step timing accumulator shared by every step's timing footer
+ * in one transcript. One forward pass over the append-only session log serves
+ * all steps' totals: each query advances a cursor over the events appended
+ * since the previous query, so a transcript of S steps costs O(events) in
+ * total instead of the O(S × events) of replaying the whole log per footer
+ * ([rationale](../../../../../.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.md)).
+ *
+ * The log must be append-only with stable indices (the session `seq = log
+ * length` contract). Event times are consumed as logged: a backward wall-clock
+ * step clamps each bucket at zero rather than cutting the scan off at the
+ * query clock. The open bucket is accumulated to the query clock at lookup,
+ * never during the scan.
*/
-export function stepTimingAt(
- events: readonly SessionEvent[],
- position: StepPosition,
- at: number,
-): TimingTotals {
- const startIndex = events.findIndex(event => event.type === 'step/start' && sameStep(event, position))
- if (startIndex < 0) return emptyTimingTotals()
- const start = events[startIndex] as Extract
- const state = timingState(start.time)
- for (let index = startIndex + 1; index < events.length; index += 1) {
- const event = events[index] as SessionEvent
- if (event.time > at) break
- if ((event.type === 'assistant/chunk' || event.type === 'tool/call' || event.type === 'step/end')
- && sameStep(event, position)) {
- advanceStepTiming(state, event)
- if (event.type === 'step/end') break
+export class StepTimingTracker {
+ private scanned = 0
+ private readonly steps = new Map()
+
+ /**
+ * Advance over events appended since the previous query, then return one
+ * step's accumulated per-phase timing up to clock `at`.
+ * @param events - Current session event log (append-only).
+ * @param position - Turn/step coordinates of the queried step.
+ * @param at - Render clock to accumulate the open bucket up to.
+ * @returns The step's per-phase totals; empty when the step never started.
+ */
+ totalsAt(events: readonly SessionEvent[], position: StepPosition, at: number): TimingTotals {
+ for (; this.scanned < events.length; this.scanned += 1) {
+ const event = events[this.scanned] as SessionEvent
+ if (event.type === 'step/start') {
+ const key = stepKey(event.data)
+ if (!this.steps.has(key)) this.steps.set(key, { ...timingState(event.time), closed: false })
+ } else if (event.type === 'assistant/chunk' || event.type === 'tool/call' || event.type === 'step/end') {
+ const state = this.steps.get(stepKey(event.data))
+ if (state !== undefined && !state.closed) {
+ advanceStepTiming(state, event)
+ if (event.type === 'step/end') state.closed = true
+ }
+ }
}
+ const state = this.steps.get(stepKey(position))
+ return state === undefined ? emptyTimingTotals() : timingTotalsAt(state, at)
}
- return timingTotalsAt(state, at)
}
/**
@@ -191,7 +217,7 @@ const COMPACTING_GLYPH = '⊙'
/**
* Derive the currently open step's active timing bucket, or `undefined` when no
* step is open. The open step is the last `step/start` with no later matching
- * `step/end`; its bucket is replayed with the same rules as {@link stepTimingAt}.
+ * `step/end`; its bucket is replayed with the same rules as {@link StepTimingTracker}.
* @param events - Session events to scan.
* @returns The open step's active bucket, or `undefined`.
*/
diff --git a/packages/ui/tui/src/components/dialogs.ts b/packages/ui/tui/src/components/dialogs.ts
index 6867a30240..d427b906e1 100644
--- a/packages/ui/tui/src/components/dialogs.ts
+++ b/packages/ui/tui/src/components/dialogs.ts
@@ -23,14 +23,8 @@ import {
type AgentLlmTarget,
} from '@deepseek-ai/dsh-agent'
import type { LlmModelInfo, LlmModelReasoningInfo, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
-import { lastActivityTime } from '@deepseek-ai/dsh-session'
import type { SessionId } from '@deepseek-ai/dsh-session'
-import { foldGoal, type GoalPhase } from '@deepseek-ai/dsh-goal'
-import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
-import type {
- SessionLogSnapshot,
- SessionRecord,
-} from '@deepseek-ai/dsh-session-query'
+import type { SessionRecord } from '@deepseek-ai/dsh-session-query'
import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction'
import { BRACKETED_PASTE_END, BRACKETED_PASTE_START, displayText, sanitizePastedText } from './text.ts'
import { dialogSelectTheme, type Palette } from './theme.ts'
@@ -506,95 +500,53 @@ export class DetailsDialog implements Component {
}
}
-/** The provider/model route recovered from a resume candidate's log. */
-export interface ResumeRoute {
- provider: string
- model: string
-}
-
-/** A preflighted resume selector row summarizing one persisted session. */
+/** A resume selector row summarizing one session from metadata and its folded title. */
export interface ResumeCandidate {
record: SessionRecord
title: string
+ /** Last observed change: live last-event time or artifact mtime, falling back to creation. */
lastActivityAt: number
- lastTurn: string
/** Whether the session's workspace is the one the current session runs in, which selects the picker scope that lists it. */
currentWorkspace: boolean
/** The session's own workspace as a prompt-style label; the all-workspaces scope shows it per row. */
workspaceLabel: string
- route?: ResumeRoute
- goalPhase?: GoalPhase
disabledReason?: string
}
-function resumeTurnLabel(snapshot: SessionLogSnapshot): string {
- const event = snapshot.events.findLast(item => item.type === 'turn/end')
- if (event === undefined) return 'no completed turn'
- const reason = event.data.reason
- switch (reason.kind) {
- case 'completed': return `turn ${event.data.turn}: completed`
- case 'aborted': return `turn ${event.data.turn}: cancelled`
- case 'error': return `turn ${event.data.turn}: error`
- case 'disposed': return `turn ${event.data.turn}: disposed`
- case 'max-tokens': return `turn ${event.data.turn}: max tokens`
- case 'interrupted': return `turn ${event.data.turn}: interrupted`
- default: return `turn ${event.data.turn}: unknown result`
- }
-}
-
-function resumeRoute(snapshot: SessionLogSnapshot): ResumeRoute | undefined {
- const header = snapshot.events.findLast(item => item.type === 'request/header')
- if (header?.type === 'request/header') {
- return { provider: header.data.header.config.provider, model: header.data.header.config.model }
- }
- const assistant = snapshot.events.findLast(item => item.type === 'assistant/message')
- return assistant?.type === 'assistant/message'
- ? { provider: assistant.data.message.source.provider, model: assistant.data.message.source.model }
- : undefined
-}
-
/**
- * Build one resume selector row from a record and its log snapshot, deriving the
- * title, route, goal phase, workspace scope, and any reason the session cannot
- * be resumed here. A workspace other than the current one is a scope, not a
- * disabled reason: resuming it hands the process off into that directory.
+ * Build one resume selector row from a record, its batch-folded title, and a
+ * metadata-derived activity time, deriving the workspace scope and any reason
+ * the session cannot be resumed here. A workspace other than the current one
+ * is a scope, not a disabled reason: resuming it hands the process off into
+ * that directory. Rows carry no per-log detail beyond the title — route and
+ * replay validity are checked by the Enter-time preflight against the one
+ * chosen log.
* @param record - The session record.
- * @param snapshot - The session's log snapshot.
+ * @param title - The session's batch-folded title, absent for an untitled log.
+ * @param lastActivityAt - Metadata activity time; absent falls back to the header's creation time.
* @param currentId - The current session id.
* @param cwd - The CURRENT session's workspace, which decides the picker scope this row falls in.
- * @param availableProviders - Providers registered in this runtime.
* @param formatWorkspace - Renders THIS record's own cwd as its prompt-style label.
* @returns The summarized resume candidate.
*/
export function summarizeResumeCandidate(
record: SessionRecord,
- snapshot: SessionLogSnapshot,
+ title: string | undefined,
+ lastActivityAt: number | undefined,
currentId: SessionId,
cwd: string | undefined,
- availableProviders: ReadonlySet,
formatWorkspace: (cwd: string | undefined) => string,
): ResumeCandidate {
- const title = foldSessionTitle(snapshot.events)?.title ?? 'Untitled session'
- const route = resumeRoute(snapshot)
- const foldedGoal = foldGoal(snapshot.events).goal
let disabledReason: string | undefined
if (record.header.id === currentId) disabledReason = 'current session'
else if (record.live) disabledReason = 'session is already live in this runtime'
else if (record.header.cwd === undefined) disabledReason = 'session has no recorded workspace'
- else if (route !== undefined && !availableProviders.has(route.provider)) {
- disabledReason = `session is complete, but route is currently unavailable (${route.provider}/${route.model})`
- }
return {
record,
- title,
- // Excludes a prior pickup's boundary, or every browsed session floats up.
- lastActivityAt: lastActivityTime(snapshot.events) ?? snapshot.session.createdAt,
- lastTurn: resumeTurnLabel(snapshot),
+ title: title ?? 'Untitled session',
+ lastActivityAt: lastActivityAt ?? record.header.createdAt,
currentWorkspace: record.header.cwd === cwd,
workspaceLabel: formatWorkspace(record.header.cwd),
- ...route === undefined ? {} : { route },
- /* v8 ignore next -- goal-bearing resume records are covered by the goal/session integration surface. */
- ...foldedGoal === undefined ? {} : { goalPhase: foldedGoal.phase },
...disabledReason === undefined ? {} : { disabledReason },
}
}
@@ -609,6 +561,10 @@ export type ResumeScope = 'workspace' | 'all'
* current session's workspace, `all` lists every workspace and labels each row
* with its own. Tab toggles between them; the search query and selection reset
* on a scope change so the highlighted row always belongs to the visible list.
+ *
+ * The picker opens before the session scan settles: an `undefined` candidate
+ * set renders a loading placeholder that keeps input away from the editor,
+ * and `setCandidates` swaps the scanned rows in without replacing the overlay.
*/
export class ResumePicker implements Component, Focusable {
private readonly search = new Input()
@@ -616,27 +572,43 @@ export class ResumePicker implements Component, Focusable {
private selectedIndex = 0
private error = ''
private scope: ResumeScope = 'workspace'
+ private candidates: readonly ResumeCandidate[] | undefined
focused = false
constructor(
- private readonly candidates: readonly ResumeCandidate[],
+ candidates: readonly ResumeCandidate[] | undefined,
private readonly maxVisible: number,
private readonly workspaceLabel: string,
private readonly viewportRows: () => number,
private readonly palette: Palette,
private readonly done: (candidate: ResumeCandidate) => void,
private readonly cancel: () => void,
- ) {}
+ ) {
+ this.candidates = candidates
+ }
invalidate(): void {
this.search.invalidate()
}
+ /**
+ * Replace the loading placeholder with the scanned candidate set.
+ * @param candidates - the summarized rows the finished scan produced.
+ */
+ setCandidates(candidates: readonly ResumeCandidate[]): void {
+ this.candidates = candidates
+ this.selectedIndex = 0
+ // A still-loading error is false the moment rows exist.
+ this.error = ''
+ this.invalidate()
+ }
+
/** Candidates in the active scope, before the search query narrows them. */
private scoped(): ResumeCandidate[] {
+ const candidates = this.candidates ?? []
return this.scope === 'all'
- ? [...this.candidates]
- : this.candidates.filter(candidate => candidate.currentWorkspace)
+ ? [...candidates]
+ : candidates.filter(candidate => candidate.currentWorkspace)
}
private filtered(): ResumeCandidate[] {
@@ -653,7 +625,7 @@ export class ResumePicker implements Component, Focusable {
private visibleCandidateCount(): number {
// The all-workspaces scope adds a per-row workspace line, so a row costs
// one more terminal row there than in the single-workspace scope.
- const rowHeight = this.scope === 'all' ? 5 : 4
+ const rowHeight = this.scope === 'all' ? 4 : 3
const candidateBudget = Math.max(1, Math.floor((Math.max(1, this.viewportRows()) - 13) / rowHeight))
return Math.min(this.maxVisible, candidateBudget)
}
@@ -718,7 +690,8 @@ export class ResumePicker implements Component, Focusable {
this.error = ''
} else if (matchesKey(data, Key.enter)) {
const selected = filtered[this.selectedIndex]
- if (selected === undefined) this.error = 'No session matches this search.'
+ if (this.candidates === undefined) this.error = 'Sessions are still loading.'
+ else if (selected === undefined) this.error = 'No session matches this search.'
else if (selected.disabledReason !== undefined) this.error = selected.disabledReason
else this.done(selected)
} else {
@@ -738,12 +711,13 @@ export class ResumePicker implements Component, Focusable {
* workspace it means, and the inactive scope with the count Tab would reveal.
*/
private renderScopeLine(): string {
- const inWorkspace = this.candidates.filter(candidate => candidate.currentWorkspace).length
+ const candidates = this.candidates ?? []
+ const inWorkspace = candidates.filter(candidate => candidate.currentWorkspace).length
const active = this.scope === 'workspace'
? `this workspace ${displayText(this.workspaceLabel)}`
- : `all workspaces (${this.candidates.length})`
+ : `all workspaces (${candidates.length})`
const other = this.scope === 'workspace'
- ? `all workspaces (${this.candidates.length})`
+ ? `all workspaces (${candidates.length})`
: `this workspace (${inWorkspace})`
return `${this.palette.accent(active)}${this.palette.dim(` ⇥ ${other}`)}`
}
@@ -758,9 +732,12 @@ export class ResumePicker implements Component, Focusable {
if (this.selectedIndex >= filtered.length) this.selectedIndex = Math.max(0, filtered.length - 1)
const selected = filtered[this.selectedIndex]
const position = selected === undefined ? 0 : this.selectedIndex + 1
+ const title = this.candidates === undefined
+ ? 'Resume session'
+ : `Resume session (${position} of ${filtered.length})`
const lines: string[] = [
'',
- `${indent}${this.palette.bold(this.palette.accent(`Resume session (${position} of ${filtered.length})`))}`,
+ `${indent}${this.palette.bold(this.palette.accent(title))}`,
'',
]
@@ -795,11 +772,7 @@ export class ResumePicker implements Component, Focusable {
].filter((value): value is string => value !== undefined).join(' · ')
const lead = `${active ? '❯' : ' '} ${displayText(candidate.title)}`
push(active ? this.palette.bold(this.palette.accent(lead)) : lead)
- const route = candidate.route === undefined ? 'route unavailable' : `${candidate.route.provider}/${candidate.route.model}`
- /* v8 ignore next -- only goal-bearing resume records add this integration-owned suffix. */
- const goal = candidate.goalPhase === undefined ? '' : ` · goal ${candidate.goalPhase}`
- push(this.palette.dim(` ${new Date(candidate.lastActivityAt).toISOString()} · ${candidate.lastTurn} · ${route}${goal}`))
- push(this.palette.dim(` ${status} · ${displayText(candidate.record.header.id)}`))
+ push(this.palette.dim(` ${new Date(candidate.lastActivityAt).toISOString()} · ${status} · ${displayText(candidate.record.header.id)}`))
// Only the all-workspaces scope mixes directories, so the per-row
// workspace is redundant in the scope that already names one.
if (this.scope === 'all') {
@@ -809,7 +782,8 @@ export class ResumePicker implements Component, Focusable {
push(this.palette.warning(` unavailable: ${displayText(candidate.disabledReason)}`))
}
}
- if (filtered.length === 0) push(this.palette.warning('No matching sessions.'))
+ if (this.candidates === undefined) push(this.palette.dim('Loading sessions…'))
+ else if (filtered.length === 0) push(this.palette.warning('No matching sessions.'))
if (this.error !== '') {
lines.push('')
push(this.palette.error(displayText(this.error)))
diff --git a/packages/ui/tui/src/components/transcript.ts b/packages/ui/tui/src/components/transcript.ts
index f0422e8417..edf5a5a661 100644
--- a/packages/ui/tui/src/components/transcript.ts
+++ b/packages/ui/tui/src/components/transcript.ts
@@ -33,8 +33,8 @@ import { contentText, type ParsedArguments } from './content.ts'
import {
formatCompletionTime,
formatTimingTotals,
- stepTimingAt,
type StepPosition,
+ type StepTimingTracker,
} from '../chat/timing.ts'
/** Concatenate the text of every block of one type, separated by blank lines. */
@@ -228,6 +228,7 @@ class StepTimingComponent extends Container {
constructor(
private readonly position: StepPosition,
private readonly events: () => readonly SessionEvent[],
+ private readonly tracker: StepTimingTracker,
private readonly now: () => number,
private readonly palette: Palette,
) {
@@ -247,7 +248,7 @@ class StepTimingComponent extends Container {
private rebuild(): void {
this.clear()
- const totals = stepTimingAt(this.events(), this.position, this.completionTime ?? this.now())
+ const totals = this.tracker.totalsAt(this.events(), this.position, this.completionTime ?? this.now())
const timing = formatTimingTotals(totals, true)
const header = this.completionTime === undefined
? timing
@@ -277,13 +278,14 @@ export class StreamingAssistantComponent extends Container {
/** The step's turn/step coordinates, used to group steps into their turn. */
readonly position: StepPosition,
events: () => readonly SessionEvent[],
+ tracker: StepTimingTracker,
now: () => number,
private showReasoning: boolean,
private readonly palette: Palette,
private readonly mdTheme: MarkdownTheme,
) {
super()
- this.timing = new StepTimingComponent(position, events, now, palette)
+ this.timing = new StepTimingComponent(position, events, tracker, now, palette)
this.rebuild()
}
@@ -409,8 +411,43 @@ interface CardBody {
*/
export type ToolCardVisibility = 'hidden' | 'collapsed' | 'expanded'
+/**
+ * Transcript card with a width-keyed rendered-row cache. pi-tui re-renders
+ * every component each frame and relies on per-component line caches (its own
+ * `Text`/`Markdown` do this); a card that rebuilds rows inside `render(width)`
+ * would re-wrap its output every frame
+ * ([rationale](../../../../../.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.md)).
+ * Subclasses render through {@link renderLines} and call {@link dropLines}
+ * from every state mutator; with `invalidate()` (pi-tui's tree-wide cascade)
+ * also dropping, a state change always re-renders.
+ */
+abstract class CachedCardComponent implements Component {
+ private cached: { width: number; lines: string[] } | undefined
+
+ /** Discard the cached rows so the next render recomputes them. */
+ protected dropLines(): void {
+ this.cached = undefined
+ }
+
+ invalidate(): void {
+ this.cached = undefined
+ }
+
+ render(width: number): string[] {
+ if (this.cached?.width !== width) this.cached = { width, lines: this.renderLines(width) }
+ return this.cached.lines
+ }
+
+ /**
+ * Render the card's rows for `width` without caching.
+ * @param width - Render width the rows are wrapped to.
+ * @returns The card's rows.
+ */
+ protected abstract renderLines(width: number): string[]
+}
+
/** A tool call and its result, rendered as a collapsible status card. */
-export class ToolCardComponent implements Component {
+export class ToolCardComponent extends CachedCardComponent {
private result: { content: ContentBlock[]; isError: boolean; meta?: JsonValue } | undefined
private visibility: ToolCardVisibility = 'collapsed'
private callView: ToolCallView
@@ -426,6 +463,7 @@ export class ToolCardComponent implements Component {
private readonly palette: Palette,
private readonly mdTheme: MarkdownTheme,
) {
+ super()
this.callView = this.presentCall()
}
@@ -447,6 +485,7 @@ export class ToolCardComponent implements Component {
*/
updateResult(event: Extract['data']): void {
this.diffBodyCache = undefined
+ this.dropLines()
const result = event.message.content[0]
this.result = {
content: [...result.content],
@@ -469,11 +508,10 @@ export class ToolCardComponent implements Component {
*/
setVisibility(visibility: ToolCardVisibility): void {
this.visibility = visibility
+ this.dropLines()
}
- invalidate(): void {}
-
- render(width: number): string[] {
+ protected renderLines(width: number): string[] {
// Hidden renders nothing — not even the leading gap — so the transcript
// keeps only the conversation, the way Codex hides tool calls.
if (this.visibility === 'hidden') return []
@@ -725,7 +763,7 @@ function stripReminderFrame(text: string): string {
* well-formed XML, which made both the fold and the frame-line suppression
* content-dependent.
*/
-export class ContextCardComponent implements Component {
+export class ContextCardComponent extends CachedCardComponent {
private expanded = false
constructor(
@@ -733,7 +771,9 @@ export class ContextCardComponent implements Component {
private readonly text: string,
private readonly maxOutputLines: number,
private readonly palette: Palette,
- ) {}
+ ) {
+ super()
+ }
/**
* Expand or collapse the card body.
@@ -741,11 +781,10 @@ export class ContextCardComponent implements Component {
*/
setExpanded(expanded: boolean): void {
this.expanded = expanded
+ this.dropLines()
}
- invalidate(): void {}
-
- render(width: number): string[] {
+ protected renderLines(width: number): string[] {
const header = this.palette.dim(`Context · ${displayText(this.label)}`)
// Emptiness is decided on the stripped text: styling a blank body would yield
// one escape-only row, which reads as a stray blank line under the header.
diff --git a/packages/ui/tui/src/config.ts b/packages/ui/tui/src/config.ts
index 8b07629af8..28ec85edb6 100644
--- a/packages/ui/tui/src/config.ts
+++ b/packages/ui/tui/src/config.ts
@@ -42,6 +42,8 @@ export interface TuiConfig {
maxModelOptions?: number
/** Maximum sessions visible at once in the resume selector. */
maxResumeOptions?: number
+ /** Maximum concurrent cold projection reads in one resume scan. */
+ resumeScanConcurrency?: number
/** User-question panel width in terminal columns, clamped to the terminal. */
questionDialogWidth?: number
/** User-question panel maximum height in terminal rows. */
@@ -72,6 +74,7 @@ const maxDiffEditLengthSchema = z.number().step(1).min(1).default(1000)
const maxQuestionOptionsSchema = z.number().step(1).min(1).default(8)
const maxModelOptionsSchema = z.number().step(1).min(1).default(8)
const maxResumeOptionsSchema = z.number().step(1).min(1).default(8)
+const resumeScanConcurrencySchema = z.number().step(1).min(1).default(4)
const questionDialogWidthSchema = z.number().step(1).min(20).default(200)
const questionDialogMaxHeightSchema = z.number().step(1).min(6).default(20)
const modelDialogWidthSchema = z.number().step(1).min(20).default(76)
@@ -105,6 +108,7 @@ const tuiConfigSchemaFields = {
maxQuestionOptions: maxQuestionOptionsSchema,
maxModelOptions: maxModelOptionsSchema,
maxResumeOptions: maxResumeOptionsSchema,
+ resumeScanConcurrency: resumeScanConcurrencySchema,
questionDialogWidth: questionDialogWidthSchema,
questionDialogMaxHeight: questionDialogMaxHeightSchema,
modelDialogWidth: modelDialogWidthSchema,
@@ -178,6 +182,7 @@ export interface ResolvedTuiConfig {
maxQuestionOptions: number
maxModelOptions: number
maxResumeOptions: number
+ resumeScanConcurrency: number
questionDialogWidth: number
questionDialogMaxHeight: number
modelDialogWidth: number
@@ -205,6 +210,7 @@ export function resolveTuiConfig(config: TuiConfig | undefined): ResolvedTuiConf
maxQuestionOptions: config?.maxQuestionOptions ?? 8,
maxModelOptions: config?.maxModelOptions ?? 8,
maxResumeOptions: config?.maxResumeOptions ?? 8,
+ resumeScanConcurrency: config?.resumeScanConcurrency ?? 4,
questionDialogWidth: config?.questionDialogWidth ?? 200,
questionDialogMaxHeight: config?.questionDialogMaxHeight ?? 20,
modelDialogWidth: config?.modelDialogWidth ?? 76,
diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts
index 0ddb73ed9c..ffcf69dbb6 100644
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -88,6 +88,7 @@ import {
runningPhaseGlyph,
STATUS_ANIMATION_INTERVAL_MS,
STATUS_FADE_MS,
+ StepTimingTracker,
TIMING_BUCKET_GLYPHS,
type StepPosition,
} from './chat/timing.ts'
@@ -358,6 +359,9 @@ export function createTuiChat(
let toolsVisibility: ToolCardVisibility = 'collapsed'
let streaming: StreamingAssistantComponent | undefined
let completedStreaming: StreamingAssistantComponent | undefined
+ // One shared accumulator serves every step's timing footer; per-footer
+ // replay of the whole log is quadratic on a long resumed session.
+ const stepTimingTracker = new StepTimingTracker()
// Assistant step components in model order per turn, for hidden-mode folding:
// with tool cards hidden, a turn keeps one Assistant header and later steps
// render as headerless continuations (see applyTurnFolding).
@@ -769,6 +773,7 @@ export function createTuiChat(
streaming = new StreamingAssistantComponent(
position,
() => agent.session.events,
+ stepTimingTracker,
now,
showReasoning,
palette,
diff --git a/packages/ui/tui/tests/harness.ts b/packages/ui/tui/tests/harness.ts
index a62b695b72..3f10d6cfe3 100644
--- a/packages/ui/tui/tests/harness.ts
+++ b/packages/ui/tui/tests/harness.ts
@@ -69,6 +69,8 @@ export interface TuiHarnessOptions {
sessionPersistence?: {
list(): Promise
load?(id: ReturnType): Promise<{ meta: SessionHeader; events: Session['events'] }>
+ /** Per-session artifact location for mtime-based activity; defaults to none. */
+ locate?(meta: SessionHeader): { kind: string; path: string } | undefined
}
handoffResume?: TuiRuntime['handoffResume']
/** Host-supplied exit line; absent exercises the no-message path. */
@@ -156,7 +158,7 @@ export async function createTuiTestHarness undefined,
+ locate: (meta: SessionHeader) => persistence.locate?.(meta),
create: () => Promise.resolve(),
append: () => Promise.resolve(),
load: persistence.load === undefined
diff --git a/packages/ui/tui/tests/snapshots/resume-sessions-all-workspaces.expected.txt b/packages/ui/tui/tests/snapshots/resume-sessions-all-workspaces.expected.txt
index 63ca211c89..9ab0788461 100644
--- a/packages/ui/tui/tests/snapshots/resume-sessions-all-workspaces.expected.txt
+++ b/packages/ui/tui/tests/snapshots/resume-sessions-all-workspaces.expected.txt
@@ -22,28 +22,25 @@ buffer
8| " "
9| " ❯ Untitled session "
style 2-19 fg=bright-magenta bold
-10| " 2026-07-23T08:00:00.000Z · no completed turn · route unavailable "
- style 2-67 dim
-11| " current · live · main-session "
- style 2-32 dim
-12| " workspace /workspace/project "
+10| " 2026-07-23T08:00:00.000Z · current · live · main-session "
+ style 2-59 dim
+11| " workspace /workspace/project "
style 2-31 dim
-13| " unavailable: current session "
+12| " unavailable: current session "
style 2-31 fg=yellow
-14| " Other workspace work "
-15| " 2024-02-02T00:00:08.000Z · turn 1: completed · deepseek-official/deepseek-v4-pro "
- style 2-83 dim
-16| " persisted · elsewhere-session "
- style 2-32 dim
-17| " workspace /workspace/other "
+13| " Other workspace work "
+14| " 2024-02-02T00:00:00.000Z · persisted · elsewhere-session "
+ style 2-59 dim
+15| " workspace /workspace/other "
style 2-29 dim
-18| " Resume selector design "
-19| " 2024-01-01T00:00:08.000Z · turn 1: completed · deepseek-official/deepseek-v4-pro "
- style 2-83 dim
-20| " persisted · earlier-session "
- style 2-30 dim
-21| " workspace /workspace/project "
+16| " Resume selector design "
+17| " 2024-01-01T00:00:00.000Z · persisted · earlier-session "
+ style 2-57 dim
+18| " workspace /workspace/project "
style 2-31 dim
+19| " "
+20| " "
+21| " "
22| " "
23| " "
24| " "
diff --git a/packages/ui/tui/tests/snapshots/resume-sessions-loading.expected.txt b/packages/ui/tui/tests/snapshots/resume-sessions-loading.expected.txt
new file mode 100644
index 0000000000..e44621ad60
--- /dev/null
+++ b/packages/ui/tui/tests/snapshots/resume-sessions-loading.expected.txt
@@ -0,0 +1,47 @@
+terminal 92x32 buffer=normal length=32 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "DSH snapshot"
+cursor hidden column=6 viewportRow=4 bufferRow=4
+buffer
+0| " "
+1| " Resume session "
+ style 2-15 fg=bright-magenta bold
+2| " "
+3| " ╭──────────────────────────────────────────────────────────────────────────────────────╮ "
+ style 2-89 dim
+4| " │ ⌕ │ "
+ style 2-2 dim
+ style 6-6 inverse
+ style 89-89 dim
+5| " ╰──────────────────────────────────────────────────────────────────────────────────────╯ "
+ style 2-89 dim
+6| " "
+7| " this workspace /workspace/project ⇥ all workspaces (0) "
+ style 2-34 fg=bright-magenta
+ style 35-56 dim
+8| " "
+9| " Loading sessions… "
+ style 2-18 dim
+10| " "
+11| " "
+12| " "
+13| " "
+14| " "
+15| " "
+16| " "
+17| " "
+18| " "
+19| " "
+20| " "
+21| " "
+22| " "
+23| " "
+24| " "
+25| " "
+26| " "
+27| " "
+28| " "
+29| " "
+30| " Type to search • ↑/↓ navigate • Tab scope • Enter resume • Esc clear/cancel "
+ style 2-84 dim
+31| " "
diff --git a/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt b/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt
index 46452aebdb..6f3e87ed43 100644
--- a/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt
+++ b/packages/ui/tui/tests/snapshots/resume-sessions.expected.txt
@@ -22,17 +22,15 @@ buffer
8| " "
9| " ❯ Untitled session "
style 2-19 fg=bright-magenta bold
-10| " 2026-07-23T08:00:00.000Z · no completed turn · route unavailable "
- style 2-67 dim
-11| " current · live · main-session "
- style 2-32 dim
-12| " unavailable: current session "
+10| " 2026-07-23T08:00:00.000Z · current · live · main-session "
+ style 2-59 dim
+11| " unavailable: current session "
style 2-31 fg=yellow
-13| " Resume selector design "
-14| " 2024-01-01T00:00:08.000Z · turn 1: completed · deepseek-official/deepseek-v4-pro "
- style 2-83 dim
-15| " persisted · earlier-session "
- style 2-30 dim
+12| " Resume selector design "
+13| " 2024-01-01T00:00:00.000Z · persisted · earlier-session "
+ style 2-57 dim
+14| " "
+15| " "
16| " "
17| " "
18| " "
diff --git a/packages/ui/tui/tests/timing-tracker.spec.ts b/packages/ui/tui/tests/timing-tracker.spec.ts
new file mode 100644
index 0000000000..93eecb08e9
--- /dev/null
+++ b/packages/ui/tui/tests/timing-tracker.spec.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { StepTimingTracker } from '../src/chat/timing.ts'
+
+/** One completed two-phase step plus a tool call, in event-log order. */
+function stepEvents(turn: number, step: number, base: number, seq: number): SessionEvent[] {
+ return [
+ { type: 'step/start', seq: seq, time: base, data: { turn, step } },
+ { type: 'assistant/chunk', seq: seq + 1, time: base + 100, data: { turn, step, chunk: { type: 'block-start', index: 0, blockType: 'reasoning' } } },
+ { type: 'assistant/chunk', seq: seq + 2, time: base + 300, data: { turn, step, chunk: { type: 'text-delta', index: 1, text: 'hi' } } },
+ { type: 'tool/call', seq: seq + 3, time: base + 450, data: { turn, step, callId: 'call-1', name: 'bash', arguments: '{}' } },
+ { type: 'step/end', seq: seq + 4, time: base + 700, data: { turn, step } },
+ ] as SessionEvent[]
+}
+
+describe('StepTimingTracker', () => {
+ it('accumulates each phase from the step lifecycle', () => {
+ const tracker = new StepTimingTracker()
+ const events = stepEvents(1, 1, 1_000, 0)
+ expect(tracker.totalsAt(events, { turn: 1, step: 1 }, 2_000)).toEqual({
+ ttft: 100, // step/start -> first chunk
+ thinking: 200, // reasoning block-start -> text delta
+ responding: 150, // text delta -> tool call
+ tools: 250, // tool call -> step/end
+ })
+ })
+
+ it('returns empty totals for a step that never started', () => {
+ const tracker = new StepTimingTracker()
+ expect(tracker.totalsAt(stepEvents(1, 1, 1_000, 0), { turn: 9, step: 9 }, 2_000)).toEqual({
+ ttft: 0, thinking: 0, responding: 0, tools: 0,
+ })
+ })
+
+ it('accumulates the open bucket to the query clock without mutating tracked state', () => {
+ const tracker = new StepTimingTracker()
+ const events = [
+ { type: 'step/start', seq: 0, time: 1_000, data: { turn: 1, step: 1 } },
+ ] as SessionEvent[]
+ expect(tracker.totalsAt(events, { turn: 1, step: 1 }, 1_250).ttft).toBe(250)
+ expect(tracker.totalsAt(events, { turn: 1, step: 1 }, 1_400).ttft).toBe(400)
+ })
+
+ it('matches a fresh replay when queried incrementally across appends', () => {
+ const incremental = new StepTimingTracker()
+ const first = stepEvents(1, 1, 1_000, 0)
+ incremental.totalsAt(first, { turn: 1, step: 1 }, 5_000)
+ const events = [...first, ...stepEvents(1, 2, 3_000, first.length)]
+ const fresh = new StepTimingTracker()
+ for (const position of [{ turn: 1, step: 1 }, { turn: 1, step: 2 }]) {
+ expect(incremental.totalsAt(events, position, 5_000)).toEqual(fresh.totalsAt(events, position, 5_000))
+ }
+ })
+
+ it('serves interleaved steps from one shared scan', () => {
+ const tracker = new StepTimingTracker()
+ const events = [
+ { type: 'step/start', seq: 0, time: 1_000, data: { turn: 1, step: 1 } },
+ { type: 'step/start', seq: 1, time: 1_100, data: { turn: 1, step: 2 } },
+ { type: 'assistant/chunk', seq: 2, time: 1_200, data: { turn: 1, step: 2, chunk: { type: 'text-delta', index: 0, text: 'x' } } },
+ { type: 'step/end', seq: 3, time: 1_500, data: { turn: 1, step: 2 } },
+ { type: 'step/end', seq: 4, time: 1_600, data: { turn: 1, step: 1 } },
+ ] as SessionEvent[]
+ expect(tracker.totalsAt(events, { turn: 1, step: 1 }, 9_000)).toEqual({ ttft: 600, thinking: 0, responding: 0, tools: 0 })
+ expect(tracker.totalsAt(events, { turn: 1, step: 2 }, 9_000)).toEqual({ ttft: 100, thinking: 0, responding: 300, tools: 0 })
+ })
+
+ it('keeps the first step/start when a duplicate arrives while the step is open', () => {
+ const tracker = new StepTimingTracker()
+ const events = [
+ { type: 'step/start', seq: 0, time: 1_000, data: { turn: 1, step: 1 } },
+ { type: 'step/start', seq: 1, time: 1_500, data: { turn: 1, step: 1 } },
+ ] as SessionEvent[]
+ expect(tracker.totalsAt(events, { turn: 1, step: 1 }, 2_000).ttft).toBe(1_000)
+ })
+
+ it('ignores same-coordinate events after the step closed', () => {
+ const tracker = new StepTimingTracker()
+ const events = [
+ ...stepEvents(1, 1, 1_000, 0),
+ // A stray duplicate start and a late chunk reuse the coordinates; the
+ // closed step's totals stay pinned.
+ { type: 'step/start', seq: 5, time: 9_000, data: { turn: 1, step: 1 } },
+ { type: 'assistant/chunk', seq: 6, time: 9_100, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'late' } } },
+ ] as SessionEvent[]
+ expect(tracker.totalsAt(events, { turn: 1, step: 1 }, 10_000)).toEqual({
+ ttft: 100, thinking: 200, responding: 150, tools: 250,
+ })
+ })
+})
diff --git a/packages/ui/tui/tests/transcript-card-cache.spec.ts b/packages/ui/tui/tests/transcript-card-cache.spec.ts
new file mode 100644
index 0000000000..9f484f21b9
--- /dev/null
+++ b/packages/ui/tui/tests/transcript-card-cache.spec.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { createToolResultMessage, CallId } from '@deepseek-ai/dsh-llm'
+import { ContextCardComponent, ToolCardComponent } from '../src/components/transcript.ts'
+import { parseArguments } from '../src/components/content.ts'
+import { createPalette, markdownTheme } from '../src/components/theme.ts'
+
+const palette = createPalette(false)
+const mdTheme = markdownTheme(palette)
+
+function toolCard(): ToolCardComponent {
+ return new ToolCardComponent('bash', parseArguments('{"command":"ls"}'), undefined, 10, 2_000, palette, mdTheme)
+}
+
+function toolResult(text: string): Extract['data'] {
+ const message = createToolResultMessage({
+ callId: CallId('call-1'),
+ content: [{ type: 'text', text }],
+ isError: false,
+ })
+ return { turn: 1, step: 1, message }
+}
+
+// pi-tui re-renders every component each frame; the cards must serve repeat
+// same-width renders from their line cache and drop it on every state change.
+describe('transcript card render caches', () => {
+ it('tool card: repeat same-width renders return the cached rows', () => {
+ const card = toolCard()
+ const first = card.render(80)
+ expect(card.render(80)).toBe(first)
+ const narrower = card.render(60)
+ expect(narrower).not.toBe(first)
+ expect(card.render(60)).toBe(narrower)
+ })
+
+ it('tool card: result, visibility, and invalidate() each drop the cache', () => {
+ const card = toolCard()
+ const pending = card.render(80)
+ card.updateResult(toolResult('output line'))
+ const settled = card.render(80)
+ expect(settled).not.toBe(pending)
+ expect(settled.join('\n')).toContain('●')
+
+ card.setVisibility('hidden')
+ expect(card.render(80)).toEqual([])
+
+ card.setVisibility('collapsed')
+ const restored = card.render(80)
+ expect(restored).toEqual(settled)
+ expect(restored).not.toBe(settled)
+
+ card.invalidate()
+ expect(card.render(80)).not.toBe(restored)
+ })
+
+ it('context card: caches by width and drops on setExpanded and invalidate()', () => {
+ const card = new ContextCardComponent('workspace-context', 'line one\nline two', 10, palette)
+ const first = card.render(80)
+ expect(card.render(80)).toBe(first)
+
+ // Same width across the mutation, so a hit here would prove a kept cache.
+ card.setExpanded(true)
+ const expanded = card.render(80)
+ expect(expanded).not.toBe(first)
+ expect(card.render(80)).toBe(expanded)
+
+ card.invalidate()
+ const reRendered = card.render(80)
+ expect(reRendered).not.toBe(expanded)
+ expect(reRendered).toEqual(expanded)
+
+ expect(card.render(60)).not.toBe(reRendered)
+ })
+})
diff --git a/packages/ui/tui/tests/tui.snapshot.ts b/packages/ui/tui/tests/tui.snapshot.ts
index 21696153a2..535a992a87 100644
--- a/packages/ui/tui/tests/tui.snapshot.ts
+++ b/packages/ui/tui/tests/tui.snapshot.ts
@@ -62,6 +62,7 @@ const CHECKPOINTS = [
'model-switching',
'errors-and-help',
'disposed-terminal',
+ 'resume-sessions-loading',
'resume-sessions',
'resume-sessions-all-workspaces',
'status-diagnostics',
@@ -981,14 +982,18 @@ describe('TUI terminal-state snapshots', () => {
{ type: 'step/end', seq: 5, time: Date.parse(`${day}T00:00:06Z`), data: { turn: 1, step: 1 } },
{ type: 'turn/end', seq: 6, time: Date.parse(`${day}T00:00:07Z`), data: { turn: 1, reason: { kind: 'completed' } } },
{ type: 'session/title', seq: 7, time: Date.parse(`${day}T00:00:08Z`), data: { title, messageSeqs: [1], source: { kind: 'fallback' } } },
- // A prior pickup, dated well after the work: the picker must still
- // show the work's date, not the pickup's.
- { type: 'session/end-seed', seq: 8, time: Date.parse('2026-07-23T07:59:00.000Z'), data: {} },
],
})
+ const listGate = Promise.withResolvers()
+ // Rows show metadata activity (here the created-at fallback: the fake
+ // store locates no per-session artifact to stat) plus each log's one
+ // batch-folded title; nothing else is read from the logs.
const harness = await setupSnapshot({
sessionPersistence: {
- list: async () => [earlier, elsewhere],
+ list: async () => {
+ await listGate.promise
+ return [earlier, elsewhere]
+ },
load: async id => id === elsewhere.id
? log(elsewhere, 'Other workspace work', '2024-02-02')
: log(earlier, 'Resume selector design', '2024-01-01'),
@@ -996,8 +1001,15 @@ describe('TUI terminal-state snapshots', () => {
}, { columns: 92, rows: 32 })
harness.terminal.send('/resume')
harness.terminal.send('\r')
- // `/resume` scans persistence asynchronously, so the listing renders a tick
- // after submit (the unit suite waits the same way); settle, then flush.
+ // The picker opens as soon as the command dispatches and owns input while
+ // the persistence scan is still pending, rendering a loading placeholder
+ // in place of rows; only the scan is gated, so this settle never lists.
+ await new Promise(resolve => setTimeout(resolve, 60))
+ await harness.terminal.flush()
+ await checkpoint('resume-sessions-loading', harness.terminal, { includeScrollback: true })
+ listGate.resolve(undefined)
+ // With the scan released, the listing renders a tick later (the unit suite
+ // waits the same way); settle, then flush.
await new Promise(resolve => setTimeout(resolve, 60))
await harness.terminal.flush()
await checkpoint('resume-sessions', harness.terminal, { includeScrollback: true })
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 4ecf78d54a..a6bfa8e978 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, rm, utimes, writeFile } from 'node:fs/promises'
import { homedir, tmpdir } from 'node:os'
import { join, resolve } from 'node:path'
import { describe, expect, it, vi } from 'vitest'
@@ -42,7 +42,8 @@ import {
type TuiRuntime,
} from '../src/index.ts'
import { WorkspaceFileSearch } from '../src/chat/file-autocomplete.ts'
-import { ATTRIBUTE_ROLES, brandText, COLOR_ROLES, paletteSpec } from '../src/components/theme.ts'
+import { ResumePicker } from '../src/components/dialogs.ts'
+import { ATTRIBUTE_ROLES, brandText, COLOR_ROLES, createPalette, paletteSpec } from '../src/components/theme.ts'
import {
appendAssistant,
appendUser,
@@ -190,6 +191,7 @@ describe('TUI config', () => {
maxQuestionOptions: 8,
maxModelOptions: 8,
maxResumeOptions: 8,
+ resumeScanConcurrency: 4,
questionDialogWidth: 200,
questionDialogMaxHeight: 20,
modelDialogWidth: 76,
@@ -216,6 +218,7 @@ describe('TUI config', () => {
maxQuestionOptions: 3,
maxModelOptions: 4,
maxResumeOptions: 5,
+ resumeScanConcurrency: 2,
questionDialogWidth: 60,
questionDialogMaxHeight: 14,
modelDialogWidth: 64,
@@ -234,6 +237,7 @@ describe('TUI config', () => {
maxQuestionOptions: 3,
maxModelOptions: 4,
maxResumeOptions: 5,
+ resumeScanConcurrency: 2,
questionDialogWidth: 60,
questionDialogMaxHeight: 14,
modelDialogWidth: 64,
@@ -286,6 +290,23 @@ describe('goodbye message and /resume', () => {
{ type: 'turn/end', seq: 6, time: time + 6, data: { turn: 1, reason } },
{ type: 'session/title', seq: 7, time: time + 7, data: { title, messageSeqs: [1], source: { kind: 'fallback' } } },
]
+ /** Derive the selector's batch title read from a fake per-session readSession. */
+ const titlesViaReadSession = (
+ readSession: (id: SessionId) => Promise<{ session: SessionHeader; events: SessionEvent[] }>,
+ ) => (ids: readonly SessionId[]) => Promise.all(ids.map(async (sessionId) => {
+ try {
+ const snapshot = await readSession(sessionId)
+ const titleEvent = snapshot.events.findLast(event => event.type === 'session/title')
+ const title = titleEvent?.type === 'session/title' ? { title: titleEvent.data.title } : undefined
+ return {
+ sessionId,
+ status: 'fulfilled',
+ value: { session: snapshot.session, ...title === undefined ? {} : { title } },
+ }
+ } catch (reason) {
+ return { sessionId, status: 'rejected', reason }
+ }
+ }))
it('prints the host goodbye message on exit', async () => {
const result = await setup({
@@ -443,7 +464,7 @@ describe('goodbye message and /resume', () => {
result.terminal.send('\x1b[6~')
await tick()
const rendered = result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session'))
- expect(rendered).toContain('❯ Paged 3')
+ expect(rendered).toContain('❯ Paged 5')
result.terminal.send('\x1b[5~')
await tick()
expect(result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session')))
@@ -476,26 +497,128 @@ describe('goodbye message and /resume', () => {
await dispose(result)
})
- it.each([
- [{ kind: 'aborted' }, 'cancelled'],
- [{ kind: 'error', step: 1, message: 'failed' }, 'error'],
- [{ kind: 'disposed' }, 'disposed'],
- [{ kind: 'max-tokens' }, 'max tokens'],
- [{ kind: 'interrupted' }, 'interrupted'],
- [{ kind: 'future-result' } as unknown as TurnEndReason, 'unknown result'],
- ] as const)('renders the last turn result %s', async (reason, label) => {
- const target = header(`turn-${label}`, 10, '/workspace')
+ it('resolves titles through the projection cache without scanning logs', async () => {
+ const current = header('main-session', 5, '/workspace')
+ const cachedRow = header('cached-title', 40, '/workspace')
+ const rowless = header('rowless-title', 30, '/workspace')
+ const untitled = header('untitled-title', 20, '/workspace')
+ const broken = header('broken-title', 10, '/workspace')
+ let coldReads = 0
const result = await setup({
cwd: '/workspace',
- sessionPersistence: {
- list: async () => [target],
- load: async () => ({ meta: target, events: resumeEvents(`Turn ${label}`, 'deepseek-official', 100, reason) }),
+ async configureContext(ctx) {
+ ctx.provide('tools', { get: () => undefined } as never)
+ ctx.provide('sessionQuery', {
+ listSessions: () => Promise.resolve([
+ { header: current, live: true, persisted: false },
+ { header: cachedRow, live: false, persisted: true },
+ { header: rowless, live: false, persisted: true },
+ { header: untitled, live: false, persisted: true },
+ { header: broken, live: false, persisted: true },
+ ]),
+ readTitleSnapshots: () => Promise.reject(new Error('the ladder must not scan logs')),
+ } as never)
+ ctx.provide('sessionProjections', {
+ snapshot: () => ({ asOfSeq: 0, values: { title: 'Live projected' } }),
+ } as never)
+ ctx.provide('sessionProjectionCache', {
+ cachedSnapshot: (meta: SessionHeader) => {
+ if (meta.id === cachedRow.id) return { asOfSeq: 3, values: { title: 'Cached projected' } }
+ if (meta.id === untitled.id) return { asOfSeq: 3, values: { title: null } }
+ if (meta.id === rowless.id) return { asOfSeq: 3, values: {} }
+ return undefined
+ },
+ coldSnapshot: async (id: SessionId) => {
+ coldReads += 1
+ if (id === broken.id) throw new Error('checkpoint restore failed')
+ return { asOfSeq: 5, values: { title: 'Cold projected' } }
+ },
+ } as never)
},
})
result.terminal.send('/resume')
result.terminal.send('\r')
await tick(); await tick()
- expect(result.terminal.output).toContain(`turn 1: ${label}`)
+ expect(result.terminal.output).toContain('Live projected')
+ expect(result.terminal.output).toContain('Cached projected')
+ expect(result.terminal.output).toContain('Cold projected')
+ expect(result.terminal.output).toContain('Untitled session')
+ expect(result.terminal.output).toContain('Unreadable session')
+ expect(result.terminal.output).toContain('checkpoint restore failed')
+ expect(result.terminal.output).not.toContain('the ladder must not scan logs')
+ expect(coldReads).toBe(2)
+ await dispose(result)
+ })
+
+ it('shows a live row untitled when the cache is mounted without the registry', async () => {
+ const current = header('main-session', 5, '/workspace')
+ const result = await setup({
+ cwd: '/workspace',
+ async configureContext(ctx) {
+ ctx.provide('tools', { get: () => undefined } as never)
+ ctx.provide('sessionQuery', {
+ listSessions: () => Promise.resolve([{ header: current, live: true, persisted: false }]),
+ } as never)
+ ctx.provide('sessionProjectionCache', {
+ cachedSnapshot: () => undefined,
+ coldSnapshot: async () => ({ asOfSeq: -1, values: {} }),
+ } as never)
+ },
+ })
+ result.terminal.send('/resume')
+ result.terminal.send('\r')
+ await tick(); await tick()
+ expect(result.terminal.output).toContain('Untitled session')
+ await dispose(result)
+ })
+
+ it('orders rows by artifact mtime without reading logs for the timestamp', async () => {
+ const dir = await mkdtemp(join(tmpdir(), 'dsh-resume-mtime-'))
+ const stale = join(dir, 'stale.log')
+ const fresh = join(dir, 'fresh.log')
+ await writeFile(stale, 'x')
+ await writeFile(fresh, 'x')
+ await utimes(stale, new Date(1000), new Date(60_000))
+ await utimes(fresh, new Date(1000), new Date(120_000))
+ // Creation order contradicts mtime order, so the sort proves its source.
+ const createdLate = header('created-late-touched-early', 50, '/workspace')
+ const createdEarly = header('created-early-touched-late', 40, '/workspace')
+ const gone = header('artifact-gone', 30, '/workspace')
+ const goneTwin = header('artifact-gone-twin', 30, '/workspace')
+ const paths = new Map([
+ [createdLate.id, stale],
+ [createdEarly.id, fresh],
+ [gone.id, join(dir, 'missing.log')],
+ [goneTwin.id, join(dir, 'missing-twin.log')],
+ ])
+ const titles = new Map([
+ [createdLate.id, 'Touched early'],
+ [createdEarly.id, 'Touched late'],
+ [gone.id, 'Artifact gone'],
+ [goneTwin.id, 'Artifact gone twin'],
+ ])
+ const result = await setup({
+ cwd: '/workspace',
+ sessionPersistence: {
+ list: async () => [createdLate, createdEarly, gone, goneTwin],
+ load: async id => ({
+ meta: [createdLate, createdEarly, gone, goneTwin].find(target => target.id === id)!,
+ events: resumeEvents(titles.get(id)!),
+ }),
+ locate: meta => ({ kind: 'jsonl', path: paths.get(meta.id)! }),
+ },
+ })
+ result.terminal.send('/resume')
+ result.terminal.send('\r')
+ await tick(); await tick()
+ const rendered = result.terminal.output.slice(result.terminal.output.lastIndexOf('Resume session'))
+ expect(rendered).toContain(new Date(120_000).toISOString())
+ expect(rendered.indexOf('Touched late')).toBeLessThan(rendered.indexOf('Touched early'))
+ // A missing artifact falls back to the header's creation time; equal
+ // times tie-break by id.
+ expect(rendered).toContain(new Date(gone.createdAt).toISOString())
+ expect(rendered.indexOf('artifact-gone')).toBeLessThan(rendered.indexOf('artifact-gone-twin'))
+ await rm(dir, { recursive: true, force: true })
await dispose(result)
})
@@ -529,6 +652,7 @@ describe('goodbye message and /resume', () => {
queryCtx = child
child.provide('sessionQuery', {
listSessions: async () => { listCalls++; return [] },
+ readTitleSnapshots: async () => [],
} as never)
},
})
@@ -559,16 +683,18 @@ describe('goodbye message and /resume', () => {
cwd: '/workspace',
async configureContext(ctx) {
ctx.provide('tools', { get: () => undefined } as never)
+ const readSession = () => Promise.resolve({
+ session: target,
+ events: resumeEvents('Query-only persisted session'),
+ })
ctx.provide('sessionQuery', {
listSessions: () => Promise.resolve([{
header: target,
live: false,
persisted: true,
}]),
- readSession: () => Promise.resolve({
- session: target,
- events: resumeEvents('Query-only persisted session'),
- }),
+ readSession,
+ readTitleSnapshots: titlesViaReadSession(readSession),
} as never)
},
})
@@ -606,11 +732,17 @@ describe('goodbye message and /resume', () => {
ctx.provide('tools', { get: () => undefined } as never)
ctx.provide('sessionQuery', {
listSessions: () => ++calls === 1 ? first.promise : Promise.resolve([]),
+ readTitleSnapshots: async () => [],
} as never)
},
})
result.terminal.send('/resume')
result.terminal.send('\r')
+ // The loading picker owns input as soon as /resume runs, so the second
+ // scan starts after dismissing the first overlay, not by typing a second
+ // slash command over it.
+ result.terminal.send('\u001B')
+ await tick()
result.terminal.send('/resume')
result.terminal.send('\r')
await tick()
@@ -641,6 +773,127 @@ describe('goodbye message and /resume', () => {
expect(result.terminal.stopped).toBeGreaterThan(0)
})
+ it('clears the still-loading error the moment scanned rows arrive', () => {
+ const picker = new ResumePicker(
+ undefined,
+ 10,
+ '/workspace',
+ () => 30,
+ createPalette(false),
+ () => {},
+ () => {},
+ )
+ picker.focused = true
+ picker.handleInput('\r')
+ expect(picker.render(80).join('\n')).toContain('Sessions are still loading.')
+ picker.setCandidates([])
+ const rendered = picker.render(80).join('\n')
+ expect(rendered).not.toContain('Sessions are still loading.')
+ expect(rendered).toContain('No matching sessions.')
+ })
+
+ it('aborts an in-flight scan when the loading picker is dismissed', async () => {
+ const listing = Promise.withResolvers()
+ let scanSignal: AbortSignal | undefined
+ let projections = 0
+ const result = await setup({
+ async configureContext(ctx) {
+ ctx.provide('tools', { get: () => undefined } as never)
+ ctx.provide('sessionQuery', {
+ listSessions: (signal?: AbortSignal) => { scanSignal = signal; return listing.promise },
+ readTitleSnapshots: async () => { projections += 1; return [] },
+ } as never)
+ },
+ })
+ result.terminal.send('/resume')
+ result.terminal.send('\r')
+ await tick()
+ expect(result.terminal.output).toContain('Loading sessions…')
+ result.terminal.send('\u001B')
+ await tick()
+ expect(scanSignal?.aborted).toBe(true)
+ // A signal-ignoring backend can still fulfill after dismissal: the stale
+ // scan must neither read titles nor report.
+ listing.resolve([])
+ await tick()
+ expect(projections).toBe(0)
+ expect(result.terminal.output).not.toContain('Resume session scan failed')
+ await dispose(result)
+ })
+
+ it('drops a title read that settles after the picker was dismissed', async () => {
+ const projecting = Promise.withResolvers()
+ const result = await setup({
+ async configureContext(ctx) {
+ ctx.provide('tools', { get: () => undefined } as never)
+ ctx.provide('sessionQuery', {
+ listSessions: async () => [],
+ readTitleSnapshots: () => projecting.promise,
+ } as never)
+ },
+ })
+ result.terminal.send('/resume')
+ result.terminal.send('\r')
+ await tick()
+ result.terminal.send('\u001B')
+ await tick()
+ projecting.resolve([])
+ await tick()
+ expect(result.terminal.output).not.toContain('(0 of 0)')
+ expect(result.terminal.output).not.toContain('Resume session scan failed')
+ await dispose(result)
+ })
+
+ it('closes the loading picker and reports a scan that fails after listing', async () => {
+ const target = header('titles-explode', 10, '/workspace')
+ const result = await setup({
+ async configureContext(ctx) {
+ ctx.provide('tools', { get: () => undefined } as never)
+ ctx.provide('sessionQuery', {
+ listSessions: () => Promise.resolve([{ header: target, live: false, persisted: true }]),
+ readTitleSnapshots: () => Promise.reject(new Error('titles exploded')),
+ } as never)
+ },
+ })
+ result.terminal.send('/resume')
+ result.terminal.send('\r')
+ await tick(); await tick()
+ expect(result.terminal.output).toContain('Resume session scan failed: titles exploded')
+ expect(result.terminal.stopped).toBe(0)
+ await dispose(result)
+ })
+
+ it('opens a loading picker immediately and swaps in the scanned rows', async () => {
+ const target = header('late-listing', 10, '/workspace')
+ const listing = Promise.withResolvers()
+ const result = await setup({
+ cwd: '/workspace',
+ async configureContext(ctx) {
+ ctx.provide('tools', { get: () => undefined } as never)
+ const readSession = () => Promise.resolve({
+ session: target,
+ events: resumeEvents('Late listing'),
+ })
+ ctx.provide('sessionQuery', {
+ listSessions: () => listing.promise,
+ readSession,
+ readTitleSnapshots: titlesViaReadSession(readSession),
+ } as never)
+ },
+ })
+ result.terminal.send('/resume')
+ result.terminal.send('\r')
+ await tick()
+ expect(result.terminal.output).toContain('Loading sessions…')
+ result.terminal.send('\r')
+ await tick()
+ expect(result.terminal.output).toContain('Sessions are still loading.')
+ listing.resolve([{ header: target, live: false, persisted: true }])
+ await tick(); await tick()
+ expect(result.terminal.output).toContain('Late listing')
+ await dispose(result)
+ })
+
it('drops loaded selector summaries when the TUI disposed during log reads', async () => {
const target = header('dispose-during-load', 10, '/workspace')
const loading = Promise.withResolvers<{ meta: SessionHeader; events: SessionEvent[] }>()
@@ -680,11 +933,12 @@ describe('goodbye message and /resume', () => {
result.terminal.send('\r')
await tick(); await tick()
expect(result.terminal.output).toContain('Missing adapter')
- expect(result.terminal.output).toContain('absent-provider/model-1')
+ // Rows carry no route: availability surfaces only at Enter-time preflight.
+ expect(result.terminal.output).not.toContain('absent-provider/model-1')
expect(result.terminal.output).toContain('Unreadable session')
result.terminal.send('Missing adapter')
result.terminal.send('\r')
- await tick()
+ await tick(); await tick()
expect(result.terminal.output).toContain('route is currently unavailable')
expect(result.terminal.stopped).toBe(0)
await dispose(result)
@@ -698,16 +952,18 @@ describe('goodbye message and /resume', () => {
handoffResume: handoff,
async configureContext(ctx) {
ctx.provide('tools', { get: () => undefined } as never)
+ const readSession = () => Promise.resolve({
+ session: target,
+ events: resumeEvents('Live target'),
+ })
ctx.provide('sessionQuery', {
listSessions: () => Promise.resolve([{
header: target,
live: true,
persisted: true,
}]),
- readSession: () => Promise.resolve({
- session: target,
- events: resumeEvents('Live target'),
- }),
+ readSession,
+ readTitleSnapshots: titlesViaReadSession(readSession),
} as never)
},
})
@@ -722,10 +978,45 @@ describe('goodbye message and /resume', () => {
await dispose(result)
})
+ it('rechecks record liveness at preflight rather than trusting the listed row', async () => {
+ const target = header('turns-live', 10, '/workspace')
+ const handoff = vi.fn>()
+ let listings = 0
+ const result = await setup({
+ cwd: '/workspace',
+ handoffResume: handoff,
+ async configureContext(ctx) {
+ ctx.provide('tools', { get: () => undefined } as never)
+ const readSession = () => Promise.resolve({
+ session: target,
+ events: resumeEvents('Turns live'),
+ })
+ ctx.provide('sessionQuery', {
+ listSessions: () => Promise.resolve([{
+ header: target,
+ live: ++listings > 1,
+ persisted: true,
+ }]),
+ readSession,
+ readTitleSnapshots: titlesViaReadSession(readSession),
+ } as never)
+ },
+ })
+ result.terminal.send('/resume')
+ result.terminal.send('\r')
+ await tick(); await tick()
+ result.terminal.send('Turns live')
+ result.terminal.send('\r')
+ await tick(); await tick()
+ expect(result.terminal.output).toContain('session is already live in this runtime')
+ expect(handoff).not.toHaveBeenCalled()
+ await dispose(result)
+ })
+
it('falls back to assistant provenance and header creation time for sparse logs', async () => {
const assistantOnly = header('assistant-route', 20, '/workspace')
const empty = header('empty-log', 10, '/workspace')
- const events = resumeEvents('Assistant route', 'deepseek-official')
+ const events = resumeEvents('Assistant route', 'absent-provider')
.filter(event => event.type !== 'request/header')
.map((event, seq) => ({ ...event, seq })) as SessionEvent[]
const result = await setup({
@@ -740,8 +1031,23 @@ describe('goodbye message and /resume', () => {
result.terminal.send('/resume')
result.terminal.send('\r')
await tick(); await tick()
- expect(result.terminal.output).toContain('deepseek-official/model-1')
+ // Without a persisted artifact to stat, listing falls back to creation time.
expect(result.terminal.output).toContain(new Date(empty.createdAt).toISOString())
+ // The preflight route fold falls back to assistant provenance when the
+ // log carries no request header.
+ result.terminal.send('Assistant route')
+ result.terminal.send('\r')
+ await tick(); await tick()
+ expect(result.terminal.output).toContain('route is currently unavailable')
+ // The failed preflight closed the picker; reopen and pick the routeless
+ // log, which passes the route check — only the absent host stops it.
+ result.terminal.send('/resume')
+ result.terminal.send('\r')
+ await tick(); await tick()
+ result.terminal.send('empty-log')
+ result.terminal.send('\r')
+ await tick(); await tick()
+ expect(result.terminal.output).toContain('cannot hand it off in place')
await dispose(result)
})
@@ -828,12 +1134,14 @@ describe('goodbye message and /resume', () => {
async configureContext(ctx) {
ctx.provide('tools', { get: () => undefined } as never)
ctx.on('session/flush', flush)
+ const readSession = () => Promise.resolve({
+ session: target,
+ events: resumeEvents('Dispose during preflight'),
+ })
ctx.provide('sessionQuery', {
listSessions: () => ++listings === 1 ? Promise.resolve([record]) : secondListing.promise,
- readSession: () => Promise.resolve({
- session: target,
- events: resumeEvents('Dispose during preflight'),
- }),
+ readSession,
+ readTitleSnapshots: titlesViaReadSession(readSession),
} as never)
},
})
@@ -860,16 +1168,18 @@ describe('goodbye message and /resume', () => {
handoffResume: handoff,
async configureContext(ctx) {
ctx.provide('tools', { get: () => undefined } as never)
+ const readSession = () => Promise.resolve({
+ session: target,
+ events: resumeEvents('Query without persistence'),
+ })
ctx.provide('sessionQuery', {
listSessions: () => Promise.resolve([{
header: target,
live: false,
persisted: true,
}]),
- readSession: () => Promise.resolve({
- session: target,
- events: resumeEvents('Query without persistence'),
- }),
+ readSession,
+ readTitleSnapshots: titlesViaReadSession(readSession),
} as never)
},
})
@@ -1265,10 +1575,6 @@ describe('pi-tui chat lifecycle and transcript', () => {
})
expect(result.terminal.output).toContain('Goal restored (active) with automatic continuation disarmed')
expect(result.terminal.output).toContain('/goal resume')
- result.terminal.send('/resume')
- result.terminal.send('\r')
- await tick(); await tick()
- expect(result.terminal.output).toContain('goal active')
await dispose(result)
})
diff --git a/packages/ui/tui/tsconfig.json b/packages/ui/tui/tsconfig.json
index eddddcc704..06a36adc28 100644
--- a/packages/ui/tui/tsconfig.json
+++ b/packages/ui/tui/tsconfig.json
@@ -32,6 +32,12 @@
{
"path": "../../session-persistence/session-persistence"
},
+ {
+ "path": "../../session-projection/session-projection"
+ },
+ {
+ "path": "../../session-projection/session-projection-cache"
+ },
{
"path": "../../session-query/session-query"
},
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5e27760b0d..5f109f8c62 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -276,9 +276,6 @@ importers:
'@deepseek-ai/dsh-host-webserver':
specifier: workspace:^
version: link:../../packages/host/webserver
- '@deepseek-ai/dsh-invariants':
- specifier: workspace:^
- version: link:../../packages/support/invariants
'@deepseek-ai/dsh-llm':
specifier: workspace:^
version: link:../../packages/llm/llm
@@ -3005,6 +3002,9 @@ importers:
packages/fs/tool-fs-search:
dependencies:
+ '@vscode/ripgrep':
+ specifier: ^1.18.0
+ version: 1.18.0
schemastery:
specifier: ^3.18.0
version: link:../../../vendor/schemastery
@@ -3012,12 +3012,6 @@ importers:
'@deepseek-ai/dsh-agent':
specifier: workspace:^
version: link:../../core/agent
- '@deepseek-ai/dsh-bash':
- specifier: workspace:^
- version: link:../../bash/bash
- '@deepseek-ai/dsh-bash-local':
- specifier: workspace:^
- version: link:../../bash/bash-local
'@deepseek-ai/dsh-invariants':
specifier: workspace:^
version: link:../../support/invariants
@@ -3033,6 +3027,9 @@ importers:
'@deepseek-ai/dsh-spill':
specifier: workspace:^
version: link:../../spill/spill
+ '@deepseek-ai/dsh-subprocess':
+ specifier: workspace:^
+ version: link:../../subprocess/subprocess
'@deepseek-ai/dsh-subprocess-local':
specifier: workspace:^
version: link:../../subprocess/subprocess-local
@@ -5881,6 +5878,12 @@ importers:
'@deepseek-ai/dsh-session-persistence':
specifier: workspace:^
version: link:../../session-persistence/session-persistence
+ '@deepseek-ai/dsh-session-projection':
+ specifier: workspace:^
+ version: link:../../session-projection/session-projection
+ '@deepseek-ai/dsh-session-projection-cache':
+ specifier: workspace:^
+ version: link:../../session-projection/session-projection-cache
'@deepseek-ai/dsh-session-query':
specifier: workspace:^
version: link:../../session-query/session-query
@@ -9198,6 +9201,69 @@ packages:
'@vitest/utils@4.1.8':
resolution: {integrity: sha512-uOJamYALNhfJ6iolExyQM40yIQwDqYnkKtQ5VCiSe17E33H0aQ/u+1GlRuz4LZBk6Mm3sg90G9hEbmEt37C1Zg==}
+ '@vscode/ripgrep-darwin-arm64@1.18.0':
+ resolution: {integrity: sha512-r3ktHSvbFycQNF6sl7sNDPocpsI7J+mEzh1IaZFkY0spm3k2Z9t8hPAeOK7+p0l6p6/swkQC14XWX01low+94Q==}
+ cpu: [arm64]
+ os: [darwin]
+
+ '@vscode/ripgrep-darwin-x64@1.18.0':
+ resolution: {integrity: sha512-25b4gWbL138dGuQU244ebCKKc0q05ULBMoFSz9oAEUHNeqK/lOJViDS7DRvbDazzAzSEdan391Znks/R5mkaTQ==}
+ cpu: [x64]
+ os: [darwin]
+
+ '@vscode/ripgrep-linux-arm64@1.18.0':
+ resolution: {integrity: sha512-lQ/5zTG++U0E3IhVgS4EPTTn/U4okncaRMM5GOFfOYZywS4nuD31GhkHbNYlDk5CuDC68+hYJ0/eQeyCKJDA+g==}
+ cpu: [arm64]
+ os: [linux]
+
+ '@vscode/ripgrep-linux-arm@1.18.0':
+ resolution: {integrity: sha512-GDAvufNDHu8zqLEmXstalQF0Wh6wQvdsBi/Vg3Yi3CK4a8XoFXqqXVEHEZ9xQz3t0NfoSEc9JbvK9DDS6FxyxQ==}
+ cpu: [arm]
+ os: [linux]
+
+ '@vscode/ripgrep-linux-ia32@1.18.0':
+ resolution: {integrity: sha512-YWLkSUtFd4Jh5EepIhA9RJSfv3uMAVMo+2rBIGHPBnvgLrZciIs2cDKei1/p6Wc/aCzUoHyMAg2R6tw4ZCBKGg==}
+ cpu: [ia32]
+ os: [linux]
+
+ '@vscode/ripgrep-linux-ppc64@1.18.0':
+ resolution: {integrity: sha512-quXVY8fwQ8O/lvU1yrSqSl3jlUzysRSb+AfUfCL/tRtphxsKlFvPAejryZ6vg4Bgvn8XL74xb4qMCDmWgYrT5w==}
+ cpu: [ppc64]
+ os: [linux]
+
+ '@vscode/ripgrep-linux-riscv64@1.18.0':
+ resolution: {integrity: sha512-f5kBQBrWfQt8Q7OhSORuNDei5dkYagBj3y4jImSUXGMy8B/Ke7SltSRcUtjPv166FAFfHCAmWuZp3+cWnX2/Vw==}
+ cpu: [riscv64]
+ os: [linux]
+
+ '@vscode/ripgrep-linux-s390x@1.18.0':
+ resolution: {integrity: sha512-rTOcJFGGcl2c07RUOWUo4U1ndnemKhY6A9hnMB18uk7jSgJc0d/QLBGWMWpumdtoJtpizn/wIv5mXIisJukusQ==}
+ cpu: [s390x]
+ os: [linux]
+
+ '@vscode/ripgrep-linux-x64@1.18.0':
+ resolution: {integrity: sha512-mQ3bVrUpnD2vs7QT0vX90Lt0cnUq467uFtEktIdsJJmW296RoSULRGqWgzG1AKxyBpNDD6l4ZO4qKf6SgyC23Q==}
+ cpu: [x64]
+ os: [linux]
+
+ '@vscode/ripgrep-win32-arm64@1.18.0':
+ resolution: {integrity: sha512-vfTIjq1OHnzUjxZcHVQAMbnggp8dpGf+0QKFOZHwWPqFwXxQC8eCWM+5NUdoJ6yrElCeMzoUTXoK/LdZaniB+Q==}
+ cpu: [arm64]
+ os: [win32]
+
+ '@vscode/ripgrep-win32-ia32@1.18.0':
+ resolution: {integrity: sha512-//rfAE+BOw5AC2EMmepmiE36jUuevtQYNQqqlw1s3m9FlRxjxEut97RkRPHAu9BG4mSojatZx+kXZXNdyI9caQ==}
+ cpu: [ia32]
+ os: [win32]
+
+ '@vscode/ripgrep-win32-x64@1.18.0':
+ resolution: {integrity: sha512-KNPvtElldqILHdnAetujPaowkNbpqJy3ssIGGN6F6Kve9Qi+nNLI2DN01O83JjCEVQbCzl8Ov3QZ9Eov3BR8Dg==}
+ cpu: [x64]
+ os: [win32]
+
+ '@vscode/ripgrep@1.18.0':
+ resolution: {integrity: sha512-ns5lWe44tSfbTMbVUsyB+I1819PVSw4AdpgK0RNkzfWfwy6+3IUNSxwSrfTno1/oWaS/hERNz+XLWVyga2aJBQ==}
+
'@vue/compiler-core@3.5.39':
resolution: {integrity: sha512-16KBTEXAJCpDr0mwlw+AZyhu8iyC7R3S2vBwsI7QnWJU6X3WKc9VKeNEZpiMdZ569qWhz9574L3vV55qRL0Vtw==}
@@ -14258,6 +14324,57 @@ snapshots:
convert-source-map: 2.0.0
tinyrainbow: 3.1.0
+ '@vscode/ripgrep-darwin-arm64@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-darwin-x64@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-linux-arm64@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-linux-arm@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-linux-ia32@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-linux-ppc64@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-linux-riscv64@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-linux-s390x@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-linux-x64@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-win32-arm64@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-win32-ia32@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep-win32-x64@1.18.0':
+ optional: true
+
+ '@vscode/ripgrep@1.18.0':
+ optionalDependencies:
+ '@vscode/ripgrep-darwin-arm64': 1.18.0
+ '@vscode/ripgrep-darwin-x64': 1.18.0
+ '@vscode/ripgrep-linux-arm': 1.18.0
+ '@vscode/ripgrep-linux-arm64': 1.18.0
+ '@vscode/ripgrep-linux-ia32': 1.18.0
+ '@vscode/ripgrep-linux-ppc64': 1.18.0
+ '@vscode/ripgrep-linux-riscv64': 1.18.0
+ '@vscode/ripgrep-linux-s390x': 1.18.0
+ '@vscode/ripgrep-linux-x64': 1.18.0
+ '@vscode/ripgrep-win32-arm64': 1.18.0
+ '@vscode/ripgrep-win32-ia32': 1.18.0
+ '@vscode/ripgrep-win32-x64': 1.18.0
+
'@vue/compiler-core@3.5.39':
dependencies:
'@babel/parser': 7.29.7
diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts
index 707c30ff70..f31cca6879 100644
--- a/scripts/gen-third-party-notices.spec.ts
+++ b/scripts/gen-third-party-notices.spec.ts
@@ -1,7 +1,8 @@
-import { readdirSync, readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { tmpdir } from 'node:os'
import { describe, expect, it } from 'vitest'
-import { collectPythonDependencies, isPermissive, type Manifest, manifestPatterns, parsePyprojectRequirements, parseVendoredRows, render, tierExternalDeps } from './gen-third-party-notices.ts'
+import { collectPythonDependencies, isPermissive, type Manifest, manifestPatterns, parsePyprojectRequirements, parseVendoredRows, render, tierExternalDeps, virtualManifest } from './gen-third-party-notices.ts'
const root = resolve(import.meta.dirname, '..')
@@ -63,6 +64,56 @@ describe('tierExternalDeps', () => {
})
})
+describe('virtualManifest', () => {
+ it('resolves a manifest from an ordinary prefix-matching store directory', () => {
+ const root = mkdtempSync(join(tmpdir(), 'dsh-notices-prefix-'))
+ try {
+ const name = '@scope/pkg'
+ const version = '1.0.0'
+ const store = join(root, 'store')
+ const manifestDir = join(store, `${name.replace('/', '+')}@${version}`, 'node_modules', name)
+ mkdirSync(manifestDir, { recursive: true })
+ writeFileSync(join(manifestDir, 'package.json'), JSON.stringify({ name, version, license: 'MIT' }))
+
+ expect(virtualManifest(store, name)).toMatchObject({ name, version, license: 'MIT' })
+ } finally {
+ rmSync(root, { recursive: true, force: true })
+ }
+ })
+
+ it('falls back to a content scan when pnpm 11 truncates the store directory name', () => {
+ const root = mkdtempSync(join(tmpdir(), 'dsh-notices-truncated-'))
+ try {
+ const name = '@scope/pkg'
+ const version = '2.0.0'
+ const store = join(root, 'store')
+ // The truncated name no longer starts with `@scope+pkg@`, so only the
+ // whole-store content scan can find the package.
+ const manifestDir = join(store, '@scope+pkg_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f', 'node_modules', name)
+ mkdirSync(manifestDir, { recursive: true })
+ writeFileSync(join(manifestDir, 'package.json'), JSON.stringify({ name, version, license: 'Apache-2.0' }))
+
+ expect(virtualManifest(store, name)).toMatchObject({ name, version, license: 'Apache-2.0' })
+ } finally {
+ rmSync(root, { recursive: true, force: true })
+ }
+ })
+
+ it('returns undefined when neither the prefix nor the content scan finds the package', () => {
+ const root = mkdtempSync(join(tmpdir(), 'dsh-notices-miss-'))
+ try {
+ const store = join(root, 'store')
+ const other = join(store, 'other-pkg@1.0.0', 'node_modules', 'other-pkg')
+ mkdirSync(other, { recursive: true })
+ writeFileSync(join(other, 'package.json'), JSON.stringify({ name: 'other-pkg', version: '1.0.0' }))
+
+ expect(virtualManifest(store, '@scope/missing')).toBeUndefined()
+ } finally {
+ rmSync(root, { recursive: true, force: true })
+ }
+ })
+})
+
describe('parseVendoredRows', () => {
it('reads the committed vendor manifest table', () => {
const rows = parseVendoredRows(readFileSync(resolve(root, 'vendor/README.md'), 'utf8'))
diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts
index 5306f9a003..6b790829d5 100644
--- a/scripts/gen-third-party-notices.ts
+++ b/scripts/gen-third-party-notices.ts
@@ -141,15 +141,22 @@ function workspaceMembers(rel: string): string[] {
return declared.map(member => String(member))
}
-/** Every workspace manifest, keyed by path, plus the set of workspace package names. */
+/**
+ * Every workspace manifest, keyed by repository-relative path, plus the set of
+ * workspace package names. Paths are normalized to `/` at ingestion: Node's
+ * `fs.globSync` returns OS-native separators, and the area matching in
+ * `tierExternalDeps` compares `/`-suffixed prefixes, so Windows backslashes
+ * would silently push dev-area manifests into the runtime tier.
+ */
function loadWorkspaceManifests(): { manifests: Map; names: Set } {
const patterns = manifestPatterns(workspaceMembers('pnpm-workspace.yaml'), workspaceMembers('native/landlock-run/pnpm-workspace.yaml'))
const manifests = new Map()
const names = new Set()
for (const pattern of patterns) {
for (const path of globSync(pattern, { cwd: root })) {
- const manifest = readManifest(path)
- manifests.set(path, manifest)
+ const normalized = path.replaceAll('\\', '/')
+ const manifest = readManifest(normalized)
+ manifests.set(normalized, manifest)
if (manifest.name !== undefined) names.add(manifest.name)
}
}
@@ -157,6 +164,35 @@ function loadWorkspaceManifests(): { manifests: Map; names: Se
return { manifests, names }
}
+type VirtualManifest = Manifest & { license?: string; repository?: string | { url?: string }; homepage?: string }
+
+/**
+ * Resolve one package's manifest inside a pnpm virtual store. The prefix scan
+ * matches ordinary `@scope+name@version` directory names; pnpm 11 truncates
+ * long names (a peer-suffixed name past the length limit becomes
+ * `_`), so a content scan falls back over the whole store when
+ * the prefix misses.
+ *
+ * @param virtual - the `.pnpm` virtual store directory to scan.
+ * @param name - the external package name, exactly as `node_modules` spells it.
+ * @returns the parsed manifest, or `undefined` when neither the prefix match
+ * nor the content scan finds the package's `package.json`.
+ */
+export function virtualManifest(virtual: string, name: string): VirtualManifest | undefined {
+ const prefix = `${name.replace('/', '+')}@`
+ const entry = readdirSync(virtual).find(dir => dir.startsWith(prefix))
+ if (entry !== undefined) {
+ return JSON.parse(readFileSync(resolve(virtual, entry, 'node_modules', name, 'package.json'), 'utf8')) as VirtualManifest
+ }
+ for (const dir of readdirSync(virtual)) {
+ const candidate = resolve(virtual, dir, 'node_modules', name, 'package.json')
+ if (existsSync(candidate)) {
+ return JSON.parse(readFileSync(candidate, 'utf8')) as VirtualManifest
+ }
+ }
+ return undefined
+}
+
/** License and repository URL for an installed external package, from the pnpm store. */
function installedMetadata(name: string): { license: string; repo: string } {
const override = OVERRIDES[name]
@@ -171,11 +207,8 @@ function installedMetadata(name: string): { license: string; repo: string } {
}
const virtual = resolve(root, store, '.pnpm')
if (!existsSync(virtual)) continue
- const prefix = `${name.replace('/', '+')}@`
- const entry = readdirSync(virtual).find(dir => dir.startsWith(prefix))
- if (entry === undefined) continue
- manifest = JSON.parse(readFileSync(resolve(virtual, entry, 'node_modules', name, 'package.json'), 'utf8')) as typeof manifest
- break
+ manifest = virtualManifest(virtual, name)
+ if (manifest !== undefined) break
}
const license = override?.license ?? manifest?.license
const rawRepo = typeof manifest?.repository === 'string' ? manifest.repository : manifest?.repository?.url ?? manifest?.homepage
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index d339be6b7f..1d214b6e8e 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -18,8 +18,6 @@ import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
import GoalService from '@deepseek-ai/dsh-goal'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
-import { BashExecutor } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
import LocalBashExecutor from '@deepseek-ai/dsh-bash-local'
import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
@@ -60,44 +58,6 @@ import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
const root = resolve(import.meta.dirname, '..')
const OUT = 'docs/tool-catalog.md'
-const CATALOG_RG_PROBE_COMMAND = 'command -v rg >/dev/null 2>&1'
-
-/**
- * Minimal bash service for harvesting `dsh-tool-fs-search` schemas. The search
- * plugin now probes `rg` at registration time, but the generated catalog must
- * remain independent of the host PATH and never execute a real search.
- */
-class CatalogSearchBashExecutor extends BashExecutor {
- override resolve(request: BashExecRequest): BashExecSpec {
- return {
- command: request.command,
- workdir: request.workdir ?? root,
- timeoutMs: request.timeoutMs ?? 60_000,
- stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
- signal: request.signal,
- sandboxPolicy: request.sandboxPolicy,
- }
- }
-
- override run(spec: BashExecSpec): Promise {
- if (spec.command !== CATALOG_RG_PROBE_COMMAND) {
- throw new Error(`gen-tool-catalog: unexpected search bash command during schema harvest: ${spec.command}`)
- }
- return Promise.resolve({
- exitCode: 0,
- signal: null,
- timedOut: false,
- aborted: false,
- timeoutMs: spec.timeoutMs,
- stdout: { text: '', truncated: false },
- stderr: { text: '', truncated: false },
- })
- }
-
- override start(): BashProcess {
- throw new Error('gen-tool-catalog: search schema harvest must not start background processes')
- }
-}
/**
* Register the descriptor needed to mount schema-producing consumers. Declares
@@ -297,19 +257,19 @@ const TOOL_PACKAGES: ToolPackage[] = [
pkg: '@deepseek-ai/dsh-tool-fs-search',
dir: 'tool-fs-search',
source: 'packages/fs/tool-fs-search/src/index.ts',
- requires: ['ctx.tools', 'ctx.bash', 'ctx.systemPrompt'],
+ requires: ['ctx.tools', 'ctx.subprocess', 'ctx.systemPrompt'],
writes: ['tool/call', 'tool/result'],
async mount(ctx) {
- // The tools inject `bash` (search executes fixed `rg` commands through
- // the executor seam, not ctx.fs). Use a catalog-only executor so the
- // registration-time `rg` probe stays deterministic and the generator
- // never depends on the host PATH. `ctx.spillStore` is optional (read via
- // ctx.get) and does not affect the schemas, so no spill backend is mounted.
- await ctx.plugin(CatalogSearchBashExecutor)
+ // The tools inject `subprocess` (search spawns the packaged ripgrep
+ // binary through the seam, not ctx.fs); registration itself never
+ // spawns, so the real local service is inert here. `ctx.spillStore` is
+ // optional (read via ctx.get) and does not affect the schemas, so no
+ // spill backend is mounted.
+ await ctx.plugin(LocalSubprocessService)
await ctx.plugin(ToolFsSearch, { sampleOverCapGlobResults: true })
},
note:
- 'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.',
+ 'glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess as ordinary foreground calls (never background tasks) — no host `rg` install and no shell layer. The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.',
},
{
pkg: '@deepseek-ai/dsh-tool-pty',
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 70f5854c69..82abd3cfc3 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -23,6 +23,7 @@
"apps/web/tests/settings-chrome.e2e.ts",
"apps/web/tests/models-settings.e2e.ts",
"apps/web/tests/onboarding-deepseek-config.e2e.ts",
+ "apps/web/tests/remote-welcome.e2e.ts",
"apps/web/tests/workspace-management.e2e.ts",
"apps/web/tests/replay-round-trip.e2e.ts",
"apps/web/tests/hmr-live.e2e.ts",
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 6a08eeb3eb..c34cd52592 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -55,12 +55,17 @@ export default defineConfig({
'packages/sdk/*/tests/**/*.snapshot.ts',
'packages/ui/tui/tests/**/*.snapshot.ts',
],
- // Each test boots a subprocess; give it room and keep the worker file singular. Replay tests
- // opt into bounded in-file concurrency, while record/refresh stay serial because they write
- // fixtures. The environment knob restores serial replay with value 1 on constrained machines.
+ // Replay never writes committed outputs and every scenario owns its
+ // mutable runtime state (the subprocess suites use a unique temp dir and
+ // fixture set per scenario), so replay runs the snapshot files in
+ // parallel and bounds in-file concurrency with the environment knob
+ // (value 1 restores fully serial replay on constrained machines). Record
+ // and refresh stay serial: record spends real API quota per scenario, and
+ // refresh write-back harvests volatile values from fixtures already on
+ // disk, so concurrent writers would corrupt goldens.
testTimeout: 120_000,
hookTimeout: 30_000,
- fileParallelism: false,
+ fileParallelism: (process.env.DSH_SNAPSHOT || 'replay') === 'replay' && snapshotMaxConcurrency > 1,
maxConcurrency: snapshotMaxConcurrency,
},
})