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 cf755d0262..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
@@ -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/architecture/2026-07-19-package-owned-invariant-service.md
-2026-07-19-package-owned-invariant-service.md: 2443a8f7d04b96f51bb798130078a7457f78b2a1
-2026-07-19-package-owned-invariant-service.zh.md: 3c71d3b7f99a507d4c0236b7ef6dc0794814cdc8
+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` declarations, infer routing-key types from real `scopeTarget(base, key)` calls, and require one unambiguous payload subject or an explicit unsupported marker. The committed runtime map imports no event-owner package, so semantic completeness does not expand either the service or scope package's runtime closure.
-### Standard composition and SDK output
+### Example composition and SDK output
-The standard agent spine mounts the service and all four stateful companion subpaths, forwarding `enabled`, `package_allowlist`, and `package_blocklist` to the service. Generated SDK Cordis composition emits the same entries. A subpath entry adds its installable root npm package rather than treating the subpath as a package name.
+The example agent spine mounts the service and all four stateful companion subpaths, forwarding `enabled`, `package_allowlist`, and `package_blocklist` to the service. Generated SDK Cordis composition emits the same entries. A subpath entry adds its installable root npm package rather than treating the subpath as a package name. The shipped `dsh` TUI and Web config trees omit the service and companions under the [shipped-config decision](../simplification/2026-08-03-omit-invariants-from-shipped-config.md).
Workspace constraints recognize the separate invariant bundle, and package exports, project references, build configuration, dependency declarations, and the lockfile describe the same publication surface. Generated config catalogs, module graphs, and API documentation derive from those sources.
@@ -97,7 +97,7 @@ Every Vitest configuration loads a test host that mounts an explicitly enabled s
- Product packages own and test their relational assertions while the service stays product-independent.
- Every package pays the publication and dependency cost of a companion; only owners with a meaningful runtime relationship add listener or trace-state cost.
-- Standard compositions can disable all checks or select package names without changing their plugin tree.
+- Compositions that mount the diagnostics can disable all checks or select package names without changing their plugin tree.
- Explicit companion entries make diagnostic cost and ownership visible in Cordis config and package exports.
- One selected executable contribution adds one child fiber and its listener/state cost; a selected empty contribution has no listener or trace-state cost, while filtered registrations retain only name ownership.
- Regex sources are deployment configuration and remain fixed until the service reloads.
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
index 3c71d3b7f9..60edaa3f60 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
@@ -8,7 +8,7 @@ Status: implemented
运行时不变式检查跨越会话轨迹、agent 状态、作用域 dispatch 和请求重建。如果所有检查都放在一个诊断包中，该包就必须导入彼此无关的产品领域词汇，测试也会离开真正的所有者；任何产品包新增或移除检查时，都要修改中央包。
-部署还需要比“是否加载一个插件”更细的控制。标准组合应携带已知的不变式贡献，同时允许全局关闭或按包选择诊断。包稍后加载或在 HMR 下重载时，选择结果必须保持稳定；被过滤的贡献也不能让两个插件静默占用同一个包名。
+选择启用诊断的部署还需要比“是否加载一个插件”更细的控制。这类组合会携带已知的不变式贡献，同时允许全局关闭或按包选择诊断。包稍后加载或在 HMR 下重载时，选择结果必须保持稳定；被过滤的贡献也不能让两个插件静默占用同一个包名。
包所有权还必须覆盖完整。若没有机械化的仓库规则，新包可能遗漏伴随插件、依赖或发布配置，并一直不会进入诊断范围，直到维护者发现这一缺口。
@@ -72,9 +72,9 @@ blocklist 匹配优先于 allowlist 匹配。每个条目都是区分大小写
生成的 scoped event 主体解析表位于 `dsh-scope`，与消费它的契约和不变式相邻。`gen-scoped-events` 使用根 TypeScript Program 枚举 `this: Scoped` 声明，从真实 `scopeTarget(base, key)` 调用推断路由键类型，并要求唯一、无歧义的 payload 主体或显式 unsupported 标记。提交的运行时映射不导入事件所有者包，因此语义完整性不会扩大服务包或 scope 包的运行时依赖闭包。
-### 标准组合与 SDK 输出
+### 示例组合与 SDK 输出
-标准 agent spine 会挂载服务和四个有状态伴随子路径，并把 `enabled`、`package_allowlist` 与 `package_blocklist` 转发给服务。生成的 SDK Cordis 组合输出相同条目。子路径条目添加可安装的根 npm 包，而不会把子路径误当成包名。
+示例 agent spine 会挂载服务和四个有状态伴随子路径，并把 `enabled`、`package_allowlist` 与 `package_blocklist` 转发给服务。生成的 SDK Cordis 组合输出相同条目。子路径条目添加可安装的根 npm 包，而不会把子路径误当成包名。根据[交付配置决策](../simplification/2026-08-03-omit-invariants-from-shipped-config.md)，交付的 `dsh` TUI 与 Web 配置树会省略该服务及其伴随插件。
Workspace 约束识别独立的不变式 bundle；包 exports、项目引用、构建配置、依赖声明和 lockfile 描述同一发布表面。生成的配置目录、模块图和 API 文档都从这些源派生。
@@ -97,7 +97,7 @@ Workspace 约束识别独立的不变式 bundle；包 exports、项目引用、
- 产品包拥有并测试自己的关系断言，服务保持与产品无关。
- 每个包都承担 companion 的发布与依赖成本；只有具备有意义运行时关系的所有者才增加 listener 或 trace 状态成本。
-- 标准组合无需改变插件树即可关闭全部检查或按包名选择。
+- 挂载诊断的组合无需改变插件树即可关闭全部检查或按包名选择。
- 显式伴随条目让诊断成本和所有权在 Cordis 配置与包 export 中可见。
- 每个选中的可执行贡献增加一个子 fiber 及其 listener/状态成本；选中的空贡献不增加 listener 或 trace 状态成本，被过滤注册则只保留包名占用。
- 正则表达式源属于部署配置，在服务重载前保持固定。
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
new file mode 100644
index 0000000000..f63372c8b4
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.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/architecture/2026-08-01-packaged-ripgrep-search.md
+2026-08-01-packaged-ripgrep-search.md: 7c515618a18b61bd90177a6fdf19bbd52e564209
+2026-08-01-packaged-ripgrep-search.zh.md: f2b1a12c737f772bff6a6c91c17f7453dbc89748
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
new file mode 100644
index 0000000000..7c515618a1
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
@@ -0,0 +1,38 @@
+# Agent Note: Packaged ripgrep spawn for glob/grep
+
+Status: implemented
+
+English | [中文](2026-08-01-packaged-ripgrep-search.zh.md)
+
+> Supersedes [bash-backed grep/glob discovery](../../archived/feature/2026-07-09-bash-backed-grep-glob-discovery.md): the v1 decision's explicitly deferred alternative — directly spawning ripgrep — is now what ships.
+
+## Problem
+
+The `glob`/`grep` tools ran through the bash executor seam, which made a system `rg` install a host dependency. On Windows and container images there is no `rg` on `PATH` by default, so the tools silently vanished there; a deployment could only discover that from the load-time probe warning. The bash seam also forced the whole model-visible argument surface through one shell-quoting helper, because a shell sat between the tool and ripgrep — the [bash-backed note](../../archived/feature/2026-07-09-bash-backed-grep-glob-discovery.md) recorded that coupling as the v1 trade-off and named direct spawn as the reasonable follow-up if the shell-string domain ever proved too sensitive. It did: every model value had to survive POSIX single-quoting, the probe had to be scripted in tests, and the executor's own timeout classification duplicated what the cooperative tool-timeout policy already owns.
+
+## Decision
+
+`@deepseek-ai/dsh-tool-fs-search` now runs the PACKAGED ripgrep binary (`@vscode/ripgrep`, an npm dependency whose optional platform packages ship the binary) through the `ctx.subprocess` seam: `runRipgrep()` spawns `rgPath` with a plain argv vector prefixed by `--no-config`, collect-mode stdout/stderr, `graceMs`, and `exec.signal` forwarded. `rgPath` resolves lazily at the first call (memoized per process): `@vscode/ripgrep` resolves its platform package at module evaluation, so a static import would turn a missing or corrupt platform package (`--omit=optional`, partial install) into a Loader-composition failure — the load-time failure mode this change exists to remove. There is no shell layer, so the shell-quoting boundary is gone from execution; the `singleQuote` helper and its shell-spawning tests are deleted with it. The raw streams request the seam's diagnostic-tail collect shape (no spill files — the tool never reads a raw spill path; a lossy stdout read fails as `SEARCH_RAW_OUTPUT_OVERFLOW`). The terminate grace and the stderr tail budget are validated `Config` fields (`graceMs` default 3000, `stderrMaxBytes` default 64 KiB), no longer inherited from bash-local's config. Registration is unconditional — the load-time `command -v rg` probe and the conditional registration decision are deleted, and with them the "rg not found" warning. The package injects `tools`, `systemPrompt`, and `subprocess`.
+
+Exit semantics stay tool-owned: exit 0 is success with results, exit 1 is a successful empty search, anything else classifies into the existing `SEARCH_*` vocabulary (invalid pattern, launch failure, signal kill, raw-output overflow). Timeout is the cooperative tool-call budget attached to the tool definitions: `@deepseek-ai/dsh-timeout-policy` aborts `exec.signal`, the subprocess seam's terminate escalation provides the hard kill, and the tool reports `SEARCH_ABORTED`. The working directory is the session header cwd when present, else `process.cwd()` — there is no executor config to default through anymore, so the tool owns the fallback.
+
+The `fs-glob-sampling` ACP snapshot scenario now executes the real packaged binary against a prepared workspace whose fixed mtimes pin the `--sort=modified` order, replacing the PATH-injected `rg` stand-in (POSIX-only, because the displayed paths carry `/` separators the session-log comparison cannot normalize).
+
+## Alternatives considered
+
+**Keep the bash seam and probe, but document `rg` as a required host dependency.** Rejected: the host dependency is exactly the failure this change removes, and Windows support for the discovery tools was the point of the exercise; a documented requirement is still a requirement.
+
+**Make `rgPath` injectable (a config field or env override) so tests and snapshots keep substituting a stand-in binary.** Rejected: it adds a public deployment surface whose only consumer would be test seams, and the real binary is deterministic enough to pin directly through fixture mtimes — the packaged binary is the deployment, so tests should exercise it.
+
+**Switch to a pure-JS glob/search engine (e.g. `picomatch`/`tinyglobby`).** Rejected: the [dependency-swaps audit](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) already rejected that on the "no glob engine exists" evidence; ripgrep semantics (`--sort=modified`, VCS pruning, JSON transport, regex dialect) are the tool contract.
+
+## Consequences
+
+- The discovery tools work on every platform the packaged binary covers (darwin/linux/win32, x64/arm64) with no host install; the shipped TUI/Web rosters gain `glob`/`grep` as fixed members ([even-out-shipped-tool-rosters](../feature/2026-07-31-even-out-shipped-tool-rosters.md)).
+- The shell-string attack surface is gone: hostile patterns are inert argv elements, pinned by the integration suite, which now runs on Windows too (it previously self-skipped without a system `rg`).
+- The spawn is unconfined (a plain `ctx.subprocess` call), so `--no-config` is prepended: a host `RIPGREP_CONFIG_PATH` (or an `rg.conf` beside the binary) can otherwise inject a `--pre` preprocessor that executes an arbitrary command for every matched file. With `--no-config`, no config file — and therefore no preprocessor — can reach the search.
+- The raw-output overflow path changed shape: the old bash-backed route inherited bash-local's always-on spill and could leave an unread multi-megabyte temp file; the subprocess seam now collects without spill, and overflow is a pure error (`SEARCH_RAW_OUTPUT_OVERFLOW`, "narrow pattern, path, or include and retry") with zero content returned.
+- Load-time failure modes changed: a broken subprocess seam now fails the first search call (`SEARCH_FAILED`) instead of failing plugin load through the probe; a missing binary is a launch failure with the packaged path, not a PATH problem.
+- The integration suite's fixture dropped a filename Windows cannot represent (`"` in a name), keeping the suite replayable on every platform.
+- Regenerating `THIRD_PARTY_NOTICES.md` surfaced a latent generator bug the new dependency made visible: Node's `fs.globSync` returns OS-native separators, so on Windows the `/`-suffixed dev-area prefixes in the notices tiering never matched and dev-only packages (test tooling, support leaves) were mis-tiered as runtime. The generator now normalizes manifest paths at ingestion, and the notices are platform-independent.
+- The `@vscode/ripgrep` dependency adds its MIT row to the runtime tier, and pnpm 11's truncated virtual-store directory names needed a content-scan fallback in the notices generator's metadata lookup.
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
new file mode 100644
index 0000000000..f2b1a12c73
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
@@ -0,0 +1,38 @@
+# Agent Note: glob/grep 改用打包的 ripgrep 二进制直接 spawn
+
+Status: implemented
+
+[English](2026-08-01-packaged-ripgrep-search.md) | 中文
+
+> 取代 [bash 承载的 grep/glob 发现工具](../../archived/feature/2026-07-09-bash-backed-grep-glob-discovery.md)：v1 决策中明确延期的方案——直接 spawn ripgrep——现在成为实际交付的实现。
+
+## 问题
+
+`glob`/`grep` 工具经由 bash 执行器 seam 运行，这使系统 `rg` 安装成为宿主依赖。Windows 和容器镜像的 `PATH` 默认没有 `rg`，工具在那里会静默消失；部署方只能从加载期探针警告里发现这一点。bash seam 还迫使整个模型可见参数面经过一个 shell 引号工具，因为工具与 ripgrep 之间隔着一层 shell——[bash 承载决策](../../archived/feature/2026-07-09-bash-backed-grep-glob-discovery.md) 把这种耦合记为 v1 的取舍，并把直接 spawn 列为 shell 字符串域一旦被证明过于敏感时的合理后续。它确实被证明了：每个模型值都要经受 POSIX 单引号转义，探针要在测试里脚本化，执行器自身的超时分类还与协作式工具超时策略已有的职责重复。
+
+## 决策
+
+`@deepseek-ai/dsh-tool-fs-search` 现在运行 PACKAGED（打包的）ripgrep 二进制（`@vscode/ripgrep`，一个 npm 依赖，其可选平台包随附二进制），经由 `ctx.subprocess` seam：`runRipgrep()` 以纯 argv 向量 spawn `rgPath`，向量前缀 `--no-config`，配以 collect 模式 stdout/stderr、`graceMs` 与转发的 `exec.signal`。`rgPath` 在首次调用时懒解析（进程内 memoize）：`@vscode/ripgrep` 在模块求值阶段解析其平台包，静态导入会把平台包缺失/损坏（`--omit=optional`、安装不全）变成 Loader 组合加载失败——这正是本次改动要消除的加载期失败模式。不再有 shell 层，执行路径上的 shell 引号边界随之消失；`singleQuote` 工具与其 shell spawn 测试一并删除。原始流使用 seam 的诊断尾部 collect 形态（无 spill 文件——工具从不读取原始 spill 路径；lossy stdout 读取以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败）。终止宽限与 stderr 尾部预算成为经校验的 `Config` 字段（`graceMs` 默认 3000，`stderrMaxBytes` 默认 64 KiB），不再继承自 bash-local 的配置。注册变为无条件——加载期 `command -v rg` 探针与条件注册决策被删除，连同那条 "rg not found" 警告。本包注入 `tools`、`systemPrompt` 与 `subprocess`。
+
+退出语义仍由工具拥有：退出码 0 为有结果的成功，1 为成功的空搜索，其余归入既有 `SEARCH_*` 词汇（无效模式、启动失败、信号杀死、原始输出溢出）。超时是挂在工具定义上的协作式工具调用预算：`@deepseek-ai/dsh-timeout-policy` 中止 `exec.signal`，subprocess seam 的终止升级提供硬终止，工具报告 `SEARCH_ABORTED`。工作目录为会话 header cwd（存在时），否则为 `process.cwd()`——不再有执行器配置可供默认化，因此回退由工具自己拥有。
+
+`fs-glob-sampling` ACP 快照场景改为执行真实的打包二进制，作用于一个用固定 mtime 钉住 `--sort=modified` 顺序的预制工作区，取代 PATH 注入的 `rg` 替身（仅 POSIX：展示路径携带 `/` 分隔符，会话日志比较无法归一化）。
+
+## 备选方案
+
+**保留 bash seam 与探针，仅把 `rg` 记为必需宿主依赖。** 否决：宿主依赖正是本次改动要消除的失败模式，而让发现工具支持 Windows 正是此举的目的；写进文档的依赖仍是依赖。
+
+**让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试 seam 会消费的公开部署面，而真实二进制本身足够确定——通过 fixture mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
+
+**改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于"不存在 glob 引擎"的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具契约。
+
+## 后果
+
+- 发现工具在打包二进制覆盖的每个平台（darwin/linux/win32，x64/arm64）上开箱即用，无需宿主安装；交付的 TUI/Web 工具清单把 `glob`/`grep` 变为固定成员（见 [拉平交付的工具清单](../feature/2026-07-31-even-out-shipped-tool-rosters.md)）。
+- shell 字符串攻击面消失：恶意模式只是惰性 argv 元素，由集成套件钉住；该套件现在也在 Windows 上运行（此前没有系统 `rg` 时它自行跳过）。
+- spawn 不受沙箱约束（普通的 `ctx.subprocess` 调用），因此前缀 `--no-config`：宿主的 `RIPGREP_CONFIG_PATH`（或二进制旁的 `rg.conf`）否则可注入 `--pre` 预处理器，对每个匹配文件执行任意命令。加上 `--no-config` 后，任何配置文件——因而任何预处理器——都无法触及搜索。
+- 原始输出溢出路径的形态改变：旧的 bash 承载路径继承了 bash-local 常开的 spill，可能留下没人读的多 MB 临时文件；subprocess seam 现在无 spill 收集，溢出是纯粹的错误（`SEARCH_RAW_OUTPUT_OVERFLOW`，"narrow pattern, path, or include and retry"），不返回任何内容。
+- 加载期失败模式改变：subprocess seam 损坏现在让首次搜索调用失败（`SEARCH_FAILED`），而非通过探针使插件加载失败；二进制缺失是带打包路径的启动失败，而不是 PATH 问题。
+- 集成套件的 fixture 去掉了 Windows 无法表示的文件名（名称含 `"`），保证套件在每个平台都能重放。
+- 重新生成 `THIRD_PARTY_NOTICES.md` 暴露了一个由新依赖带出的潜在生成器 bug：Node 的 `fs.globSync` 返回操作系统原生分隔符，因此在 Windows 上 notices 分层中带 `/` 后缀的 dev 区前缀永远匹配不上，dev-only 包（测试工具、support 叶子）被错分为 runtime。生成器现在在入口处归一化清单路径，notices 与平台无关。
+- `@vscode/ripgrep` 依赖为 runtime 层增加其 MIT 行；pnpm 11 截断的虚拟存储目录名需要在 notices 生成器的元数据查找中增加内容扫描回退。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
new file mode 100644
index 0000000000..3c6718b975
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.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/bug-fix/2026-07-31-resume-selector-batch-projection.md
+2026-07-31-resume-selector-batch-projection.md: 39146527f13b20813bb6f5d5f1349ecab5724662
+2026-07-31-resume-selector-batch-projection.zh.md: 10333ea7cc5e7f2051c37f3374c5dc061bd0586e
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
new file mode 100644
index 0000000000..39146527f1
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
@@ -0,0 +1,35 @@
+# Agent Note: Resume selector folds titles only
+
+Status: implemented
+
+English | [中文](2026-07-31-resume-selector-batch-projection.zh.md)
+
+## Problem
+
+Opening the TUI `/resume` selector called `sessionQuery.readSession()` once per listed session under an unbounded `Promise.all`. Each call re-listed the whole persistence store inside `SessionCorpus.load()` (O(N²) listings), read and decompressed the complete log, replay-validated every event through the `Session` constructor, and deep-cloned the header and events up to three times — all to derive one selector row's title, last-activity time, last `turn/end` label, provider/model route, and goal phase. On a real store (185 sessions, 87 MB compressed, ~353k events) the selector took tens of seconds to open, and the cost grew with total log size rather than session count.
+
+## Decision
+
+Selector rows fold nothing but titles, and everything else a row shows comes from metadata:
+
+- Titles come from the projection system: `session-title` already registers a `title` unit, so a live row reads the registry snapshot, a persisted row reads the durable checkpoint row (`sessionProjectionCache.cachedSnapshot`, zero I/O), and only a row without a usable checkpoint pays a `coldSnapshot` — checkpoint plus a `readFrom` tail, written back so the next scan is zero-I/O. Cold reads are bounded by the TUI `resumeScanConcurrency` config. A composition without the cache falls back to one bounded `readTitleSnapshots` batch over the logs; either path isolates a per-row failure into the disabled "Unreadable session" fallback.
+- The activity timestamp never reads a log: a live session uses its last in-memory event time; a persisted session stats the artifact named by the optional `sessionPersistence.locate()` (mtime), falling back to the header's creation time when the backend locates no per-session artifact (SQLite) or the stat fails. Any append moves the mtime, so a mere pickup boundary now floats a browsed session up — accepted as the price of a metadata-only timestamp.
+- The last-turn label, provider/model route, and goal phase columns are gone from rows. Route availability is now enforced by the Enter-time preflight, which fully reads and replay-validates the one chosen log through `readSession` before handoff.
+
+The selector overlay opens synchronously when `/resume` dispatches, before the scan settles: an `undefined` candidate set renders a "Loading sessions…" placeholder, the picker owns terminal input from its first frame, Enter reports that sessions are still loading, and Escape cancels. Closing the overlay aborts the scan through the `AbortSignal` the query methods accept; a signal-ignoring backend's late settlement is dropped by a staleness check. The finished scan swaps rows in through `setCandidates` (clearing a stale still-loading error) without replacing the overlay; a queued activation behind a closing predecessor receives an already-scanned set at construction; one catch spans listing, titles, and mtimes, so any scan failure closes the overlay and reports a notice rather than stranding the loading placeholder.
+
+No session-query or session-persistence surface changed. The shipped TUI composition gains the projection registry, storage, and projection-cache rows (mirroring the web overlay over the same `storages` root, so checkpoints written by either surface serve both); the first scan over a pre-existing store still reads each log once to seed checkpoints, and every later scan is metadata-only.
+
+## Alternatives considered
+
+**Keep per-row route/turn/goal columns via a generic batch projection (`projectSessions`).** Implemented first, then rejected: it still decompressed and parsed every log on every `/resume`, so browsing cost stayed O(total log bytes), and it grew the session-query public API for one consumer. The public seam was reverted; `readTitleSnapshots` keeps using the internal `projectMany` unchanged.
+
+**Fix only the O(N²) listing inside `SessionCorpus.load()`.** Rejected as the primary fix: the per-candidate full decompress, replay validation, and triple clone dominated on large logs. The redundant pre-listing in `load()` remains a candidate cleanup with error-semantics implications.
+
+**Surface a last-modified time through `listSnapshots`/`SessionRecord`.** Cleanest seam-wise, but touches the persistence contract, both backends, and the query record shape for what the TUI can already derive from `locate()` plus one stat. Reintroduce if a second consumer needs metadata activity times.
+
+**A bespoke persisted title index or TUI-local title cache.** Rejected: the session-projection cache already is the owned durable checkpoint system with an invalidation contract (`stateVersion`, identity binding, shrunk-log anchoring); mounting it beats adding a parallel cache.
+
+## Consequences
+
+Opening `/resume` performs one listing, one stat per persisted row, and per-row title reads that touch only checkpoint rows and log tails once checkpoints exist — O(session count) metadata instead of O(total log bytes); the fallback path without the cache remains one bounded title pass. Rows show title, timestamp, status, and id only; route problems surface as an Enter-time preflight error instead of a disabled row, and a session that fails replay is caught by preflight rather than the listing. Browsed-then-abandoned sessions float up on their pickup mtime. Fake `sessionQuery` services in TUI tests provide `readTitleSnapshots` alongside `listSessions`/`readSession`, and the test harness forwards an optional `locate`. Because the picker takes focus immediately, starting a second scan requires dismissing the current overlay first — a second `/resume` typed during a scan lands in the search field, which is the intended input capture.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
new file mode 100644
index 0000000000..10333ea7cc
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 恢复选择器只折叠标题
+
+Status: implemented
+
+[English](2026-07-31-resume-selector-batch-projection.md) | 中文
+
+## Problem
+
+打开 TUI `/resume` 选择器时，会在一个无界 `Promise.all` 中对每个列出的会话调用一次 `sessionQuery.readSession()`。每次调用都会在 `SessionCorpus.load()` 内部重新列出整个持久化存储（O(N²) 次列表查询）、读取并解压完整日志、通过 `Session` 构造函数对每个事件做回放验证，并将 header 和事件深克隆多达三次——而这一切只为推导一行选择器条目的标题、最近活动时间、最后一个 `turn/end` 标签、提供方/模型路由和目标阶段。在真实存储上（185 个会话、压缩后 87 MB、约 35.3 万个事件），选择器需要数十秒才能打开，且开销随日志总大小而非会话数量增长。
+
+## Decision
+
+选择器行除标题外不折叠任何内容，行内其余信息全部来自元数据：
+
+- 标题来自投影系统：`session-title` 已注册 `title` 投影单元，因此实时行读取注册表快照，持久化行读取持久 checkpoint 行（`sessionProjectionCache.cachedSnapshot`，零 I/O），只有没有可用 checkpoint 的行才付出一次 `coldSnapshot`——checkpoint 加 `readFrom` 尾部折叠，并写回使下次扫描零 I/O。冷读取受 TUI `resumeScanConcurrency` 配置约束。未挂载缓存的组合回退到一次对日志的有界 `readTitleSnapshots` 批量读取；两条路径都把单行失败隔离为禁用的"Unreadable session"回退。
+- 活动时间戳从不读取日志：实时会话取内存中最后一个事件的时间；持久化会话对可选 `sessionPersistence.locate()` 命名的产物做 stat（mtime），当后端定位不到按会话的产物（SQLite）或 stat 失败时回退到 header 的创建时间。任何追加都会移动 mtime，因此仅仅一次 pickup 边界也会让浏览过的会话上浮——这是元数据时间戳的代价，予以接受。
+- 行内不再有最后轮次标签、提供方/模型路由和目标阶段列。路由可用性改由 Enter 时的预检强制：预检通过 `readSession` 完整读取并回放验证选中的那一份日志后才移交。
+
+选择器 overlay 在 `/resume` 分发时同步打开，早于扫描结算：`undefined` 候选集渲染"Loading sessions…"加载占位符，选择器从第一帧起就拥有终端输入，Enter 提示会话仍在加载，Escape 取消。关闭 overlay 会通过查询方法接受的 `AbortSignal` 中止扫描；忽略信号的后端的迟到结算由过期检查丢弃。扫描完成后通过 `setCandidates`（同时清除过期的仍在加载错误）换入行数据，不替换 overlay；排在正在关闭的前任之后的排队激活会在构造时直接收到已扫描的集合；列表查询、标题与 mtime 共用同一个 catch，因此任何扫描失败都会关闭 overlay 并报告通知，而不会让加载占位符悬置。
+
+session-query 与 session-persistence 的任何表面都未改变。随附的 TUI 组合新增投影注册表、storage 与投影缓存行（镜像 web overlay，共用同一 `storages` 根，因此任一表面写下的 checkpoint 都服务两者）；对既有存储的首次扫描仍会各读取一次日志以播种 checkpoint，之后的每次扫描都只读元数据。
+
+## Alternatives considered
+
+**通过通用批量投影（`projectSessions`）保留每行的路由/轮次/目标列。** 先实现后否决：它仍在每次 `/resume` 时解压并解析全部日志，浏览开销依旧是 O(日志总字节数)，且为单一消费者扩大了 session-query 公开 API。该公开接缝已回退；`readTitleSnapshots` 继续使用内部 `projectMany`，保持不变。
+
+**只修复 `SessionCorpus.load()` 内部的 O(N²) 列表查询。** 作为主要修复被否决：在大日志上，按候选行执行的完整解压、回放验证和三重克隆才是主要开销。`load()` 中的冗余预列表查询仍是一个候选清理项，但涉及错误语义。
+
+**通过 `listSnapshots`/`SessionRecord` 暴露最后修改时间。** 从接缝角度最干净，但要触碰持久化契约、两个后端和查询记录形状，而 TUI 已能用 `locate()` 加一次 stat 得到同样的信息。若出现第二个需要元数据活动时间的消费者再引入。
+
+**专门的持久化标题索引或 TUI 本地标题缓存。** 否决：session-projection 缓存本身就是自有的持久 checkpoint 系统，并已带失效契约（`stateVersion`、身份绑定、日志收缩锚定）；挂载它优于再造一套并行缓存。
+
+## Consequences
+
+打开 `/resume` 只执行一次列表查询、每个持久化行一次 stat，标题读取在 checkpoint 就绪后只触碰 checkpoint 行和日志尾部——O(会话数) 的元数据开销，而非 O(日志总字节数)；无缓存的回退路径仍是一次有界标题扫描。行内只显示标题、时间戳、状态和 id；路由问题以 Enter 时预检错误的形式出现，而不再是禁用行；回放会失败的会话由预检而非列表阶段拦截。浏览后放弃的会话会因 pickup 的 mtime 上浮。TUI 测试中的伪造 `sessionQuery` 服务在 `listSessions`/`readSession` 之外提供 `readTitleSnapshots`，测试 harness 会转发可选的 `locate`。由于选择器立即接管焦点，启动第二次扫描需要先关闭当前 overlay——扫描期间输入的第二个 `/resume` 会落入搜索字段，这正是预期的输入捕获行为。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.i18n.yaml
new file mode 100644
index 0000000000..8beb847e60
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.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/bug-fix/2026-08-03-tui-long-session-render-costs.md
+2026-08-03-tui-long-session-render-costs.md: c5b03960b6951cb2de2b847f03ec8eb2b92cc55c
+2026-08-03-tui-long-session-render-costs.zh.md: b41c5a8c546e296525645d82808117673fdeec6d
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.md b/.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.md
new file mode 100644
index 0000000000..c5b03960b6
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.md
@@ -0,0 +1,33 @@
+# Agent Note: TUI long-session render costs — shared step-timing scan and card line caches
+
+Status: implemented
+
+English | [中文](2026-08-03-tui-long-session-render-costs.zh.md)
+
+## Problem
+
+On a long resumed session (196k events, 2.2k steps, 1.8k tool cards) the TUI took ~12 s to render the transcript and ~800 ms to echo one keystroke. Profiling attributed both to the render path, not to session load (zstd + parse + surface seed is ~1.7 s):
+
+- Every step's timing footer called `stepTimingAt`, which replayed the whole event log from index 0 per footer — O(steps × events) on the initial render, ~6 s of CPU.
+- pi-tui re-renders every component each frame and relies on per-component line caches (its own `Text`/`Markdown` cache by `(text, width)`). `ToolCardComponent.render()` and `ContextCardComponent.render()` built throwaway `new Text(...)`/`new Markdown(...)` instances inside `render(width)`, so every frame — every keystroke — re-wrapped every settled card's output.
+
+## Decision
+
+`packages/ui/tui/src/chat/timing.ts` replaces `stepTimingAt` with `StepTimingTracker`: one accumulator per chat mount, created in `createTuiChat` and threaded through `StreamingAssistantComponent` into each `StepTimingComponent`. A query advances a cursor over events appended since the previous query and keeps per-step bucket state in a map, so all footers together cost O(events). The open bucket is accumulated to the query clock at lookup, and a step is pinned at its `step/end`. The tracker requires the append-only session log (the `seq = log length` contract).
+
+`ToolCardComponent` and `ContextCardComponent` cache their rendered rows keyed by width. The cache drops on every state mutator (`updateResult`, `setVisibility`, `setExpanded`) and on `invalidate()` (pi-tui's tree-wide cascade), so a state change always re-renders; everything else — including every keystroke frame — returns the cached rows. This restores upstream pi's own component convention (persistent child components plus explicit `cachedWidth`/`cachedLines` where rendering is custom, e.g. pi `coding-agent` `bash.ts`), which the imperative `render(width)` bodies here had silently defeated.
+
+Measured on the 196k-event session (tmux, 200×50): resume prompt-ready 12.2 s → 7.2 s; per-keystroke echo 796 ms median → 17 ms (fresh-session parity).
+
+## Alternatives considered
+
+- **Index `step/start` offsets, keep per-footer replay** — removes the `findIndex` but each footer still scans its step's span from a shared array; the tracker's single shared pass is the same complexity win with less bookkeeping.
+- **Restructure the cards into persistent pi-tui child components** (upstream pi's primary style) — equivalent steady-state cost, but a larger diff across card state handling for no additional win over the width-keyed cache.
+- **Cache inside pi-tui's `Container.render`** — wrong layer: the vendored patch surface would grow, and the contract (components own their caches) already exists upstream.
+
+## Consequences
+
+- Typing latency no longer scales with total tool output; the residual per-frame cost is pi-tui's tree traversal and row concatenation, linear in rendered rows. Resume render cost is now dominated by pi-tui's one-time initial layout (~4 s at 196k events) plus load (~1.7 s), both linear.
+- The tracker consumes event times as logged and drops the removed implementation's mid-scan `time > at` cutoff, which per-footer `at` values make impossible in a shared scan; under a backward wall-clock step each bucket clamps at zero, which can differ from the old cutoff's totals.
+- Card `render()` is no longer a pure function of `(state, width)` per call — mutators must drop `linesCache`. A new mutator that forgets to do so shows stale rows; the cache tests in `packages/ui/tui/tests/transcript-card-cache.spec.ts` pin the contract for the existing mutators.
+- `StepTimingTracker` assumes step coordinates are not reused after `step/end`; a duplicate `step/start` for a closed step is ignored rather than restarting the step.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.zh.md
new file mode 100644
index 0000000000..b41c5a8c54
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-tui-long-session-render-costs.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: TUI 长会话渲染开销：共享步骤耗时扫描与卡片行缓存
+
+Status: implemented
+
+[English](2026-08-03-tui-long-session-render-costs.md) | 中文
+
+## 问题
+
+在一个恢复后的长会话（196k 条事件、2.2k 个步骤、1.8k 张工具卡片）中，TUI 渲染 transcript（文本记录）耗时约 12 秒，回显一次按键耗时约 800 毫秒。性能剖析表明，两项耗时都来自渲染路径，而非会话加载（zstd + 解析 + 表层播种约为 1.7 秒）：
+
+- 每个步骤的耗时页脚都会调用 `stepTimingAt`，而它会针对每个页脚从索引 0 起回放整个事件日志，因此初次渲染的复杂度为 O(步骤数 × 事件数)，占用约 6 秒 CPU 时间。
+- pi-tui 每一帧都会重新渲染所有组件，并依赖各组件自己的行缓存（它的 `Text`/`Markdown` 会按 `(text, width)` 缓存）。`ToolCardComponent.render()` 和 `ContextCardComponent.render()` 构造用后即弃的 `new Text(...)`/`new Markdown(...)` 实例，且构造发生在 `render(width)` 内，因此每一帧，也就是每次按键，都会重新对每张已结算卡片的输出进行折行。
+
+## 决策
+
+`packages/ui/tui/src/chat/timing.ts` 不再使用 `stepTimingAt`，改用 `StepTimingTracker`：每次挂载聊天界面时在 `createTuiChat` 中创建一个累加器，再经 `StreamingAssistantComponent` 传入每个 `StepTimingComponent`。每次查询都会推进游标，扫描上次查询后追加的事件，并在一个映射表中保存各步骤的 bucket 状态，因此所有页脚合计只需 O(事件数)。查询时，系统把未闭合 bucket 累加到查询时刻；步骤在其 `step/end` 处固定。该跟踪器要求会话日志仅追加，即遵守 `seq = log length` 契约。
+
+`ToolCardComponent` 和 `ContextCardComponent` 按宽度键控缓存渲染行。调用任一状态修改方法（`updateResult`、`setVisibility`、`setExpanded`）或 `invalidate()`（pi-tui 的全树级联）时会清空缓存，因此状态变化一定会重新渲染；其他情况，包括每一次按键帧，都会返回缓存行。这恢复了上游 pi 自身的组件惯例：使用常驻子组件；自定义渲染时显式使用 `cachedWidth`/`cachedLines`，例如 pi `coding-agent` 的 `bash.ts`。而这里命令式的 `render(width)` 函数体此前让这套惯例失效。
+
+在该 196k 条事件的会话上测得（tmux，200×50）：恢复后提示符就绪耗时从 12.2 秒降至 7.2 秒；每次按键的回显耗时中位数从 796 毫秒降至 17 毫秒（与新会话持平）。
+
+## 曾考虑的替代方案
+
+- **索引 `step/start` 偏移量，保留逐页脚回放**：这会消除 `findIndex`，但每个页脚仍要从共享数组扫描所属步骤的区间；跟踪器的一次共享遍历以更少的额外状态记录取得相同的复杂度改进。
+- **把卡片重构为常驻 pi-tui 子组件**（上游 pi 的主要风格）：稳定状态下成本相同，但卡片状态处理所需改动更大，相较按宽度键控的缓存并无额外收益。
+- **在 pi-tui 的 `Container.render` 内缓存**：层级不对：对第三方内嵌代码的补丁范围会扩大，而上游已经约定由组件拥有各自的缓存。
+
+## 后果
+
+- 输入延迟不再随工具输出总量增长；剩余的每帧成本是 pi-tui 的树遍历与行拼接，与渲染行数呈线性关系。恢复时的渲染成本现由 pi-tui 的一次性初始布局（196k 条事件时约 4 秒）与加载（约 1.7 秒）主导，两者均为线性。
+- 该跟踪器直接采用日志记录的事件时间，不再像已移除的实现那样，在扫描中途遇到 `time > at` 时截断；由于每个页脚的 `at` 值不同，共享扫描无法采用这种截断；挂钟时间倒退时，每个 bucket 都以零为下限，所得总计值可能与旧截断下的总计值不同。
+- 卡片的 `render()` 不再是每次调用时 `(state, width)` 的纯函数，状态修改方法必须清空 `linesCache`。若新增状态修改方法时忘记清空，界面会显示陈旧行；`packages/ui/tui/tests/transcript-card-cache.spec.ts` 中的缓存测试固定了现有状态修改方法的契约。
+- `StepTimingTracker` 假定步骤坐标在 `step/end` 后不会复用；对已关闭步骤重复出现的 `step/start` 会被忽略，不会重新启动该步骤。
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/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/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/shipped-composition.e2e.ts b/apps/web/tests/shipped-composition.e2e.ts
index f9da7d3bd3..782279f074 100644
--- a/apps/web/tests/shipped-composition.e2e.ts
+++ b/apps/web/tests/shipped-composition.e2e.ts
@@ -47,10 +47,10 @@ const EXPECTED_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']
@@ -65,7 +65,9 @@ it('assembles the shipped Web catalog with the confined access default', async (
scaffold = await launchWebScaffold()
const names = scaffold.ctx.tools.schemas().map(schema => 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/docs/config-catalog.md b/docs/config-catalog.md
index 99d7e5cee9..699a5ea632 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 3deca19c42..fe28baa242 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2458,7 +2458,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 7ef8a943c4..c13c713c26 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -711,12 +711,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
@@ -938,6 +938,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
@@ -1200,7 +1202,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) |
@@ -1236,7 +1238,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 8b055ea0d1..42734e0fb2 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`, `goal/change 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 d5253cce75..ea2a53a1aa 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/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 5b189bed3b..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,27 +1,31 @@
-{"type":"session","version":0,"id":"f5a99d52-3eaa-4ce7-858d-61d4fd77df2a","createdAt":1785218400000,"cwd":"{{cwd}}","delegationDepth":0}
-{"type":"agent/inbox/spliced","seq":0,"time":1785498778193,"data":{"target":"next-turn","start":0,"inserted":[{"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":"909083a0-9476-4b51-9eb0-62ab135e03f3"}]}}
-{"type":"agent/inbox/spliced","seq":1,"time":1785498778193,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
-{"type":"turn/start","seq":2,"time":1785498778214,"data":{"turn":1}}
-{"type":"step/start","seq":3,"time":1785218400004,"data":{"turn":1,"step":1}}
-{"type":"user/message","seq":4,"time":1785498778214,"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":"909083a0-9476-4b51-9eb0-62ab135e03f3"},"surfaceOp":"append"}
-{"type":"session/title","seq":5,"time":1785498778214,"data":{"title":"Call glob exactly once with","messageSeqs":[4],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":6,"time":1785498778215,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
-{"type":"request/context","seq":7,"time":1785730431213,"data":{"provider":"deepseek","model":"deepseek-v4-pro"}}
-{"type":"assistant/chunk","seq":8,"time":1785218400008,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":9,"time":1785218400009,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"glob-sampling-call","name":"glob","argumentsDelta":"{\"pattern\":\"*\"}"}}}
-{"type":"assistant/chunk","seq":10,"time":1785218400010,"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":11,"time":1785498778222,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":1,"outputTokens":1}}}}
-{"type":"assistant/chunk","seq":12,"time":1785730431221,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":13,"time":1785730431221,"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":"4abc7850-3ecd-4ce2-b280-51100b1e4ad3"},"usage":{"inputTokens":1,"outputTokens":1}},"sourceEventSeqs":[8,9,10,11,12],"surfaceOp":"append"}
-{"type":"tool/call","seq":14,"time":1785730431221,"data":{"turn":1,"step":1,"callId":"glob-sampling-call","name":"glob","arguments":"{\"pattern\":\"*\"}"}}
-{"type":"tool/result","seq":15,"time":1785730431237,"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":"ed4bcc40-b644-408f-a9e7-9e9a4646ca82"},"meta":{"shape":"paths","paths":["archive/a.ts","old\\one","old\\two","src/index.ts"],"truncated":true,"total":8}},"sourceEventSeqs":[14],"surfaceOp":"append"}
-{"type":"step/end","seq":16,"time":1785730431237,"data":{"turn":1,"step":1}}
-{"type":"step/start","seq":17,"time":1785730431245,"data":{"turn":1,"step":2}}
-{"type":"assistant/chunk","seq":18,"time":1785218400018,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":19,"time":1785218400019,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"GLOB_SAMPLED"}}}
-{"type":"assistant/chunk","seq":20,"time":1785218400020,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"GLOB_SAMPLED"}}}}
-{"type":"assistant/chunk","seq":21,"time":1785498778247,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":1,"outputTokens":1}}}}
-{"type":"assistant/chunk","seq":22,"time":1785730431249,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":23,"time":1785730431249,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"GLOB_SAMPLED"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-pro"},"id":"417b0db5-416d-4f7d-ac3d-c076110ab5ee"},"usage":{"inputTokens":1,"outputTokens":1}},"sourceEventSeqs":[18,19,20,21,22],"surfaceOp":"append"}
-{"type":"step/end","seq":24,"time":1785730431249,"data":{"turn":1,"step":2}}
-{"type":"turn/end","seq":25,"time":1785730431249,"data":{"turn":1,"step":2,"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/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 &1',
-]
-
-describe('singleQuote', () => {
- it('wraps a plain value in single quotes', () => {
- expect(singleQuote('abc')).toBe("'abc'")
- })
-
- it("rewrites embedded single quotes as '\\''", () => {
- expect(singleQuote("a'b")).toBe("'a'\\''b'")
- expect(singleQuote("''")).toBe("''\\'''\\'''")
- })
-
- it.each(HOSTILE.map(value => [JSON.stringify(value), value] as const))(
- 'round-trips %s through a real bash -c unchanged',
- (_label, value) => {
- const result = spawnSync('bash', ['-c', `printf '%s' ${singleQuote(value)}`], { encoding: 'utf8' })
- expect(result.status).toBe(0)
- expect(result.stdout).toBe(value)
- },
- )
-
- it('a quoted command substitution does not execute (the world stays untouched)', () => {
- const canary = `/tmp/dsh-quote-canary-${process.pid}`
- const result = spawnSync('bash', ['-c', `printf '%s' ${singleQuote(`$(touch ${canary})`)}`], { encoding: 'utf8' })
- expect(result.stdout).toBe(`$(touch ${canary})`)
- // The canary file must NOT exist — the substitution stayed literal.
- expect(spawnSync('test', ['-e', canary]).status).not.toBe(0)
- })
-})
diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts
index 389d8dbe05..9a8fa991ff 100644
--- a/packages/fs/tool-fs-search/tests/tools.spec.ts
+++ b/packages/fs/tool-fs-search/tests/tools.spec.ts
@@ -1,23 +1,24 @@
/**
- * Consumer-surface tests for the search tools over a FAKE bash executor and a
- * FAKE spill backend, exercised through `ctx.tools.execute()` so nothing
- * bypasses the tool registry. The fake executor makes every seam outcome
- * scriptable — registration-time `rg` probing, truncated stdout with/without a
- * raw spill path, abort/timeout, signal kills, ripgrep exit codes — so these
- * tests verify schemas, argument validation, shell-safe command construction,
- * workdir derivation, signal forwarding, `SEARCH_*` error classification,
- * retention, formatted-result spill handoff, and the no-background-task
- * invariant. Real-`rg` behavior is pinned separately in integration.spec.ts.
+ * Consumer-surface tests for the search tools over a FAKE subprocess service
+ * and a FAKE spill backend, exercised through `ctx.tools.execute()` so nothing
+ * bypasses the tool registry. The fake service makes every seam outcome
+ * scriptable — spawn failure, truncated stdout with/without a raw spill path,
+ * abort/timeout kills, signal kills, ripgrep exit codes — so these tests
+ * verify schemas, argument validation, argv construction, workdir derivation,
+ * signal forwarding, `SEARCH_*` error classification, retention,
+ * formatted-result spill handoff, and the no-background-task invariant.
+ * Real-`rg` behavior is pinned separately in integration.spec.ts.
*/
import { describe, expect, it } from 'vitest'
import { Context } from 'cordis'
import { join, sep } from 'node:path'
-import { createUserMessage, CallId } from '@deepseek-ai/dsh-llm'
+import { createUserMessage, CallId } from '@deepseek-ai/dsh-llm'
import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { TOOL_ABORTED_BEFORE_DISPATCH, type ToolExecutionToken } from '@deepseek-ai/dsh-tools'
-import { BashExecutor } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
+import ToolRegistry, { TOOL_ABORTED_BEFORE_DISPATCH, type ToolExecution, type ToolExecutionToken } from '@deepseek-ai/dsh-tools'
+import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
+import type { SubprocessCollectedOutputs, SubprocessHandle, SubprocessOutcome, SubprocessOutputRead, SubprocessOutputReader, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { rgPath } from '@vscode/ripgrep'
import { SpillLocator, SpillStore } from '@deepseek-ai/dsh-spill'
import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
import * as ToolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
@@ -31,68 +32,132 @@ import {
presentGrepCall,
presentGrepResult,
previewLine,
+ resolveRgPath,
+ runRipgrep,
sampleAcrossTopLevel,
toWorkdirRelative,
} from '@deepseek-ai/dsh-tool-fs-search'
const testToolSignal = new AbortController().signal
-const RG_PROBE_COMMAND = 'command -v rg >/dev/null 2>&1'
-/** A successful run result over the given stdout; overrides script the failure shapes. */
-function runResult(stdout: string, overrides?: Partial): 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 5dae12b17e..58d9ba2e1d 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/ui/tui/README.i18n.yaml b/packages/ui/tui/README.i18n.yaml
index 8b7c2f82ad..254a27d03c 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: 07e4c439eef78fc9497a1c0fa5824c9ab6680cb5
-README.zh.md: 962f8f67851aaf44a708baf3cf5220a76781c8bd
+README.md: a84b9b5c75581ba2aff97a7e6085ecb697e911b0
+README.zh.md: 4c6bd757e9aed875a12ce925b3a0acef5d20d623
diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md
index 07e4c439ee..a84b9b5c75 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 `↑ ↓