From 3e22adab2878ec5f78f3253877cd8e1a346a4250 Mon Sep 17 00:00:00 2001 From: Chinesezjc Date: Thu, 30 Jul 2026 17:03:54 +0800 Subject: [PATCH 01/43] feat(fs): add a search render-intent card for grep and glob results grep and glob returned only model-facing text; the structured matches/paths never reached the client. Add a card:'search' result view with a kind discriminant ('matches' grouped by file for grep, 'paths' for glob), projected through each tool's output.presentationMeta and read back in presentResult. The projections re-apply the same inline cap and per-line budget as the render text and report total + truncated, so a UI never presents a capped page as complete. A UI without the search card falls back to content; the TUI is unchanged. The web consumer is a follow-up. --- .../2026-07-30-search-render-card.i18n.yaml | 6 + .../feature/2026-07-30-search-render-card.md | 51 ++++++ .../2026-07-30-search-render-card.zh.md | 51 ++++++ docs/cordis-catalog/events.md | 12 +- docs/cordis-catalog/services.md | 2 +- .../cordis/tool-cordis/src/api-catalog.ts | 22 ++- packages/core/tools/src/index.ts | 5 + packages/core/tools/src/presentation.ts | 89 ++++++++++- packages/fs/tool-fs-search/src/glob.ts | 23 ++- packages/fs/tool-fs-search/src/grep.ts | 26 ++- packages/fs/tool-fs-search/src/index.ts | 5 +- .../fs/tool-fs-search/src/presentation.ts | 149 ++++++++++++++++++ .../tool-fs-search/tests/presentation.spec.ts | 129 +++++++++++++++ .../fs/tool-fs-search/tests/tools.spec.ts | 70 ++++++++ 14 files changed, 628 insertions(+), 12 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-30-search-render-card.md create mode 100644 .agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md create mode 100644 packages/fs/tool-fs-search/src/presentation.ts create mode 100644 packages/fs/tool-fs-search/tests/presentation.spec.ts diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml new file mode 100644 index 0000000000..4a00c287a2 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-search-render-card.md +2026-07-30-search-render-card.md: de59992cebcdf056e3446e4f546f8bff4b10e421 +2026-07-30-search-render-card.zh.md: 8b91255094c24972c05add92ee65f8c76c60a882 diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.md new file mode 100644 index 0000000000..de59992ceb --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.md @@ -0,0 +1,51 @@ +# Agent Note: Search render intent — grep and glob emit a structured search card + +Status: implemented + +English | [中文](2026-07-30-search-render-card.zh.md) + +## Problem + +`grep` and `glob` return structured canonical values — `grep` a flat `{ matches: [{ path, lineNumber, line }] }`, `glob` a `{ paths: string[] }` — but every UI only ever saw their model-facing render text: `grep` groups its matches under file headers with `Line N:` rows, `glob` prints a newline-joined path list, and both append a spill footer when the inline cap ({@link module:@deepseek-ai/dsh-tool-fs-search/grep} `grepMaxMatches`, default 250; {@link module:@deepseek-ai/dsh-tool-fs-search/glob} `globMaxResults`, default 100) drops later results to a spill file. A web frontend that wants to render a search result as an expandable per-file group of matches, or as a selectable path list, had to re-parse that text. Both tools already declared a call-time [render intent](../architecture/2026-07-02-tool-render-intent-union.md) (`GenericCallView`, `kind: 'search'`) but no result-time view, so the completed call fell back to the generic card that renders the raw text. + +The structured canonical value does not cross the wire: only the model-facing render text and, when a tool declares `output.presentationMeta`, a JSON metadata payload reach the client, threaded through the `tool/result` event ([canonical-output contract](../architecture/2026-07-20-canonical-tool-output-contract.md)). A result-time view carrying structured data therefore has to project that data into `presentationMeta` and read it back in `presentResult` — the same path `write`/`edit` use for their diff cards. + +## Decision + +`packages/core/tools/src/presentation.ts` adds `card: 'search'` to the `ToolResultView` union as `SearchResultView`, a `kind`-discriminated view that expresses both tools' shapes: `SearchMatchesResultView` (`kind: 'matches'`) carries `grep`'s matches grouped by file as `files: { path, matches: { lineNumber, line }[] }[]`, and `SearchPathsResultView` (`kind: 'paths'`) carries `glob`'s flat `paths: string[]`. Both carry `truncated: boolean` and `total: number`, and an optional `content?: ContentBlock[]`. + +One view with two shapes rather than two cards, because both tools are the same visual object — a search result — and a web consumer switches on one `card` value, then on `kind` for the row shape. The discriminated `kind` keeps each shape's fields non-optional (a matches view always has `files`, a paths view always has `paths`) instead of a single interface where every shape-specific field is optional. + +The card tag is result-time only. A search call stays a `GenericCallView` (`kind: 'search'`): the pending state has no matches or paths to show, so there is nothing a `SearchCallView` would carry that the generic title does not. This is the asymmetry with the terminal card, whose call view carries the command, cwd, and description that exist before execution; a search's structured content exists only after `execute`. + +`packages/fs/tool-fs-search/src/presentation.ts` owns the projection and the narrowing. `grepSearchMeta`/`globSearchMeta` project the canonical value into a `SearchMeta` payload each tool declares as `output.presentationMeta`; `presentGrepResult`/`presentGlobResult` read `result.meta` back through `searchViewFromMeta` and attach the model-facing `result.content` as the view's `content`. The projections apply the SAME inline cap and per-line preview budget the model-facing render applies, and report `total` as every result the search found (before capping) with `truncated` set when the cap dropped results. This is the truncation-honesty point: the model saw a capped inline result plus a spill footer, so the card must not present the retained page as the complete result — a UI reads `truncated`/`total` to show a capped indicator rather than claiming completeness the model never had. + +`searchViewFromMeta` narrows the opaque `meta` defensively and returns `undefined` on any malformed or absent payload, exactly as `diffsFromMeta` does, so a presenter run on an older or hand-edited replayed log falls back to the generic card instead of throwing. `presentResult` returns `undefined` for a failed result, for absent meta (a nested `run_code` dispatch computes no `presentationMeta`), and for the other tool's meta shape (each presenter narrows to its own `kind`). + +The `SearchMeta` member shapes are object-literal `type` aliases, not the `SearchFileMatches`/`SearchLineMatch` interfaces the view exposes. Only a type alias is assignable to the `JsonValue` index signature `presentationMeta` returns; the two are structurally identical, so the projected value still reads back as a `SearchResultView`. + +The TUI (`packages/ui/tui/src/components/transcript.ts`) needs no dedicated arm: its result-view switch handles `terminal` and `diff` explicitly and falls through to a generic arm that renders `view.content ?? this.result?.content`. Because `SearchResultView` carries the model-facing text as `content`, the TUI renders it as the same text it already showed. The web frontend that renders the structured `files`/`paths` shape is a separate later PR; this PR is the backend contract and its two producers. + +## Alternatives considered + +**A single flat `SearchResultView` interface with optional `files?` and `paths?`.** Rejected: it makes both shape-specific fields optional on every value and lets a malformed view carry both or neither. The `kind` discriminant keeps each shape's fields required and lets a consumer switch exhaustively. + +**A call-time `SearchCallView` mirroring the terminal card's both-sides symmetry.** Rejected: a search call has no matches or paths before `execute`, so the view would carry only the title the `GenericCallView` already carries. The terminal card's call view earns its tag because a command, cwd, and description exist at call time; a search's structured content does not. + +**Carry the structured result in a bespoke channel instead of `presentationMeta`.** Rejected: the canonical value is execution-local and never reaches the client, and `presentationMeta` is the established seam that persists a tool's JSON presentation payload with `tool/result` and threads it back to `presentResult`. Adding a second channel would duplicate that path. + +## Consequences + +`grep` and `glob` now compute `presentationMeta` on every non-nested successful call, a bounded projection over the already-parsed matches or paths. The projection re-applies the retention cap the render already applied, so the retained set is computed twice per call; the input is bounded by the raw-output cap, so this is not a new scaling concern. + +A UI without a search card renders the attached `content` text, so no consumer regresses. The web consumer that renders the structured shape reads `truncated`/`total` and the per-file groups; because the view carries only the retained page, a UI wanting the complete result follows the spill locator in the model-facing text, exactly as the model does. + +## Testing + +`packages/fs/tool-fs-search/tests/presentation.spec.ts` pins the pure layer: `groupMatchesByFile`'s first-seen file order, `grepSearchMeta`/`globSearchMeta` projection with the cap applied and `total` reporting the pre-cap count, the per-line preview budget on a projected match line, and `searchViewFromMeta`'s narrowing of both good shapes plus every malformed case (non-object/array meta, missing or mistyped `truncated`/`total`, unknown `kind`, malformed `files` entries, non-string `paths`). `packages/fs/tool-fs-search/tests/tools.spec.ts` pins the wiring through the real tool registry: a capped `grep`/`glob` execute produces the `SearchMeta` on `result.meta` and `presentResult` builds the search view with `content` attached, a nested `run_code` dispatch computes no meta so `presentResult` falls back, and a failed or cross-shape or malformed result falls back to the generic card. Per-file 100% coverage holds over the search package `src`. + +## Related + +- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary this extends with the `search` result tag. +- [Canonical tool output contract](../architecture/2026-07-20-canonical-tool-output-contract.md) — the value/render/`presentationMeta` split this projection rides; the structured value stays execution-local, the card rides `meta`. +- [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent this mirrors on the backend: a tool projects its result into `presentationMeta` and a `presentResult` view; the search card's web consumer is the analogous follow-up. diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md new file mode 100644 index 0000000000..8b91255094 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md @@ -0,0 +1,51 @@ +# Agent Note: Search render intent — grep and glob emit a structured search card + +Status: implemented + +[English](2026-07-30-search-render-card.md) | 中文 + +## Problem + +`grep` 与 `glob` 返回结构化的规范值——`grep` 是扁平的 `{ matches: [{ path, lineNumber, line }] }`,`glob` 是 `{ paths: string[] }`——但每一个 UI 见到的只有它们面向模型的渲染文本:`grep` 把匹配按文件分组,文件头下是 `Line N:` 行;`glob` 打印换行连接的路径列表;当内联上限({@link module:@deepseek-ai/dsh-tool-fs-search/grep} `grepMaxMatches`,默认 250;{@link module:@deepseek-ai/dsh-tool-fs-search/glob} `globMaxResults`,默认 100)把后续结果溢出到 spill 文件时,两者都追加一段溢出脚注。想把搜索结果渲染成可展开的按文件分组匹配、或渲染成可选择的路径列表的 web 前端,只能去重新解析这段文本。两个工具都已声明了调用期的[渲染意图](../architecture/2026-07-02-tool-render-intent-union.md)(`GenericCallView`,`kind: 'search'`),但没有结果期视图,于是已完成的调用回退到渲染原始文本的通用卡片。 + +结构化的规范值不过线:只有面向模型的渲染文本、以及当工具声明 `output.presentationMeta` 时的一段 JSON 元数据抵达客户端,二者通过 `tool/result` 事件穿线([规范输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md))。因此携带结构化数据的结果期视图必须把该数据投射进 `presentationMeta`,再在 `presentResult` 里读回——正是 `write`/`edit` 的 diff 卡片所走的路径。 + +## Decision + +`packages/core/tools/src/presentation.ts` 向 `ToolResultView` 联合类型加入 `card: 'search'`,即 `SearchResultView`:一个以 `kind` 区分的视图,表达两个工具的形状。`SearchMatchesResultView`(`kind: 'matches'`)以 `files: { path, matches: { lineNumber, line }[] }[]` 携带 `grep` 按文件分组的匹配;`SearchPathsResultView`(`kind: 'paths'`)携带 `glob` 的扁平 `paths: string[]`。两者都携带 `truncated: boolean` 与 `total: number`,以及可选的 `content?: ContentBlock[]`。 + +一个视图两种形状,而非两张卡片,因为两个工具是同一个视觉对象——一个搜索结果——web 消费方先在一个 `card` 值上分派,再在 `kind` 上分派行的形状。区分性的 `kind` 让每种形状各自的字段保持非可选(matches 视图恒有 `files`,paths 视图恒有 `paths`),而不是让所有形状相关字段都变成可选的单一接口。 + +卡片标签只在结果期。搜索调用仍是 `GenericCallView`(`kind: 'search'`):pending 状态没有匹配或路径可展示,因此 `SearchCallView` 能携带的东西不会超出通用标题。这是与 terminal 卡片的不对称之处——terminal 的调用视图携带执行前就存在的命令、cwd 与描述;而搜索的结构化内容只在 `execute` 之后才存在。 + +`packages/fs/tool-fs-search/src/presentation.ts` 拥有投射与收窄。`grepSearchMeta`/`globSearchMeta` 把规范值投射为一段 `SearchMeta`,各工具将其声明为 `output.presentationMeta`;`presentGrepResult`/`presentGlobResult` 通过 `searchViewFromMeta` 把 `result.meta` 读回,并把面向模型的 `result.content` 作为视图的 `content` 附上。投射施加与面向模型渲染相同的内联上限与每行预览预算,并把 `total` 报告为搜索找到的全部结果(截断之前),当上限丢弃了结果时把 `truncated` 置为真。这就是截断诚实性的要点:模型看到的是被截断的内联结果加一段溢出脚注,因此卡片不得把保留的那一页当作完整结果呈现——UI 读取 `truncated`/`total` 去展示截断指示,而非宣称模型从未拥有的完整性。 + +`searchViewFromMeta` 防御性地收窄不透明的 `meta`,对任何畸形或缺失的 payload 返回 `undefined`,与 `diffsFromMeta` 完全一致,因此在较旧或手工编辑过的回放日志上运行的呈现器会回退到通用卡片而非抛错。`presentResult` 对失败结果、对缺失的 meta(嵌套 `run_code` 分发不计算 `presentationMeta`)、对另一个工具的 meta 形状(每个呈现器只收窄到自己的 `kind`)都返回 `undefined`。 + +`SearchMeta` 的成员形状是对象字面量 `type` 别名,而不是视图对外暴露的 `SearchFileMatches`/`SearchLineMatch` 接口。只有 type 别名可以赋值给 `presentationMeta` 返回的 `JsonValue` 索引签名;二者结构完全相同,因此投射出的值仍能读回为 `SearchResultView`。 + +TUI(`packages/ui/tui/src/components/transcript.ts`)无需专用分支:它的结果视图 switch 显式处理 `terminal` 与 `diff`,并落到一个渲染 `view.content ?? this.result?.content` 的通用分支。因为 `SearchResultView` 以 `content` 携带了面向模型的文本,TUI 渲染出的仍是它此前已展示的同一段文本。渲染结构化 `files`/`paths` 形状的 web 前端是后续独立的 PR;本 PR 是后端契约及其两个生产者。 + +## Alternatives considered + +**单一扁平的 `SearchResultView` 接口,带可选的 `files?` 与 `paths?`。** 否决:它让两种形状相关字段在每个值上都成为可选,并允许一个畸形视图同时携带二者或都不携带。`kind` 区分符让每种形状的字段保持必填,并让消费方能穷尽分派。 + +**一个调用期的 `SearchCallView`,镜像 terminal 卡片两侧对称。** 否决:搜索调用在 `execute` 之前没有匹配或路径,视图只会携带 `GenericCallView` 已携带的标题。terminal 卡片的调用视图之所以配得上其标签,是因为命令、cwd 与描述在调用期就存在;而搜索的结构化内容不存在。 + +**用一个专门的通道而非 `presentationMeta` 携带结构化结果。** 否决:规范值是执行局部的、绝不抵达客户端,而 `presentationMeta` 是既有的接缝,它把工具的 JSON 呈现 payload 随 `tool/result` 持久化并穿线回 `presentResult`。再加一条通道只会重复这条路径。 + +## Consequences + +`grep` 与 `glob` 现在在每次非嵌套的成功调用上计算 `presentationMeta`,这是对已解析的匹配或路径做的一次有界投射。投射重新施加渲染已施加过的保留上限,因此每次调用会计算两遍保留集;输入受原始输出上限约束,故这不是新的伸缩性问题。 + +没有搜索卡片的 UI 渲染附上的 `content` 文本,因此没有消费方回退。渲染结构化形状的 web 消费方读取 `truncated`/`total` 与按文件分组;因为视图只携带保留的那一页,想要完整结果的 UI 沿面向模型文本里的 spill 定位符去取,与模型的做法完全一致。 + +## Testing + +`packages/fs/tool-fs-search/tests/presentation.spec.ts` 钉住纯函数层:`groupMatchesByFile` 的首见文件顺序,`grepSearchMeta`/`globSearchMeta` 施加上限后的投射与把 `total` 报告为截断前计数,投射出的匹配行上的每行预览预算,以及 `searchViewFromMeta` 对两种良态形状的收窄外加所有畸形情形(非对象/数组 meta、缺失或类型错误的 `truncated`/`total`、未知 `kind`、畸形 `files` 条目、非字符串 `paths`)。`packages/fs/tool-fs-search/tests/tools.spec.ts` 通过真实工具注册表钉住穿线:一次被截断的 `grep`/`glob` execute 在 `result.meta` 上产出 `SearchMeta`,且 `presentResult` 构建出附带 `content` 的搜索视图;嵌套 `run_code` 分发不计算 meta 于是 `presentResult` 回退;失败、跨形状或畸形结果回退到通用卡片。搜索包 `src` 上维持逐文件 100% 覆盖。 + +## Related + +- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 PR 以 `search` 结果标签扩展的 `card` 标签词汇。 +- [Canonical tool output contract](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投射所乘的 value/render/`presentationMeta` 拆分;结构化值留在执行局部,卡片乘 `meta`。 +- [Web terminal card](2026-07-28-web-terminal-card.md) —— 本 PR 在后端所镜像的先例:工具把结果投射进 `presentationMeta` 与一个 `presentResult` 视图;搜索卡片的 web 消费方是类似的后续工作。 diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index dafa342d5a..7abb71cb40 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -841,7 +841,7 @@ A tool was registered or unregistered, or a scoped restriction changed (the avai 'tools/change'(): void ``` -Source: [`packages/core/tools/src/index.ts:156`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:161`](../../packages/core/tools/src/index.ts) ### `tools/code-dispatch-log` — waterfall @@ -865,7 +865,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri Types: [CodeDispatchLog](../core-data-structures/tools.md) · [ContentBlock](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [ToolRegistry](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:138`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:143`](../../packages/core/tools/src/index.ts) ### `tools/execute` — waterfall @@ -887,7 +887,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor Types: [Scoped](../core-data-structures/scope.md) · [ToolDispatchExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:113`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:118`](../../packages/core/tools/src/index.ts) ### `tools/post-execute` — waterfall @@ -910,7 +910,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts Types: [PostToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:125`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:130`](../../packages/core/tools/src/index.ts) ### `tools/pre-execute` — waterfall @@ -931,7 +931,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv Types: [PreToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:102`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:107`](../../packages/core/tools/src/index.ts) ### `tools/result` — emit @@ -950,7 +950,7 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained Types: [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:146`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:151`](../../packages/core/tools/src/index.ts) ## `workflow/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index c655de3a70..aebc61a3b5 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -2174,7 +2174,7 @@ async execute(exec: ToolExecutionInput): Promise Types: [ScopeKey](../core-data-structures/scope.md) · [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionMode](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolGuard](../core-data-structures/tools.md) · [ToolRestriction](../core-data-structures/tools.md) · [ToolSchema](../core-data-structures/tools.md) -Source: [`packages/core/tools/src/index.ts:700`](../../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:705`](../../packages/core/tools/src/index.ts) ## `ctx.tui` — `TuiExtensionService` (abstract seam) diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 60f7d330d8..20c534ba36 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -2155,6 +2155,26 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ScopeKey', declaration: 'export type ScopeKey = object;', }, + { + name: 'SearchFileMatches', + declaration: 'export interface SearchFileMatches {\n path: string;\n matches: SearchLineMatch[];\n}', + }, + { + name: 'SearchLineMatch', + declaration: 'export interface SearchLineMatch {\n lineNumber: number;\n line: string;\n}', + }, + { + name: 'SearchMatchesResultView', + declaration: 'export interface SearchMatchesResultView {\n card: \'search\';\n kind: \'matches\';\n title?: string;\n files: SearchFileMatches[];\n truncated: boolean;\n total: number;\n content?: ContentBlock[];\n}', + }, + { + name: 'SearchPathsResultView', + declaration: 'export interface SearchPathsResultView {\n card: \'search\';\n kind: \'paths\';\n title?: string;\n paths: string[];\n truncated: boolean;\n total: number;\n content?: ContentBlock[];\n}', + }, + { + name: 'SearchResultView', + declaration: 'export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;', + }, { name: 'SendOptions', declaration: 'export interface SendOptions {\n target: SendTarget;\n wakeup: boolean;\n}', @@ -2697,7 +2717,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'ToolResultView', - declaration: 'export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;', + declaration: 'export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView;', }, { name: 'ToolRunContext', diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index 2caaaa8276..4a91808a4c 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -82,6 +82,11 @@ export type { GenericResultView, TerminalResultView, DiffResultView, + SearchResultView, + SearchMatchesResultView, + SearchPathsResultView, + SearchFileMatches, + SearchLineMatch, } from './presentation.ts' declare module 'cordis' { diff --git a/packages/core/tools/src/presentation.ts b/packages/core/tools/src/presentation.ts index 17b88b822f..338a73faa1 100644 --- a/packages/core/tools/src/presentation.ts +++ b/packages/core/tools/src/presentation.ts @@ -125,7 +125,7 @@ export interface DiffCallView { * `ToolDefinition.presentResult`; omitting the method keeps the pending * title and renders the raw result content. */ -export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView +export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView /** * The default completed card: an optional replacement title and reformatted @@ -176,3 +176,90 @@ export interface DiffResultView { /** The change to show, in file order — applied contextual hunks, or a whole-file diff when there is no before-image. */ diffs: FileDiff[] } + +/** One matched line inside a {@link SearchFileMatches} group: its 1-based line number and text. */ +export interface SearchLineMatch { + /** 1-based line number of the match within its file. */ + lineNumber: number + /** The matched line text, as the tool surfaced it (the per-line preview budget already applied). */ + line: string +} + +/** One file's grouped content matches for a {@link SearchMatchesResultView}, in first-seen file order. */ +export interface SearchFileMatches { + /** The file the matches belong to (the model-facing display path). */ + path: string + /** The file's matched lines, in output order. */ + matches: SearchLineMatch[] +} + +/** + * A completed content search (`grep`) rendered as a search card whose matches are + * grouped by file, so a capable UI can list each file as an expandable group of + * its matched lines. `kind: 'matches'` discriminates this shape from the path + * shape ({@link SearchPathsResultView}) within {@link SearchResultView}. + */ +export interface SearchMatchesResultView { + card: 'search' + kind: 'matches' + /** Replacement title for the completed call. Omit to keep the pending-state title. */ + title?: string + /** Matched lines grouped by file, in first-seen file order. */ + files: SearchFileMatches[] + /** + * Whether the tool capped the inline result: `files` carries only the retained + * matches, not every match the search found. A UI shows a capped indicator so it + * never presents a partial group as complete. + */ + truncated: boolean + /** Total matches the search found before capping (equals the retained count when not `truncated`). */ + total: number + /** + * UI-facing content blocks reproducing the model-facing result text, so a UI + * without a dedicated search card renders it as text. Omit to let the UI render + * the raw result content. + */ + content?: ContentBlock[] +} + +/** + * A completed path search (`glob`) rendered as a search card whose result is a flat + * path list. `kind: 'paths'` discriminates this shape from the grouped-matches + * shape ({@link SearchMatchesResultView}) within {@link SearchResultView}. + */ +export interface SearchPathsResultView { + card: 'search' + kind: 'paths' + /** Replacement title for the completed call. Omit to keep the pending-state title. */ + title?: string + /** The discovered paths, in the tool's result order (the retained page when `truncated`). */ + paths: string[] + /** + * Whether the tool capped the inline result: `paths` carries only the retained + * page, not every path the search found. A UI shows a capped indicator so it + * never presents a partial list as complete. + */ + truncated: boolean + /** Total paths the search found before capping (equals `paths.length` when not `truncated`). */ + total: number + /** + * UI-facing content blocks reproducing the model-facing result text, so a UI + * without a dedicated search card renders it as text. Omit to let the UI render + * the raw result content. + */ + content?: ContentBlock[] +} + +/** + * A completed search rendered as a search card, the result-time view a discovery + * tool (`grep`, `glob`) returns from `presentResult`. One `card: 'search'` view + * with two `kind`-discriminated shapes: grouped-by-file content matches + * ({@link SearchMatchesResultView}) and a flat path list + * ({@link SearchPathsResultView}). Both carry a `truncated`/`total` signal so a UI + * never presents a capped result as complete, and an optional `content` a UI + * without a search card renders as text. There is no call-time analogue: a search + * call stays a {@link GenericCallView} (`kind: 'search'`) because the pending + * state has no matches or paths to show — the structured shape exists only after + * `execute`. + */ +export type SearchResultView = SearchMatchesResultView | SearchPathsResultView diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts index 6d42acee66..8fd2d20ebf 100644 --- a/packages/fs/tool-fs-search/src/glob.ts +++ b/packages/fs/tool-fs-search/src/glob.ts @@ -11,13 +11,14 @@ import type { Context } from 'cordis' import { defineTool } from '@deepseek-ai/dsh-tools' -import type { GenericCallView } from '@deepseek-ai/dsh-tools' +import type { GenericCallView, SearchResultView, ToolResult } from '@deepseek-ai/dsh-tools' import { ItemRetainer } from '@deepseek-ai/dsh-retention' 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 { runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts' +import { globSearchMeta, searchViewFromMeta } from './presentation.ts' import { singleQuote } from './shell-quote.ts' import { acceptedSurfaceValue } from './surface.ts' @@ -136,6 +137,24 @@ export function presentGlobCall(args: { pattern: string; path?: string }): Gener return { card: 'generic', title: `Glob ${args.pattern}${where}`, kind: 'search', rawInput: args.pattern } } +/** + * Completed-call presentation: the search card projected from the result's + * `presentationMeta` (the discovered path list, with the truncation signal), with + * the model-facing result text attached as `content` for a UI without a search + * card. Malformed or absent metadata (an obsolete or hand-edited replayed log) + * falls back to the generic card. + * + * @param _args - the raw tool arguments; unused, the view derives from the result. + * @param result - the final model-facing tool result carrying the projected metadata. + * @returns the search card view, or `undefined` for the generic fallback. + */ +export function presentGlobResult(_args: { pattern: string; path?: string }, result: ToolResult): SearchResultView | undefined { + if (result.isError) return undefined + const view = searchViewFromMeta(result.meta) + if (view === undefined || view.kind !== 'paths') return undefined + return { ...view, content: result.content } +} + /** * Register the `glob` tool and its system-prompt guidance. * @@ -169,6 +188,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { }, }, render: (_args, value) => [{ type: 'text', text: renderGlobPaths(value.paths, caps.maxResults) }], + presentationMeta: (_args, value) => globSearchMeta(value.paths, caps.maxResults), }, async execute(args, exec) { const input = parseGlobArgs(args) @@ -184,6 +204,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { return { paths: all } }, presentCall: presentGlobCall, + presentResult: presentGlobResult, }) ctx.tools.register(tool) diff --git a/packages/fs/tool-fs-search/src/grep.ts b/packages/fs/tool-fs-search/src/grep.ts index aa82749f3f..4f3273f0fb 100644 --- a/packages/fs/tool-fs-search/src/grep.ts +++ b/packages/fs/tool-fs-search/src/grep.ts @@ -12,13 +12,14 @@ import type { Context } from 'cordis' import { defineTool } from '@deepseek-ai/dsh-tools' -import type { GenericCallView } from '@deepseek-ai/dsh-tools' +import type { GenericCallView, SearchResultView, ToolResult } from '@deepseek-ai/dsh-tools' import { ItemRetainer, TextRetainer } from '@deepseek-ai/dsh-retention' 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 { SearchError, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts' +import { grepSearchMeta, searchViewFromMeta } from './presentation.ts' import { singleQuote } from './shell-quote.ts' import { acceptedSurfaceValue } from './surface.ts' @@ -268,6 +269,27 @@ export function presentGrepCall(args: { pattern: string; path?: string; include? return { card: 'generic', title: `Grep ${args.pattern}${where}${filter}`, kind: 'search', rawInput: args.pattern } } +/** + * Completed-call presentation: the search card projected from the result's + * `presentationMeta` (matches grouped by file, with the truncation signal), with + * the model-facing result text attached as `content` for a UI without a search + * card. Malformed or absent metadata (an obsolete or hand-edited replayed log) + * falls back to the generic card. + * + * @param _args - the raw tool arguments; unused, the view derives from the result. + * @param result - the final model-facing tool result carrying the projected metadata. + * @returns the search card view, or `undefined` for the generic fallback. + */ +export function presentGrepResult( + _args: { pattern: string; path?: string; include?: string }, + result: ToolResult, +): SearchResultView | undefined { + if (result.isError) return undefined + const view = searchViewFromMeta(result.meta) + if (view === undefined || view.kind !== 'matches') return undefined + return { ...view, content: result.content } +} + /** * Register the `grep` tool and its system-prompt guidance. * @@ -317,6 +339,7 @@ export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void { type: 'text', text: renderGrepMatches(value.matches, caps.maxMatches, caps.maxLineBytes), }], + presentationMeta: (_args, value) => grepSearchMeta(value.matches, caps.maxMatches, caps.maxLineBytes), }, async execute(args, exec) { const input = parseGrepArgs(args) @@ -335,6 +358,7 @@ export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void { return { matches: all } }, presentCall: presentGrepCall, + presentResult: presentGrepResult, }) ctx.tools.register(tool) diff --git a/packages/fs/tool-fs-search/src/index.ts b/packages/fs/tool-fs-search/src/index.ts index 5930890b7a..0c53776d1e 100644 --- a/packages/fs/tool-fs-search/src/index.ts +++ b/packages/fs/tool-fs-search/src/index.ts @@ -33,7 +33,7 @@ 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_TIMEOUT_MS } from './search-core.ts' -export { GLOB_MAX_RESULTS, GLOB_VCS_EXCLUDES, applyGlobTool, buildGlobCommand, formatGlobOutput, parseGlobArgs, presentGlobCall } from './glob.ts' +export { GLOB_MAX_RESULTS, GLOB_VCS_EXCLUDES, applyGlobTool, buildGlobCommand, formatGlobOutput, parseGlobArgs, presentGlobCall, presentGlobResult } from './glob.ts' export type { GlobInput, GlobToolCaps } from './glob.ts' export { GREP_MAX_LINE_BYTES, @@ -45,9 +45,12 @@ export { parseGrepArgs, parseGrepMatches, presentGrepCall, + presentGrepResult, previewLine, } from './grep.ts' export type { GrepInput, GrepMatch, GrepToolCaps } from './grep.ts' +export { globSearchMeta, grepSearchMeta, groupMatchesByFile, searchViewFromMeta } from './presentation.ts' +export type { SearchMeta } from './presentation.ts' export { RAW_OUTPUT_MAX_BYTES, SEARCH_TIMEOUT_MS, SearchError, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts' export type { RipgrepRun, SearchErrorCode } from './search-core.ts' export { singleQuote } from './shell-quote.ts' diff --git a/packages/fs/tool-fs-search/src/presentation.ts b/packages/fs/tool-fs-search/src/presentation.ts new file mode 100644 index 0000000000..479a64d7d1 --- /dev/null +++ b/packages/fs/tool-fs-search/src/presentation.ts @@ -0,0 +1,149 @@ +/** + * Result-time search-card presentation for `grep` and `glob`. Both tools land on + * one `card: 'search'` render intent ({@link SearchResultView}) with two + * `kind`-discriminated shapes: `grep` projects its matches grouped by file + * ({@link SearchMatchesResultView}), `glob` projects a flat path list + * ({@link SearchPathsResultView}). This module owns the value→`presentationMeta` + * projection each tool declares and the defensive `meta`→view narrowing each + * tool's `presentResult` reads back on replay. + * + * The canonical value never crosses the wire — only the model-facing render text + * and this JSON `meta` do — so the structured shape a UI renders MUST ride in + * `meta`. Each projection applies the SAME inline cap the model-facing render + * applies ({@link module:@deepseek-ai/dsh-tool-fs-search/grep} `grepMaxMatches`, + * {@link module:@deepseek-ai/dsh-tool-fs-search/glob} `globMaxResults`) and reports + * `total` (every result found) and `truncated`, so a UI never presents a capped + * result as complete. + * + * @module @deepseek-ai/dsh-tool-fs-search/presentation + */ + +import type { + SearchFileMatches, + SearchLineMatch, + SearchResultView, +} from '@deepseek-ai/dsh-tools' +import { ItemRetainer } from '@deepseek-ai/dsh-retention' +import type { GrepMatch } from './grep.ts' +import { previewLine } from './grep.ts' + +/** + * The `grep`/`glob` tools' private `tool/result` `meta` payload: the capped, + * structured search result. Attached opaquely (as `JsonValue`) on the tool result + * and persisted with the session log, so `presentResult` reproduces the search + * card on replay. The `matches` shape carries the by-file groups; the `paths` + * shape carries the flat list. Both carry the pre-cap `total` and the `truncated` + * flag. The producing tool owns and narrows this opaque shape. + * + * The member shapes use object-literal `type` aliases rather than the + * {@link SearchFileMatches}/{@link SearchLineMatch} interfaces because only a type + * alias is assignable to the `JsonValue` index signature `presentationMeta` + * returns; the two are structurally identical, so the projected value still reads + * back as a {@link SearchResultView}. + */ +export type SearchMeta = + | { kind: 'matches'; files: MetaFileMatches[]; truncated: boolean; total: number } + | { kind: 'paths'; paths: string[]; truncated: boolean; total: number } + +/** One matched line in {@link SearchMeta} (the JSON-assignable form of {@link SearchLineMatch}). */ +type MetaLineMatch = { lineNumber: number; line: string } + +/** One file's grouped matches in {@link SearchMeta} (the JSON-assignable form of {@link SearchFileMatches}). */ +type MetaFileMatches = { path: string; matches: MetaLineMatch[] } + +/** + * Group flat matches by file (first-seen order) into the structured by-file shape + * a UI renders as expandable per-file groups. The grouping matches the + * model-facing text grouping + * ({@link module:@deepseek-ai/dsh-tool-fs-search/grep} `formatGrepMatches`), so + * card and text agree about file order and membership. + * + * @param matches - the retained matches to group, in output order. + * @returns one entry per file, in first-seen order. + */ +export function groupMatchesByFile(matches: GrepMatch[]): MetaFileMatches[] { + const byFile = new Map() + for (const match of matches) { + const entry: MetaLineMatch = { lineNumber: match.lineNumber, line: match.line } + const group = byFile.get(match.path) + if (group !== undefined) group.push(entry) + else byFile.set(match.path, [entry]) + } + return Array.from(byFile, ([path, fileMatches]) => ({ path, matches: fileMatches })) +} + +/** + * Project the canonical `grep` matches into {@link SearchMeta} for the search + * card. Applies the per-line preview budget and the inline match cap exactly as + * the model-facing render does, groups the retained matches by file, and reports + * `total` (every parsed match) and `truncated`. + * + * @param matches - every match the search parsed (the canonical value's matches). + * @param maxMatches - the inline match cap (the `grepMaxMatches` config). + * @param maxLineBytes - the per-matched-line preview budget in bytes. + * @returns the `matches`-shaped search metadata. + */ +export function grepSearchMeta(matches: GrepMatch[], maxMatches: number, maxLineBytes: number): SearchMeta { + const retainer = new ItemRetainer({ kind: 'head', maxItems: maxMatches }) + for (const match of matches) retainer.push({ ...match, line: previewLine(match.line, maxLineBytes) }) + const retained = retainer.finish() + return { kind: 'matches', files: groupMatchesByFile(retained.items), truncated: retained.truncated, total: retained.seen } +} + +/** + * Project the canonical `glob` paths into {@link SearchMeta} for the search card. + * Applies the inline path cap exactly as the model-facing render does and reports + * `total` (every discovered path) and `truncated`. + * + * @param paths - every path the search discovered (the canonical value's paths). + * @param maxResults - the inline path cap (the `globMaxResults` config). + * @returns the `paths`-shaped search metadata. + */ +export function globSearchMeta(paths: string[], maxResults: number): SearchMeta { + const retainer = new ItemRetainer({ kind: 'head', maxItems: maxResults }) + for (const path of paths) retainer.push(path) + const retained = retainer.finish() + return { kind: 'paths', paths: retained.items, truncated: retained.truncated, total: retained.seen } +} + +/** Whether `value` is a valid {@link SearchLineMatch} (defensive narrowing from opaque `meta`). */ +function isSearchLineMatch(value: unknown): value is SearchLineMatch { + if (typeof value !== 'object' || value === null || Array.isArray(value)) return false + const { lineNumber, line } = value as Record + return typeof lineNumber === 'number' && typeof line === 'string' +} + +/** Whether `value` is a valid {@link SearchFileMatches} (defensive narrowing from opaque `meta`). */ +function isSearchFileMatches(value: unknown): value is SearchFileMatches { + if (typeof value !== 'object' || value === null || Array.isArray(value)) return false + const { path, matches } = value as Record + return typeof path === 'string' && Array.isArray(matches) && matches.every(isSearchLineMatch) +} + +/** + * Narrow opaque live or replayed result metadata to a {@link SearchResultView}. + * Malformed metadata returns `undefined` so `presentResult` can fall back to the + * generic card instead of throwing during replay of an older or hand-edited log. + * The returned view carries no `content`; the caller attaches the model-facing + * result text so a UI without a search card renders it as text. + * + * @param meta - result metadata (the {@link SearchMeta} the tool projected). + * @returns the search view, or `undefined` for absent or malformed metadata. + */ +export function searchViewFromMeta(meta: unknown): SearchResultView | undefined { + if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) return undefined + const record = meta as Record + const { truncated, total } = record + if (typeof truncated !== 'boolean' || typeof total !== 'number') return undefined + if (record.kind === 'matches') { + const { files } = record + if (!Array.isArray(files) || !files.every(isSearchFileMatches)) return undefined + return { card: 'search', kind: 'matches', files: files, truncated, total } + } + if (record.kind === 'paths') { + const { paths } = record + if (!Array.isArray(paths) || !paths.every((path): path is string => typeof path === 'string')) return undefined + return { card: 'search', kind: 'paths', paths, truncated, total } + } + return undefined +} diff --git a/packages/fs/tool-fs-search/tests/presentation.spec.ts b/packages/fs/tool-fs-search/tests/presentation.spec.ts new file mode 100644 index 0000000000..7f3131a2ab --- /dev/null +++ b/packages/fs/tool-fs-search/tests/presentation.spec.ts @@ -0,0 +1,129 @@ +/** + * Unit tests for the search-card presentation layer (`src/presentation.ts`): the + * canonical value → `presentationMeta` projections (`grepSearchMeta`, + * `globSearchMeta`, `groupMatchesByFile`) and the defensive `meta` → view + * narrowing (`searchViewFromMeta`). These pin the by-file grouping, the inline + * cap and `truncated`/`total` honesty, and the malformed-metadata fallback a + * replayed or hand-edited log can deliver. + */ + +import { describe, expect, it } from 'vitest' +import type { JsonValue } from '@deepseek-ai/dsh-session' +import { + globSearchMeta, + grepSearchMeta, + groupMatchesByFile, + searchViewFromMeta, +} from '../src/presentation.ts' +import type { GrepMatch } from '../src/grep.ts' + +const match = (path: string, lineNumber: number, line: string): GrepMatch => ({ path, lineNumber, line }) + +describe('groupMatchesByFile', () => { + it('groups matches by first-seen file order, keeping line/lineNumber only', () => { + expect(groupMatchesByFile([ + match('b.ts', 2, 'x'), + match('a.ts', 1, 'y'), + match('b.ts', 5, 'z'), + ])).toEqual([ + { path: 'b.ts', matches: [{ lineNumber: 2, line: 'x' }, { lineNumber: 5, line: 'z' }] }, + { path: 'a.ts', matches: [{ lineNumber: 1, line: 'y' }] }, + ]) + }) + + it('returns an empty list for no matches', () => { + expect(groupMatchesByFile([])).toEqual([]) + }) +}) + +describe('grepSearchMeta', () => { + it('projects grouped matches with total and a false truncation flag within the cap', () => { + const meta = grepSearchMeta([match('a.ts', 1, 'one'), match('a.ts', 2, 'two')], 10, 2000) + expect(meta).toEqual({ + kind: 'matches', + files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'one' }, { lineNumber: 2, line: 'two' }] }], + truncated: false, + total: 2, + }) + }) + + it('caps the retained matches and reports the pre-cap total when truncated', () => { + const meta = grepSearchMeta([match('a.ts', 1, 'one'), match('a.ts', 2, 'two'), match('b.ts', 3, 'three')], 2, 2000) + expect(meta).toEqual({ + kind: 'matches', + files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'one' }, { lineNumber: 2, line: 'two' }] }], + truncated: true, + total: 3, + }) + }) + + it('applies the per-line preview budget (UTF-8 boundary) to the projected line', () => { + const meta = grepSearchMeta([match('a.txt', 1, 'aéaéaéaé')], 10, 7) + expect(meta).toMatchObject({ kind: 'matches', files: [{ path: 'a.txt', matches: [{ lineNumber: 1, line: 'aéaéa (line truncated)' }] }] }) + }) +}) + +describe('globSearchMeta', () => { + it('projects the path list with total and a false truncation flag within the cap', () => { + expect(globSearchMeta(['a.ts', 'b.ts'], 10)).toEqual({ kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: false, total: 2 }) + }) + + it('caps the retained paths and reports the pre-cap total when truncated', () => { + expect(globSearchMeta(['a.ts', 'b.ts', 'c.ts'], 2)).toEqual({ kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3 }) + }) +}) + +describe('searchViewFromMeta (defensive narrowing)', () => { + // The narrowing accepts an opaque JsonValue; a malformed payload is not a + // statically-valid JsonValue, so route every case through one cast helper that + // mirrors how a hand-edited/older session log delivers arbitrary shapes. + const m = (value: unknown): JsonValue | undefined => value as JsonValue | undefined + + it('narrows a well-formed matches payload into a matches view', () => { + const meta = { kind: 'matches', files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'x' }] }], truncated: true, total: 5 } + expect(searchViewFromMeta(m(meta))).toEqual({ card: 'search', ...meta }) + }) + + it('narrows a well-formed paths payload into a paths view', () => { + const meta = { kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: false, total: 2 } + expect(searchViewFromMeta(m(meta))).toEqual({ card: 'search', ...meta }) + }) + + it('rejects undefined / non-object / array meta', () => { + expect(searchViewFromMeta(undefined)).toBeUndefined() + expect(searchViewFromMeta(null)).toBeUndefined() + expect(searchViewFromMeta(m('nope'))).toBeUndefined() + expect(searchViewFromMeta(m([]))).toBeUndefined() + }) + + it('rejects a payload with a missing / mistyped truncated or total field', () => { + expect(searchViewFromMeta(m({ kind: 'paths', paths: [], total: 0 }))).toBeUndefined() + expect(searchViewFromMeta(m({ kind: 'paths', paths: [], truncated: 'no', total: 0 }))).toBeUndefined() + expect(searchViewFromMeta(m({ kind: 'paths', paths: [], truncated: false }))).toBeUndefined() + expect(searchViewFromMeta(m({ kind: 'paths', paths: [], truncated: false, total: '0' }))).toBeUndefined() + }) + + it('rejects an unknown or missing kind discriminant', () => { + expect(searchViewFromMeta(m({ kind: 'other', truncated: false, total: 0 }))).toBeUndefined() + expect(searchViewFromMeta(m({ truncated: false, total: 0 }))).toBeUndefined() + }) + + it('rejects a matches payload with a malformed files array', () => { + const base = { kind: 'matches', truncated: false, total: 1 } + expect(searchViewFromMeta(m({ ...base, files: 'x' }))).toBeUndefined() + expect(searchViewFromMeta(m({ ...base, files: [null] }))).toBeUndefined() + expect(searchViewFromMeta(m({ ...base, files: ['x'] }))).toBeUndefined() + expect(searchViewFromMeta(m({ ...base, files: [[]] }))).toBeUndefined() + expect(searchViewFromMeta(m({ ...base, files: [{ path: 1, matches: [] }] }))).toBeUndefined() + expect(searchViewFromMeta(m({ ...base, files: [{ path: 'a', matches: 'x' }] }))).toBeUndefined() + expect(searchViewFromMeta(m({ ...base, files: [{ path: 'a', matches: [null] }] }))).toBeUndefined() + expect(searchViewFromMeta(m({ ...base, files: [{ path: 'a', matches: [{ lineNumber: '1', line: 'x' }] }] }))).toBeUndefined() + expect(searchViewFromMeta(m({ ...base, files: [{ path: 'a', matches: [{ lineNumber: 1, line: 2 }] }] }))).toBeUndefined() + }) + + it('rejects a paths payload with a non-array or non-string-element paths field', () => { + const base = { kind: 'paths', truncated: false, total: 1 } + expect(searchViewFromMeta(m({ ...base, paths: 'x' }))).toBeUndefined() + expect(searchViewFromMeta(m({ ...base, paths: [1] }))).toBeUndefined() + }) +}) diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index 9ec1c374e1..6d55395e3a 100644 --- a/packages/fs/tool-fs-search/tests/tools.spec.ts +++ b/packages/fs/tool-fs-search/tests/tools.spec.ts @@ -27,7 +27,9 @@ import { formatGrepMatches, parseGrepMatches, presentGlobCall, + presentGlobResult, presentGrepCall, + presentGrepResult, previewLine, toWorkdirRelative, } from '@deepseek-ai/dsh-tool-fs-search' @@ -802,6 +804,74 @@ describe('presentation', () => { expect(presentGrepCall({ pattern: 'todo' })).toMatchObject({ card: 'generic', title: 'Grep todo', kind: 'search' }) expect(presentGrepCall({ pattern: 'todo', path: 'src', include: '*.ts' }).title).toBe('Grep todo in src (*.ts)') }) + + 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([ + matchLine('a.ts', 1, 'one'), + matchLine('a.ts', 2, 'two'), + matchLine('b.ts', 3, 'three'), + '', + ].join('\n')) + const result = await call(ctx, 'grep', { pattern: 'e' }, { agent: agent('/w') }) + if (result.isError) throw new Error('expected grep success') + // The presentationMeta projection rides the result meta (a surface call). + expect(result.meta).toEqual({ + kind: 'matches', + files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'one' }, { lineNumber: 2, line: 'two' }] }], + truncated: true, + total: 3, + }) + const view = presentGrepResult({ pattern: 'e' }, result) + expect(view).toEqual({ + card: 'search', + kind: 'matches', + files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'one' }, { lineNumber: 2, line: 'two' }] }], + truncated: true, + total: 3, + content: result.content, + }) + }) + + 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 result = await call(ctx, 'glob', { pattern: '*.ts' }, { agent: agent('/w') }) + if (result.isError) throw new Error('expected glob success') + expect(result.meta).toEqual({ kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3 }) + const view = presentGlobResult({ pattern: '*.ts' }, result) + expect(view).toEqual({ card: 'search', kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3, content: result.content }) + }) + + 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 result = await call(ctx, 'grep', { pattern: 'o' }, { + agent: agent('/w'), + parent: Symbol('run_code') as ToolExecutionToken, + }) + if (result.isError) throw new Error('expected grep success') + expect(result.meta).toBeUndefined() + expect(presentGrepResult({ pattern: 'o' }, result)).toBeUndefined() + }) + + it('presentResult returns undefined for a failed result and for the other tool’s meta shape', () => { + const errorResult = { content: [{ type: 'text' as const, text: 'boom' }], isError: true } + expect(presentGrepResult({ pattern: 'x' }, errorResult)).toBeUndefined() + expect(presentGlobResult({ pattern: '*' }, errorResult)).toBeUndefined() + // A grep result carrying a paths-shaped meta (and vice versa) is not this + // tool's shape: each presenter narrows to its own kind and otherwise falls back. + const pathsResult = { content: [], isError: false, meta: { kind: 'paths', paths: ['a.ts'], truncated: false, total: 1 } } + const matchesResult = { content: [], isError: false, meta: { kind: 'matches', files: [], truncated: false, total: 0 } } + expect(presentGrepResult({ pattern: 'x' }, pathsResult)).toBeUndefined() + expect(presentGlobResult({ pattern: '*' }, matchesResult)).toBeUndefined() + }) + + it('presentResult falls back to the generic card on malformed replayed meta', () => { + const malformed = { content: [], isError: false, meta: { kind: 'matches', files: 'nope', truncated: false, total: 0 } } + expect(presentGrepResult({ pattern: 'x' }, malformed)).toBeUndefined() + expect(presentGlobResult({ pattern: '*' }, { content: [], isError: false, meta: 42 })).toBeUndefined() + }) }) describe('helpers', () => { From 41ce92776ea58af06ed40b967f8ae63982512871 Mon Sep 17 00:00:00 2001 From: Chinesezjc Date: Thu, 30 Jul 2026 17:52:59 +0800 Subject: [PATCH 02/43] docs: regenerate config and event catalogs for the search card tag The re-exports for SearchResultView shift line numbers in packages/core/tools; regenerate the generated docs the static gate checks (cordis catalog was already regenerated with the feature commit). --- docs/config-catalog.md | 4 ++-- docs/event-producer-consumer.md | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 191d96b255..4d47d6ec01 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1650,7 +1650,7 @@ export interface Config { } ``` -Source: [`packages/fs/tool-fs-search/src/index.ts:62`](../packages/fs/tool-fs-search/src/index.ts) +Source: [`packages/fs/tool-fs-search/src/index.ts:65`](../packages/fs/tool-fs-search/src/index.ts) ## `@deepseek-ai/dsh-tool-goal` @@ -1890,7 +1890,7 @@ export interface Config { export type ToolPresentationMode = 'native' | 'code' | 'both' ``` -Source: [`packages/core/tools/src/index.ts:578`](../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:583`](../packages/core/tools/src/index.ts) ## `@deepseek-ai/dsh-tui` diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index b9538b89d5..bb6b1197b7 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -44,12 +44,12 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) | | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | | `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:41`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - | -| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:156`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | -| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:138`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) | -| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:113`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`timeout-policy`](../packages/timeout/timeout-policy) | -| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:125`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search), [`workspace-context`](../packages/context/workspace-context) | -| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:102`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) | -| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:146`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) | +| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:161`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | +| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:143`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) | +| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:118`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`timeout-policy`](../packages/timeout/timeout-policy) | +| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:130`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search), [`workspace-context`](../packages/context/workspace-context) | +| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:107`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) | +| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:151`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) | | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:81`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:91`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | From 7a60a236bc3a01c175ec5df61733cd33f84cb6cb Mon Sep 17 00:00:00 2001 From: Chinesezjc Date: Thu, 30 Jul 2026 18:15:38 +0800 Subject: [PATCH 03/43] feat(web): render read tool output as a line-numbered code card MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consume the card:'read' result view (path, numbered lines, totalLines, lang) the read backend PR added. ReadBlock (ui-primitives) draws a per-line gutter with each line's own file number, shiki highlighting via a new highlightLines returning per-line token arrays, a 显示 X / Y 行 window note, a height cap matching TerminalBlock, and a copy control. read-card-model is the single resultView derivation; a keyed ReadRow registers under read with the card resident under its path-link summary. The generic fallback and the details panel are read-aware. Fixture gains a windowed read turn for the built-boot snapshot. --- ...026-07-30-web-read-card-frontend.i18n.yaml | 6 + .../2026-07-30-web-read-card-frontend.md | 48 +++ .../2026-07-30-web-read-card-frontend.zh.md | 48 +++ .../client/connection/src/client/fixture.ts | 58 +++- .../ui-conversation/src/client/apply.ts | 5 + .../client/chat/GenericToolCard.module.css | 12 + .../src/client/chat/GenericToolCard.tsx | 18 +- .../src/client/contract/read-card-model.ts | 75 +++++ .../src/client/contract/tool-call-model.ts | 9 +- .../client/skeleton/DetailsPanel.module.css | 6 + .../src/client/skeleton/DetailsPanel.tsx | 13 +- .../src/client/toolviews/read-row.module.css | 93 ++++++ .../src/client/toolviews/read-row.tsx | 100 +++++++ .../ui-conversation/tests/chat-apply.spec.tsx | 6 +- .../ui-conversation/tests/read-card.spec.tsx | 282 ++++++++++++++++++ .../ui-primitives/src/ReadBlock.module.css | 117 ++++++++ .../client/ui-primitives/src/ReadBlock.tsx | 156 ++++++++++ packages/client/ui-primitives/src/index.ts | 2 + .../ui-primitives/src/markdown/highlight.ts | 40 +++ .../ui-primitives/tests/read-block.spec.tsx | 215 +++++++++++++ 20 files changed, 1297 insertions(+), 12 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md create mode 100644 .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md create mode 100644 packages/client/ui-conversation/src/client/chat/GenericToolCard.module.css create mode 100644 packages/client/ui-conversation/src/client/contract/read-card-model.ts create mode 100644 packages/client/ui-conversation/src/client/toolviews/read-row.module.css create mode 100644 packages/client/ui-conversation/src/client/toolviews/read-row.tsx create mode 100644 packages/client/ui-conversation/tests/read-card.spec.tsx create mode 100644 packages/client/ui-primitives/src/ReadBlock.module.css create mode 100644 packages/client/ui-primitives/src/ReadBlock.tsx create mode 100644 packages/client/ui-primitives/tests/read-block.spec.tsx diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml new file mode 100644 index 0000000000..9ed8258368 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md +2026-07-30-web-read-card-frontend.md: 3d1893b72dc9ef8fed3ee3d92e52980b3eb06743 +2026-07-30-web-read-card-frontend.zh.md: acfb31a8e6306a90f634075754074e163d2431e1 diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md new file mode 100644 index 0000000000..3d1893b72d --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md @@ -0,0 +1,48 @@ +# Agent Note: Web read card frontend — the read tool's line window renders line-numbered and highlighted + +Status: implemented + +English | [中文](2026-07-30-web-read-card-frontend.zh.md) + +## Problem + +The [read backend](2026-07-30-web-read-card.md) added a fourth render-intent card, `card: 'read'`, to `ToolResultView`: a settled read now carries `{ path, lines: [{ number, text }], totalLines, lang? }` onto the conversation snapshot as `resultView`. That data reaches the browser, but the Web client had no consumer for it. Every read row derived from args alone and the details panel flattened the result's content blocks into one `
`, so a read showed as `N: text`-prefixed plain text with no gutter, no syntax highlighting, and no "showing N of M" affordance for a windowed read. The [web terminal card](2026-07-28-web-terminal-card.md) established the pattern for consuming a structured card; the read card follows it, result-side only.
+
+## Decision
+
+`ReadBlock` is a `ui-primitives` component that renders a read result as a line-numbered, optionally syntax-highlighted file view, and both Web render sites for a read consume the read render intent through it: the chat tool row (resident under the summary line) and the details panel's Output section. `ui-conversation/src/client/contract/read-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so the two sites cannot disagree.
+
+**A new `ReadBlock` primitive, not an extension of `CodeBlock`.** `CodeBlock` already does shiki highlighting with a language banner and a copy control, but a read view needs a per-line gutter carrying each line's own file number, which `CodeBlock` renders as a single `
` tree with no per-line structure. Extending `CodeBlock` with an optional gutter would push a read-specific concern (windowed line numbers, a "showing N of M" note, a height cap) onto every markdown fence and every `run_code` body that shares that component. Instead `ReadBlock` reuses the part that is genuinely shared: the shiki grammar singleton in `markdown/highlight.ts`. A new `highlightLines(code, lang)` there tokenizes into shiki's own per-line token arrays (`codeToTokens`) rather than the single-`
` HTML `highlightToHtml` produces, so the block can place one gutter number per line and still color the content through the same `--shiki-*` custom properties on the same grammar allowlist. The height cap and its head/tail expand arithmetic are copied from `TerminalBlock` (`ceil(max/2)` head plus the remaining tail), so a long read and a long command output collapse at the same place. The copy control writes the window's raw text (the lines joined by newlines), never the gutter numbers or the banner.
+
+`readCardModel` is result-side only, mirroring the backend: a read call carries no content until `execute` returns, so the pending call stays a `GenericCallView` (`kind: 'read'`) and this returns null for a running read — the row keeps its args-derived summary until the result arrives. It also returns null for a settled call whose result view is not a read card, including a `card` value this UI version does not know (which arrives over the wire and cannot be trusted to be a compiled variant) and the read tool's own generic fallback for an error result. The card's banner label is the read view's `title` when the tool supplied one (the contract's replacement-title rule), otherwise the file path relativized to the session workspace so a workspace-rooted absolute path shows the same short form the row summary shows. The model copies the frozen line array into the primitive's own line shape, so the card never holds a reference into the runtime's snapshot cache.
+
+The chat row renders the card **resident** under the summary line, capped at `CHAT_READ_MAX_LINES` (8, half the primitive's default), the same posture `BashRow` gives a terminal card — the block's internal expander keeps a long read from taking over the message flow. Two render sites carry it: the keyed `ReadRow` (registered under `read` in `apply.ts`, the load-order seam being `inject: ['slots', 'conversation']` exactly as the bash sample) whose summary is the file path as an openable host link, and `GenericToolCard`'s fallback for a read-declaring tool without its own keyed row (e.g. `web_fetch`, which classifies to the `read` variant). The details panel renders the same card at the primitive's own full-height cap (16), because the panel is the single-call reading surface.
+
+Whole-row collapse/expand (defaulting every tool call to collapsed) is a separate later change that will flip every resident card at once; this note's card is resident, matching the terminal card it sits beside.
+
+## Alternatives considered
+
+**Extend `CodeBlock` with an optional line-number gutter and `startLine`.** Rejected: it imposes a read-specific gutter, a windowed-count note, and a height cap on every markdown fence and `run_code` body that shares `CodeBlock`, for no benefit to those callers. The genuinely shared surface is the shiki grammar singleton, which both blocks reuse through `highlight.ts`; the chrome around it differs (a read has a gutter and a window note, a fence has neither), so a second small primitive is the correct split, exactly as `TerminalBlock` is a second primitive over the same tokens rather than a `CodeBlock` mode.
+
+**Reuse `highlightToHtml` and inject gutter numbers with CSS counters.** Rejected: the single-`
` HTML shiki emits has no per-line boundary a gutter can hang a file line number off (a windowed read's numbers start above 1 and are not a simple CSS counter increment), and parsing the numbers back out of the HTML would be fragile. `codeToTokens` gives the per-line token structure directly.
+
+## Consequences
+
+`ui-primitives` gains `ReadBlock` and `highlightLines`; no new runtime dependency (shiki was already present for `CodeBlock`). `ReadBlock` reads only the read view's fields, so it stays a pure function of what the render intent carries — no session lookups, replay-safe like the presenters that produce the view. A UI without the read capability still gets the backend's `content` fallback (the envelope-stripped text) through the generic card, unchanged.
+
+A read row in the Web chat now carries the file content resident, a deliberate density increase over a summary-only row, bounded by the chat cap. A `run_code` sub-dispatch does not reach a read card on the shipped wire for the same reason a nested bash call does not reach a terminal card: `session.ts` folds `tool/code-dispatch(-start)` with `resultView: null`, so a nested read keeps the generic flattened form.
+
+## Testing
+
+`packages/client/ui-primitives/tests/read-block.spec.tsx` pins the primitive and the token path: `highlightLines`' per-line css-variables runs, its trailing-terminator-line drop and the genuinely-blank-final-line case, and its `undefined` for an unknown/absent language; and `ReadBlock`'s gutter-numbered rows keeping the file's own numbers, the highlighted-vs-plain content arms, the banner (label, language, the count note only when the read is a window), the head/tail height cap with its `aria-expanded` toggle, and the copy control writing the window's raw text on both the accepted and refused clipboard paths. Both `ReadBlock.tsx` and `highlight.ts` hold per-file 100% coverage (the latter over this spec plus `code-block.spec.tsx`, which covers `highlightToHtml`).
+
+`packages/client/ui-conversation/tests/read-card.spec.tsx` pins the wiring at every render site: `readCardModel`'s derivation and each null arm (running read, no view, generic view, unknown card), the result title replacing the relativized path, the path relativization against the workspace, the copy-not-alias of the frozen line array; the resident card in `GenericToolCard`'s fallback and in the keyed `ReadRow` (plus its path link opening the host, its running/error/stopped states, and its `read`-key registration); and the panel's Output section rendering the read card at full height while keeping the JSON Input section, with the running-read placeholder and non-read flattened-pre arms. That file sits on the coverage `exclude` list (`ui-conversation/src/*`), so it is written against no gate pressure.
+
+The fixture (`packages/client/connection/src/client/fixture.ts`) gains turn 66, a `read` call whose result view is a windowed read (lines starting at file line 41, `totalLines` 180, a `ts` hint), so the built-boot snapshot and a live `?fixture` server show the read card with its gutter numbers, highlighting, and count note. It is named `read` to exercise the keyed `ReadRow`; the render-site fallback row is already covered by the read sub-dispatches in the turn 64 `run_code` sample. It is ordered before the todo turn (now 67) for the same reason the terminal sample is: the standing plan retires at the next `turn/start`.
+
+## Related
+
+- [Read card backend](2026-07-30-web-read-card.md) — adds the `card: 'read'` result view this consumes; produces the `lines`/`totalLines`/`lang` this renders.
+- [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent this follows: a `ui-primitives` block, a `contract/*-card-model.ts` derivation, a keyed row, and making `GenericToolCard`/`DetailsPanel` card-aware.
+- [Web client syntax highlighting](../process/2026-07-26-web-syntax-highlighting-shiki.md) — owns `CodeBlock` and the shiki `highlight.ts` singleton this extends with a per-line token path.
+- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary; the Web client is now a full consumer of the `read` arm.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
new file mode 100644
index 0000000000..acfb31a8e6
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
@@ -0,0 +1,48 @@
+# Agent Note: Web 读取卡片前端 —— 读取工具的行窗口以带行号、语法高亮的形式渲染
+
+Status: implemented
+
+[English](2026-07-30-web-read-card-frontend.md) | 中文
+
+## Problem
+
+[读取后端](2026-07-30-web-read-card.md)给 `ToolResultView` 增加了第四种渲染意图卡片 `card: 'read'`:一次已结算的读取现在会把 `{ path, lines: [{ number, text }], totalLines, lang? }` 作为 `resultView` 带到会话快照上。这份数据能到达浏览器,但 Web 客户端没有消费者。每个读取行都仅从参数派生,详情面板把结果的 content block 摊平进一个 `
`,于是读取显示为带 `N: text` 前缀的纯文本,没有行号栏、没有语法高亮,也没有窗口读取的"显示 N / M"提示。[web 终端卡片](2026-07-28-web-terminal-card.md)确立了消费一个结构化卡片的模式;读取卡片沿用它,只在结果侧。
+
+## Decision
+
+`ReadBlock` 是一个 `ui-primitives` 组件,把一次读取结果渲染成带行号、可选语法高亮的文件视图,读取的两个 Web 渲染点都通过它消费读取渲染意图:聊天工具行(常驻在摘要行之下)与详情面板的 Output 区段。`ui-conversation/src/client/contract/read-card-model.ts` 是把快照的 `resultView` 转成组件 props 的唯一位置,因此两个渲染点不会产生分歧。
+
+**新建一个 `ReadBlock` primitive,而不是扩展 `CodeBlock`。** `CodeBlock` 已经带语言横幅和复制控件做 shiki 高亮,但读取视图需要一个每行带该行自身文件行号的行号栏,而 `CodeBlock` 把内容渲染为单个 `
` 树、没有逐行结构。给 `CodeBlock` 加一个可选行号栏会把读取专属的关切(窗口行号、"显示 N / M"提示、高度上限)强加给共享该组件的每个 markdown 代码围栏和每个 `run_code` 程序体。`ReadBlock` 转而复用真正共享的部分:`markdown/highlight.ts` 里的 shiki 语法单例。那里新增的 `highlightLines(code, lang)` 把代码切成 shiki 自己的逐行 token 数组(`codeToTokens`),而不是 `highlightToHtml` 产出的单 `
` HTML,于是该 block 能每行放一个行号、同时用同一套 `--shiki-*` 自定义属性、同一份语法白名单给内容上色。高度上限及其头/尾展开算法照抄自 `TerminalBlock`(`ceil(max/2)` 行头部加剩余的尾部),因此长读取和长命令输出在同一处折叠。复制控件写入窗口的原始文本(各行以换行拼接),绝不含行号栏或横幅。
+
+`readCardModel` 只在结果侧,与后端对称:一次读取调用在 `execute` 返回前不带任何内容,因此挂起中的调用保持为 `GenericCallView`(`kind: 'read'`),本函数对运行中的读取返回 null —— 该行保持其从参数派生的摘要,直到结果到达。它对结果视图不是读取卡片的已结算调用也返回 null,包括本 UI 版本不认识的 `card` 值(它从线路到来、不能被信任为一个已编译的变体)以及读取工具对错误结果自己的通用回退。卡片横幅标签在工具提供 `title` 时取它(契约的替换标题规则),否则取相对于会话工作区化简后的文件路径,使工作区根下的绝对路径显示为与行摘要相同的短形式。该 model 把冻结的行数组复制进 primitive 自己的行形状,因此卡片绝不持有指向运行时快照缓存的引用。
+
+聊天行把卡片**常驻**渲染在摘要行之下,上限 `CHAT_READ_MAX_LINES`(8,是 primitive 默认值的一半),与 `BashRow` 对终端卡片的姿态相同 —— block 的内部展开器让长读取不会占据整个消息流。两个渲染点承载它:keyed `ReadRow`(在 `apply.ts` 里以 `read` 键注册,加载顺序接缝为 `inject: ['slots', 'conversation']`,与 bash 样例完全一致),其摘要是作为可打开的宿主链接的文件路径;以及 `GenericToolCard` 对没有自己 keyed 行的读取声明工具(例如归到 `read` 变体的 `web_fetch`)的回退。详情面板以 primitive 自己的全高上限(16)渲染同一张卡片,因为面板是单次调用的阅读界面。
+
+整行折叠/展开(把每个工具调用默认折叠)是一个单独的后续改动,它会一次性翻转每张常驻卡片;本 note 的卡片是常驻的,与它旁边的终端卡片一致。
+
+## Alternatives considered
+
+**给 `CodeBlock` 加一个可选行号栏和 `startLine`。** 拒绝:这会把读取专属的行号栏、窗口计数提示和高度上限强加给共享 `CodeBlock` 的每个 markdown 围栏和 `run_code` 程序体,对那些调用者毫无好处。真正共享的界面是 shiki 语法单例,两个 block 都通过 `highlight.ts` 复用它;围绕它的外壳各不相同(读取有行号栏和窗口提示,围栏两者都没有),因此第二个小 primitive 是正确的切分 —— 正如 `TerminalBlock` 是基于同一套 token 的第二个 primitive,而不是 `CodeBlock` 的一种模式。
+
+**复用 `highlightToHtml`,用 CSS counter 注入行号。** 拒绝:shiki 产出的单 `
` HTML 没有可供行号栏挂上文件行号的逐行边界(窗口读取的行号从大于 1 处开始,不是简单的 CSS counter 自增),而从 HTML 里把行号解析回来又很脆弱。`codeToTokens` 直接给出逐行 token 结构。
+
+## Consequences
+
+`ui-primitives` 增加 `ReadBlock` 和 `highlightLines`;没有新的运行时依赖(shiki 已因 `CodeBlock` 存在)。`ReadBlock` 只读取读取视图的字段,因此保持为渲染意图所承载内容的纯函数 —— 无会话查询,与产出该视图的 presenter 一样可安全回放。没有读取能力的 UI 仍通过通用卡片拿到后端的 `content` 回退(剥掉外壳的文本),保持不变。
+
+Web 聊天里的读取行现在常驻承载文件内容,是相对纯摘要行的一次刻意的密度增加,受聊天上限约束。`run_code` 子派发在已发布的线路上到不了读取卡片,与嵌套 bash 调用到不了终端卡片同因:`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `resultView: null`,因此嵌套读取保持通用的摊平形式。
+
+## Testing
+
+`packages/client/ui-primitives/tests/read-block.spec.tsx` 固定 primitive 与 token 路径:`highlightLines` 的逐行 css-variables 运行、它对尾部终止行的丢弃与真正空白末行的情形、以及它对未知/缺省语言返回 `undefined`;还有 `ReadBlock` 的带行号行保留文件自身编号、高亮与纯文本两条内容分支、横幅(标签、语言、仅当读取是窗口时的计数提示)、头/尾高度上限及其 `aria-expanded` 切换、以及复制控件在接受与拒绝两条剪贴板路径上写入窗口原始文本。`ReadBlock.tsx` 与 `highlight.ts` 均保持每文件 100% 覆盖(后者由本 spec 加上覆盖 `highlightToHtml` 的 `code-block.spec.tsx` 共同达成)。
+
+`packages/client/ui-conversation/tests/read-card.spec.tsx` 固定每个渲染点的接线:`readCardModel` 的派生与每条 null 分支(运行中读取、无视图、通用视图、未知卡片)、结果标题替换化简后的路径、路径相对工作区的化简、冻结行数组的复制而非别名;`GenericToolCard` 回退中与 keyed `ReadRow` 中的常驻卡片(外加其路径链接打开宿主、其 running/error/stopped 状态、以及其 `read` 键注册);还有面板 Output 区段以全高渲染读取卡片同时保留 JSON Input 区段,含运行中读取占位与非读取摊平 pre 两条分支。该文件位于覆盖 `exclude` 列表(`ui-conversation/src/*`),因此不承受门槛压力。
+
+fixture(`packages/client/connection/src/client/fixture.ts`)增加 turn 66,一次 `read` 调用,其结果视图是窗口读取(行号从文件行 41 起、`totalLines` 180、`ts` 提示),使内置启动快照和实时 `?fixture` 服务器展示带行号、高亮和计数提示的读取卡片。它命名为 `read` 以驱动 keyed `ReadRow`;渲染点回退行已由 turn 64 的 `run_code` 样例中的读取子派发覆盖。它排在 todo turn(现为 67)之前,与终端样例同因:常驻计划在下一次 `turn/start` 退场。
+
+## Related
+
+- [读取卡片后端](2026-07-30-web-read-card.md) —— 增加本文消费的 `card: 'read'` 结果视图;产出本文渲染的 `lines`/`totalLines`/`lang`。
+- [Web 终端卡片](2026-07-28-web-terminal-card.md) —— 本文遵循的先例:一个 `ui-primitives` block、一个 `contract/*-card-model.ts` 派生、一个 keyed 行,以及让 `GenericToolCard`/`DetailsPanel` 感知卡片。
+- [Web 客户端语法高亮](../process/2026-07-26-web-syntax-highlighting-shiki.md) —— 拥有 `CodeBlock` 与 shiki `highlight.ts` 单例,本文以逐行 token 路径扩展它。
+- [工具调用呈现的标签式渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— `card` 标签词汇表;Web 客户端现在是 `read` 分支的完整消费者。
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index cb79a6b9a2..6c177e6c70 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -136,6 +136,33 @@ const TERMINAL_EXIT_STATUS: Record ({ number: READ_SAMPLE_FIRST_LINE + index, text }))
+const READ_SAMPLE_PATH = 'packages/client/ui-primitives/src/ReadBlock.tsx'
+const READ_SAMPLE_TOTAL = 180
+const READ_SAMPLE_TEXT = READ_SAMPLE_SOURCE.map((text, index) => `${READ_SAMPLE_FIRST_LINE + index}: ${text}`).join('\n')
+
 const DEEPSEEK_REASONING = {
   efforts: [
     { id: 'off', name: 'Off' },
@@ -275,7 +302,7 @@ function buildAlphaLog(): SessionEvent[] {
     push({ type: 'step/end', data: { turn, step: 0 } })
     push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
   }
-  // Turn 65: todo_write sample — the TodoRow toolview in the flow plus the
+  // Turn 67: todo_write sample — the TodoRow toolview in the flow plus the
   // todo/write snapshot event feeding the TodoPanel plan strip.
   const fixtureTodos = [
     { content: '梳理需求', status: 'completed' },
@@ -296,8 +323,19 @@ function buildAlphaLog(): SessionEvent[] {
   // strip empty and take the todo surfaces' own coverage with it.
   toolTurn(65, 'bash', '{"command":"pnpm run check","cwd":"/tmp/fixture/deep/nested"}', TERMINAL_OUTPUT_FIXTURE)
 
+  // Turn 66: the read sample — a WINDOW past an offset so the card draws file
+  // line numbers starting above 1 and a "showing N of M" note (the window is
+  // shorter than READ_SAMPLE_TOTAL), with a `ts` language hint the shiki path
+  // highlights. Named `read`, so it exercises the keyed ReadRow registration
+  // (the render-site fallback row is covered by the read sub-dispatches in the
+  // turn 64 run_code sample). The read render intent is result-side only, so its
+  // pending call stays a generic `kind: 'read'` card; presentResult carries the
+  // structured window. Ordered BEFORE the todo turn for the same reason the
+  // terminal sample is: the standing plan retires at the next `turn/start`.
+  toolTurn(66, 'read', `{"path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
+
   const todoArgs = JSON.stringify({ todos: fixtureTodos })
-  toolTurn(66, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
+  toolTurn(67, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
   // The real tool appends the snapshot mid-execution — between tool/call and
   // tool/result — so the fixture reproduces that exact ordering (the last
   // toolTurn events run ... tool/call, tool/result, step/end, turn/end).
@@ -332,6 +370,12 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
         card: 'diff', title: `Write ${str(args.path)}`,
         diffs: [{ path: str(args.path), oldText: null, newText: str(args.content) }],
       }
+    // A read pending call is a GENERIC card (kind: 'read', a follow-along
+    // location): the read render intent is result-side only, because a call
+    // carries no file content until execute returns. The rich read card arrives
+    // in presentResult.
+    case 'read':
+      return { card: 'generic', title: `Read ${str(args.path)}`, kind: 'read', locations: [{ path: str(args.path) }] }
     case 'edit':
       return { card: 'generic', title: `Edit ${str(args.file_path)}`, kind: 'edit', rawInput: args }
     case 'write':
@@ -344,6 +388,16 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
 function presentResult(name: string, argsRaw: string, resultText: string): ToolResultView | undefined {
   const call = presentCall(name, argsRaw)
   if (call === undefined) return undefined
+  // The read result is the structured window the tool projects through
+  // `presentationMeta`; the fixture authors it inline (it cannot import the
+  // tool). Keyed on the name because the read pending call is a generic card,
+  // so `call.card` alone does not distinguish it from edit/write.
+  if (name === 'read') {
+    return {
+      card: 'read', path: READ_SAMPLE_PATH, lines: READ_SAMPLE_LINES,
+      totalLines: READ_SAMPLE_TOTAL, lang: 'ts', content: text(resultText),
+    }
+  }
   switch (call.card) {
     case 'terminal':
       // The sample's own exit status, authored beside it: re-parsing the
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 7f3aeb38cc..e0027d2a86 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -19,6 +19,7 @@ import { InputBar } from './skeleton/InputBar.tsx'
 import { ChatView } from './chat/ChatView.tsx'
 import { StatsLine } from './chat/StatsLine.tsx'
 import { bashToolviewSample } from './toolviews/bash-sample.tsx'
+import { readToolview } from './toolviews/read-row.tsx'
 import { ApprovalPanel } from './skeleton/ApprovalPanel.tsx'
 import { todoToolview } from './toolviews/todo-row.tsx'
 import { todoDockEntry } from './skeleton/TodoPanel.tsx'
@@ -254,6 +255,10 @@ export function apply(ctx: Context): void {
   // (ToolRow-matching Bash · {description} chrome; scoped badge in child sessions).
   ctx.plugin(bashToolviewSample)
 
+  // The read row rides the same seam (a product registration, not a sample):
+  // Read · {path} chrome with the file's read card resident below it.
+  ctx.plugin(readToolview)
+
   // The todo_write row rides the same seam (a product registration, not a sample).
   ctx.plugin(todoToolview)
 
diff --git a/packages/client/ui-conversation/src/client/chat/GenericToolCard.module.css b/packages/client/ui-conversation/src/client/chat/GenericToolCard.module.css
new file mode 100644
index 0000000000..5c2c6f2509
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/GenericToolCard.module.css
@@ -0,0 +1,12 @@
+/* GenericToolCard read card: same column-around-summary layout and indentation
+   the keyed ReadRow uses, so a read-declaring tool without its own row (e.g.
+   web_fetch) renders its read card identically. */
+
+.card {
+  display: flex;
+  flex-direction: column;
+}
+
+.read {
+  margin: 4px 0 4px 22px;
+}
diff --git a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
index ce55d84f57..b96a14a62a 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
@@ -7,12 +7,14 @@
 import type { ReactNode } from 'react'
 import {
   IconApiOutline14, IconBrowseOutline16, IconCodeOutline16, IconEditOutline16, IconSearchOutline16, IconSparkle16,
-  IconThinkOutline14,
+  IconThinkOutline14, ReadBlock,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ToolRowOwnerProps } from '../contract/slots.ts'
+import { CHAT_READ_MAX_LINES, readCardModel } from '../contract/read-card-model.ts'
 import { terminalCardModel } from '../contract/terminal-card-model.ts'
 import { toolRowModel, type ToolRowVariant } from '../contract/tool-call-model.ts'
 import { ToolRow } from './ToolRow.tsx'
+import css from './GenericToolCard.module.css'
 
 /** Variant leading icons (figma table); all glyphs render at 14 inside the 16px leading box. */
 const VARIANT_ICONS: Record = {
@@ -29,8 +31,9 @@ const VARIANT_ICONS: Record = {
 export function GenericToolCard({ toolName, block, cwd, openFile }: ToolRowOwnerProps) {
   const model = toolRowModel(toolName, block, cwd)
   const terminal = terminalCardModel(block, cwd)
+  const read = readCardModel(block, cwd)
   const singleFile = model.filePath !== undefined
-  return (
+  const row = (
     
   )
+  // A read-declaring tool without its own keyed row lands here (e.g. web_fetch),
+  // so the file's read card is resident below the summary row exactly as the
+  // keyed ReadRow draws it. Only wrap when a card is present, so every other
+  // tool keeps the bare ToolRow.
+  if (read === null) return row
+  return (
+    
+ {row} + +
+ ) } diff --git a/packages/client/ui-conversation/src/client/contract/read-card-model.ts b/packages/client/ui-conversation/src/client/contract/read-card-model.ts new file mode 100644 index 0000000000..83779722f8 --- /dev/null +++ b/packages/client/ui-conversation/src/client/contract/read-card-model.ts @@ -0,0 +1,75 @@ +/** + * Pure derivation of the read-card props from a frozen call slice: the + * `card:'read'` render intent the read tool declares arrives on the snapshot as + * the settled result node's `resultView`, and this is the one place that turns + * it into what {@link ReadBlock} draws. Both conversation render sites (the chat + * tool row's resident body and the details panel's Output section) call this, so + * the path, lines, total, and language they show are derived once. + * + * The read card is result-side only ([read card note](../../../../../../.agents/notes/implemented/feature/2026-07-30-web-read-card.md)): + * a call carries no file content until `execute` returns, so the pending call + * stays a generic card (`kind: 'read'`). A running read therefore has no read + * card, and this returns null for it — the row keeps its args-derived summary + * until the result arrives. + * @module + */ +import type { ReadBlockLine, ReadBlockProps } from '@deepseek-ai/dsh-client-ui-primitives' +import { relativizeToCwd, type ToolCallBlock } from './tool-call-model.ts' + +/** + * Content lines the chat row's resident read body shows before collapsing the + * middle — half the primitive's own default, which the details panel keeps. A + * chat row is a summary surface inside the message flow: the flow must stay + * scannable across many calls, while the details panel is the single-call + * reading surface. A design constant of this UI's row geometry, not a + * deployment choice, so it is fixed here rather than a plugin Config field. The + * same split {@link CHAT_TERMINAL_MAX_LINES} draws for terminal output. + */ +export const CHAT_READ_MAX_LINES = 8 + +/** + * The {@link ReadBlock} props this derivation owns. Picked off the primitive's + * props so the two stay in step; `maxLines`/`className` belong to each render + * site. + */ +export type ReadCardModel = Pick + +/** + * Derive the read-card props for a tool call, or null when this call is not a + * read card and belongs on the generic path. + * + * The read card is result-side only, so only a settled call whose result view + * declares `card:'read'` produces one. Every other case is null — the + * documented generic-card default: + * + * - A running call: it has no result view yet, and a read carries no content at + * call time. + * - A settled call whose result view is not a read card — including a `card` + * value this UI version does not know, which arrives over the wire and cannot + * be trusted to be one of the compiled variants, and the read tool's own + * generic fallback for an error result or a non-envelope body. + * + * The label is the read view's `title` when the tool supplied one (the + * presentation contract's replacement-title rule), otherwise the file path + * relativized to the session workspace so a workspace-rooted absolute path + * displays the same short form the row summary shows. + * @param block - RunningToolCall or ToolResultNode off the snapshot caches. + * @param sessionCwd - the session workspace root; a workspace-rooted absolute + * path label displays relative to it. Absent leaves the path as authored. + * @returns the read-card props, or null for the generic path. + */ +export function readCardModel(block: ToolCallBlock, sessionCwd?: string): ReadCardModel | null { + // Running has no result view; a read carries no content until execute returns. + if (!('kind' in block)) return null + const result = block.resultView?.card === 'read' ? block.resultView : null + if (result === null) return null + // Lines arrive frozen off the snapshot; copy into the primitive's own line + // shape so the card never holds a reference into the runtime's cache. + const lines: ReadBlockLine[] = result.lines.map(line => ({ number: line.number, text: line.text })) + return { + label: result.title ?? relativizeToCwd(result.path, sessionCwd), + lines, + totalLines: result.totalLines, + lang: result.lang, + } +} diff --git a/packages/client/ui-conversation/src/client/contract/tool-call-model.ts b/packages/client/ui-conversation/src/client/contract/tool-call-model.ts index b53ef95c01..7043846f5b 100644 --- a/packages/client/ui-conversation/src/client/contract/tool-call-model.ts +++ b/packages/client/ui-conversation/src/client/contract/tool-call-model.ts @@ -109,8 +109,13 @@ const SUMMARY_KEYS: Record = { others: [], } -/** Strip the workspace root from workspace-rooted absolute paths (display only). */ -function relativizeToCwd(text: string, cwd: string | undefined): string { +/** + * Strip the workspace root from a workspace-rooted absolute path (display only). + * @param text - the path to shorten. + * @param cwd - session workspace root; absent or empty leaves the path unchanged. + * @returns the path relative to the workspace root, or unchanged when it is not rooted there. + */ +export function relativizeToCwd(text: string, cwd: string | undefined): string { if (cwd === undefined || cwd === '') return text const root = cwd.replace(/[/\\]+$/, '') if (text.startsWith(`${root}/`) || text.startsWith(`${root}\\`)) return text.slice(root.length + 1) diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css index 143174fe42..c513b9d976 100644 --- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css +++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css @@ -106,3 +106,9 @@ .terminal { margin: 0; } + +/* The read card sits directly under its section label, same as the terminal + card: drop the primitive's standalone vertical margin. */ +.read { + margin: 0; +} diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx index 9fc5a04ff6..642eec8946 100644 --- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx +++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx @@ -7,10 +7,11 @@ // share the store seat exists for) and derives the call material from the // session snapshot — no data of its own. -import { CodeBlock, TerminalBlock } from '@deepseek-ai/dsh-client-ui-primitives' +import { CodeBlock, ReadBlock, TerminalBlock } from '@deepseek-ai/dsh-client-ui-primitives' import { shallowEqual } from '@deepseek-ai/dsh-client-runtime/client' import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client' import type { DetailsSlotProps } from '../contract/slots.ts' +import { readCardModel } from '../contract/read-card-model.ts' import { terminalCardModel } from '../contract/terminal-card-model.ts' import type { ToolCallBlock } from '../contract/tool-call-model.ts' import css from './DetailsPanel.module.css' @@ -127,8 +128,10 @@ export function DetailsPanel({ useSession, useSessions, sessionId, useStore, clo * The Output section's body for the selected call. A terminal-card call — a * shell command's call/result views — renders through the shared TerminalBlock * at the primitive's own full height allowance, so column-aligned output keeps - * its alignment and scrolls sideways instead of folding. Every other call, and - * a running call with no terminal card yet, keeps the flattened text form. + * its alignment and scrolls sideways instead of folding. A read-card call + * renders through the shared ReadBlock at that same full height, so the whole + * returned window is line-numbered and highlighted. Every other call, and a + * running call with no card yet, keeps the flattened text form. * @param props.material - the selected call's material from {@link materialFor}. * @param props.cwd - the session workspace root, resolving the terminal view's cwd. * @returns the Output section's body element. @@ -147,6 +150,10 @@ function OutputBody({ material, cwd }: { material: CallMaterial; cwd: string | u ) } + const read = readCardModel(material.block, cwd) + // The panel takes the primitive's own default cap, not the row's tighter one: + // it is the single-call reading surface, so the whole window is available. + if (read !== null) return // A settled call always carries the result node the flattened form needs; // the running shape has no result to flatten. if (!('kind' in material.block)) return
运行中…
diff --git a/packages/client/ui-conversation/src/client/toolviews/read-row.module.css b/packages/client/ui-conversation/src/client/toolviews/read-row.module.css new file mode 100644 index 0000000000..b83b395f1a --- /dev/null +++ b/packages/client/ui-conversation/src/client/toolviews/read-row.module.css @@ -0,0 +1,93 @@ +/* Read toolview: same geometry/tokens as ToolRow (figma Read · {path}), plus + the read card the row stacks under its summary line. */ + +/* Summary line over the read card; the summary row keeps its own 24px height, + so the card is a column around it rather than a change to it. */ +.card { + display: flex; + flex-direction: column; +} + +/* Row indentation matches ToolRow's expanded bodies (16px leading + 6px gap), + and replaces the primitive's standalone vertical margin with the flow's. */ +.read { + margin: 4px 0 4px 22px; +} + +.root { + position: relative; + overflow: hidden; + display: flex; + align-items: center; + height: 24px; + min-width: 0; +} + +.leading { + flex: none; + width: 16px; + height: 16px; + display: inline-flex; + align-items: center; + justify-content: center; + margin-right: 6px; + color: var(--dsw-alias-label-tertiary); +} + +.title { + flex: none; + font-size: 14px; + line-height: 24px; + color: var(--dsw-alias-label-secondary); +} + +.sep { + flex: none; + width: 2px; + height: 2px; + border-radius: 1px; + margin: 0 8px; + background: var(--dsw-alias-label-caption); +} + +.summary { + flex: 1 1 auto; + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + font-size: 14px; + line-height: 24px; + color: var(--dsw-alias-label-tertiary); +} + +/* File path: same geometry as .summary; hover underline + pointer. */ +.fileLink { + flex: 1 1 auto; + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + margin: 0; + padding: 0; + border: none; + background: none; + text-align: left; + font-size: 14px; + line-height: 24px; + color: var(--dsw-alias-label-tertiary); + cursor: pointer; +} + +.fileLink:hover { + text-decoration: underline; +} + +.visuallyHidden { + position: absolute; + width: 1px; + height: 1px; + overflow: hidden; + clip: rect(0 0 0 0); + white-space: nowrap; +} diff --git a/packages/client/ui-conversation/src/client/toolviews/read-row.tsx b/packages/client/ui-conversation/src/client/toolviews/read-row.tsx new file mode 100644 index 0000000000..28151ed602 --- /dev/null +++ b/packages/client/ui-conversation/src/client/toolviews/read-row.tsx @@ -0,0 +1,100 @@ +// Read toolview registrant: the keyed toolview hole for the read tool +// (ctx.slots.register + ToolRowProps only — never imports the chat domain). +// Product chrome matches ToolRow (figma: Read · {path}); the summary is the +// file path as an openable link, exactly as the generic read row draws it. +// +// A read RESULT declares the read render intent, so this row renders the file's +// own line-numbered, syntax-highlighted content through ReadBlock resident +// below its summary line — the same posture BashRow gives a terminal card. The +// card is capped at CHAT_READ_MAX_LINES (the chat flow's tighter cap over the +// block's own default of 16) with the block's internal expander keeping a long +// read from taking over the message flow. A running read (no result yet) and a +// non-read result both render the summary row alone. The read intent is +// result-side only, so there is no running-state read card to draw. + +import type { Context } from 'cordis' +import { IconBrowseOutline16, ReadBlock, StateDot } from '@deepseek-ai/dsh-client-ui-primitives' +import type { ToolRowProps } from '../contract/slots.ts' +import { CHAT_READ_MAX_LINES, readCardModel } from '../contract/read-card-model.ts' +import { toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts' +import css from './read-row.module.css' + +/** Leading-slot state substitution: the tool icon yields to the state dot + * (error = red, interrupted = amber). Running keeps the icon. */ +function leadingFor(state: ToolRowState) { + switch (state) { + case 'error': return + case 'stopped': return + default: return + } +} + +/** Visually hidden status — StateDot is aria-hidden; AT needs a text label. */ +function stateStatus(state: ToolRowState): string | null { + switch (state) { + case 'running': return '运行中' + case 'error': return '失败' + case 'stopped': return '已停止' + default: return null + } +} + +/** + * Read row: icon + Read · {path} in the shared ToolRow chrome, with the file's + * read card resident below it. The summary path is an openable host link when + * the row names a single file; the card's copy and expand controls plus that + * link are the row's only interactions (tool rows are not details-panel + * targets). + */ +export function ReadRow({ toolName, block, sessionId, useSessions, openFile }: ToolRowProps) { + // Session workspace root: the read view's path relativizes against it (a + // workspace-rooted absolute path shows its short form), which the pure + // presenter cannot do. + const cwd = useSessions(list => list.byId[sessionId]?.cwd) + const model = toolRowModel(toolName, block, cwd) + const read = readCardModel(block, cwd) + const status = stateStatus(model.state) + const filePath = model.filePath + return ( +
+
+ {leadingFor(model.state)} + {status !== null && {status}} + {model.title} + + {filePath !== undefined ? ( + + ) : ( + {model.summary} + )} +
+ {read !== null && ( + + )} +
+ ) +} + +/** + * The read row as a plain registrant plugin. `inject` carries the load-order + * seam: requiring the conversation service guarantees the chat entry (and with + * it the 'conversation.chat.toolview' declaration) is registered — + * ui-conversation's apply mounts the service after the chat entry. + */ +export const readToolview = { + name: 'read-toolview', + inject: ['slots', 'conversation'], + /** + * Register the read row into the chat view's keyed toolview hole. + * @param ctx - registrant context (disposal rides ctx.effect inside slots.register). + */ + apply(ctx: Context): void { + ctx.slots.register({ name: 'conversation.chat.toolview', key: 'read' }, ReadRow) + }, +} diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx index d7b9125b34..57512c4d0d 100644 --- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx @@ -80,12 +80,12 @@ describe('apply wiring', () => { await b.runtime.dispose() }) - it('mounts the bash sample and the todo row as keyed entries through the load-order seam', async () => { + it('mounts the bash sample, the read row, and the todo row as keyed entries through the load-order seam', async () => { const b = await bench() - // Both registrant plugins' inject: ['slots', 'conversation'] resolved — the + // All registrant plugins' inject: ['slots', 'conversation'] resolved — the // service being present implies the chat entry declared the hole first. const entries = b.slots.entries('conversation.chat.toolview') - expect(entries.map(e => e.options.key)).toEqual(['bash', 'todo_write']) + expect(entries.map(e => e.options.key)).toEqual(['bash', 'read', 'todo_write']) // Stats stick with the composer (not inside ChatView). expect(b.slots.entries('conversation.composer.dock').map(e => e.options.id)).toEqual(['stats']) await b.runtime.dispose() diff --git a/packages/client/ui-conversation/tests/read-card.spec.tsx b/packages/client/ui-conversation/tests/read-card.spec.tsx new file mode 100644 index 0000000000..a4ead14748 --- /dev/null +++ b/packages/client/ui-conversation/tests/read-card.spec.tsx @@ -0,0 +1,282 @@ +// @vitest-environment jsdom +// The read render intent on the web side: the pure readCardModel derivation +// over the settled result view, and both conversation render sites that consume +// it — the chat tool row (the keyed ReadRow and the GenericToolCard fallback, +// each with the read card resident under the summary) and the details panel's +// Output section. Also pins the keyed 'read' toolview registration. + +import { afterEach, describe, expect, it, vi } from 'vitest' +import { cleanup, fireEvent, render } from '@testing-library/react' +import { Context } from 'cordis' +import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react' +import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' +import type { + ConversationSnapshot, RunningToolCall, SessionId, SessionListState, ToolResultNode, WorkspaceListState, +} from '@deepseek-ai/dsh-client-runtime/client' +import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client' +import type { SelectionTarget, ToolRowOwnerProps, ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client' +import { CHAT_READ_MAX_LINES, readCardModel } from '../src/client/contract/read-card-model.ts' +import { createChatStore } from '../src/client/stores.ts' +import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx' +import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx' +import { ReadRow, readToolview } from '../src/client/toolviews/read-row.tsx' + +afterEach(cleanup) + +const SID = 's1' as SessionId + +const ARGS = '{"path":"src/a.ts","offset":41}' + +/** The read block's rendered content cells, one string per row (highlighting + * breaks a line across token spans, so match on the row's textContent). */ +function contentTexts(container: HTMLElement): string[] { + return [...container.querySelectorAll('[data-read] [class^="_content_"]')].map(cell => cell.textContent ?? '') +} + +/** Three windowed lines starting at file line 41 (a read past an offset). */ +const sampleLines = [ + { number: 41, text: 'export const a = 1' }, + { number: 42, text: 'export const b = 2' }, + { number: 43, text: 'export const c = 3' }, +] + +/** The read tool's own result view for a settled file read. */ +const resultRead = (over?: Partial>): ToolResultView => ({ + card: 'read', path: 'src/a.ts', lines: sampleLines, totalLines: 180, lang: 'ts', ...over, +}) + +const running = (over?: Partial): RunningToolCall => ({ + callId: 'c1', name: 'read', argsRaw: ARGS, + turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, ...over, +}) + +const settled = (over?: Partial): ToolResultNode => ({ + kind: 'tool-result', seq: 10, time: 2_000, callId: 'c1', + call: { name: 'read', argsRaw: ARGS }, + callTime: 1_000, + content: [{ type: 'text', text: '41: export const a = 1' }], isError: false, + callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, resultView: resultRead(), ...over, +}) + +describe('readCardModel', () => { + it('derives the card from a settled read result view', () => { + expect(readCardModel(settled())).toEqual({ + label: 'src/a.ts', lines: sampleLines, totalLines: 180, lang: 'ts', + }) + }) + + it('copies the lines into the primitive shape rather than aliasing the frozen slice', () => { + const model = readCardModel(settled()) + expect(model?.lines).toEqual(sampleLines) + expect(model?.lines).not.toBe(sampleLines) + expect(model?.lines[0]).not.toBe(sampleLines[0]) + }) + + it('takes the result view\'s replacement title over the relativized path', () => { + // The presentation contract defines a result title as REPLACING the pending + // one, so a tool that supplies a label wins over the path here. + expect(readCardModel(settled({ resultView: resultRead({ title: 'Read (head) src/a.ts' }) }))?.label) + .toBe('Read (head) src/a.ts') + }) + + it('relativizes a workspace-rooted path label, and leaves others as authored', () => { + // A workspace-rooted absolute path shows its short form. + expect(readCardModel(settled({ resultView: resultRead({ path: '/w/app/src/a.ts' }) }), '/w/app')?.label) + .toBe('src/a.ts') + // A path outside the workspace stays as authored. + expect(readCardModel(settled({ resultView: resultRead({ path: '/srv/other.ts' }) }), '/w/app')?.label) + .toBe('/srv/other.ts') + // With no session cwd there is nothing to relativize against. + expect(readCardModel(settled({ resultView: resultRead({ path: '/w/app/src/a.ts' }) }))?.label) + .toBe('/w/app/src/a.ts') + }) + + it('carries an omitted language through as undefined', () => { + const noLang = resultRead() + delete (noLang as { lang?: string }).lang + expect(readCardModel(settled({ resultView: noLang }))?.lang).toBeUndefined() + }) + + it('returns null for a running read: the read intent is result-side only', () => { + // A read carries no content until execute returns, so the pending call is a + // generic card and there is no read card to draw yet. + expect(readCardModel(running())).toBeNull() + }) + + it('returns null for every non-read settled call: no view, generic view, unknown card', () => { + expect(readCardModel(settled({ resultView: null }))).toBeNull() + expect(readCardModel(settled({ resultView: { card: 'generic' } }))).toBeNull() + // A card tag this UI version does not know arrives over the wire; the + // documented generic-card default takes it, not a crash. + const future = { card: 'chart' } as unknown as ToolResultView + expect(readCardModel(settled({ resultView: future }))).toBeNull() + }) +}) + +describe('GenericToolCard read body', () => { + const ownerProps = (block: RunningToolCall | ToolResultNode): ToolRowOwnerProps => ({ + callId: 'c1', toolName: 'web_fetch', block, openFile: vi.fn(), + }) + + it('renders the read card resident under the summary, capped tighter than the panel', () => { + expect(CHAT_READ_MAX_LINES).toBeLessThan(16) + // web_fetch lands on the read variant without its own keyed row, so the + // fallback card owns the resident read block. + const view = render() + expect(view.container.querySelector('[data-read]')).not.toBeNull() + expect(contentTexts(view.container)).toContain('export const a = 1') + // The gutter keeps the file's own line numbers. + expect(view.getByText('41')).toBeTruthy() + }) + + it('a non-read tool renders the bare row with no read card', () => { + const view = render() + expect(view.container.querySelector('[data-read]')).toBeNull() + }) + + it('a running read renders the summary row alone (no result view yet)', () => { + const view = render() + expect(view.container.querySelector('[data-read]')).toBeNull() + }) +}) + +describe('ReadRow keyed toolview', () => { + const list = () => createSnapshotStore({ + ids: [SID], + byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, waitingApproval: false, updatedAt: 0, cwd: '/w/app' } }, + current: SID, + phase: 'ready', + }) + + const rowProps = (block: RunningToolCall | ToolResultNode): ToolRowProps => ({ + callId: 'c1', toolName: 'read', block, openFile: vi.fn(), + sessionId: SID, useSessions: bindSnapshotSelector(list()), + } as unknown as ToolRowProps) + + it('renders the file path summary and the resident read card', () => { + const view = render() + expect(view.getByText('Read')).toBeTruthy() + // The path appears twice: the row summary link and the card's banner label. + expect(view.getAllByText('src/a.ts').length).toBe(2) + expect(view.container.querySelector('[data-read]')).not.toBeNull() + expect(contentTexts(view.container)).toContain('export const a = 1') + expect(view.getByText('显示 3 / 180 行')).toBeTruthy() + }) + + it('the path summary opens the file through the host', () => { + const openFile = vi.fn() + const view = render() + fireEvent.click(view.getByRole('button', { name: 'src/a.ts' })) + // The row derives the file path from args; the chat view resolves it against + // the cwd before this callback opens it, so the arg path is what arrives. + expect(openFile).toHaveBeenCalledWith('src/a.ts') + }) + + it('a running read renders the summary row alone, and its state', () => { + const view = render() + expect(view.container.querySelector('[data-variant="read"]')?.getAttribute('data-state')).toBe('running') + expect(view.container.querySelector('[data-read]')).toBeNull() + }) + + it('an error read result shows the error state and no read card', () => { + const view = render() + expect(view.container.querySelector('[data-variant="read"]')?.getAttribute('data-state')).toBe('error') + expect(view.container.querySelector('[data-read]')).toBeNull() + }) + + it('an interrupted read shows the stopped state', () => { + const view = render() + expect(view.container.querySelector('[data-variant="read"]')?.getAttribute('data-state')).toBe('stopped') + }) + + it('registers under the read key of the keyed toolview slot', () => { + const registered: { name: unknown; key?: unknown }[] = [] + const ctx = { slots: { register: (options: { name: unknown; key?: unknown }) => { registered.push(options) } } } as unknown as Context + readToolview.apply(ctx) + expect(registered).toEqual([{ name: 'conversation.chat.toolview', key: 'read' }]) + expect(readToolview.inject).toContain('conversation') + }) +}) + +describe('DetailsPanel Output section (read)', () => { + function mount(snapshot: ConversationSnapshot, selection: SelectionTarget | null, cwd?: string) { + localStorage.clear() + const chat = createChatStore().create() + if (selection !== null) chat.actions.select(selection) + const sessions = createSnapshotStore(cwd === undefined + ? { ids: [], byId: {}, current: undefined, phase: 'ready' } + : { + ids: [SID], + byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, waitingApproval: false, updatedAt: 0, cwd } }, + current: SID, + phase: 'ready', + }) + const workspaces = createSnapshotStore({ + items: [], state: 'idle', phase: 'ready', error: null, + baselinesReady: true, recentWorkspaceId: undefined, + }) + return render( + snapshot, subscribe: () => () => {} })} + useSessions={bindSnapshotSelector(sessions)} + useWorkspaces={bindSnapshotSelector(workspaces)} + useInput={(() => { throw new Error('unused') })} + inputActions={{ setDraft: () => {}, submit: () => {} }} + useProjection={(() => undefined)} + useStore={bindSnapshotSelector(chat)} + actions={chat.actions} + closeDetails={vi.fn()} + />, + ) + } + + function snapshot(over: Partial = {}): ConversationSnapshot { + return { + sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(), + pending: [], queue: [], running: false, composerPhase: 'active', removed: false, + openState: 'open', openError: null, hasMore: false, loadingOlder: false, + promptError: null, blank: false, lastAgentError: null, ...over, + } + } + + const target: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'read' } + + it('renders the read card at full height, keeping the JSON Input section', () => { + const long = Array.from({ length: 20 }, (_, i) => ({ number: i + 1, text: `row-${i}` })) + const view = mount(snapshot({ + nodes: [settled({ resultView: resultRead({ lines: long, totalLines: 20 }) })], + }), target) + expect(view.getByText(/"path"/)).toBeTruthy() + expect(view.container.querySelector('[data-read]')).not.toBeNull() + // The panel takes the primitive's own default cap (16), not the row's. + expect(view.getByText(`… 其余 ${20 - 16} 行`)).toBeTruthy() + expect(contentTexts(view.container)).toContain('row-0') + }) + + it('a non-read result keeps the flattened pre form', () => { + const view = mount(snapshot({ + nodes: [settled({ + callView: null, resultView: null, + content: [{ type: 'text', text: 'plain result' }], + })], + }), target) + expect(view.container.querySelector('[data-read]')).toBeNull() + expect(view.getByText('Output').closest('section')?.querySelector('pre')?.textContent).toBe('plain result') + }) + + it('a running read keeps the 运行中… placeholder (no result view)', () => { + const view = mount(snapshot({ runningCalls: [running()] }), target) + expect(view.getByText('运行中…')).toBeTruthy() + expect(view.container.querySelector('[data-read]')).toBeNull() + }) +}) diff --git a/packages/client/ui-primitives/src/ReadBlock.module.css b/packages/client/ui-primitives/src/ReadBlock.module.css new file mode 100644 index 0000000000..a18afe6152 --- /dev/null +++ b/packages/client/ui-primitives/src/ReadBlock.module.css @@ -0,0 +1,117 @@ +/* Geometry mirrors CodeBlock (12px radius, code-block surface + banner row, + markdown code-block font) so a read card and a fenced code block read as one + family. Content keeps `white-space: pre` and scrolls horizontally rather than + folding, because a source line's indentation is part of what a reader is + reading. */ + +.block { + --dsl-read-radius: 12px; + --dsl-read-line-height: 22px; + /* Fixed-width gutter column for the line numbers, so the content edge stays + put down the whole window regardless of how wide the numbers grow. */ + --dsl-read-gutter: 48px; + + position: relative; + margin: 16px 0; + color: var(--dsw-alias-label-primary); + background: var(--dsw-alias-markdown-code-block); + border-radius: var(--dsl-read-radius); +} + +.banner { + display: flex; + justify-content: space-between; + align-items: center; + gap: 12px; + padding: 9px 14px; + background: var(--dsw-alias-markdown-code-block-banner); + border-top-left-radius: var(--dsl-read-radius); + border-top-right-radius: var(--dsl-read-radius); +} + +.label { + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + color: var(--dsw-alias-label-primary); + font-family: var(--ds-font-family-code); + font-size: 12px; + line-height: 18px; +} + +.action { + display: flex; + align-items: center; + flex-shrink: 0; + gap: 12px; +} + +.count { + color: var(--dsw-alias-label-tertiary); + font: var(--dsw-font-xs-13); +} + +.lang { + color: var(--dsw-alias-label-tertiary); + font-family: var(--ds-font-family-code); + font-size: 12px; + line-height: 18px; +} + +.copyButton { + background-color: transparent; + border: none; + padding: 0; + margin: 0; + color: var(--dsw-alias-label-secondary); + cursor: pointer; + font: var(--dsw-font-xs-13); +} + +.body { + padding: 12px 0; + font: var(--dsw-font-markdown-code-block); + overflow-x: auto; + overflow-y: hidden; +} + +/* One row per file line: a fixed gutter column, then the content. No wrapping — + a source line's leading whitespace is meaningful and scrolls sideways. */ +.line { + display: flex; + min-height: var(--dsl-read-line-height); + line-height: var(--dsl-read-line-height); + white-space: pre; +} + +.gutter { + flex: none; + width: var(--dsl-read-gutter); + padding-right: 14px; + text-align: right; + color: var(--dsw-alias-label-tertiary); + /* The gutter is chrome, not content: keep it out of a text selection so a + copy of the visible rows carries the source, not the line numbers. */ + user-select: none; +} + +.content { + color: var(--dsw-alias-label-primary); +} + +.expand { + display: block; + width: 100%; + padding: 0 0 0 var(--dsl-read-gutter); + border: none; + background-color: transparent; + color: var(--dsw-alias-label-tertiary); + cursor: pointer; + font: inherit; + text-align: left; +} + +.expand:hover { + color: var(--dsw-alias-label-secondary); +} diff --git a/packages/client/ui-primitives/src/ReadBlock.tsx b/packages/client/ui-primitives/src/ReadBlock.tsx new file mode 100644 index 0000000000..df9658e3dd --- /dev/null +++ b/packages/client/ui-primitives/src/ReadBlock.tsx @@ -0,0 +1,156 @@ +// ReadBlock: the file surface for a read tool result — a banner (label + +// language + a "showing N of M" note when the read is a window + a copy +// control) over line-numbered, syntax-highlighted source. Each row carries the +// file's OWN line number in a gutter, so a windowed read past an offset keeps +// its file numbering rather than re-counting from 1. Highlighting reuses the +// CodeBlock shiki path (highlight.ts) at the per-line granularity a gutter +// needs; an unknown or absent language renders plain monospace. Long content is +// height-capped with the same head/tail arithmetic TerminalBlock uses, so the +// two cards collapse a long body at the same place. Colors resolve through +// --shiki-*/--dsw-* tokens. + +import { useCallback, useMemo, useState } from 'react' +import clsx from 'clsx' +import { writeClipboard } from './clipboard.ts' +import { highlightLines, type HighlightSpan } from './markdown/highlight.ts' +import css from './ReadBlock.module.css' + +/** + * Content lines shown before the height cap collapses the middle. Matches + * TerminalBlock's default so a long read and a long command output cut at the + * same place in the same flow. + */ +export const DEFAULT_READ_MAX_LINES = 16 + +/** One line of the read window: its file line number and its text (no trailing newline). */ +export interface ReadBlockLine { + /** 1-based line number in the file (a window past an offset keeps the file's own numbering). */ + number: number + /** The line's text, already truncated to the read tool's per-line cap. */ + text: string +} + +export interface ReadBlockProps { + /** Banner label (the file path, or a tool-supplied replacement title); omitted draws no label. */ + label?: string | undefined + /** The returned window's lines, in file order, each keeping its file line number. */ + lines: readonly ReadBlockLine[] + /** Exact total line count in the file, for the "showing N of M" note when the read is a window. */ + totalLines: number + /** Grammar hint (a file-extension-derived language id); unknown or absent = plain monospace. */ + lang?: string | undefined + /** Height cap in content lines before the middle collapses (default {@link DEFAULT_READ_MAX_LINES}). */ + maxLines?: number | undefined + /** Extra class merged onto the wrapper (callers position; this component draws). */ + className?: string | undefined +} + +/** + * Render one line's highlighted runs. The css-variables theme colors every run, + * so each run is a styled span; a line with no highlighting at all takes the + * bare-text path in the caller instead (an unknown or absent language). + * @param spans - the line's styled runs. + * @returns the line's children. + */ +function renderSpans(spans: readonly HighlightSpan[]) { + return spans.map((span, index) => {span.text}) +} + +/** + * Render a read tool result as a line-numbered, optionally syntax-highlighted + * file view. + * @param props - see {@link ReadBlockProps}. + * @returns the read block element. + */ +export function ReadBlock({ + label, + lines, + totalLines, + lang, + maxLines = DEFAULT_READ_MAX_LINES, + className, +}: ReadBlockProps) { + // The raw text the copy control writes and the highlighter tokenizes: the + // window's lines joined by newlines, without the file numbers or any chrome. + // Highlighting the whole window in one call (not line by line) keeps grammar + // context across lines — a multi-line string or comment stays one construct. + const raw = useMemo(() => lines.map(line => line.text).join('\n'), [lines]) + // Per-line highlighted runs aligned 1:1 with `lines`; undefined for an + // unknown/absent language, when every line renders as bare text. + const highlighted = useMemo(() => highlightLines(raw, lang), [raw, lang]) + const [expanded, setExpanded] = useState(false) + const [copied, setCopied] = useState(false) + + const onCopy = useCallback(() => { + if (copied) return + // The window's raw text, never the rendered tree: the gutter numbers and the + // banner are chrome the file does not contain. + void writeClipboard(raw).then((ok) => { + if (!ok) return + setCopied(true) + window.setTimeout(() => { setCopied(false) }, 1000) + }) + }, [copied, raw]) + + const onToggle = useCallback(() => { setExpanded(value => !value) }, []) + + const hidden = lines.length - maxLines + const capped = hidden > 0 && !expanded + // Same split arithmetic as TerminalBlock's height cap, so a long read and a + // long command output slice their head and tail at the same place. + const headLines = Math.ceil(maxLines / 2) + const tailLines = maxLines - headLines + // A read is a window when its returned lines are fewer than the file's total; + // the note states that so a reader is not misled that the file ends here. + const windowed = lines.length < totalLines + + /** + * Render a slice of the line array as gutter-numbered rows. + * @param slice - the lines to draw, each with its aligned run array. + * @returns the row elements. + */ + const rows = (slice: readonly (readonly [ReadBlockLine, readonly HighlightSpan[] | undefined])[]) => + slice.map(([line, spans]) => ( +
+ {line.number} + {spans === undefined ? line.text : renderSpans(spans)} +
+ )) + + // Pair each line with its aligned run array up front, so head/tail slicing + // keeps the two in step without re-indexing. + const paired = lines.map((line, index): readonly [ReadBlockLine, readonly HighlightSpan[] | undefined] => + [line, highlighted?.[index]]) + + return ( +
+
+
{label ?? ''}
+
+ {windowed && ( + {`显示 ${lines.length} / ${totalLines} 行`} + )} + {lang ?? ''} + +
+
+
+ {rows(capped ? paired.slice(0, headLines) : paired)} + {hidden > 0 && ( + + )} + {capped && rows(paired.slice(paired.length - tailLines))} +
+
+ ) +} diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts index aa674f7a1a..362c028a5b 100644 --- a/packages/client/ui-primitives/src/index.ts +++ b/packages/client/ui-primitives/src/index.ts @@ -22,6 +22,8 @@ export { JsonTree } from './JsonTree.tsx' export type { JsonTreeProps } from './JsonTree.tsx' export { TerminalBlock, DEFAULT_TERMINAL_MAX_LINES } from './TerminalBlock.tsx' export type { TerminalBlockProps } from './TerminalBlock.tsx' +export { ReadBlock, DEFAULT_READ_MAX_LINES } from './ReadBlock.tsx' +export type { ReadBlockProps, ReadBlockLine } from './ReadBlock.tsx' export { CodeBlock } from './markdown/CodeBlock.tsx' export { JsonBlock } from './markdown/JsonBlock.tsx' export { MarkdownText } from './markdown/MarkdownText.tsx' diff --git a/packages/client/ui-primitives/src/markdown/highlight.ts b/packages/client/ui-primitives/src/markdown/highlight.ts index 1fa50f6d2f..74709d4ac2 100644 --- a/packages/client/ui-primitives/src/markdown/highlight.ts +++ b/packages/client/ui-primitives/src/markdown/highlight.ts @@ -17,6 +17,7 @@ import langTs from '@shikijs/langs/typescript' import langBash from '@shikijs/langs/shellscript' import langJson from '@shikijs/langs/json' import type { HighlighterCore } from 'shiki/core' +import type { CSSProperties } from 'react' /** * Language ids (and aliases) the singleton registers; everything else renders @@ -80,3 +81,42 @@ export function highlightToHtml(code: string, lang: string | undefined): string if (resolved === undefined) return undefined return highlighter().codeToHtml(code, { lang: resolved, theme: 'css-variables' }) } + +/** + * One highlighted run of a line: the text and the inline style shiki assigned + * it. The css-variables theme colors every run through a `--shiki-*` custom + * property, so `style.color` is always present; it is held as a style object + * rather than a bare color so a run spreads onto a `` uniformly. + */ +export interface HighlightSpan { + text: string + style: CSSProperties +} + +/** + * Tokenize `code` into per-line highlighted runs when `lang` maps to a + * registered grammar; `undefined` means the caller renders its plain fallback. + * A line-numbered view needs the token runs split per line (one gutter number + * per line), which the single-`
` {@link highlightToHtml} does not expose,
+ * so this returns shiki's own 2D line/token structure narrowed to what a run
+ * renders. Each run's color is a `--shiki-*` custom property, keeping token
+ * colors on the theme package's sheets exactly as the HTML path does; the
+ * css-variables theme carries no font-style bits, matching that path's
+ * color-only output. The trailing newline shiki appends as a final empty line
+ * is dropped so the run count matches the caller's own line array.
+ * @param code - the source text.
+ * @param lang - the language hint (a file-extension-derived language id).
+ * @returns one entry per source line (each an array of runs), or `undefined` for unknown languages.
+ */
+export function highlightLines(code: string, lang: string | undefined): HighlightSpan[][] | undefined {
+  const resolved = lang === undefined ? undefined : LANG_ALIASES.get(lang.toLowerCase())
+  if (resolved === undefined) return undefined
+  const { tokens } = highlighter().codeToTokens(code, { lang: resolved, theme: 'css-variables' })
+  // shiki tokenizes `a\nb` into two lines; a trailing newline (`a\n`) adds a
+  // third, empty line the caller's own line array does not carry. Drop that
+  // one terminator line so the two structures stay in step.
+  const lines = tokens.length > 1 && tokens[tokens.length - 1]?.length === 0
+    ? tokens.slice(0, -1)
+    : tokens
+  return lines.map(line => line.map(token => ({ text: token.content, style: { color: token.color } })))
+}
diff --git a/packages/client/ui-primitives/tests/read-block.spec.tsx b/packages/client/ui-primitives/tests/read-block.spec.tsx
new file mode 100644
index 0000000000..339fd2d71e
--- /dev/null
+++ b/packages/client/ui-primitives/tests/read-block.spec.tsx
@@ -0,0 +1,215 @@
+// @vitest-environment jsdom
+// ReadBlock + the highlightLines token path: the banner (label, language, the
+// "showing N of M" note only when the read is a window, copy control), the
+// gutter-numbered rows keeping the file's own line numbers, the shiki per-line
+// highlighting resolved to css-variables token spans with an identical-geometry
+// plain fallback for an unknown/absent language, the head/tail height cap and
+// its expand control, and the copy control writing the raw window text on both
+// the accepted and refused clipboard paths.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { DEFAULT_READ_MAX_LINES, ReadBlock, type ReadBlockLine } from '../src/index.ts'
+import { highlightLines } from '../src/markdown/highlight.ts'
+
+afterEach(cleanup)
+
+beforeEach(() => {
+  vi.useRealTimers()
+})
+
+/** `count` lines starting at `first`, each with distinct text. */
+function lines(count: number, first = 1): ReadBlockLine[] {
+  return Array.from({ length: count }, (_value, index) => ({ number: first + index, text: `line ${first + index}` }))
+}
+
+/** The rendered rows as `` strings (CSS-module class prefix). */
+function rowTexts(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[class^="_line_"]')].map(row => row.textContent ?? '')
+}
+
+/** The gutter numbers of the rendered rows, in order. */
+function gutters(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[class^="_gutter_"]')].map(cell => cell.textContent ?? '')
+}
+
+describe('highlightLines', () => {
+  it('tokenizes a registered grammar into per-line css-variables runs', () => {
+    const result = highlightLines('const x = 1\n// c', 'ts')
+    expect(result).not.toBeUndefined()
+    expect(result).toHaveLength(2)
+    // The keyword run carries a color style through a --shiki-* custom property.
+    const keyword = result![0]!.find(span => span.text === 'const')
+    expect(keyword?.style?.color).toContain('var(--shiki-')
+    // Whitespace between tokens is a run of its own; the comment is line two.
+    expect(result![0]!.map(span => span.text).join('')).toBe('const x = 1')
+    expect(result![1]!.map(span => span.text).join('')).toBe('// c')
+  })
+
+  it('colors every run through a --shiki-* custom property', () => {
+    // The css-variables theme colors even the whitespace run (as the foreground
+    // token), so every run is a styled span; the plain fallback is the whole
+    // unknown-language path, not a per-run one.
+    const result = highlightLines('const x = 1', 'ts')
+    for (const span of result!) for (const run of span) expect(run.style.color).toContain('var(--shiki-')
+  })
+
+  it('drops the trailing terminator line so the run count matches the source lines', () => {
+    // `a\n` tokenizes to two lines in shiki (the second empty); the caller's own
+    // line array has one entry, so the terminator line is dropped.
+    const result = highlightLines('const a = 1\n', 'ts')
+    expect(result).toHaveLength(1)
+  })
+
+  it('keeps a genuinely blank final line when the source ends in two newlines', () => {
+    const result = highlightLines('a\n\n', 'ts')
+    expect(result).toHaveLength(2)
+    expect(result![1]).toEqual([])
+  })
+
+  it('returns undefined for an unknown or absent language', () => {
+    expect(highlightLines('x', 'cobol')).toBeUndefined()
+    expect(highlightLines('x', undefined)).toBeUndefined()
+  })
+})
+
+describe('ReadBlock rows', () => {
+  it('renders one gutter-numbered row per line, keeping the file line numbers', () => {
+    const view = render()
+    expect(gutters(view.container)).toEqual(['41', '42', '43'])
+    expect(rowTexts(view.container)).toEqual(['41line 41', '42line 42', '43line 43'])
+  })
+
+  it('highlights the content for a known language into token spans', () => {
+    const view = render(
+      ,
+    )
+    const content = view.container.querySelector('[class^="_content_"]')
+    expect(content?.querySelectorAll('span[style]').length).toBeGreaterThan(1)
+    expect(content?.textContent).toBe('const a = 1')
+  })
+
+  it('renders the content as bare text with no span wrappers for an unknown language', () => {
+    const view = render(
+      ,
+    )
+    const content = view.container.querySelector('[class^="_content_"]')
+    expect(content?.querySelectorAll('span').length).toBe(0)
+    expect(content?.textContent).toBe('IDENT DIVISION.')
+  })
+
+  it('renders bare text when no language is given', () => {
+    const view = render()
+    const content = view.container.querySelector('[class^="_content_"]')
+    expect(content?.querySelectorAll('span').length).toBe(0)
+    expect(view.getByText('plain')).toBeTruthy()
+  })
+})
+
+describe('ReadBlock banner', () => {
+  it('shows the label, the language, and the count note when the read is a window', () => {
+    const view = render()
+    expect(view.getByText('src/a.ts')).toBeTruthy()
+    expect(view.getByText('ts')).toBeTruthy()
+    expect(view.getByText('显示 3 / 180 行')).toBeTruthy()
+  })
+
+  it('omits the count note when the window is the whole file', () => {
+    const view = render()
+    expect(view.queryByText(/显示/u)).toBeNull()
+  })
+
+  it('draws an empty label and empty language when neither is given', () => {
+    const view = render()
+    expect(view.container.querySelector('[class^="_label_"]')?.textContent).toBe('')
+    expect(view.container.querySelector('[class^="_lang_"]')?.textContent).toBe('')
+  })
+})
+
+describe('ReadBlock height cap', () => {
+  it('renders every line and no expand control under the cap', () => {
+    const view = render()
+    expect(rowTexts(view.container)).toHaveLength(4)
+    expect(view.container.querySelector('[aria-expanded]')).toBeNull()
+  })
+
+  it('slices head and tail over the cap and expands on click', () => {
+    const view = render()
+    // maxLines 4: head = ceil(4/2) = 2, tail = 4 - 2 = 2, 6 hidden.
+    expect(gutters(view.container)).toEqual(['1', '2', '9', '10'])
+    const toggle = view.getByRole('button', { name: '展开其余 6 行' })
+    expect(toggle.getAttribute('aria-expanded')).toBe('false')
+    expect(toggle.textContent).toBe('… 其余 6 行')
+
+    fireEvent.click(toggle)
+    expect(rowTexts(view.container)).toHaveLength(10)
+    const collapse = view.getByRole('button', { name: '收起内容' })
+    expect(collapse.getAttribute('aria-expanded')).toBe('true')
+    expect(collapse.textContent).toBe('收起')
+
+    fireEvent.click(collapse)
+    expect(gutters(view.container)).toEqual(['1', '2', '9', '10'])
+  })
+
+  it('renders the head slice alone when the cap leaves no tail', () => {
+    const view = render()
+    expect(gutters(view.container)).toEqual(['1'])
+    expect(view.getByRole('button', { name: '展开其余 4 行' })).toBeTruthy()
+  })
+
+  it('caps at the documented default when maxLines is absent', () => {
+    const view = render(
+      ,
+    )
+    expect(rowTexts(view.container)).toHaveLength(DEFAULT_READ_MAX_LINES)
+    expect(view.getByRole('button', { name: '展开其余 1 行' })).toBeTruthy()
+  })
+})
+
+describe('ReadBlock copy', () => {
+  it('copies the raw window text, joined by newlines, never the gutter numbers', async () => {
+    vi.useFakeTimers()
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    render()
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    expect(writeText).toHaveBeenCalledWith('line 41\nline 42\nline 43')
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(screen.getByRole('button', { name: '复制成功' })).toBeTruthy()
+    // While the ok label is showing, further clicks are no-ops.
+    fireEvent.click(screen.getByRole('button', { name: '复制成功' }))
+    expect(writeText).toHaveBeenCalledTimes(1)
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+  })
+
+  it('copies the whole window while the height cap hides its middle', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    render()
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    expect(writeText).toHaveBeenCalledWith(lines(10).map(line => line.text).join('\n'))
+    expect(await screen.findByRole('button', { name: '复制成功' })).toBeTruthy()
+  })
+
+  it('does not claim success when the host refuses the write', async () => {
+    Object.defineProperty(navigator, 'clipboard', {
+      configurable: true,
+      value: { writeText: vi.fn().mockRejectedValue(new Error('denied')) },
+    })
+    render()
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: '复制成功' })).toBeNull()
+  })
+
+  it('merges className onto the wrapper', () => {
+    const view = render()
+    expect(view.container.firstElementChild?.classList.contains('x')).toBe(true)
+  })
+})

From c2751d41266c18f6b5c35283416f01102f5ada55 Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 18:53:09 +0800
Subject: [PATCH 04/43] test(snapshot): re-record cordis-inspect golden for the
 search card tag

The widened ToolResultView (adding SearchResultView and its member types) shows
in the tools API type surface that cordis_inspect reports, so the
cordis-inspect-jsdoc golden shifts. No other scenario renders a search result
body, so no other snapshot changes. Refreshed keyless.
---
 .../tests/snapshots/cordis-inspect-jsdoc/session.jsonl          | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
index ea8dad9a96..2abca25ea9 100644
--- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
@@ -11,7 +11,7 @@
 {"type":"assistant/chunk","seq":9,"time":1783951000009,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":10,"time":1784449176722,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"1ac37046-d1c0-4ef6-9ea9-963e4b46d1cf"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}
 {"type":"tool/call","seq":11,"time":1784449176722,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}}
-{"type":"tool/result","seq":12,"time":1784449176732,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly status: AgentStatus;\n        readonly acceptsNextStep: boolean;\n        readonly ctx: Context;\n        send(message: UserMessage, options: SendOptions): void;\n        updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type Branded = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export type InboxAction = {\n        readonly kind: 'edit';\n        readonly content: ContentBlock[];\n    } | {\n        readonly kind: 'remove';\n    };\n    export type InboxActionResult = 'applied' | 'not-found';\n    export type InboxItemId = Branded<'InboxItemId'>;\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        };\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SendOptions {\n        target: SendTarget;\n        wakeup: boolean;\n    }\n    export type SendTarget = 'next-turn' | 'next-step';\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent;\n        requestHeader(): EpochHeader | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n            trigger: TurnTrigger;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'steering/message': {\n            turn: number;\n            message: UserMessage;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly delegationDepth?: number;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result' | 'steering/message';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise;\n        finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record;\n    }\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n        };\n        error: {\n            kind: 'error';\n            step: number;\n        } & ({\n            failure: LlmFailure;\n            message?: never;\n            code?: never;\n        } | {\n            message: string;\n            code?: string;\n            failure?: never;\n        });\n        disposed: {\n            kind: 'disposed';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n    export interface TurnTriggerMap {\n        message: {\n            kind: 'message';\n            source: MessageSource;\n        };\n        retry: {\n            kind: 'retry';\n        };\n        injection: {\n            kind: 'injection';\n            source: MessageSource;\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }"}],"isError":false}],"role":"user","id":"1c43b8df-aae8-42e7-8253-5b275edc09bc"}},"sourceEventSeqs":[11],"surfaceOp":"append"}
+{"type":"tool/result","seq":12,"time":1784449176732,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly status: AgentStatus;\n        readonly acceptsNextStep: boolean;\n        readonly ctx: Context;\n        send(message: UserMessage, options: SendOptions): void;\n        updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type Branded = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export type InboxAction = {\n        readonly kind: 'edit';\n        readonly content: ContentBlock[];\n    } | {\n        readonly kind: 'remove';\n    };\n    export type InboxActionResult = 'applied' | 'not-found';\n    export type InboxItemId = Branded<'InboxItemId'>;\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        };\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SearchFileMatches {\n        path: string;\n        matches: SearchLineMatch[];\n    }\n    export interface SearchLineMatch {\n        lineNumber: number;\n        line: string;\n    }\n    export interface SearchMatchesResultView {\n        card: 'search';\n        kind: 'matches';\n        title?: string;\n        files: SearchFileMatches[];\n        truncated: boolean;\n        total: number;\n        content?: ContentBlock[];\n    }\n    export interface SearchPathsResultView {\n        card: 'search';\n        kind: 'paths';\n        title?: string;\n        paths: string[];\n        truncated: boolean;\n        total: number;\n        content?: ContentBlock[];\n    }\n    export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n    export interface SendOptions {\n        target: SendTarget;\n        wakeup: boolean;\n    }\n    export type SendTarget = 'next-turn' | 'next-step';\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent;\n        requestHeader(): EpochHeader | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n            trigger: TurnTrigger;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'steering/message': {\n            turn: number;\n            message: UserMessage;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly delegationDepth?: number;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result' | 'steering/message';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise;\n        finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record;\n    }\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n        };\n        error: {\n            kind: 'error';\n            step: number;\n        } & ({\n            failure: LlmFailure;\n            message?: never;\n            code?: never;\n        } | {\n            message: string;\n            code?: string;\n            failure?: never;\n        });\n        disposed: {\n            kind: 'disposed';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n    export interface TurnTriggerMap {\n        message: {\n            kind: 'message';\n            source: MessageSource;\n        };\n        retry: {\n            kind: 'retry';\n        };\n        injection: {\n            kind: 'injection';\n            source: MessageSource;\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }"}],"isError":false}],"role":"user","id":"1c43b8df-aae8-42e7-8253-5b275edc09bc"}},"sourceEventSeqs":[11],"surfaceOp":"append"}
 {"type":"step/end","seq":13,"time":1784449176732,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":14,"time":1784449176733,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":15,"time":1783951000015,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}

From 47ee9764e903888190783f12f6640e9ca1084a0f Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 18:59:16 +0800
Subject: [PATCH 05/43] test(snapshot): re-apply search card type surface after
 master merge

---
 .../tests/snapshots/cordis-inspect-jsdoc/session.jsonl          | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
index c47cb8c89f..6b50bb2ac0 100644
--- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
@@ -11,7 +11,7 @@
 {"type":"assistant/chunk","seq":9,"time":1783951000009,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":10,"time":1784449176722,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"1ac37046-d1c0-4ef6-9ea9-963e4b46d1cf"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}
 {"type":"tool/call","seq":11,"time":1784449176722,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}}
-{"type":"tool/result","seq":12,"time":1784449176732,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly status: AgentStatus;\n        readonly acceptsNextStep: boolean;\n        readonly ctx: Context;\n        send(message: UserMessage, options: SendOptions): void;\n        updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type Branded = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export type InboxAction = {\n        readonly kind: 'edit';\n        readonly content: ContentBlock[];\n    } | {\n        readonly kind: 'remove';\n    };\n    export type InboxActionResult = 'applied' | 'not-found';\n    export type InboxItemId = Branded<'InboxItemId'>;\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        };\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SendOptions {\n        target: SendTarget;\n        wakeup: boolean;\n    }\n    export type SendTarget = 'next-turn' | 'next-step';\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent;\n        requestHeader(): EpochHeader | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n            trigger: TurnTrigger;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'steering/message': {\n            turn: number;\n            message: UserMessage;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n        'session/end-seed': Record;\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly delegationDepth?: number;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result' | 'steering/message';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise;\n        finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record;\n    }\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n        };\n        error: {\n            kind: 'error';\n            step: number;\n        } & ({\n            failure: LlmFailure;\n            message?: never;\n            code?: never;\n        } | {\n            message: string;\n            code?: string;\n            failure?: never;\n        });\n        disposed: {\n            kind: 'disposed';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n    export interface TurnTriggerMap {\n        message: {\n            kind: 'message';\n            source: MessageSource;\n        };\n        retry: {\n            kind: 'retry';\n        };\n        injection: {\n            kind: 'injection';\n            source: MessageSource;\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }"}],"isError":false}],"role":"user","id":"1c43b8df-aae8-42e7-8253-5b275edc09bc"}},"sourceEventSeqs":[11],"surfaceOp":"append"}
+{"type":"tool/result","seq":12,"time":1784449176732,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly status: AgentStatus;\n        readonly acceptsNextStep: boolean;\n        readonly ctx: Context;\n        send(message: UserMessage, options: SendOptions): void;\n        updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type Branded = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export type InboxAction = {\n        readonly kind: 'edit';\n        readonly content: ContentBlock[];\n    } | {\n        readonly kind: 'remove';\n    };\n    export type InboxActionResult = 'applied' | 'not-found';\n    export type InboxItemId = Branded<'InboxItemId'>;\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        };\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SearchFileMatches {\n        path: string;\n        matches: SearchLineMatch[];\n    }\n    export interface SearchLineMatch {\n        lineNumber: number;\n        line: string;\n    }\n    export interface SearchMatchesResultView {\n        card: 'search';\n        kind: 'matches';\n        title?: string;\n        files: SearchFileMatches[];\n        truncated: boolean;\n        total: number;\n        content?: ContentBlock[];\n    }\n    export interface SearchPathsResultView {\n        card: 'search';\n        kind: 'paths';\n        title?: string;\n        paths: string[];\n        truncated: boolean;\n        total: number;\n        content?: ContentBlock[];\n    }\n    export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n    export interface SendOptions {\n        target: SendTarget;\n        wakeup: boolean;\n    }\n    export type SendTarget = 'next-turn' | 'next-step';\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent;\n        requestHeader(): EpochHeader | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n            trigger: TurnTrigger;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'steering/message': {\n            turn: number;\n            message: UserMessage;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n        'session/end-seed': Record;\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly delegationDepth?: number;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result' | 'steering/message';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise;\n        finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record;\n    }\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n        };\n        error: {\n            kind: 'error';\n            step: number;\n        } & ({\n            failure: LlmFailure;\n            message?: never;\n            code?: never;\n        } | {\n            message: string;\n            code?: string;\n            failure?: never;\n        });\n        disposed: {\n            kind: 'disposed';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n    export interface TurnTriggerMap {\n        message: {\n            kind: 'message';\n            source: MessageSource;\n        };\n        retry: {\n            kind: 'retry';\n        };\n        injection: {\n            kind: 'injection';\n            source: MessageSource;\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }"}],"isError":false}],"role":"user","id":"1c43b8df-aae8-42e7-8253-5b275edc09bc"}},"sourceEventSeqs":[11],"surfaceOp":"append"}
 {"type":"step/end","seq":13,"time":1784449176732,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":14,"time":1784449176733,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":15,"time":1783951000015,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}

From 69a84e14036cc00236b622b5bc87f808e73a0e71 Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 19:56:06 +0800
Subject: [PATCH 06/43] fix(web-read-card): align highlight grammars with read
 hints, fix fixture schema, restore running sweep

Register the full grammar set the read tool's langFromPath emits (python,
go, rust, yaml, markdown, html, and the rest) so a read card highlights the
same extensions the backend recognizes instead of returning undefined for
them. Rewrite highlightLines' terminator-line check to the explicit
last !== undefined form to keep a single branch for per-file coverage.

Add the running-state sweep animation to ReadRow, matching BashRow/ToolRow,
so a running read row shows executing feedback.

Use file_path (the real read tool schema field) in the turn 66 read fixture
sample, its presentCall branch, and the turn 64 run_code read sub-dispatches,
so the built-boot snapshot replays a production-shaped call and the details
panel shows the correct Input JSON.

Document why ReadBlock omits TerminalBlock's empty-window copy guard, and
correct the read-card-model {@link} and the turn 66 fixture comment.
---
 .../client/connection/src/client/fixture.ts   | 23 ++---
 .../src/client/contract/read-card-model.ts    |  3 +-
 .../src/client/toolviews/read-row.module.css  | 28 +++++-
 .../client/ui-primitives/src/ReadBlock.tsx    |  7 ++
 .../ui-primitives/src/markdown/highlight.ts   | 90 +++++++++++++++++--
 5 files changed, 132 insertions(+), 19 deletions(-)

diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 6c177e6c70..0a2379c70e 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -267,8 +267,8 @@ function buildAlphaLog(): SessionEvent[] {
     const turn = 64
     const callId = `fx-call-${turn}`
     const program = 'const listing = await tools.bash({ command: "ls notes", description: "List notes" })\n'
-      + 'const demo = await tools.read({ path: "notes/demo.txt" })\n'
-      + 'await tools.read({ path: "notes/missing.txt" }).catch(() => "tolerated")\n'
+      + 'const demo = await tools.read({ file_path: "notes/demo.txt" })\n'
+      + 'await tools.read({ file_path: "notes/missing.txt" }).catch(() => "tolerated")\n'
       + 'return { listing, demo }'
     const args = JSON.stringify({ code: program, description: 'Read the notes files and summarize' })
     push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
@@ -293,8 +293,8 @@ function buildAlphaLog(): SessionEvent[] {
       })
     }
     dispatchPair(1, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt\nnew-demo.txt')
-    dispatchPair(2, 'read', { path: 'notes/demo.txt' }, 'hello fixture\n')
-    dispatchPair(3, 'read', { path: 'notes/missing.txt' }, 'Error: ENOENT: notes/missing.txt not found', true)
+    dispatchPair(2, 'read', { file_path: 'notes/demo.txt' }, 'hello fixture\n')
+    dispatchPair(3, 'read', { file_path: 'notes/missing.txt' }, 'Error: ENOENT: notes/missing.txt not found', true)
     push({
       type: 'tool/result', surfaceOp: 'append',
       data: { turn, step: 0, message: toolResultMessage(callId, text('{"listing":"demo.txt\\nnew-demo.txt","demo":"hello fixture\\n"}'), false) },
@@ -326,13 +326,16 @@ function buildAlphaLog(): SessionEvent[] {
   // Turn 66: the read sample — a WINDOW past an offset so the card draws file
   // line numbers starting above 1 and a "showing N of M" note (the window is
   // shorter than READ_SAMPLE_TOTAL), with a `ts` language hint the shiki path
-  // highlights. Named `read`, so it exercises the keyed ReadRow registration
-  // (the render-site fallback row is covered by the read sub-dispatches in the
-  // turn 64 run_code sample). The read render intent is result-side only, so its
-  // pending call stays a generic `kind: 'read'` card; presentResult carries the
+  // highlights. Named `read`, so it exercises the keyed ReadRow registration.
+  // The render-site fallback ROW SHAPE (a read call on the generic flattened
+  // path) is covered by the turn 64 run_code read sub-dispatches, which
+  // session.ts folds with resultView: null; the fallback-row + read-CARD
+  // combination is pinned by the web_fetch case in read-card.spec.tsx, not by
+  // this fixture. The read render intent is result-side only, so its pending
+  // call stays a generic `kind: 'read'` card; presentResult carries the
   // structured window. Ordered BEFORE the todo turn for the same reason the
   // terminal sample is: the standing plan retires at the next `turn/start`.
-  toolTurn(66, 'read', `{"path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
+  toolTurn(66, 'read', `{"file_path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
 
   const todoArgs = JSON.stringify({ todos: fixtureTodos })
   toolTurn(67, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
@@ -375,7 +378,7 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
     // carries no file content until execute returns. The rich read card arrives
     // in presentResult.
     case 'read':
-      return { card: 'generic', title: `Read ${str(args.path)}`, kind: 'read', locations: [{ path: str(args.path) }] }
+      return { card: 'generic', title: `Read ${str(args.file_path)}`, kind: 'read', locations: [{ path: str(args.file_path) }] }
     case 'edit':
       return { card: 'generic', title: `Edit ${str(args.file_path)}`, kind: 'edit', rawInput: args }
     case 'write':
diff --git a/packages/client/ui-conversation/src/client/contract/read-card-model.ts b/packages/client/ui-conversation/src/client/contract/read-card-model.ts
index 83779722f8..62a591bb17 100644
--- a/packages/client/ui-conversation/src/client/contract/read-card-model.ts
+++ b/packages/client/ui-conversation/src/client/contract/read-card-model.ts
@@ -23,7 +23,8 @@ import { relativizeToCwd, type ToolCallBlock } from './tool-call-model.ts'
  * scannable across many calls, while the details panel is the single-call
  * reading surface. A design constant of this UI's row geometry, not a
  * deployment choice, so it is fixed here rather than a plugin Config field. The
- * same split {@link CHAT_TERMINAL_MAX_LINES} draws for terminal output.
+ * same split [`CHAT_TERMINAL_MAX_LINES`](./terminal-card-model.ts) draws for
+ * terminal output.
  */
 export const CHAT_READ_MAX_LINES = 8
 
diff --git a/packages/client/ui-conversation/src/client/toolviews/read-row.module.css b/packages/client/ui-conversation/src/client/toolviews/read-row.module.css
index b83b395f1a..a03a949451 100644
--- a/packages/client/ui-conversation/src/client/toolviews/read-row.module.css
+++ b/packages/client/ui-conversation/src/client/toolviews/read-row.module.css
@@ -15,7 +15,7 @@
 }
 
 .root {
-  position: relative;
+  position: relative; /* sweep-glare overlay anchor */
   overflow: hidden;
   display: flex;
   align-items: center;
@@ -23,6 +23,32 @@
   min-width: 0;
 }
 
+/* Running sweep glare — same pattern as BashRow/ToolRow, so a running read row
+   gives the same executing feedback a running command row does. The leading
+   read icon stays static (a read has no per-step state to animate); the sweep
+   is the row-level running signal. */
+.root[data-state='running']::after {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 300px;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
+    transparent 100%
+  );
+  animation: dsh-read-row-sweep 2.6s ease-out infinite;
+  pointer-events: none;
+}
+
+@keyframes dsh-read-row-sweep {
+  0% { left: -300px; }
+  90%, 100% { left: 100%; }
+}
+
 .leading {
   flex: none;
   width: 16px;
diff --git a/packages/client/ui-primitives/src/ReadBlock.tsx b/packages/client/ui-primitives/src/ReadBlock.tsx
index df9658e3dd..bd5ef6f5ac 100644
--- a/packages/client/ui-primitives/src/ReadBlock.tsx
+++ b/packages/client/ui-primitives/src/ReadBlock.tsx
@@ -131,6 +131,13 @@ export function ReadBlock({
             {`显示 ${lines.length} / ${totalLines} 行`}
           )}
           {lang ?? ''}
+          {/* No empty-window guard around the copy control, unlike TerminalBlock
+              (which hides copy on empty output): a read card is reached only for
+              a settled read whose result view declares `card:'read'`, and the
+              read tool projects that view solely for a parsed envelope with a
+              line window. An empty or non-envelope result falls back to the
+              generic card upstream (readCardModel returns null), so `lines` is
+              never empty here — the branch TerminalBlock needs cannot arise. */}
           
diff --git a/packages/client/ui-primitives/src/markdown/highlight.ts b/packages/client/ui-primitives/src/markdown/highlight.ts
index 74709d4ac2..cd669b9919 100644
--- a/packages/client/ui-primitives/src/markdown/highlight.ts
+++ b/packages/client/ui-primitives/src/markdown/highlight.ts
@@ -5,9 +5,11 @@
  * theme package's token sheets as `--shiki-*` custom properties (light and
  * dark blocks), never here — the repo's tokens-only styling rule.
  *
- * Grammars are the set the harness actually renders: TypeScript programs
- * (`run_code` bodies; TS pulls in JS via grammar embedding), shell commands,
- * and JSON payloads. An unknown or absent language falls back to plain text
+ * Grammars are the set the harness actually renders: the markdown-fence and
+ * `run_code` languages (TypeScript, shell, JSON) plus the file-extension
+ * language hints the read tool's `langFromPath` emits (`packages/fs/tool-fs`),
+ * so a read card highlights the same source, config, and markup extensions the
+ * backend recognizes. An unknown or absent language falls back to plain text
  * (no highlighting, still monospace) — never an error.
  */
 
@@ -16,14 +18,55 @@ import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
 import langTs from '@shikijs/langs/typescript'
 import langBash from '@shikijs/langs/shellscript'
 import langJson from '@shikijs/langs/json'
+import langPython from '@shikijs/langs/python'
+import langRuby from '@shikijs/langs/ruby'
+import langGo from '@shikijs/langs/go'
+import langRust from '@shikijs/langs/rust'
+import langJava from '@shikijs/langs/java'
+import langC from '@shikijs/langs/c'
+import langCpp from '@shikijs/langs/cpp'
+import langCsharp from '@shikijs/langs/csharp'
+import langKotlin from '@shikijs/langs/kotlin'
+import langSwift from '@shikijs/langs/swift'
+import langPhp from '@shikijs/langs/php'
+import langYaml from '@shikijs/langs/yaml'
+import langToml from '@shikijs/langs/toml'
+import langIni from '@shikijs/langs/ini'
+import langMarkdown from '@shikijs/langs/markdown'
+import langMdx from '@shikijs/langs/mdx'
+import langHtml from '@shikijs/langs/html'
+import langCss from '@shikijs/langs/css'
+import langScss from '@shikijs/langs/scss'
+import langLess from '@shikijs/langs/less'
+import langSql from '@shikijs/langs/sql'
+import langXml from '@shikijs/langs/xml'
+import langLua from '@shikijs/langs/lua'
 import type { HighlighterCore } from 'shiki/core'
 import type { CSSProperties } from 'react'
 
+/**
+ * Grammars the singleton registers; each entry's own `name` is the id
+ * `codeToTokens`/`codeToHtml` resolve. The TypeScript grammar embeds JS/JSX/TSX,
+ * so the JS-family fence aliases resolve to it rather than a separate grammar.
+ */
+const LANGS = [
+  langTs, langBash, langJson,
+  langPython, langRuby, langGo, langRust, langJava,
+  langC, langCpp, langCsharp, langKotlin, langSwift, langPhp,
+  langYaml, langToml, langIni,
+  langMarkdown, langMdx, langHtml, langCss, langScss, langLess,
+  langSql, langXml, langLua,
+]
+
 /**
  * Language ids (and aliases) the singleton registers; everything else renders
  * plain. A Map, not an object: fence info strings are assistant-authored, so
  * a label like `constructor` or `__proto__` must miss instead of resolving an
- * inherited property and crashing the renderer inside shiki.
+ * inherited property and crashing the renderer inside shiki. Keys cover both
+ * the markdown-fence aliases `CodeBlock` uses and the file-extension hint ids
+ * the read tool's `langFromPath` emits, so both callers resolve the same
+ * grammars. The JS family maps to the TypeScript grammar (which embeds it),
+ * unchanged from when this was the only non-shell/JSON grammar.
  */
 const LANG_ALIASES = new Map([
   ['typescript', 'typescript'],
@@ -31,6 +74,7 @@ const LANG_ALIASES = new Map([
   ['tsx', 'typescript'],
   ['javascript', 'typescript'],
   ['js', 'typescript'],
+  ['jsx', 'typescript'],
   ['shellscript', 'shellscript'],
   ['bash', 'shellscript'],
   ['sh', 'shellscript'],
@@ -38,6 +82,35 @@ const LANG_ALIASES = new Map([
   ['zsh', 'shellscript'],
   ['json', 'json'],
   ['jsonc', 'json'],
+  ['py', 'python'],
+  ['python', 'python'],
+  ['rb', 'ruby'],
+  ['ruby', 'ruby'],
+  ['go', 'go'],
+  ['rs', 'rust'],
+  ['rust', 'rust'],
+  ['java', 'java'],
+  ['c', 'c'],
+  ['cpp', 'cpp'],
+  ['cs', 'csharp'],
+  ['csharp', 'csharp'],
+  ['kotlin', 'kotlin'],
+  ['swift', 'swift'],
+  ['php', 'php'],
+  ['yaml', 'yaml'],
+  ['yml', 'yaml'],
+  ['toml', 'toml'],
+  ['ini', 'ini'],
+  ['md', 'markdown'],
+  ['markdown', 'markdown'],
+  ['mdx', 'mdx'],
+  ['html', 'html'],
+  ['css', 'css'],
+  ['scss', 'scss'],
+  ['less', 'less'],
+  ['sql', 'sql'],
+  ['xml', 'xml'],
+  ['lua', 'lua'],
 ])
 
 /** All token colors resolve through `--shiki-*` custom properties (theme package sheets). */
@@ -53,7 +126,7 @@ let singleton: HighlighterCore | undefined
 function highlighter(): HighlighterCore {
   singleton ??= createHighlighterCoreSync({
     themes: [cssVariablesTheme],
-    langs: [langTs, langBash, langJson],
+    langs: LANGS,
     engine: createJavaScriptRegexEngine({ forgiving: true }),
   })
   return singleton
@@ -114,8 +187,11 @@ export function highlightLines(code: string, lang: string | undefined): Highligh
   const { tokens } = highlighter().codeToTokens(code, { lang: resolved, theme: 'css-variables' })
   // shiki tokenizes `a\nb` into two lines; a trailing newline (`a\n`) adds a
   // third, empty line the caller's own line array does not carry. Drop that
-  // one terminator line so the two structures stay in step.
-  const lines = tokens.length > 1 && tokens[tokens.length - 1]?.length === 0
+  // one terminator line so the two structures stay in step. The explicit
+  // `last !== undefined` (over `tokens[...]?.length`) keeps a single branch for
+  // per-file coverage, matching TerminalBlock's terminator check.
+  const last = tokens[tokens.length - 1]
+  const lines = tokens.length > 1 && last !== undefined && last.length === 0
     ? tokens.slice(0, -1)
     : tokens
   return lines.map(line => line.map(token => ({ text: token.content, style: { color: token.color } })))

From e98f458852d5513ee29f95a88b4e7dfd62598ffa Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 21:28:38 +0800
Subject: [PATCH 07/43] perf(web-read-card): lazy-load read grammars and guard
 empty-window copy

Only TypeScript, shell, and JSON grammars load at Web boot; the read card's
wider langFromPath extension set loads through dynamic imports on first use,
so a session that never opens a read card in one of those languages avoids
~1.6 MB of grammar modules and their synchronous init. ReadBlock/CodeBlock
re-render on grammar-load via useSyncExternalStore, picking up highlighting
once the grammar registers. ReadBlock hides the copy control on an empty
window (a successful read of an empty file settles to lines: [] with
card:'read'), matching TerminalBlock so it cannot wipe the clipboard.
---
 ...026-07-30-web-read-card-frontend.i18n.yaml |   4 +-
 .../2026-07-30-web-read-card-frontend.md      |  10 +-
 .../2026-07-30-web-read-card-frontend.zh.md   |  10 +-
 .../client/ui-primitives/src/ReadBlock.tsx    |  37 ++--
 .../ui-primitives/src/markdown/CodeBlock.tsx  |  10 +-
 .../ui-primitives/src/markdown/highlight.ts   | 170 +++++++++++++-----
 .../ui-primitives/tests/code-block.spec.tsx   |  18 ++
 .../ui-primitives/tests/read-block.spec.tsx   |  28 ++-
 8 files changed, 216 insertions(+), 71 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
index 9ed8258368..7efb9e75d5 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.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-30-web-read-card-frontend.md
-2026-07-30-web-read-card-frontend.md: 3d1893b72dc9ef8fed3ee3d92e52980b3eb06743
-2026-07-30-web-read-card-frontend.zh.md: acfb31a8e6306a90f634075754074e163d2431e1
+2026-07-30-web-read-card-frontend.md: f504cab7705d03f6d3e911da05c509da50bb9abe
+2026-07-30-web-read-card-frontend.zh.md: b6314f21ba3eb2283788374b10c77ed22e26d16c
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
index 3d1893b72d..f504cab770 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
@@ -20,12 +20,18 @@ The chat row renders the card **resident** under the summary line, capped at `CH
 
 Whole-row collapse/expand (defaulting every tool call to collapsed) is a separate later change that will flip every resident card at once; this note's card is resident, matching the terminal card it sits beside.
 
+**Read-card grammars load lazily; only the boot three stay eager.** `highlight.ts` is a platform seed `ui-primitives` loads on every Web boot, and its warm-up unconditionally builds the shiki singleton. The read card's `langFromPath` hints span the full source/config/markup extension set (python, rust, yaml, html, …); registering all of them eagerly would add ~1.6 MB of grammar modules to the boot chunk and their synchronous init to every session, including sessions that never open a read card. So only the three grammars every session already renders — TypeScript, shell, JSON (the markdown-fence and `run_code` languages) — load at boot. Each read-card extension grammar sits behind a dynamic `import()` in `LAZY_GRAMMARS`, keyed by the grammar id its aliases resolve to. On the first `highlightLines`/`highlightToHtml` call for a lazy language, `ensureGrammar` starts the import (once) and returns not-ready, so the card renders plain that frame; when the import resolves it registers the grammar with `loadLanguageSync`, bumps a load counter, and notifies subscribers. `ReadBlock` and `CodeBlock` subscribe through `useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount)`, so the card re-renders with highlighting the moment the grammar is ready. An unknown/absent language still returns undefined synchronously (plain, never an error).
+
+**The empty-window copy control is hidden, matching `TerminalBlock`.** A successful read of an empty file returns `lines: []`, `totalLines: 0`, and `presentResult` still projects `card: 'read'`, so the empty-window branch is reachable — the read card is not, as an earlier draft assumed, unreachable for an empty result. `ReadBlock` therefore hides the copy control when `lines` is empty, exactly as `TerminalBlock` hides copy on empty output, so the button can never wipe the clipboard with an empty string.
+
 ## Alternatives considered
 
 **Extend `CodeBlock` with an optional line-number gutter and `startLine`.** Rejected: it imposes a read-specific gutter, a windowed-count note, and a height cap on every markdown fence and `run_code` body that shares `CodeBlock`, for no benefit to those callers. The genuinely shared surface is the shiki grammar singleton, which both blocks reuse through `highlight.ts`; the chrome around it differs (a read has a gutter and a window note, a fence has neither), so a second small primitive is the correct split, exactly as `TerminalBlock` is a second primitive over the same tokens rather than a `CodeBlock` mode.
 
 **Reuse `highlightToHtml` and inject gutter numbers with CSS counters.** Rejected: the single-`
` HTML shiki emits has no per-line boundary a gutter can hang a file line number off (a windowed read's numbers start above 1 and are not a simple CSS counter increment), and parsing the numbers back out of the HTML would be fragile. `codeToTokens` gives the per-line token structure directly.
 
+**Register all read-card grammars eagerly in the boot warm-up.** Rejected: it puts ~1.6 MB of grammar modules and their synchronous init on every Web boot for a card most sessions never open. The lazy path costs a single plain-first frame the first time a given language is read, then highlights on the grammar-load re-render; the boot cost is paid only for the three grammars every session already renders.
+
 ## Consequences
 
 `ui-primitives` gains `ReadBlock` and `highlightLines`; no new runtime dependency (shiki was already present for `CodeBlock`). `ReadBlock` reads only the read view's fields, so it stays a pure function of what the render intent carries — no session lookups, replay-safe like the presenters that produce the view. A UI without the read capability still gets the backend's `content` fallback (the envelope-stripped text) through the generic card, unchanged.
@@ -34,11 +40,11 @@ A read row in the Web chat now carries the file content resident, a deliberate d
 
 ## Testing
 
-`packages/client/ui-primitives/tests/read-block.spec.tsx` pins the primitive and the token path: `highlightLines`' per-line css-variables runs, its trailing-terminator-line drop and the genuinely-blank-final-line case, and its `undefined` for an unknown/absent language; and `ReadBlock`'s gutter-numbered rows keeping the file's own numbers, the highlighted-vs-plain content arms, the banner (label, language, the count note only when the read is a window), the head/tail height cap with its `aria-expanded` toggle, and the copy control writing the window's raw text on both the accepted and refused clipboard paths. Both `ReadBlock.tsx` and `highlight.ts` hold per-file 100% coverage (the latter over this spec plus `code-block.spec.tsx`, which covers `highlightToHtml`).
+`packages/client/ui-primitives/tests/read-block.spec.tsx` pins the primitive and the token path: `highlightLines`' per-line css-variables runs, its trailing-terminator-line drop and the genuinely-blank-final-line case, its `undefined` for an unknown/absent language, and its lazy path (a lazy grammar returns plain on first touch, then highlights after the import registers and the subscriber fires); and `ReadBlock`'s gutter-numbered rows keeping the file's own numbers, the highlighted-vs-plain content arms, the banner (label, language, the count note only when the read is a window), the head/tail height cap with its `aria-expanded` toggle, the copy control writing the window's raw text on both the accepted and refused clipboard paths, and the empty-window arm hiding the copy control. `code-block.spec.tsx` covers `highlightToHtml` including its lazy path over every read-card grammar (each dynamic import thunk touched once). Both `ReadBlock.tsx` and `highlight.ts` (and `CodeBlock.tsx`) hold per-file 100% coverage across the two specs.
 
 `packages/client/ui-conversation/tests/read-card.spec.tsx` pins the wiring at every render site: `readCardModel`'s derivation and each null arm (running read, no view, generic view, unknown card), the result title replacing the relativized path, the path relativization against the workspace, the copy-not-alias of the frozen line array; the resident card in `GenericToolCard`'s fallback and in the keyed `ReadRow` (plus its path link opening the host, its running/error/stopped states, and its `read`-key registration); and the panel's Output section rendering the read card at full height while keeping the JSON Input section, with the running-read placeholder and non-read flattened-pre arms. That file sits on the coverage `exclude` list (`ui-conversation/src/*`), so it is written against no gate pressure.
 
-The fixture (`packages/client/connection/src/client/fixture.ts`) gains turn 66, a `read` call whose result view is a windowed read (lines starting at file line 41, `totalLines` 180, a `ts` hint), so the built-boot snapshot and a live `?fixture` server show the read card with its gutter numbers, highlighting, and count note. It is named `read` to exercise the keyed `ReadRow`; the render-site fallback row is already covered by the read sub-dispatches in the turn 64 `run_code` sample. It is ordered before the todo turn (now 67) for the same reason the terminal sample is: the standing plan retires at the next `turn/start`.
+The fixture (`packages/client/connection/src/client/fixture.ts`) gains turn 66, a `read` call whose result view is a windowed read (lines starting at file line 41, `totalLines` 180, a `ts` hint), so the built-boot snapshot and a live `?fixture` server show the read card with its gutter numbers, highlighting, and count note. It is named `read` to exercise the keyed `ReadRow`. The turn 64 `run_code` sample's nested read sub-dispatches do not exercise the render-site fallback read card: `session.ts` folds them with `resultView: null`, so they cover only the fallback row's generic row shape, not a read card inside it; the fallback-row read card is pinned by `read-card.spec.tsx`'s `web_fetch` case. Turn 66 is ordered before the todo turn (now 67) for the same reason the terminal sample is: the standing plan retires at the next `turn/start`.
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
index acfb31a8e6..b6314f21ba 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
@@ -20,12 +20,18 @@ Status: implemented
 
 整行折叠/展开(把每个工具调用默认折叠)是一个单独的后续改动,它会一次性翻转每张常驻卡片;本 note 的卡片是常驻的,与它旁边的终端卡片一致。
 
+**读取卡片的语法按需 lazy 加载,只有 boot 三种保持 eager。** `highlight.ts` 是 `ui-primitives` 在每次 Web 启动都加载的平台 seed,其预热会无条件构建 shiki 单例。读取卡片的 `langFromPath` 提示覆盖完整的源码/配置/标记扩展集(python、rust、yaml、html……);把它们全部 eager 注册会给启动 chunk 增加约 1.6 MB 的语法模块、并把它们的同步初始化摊给每个会话,包括从不打开读取卡片的会话。因此只有每个会话本就渲染的三种语法 —— TypeScript、shell、JSON(markdown 围栏与 `run_code` 语言)—— 在 boot 时加载。每种读取卡片扩展语法置于 `LAZY_GRAMMARS` 中一个动态 `import()` 之后,以其别名解析到的语法 id 为键。对某个 lazy 语言首次调用 `highlightLines`/`highlightToHtml` 时,`ensureGrammar` 启动 import(仅一次)并返回未就绪,于是卡片该帧渲染纯文本;import 解析后用 `loadLanguageSync` 注册该语法、递增一个加载计数、并通知订阅者。`ReadBlock` 与 `CodeBlock` 通过 `useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount)` 订阅,因此语法就绪的那一刻卡片就重渲染带上高亮。未知/缺省语言仍同步返回 undefined(纯文本,绝不报错)。
+
+**空窗口的复制控件被隐藏,与 `TerminalBlock` 对齐。** 成功读取一个空文件会返回 `lines: []`、`totalLines: 0`,且 `presentResult` 仍投出 `card: 'read'`,因此空窗口分支是可达的 —— 读取卡片并非如早前草稿所假设的对空结果不可达。故 `ReadBlock` 在 `lines` 为空时隐藏复制控件,正如 `TerminalBlock` 对空输出隐藏复制,使按钮绝不会用空字符串清空剪贴板。
+
 ## Alternatives considered
 
 **给 `CodeBlock` 加一个可选行号栏和 `startLine`。** 拒绝:这会把读取专属的行号栏、窗口计数提示和高度上限强加给共享 `CodeBlock` 的每个 markdown 围栏和 `run_code` 程序体,对那些调用者毫无好处。真正共享的界面是 shiki 语法单例,两个 block 都通过 `highlight.ts` 复用它;围绕它的外壳各不相同(读取有行号栏和窗口提示,围栏两者都没有),因此第二个小 primitive 是正确的切分 —— 正如 `TerminalBlock` 是基于同一套 token 的第二个 primitive,而不是 `CodeBlock` 的一种模式。
 
 **复用 `highlightToHtml`,用 CSS counter 注入行号。** 拒绝:shiki 产出的单 `
` HTML 没有可供行号栏挂上文件行号的逐行边界(窗口读取的行号从大于 1 处开始,不是简单的 CSS counter 自增),而从 HTML 里把行号解析回来又很脆弱。`codeToTokens` 直接给出逐行 token 结构。
 
+**在 boot 预热里 eager 注册所有读取卡片语法。** 拒绝:这会给每次 Web 启动摊上约 1.6 MB 语法模块及其同步初始化,只为一张多数会话从不打开的卡片。lazy 路径的代价是某个语言首次被读取时的一帧纯文本,随后在语法加载的重渲染里高亮;boot 代价只为每个会话本就渲染的三种语法付出。
+
 ## Consequences
 
 `ui-primitives` 增加 `ReadBlock` 和 `highlightLines`;没有新的运行时依赖(shiki 已因 `CodeBlock` 存在)。`ReadBlock` 只读取读取视图的字段,因此保持为渲染意图所承载内容的纯函数 —— 无会话查询,与产出该视图的 presenter 一样可安全回放。没有读取能力的 UI 仍通过通用卡片拿到后端的 `content` 回退(剥掉外壳的文本),保持不变。
@@ -34,11 +40,11 @@ Web 聊天里的读取行现在常驻承载文件内容,是相对纯摘要行
 
 ## Testing
 
-`packages/client/ui-primitives/tests/read-block.spec.tsx` 固定 primitive 与 token 路径:`highlightLines` 的逐行 css-variables 运行、它对尾部终止行的丢弃与真正空白末行的情形、以及它对未知/缺省语言返回 `undefined`;还有 `ReadBlock` 的带行号行保留文件自身编号、高亮与纯文本两条内容分支、横幅(标签、语言、仅当读取是窗口时的计数提示)、头/尾高度上限及其 `aria-expanded` 切换、以及复制控件在接受与拒绝两条剪贴板路径上写入窗口原始文本。`ReadBlock.tsx` 与 `highlight.ts` 均保持每文件 100% 覆盖(后者由本 spec 加上覆盖 `highlightToHtml` 的 `code-block.spec.tsx` 共同达成)。
+`packages/client/ui-primitives/tests/read-block.spec.tsx` 固定 primitive 与 token 路径:`highlightLines` 的逐行 css-variables 运行、它对尾部终止行的丢弃与真正空白末行的情形、它对未知/缺省语言返回 `undefined`、以及它的 lazy 路径(lazy 语法首次触碰返回纯文本,import 注册且订阅者触发后再高亮);还有 `ReadBlock` 的带行号行保留文件自身编号、高亮与纯文本两条内容分支、横幅(标签、语言、仅当读取是窗口时的计数提示)、头/尾高度上限及其 `aria-expanded` 切换、复制控件在接受与拒绝两条剪贴板路径上写入窗口原始文本、以及空窗口分支隐藏复制控件。`code-block.spec.tsx` 覆盖 `highlightToHtml`,含它对每种读取卡片语法的 lazy 路径(每个动态 import thunk 各触碰一次)。`ReadBlock.tsx`、`highlight.ts`(及 `CodeBlock.tsx`)在这两个 spec 上均保持每文件 100% 覆盖。
 
 `packages/client/ui-conversation/tests/read-card.spec.tsx` 固定每个渲染点的接线:`readCardModel` 的派生与每条 null 分支(运行中读取、无视图、通用视图、未知卡片)、结果标题替换化简后的路径、路径相对工作区的化简、冻结行数组的复制而非别名;`GenericToolCard` 回退中与 keyed `ReadRow` 中的常驻卡片(外加其路径链接打开宿主、其 running/error/stopped 状态、以及其 `read` 键注册);还有面板 Output 区段以全高渲染读取卡片同时保留 JSON Input 区段,含运行中读取占位与非读取摊平 pre 两条分支。该文件位于覆盖 `exclude` 列表(`ui-conversation/src/*`),因此不承受门槛压力。
 
-fixture(`packages/client/connection/src/client/fixture.ts`)增加 turn 66,一次 `read` 调用,其结果视图是窗口读取(行号从文件行 41 起、`totalLines` 180、`ts` 提示),使内置启动快照和实时 `?fixture` 服务器展示带行号、高亮和计数提示的读取卡片。它命名为 `read` 以驱动 keyed `ReadRow`;渲染点回退行已由 turn 64 的 `run_code` 样例中的读取子派发覆盖。它排在 todo turn(现为 67)之前,与终端样例同因:常驻计划在下一次 `turn/start` 退场。
+fixture(`packages/client/connection/src/client/fixture.ts`)增加 turn 66,一次 `read` 调用,其结果视图是窗口读取(行号从文件行 41 起、`totalLines` 180、`ts` 提示),使内置启动快照和实时 `?fixture` 服务器展示带行号、高亮和计数提示的读取卡片。它命名为 `read` 以驱动 keyed `ReadRow`。turn 64 的 `run_code` 样例中的嵌套读取子派发并不驱动渲染点回退读取卡片:`session.ts` 把它们折叠为 `resultView: null`,因此它们只覆盖回退行的通用行形状,而非回退行内的读取卡片;回退行读取卡片由 `read-card.spec.tsx` 的 `web_fetch` 用例钉住。turn 66 排在 todo turn(现为 67)之前,与终端样例同因:常驻计划在下一次 `turn/start` 退场。
 
 ## Related
 
diff --git a/packages/client/ui-primitives/src/ReadBlock.tsx b/packages/client/ui-primitives/src/ReadBlock.tsx
index bd5ef6f5ac..a6a83d3668 100644
--- a/packages/client/ui-primitives/src/ReadBlock.tsx
+++ b/packages/client/ui-primitives/src/ReadBlock.tsx
@@ -9,10 +9,15 @@
 // two cards collapse a long body at the same place. Colors resolve through
 // --shiki-*/--dsw-* tokens.
 
-import { useCallback, useMemo, useState } from 'react'
+import { useCallback, useMemo, useState, useSyncExternalStore } from 'react'
 import clsx from 'clsx'
 import { writeClipboard } from './clipboard.ts'
-import { highlightLines, type HighlightSpan } from './markdown/highlight.ts'
+import {
+  grammarLoadCount,
+  highlightLines,
+  subscribeGrammarLoaded,
+  type HighlightSpan,
+} from './markdown/highlight.ts'
 import css from './ReadBlock.module.css'
 
 /**
@@ -75,9 +80,14 @@ export function ReadBlock({
   // Highlighting the whole window in one call (not line by line) keeps grammar
   // context across lines — a multi-line string or comment stays one construct.
   const raw = useMemo(() => lines.map(line => line.text).join('\n'), [lines])
+  // Re-render when a lazy grammar finishes loading, so a read card that showed
+  // plain text while its language's grammar imported picks up highlighting. The
+  // snapshot value is opaque; only its change across renders drives the memo.
+  const loaded = useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount, grammarLoadCount)
   // Per-line highlighted runs aligned 1:1 with `lines`; undefined for an
-  // unknown/absent language, when every line renders as bare text.
-  const highlighted = useMemo(() => highlightLines(raw, lang), [raw, lang])
+  // unknown/absent (or not-yet-loaded) language, when every line renders as
+  // bare text.
+  const highlighted = useMemo(() => highlightLines(raw, lang), [raw, lang, loaded])
   const [expanded, setExpanded] = useState(false)
   const [copied, setCopied] = useState(false)
 
@@ -131,16 +141,15 @@ export function ReadBlock({
             {`显示 ${lines.length} / ${totalLines} 行`}
           )}
           {lang ?? ''}
-          {/* No empty-window guard around the copy control, unlike TerminalBlock
-              (which hides copy on empty output): a read card is reached only for
-              a settled read whose result view declares `card:'read'`, and the
-              read tool projects that view solely for a parsed envelope with a
-              line window. An empty or non-envelope result falls back to the
-              generic card upstream (readCardModel returns null), so `lines` is
-              never empty here — the branch TerminalBlock needs cannot arise. */}
-          
+          {/* Hide copy on an empty window, matching TerminalBlock's empty-output
+              guard: a successful read of an empty file returns lines: [] with
+              card:'read', so this branch is reachable, and copying then would
+              wipe the clipboard with an empty string. */}
+          {lines.length > 0 && (
+            
+          )}
         
       
       
diff --git a/packages/client/ui-primitives/src/markdown/CodeBlock.tsx b/packages/client/ui-primitives/src/markdown/CodeBlock.tsx index 9c7e968053..96c9c75a11 100644 --- a/packages/client/ui-primitives/src/markdown/CodeBlock.tsx +++ b/packages/client/ui-primitives/src/markdown/CodeBlock.tsx @@ -4,10 +4,10 @@ // plain fallback for everything else. Chrome (language banner + copy) matches // deepsuite `@deepseek/md` code blocks; token colors stay on `--shiki-*`. -import { useCallback, useMemo, useRef, useState } from 'react' +import { useCallback, useMemo, useRef, useState, useSyncExternalStore } from 'react' import clsx from 'clsx' import { writeClipboard } from '../clipboard.ts' -import { highlightToHtml } from './highlight.ts' +import { grammarLoadCount, highlightToHtml, subscribeGrammarLoaded } from './highlight.ts' import css from './CodeBlock.module.css' export interface CodeBlockProps { @@ -21,7 +21,11 @@ export interface CodeBlockProps { export function CodeBlock({ code, lang, className }: CodeBlockProps) { const trimmed = code.endsWith('\n') ? code.slice(0, -1) : code - const html = useMemo(() => highlightToHtml(trimmed, lang), [trimmed, lang]) + // Re-render when a lazy grammar finishes loading, so a fence that showed plain + // text while its language's grammar imported picks up highlighting. The + // snapshot value is opaque; only its change across renders drives the memo. + const loaded = useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount, grammarLoadCount) + const html = useMemo(() => highlightToHtml(trimmed, lang), [trimmed, lang, loaded]) const rootRef = useRef(null) const [copied, setCopied] = useState(false) diff --git a/packages/client/ui-primitives/src/markdown/highlight.ts b/packages/client/ui-primitives/src/markdown/highlight.ts index cd669b9919..2116fa2b93 100644 --- a/packages/client/ui-primitives/src/markdown/highlight.ts +++ b/packages/client/ui-primitives/src/markdown/highlight.ts @@ -5,12 +5,17 @@ * theme package's token sheets as `--shiki-*` custom properties (light and * dark blocks), never here — the repo's tokens-only styling rule. * - * Grammars are the set the harness actually renders: the markdown-fence and - * `run_code` languages (TypeScript, shell, JSON) plus the file-extension - * language hints the read tool's `langFromPath` emits (`packages/fs/tool-fs`), - * so a read card highlights the same source, config, and markup extensions the - * backend recognizes. An unknown or absent language falls back to plain text - * (no highlighting, still monospace) — never an error. + * Only the three markdown-fence and `run_code` grammars (TypeScript, shell, + * JSON) load into the singleton at boot — the set every session renders. The + * read card's wider extension set (the file-extension language hints the read + * tool's `langFromPath` emits — `packages/fs/tool-fs`: python, rust, yaml, + * markup, …) is imported lazily and registered the first time such a language + * is requested, so a session that never opens a read card in one of those + * languages pays neither the ~1.6 MB of grammar modules nor their synchronous + * init. The first render of a lazy language falls back to plain text while its + * grammar loads, then {@link onGrammarLoaded} notifies subscribers to re-render + * with highlighting. An unknown or absent language falls back to plain text (no + * highlighting, still monospace) — never an error. */ import { createHighlighterCoreSync, createCssVariablesTheme } from 'shiki/core' @@ -18,55 +23,66 @@ import { createJavaScriptRegexEngine } from 'shiki/engine/javascript' import langTs from '@shikijs/langs/typescript' import langBash from '@shikijs/langs/shellscript' import langJson from '@shikijs/langs/json' -import langPython from '@shikijs/langs/python' -import langRuby from '@shikijs/langs/ruby' -import langGo from '@shikijs/langs/go' -import langRust from '@shikijs/langs/rust' -import langJava from '@shikijs/langs/java' -import langC from '@shikijs/langs/c' -import langCpp from '@shikijs/langs/cpp' -import langCsharp from '@shikijs/langs/csharp' -import langKotlin from '@shikijs/langs/kotlin' -import langSwift from '@shikijs/langs/swift' -import langPhp from '@shikijs/langs/php' -import langYaml from '@shikijs/langs/yaml' -import langToml from '@shikijs/langs/toml' -import langIni from '@shikijs/langs/ini' -import langMarkdown from '@shikijs/langs/markdown' -import langMdx from '@shikijs/langs/mdx' -import langHtml from '@shikijs/langs/html' -import langCss from '@shikijs/langs/css' -import langScss from '@shikijs/langs/scss' -import langLess from '@shikijs/langs/less' -import langSql from '@shikijs/langs/sql' -import langXml from '@shikijs/langs/xml' -import langLua from '@shikijs/langs/lua' import type { HighlighterCore } from 'shiki/core' import type { CSSProperties } from 'react' -/** - * Grammars the singleton registers; each entry's own `name` is the id - * `codeToTokens`/`codeToHtml` resolve. The TypeScript grammar embeds JS/JSX/TSX, - * so the JS-family fence aliases resolve to it rather than a separate grammar. - */ -const LANGS = [ - langTs, langBash, langJson, - langPython, langRuby, langGo, langRust, langJava, - langC, langCpp, langCsharp, langKotlin, langSwift, langPhp, - langYaml, langToml, langIni, - langMarkdown, langMdx, langHtml, langCss, langScss, langLess, - langSql, langXml, langLua, -] +/** A shiki grammar module's default export (a `LanguageRegistration[]`), taken + * from a boot grammar so no direct `@shikijs/types` dependency is needed. */ +type LangModule = { default: typeof langTs } /** - * Language ids (and aliases) the singleton registers; everything else renders + * Grammars the singleton loads at boot; each entry's own `name` is the id + * `codeToTokens`/`codeToHtml` resolve. The TypeScript grammar embeds JS/JSX/TSX, + * so the JS-family fence aliases resolve to it rather than a separate grammar. + * The read card's wider set loads lazily through {@link LAZY_GRAMMARS}. + */ +const LANGS = [langTs, langBash, langJson] + +/** + * The read card's extension grammars, each behind a dynamic import so its + * module stays out of the boot chunk until a read of that language renders. + * Keyed by the grammar id (`LanguageRegistration.name`) the aliases resolve to. + * `@shikijs/langs`' default export is a `LanguageRegistration[]`; the loader + * hands the whole array to `loadLanguageSync`, which registers each entry + * (including embedded sub-grammars). The three boot grammars are absent — + * already loaded, so no alias value ever points at a missing entry here. + */ +const LAZY_GRAMMARS = new Map Promise>([ + ['python', () => import('@shikijs/langs/python')], + ['ruby', () => import('@shikijs/langs/ruby')], + ['go', () => import('@shikijs/langs/go')], + ['rust', () => import('@shikijs/langs/rust')], + ['java', () => import('@shikijs/langs/java')], + ['c', () => import('@shikijs/langs/c')], + ['cpp', () => import('@shikijs/langs/cpp')], + ['csharp', () => import('@shikijs/langs/csharp')], + ['kotlin', () => import('@shikijs/langs/kotlin')], + ['swift', () => import('@shikijs/langs/swift')], + ['php', () => import('@shikijs/langs/php')], + ['yaml', () => import('@shikijs/langs/yaml')], + ['toml', () => import('@shikijs/langs/toml')], + ['ini', () => import('@shikijs/langs/ini')], + ['markdown', () => import('@shikijs/langs/markdown')], + ['mdx', () => import('@shikijs/langs/mdx')], + ['html', () => import('@shikijs/langs/html')], + ['css', () => import('@shikijs/langs/css')], + ['scss', () => import('@shikijs/langs/scss')], + ['less', () => import('@shikijs/langs/less')], + ['sql', () => import('@shikijs/langs/sql')], + ['xml', () => import('@shikijs/langs/xml')], + ['lua', () => import('@shikijs/langs/lua')], +]) + +/** + * Language ids (and aliases) the highlighter accepts; everything else renders * plain. A Map, not an object: fence info strings are assistant-authored, so * a label like `constructor` or `__proto__` must miss instead of resolving an * inherited property and crashing the renderer inside shiki. Keys cover both * the markdown-fence aliases `CodeBlock` uses and the file-extension hint ids * the read tool's `langFromPath` emits, so both callers resolve the same * grammars. The JS family maps to the TypeScript grammar (which embeds it), - * unchanged from when this was the only non-shell/JSON grammar. + * unchanged from when this was the only non-shell/JSON grammar. A value not in + * {@link LANGS} names a {@link LAZY_GRAMMARS} entry loaded on first use. */ const LANG_ALIASES = new Map([ ['typescript', 'typescript'], @@ -132,6 +148,62 @@ function highlighter(): HighlighterCore { return singleton } +/** Grammar ids whose lazy import is in flight or done, so it is requested once. */ +const requested = new Set() +/** Subscribers re-rendered after a lazy grammar registers (React callers). */ +const listeners = new Set<() => void>() +/** Bumped on each lazy-grammar load; the `useSyncExternalStore` snapshot. */ +let loadCount = 0 + +/** + * Subscribe to lazy-grammar load completions; `listener` fires after a + * {@link LAZY_GRAMMARS} grammar finishes registering on the singleton, so a + * caller that rendered its plain fallback while the grammar loaded can + * re-highlight. Shaped as a `useSyncExternalStore` subscribe: pair it with + * {@link grammarLoadCount} as the snapshot. Returns an unsubscribe function. + * @param listener - invoked (no args) on each grammar-load completion. + * @returns a disposer that removes the listener. + */ +export function subscribeGrammarLoaded(listener: () => void): () => void { + listeners.add(listener) + return () => { listeners.delete(listener) } +} + +/** + * The lazy-grammar load counter — a value that changes on every load, so a + * `useSyncExternalStore` snapshot re-renders the subscriber when a grammar + * registers. Opaque: only its identity across renders matters. + * @returns the current load count. + */ +export function grammarLoadCount(): number { + return loadCount +} + +/** + * Ensure the grammar `resolved` names is registered. A boot grammar (not in + * {@link LAZY_GRAMMARS}) and an already-loaded lazy grammar report ready + * synchronously; a lazy grammar not yet loaded starts its import (once) and + * reports not-ready, so the caller renders plain until a + * {@link subscribeGrammarLoaded} listener fires. + * @param resolved - the grammar id an alias resolved to. + * @returns whether the grammar is registered and ready to tokenize now. + */ +function ensureGrammar(resolved: string): boolean { + const load = LAZY_GRAMMARS.get(resolved) + // A boot grammar (already registered) has no lazy loader; it is always ready. + if (load === undefined) return true + if (highlighter().getLoadedLanguages().includes(resolved)) return true + if (!requested.has(resolved)) { + requested.add(resolved) + void load().then((mod) => { + highlighter().loadLanguageSync(mod.default) + loadCount += 1 + for (const listener of listeners) listener() + }) + } + return false +} + // Engine + grammar construction costs a long task (~120-175ms); building it // during the first finalized fence's render would jank exactly when a stream // completes. Warm the singleton in a deferred task at module load (= plugin @@ -144,14 +216,17 @@ const warmupTimer = setTimeout(() => { highlighter() }, 0) /** * Highlight `code` into shiki's HTML (a single `
` tree)
  * when `lang` maps to a registered grammar; `undefined` means the caller
- * renders its plain fallback.
+ * renders its plain fallback. A lazy grammar not yet loaded returns `undefined`
+ * for this call and loads in the background; subscribe with
+ * {@link onGrammarLoaded} to re-highlight once it registers.
  * @param code - the source text.
  * @param lang - the language hint (a markdown fence info string or a fixed caller id).
- * @returns the highlighted HTML, or `undefined` for unknown languages.
+ * @returns the highlighted HTML, or `undefined` for unknown or not-yet-loaded languages.
  */
 export function highlightToHtml(code: string, lang: string | undefined): string | undefined {
   const resolved = lang === undefined ? undefined : LANG_ALIASES.get(lang.toLowerCase())
   if (resolved === undefined) return undefined
+  if (!ensureGrammar(resolved)) return undefined
   return highlighter().codeToHtml(code, { lang: resolved, theme: 'css-variables' })
 }
 
@@ -179,11 +254,12 @@ export interface HighlightSpan {
  * is dropped so the run count matches the caller's own line array.
  * @param code - the source text.
  * @param lang - the language hint (a file-extension-derived language id).
- * @returns one entry per source line (each an array of runs), or `undefined` for unknown languages.
+ * @returns one entry per source line (each an array of runs), or `undefined` for unknown or not-yet-loaded languages.
  */
 export function highlightLines(code: string, lang: string | undefined): HighlightSpan[][] | undefined {
   const resolved = lang === undefined ? undefined : LANG_ALIASES.get(lang.toLowerCase())
   if (resolved === undefined) return undefined
+  if (!ensureGrammar(resolved)) return undefined
   const { tokens } = highlighter().codeToTokens(code, { lang: resolved, theme: 'css-variables' })
   // shiki tokenizes `a\nb` into two lines; a trailing newline (`a\n`) adds a
   // third, empty line the caller's own line array does not carry. Drop that
diff --git a/packages/client/ui-primitives/tests/code-block.spec.tsx b/packages/client/ui-primitives/tests/code-block.spec.tsx
index 47b0ad24fb..2d56bc1a2d 100644
--- a/packages/client/ui-primitives/tests/code-block.spec.tsx
+++ b/packages/client/ui-primitives/tests/code-block.spec.tsx
@@ -31,6 +31,24 @@ describe('highlightToHtml', () => {
     expect(highlightToHtml('x', 'cobol')).toBeUndefined()
     expect(highlightToHtml('x', undefined)).toBeUndefined()
   })
+
+  // Every read-tool language hint whose grammar loads lazily (the boot set —
+  // ts/js/bash/sh/json — is covered above). Touching each one drives its own
+  // dynamic import thunk, so the whole LAZY_GRAMMARS table is exercised.
+  const LAZY_ALIASES = [
+    'py', 'rb', 'go', 'rs', 'java', 'c', 'cpp', 'cs', 'kotlin', 'swift', 'php',
+    'yaml', 'toml', 'ini', 'md', 'mdx', 'html', 'css', 'scss', 'less', 'sql',
+    'xml', 'lua',
+  ]
+
+  it('lazily loads every read-card grammar: plain first, highlighted after load', async () => {
+    // First touch returns the plain fallback (undefined) and starts the import.
+    for (const alias of LAZY_ALIASES) expect(highlightToHtml('x', alias)).toBeUndefined()
+    // Once every grammar has registered, the same call highlights.
+    await vi.waitFor(() => {
+      for (const alias of LAZY_ALIASES) expect(highlightToHtml('x', alias)).toContain('shiki')
+    })
+  })
 })
 
 describe('CodeBlock', () => {
diff --git a/packages/client/ui-primitives/tests/read-block.spec.tsx b/packages/client/ui-primitives/tests/read-block.spec.tsx
index 339fd2d71e..fab9450932 100644
--- a/packages/client/ui-primitives/tests/read-block.spec.tsx
+++ b/packages/client/ui-primitives/tests/read-block.spec.tsx
@@ -10,7 +10,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { DEFAULT_READ_MAX_LINES, ReadBlock, type ReadBlockLine } from '../src/index.ts'
-import { highlightLines } from '../src/markdown/highlight.ts'
+import { grammarLoadCount, highlightLines, subscribeGrammarLoaded } from '../src/markdown/highlight.ts'
 
 afterEach(cleanup)
 
@@ -71,6 +71,25 @@ describe('highlightLines', () => {
     expect(highlightLines('x', 'cobol')).toBeUndefined()
     expect(highlightLines('x', undefined)).toBeUndefined()
   })
+
+  it('loads a lazy grammar on first use: plain first, highlighted after it registers', async () => {
+    // A boot grammar (ts) is ready synchronously; a lazy grammar (python) is
+    // not, so the first call renders plain and imports the grammar, and a
+    // subscriber fires once it registers, after which the same call highlights.
+    let notified = 0
+    const stop = subscribeGrammarLoaded(() => { notified += 1 })
+    // First touch: grammar not loaded yet, so plain fallback while it imports.
+    expect(highlightLines('def f(): pass', 'py')).toBeUndefined()
+    // The import + loadLanguageSync resolve on a microtask; wait for the notify.
+    await vi.waitFor(() => { expect(notified).toBeGreaterThan(0) })
+    expect(grammarLoadCount()).toBeGreaterThan(0)
+    const result = highlightLines('def f(): pass', 'py')
+    expect(result).not.toBeUndefined()
+    // `def` is a python keyword and carries a --shiki-* color once highlighted.
+    const keyword = result!.flat().find(span => span.text === 'def')
+    expect(keyword?.style?.color).toContain('var(--shiki-')
+    stop()
+  })
 })
 
 describe('ReadBlock rows', () => {
@@ -212,4 +231,11 @@ describe('ReadBlock copy', () => {
     const view = render()
     expect(view.container.firstElementChild?.classList.contains('x')).toBe(true)
   })
+
+  it('hides the copy control for an empty window so it cannot wipe the clipboard', () => {
+    // A successful read of an empty file settles to lines: [] with card:'read',
+    // so this branch is reachable; copying then would clear the clipboard.
+    const view = render()
+    expect(view.queryByRole('button', { name: '复制' })).toBeNull()
+  })
 })

From c7d95f5b7f08222f728b4419f1b0a835cd4a75ae Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 21:46:05 +0800
Subject: [PATCH 08/43] fix(web-read-card): align read spec with real schema
 and correct grammar docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Top-level read samples in read-card.spec use the read tool's real file_path
schema key (web_fetch keeps its own path key); the Input-JSON assertion follows.
The LANGS/LANG_ALIASES JSDoc no longer claims the TypeScript grammar embeds
JSX/TSX — shiki's TS grammar tokenizes JSX approximately, an accepted trade to
keep one JS-family boot grammar.
---
 .../ui-conversation/tests/read-card.spec.tsx     | 10 +++++++---
 .../ui-primitives/src/markdown/highlight.ts      | 16 ++++++++++------
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/packages/client/ui-conversation/tests/read-card.spec.tsx b/packages/client/ui-conversation/tests/read-card.spec.tsx
index a4ead14748..d5804b505b 100644
--- a/packages/client/ui-conversation/tests/read-card.spec.tsx
+++ b/packages/client/ui-conversation/tests/read-card.spec.tsx
@@ -25,7 +25,11 @@ afterEach(cleanup)
 
 const SID = 's1' as SessionId
 
-const ARGS = '{"path":"src/a.ts","offset":41}'
+// The read tool's real schema key is `file_path`; the top-level read samples
+// use it so the row exercises a production-shaped call. `web_fetch` (below) has
+// its own schema whose key is not `file_path`, so it keeps a `url`-less `path`.
+const ARGS = '{"file_path":"src/a.ts","offset":41}'
+const WEB_FETCH_ARGS = '{"path":"src/a.ts","offset":41}'
 
 /** The read block's rendered content cells, one string per row (highlighting
  *  breaks a line across token spans, so match on the row's textContent). */
@@ -122,7 +126,7 @@ describe('GenericToolCard read body', () => {
     expect(CHAT_READ_MAX_LINES).toBeLessThan(16)
     // web_fetch lands on the read variant without its own keyed row, so the
     // fallback card owns the resident read block.
-    const view = render()
+    const view = render()
     expect(view.container.querySelector('[data-read]')).not.toBeNull()
     expect(contentTexts(view.container)).toContain('export const a = 1')
     // The gutter keeps the file's own line numbers.
@@ -256,7 +260,7 @@ describe('DetailsPanel Output section (read)', () => {
     const view = mount(snapshot({
       nodes: [settled({ resultView: resultRead({ lines: long, totalLines: 20 }) })],
     }), target)
-    expect(view.getByText(/"path"/)).toBeTruthy()
+    expect(view.getByText(/"file_path"/)).toBeTruthy()
     expect(view.container.querySelector('[data-read]')).not.toBeNull()
     // The panel takes the primitive's own default cap (16), not the row's.
     expect(view.getByText(`… 其余 ${20 - 16} 行`)).toBeTruthy()
diff --git a/packages/client/ui-primitives/src/markdown/highlight.ts b/packages/client/ui-primitives/src/markdown/highlight.ts
index 2116fa2b93..d0727c833a 100644
--- a/packages/client/ui-primitives/src/markdown/highlight.ts
+++ b/packages/client/ui-primitives/src/markdown/highlight.ts
@@ -32,9 +32,12 @@ type LangModule = { default: typeof langTs }
 
 /**
  * Grammars the singleton loads at boot; each entry's own `name` is the id
- * `codeToTokens`/`codeToHtml` resolve. The TypeScript grammar embeds JS/JSX/TSX,
- * so the JS-family fence aliases resolve to it rather than a separate grammar.
- * The read card's wider set loads lazily through {@link LAZY_GRAMMARS}.
+ * `codeToTokens`/`codeToHtml` resolve. The JS-family aliases (js/jsx/ts/tsx)
+ * resolve to the TypeScript grammar rather than a separate one: it tokenizes
+ * plain TS/JS exactly, and JSX/TSX approximately (shiki's TS grammar is not the
+ * dedicated TSX grammar, so JSX elements tokenize imperfectly) — an accepted
+ * trade to keep the boot set to one JS-family grammar. The read card's wider
+ * set loads lazily through {@link LAZY_GRAMMARS}.
  */
 const LANGS = [langTs, langBash, langJson]
 
@@ -80,9 +83,10 @@ const LAZY_GRAMMARS = new Map Promise>([
  * inherited property and crashing the renderer inside shiki. Keys cover both
  * the markdown-fence aliases `CodeBlock` uses and the file-extension hint ids
  * the read tool's `langFromPath` emits, so both callers resolve the same
- * grammars. The JS family maps to the TypeScript grammar (which embeds it),
- * unchanged from when this was the only non-shell/JSON grammar. A value not in
- * {@link LANGS} names a {@link LAZY_GRAMMARS} entry loaded on first use.
+ * grammars. The JS family maps to the TypeScript grammar (see {@link LANGS} for
+ * the JSX/TSX approximation), unchanged from when this was the only
+ * non-shell/JSON grammar. A value not in {@link LANGS} names a
+ * {@link LAZY_GRAMMARS} entry loaded on first use.
  */
 const LANG_ALIASES = new Map([
   ['typescript', 'typescript'],

From 7b6f33f87258c6d2d68a79df1302511519b2e49e Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 21:57:49 +0800
Subject: [PATCH 09/43] refactor(fs): minimize and cap search card meta; keep
 TUI byte-identical

Address the review of the search render card:

- The search result view carries no `content`: it was a no-op for every
  consumer and serialized the whole search text twice. A UI without a search
  card falls back to the raw tool/result content; the TUI stays byte-identical
  to the pre-search-card generic fallback.
- Bound the serialized presentationMeta with a configurable searchMetaMaxBytes
  (default 64 KiB): the inline item cap does not bound bytes, and spill-policy
  only shrinks content, never meta. capMetaBytes drops trailing groups/paths.
- Share one retention pass (retainGrepMatches/retainGlobPaths in search-core)
  between the model-facing render and the meta projection; remove the second
  cap/preview implementation and the presentation<->grep module cycle by
  moving GrepMatch/previewLine to search-core.
- Rename the result-view discriminant kind -> shape so it no longer collides
  with GenericCallView.kind (ToolCallKind, whose values include 'search').
- Narrow the entry export surface to consumed symbols.
- Sync the three bilingual ToolResultView doc pairs and the Agent Note pair;
  document the deliberate empty-card acceptance vs diffsFromMeta.
- Regenerate config/tool/cordis catalogs for the new config field.
---
 .../2026-07-30-search-render-card.i18n.yaml   |   4 +-
 .../feature/2026-07-30-search-render-card.md  |  36 +++--
 .../2026-07-30-search-render-card.zh.md       |  60 ++++----
 docs/config-catalog.md                        |   4 +-
 docs/cookbook/adding-a-tool.i18n.yaml         |   6 +-
 docs/cookbook/adding-a-tool.md                |   1 +
 docs/cookbook/adding-a-tool.zh.md             |   1 +
 docs/core-data-structures/tools.i18n.yaml     |   4 +-
 docs/core-data-structures/tools.md            |   2 +-
 docs/core-data-structures/tools.zh.md         |   2 +-
 .../cordis/tool-cordis/src/api-catalog.ts     |   4 +-
 packages/core/tools/README.i18n.yaml          |   4 +-
 packages/core/tools/README.md                 |   2 +-
 packages/core/tools/README.zh.md              |   2 +-
 packages/core/tools/src/presentation.ts       |  38 ++---
 packages/fs/tool-fs-search/src/glob.ts        |  33 +++--
 packages/fs/tool-fs-search/src/grep.ts        |  69 +++------
 packages/fs/tool-fs-search/src/index.ts       |  26 +++-
 .../fs/tool-fs-search/src/presentation.ts     | 133 ++++++++++++------
 packages/fs/tool-fs-search/src/search-core.ts |  71 ++++++++++
 .../tool-fs-search/tests/presentation.spec.ts |  97 +++++++++----
 .../fs/tool-fs-search/tests/tools.spec.ts     |  17 ++-
 packages/ui/tui/src/components/transcript.ts  |  15 +-
 23 files changed, 403 insertions(+), 228 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
index 4a00c287a2..ec0e020502 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.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-30-search-render-card.md
-2026-07-30-search-render-card.md: de59992cebcdf056e3446e4f546f8bff4b10e421
-2026-07-30-search-render-card.zh.md: 8b91255094c24972c05add92ee65f8c76c60a882
+2026-07-30-search-render-card.md: 36f772d7198ef30d6c243549cbaa9f16c780268b
+2026-07-30-search-render-card.zh.md: 7d7ba352f19f3fb83cb6b7d049980776dc2c277e
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.md
index de59992ceb..36f772d719 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.md
@@ -6,43 +6,53 @@ English | [中文](2026-07-30-search-render-card.zh.md)
 
 ## Problem
 
-`grep` and `glob` return structured canonical values — `grep` a flat `{ matches: [{ path, lineNumber, line }] }`, `glob` a `{ paths: string[] }` — but every UI only ever saw their model-facing render text: `grep` groups its matches under file headers with `Line N:` rows, `glob` prints a newline-joined path list, and both append a spill footer when the inline cap ({@link module:@deepseek-ai/dsh-tool-fs-search/grep} `grepMaxMatches`, default 250; {@link module:@deepseek-ai/dsh-tool-fs-search/glob} `globMaxResults`, default 100) drops later results to a spill file. A web frontend that wants to render a search result as an expandable per-file group of matches, or as a selectable path list, had to re-parse that text. Both tools already declared a call-time [render intent](../architecture/2026-07-02-tool-render-intent-union.md) (`GenericCallView`, `kind: 'search'`) but no result-time view, so the completed call fell back to the generic card that renders the raw text.
+`grep` and `glob` return structured canonical values — `grep` a flat `{ matches: [{ path, lineNumber, line }] }`, `glob` a `{ paths: string[] }` — but every UI only ever saw their model-facing render text: `grep` groups its matches under file headers with `Line N:` rows, `glob` prints a newline-joined path list, and both append a spill footer when the inline cap (`grepMaxMatches`, default 250; `globMaxResults`, default 100) drops later results to a spill file. A web frontend that wants to render a search result as an expandable per-file group of matches, or as a selectable path list, had to re-parse that text. Both tools already declared a call-time [render intent](../architecture/2026-07-02-tool-render-intent-union.md) (`GenericCallView`, `kind: 'search'`) but no result-time view, so the completed call fell back to the generic card that renders the raw text.
 
 The structured canonical value does not cross the wire: only the model-facing render text and, when a tool declares `output.presentationMeta`, a JSON metadata payload reach the client, threaded through the `tool/result` event ([canonical-output contract](../architecture/2026-07-20-canonical-tool-output-contract.md)). A result-time view carrying structured data therefore has to project that data into `presentationMeta` and read it back in `presentResult` — the same path `write`/`edit` use for their diff cards.
 
 ## Decision
 
-`packages/core/tools/src/presentation.ts` adds `card: 'search'` to the `ToolResultView` union as `SearchResultView`, a `kind`-discriminated view that expresses both tools' shapes: `SearchMatchesResultView` (`kind: 'matches'`) carries `grep`'s matches grouped by file as `files: { path, matches: { lineNumber, line }[] }[]`, and `SearchPathsResultView` (`kind: 'paths'`) carries `glob`'s flat `paths: string[]`. Both carry `truncated: boolean` and `total: number`, and an optional `content?: ContentBlock[]`.
+`packages/core/tools/src/presentation.ts` adds `card: 'search'` to the `ToolResultView` union as `SearchResultView`, a `shape`-discriminated view that expresses both tools' shapes: `SearchMatchesResultView` (`shape: 'matches'`) carries `grep`'s matches grouped by file as `files: { path, matches: { lineNumber, line }[] }[]`, and `SearchPathsResultView` (`shape: 'paths'`) carries `glob`'s flat `paths: string[]`. Both carry `truncated: boolean` and `total: number`.
 
-One view with two shapes rather than two cards, because both tools are the same visual object — a search result — and a web consumer switches on one `card` value, then on `kind` for the row shape. The discriminated `kind` keeps each shape's fields non-optional (a matches view always has `files`, a paths view always has `paths`) instead of a single interface where every shape-specific field is optional.
+The discriminant is `shape`, not `kind`, deliberately: the same presentation module already gives `GenericCallView` a `kind: ToolCallKind` field whose values include `'search'` (the icon category). A bridge holding a `ToolCallView | ToolResultView` would see two `kind` fields with two meanings; `shape` for the result variant keeps the two apart.
+
+One view with two shapes rather than two cards, because both tools are the same visual object — a search result — and a web consumer switches on one `card` value, then on `shape` for the row layout. The discriminated `shape` keeps each variant's fields non-optional (a matches view always has `files`, a paths view always has `paths`) instead of a single interface where every shape-specific field is optional.
+
+The view carries **no** result text. An earlier revision attached the model-facing `result.content` to the view; that was a no-op for every consumer (the TUI already falls back to `result.content`, and web fallbacks read the raw `tool/result` content), and it serialized the whole search text a second time into the persisted view. The view is the structured shape only; a UI without a search card falls back to the raw `tool/result` content.
 
 The card tag is result-time only. A search call stays a `GenericCallView` (`kind: 'search'`): the pending state has no matches or paths to show, so there is nothing a `SearchCallView` would carry that the generic title does not. This is the asymmetry with the terminal card, whose call view carries the command, cwd, and description that exist before execution; a search's structured content exists only after `execute`.
 
-`packages/fs/tool-fs-search/src/presentation.ts` owns the projection and the narrowing. `grepSearchMeta`/`globSearchMeta` project the canonical value into a `SearchMeta` payload each tool declares as `output.presentationMeta`; `presentGrepResult`/`presentGlobResult` read `result.meta` back through `searchViewFromMeta` and attach the model-facing `result.content` as the view's `content`. The projections apply the SAME inline cap and per-line preview budget the model-facing render applies, and report `total` as every result the search found (before capping) with `truncated` set when the cap dropped results. This is the truncation-honesty point: the model saw a capped inline result plus a spill footer, so the card must not present the retained page as the complete result — a UI reads `truncated`/`total` to show a capped indicator rather than claiming completeness the model never had.
+`packages/fs/tool-fs-search/src/presentation.ts` owns the projection and the narrowing. `grepSearchMeta`/`globSearchMeta` project the canonical value into a `SearchMeta` payload each tool declares as `output.presentationMeta`; `presentGrepResult`/`presentGlobResult` read `result.meta` back through `searchViewFromMeta`. They consume the SAME retained result the model-facing render consumes — `retainGrepMatches`/`retainGlobPaths` in `search-core.ts` run the inline cap and per-line preview budget ONCE, and both the render and the projection take that outcome — so text and card never disagree about which results survived, and there is no second retention pass. `total` is every result the search found (before capping); `truncated` is set when the cap dropped results. This is the truncation-honesty point: the model saw a capped inline result plus a spill footer, so the card must not present the retained page as the complete result — a UI reads `truncated`/`total` to show a capped indicator rather than claiming completeness the model never had.
 
-`searchViewFromMeta` narrows the opaque `meta` defensively and returns `undefined` on any malformed or absent payload, exactly as `diffsFromMeta` does, so a presenter run on an older or hand-edited replayed log falls back to the generic card instead of throwing. `presentResult` returns `undefined` for a failed result, for absent meta (a nested `run_code` dispatch computes no `presentationMeta`), and for the other tool's meta shape (each presenter narrows to its own `kind`).
+**The meta has its own byte budget.** The inline cap bounds the item COUNT, but the retained matches of a broad search (hundreds of long lines) can still serialize to hundreds of kilobytes, and `meta` is persisted with the session log and re-sent on every request. A deployment's final output budget (`dsh-spill-policy`, `maxInlineBytes`) only shrinks a result's `content` — `PostToolDecision` has no `meta` channel — so the projection owns keeping `meta` bounded. `capMetaBytes` drops trailing file groups / paths until the serialized meta fits `searchMetaMaxBytes` (config, default 64 KiB) and marks the result `truncated`. A single item too large to fit on its own is kept: the invariant is a bounded payload wherever droppable, never an empty card that hides a real result.
 
-The `SearchMeta` member shapes are object-literal `type` aliases, not the `SearchFileMatches`/`SearchLineMatch` interfaces the view exposes. Only a type alias is assignable to the `JsonValue` index signature `presentationMeta` returns; the two are structurally identical, so the projected value still reads back as a `SearchResultView`.
+`searchViewFromMeta` narrows the opaque `meta` defensively and returns `undefined` on any malformed or absent payload, so a presenter run on an older or hand-edited replayed log falls back to the generic card instead of throwing. It DOES accept a zero-result payload (`files: []` / `paths: []`) as a valid empty card — this is a deliberate departure from the mirrored `diffsFromMeta`, which rejects empty `diffs`, because a zero-match grep is a legitimate result a UI shows as "no matches", not an absent projection. `presentResult` returns `undefined` for a failed result, for absent meta (a nested `run_code` dispatch computes no `presentationMeta`), and for the other tool's meta shape (each presenter narrows to its own `shape`).
 
-The TUI (`packages/ui/tui/src/components/transcript.ts`) needs no dedicated arm: its result-view switch handles `terminal` and `diff` explicitly and falls through to a generic arm that renders `view.content ?? this.result?.content`. Because `SearchResultView` carries the model-facing text as `content`, the TUI renders it as the same text it already showed. The web frontend that renders the structured `files`/`paths` shape is a separate later PR; this PR is the backend contract and its two producers.
+The `SearchMeta` member shapes are object-literal `type` aliases, not the `SearchFileMatches`/`SearchLineMatch` interfaces the view exposes, because only a type alias is assignable to the `JsonValue` index signature `presentationMeta` returns; the two are structurally identical, so the projected value still reads back as a `SearchResultView`.
+
+The TUI (`packages/ui/tui/src/components/transcript.ts`) needs no dedicated arm: its result-view switch handles `terminal` and `diff` explicitly, and a `search` view falls through to the same dim generic body, reading the model-facing text from `this.result?.content`. Because the search view carries no `content` of its own and grep/glob returned a generic card before this PR, the TUI output stays byte-identical to the pre-search-card fallback. The web frontend that renders the structured `files`/`paths` shape is a separate later PR; this PR is the backend contract and its two producers.
 
 ## Alternatives considered
 
-**A single flat `SearchResultView` interface with optional `files?` and `paths?`.** Rejected: it makes both shape-specific fields optional on every value and lets a malformed view carry both or neither. The `kind` discriminant keeps each shape's fields required and lets a consumer switch exhaustively.
+**A single flat `SearchResultView` interface with optional `files?` and `paths?`.** Rejected: it makes both shape-specific fields optional on every value and lets a malformed view carry both or neither. The `shape` discriminant keeps each variant's fields required and lets a consumer switch exhaustively.
 
-**A call-time `SearchCallView` mirroring the terminal card's both-sides symmetry.** Rejected: a search call has no matches or paths before `execute`, so the view would carry only the title the `GenericCallView` already carries. The terminal card's call view earns its tag because a command, cwd, and description exist at call time; a search's structured content does not.
+**Reuse `kind` as the shape discriminant.** Rejected: `kind` already means `ToolCallKind` (the icon category, whose values include `'search'`) on the call view in the same module. A second `kind` with a different meaning on the result view collides for any bridge holding both.
 
-**Carry the structured result in a bespoke channel instead of `presentationMeta`.** Rejected: the canonical value is execution-local and never reaches the client, and `presentationMeta` is the established seam that persists a tool's JSON presentation payload with `tool/result` and threads it back to `presentResult`. Adding a second channel would duplicate that path.
+**Attach the model-facing text as the view's `content`.** Rejected: a no-op for every current consumer and a second serialization of the whole search text into the persisted view. The view is the structured shape; text fallback reads the raw result content.
+
+**A meta channel on `PostToolDecision` so `dsh-spill-policy` bounds `meta` like it bounds `content`.** Rejected for this PR: it changes the core tool decision contract and the spill-policy plugin for one tool's payload. The projection bounding its own `meta` at a config byte cap is self-contained and keeps the seam unchanged.
+
+**A call-time `SearchCallView` mirroring the terminal card's both-sides symmetry.** Rejected: a search call has no matches or paths before `execute`, so the view would carry only the title the `GenericCallView` already carries.
 
 ## Consequences
 
-`grep` and `glob` now compute `presentationMeta` on every non-nested successful call, a bounded projection over the already-parsed matches or paths. The projection re-applies the retention cap the render already applied, so the retained set is computed twice per call; the input is bounded by the raw-output cap, so this is not a new scaling concern.
+`grep` and `glob` now compute `presentationMeta` on every non-nested successful call, a bounded projection over the already-retained matches or paths — the same retention outcome the render consumes, so there is no second retention pass and no doubled search text on the wire. The serialized meta is bounded by `searchMetaMaxBytes`, so a broad search no longer persists an unbounded structured copy into the session log.
 
-A UI without a search card renders the attached `content` text, so no consumer regresses. The web consumer that renders the structured shape reads `truncated`/`total` and the per-file groups; because the view carries only the retained page, a UI wanting the complete result follows the spill locator in the model-facing text, exactly as the model does.
+A UI without a search card renders the raw `tool/result` content, so no consumer regresses, and the TUI stays byte-identical. The web consumer that renders the structured shape reads `truncated`/`total` and the per-file groups; because the view carries only the retained, byte-bounded page, a UI wanting the complete result follows the spill locator in the model-facing text, exactly as the model does.
 
 ## Testing
 
-`packages/fs/tool-fs-search/tests/presentation.spec.ts` pins the pure layer: `groupMatchesByFile`'s first-seen file order, `grepSearchMeta`/`globSearchMeta` projection with the cap applied and `total` reporting the pre-cap count, the per-line preview budget on a projected match line, and `searchViewFromMeta`'s narrowing of both good shapes plus every malformed case (non-object/array meta, missing or mistyped `truncated`/`total`, unknown `kind`, malformed `files` entries, non-string `paths`). `packages/fs/tool-fs-search/tests/tools.spec.ts` pins the wiring through the real tool registry: a capped `grep`/`glob` execute produces the `SearchMeta` on `result.meta` and `presentResult` builds the search view with `content` attached, a nested `run_code` dispatch computes no meta so `presentResult` falls back, and a failed or cross-shape or malformed result falls back to the generic card. Per-file 100% coverage holds over the search package `src`.
+`packages/fs/tool-fs-search/tests/presentation.spec.ts` pins the pure layer: `groupMatchesByFile`'s first-seen file order; `grepSearchMeta`/`globSearchMeta` projection over a shared retention outcome with `total` reporting the pre-cap count and `truncated` carried through; the per-line preview budget the retention pass applied; the serialized-meta byte cap dropping trailing groups/paths while keeping a single oversized item; and `searchViewFromMeta`'s narrowing of both good shapes, the zero-result empty card, and every malformed case (non-object/array meta, missing or mistyped `truncated`/`total`, unknown `shape`, malformed `files` entries, non-string `paths`). `packages/fs/tool-fs-search/tests/tools.spec.ts` pins the wiring through the real tool registry: a capped `grep`/`glob` execute produces the `SearchMeta` on `result.meta` and `presentResult` builds the search view (no `content`), a nested `run_code` dispatch computes no meta so `presentResult` falls back, and a failed or cross-shape or malformed result falls back to the generic card. Per-file 100% coverage holds over the search package `src`.
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
index 8b91255094..7d7ba352f1 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
@@ -1,51 +1,61 @@
-# Agent Note: Search render intent — grep and glob emit a structured search card
+# Agent Note:搜索渲染意图 —— grep 与 glob 产出结构化搜索卡片
 
 Status: implemented
 
 [English](2026-07-30-search-render-card.md) | 中文
 
-## Problem
+## 问题
 
-`grep` 与 `glob` 返回结构化的规范值——`grep` 是扁平的 `{ matches: [{ path, lineNumber, line }] }`,`glob` 是 `{ paths: string[] }`——但每一个 UI 见到的只有它们面向模型的渲染文本:`grep` 把匹配按文件分组,文件头下是 `Line N:` 行;`glob` 打印换行连接的路径列表;当内联上限({@link module:@deepseek-ai/dsh-tool-fs-search/grep} `grepMaxMatches`,默认 250;{@link module:@deepseek-ai/dsh-tool-fs-search/glob} `globMaxResults`,默认 100)把后续结果溢出到 spill 文件时,两者都追加一段溢出脚注。想把搜索结果渲染成可展开的按文件分组匹配、或渲染成可选择的路径列表的 web 前端,只能去重新解析这段文本。两个工具都已声明了调用期的[渲染意图](../architecture/2026-07-02-tool-render-intent-union.md)(`GenericCallView`,`kind: 'search'`),但没有结果期视图,于是已完成的调用回退到渲染原始文本的通用卡片。
+`grep` 与 `glob` 返回结构化的 canonical 值 —— `grep` 是扁平的 `{ matches: [{ path, lineNumber, line }] }`,`glob` 是 `{ paths: string[] }` —— 但每个 UI 只见过它们面向模型的渲染文本:`grep` 把匹配按文件头分组、每行 `Line N:`,`glob` 打印换行连接的路径列表,两者在内联上限(`grepMaxMatches`,默认 250;`globMaxResults`,默认 100)把后续结果落到 spill 文件时都追加一个 spill 脚注。想把搜索结果渲染成可展开的按文件匹配组、或可选择的路径列表的 web 前端,只能去重新解析那段文本。两个工具都已声明调用时的[渲染意图](../architecture/2026-07-02-tool-render-intent-union.md)(`GenericCallView`,`kind: 'search'`),但没有结果时视图,所以已完成的调用回退到渲染原始文本的 generic 卡片。
 
-结构化的规范值不过线:只有面向模型的渲染文本、以及当工具声明 `output.presentationMeta` 时的一段 JSON 元数据抵达客户端,二者通过 `tool/result` 事件穿线([规范输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md))。因此携带结构化数据的结果期视图必须把该数据投射进 `presentationMeta`,再在 `presentResult` 里读回——正是 `write`/`edit` 的 diff 卡片所走的路径。
+结构化 canonical 值不跨线传输:只有面向模型的渲染文本、以及当工具声明了 `output.presentationMeta` 时的一份 JSON 元数据,会经 `tool/result` 事件到达客户端([canonical-output 契约](../architecture/2026-07-20-canonical-tool-output-contract.md))。因此携带结构化数据的结果时视图必须把数据投影进 `presentationMeta`,再在 `presentResult` 里读回 —— 与 `write`/`edit` 的 diff 卡片走同一条路。
 
-## Decision
+## 决定
 
-`packages/core/tools/src/presentation.ts` 向 `ToolResultView` 联合类型加入 `card: 'search'`,即 `SearchResultView`:一个以 `kind` 区分的视图,表达两个工具的形状。`SearchMatchesResultView`(`kind: 'matches'`)以 `files: { path, matches: { lineNumber, line }[] }[]` 携带 `grep` 按文件分组的匹配;`SearchPathsResultView`(`kind: 'paths'`)携带 `glob` 的扁平 `paths: string[]`。两者都携带 `truncated: boolean` 与 `total: number`,以及可选的 `content?: ContentBlock[]`。
+`packages/core/tools/src/presentation.ts` 把 `card: 'search'` 作为 `SearchResultView` 加入 `ToolResultView` 联合,这是一个以 `shape` 判别的视图,表达两个工具的形状:`SearchMatchesResultView`(`shape: 'matches'`)以 `files: { path, matches: { lineNumber, line }[] }[]` 承载 `grep` 按文件分组的匹配,`SearchPathsResultView`(`shape: 'paths'`)承载 `glob` 的扁平 `paths: string[]`。两者都带 `truncated: boolean` 与 `total: number`。
 
-一个视图两种形状,而非两张卡片,因为两个工具是同一个视觉对象——一个搜索结果——web 消费方先在一个 `card` 值上分派,再在 `kind` 上分派行的形状。区分性的 `kind` 让每种形状各自的字段保持非可选(matches 视图恒有 `files`,paths 视图恒有 `paths`),而不是让所有形状相关字段都变成可选的单一接口。
+判别子是 `shape` 而非 `kind`,是刻意为之:同一个 presentation 模块已经给 `GenericCallView` 一个 `kind: ToolCallKind` 字段,其取值恰好包含 `'search'`(图标类别)。持有 `ToolCallView | ToolResultView` 的桥接层会看到两个含义不同的 `kind` 字段;结果变体用 `shape` 把两者分开。
 
-卡片标签只在结果期。搜索调用仍是 `GenericCallView`(`kind: 'search'`):pending 状态没有匹配或路径可展示,因此 `SearchCallView` 能携带的东西不会超出通用标题。这是与 terminal 卡片的不对称之处——terminal 的调用视图携带执行前就存在的命令、cwd 与描述;而搜索的结构化内容只在 `execute` 之后才存在。
+用一个带两种形状的视图而非两张卡片,因为两个工具是同一个视觉对象 —— 一个搜索结果 —— web 消费方先在一个 `card` 值上分支,再在 `shape` 上分支决定行布局。判别式 `shape` 让每个变体的字段保持非可选(matches 视图总有 `files`,paths 视图总有 `paths`),而不是一个所有形状相关字段都可选的单一接口。
 
-`packages/fs/tool-fs-search/src/presentation.ts` 拥有投射与收窄。`grepSearchMeta`/`globSearchMeta` 把规范值投射为一段 `SearchMeta`,各工具将其声明为 `output.presentationMeta`;`presentGrepResult`/`presentGlobResult` 通过 `searchViewFromMeta` 把 `result.meta` 读回,并把面向模型的 `result.content` 作为视图的 `content` 附上。投射施加与面向模型渲染相同的内联上限与每行预览预算,并把 `total` 报告为搜索找到的全部结果(截断之前),当上限丢弃了结果时把 `truncated` 置为真。这就是截断诚实性的要点:模型看到的是被截断的内联结果加一段溢出脚注,因此卡片不得把保留的那一页当作完整结果呈现——UI 读取 `truncated`/`total` 去展示截断指示,而非宣称模型从未拥有的完整性。
+该视图**不**携带结果文本。早期版本曾把面向模型的 `result.content` 附到视图上;那对每个消费方都是 no-op(TUI 本就回退到 `result.content`,web 回退读原始 `tool/result` 内容),却把整段搜索文本又序列化进持久化视图一遍。视图只承载结构化形状;无 search 卡片的 UI 回退到原始 `tool/result` 内容。
 
-`searchViewFromMeta` 防御性地收窄不透明的 `meta`,对任何畸形或缺失的 payload 返回 `undefined`,与 `diffsFromMeta` 完全一致,因此在较旧或手工编辑过的回放日志上运行的呈现器会回退到通用卡片而非抛错。`presentResult` 对失败结果、对缺失的 meta(嵌套 `run_code` 分发不计算 `presentationMeta`)、对另一个工具的 meta 形状(每个呈现器只收窄到自己的 `kind`)都返回 `undefined`。
+卡片标签只在结果时存在。搜索调用保持为 `GenericCallView`(`kind: 'search'`):pending 状态没有匹配或路径可展示,所以 `SearchCallView` 能携带的东西不会比 generic 标题更多。这是与 terminal 卡片的不对称之处 —— terminal 的调用视图携带执行前就存在的命令、cwd、description;搜索的结构化内容只在 `execute` 之后才存在。
 
-`SearchMeta` 的成员形状是对象字面量 `type` 别名,而不是视图对外暴露的 `SearchFileMatches`/`SearchLineMatch` 接口。只有 type 别名可以赋值给 `presentationMeta` 返回的 `JsonValue` 索引签名;二者结构完全相同,因此投射出的值仍能读回为 `SearchResultView`。
+`packages/fs/tool-fs-search/src/presentation.ts` 拥有投影与收窄。`grepSearchMeta`/`globSearchMeta` 把 canonical 值投影为每个工具声明为 `output.presentationMeta` 的 `SearchMeta` 载荷;`presentGrepResult`/`presentGlobResult` 经 `searchViewFromMeta` 把 `result.meta` 读回。它们消费与面向模型渲染相同的已保留结果 —— `search-core.ts` 里的 `retainGrepMatches`/`retainGlobPaths` 只跑一次内联上限与每行预览预算,render 与投影都取这份产出 —— 所以文本与卡片对哪些结果幸存永不分歧,也没有第二次保留计算。`total` 是搜索找到的全部结果(截断前);`truncated` 在上限丢弃了结果时置位。这是截断诚实点:模型看到的是被截断的内联结果加一个 spill 脚注,所以卡片不能把保留页当作完整结果 —— UI 读 `truncated`/`total` 显示截断指示,而非宣称模型从未有过的完整性。
 
-TUI(`packages/ui/tui/src/components/transcript.ts`)无需专用分支:它的结果视图 switch 显式处理 `terminal` 与 `diff`,并落到一个渲染 `view.content ?? this.result?.content` 的通用分支。因为 `SearchResultView` 以 `content` 携带了面向模型的文本,TUI 渲染出的仍是它此前已展示的同一段文本。渲染结构化 `files`/`paths` 形状的 web 前端是后续独立的 PR;本 PR 是后端契约及其两个生产者。
+**meta 有自己的字节预算。** 内联上限约束的是条目数,但一次宽泛搜索保留下来的匹配(数百条长行)仍可序列化到数百 KB,而 `meta` 会随会话日志持久化并在每次请求时重发。部署的最终输出预算(`dsh-spill-policy` 的 `maxInlineBytes`)只缩减结果的 `content` —— `PostToolDecision` 没有 `meta` 通道 —— 所以投影自己负责把 `meta` 约束住。`capMetaBytes` 丢弃末尾的文件组/路径,直到序列化 meta 装进 `searchMetaMaxBytes`(配置,默认 64 KiB),并把结果标记 `truncated`。单个大到自身都装不下的条目会被保留:不变量是可丢弃处一律有界,绝不产出隐藏了真实结果的空卡片。
 
-## Alternatives considered
+`searchViewFromMeta` 防御性地收窄不透明的 `meta`,对任何畸形或缺失载荷返回 `undefined`,使在较旧或手工编辑的回放日志上运行的 presenter 回退到 generic 卡片而非抛错。它确实接受零结果载荷(`files: []` / `paths: []`)为合法的空卡片 —— 这是与被镜像的 `diffsFromMeta` 的刻意偏离(后者拒绝空 `diffs`),因为零匹配的 grep 是 UI 展示为「no matches」的合法结果,而非缺失的投影。`presentResult` 对失败结果、对缺失 meta(嵌套 `run_code` 分发不计算 `presentationMeta`)、以及对另一工具的 meta 形状(每个 presenter 收窄到自己的 `shape`)返回 `undefined`。
 
-**单一扁平的 `SearchResultView` 接口,带可选的 `files?` 与 `paths?`。** 否决:它让两种形状相关字段在每个值上都成为可选,并允许一个畸形视图同时携带二者或都不携带。`kind` 区分符让每种形状的字段保持必填,并让消费方能穷尽分派。
+`SearchMeta` 的成员形状是对象字面量 `type` 别名,而非视图暴露的 `SearchFileMatches`/`SearchLineMatch` 接口,因为只有 type 别名可赋给 `presentationMeta` 返回的 `JsonValue` 索引签名;两者结构等价,所以投影值仍读回为 `SearchResultView`。
 
-**一个调用期的 `SearchCallView`,镜像 terminal 卡片两侧对称。** 否决:搜索调用在 `execute` 之前没有匹配或路径,视图只会携带 `GenericCallView` 已携带的标题。terminal 卡片的调用视图之所以配得上其标签,是因为命令、cwd 与描述在调用期就存在;而搜索的结构化内容不存在。
+TUI(`packages/ui/tui/src/components/transcript.ts`)不需要专门分支:它的结果视图 switch 显式处理 `terminal` 与 `diff`,`search` 视图落入同一个变暗的 generic body,从 `this.result?.content` 读取面向模型的文本。因为搜索视图不带自己的 `content`,而本 PR 之前 grep/glob 返回的是 generic 卡片,所以 TUI 输出与无 search 卡片的回退逐字节一致。渲染结构化 `files`/`paths` 形状的 web 前端是另一个后续 PR;本 PR 是后端契约及其两个生产者。
 
-**用一个专门的通道而非 `presentationMeta` 携带结构化结果。** 否决:规范值是执行局部的、绝不抵达客户端,而 `presentationMeta` 是既有的接缝,它把工具的 JSON 呈现 payload 随 `tool/result` 持久化并穿线回 `presentResult`。再加一条通道只会重复这条路径。
+## 考虑过的备选
 
-## Consequences
+**一个扁平的 `SearchResultView` 接口,带可选 `files?` 与 `paths?`。** 否决:它让两个形状相关字段在每个值上都可选,并允许畸形视图同时带两者或都不带。`shape` 判别式让每个变体的字段保持必需,并让消费方穷尽分支。
 
-`grep` 与 `glob` 现在在每次非嵌套的成功调用上计算 `presentationMeta`,这是对已解析的匹配或路径做的一次有界投射。投射重新施加渲染已施加过的保留上限,因此每次调用会计算两遍保留集;输入受原始输出上限约束,故这不是新的伸缩性问题。
+**复用 `kind` 作形状判别子。** 否决:同一模块里调用视图上的 `kind` 已经表示 `ToolCallKind`(图标类别,取值含 `'search'`)。结果视图上再有一个含义不同的 `kind`,对任何同时持有两者的桥接层都会冲突。
 
-没有搜索卡片的 UI 渲染附上的 `content` 文本,因此没有消费方回退。渲染结构化形状的 web 消费方读取 `truncated`/`total` 与按文件分组;因为视图只携带保留的那一页,想要完整结果的 UI 沿面向模型文本里的 spill 定位符去取,与模型的做法完全一致。
+**把面向模型的文本作为视图的 `content` 附上。** 否决:对每个当前消费方是 no-op,且把整段搜索文本第二次序列化进持久化视图。视图是结构化形状;文本回退读原始结果内容。
 
-## Testing
+**在 `PostToolDecision` 上加 meta 通道,让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决:它为一个工具的载荷改动核心工具决策契约与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的,且保持 seam 不变。
 
-`packages/fs/tool-fs-search/tests/presentation.spec.ts` 钉住纯函数层:`groupMatchesByFile` 的首见文件顺序,`grepSearchMeta`/`globSearchMeta` 施加上限后的投射与把 `total` 报告为截断前计数,投射出的匹配行上的每行预览预算,以及 `searchViewFromMeta` 对两种良态形状的收窄外加所有畸形情形(非对象/数组 meta、缺失或类型错误的 `truncated`/`total`、未知 `kind`、畸形 `files` 条目、非字符串 `paths`)。`packages/fs/tool-fs-search/tests/tools.spec.ts` 通过真实工具注册表钉住穿线:一次被截断的 `grep`/`glob` execute 在 `result.meta` 上产出 `SearchMeta`,且 `presentResult` 构建出附带 `content` 的搜索视图;嵌套 `run_code` 分发不计算 meta 于是 `presentResult` 回退;失败、跨形状或畸形结果回退到通用卡片。搜索包 `src` 上维持逐文件 100% 覆盖。
+**镜像 terminal 卡片双侧对称的调用时 `SearchCallView`。** 否决:搜索调用在 `execute` 前没有匹配或路径,视图只会携带 `GenericCallView` 已有的标题。
 
-## Related
+## 后果
 
-- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 PR 以 `search` 结果标签扩展的 `card` 标签词汇。
-- [Canonical tool output contract](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投射所乘的 value/render/`presentationMeta` 拆分;结构化值留在执行局部,卡片乘 `meta`。
-- [Web terminal card](2026-07-28-web-terminal-card.md) —— 本 PR 在后端所镜像的先例:工具把结果投射进 `presentationMeta` 与一个 `presentResult` 视图;搜索卡片的 web 消费方是类似的后续工作。
+`grep` 与 `glob` 现在在每次非嵌套的成功调用上计算 `presentationMeta`,这是对已保留匹配或路径的一次有界投影 —— 与 render 消费的是同一份保留产出,所以没有第二次保留计算,线上也没有翻倍的搜索文本。序列化 meta 受 `searchMetaMaxBytes` 约束,所以宽泛搜索不再把无界的结构化副本持久化进会话日志。
+
+无 search 卡片的 UI 渲染原始 `tool/result` 内容,所以没有消费方退化,TUI 也逐字节一致。渲染结构化形状的 web 消费方读 `truncated`/`total` 与按文件分组;因为视图只携带保留的、字节有界的页,想要完整结果的 UI 跟随面向模型文本里的 spill 定位符,与模型的做法完全一致。
+
+## 测试
+
+`packages/fs/tool-fs-search/tests/presentation.spec.ts` 钉住纯层:`groupMatchesByFile` 的首见文件顺序;`grepSearchMeta`/`globSearchMeta` 在共享保留产出上的投影,`total` 报告截断前计数、`truncated` 被带过;保留过程施加的每行预览预算;序列化 meta 字节上限丢弃末尾组/路径同时保留单个超大条目;以及 `searchViewFromMeta` 对两种良好形状、零结果空卡片、以及每种畸形情形(非对象/数组 meta、缺失或误型的 `truncated`/`total`、未知 `shape`、畸形 `files` 条目、非字符串 `paths`)的收窄。`packages/fs/tool-fs-search/tests/tools.spec.ts` 钉住经真实工具注册表的接线:被截断的 `grep`/`glob` execute 在 `result.meta` 上产出 `SearchMeta`,`presentResult` 构建搜索视图(无 `content`),嵌套 `run_code` 分发不计算 meta 故 `presentResult` 回退,失败或跨形状或畸形结果回退到 generic 卡片。搜索包 `src` 上保持 per-file 100% 覆盖。
+
+## 相关
+
+- [工具调用呈现的带标签渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 PR 用 `search` 结果标签扩展的 `card` 标签词汇。
+- [Canonical 工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所乘的 value/render/`presentationMeta` 划分;结构化值留在执行本地,卡片乘 `meta`。
+- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— 本 PR 在后端镜像的先例:工具把结果投影进 `presentationMeta` 与一个 `presentResult` 视图;搜索卡片的 web 消费方是与之类比的后续。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 3e8f197a8e..12cb6d6500 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1672,6 +1672,8 @@ export interface Config {
   grepMaxMatches?: number
   /** Max bytes retained for one matched-line preview (the cut preserves UTF-8 boundaries). */
   grepMaxLineBytes?: number
+  /** Max bytes of one search's serialized `presentationMeta`; trailing groups/paths drop past it so the persisted, re-sent card stays bounded. */
+  searchMetaMaxBytes?: number
   /** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
   rawOutputMaxBytes?: number
   /** Cooperative tool-call timeout budget (ms) on both tools, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`. */
@@ -1679,7 +1681,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/fs/tool-fs-search/src/index.ts:65`](../packages/fs/tool-fs-search/src/index.ts)
+Source: [`packages/fs/tool-fs-search/src/index.ts:71`](../packages/fs/tool-fs-search/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-goal`
 
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index 423737be39..0ce5d0df1c 100644
--- a/docs/cookbook/adding-a-tool.i18n.yaml
+++ b/docs/cookbook/adding-a-tool.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-adding-a-tool.md: d06e3d8e3c7da1f71a55bf9c4f56cd4b2cc03697
-adding-a-tool.zh.md: 53f608eba3b26b124f873990fa13ce1572c0baf2
+#   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-tool.md
+adding-a-tool.md: 75a4d87aab77c7dfcc31a1e8d0d58bc41e9e3f7e
+adding-a-tool.zh.md: ba76c14437f15b6c5381107cf2d7bd40eb5861b2
diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md
index d06e3d8e3c..75a4d87aab 100644
--- a/docs/cookbook/adding-a-tool.md
+++ b/docs/cookbook/adding-a-tool.md
@@ -78,6 +78,7 @@ Both methods return a **`card`-tagged render intent** — pick the card kind tha
   - `generic` supplies an optional title and content.
   - `terminal` supplies raw output and optional exit metadata; each UI renders its capable or fallback view.
   - `diff` supplies applied hunks, often derived by `output.presentationMeta` and carried in persisted `result.meta` so replay reproduces them. Mutation tools keep a diff result because the completed view replaces the pending card.
+  - `search` supplies a discovery result reconstructed from persisted `result.meta`: grouped-by-file matches (`shape: 'matches'`, grep) or a flat path list (`shape: 'paths'`, glob), plus `truncated`/`total` so a UI never presents a capped result as complete. The view carries no result text (a UI without a search card falls back to the raw result content), and there is no `search` call view — a discovery call's pending state stays a generic card, since matches exist only after `execute`. (tool-fs-search `grep`/`glob`.)
 
 Hard rules (they bite if broken):
 
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index 53f608eba3..ba76c14437 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -78,6 +78,7 @@ producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的
   - `generic` 提供可选的标题和内容。
   - `terminal` 提供原始输出和可选的退出元数据;各 UI 根据自身能力渲染对应视图或回退视图。
   - `diff` 提供已应用的 hunk,通常由 `output.presentationMeta` 派生并通过持久化的 `result.meta` 携带,使回放能重现它们。变更类工具保留 diff 结果,因为完成后的视图会替换 pending 卡片。
+  - `search` 提供从持久化 `result.meta` 重建的发现型结果:按文件分组的匹配(`shape: 'matches'`,grep)或扁平路径列表(`shape: 'paths'`,glob),外加 `truncated`/`total` 使 UI 永不把被截断的结果当作完整结果呈现。该视图不携带结果文本(无 search 卡片的 UI 回退到原始结果内容),也没有 `search` 调用视图——发现型调用的 pending 状态保持为 generic 卡片,因为匹配只在 `execute` 之后才存在。(tool-fs-search 的 `grep`/`glob`。)
 
 硬性规则(违反会出问题):
 
diff --git a/docs/core-data-structures/tools.i18n.yaml b/docs/core-data-structures/tools.i18n.yaml
index fa49f46c59..326a95a9b1 100644
--- a/docs/core-data-structures/tools.i18n.yaml
+++ b/docs/core-data-structures/tools.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 docs/core-data-structures/tools.md
-tools.md: dad7f7421caa94940801407fd4ef7fd936eb05c9
-tools.zh.md: 8386e5870e665e90ee0dbada8cb98084281001a7
+tools.md: c6a6ebf4e65cc8abf93ebeff756dde5819b8806a
+tools.zh.md: 0a83ae92f2b400e1279f397a434ac8e4ad020464
diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md
index dad7f7421c..c6a6ebf4e6 100644
--- a/docs/core-data-structures/tools.md
+++ b/docs/core-data-structures/tools.md
@@ -447,7 +447,7 @@ type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
 How a tool wants its call shown in a UI (an editor tool-call card, a CLI log line), provider-neutral so a tool describes itself without depending on any client protocol. `presentCall`/`presentResult` return a **`card`-tagged render intent** — a discriminated union a UI bridge switches on:
 
 - `ToolCallView` (pending): `{ card: 'generic', title, kind?, rawInput?, content?, locations? }` (the default card; `locations` is `{ path, line? }[]` files the call reads/modifies, for editor follow-along), `{ card: 'terminal', title, description?, cwd? }` (a shell command → a terminal card), or `{ card: 'diff', title, diffs, locations? }` (a file create/modify → an inline diff card; `diffs` is `{ path, oldText, newText }[]`, `oldText: null` for a new file).
-- `ToolResultView` (completed): `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }` (the captured run output + exit; a capable UI shows an exit-status pill, while another may derive a fenced ` ```console ` fallback), or `{ card: 'diff', title?, diffs }` (a completed file mutation → the change to show, typically the applied hunks with context lines computed from the before/after content, or a whole-file diff when there is no before-image). Completed views replace pending views, so mutation tools return a diff result even when it duplicates the call-time snippet.
+- `ToolResultView` (completed): `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }` (the captured run output + exit; a capable UI shows an exit-status pill, while another may derive a fenced ` ```console ` fallback), `{ card: 'diff', title?, diffs }` (a completed file mutation → the change to show, typically the applied hunks with context lines computed from the before/after content, or a whole-file diff when there is no before-image), or `{ card: 'search', shape, title?, truncated, total, … }` (a completed discovery search → grouped-by-file matches for `shape: 'matches'` (grep) or a flat path list for `shape: 'paths'` (glob); `truncated`/`total` report whether the inline result was capped so a UI never presents a partial result as complete; the view carries no result text — a UI without a search card falls back to the raw result content). Completed views replace pending views, so mutation tools return a diff result even when it duplicates the call-time snippet; a search has no `card: 'search'` call-time analogue (its pending state stays a generic card, since matches exist only after `execute`).
 
 `ToolCallKind` (`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`) picks an icon on a generic card. `FileLocation` (`{ path, line? }`) and `FileDiff` (`{ path, oldText, newText }`) are the shared file-card vocabulary. The design is pinned in [the render-intent-union Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md); the TUI and host/client runtime project this neutral vocabulary into their own views.
 
diff --git a/docs/core-data-structures/tools.zh.md b/docs/core-data-structures/tools.zh.md
index 8386e5870e..0a83ae92f2 100644
--- a/docs/core-data-structures/tools.zh.md
+++ b/docs/core-data-structures/tools.zh.md
@@ -447,7 +447,7 @@ type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
 工具希望其调用在 UI 中如何呈现(编辑器工具调用卡片、CLI(命令行界面)日志行),提供方无关,使工具在不依赖任何客户端协议的情况下描述自身。`presentCall`/`presentResult` 返回一个 **`card` 标签的渲染意图**——一个可辨识联合类型,UI 桥接层据此分发:
 
 - `ToolCallView`(待执行):`{ card: 'generic', title, kind?, rawInput?, content?, locations? }`(默认卡片;`locations` 是 `{ path, line? }[]`,表示调用读取/修改的文件,供编辑器跟随)、`{ card: 'terminal', title, description?, cwd? }`(shell 命令→终端卡片)、或 `{ card: 'diff', title, diffs, locations? }`(文件创建/修改→行内 diff 卡片;`diffs` 是 `{ path, oldText, newText }[]`,新文件时 `oldText: null`)。
-- `ToolResultView`(已完成):`{ card: 'generic', title?, content? }`、`{ card: 'terminal', title?, output?, exitCode?, signal? }`(捕获的运行输出 + 退出状态;有能力的 UI 显示退出状态标签,其他 UI 可以派生围栏 ` ```console ` 回退)、或 `{ card: 'diff', title?, diffs }`(已完成的文件变更→要展示的变更,通常是从变更前后内容计算出带上下文行的已应用 hunk,或在没有前像时的整文件 diff)。已完成视图会替换待执行视图,因此变更工具即使与调用时的片段重复也要返回 diff 结果。
+- `ToolResultView`(已完成):`{ card: 'generic', title?, content? }`、`{ card: 'terminal', title?, output?, exitCode?, signal? }`(捕获的运行输出 + 退出状态;有能力的 UI 显示退出状态标签,其他 UI 可以派生围栏 ` ```console ` 回退)、`{ card: 'diff', title?, diffs }`(已完成的文件变更→要展示的变更,通常是从变更前后内容计算出带上下文行的已应用 hunk,或在没有前像时的整文件 diff)、或 `{ card: 'search', shape, title?, truncated, total, … }`(已完成的发现型搜索→`shape: 'matches'`(grep)为按文件分组的匹配,`shape: 'paths'`(glob)为扁平路径列表;`truncated`/`total` 报告内联结果是否被截断,使 UI 永不把部分结果当作完整结果呈现;该视图不携带结果文本——无 search 卡片的 UI 回退到原始结果内容)。已完成视图会替换待执行视图,因此变更工具即使与调用时的片段重复也要返回 diff 结果;搜索没有 `card: 'search'` 的调用时对应视图(其 pending 状态保持为 generic 卡片,因为匹配只在 `execute` 之后才存在)。
 
 `ToolCallKind`(`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`)用于为通用卡片选择图标。`FileLocation`(`{ path, line? }`)与 `FileDiff`(`{ path, oldText, newText }`)是共享的文件卡片词汇。该设计由[渲染意图联合类型 Agent Note(agent 决策记录)](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md)固定;TUI 和 host/client 运行时将这套中性词汇投影为各自的视图。
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index e57855c29b..fddda8225e 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -2165,11 +2165,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SearchMatchesResultView',
-    declaration: 'export interface SearchMatchesResultView {\n    card: \'search\';\n    kind: \'matches\';\n    title?: string;\n    files: SearchFileMatches[];\n    truncated: boolean;\n    total: number;\n    content?: ContentBlock[];\n}',
+    declaration: 'export interface SearchMatchesResultView {\n    card: \'search\';\n    shape: \'matches\';\n    title?: string;\n    files: SearchFileMatches[];\n    truncated: boolean;\n    total: number;\n}',
   },
   {
     name: 'SearchPathsResultView',
-    declaration: 'export interface SearchPathsResultView {\n    card: \'search\';\n    kind: \'paths\';\n    title?: string;\n    paths: string[];\n    truncated: boolean;\n    total: number;\n    content?: ContentBlock[];\n}',
+    declaration: 'export interface SearchPathsResultView {\n    card: \'search\';\n    shape: \'paths\';\n    title?: string;\n    paths: string[];\n    truncated: boolean;\n    total: number;\n}',
   },
   {
     name: 'SearchResultView',
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index 429e76ed6a..854b5d78bf 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: e5adb153e77d7a2d8c4068b016194ab6abb6473e
-README.zh.md: c67a2f2ee4ac2a9d587c6efbf2b5c60d14fc58c2
+README.md: a8afab7839983d300c2c17627e34dafaa4648d8b
+README.zh.md: 8beb63e8376f397ac859a6a04ab2f35316ef6d27
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index e5adb153e7..a8afab7839 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -108,7 +108,7 @@ Optional `isConcurrencySafe(args)` receives typed, softly validated arguments. E
 Tools optionally own pure `presentCall()` and `presentResult()` render intents, so UIs do not special-case tool names:
 
 - Call views are `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`, `{ card: 'terminal', title, description?, cwd? }`, or `{ card: 'diff', title, diffs, locations? }`.
-- Result views are `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }`, or `{ card: 'diff', title?, diffs }`.
+- Result views are `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }`, `{ card: 'diff', title?, diffs }`, or `{ card: 'search', shape, title?, truncated, total, … }` (a completed discovery search — grouped-by-file matches for `shape: 'matches'` (grep) or a flat path list for `shape: 'paths'` (glob), with `truncated`/`total` so a UI never presents a capped result as complete; the view carries no result text and a search has no `card: 'search'` call-time analogue).
 
 Returning `undefined` selects generic fallback. Presenters depend only on their arguments and the durable result because UIs call them during live streaming and log replay. `output.presentationMeta(args, value)` derives JSON metadata for direct surface calls; that metadata persists with `tool/result` and returns to `presentResult`, while the canonical value itself remains execution-local and is never replayed. Nested Code dispatches do not compute metadata. `defineTool` soft-validates older logged arguments and falls back instead of crashing replay. `dsh-tool-bash` and `dsh-tool-fs` are the reference implementations; the [canonical-output Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md) owns the value/presentation split and the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) owns card vocabulary.
 
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index c67a2f2ee4..8beb63e837 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -108,7 +108,7 @@ ctx.tools.register(defineTool({
 工具可以选择拥有纯 `presentCall()` 和 `presentResult()` 呈现意图,使 UI 无需特殊处理工具名称:
 
 - 调用视图为 `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`、`{ card: 'terminal', title, description?, cwd? }` 或 `{ card: 'diff', title, diffs, locations? }`。
-- 结果视图为 `{ card: 'generic', title?, content? }`、`{ card: 'terminal', title?, output?, exitCode?, signal? }` 或 `{ card: 'diff', title?, diffs }`。
+- 结果视图为 `{ card: 'generic', title?, content? }`、`{ card: 'terminal', title?, output?, exitCode?, signal? }`、`{ card: 'diff', title?, diffs }` 或 `{ card: 'search', shape, title?, truncated, total, … }`(已完成的发现型搜索——`shape: 'matches'`(grep)为按文件分组的匹配,`shape: 'paths'`(glob)为扁平路径列表,配 `truncated`/`total` 使 UI 永不把被截断的结果当作完整结果呈现;该视图不携带结果文本,且搜索没有 `card: 'search'` 的调用时对应视图)。
 
 返回 `undefined` 会选择通用回退。呈现器只依赖其参数和持久结果,因为 UI 会在实时流式输出和日志回放期间调用它们。`output.presentationMeta(args, value)` 为直接接口调用派生 JSON 元数据;该元数据随 `tool/result` 持久化并传回 `presentResult`,而规范值本身仍只存在于执行局部,绝不会回放。嵌套 Code 分发不会计算元数据。`defineTool` 会软验证较旧的日志参数并回退,而不会使回放崩溃。`dsh-tool-bash` 与 `dsh-tool-fs` 是参考实现;[规范输出 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md) 规定值/呈现拆分,[呈现意图 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) 规定卡片词汇。
 
diff --git a/packages/core/tools/src/presentation.ts b/packages/core/tools/src/presentation.ts
index 338a73faa1..d8b6352b52 100644
--- a/packages/core/tools/src/presentation.ts
+++ b/packages/core/tools/src/presentation.ts
@@ -196,12 +196,14 @@ export interface SearchFileMatches {
 /**
  * A completed content search (`grep`) rendered as a search card whose matches are
  * grouped by file, so a capable UI can list each file as an expandable group of
- * its matched lines. `kind: 'matches'` discriminates this shape from the path
- * shape ({@link SearchPathsResultView}) within {@link SearchResultView}.
+ * its matched lines. `shape: 'matches'` discriminates this variant from the path
+ * variant ({@link SearchPathsResultView}) within {@link SearchResultView}. The
+ * discriminant is `shape`, not `kind`, so it never collides with the
+ * {@link ToolCallKind} `kind` an icon-picking bridge reads off a call view.
  */
 export interface SearchMatchesResultView {
   card: 'search'
-  kind: 'matches'
+  shape: 'matches'
   /** Replacement title for the completed call. Omit to keep the pending-state title. */
   title?: string
   /** Matched lines grouped by file, in first-seen file order. */
@@ -214,22 +216,16 @@ export interface SearchMatchesResultView {
   truncated: boolean
   /** Total matches the search found before capping (equals the retained count when not `truncated`). */
   total: number
-  /**
-   * UI-facing content blocks reproducing the model-facing result text, so a UI
-   * without a dedicated search card renders it as text. Omit to let the UI render
-   * the raw result content.
-   */
-  content?: ContentBlock[]
 }
 
 /**
  * A completed path search (`glob`) rendered as a search card whose result is a flat
- * path list. `kind: 'paths'` discriminates this shape from the grouped-matches
- * shape ({@link SearchMatchesResultView}) within {@link SearchResultView}.
+ * path list. `shape: 'paths'` discriminates this variant from the grouped-matches
+ * variant ({@link SearchMatchesResultView}) within {@link SearchResultView}.
  */
 export interface SearchPathsResultView {
   card: 'search'
-  kind: 'paths'
+  shape: 'paths'
   /** Replacement title for the completed call. Omit to keep the pending-state title. */
   title?: string
   /** The discovered paths, in the tool's result order (the retained page when `truncated`). */
@@ -242,24 +238,18 @@ export interface SearchPathsResultView {
   truncated: boolean
   /** Total paths the search found before capping (equals `paths.length` when not `truncated`). */
   total: number
-  /**
-   * UI-facing content blocks reproducing the model-facing result text, so a UI
-   * without a dedicated search card renders it as text. Omit to let the UI render
-   * the raw result content.
-   */
-  content?: ContentBlock[]
 }
 
 /**
  * A completed search rendered as a search card, the result-time view a discovery
  * tool (`grep`, `glob`) returns from `presentResult`. One `card: 'search'` view
- * with two `kind`-discriminated shapes: grouped-by-file content matches
+ * with two `shape`-discriminated variants: grouped-by-file content matches
  * ({@link SearchMatchesResultView}) and a flat path list
  * ({@link SearchPathsResultView}). Both carry a `truncated`/`total` signal so a UI
- * never presents a capped result as complete, and an optional `content` a UI
- * without a search card renders as text. There is no call-time analogue: a search
- * call stays a {@link GenericCallView} (`kind: 'search'`) because the pending
- * state has no matches or paths to show — the structured shape exists only after
- * `execute`.
+ * never presents a capped result as complete. The view carries no result text: a
+ * UI without a search card falls back to the raw `tool/result` content. There is
+ * no call-time analogue: a search call stays a {@link GenericCallView}
+ * (`kind: 'search'`) because the pending state has no matches or paths to show —
+ * the structured shape exists only after `execute`.
  */
 export type SearchResultView = SearchMatchesResultView | SearchPathsResultView
diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts
index 8fd2d20ebf..ba7990ca2e 100644
--- a/packages/fs/tool-fs-search/src/glob.ts
+++ b/packages/fs/tool-fs-search/src/glob.ts
@@ -12,12 +12,11 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView, SearchResultView, ToolResult } from '@deepseek-ai/dsh-tools'
-import { ItemRetainer } from '@deepseek-ai/dsh-retention'
 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 { runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
+import { retainGlobPaths, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
 import { globSearchMeta, searchViewFromMeta } from './presentation.ts'
 import { singleQuote } from './shell-quote.ts'
 import { acceptedSurfaceValue } from './surface.ts'
@@ -44,6 +43,8 @@ export const GLOB_VCS_EXCLUDES: readonly string[] = ['.git', '.svn', '.hg', '.bz
 export interface GlobToolCaps {
   /** Max paths retained inline; later paths go to the formatted spill file. */
   maxResults: number
+  /** Max bytes of serialized `presentationMeta`; trailing paths drop past it. */
+  maxMetaBytes: number
   /** Cap on the complete raw `rg` stdout the tool will parse. */
   rawOutputMaxBytes: number
   /** Cooperative tool-call budget (ms) attached as `ToolDefinition.timeoutMs`. */
@@ -118,12 +119,10 @@ export function formatGlobOutput(retained: RetainedItems, spillRef: Spil
   return `${body}\n\n(Showing ${retained.kept} of ${retained.seen} paths. ${recovery})`
 }
 
-/** Retain and format one canonical path list for the Native surface. */
-function renderGlobPaths(paths: string[], maxResults: number, spillRef?: SpillRef): string {
-  if (paths.length === 0) return 'No files found'
-  const retainer = new ItemRetainer({ kind: 'head', maxItems: maxResults })
-  for (const path of paths) retainer.push(path)
-  return formatGlobOutput(retainer.finish(), spillRef)
+/** Format one already-retained path list for the Native surface. */
+function formatRetainedGlob(retained: RetainedItems, spillRef?: SpillRef): string {
+  if (retained.seen === 0) return 'No files found'
+  return formatGlobOutput(retained, spillRef)
 }
 
 /**
@@ -139,10 +138,10 @@ export function presentGlobCall(args: { pattern: string; path?: string }): Gener
 
 /**
  * Completed-call presentation: the search card projected from the result's
- * `presentationMeta` (the discovered path list, with the truncation signal), with
- * the model-facing result text attached as `content` for a UI without a search
- * card. Malformed or absent metadata (an obsolete or hand-edited replayed log)
- * falls back to the generic card.
+ * `presentationMeta` (the discovered path list, with the truncation signal). A UI
+ * without a search card falls back to the raw `tool/result` content, so the view
+ * carries no result text of its own. Malformed or absent metadata (an obsolete or
+ * hand-edited replayed log) falls back to the generic card.
  *
  * @param _args - the raw tool arguments; unused, the view derives from the result.
  * @param result - the final model-facing tool result carrying the projected metadata.
@@ -151,8 +150,8 @@ export function presentGlobCall(args: { pattern: string; path?: string }): Gener
 export function presentGlobResult(_args: { pattern: string; path?: string }, result: ToolResult): SearchResultView | undefined {
   if (result.isError) return undefined
   const view = searchViewFromMeta(result.meta)
-  if (view === undefined || view.kind !== 'paths') return undefined
-  return { ...view, content: result.content }
+  if (view === undefined || view.shape !== 'paths') return undefined
+  return view
 }
 
 /**
@@ -187,8 +186,8 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void {
           paths: { type: 'array', required: true, items: { type: 'string' } },
         },
       },
-      render: (_args, value) => [{ type: 'text', text: renderGlobPaths(value.paths, caps.maxResults) }],
-      presentationMeta: (_args, value) => globSearchMeta(value.paths, caps.maxResults),
+      render: (_args, value) => [{ type: 'text', text: formatRetainedGlob(retainGlobPaths(value.paths, caps.maxResults)) }],
+      presentationMeta: (_args, value) => globSearchMeta(retainGlobPaths(value.paths, caps.maxResults), caps.maxMetaBytes),
     },
     async execute(args, exec) {
       const input = parseGlobArgs(args)
@@ -217,7 +216,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void {
     const spillRef = await trySaveFormattedResult(ctx, exec, 'glob-results.txt', paths.join('\n'))
     return {
       kind: 'accept',
-      content: [{ type: 'text', text: renderGlobPaths(paths, caps.maxResults, spillRef) }],
+      content: [{ type: 'text', text: formatRetainedGlob(retainGlobPaths(paths, caps.maxResults), spillRef) }],
       ...decision.additionalContexts !== undefined ? { additionalContexts: decision.additionalContexts } : {},
     }
   })
diff --git a/packages/fs/tool-fs-search/src/grep.ts b/packages/fs/tool-fs-search/src/grep.ts
index 4f3273f0fb..b7e67ea153 100644
--- a/packages/fs/tool-fs-search/src/grep.ts
+++ b/packages/fs/tool-fs-search/src/grep.ts
@@ -13,12 +13,12 @@
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView, SearchResultView, ToolResult } from '@deepseek-ai/dsh-tools'
-import { ItemRetainer, TextRetainer } from '@deepseek-ai/dsh-retention'
 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 { SearchError, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
+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'
@@ -42,6 +42,8 @@ export interface GrepToolCaps {
   maxMatches: number
   /** Max bytes retained per matched-line preview. */
   maxLineBytes: number
+  /** Max bytes of serialized `presentationMeta`; trailing file groups drop past it. */
+  maxMetaBytes: number
   /** Cap on the complete raw `rg` stdout the tool will parse. */
   rawOutputMaxBytes: number
   /** Cooperative tool-call budget (ms) attached as `ToolDefinition.timeoutMs`. */
@@ -55,13 +57,6 @@ export interface GrepInput {
   include?: string
 }
 
-/** One parsed match: the file, the 1-based line number, and the (possibly previewed) line text. */
-export interface GrepMatch {
-  path: string
-  lineNumber: number
-  line: string
-}
-
 /**
  * Reject an `include` that is not ONE positive glob filter: blank strings,
  * negated patterns (`!…`), and comma-separated lists. A comma inside a brace
@@ -178,22 +173,6 @@ export function parseGrepMatches(stdout: string): GrepMatch[] {
   return matches
 }
 
-/**
- * Bound one matched-line preview to `maxBytes` (UTF-8 boundary preserved) and
- * mark the cut. The cap is a per-line budget fact; the complete line stays in
- * the searched file for `read`.
- *
- * @param line - the matched line text (trailing newline already stripped).
- * @param maxBytes - the preview budget in bytes.
- * @returns the preview, suffixed with ` (line truncated)` when bytes were cut.
- */
-export function previewLine(line: string, maxBytes: number): string {
-  const retainer = new TextRetainer({ kind: 'head', maxBytes })
-  retainer.push(line)
-  const kept = retainer.finish()
-  return kept.truncated ? `${kept.text} (line truncated)` : kept.text
-}
-
 /** `match` / `matches` for a count. */
 function matchNoun(count: number): string {
   return count === 1 ? 'match' : 'matches'
@@ -242,18 +221,10 @@ export function formatGrepOutput(retained: RetainedItems, spillRef: S
   return `${header}\n\n${body}\n\n(${recovery})`
 }
 
-/** Apply the Native per-line preview budget without changing the canonical matches. */
-function previewGrepMatches(matches: GrepMatch[], maxLineBytes: number): GrepMatch[] {
-  return matches.map(match => ({ ...match, line: previewLine(match.line, maxLineBytes) }))
-}
-
-/** Retain and format one canonical match list for the Native surface. */
-function renderGrepMatches(matches: GrepMatch[], maxMatches: number, maxLineBytes: number, spillRef?: SpillRef): string {
-  if (matches.length === 0) return 'No matches found'
-  const previewed = previewGrepMatches(matches, maxLineBytes)
-  const retainer = new ItemRetainer({ kind: 'head', maxItems: maxMatches })
-  for (const match of previewed) retainer.push(match)
-  return formatGrepOutput(retainer.finish(), spillRef)
+/** Format one already-retained match list for the Native surface. */
+function formatRetainedGrep(retained: RetainedItems, spillRef?: SpillRef): string {
+  if (retained.seen === 0) return 'No matches found'
+  return formatGrepOutput(retained, spillRef)
 }
 
 /**
@@ -271,10 +242,10 @@ export function presentGrepCall(args: { pattern: string; path?: string; include?
 
 /**
  * Completed-call presentation: the search card projected from the result's
- * `presentationMeta` (matches grouped by file, with the truncation signal), with
- * the model-facing result text attached as `content` for a UI without a search
- * card. Malformed or absent metadata (an obsolete or hand-edited replayed log)
- * falls back to the generic card.
+ * `presentationMeta` (matches grouped by file, with the truncation signal). A UI
+ * without a search card falls back to the raw `tool/result` content, so the view
+ * carries no result text of its own. Malformed or absent metadata (an obsolete or
+ * hand-edited replayed log) falls back to the generic card.
  *
  * @param _args - the raw tool arguments; unused, the view derives from the result.
  * @param result - the final model-facing tool result carrying the projected metadata.
@@ -286,8 +257,8 @@ export function presentGrepResult(
 ): SearchResultView | undefined {
   if (result.isError) return undefined
   const view = searchViewFromMeta(result.meta)
-  if (view === undefined || view.kind !== 'matches') return undefined
-  return { ...view, content: result.content }
+  if (view === undefined || view.shape !== 'matches') return undefined
+  return view
 }
 
 /**
@@ -337,9 +308,10 @@ export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void {
       },
       render: (_args, value) => [{
         type: 'text',
-        text: renderGrepMatches(value.matches, caps.maxMatches, caps.maxLineBytes),
+        text: formatRetainedGrep(retainGrepMatches(value.matches, caps.maxMatches, caps.maxLineBytes)),
       }],
-      presentationMeta: (_args, value) => grepSearchMeta(value.matches, caps.maxMatches, caps.maxLineBytes),
+      presentationMeta: (_args, value) =>
+        grepSearchMeta(retainGrepMatches(value.matches, caps.maxMatches, caps.maxLineBytes), caps.maxMetaBytes),
     },
     async execute(args, exec) {
       const input = parseGrepArgs(args)
@@ -368,17 +340,20 @@ export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void {
     if (value === undefined) return decision
     const matches = value.matches
     if (matches.length <= caps.maxMatches) return decision
+    // The spill artifact holds the COMPLETE result: preview each line, but keep
+    // every match (no inline cap), so the recovery file is the full search.
+    const previewedAll = matches.map(match => ({ ...match, line: previewLine(match.line, caps.maxLineBytes) }))
     const spillRef = await trySaveFormattedResult(
       ctx,
       exec,
       'grep-results.txt',
-      `Found ${matches.length} ${matchNoun(matches.length)}\n\n${formatGrepMatches(previewGrepMatches(matches, caps.maxLineBytes))}`,
+      `Found ${matches.length} ${matchNoun(matches.length)}\n\n${formatGrepMatches(previewedAll)}`,
     )
     return {
       kind: 'accept',
       content: [{
         type: 'text',
-        text: renderGrepMatches(matches, caps.maxMatches, caps.maxLineBytes, spillRef),
+        text: formatRetainedGrep(retainGrepMatches(matches, caps.maxMatches, caps.maxLineBytes), spillRef),
       }],
       ...decision.additionalContexts !== undefined ? { additionalContexts: decision.additionalContexts } : {},
     }
diff --git a/packages/fs/tool-fs-search/src/index.ts b/packages/fs/tool-fs-search/src/index.ts
index 0c53776d1e..f7b75bbc2a 100644
--- a/packages/fs/tool-fs-search/src/index.ts
+++ b/packages/fs/tool-fs-search/src/index.ts
@@ -31,7 +31,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_TIMEOUT_MS } from './search-core.ts'
+import { RAW_OUTPUT_MAX_BYTES, SEARCH_META_MAX_BYTES, SEARCH_TIMEOUT_MS } from './search-core.ts'
 
 export { GLOB_MAX_RESULTS, GLOB_VCS_EXCLUDES, applyGlobTool, buildGlobCommand, formatGlobOutput, parseGlobArgs, presentGlobCall, presentGlobResult } from './glob.ts'
 export type { GlobInput, GlobToolCaps } from './glob.ts'
@@ -46,13 +46,19 @@ export {
   parseGrepMatches,
   presentGrepCall,
   presentGrepResult,
-  previewLine,
 } from './grep.ts'
-export type { GrepInput, GrepMatch, GrepToolCaps } from './grep.ts'
-export { globSearchMeta, grepSearchMeta, groupMatchesByFile, searchViewFromMeta } from './presentation.ts'
-export type { SearchMeta } from './presentation.ts'
-export { RAW_OUTPUT_MAX_BYTES, SEARCH_TIMEOUT_MS, SearchError, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
-export type { RipgrepRun, SearchErrorCode } from './search-core.ts'
+export type { GrepInput, GrepToolCaps } from './grep.ts'
+export {
+  RAW_OUTPUT_MAX_BYTES,
+  SEARCH_META_MAX_BYTES,
+  SEARCH_TIMEOUT_MS,
+  SearchError,
+  previewLine,
+  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. */
@@ -69,6 +75,8 @@ export interface Config {
   grepMaxMatches?: number
   /** Max bytes retained for one matched-line preview (the cut preserves UTF-8 boundaries). */
   grepMaxLineBytes?: number
+  /** Max bytes of one search's serialized `presentationMeta`; trailing groups/paths drop past it so the persisted card stays bounded. */
+  searchMetaMaxBytes?: number
   /** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
   rawOutputMaxBytes?: number
   /** Cooperative tool-call timeout budget (ms) on both tools, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`. */
@@ -79,6 +87,7 @@ export const Config: z = z.object({
   globMaxResults: z.number().default(GLOB_MAX_RESULTS),
   grepMaxMatches: z.number().default(GREP_MAX_MATCHES),
   grepMaxLineBytes: z.number().default(GREP_MAX_LINE_BYTES),
+  searchMetaMaxBytes: z.number().default(SEARCH_META_MAX_BYTES),
   rawOutputMaxBytes: z.number().default(RAW_OUTPUT_MAX_BYTES),
   timeoutMs: z.number().default(SEARCH_TIMEOUT_MS),
 })
@@ -133,6 +142,7 @@ export async function apply(ctx: Context, config: Config): Promise {
   assertPositiveInteger('globMaxResults', resolved.globMaxResults)
   assertPositiveInteger('grepMaxMatches', resolved.grepMaxMatches)
   assertPositiveInteger('grepMaxLineBytes', resolved.grepMaxLineBytes)
+  assertPositiveInteger('searchMetaMaxBytes', resolved.searchMetaMaxBytes)
   assertPositiveInteger('rawOutputMaxBytes', resolved.rawOutputMaxBytes)
   assertPositiveInteger('timeoutMs', resolved.timeoutMs)
   if (!await ripgrepAvailable(ctx)) {
@@ -141,12 +151,14 @@ export async function apply(ctx: Context, config: Config): Promise {
   }
   applyGlobTool(ctx, {
     maxResults: resolved.globMaxResults,
+    maxMetaBytes: resolved.searchMetaMaxBytes,
     rawOutputMaxBytes: resolved.rawOutputMaxBytes,
     timeoutMs: resolved.timeoutMs,
   })
   applyGrepTool(ctx, {
     maxMatches: resolved.grepMaxMatches,
     maxLineBytes: resolved.grepMaxLineBytes,
+    maxMetaBytes: resolved.searchMetaMaxBytes,
     rawOutputMaxBytes: resolved.rawOutputMaxBytes,
     timeoutMs: resolved.timeoutMs,
   })
diff --git a/packages/fs/tool-fs-search/src/presentation.ts b/packages/fs/tool-fs-search/src/presentation.ts
index 479a64d7d1..669c4b1d0a 100644
--- a/packages/fs/tool-fs-search/src/presentation.ts
+++ b/packages/fs/tool-fs-search/src/presentation.ts
@@ -1,7 +1,7 @@
 /**
  * Result-time search-card presentation for `grep` and `glob`. Both tools land on
  * one `card: 'search'` render intent ({@link SearchResultView}) with two
- * `kind`-discriminated shapes: `grep` projects its matches grouped by file
+ * `shape`-discriminated variants: `grep` projects its matches grouped by file
  * ({@link SearchMatchesResultView}), `glob` projects a flat path list
  * ({@link SearchPathsResultView}). This module owns the value→`presentationMeta`
  * projection each tool declares and the defensive `meta`→view narrowing each
@@ -9,11 +9,19 @@
  *
  * The canonical value never crosses the wire — only the model-facing render text
  * and this JSON `meta` do — so the structured shape a UI renders MUST ride in
- * `meta`. Each projection applies the SAME inline cap the model-facing render
- * applies ({@link module:@deepseek-ai/dsh-tool-fs-search/grep} `grepMaxMatches`,
- * {@link module:@deepseek-ai/dsh-tool-fs-search/glob} `globMaxResults`) and reports
- * `total` (every result found) and `truncated`, so a UI never presents a capped
- * result as complete.
+ * `meta`. Each projection consumes the SAME retained matches/paths the
+ * model-facing render consumes ({@link module:@deepseek-ai/dsh-tool-fs-search/search-core}
+ * `retainGrepMatches`/`retainGlobPaths`), so text and card agree about which
+ * results survived the inline cap, and reports `total` (every result found) and
+ * `truncated`, so a UI never presents a capped result as complete.
+ *
+ * A second, independent cap bounds the JSON `meta` itself: the retained matches
+ * of a broad search (hundreds of long lines) can still serialize to hundreds of
+ * kilobytes, and `meta` is persisted with the session log and re-sent on every
+ * request. {@link capMetaBytes} drops trailing groups/paths until the serialized
+ * `meta` fits `maxMetaBytes` and marks the result `truncated`; a deployment's
+ * final output budget (`dsh-spill-policy`) only shrinks `content`, never `meta`,
+ * so this projection owns keeping `meta` bounded.
  *
  * @module @deepseek-ai/dsh-tool-fs-search/presentation
  */
@@ -23,9 +31,8 @@ import type {
   SearchLineMatch,
   SearchResultView,
 } from '@deepseek-ai/dsh-tools'
-import { ItemRetainer } from '@deepseek-ai/dsh-retention'
-import type { GrepMatch } from './grep.ts'
-import { previewLine } from './grep.ts'
+import type { RetainedItems } from '@deepseek-ai/dsh-retention'
+import type { GrepMatch } from './search-core.ts'
 
 /**
  * The `grep`/`glob` tools' private `tool/result` `meta` payload: the capped,
@@ -42,8 +49,8 @@ import { previewLine } from './grep.ts'
  * back as a {@link SearchResultView}.
  */
 export type SearchMeta =
-  | { kind: 'matches'; files: MetaFileMatches[]; truncated: boolean; total: number }
-  | { kind: 'paths'; paths: string[]; truncated: boolean; total: number }
+  | { shape: 'matches'; files: MetaFileMatches[]; truncated: boolean; total: number }
+  | { shape: 'paths'; paths: string[]; truncated: boolean; total: number }
 
 /** One matched line in {@link SearchMeta} (the JSON-assignable form of {@link SearchLineMatch}). */
 type MetaLineMatch = { lineNumber: number; line: string }
@@ -72,38 +79,73 @@ export function groupMatchesByFile(matches: GrepMatch[]): MetaFileMatches[] {
   return Array.from(byFile, ([path, fileMatches]) => ({ path, matches: fileMatches }))
 }
 
-/**
- * Project the canonical `grep` matches into {@link SearchMeta} for the search
- * card. Applies the per-line preview budget and the inline match cap exactly as
- * the model-facing render does, groups the retained matches by file, and reports
- * `total` (every parsed match) and `truncated`.
- *
- * @param matches - every match the search parsed (the canonical value's matches).
- * @param maxMatches - the inline match cap (the `grepMaxMatches` config).
- * @param maxLineBytes - the per-matched-line preview budget in bytes.
- * @returns the `matches`-shaped search metadata.
- */
-export function grepSearchMeta(matches: GrepMatch[], maxMatches: number, maxLineBytes: number): SearchMeta {
-  const retainer = new ItemRetainer({ kind: 'head', maxItems: maxMatches })
-  for (const match of matches) retainer.push({ ...match, line: previewLine(match.line, maxLineBytes) })
-  const retained = retainer.finish()
-  return { kind: 'matches', files: groupMatchesByFile(retained.items), truncated: retained.truncated, total: retained.seen }
+/** The serialized UTF-8 byte size of one meta payload (the size persisted and re-sent). */
+function metaBytes(meta: SearchMeta): number {
+  return Buffer.byteLength(JSON.stringify(meta), 'utf8')
 }
 
 /**
- * Project the canonical `glob` paths into {@link SearchMeta} for the search card.
- * Applies the inline path cap exactly as the model-facing render does and reports
- * `total` (every discovered path) and `truncated`.
+ * Drop trailing top-level items (file groups or paths) until the serialized meta
+ * fits `maxMetaBytes`, marking the result `truncated` when anything was dropped.
+ * `total` is preserved (it counts what the search found, not what meta retains).
+ * A single item too large to fit on its own is kept: the invariant is a bounded
+ * payload wherever droppable, never an empty card that hides a real result.
  *
- * @param paths - every path the search discovered (the canonical value's paths).
- * @param maxResults - the inline path cap (the `globMaxResults` config).
+ * @param meta - the projected meta, already capped to the inline item count.
+ * @param maxMetaBytes - the serialized-meta byte budget.
+ * @returns the same meta when it fits, else a byte-bounded copy marked `truncated`.
+ */
+function capMetaBytes(meta: SearchMeta, maxMetaBytes: number): SearchMeta {
+  if (metaBytes(meta) <= maxMetaBytes) return meta
+  if (meta.shape === 'matches') {
+    const files = [...meta.files]
+    while (files.length > 1 && metaBytes({ ...meta, files, truncated: true }) > maxMetaBytes) files.pop()
+    return { ...meta, files, truncated: true }
+  }
+  const paths = [...meta.paths]
+  while (paths.length > 1 && metaBytes({ ...meta, paths, truncated: true }) > maxMetaBytes) paths.pop()
+  return { ...meta, paths, truncated: true }
+}
+
+/**
+ * Project the retained `grep` matches into {@link SearchMeta} for the search
+ * card. Consumes the same {@link RetainedItems} the model-facing render consumes
+ * (preview budget and inline match cap already applied), groups the retained
+ * matches by file, reports `total` (every parsed match) and `truncated`, then
+ * bounds the serialized meta to `maxMetaBytes`.
+ *
+ * @param retained - the retention outcome over every parsed match (previewed, capped).
+ * @param maxMetaBytes - the serialized-meta byte budget.
+ * @returns the `matches`-shaped search metadata.
+ */
+export function grepSearchMeta(retained: RetainedItems, maxMetaBytes: number): SearchMeta {
+  const meta: SearchMeta = {
+    shape: 'matches',
+    files: groupMatchesByFile(retained.items),
+    truncated: retained.truncated,
+    total: retained.seen,
+  }
+  return capMetaBytes(meta, maxMetaBytes)
+}
+
+/**
+ * Project the retained `glob` paths into {@link SearchMeta} for the search card.
+ * Consumes the same {@link RetainedItems} the model-facing render consumes (inline
+ * path cap already applied), reports `total` (every discovered path) and
+ * `truncated`, then bounds the serialized meta to `maxMetaBytes`.
+ *
+ * @param retained - the retention outcome over every discovered path (capped).
+ * @param maxMetaBytes - the serialized-meta byte budget.
  * @returns the `paths`-shaped search metadata.
  */
-export function globSearchMeta(paths: string[], maxResults: number): SearchMeta {
-  const retainer = new ItemRetainer({ kind: 'head', maxItems: maxResults })
-  for (const path of paths) retainer.push(path)
-  const retained = retainer.finish()
-  return { kind: 'paths', paths: retained.items, truncated: retained.truncated, total: retained.seen }
+export function globSearchMeta(retained: RetainedItems, maxMetaBytes: number): SearchMeta {
+  const meta: SearchMeta = {
+    shape: 'paths',
+    paths: retained.items,
+    truncated: retained.truncated,
+    total: retained.seen,
+  }
+  return capMetaBytes(meta, maxMetaBytes)
 }
 
 /** Whether `value` is a valid {@link SearchLineMatch} (defensive narrowing from opaque `meta`). */
@@ -124,8 +166,13 @@ function isSearchFileMatches(value: unknown): value is SearchFileMatches {
  * Narrow opaque live or replayed result metadata to a {@link SearchResultView}.
  * Malformed metadata returns `undefined` so `presentResult` can fall back to the
  * generic card instead of throwing during replay of an older or hand-edited log.
- * The returned view carries no `content`; the caller attaches the model-facing
- * result text so a UI without a search card renders it as text.
+ * The view carries no result text: a UI without a search card falls back to the
+ * raw `tool/result` content.
+ *
+ * A zero-result meta (`files: []` / `paths: []`) narrows to a valid empty card —
+ * unlike the mirrored `diffsFromMeta`, which rejects empty diffs, because a
+ * zero-match grep is a legitimate result a UI shows as "no matches", not an
+ * absent projection.
  *
  * @param meta - result metadata (the {@link SearchMeta} the tool projected).
  * @returns the search view, or `undefined` for absent or malformed metadata.
@@ -135,15 +182,15 @@ export function searchViewFromMeta(meta: unknown): SearchResultView | undefined
   const record = meta as Record
   const { truncated, total } = record
   if (typeof truncated !== 'boolean' || typeof total !== 'number') return undefined
-  if (record.kind === 'matches') {
+  if (record.shape === 'matches') {
     const { files } = record
     if (!Array.isArray(files) || !files.every(isSearchFileMatches)) return undefined
-    return { card: 'search', kind: 'matches', files: files, truncated, total }
+    return { card: 'search', shape: 'matches', files: files, truncated, total }
   }
-  if (record.kind === 'paths') {
+  if (record.shape === 'paths') {
     const { paths } = record
     if (!Array.isArray(paths) || !paths.every((path): path is string => typeof path === 'string')) return undefined
-    return { card: 'search', kind: 'paths', paths, truncated, total }
+    return { card: 'search', shape: 'paths', paths, truncated, total }
   }
   return undefined
 }
diff --git a/packages/fs/tool-fs-search/src/search-core.ts b/packages/fs/tool-fs-search/src/search-core.ts
index 0eff077fea..402fc9d655 100644
--- a/packages/fs/tool-fs-search/src/search-core.ts
+++ b/packages/fs/tool-fs-search/src/search-core.ts
@@ -19,6 +19,8 @@
 import { isAbsolute, relative, sep } from 'node:path'
 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 { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
@@ -36,6 +38,18 @@ export const RAW_OUTPUT_MAX_BYTES = 20_000_000
  */
 export const SEARCH_TIMEOUT_MS = 30_000
 
+/**
+ * Default cap in bytes on one search's serialized `presentationMeta` (the
+ * `searchMetaMaxBytes` config). The inline match/path caps already bound the item
+ * COUNT, but retained matches of a broad search (many long lines) can still
+ * serialize to hundreds of kilobytes, and `meta` is persisted with the session
+ * log and re-sent on every request. A deployment's final output budget
+ * (`dsh-spill-policy`) only shrinks a result's `content`, never its `meta`, so the
+ * projection owns this cap. 64 KiB holds the full default-capped result of a
+ * typical search while bounding the pathological one.
+ */
+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`
@@ -212,6 +226,63 @@ export function toWorkdirRelative(path: string, workdir: string): string {
   return rel
 }
 
+/** One parsed match: the file, the 1-based line number, and the (possibly previewed) line text. */
+export interface GrepMatch {
+  path: string
+  lineNumber: number
+  line: string
+}
+
+/**
+ * Bound one matched-line preview to `maxBytes` (UTF-8 boundary preserved) and
+ * mark the cut. The cap is a per-line budget fact; the complete line stays in
+ * the searched file for `read`.
+ *
+ * @param line - the matched line text (trailing newline already stripped).
+ * @param maxBytes - the preview budget in bytes.
+ * @returns the preview, suffixed with ` (line truncated)` when bytes were cut.
+ */
+export function previewLine(line: string, maxBytes: number): string {
+  const retainer = new TextRetainer({ kind: 'head', maxBytes })
+  retainer.push(line)
+  const kept = retainer.finish()
+  return kept.truncated ? `${kept.text} (line truncated)` : kept.text
+}
+
+/**
+ * Apply the shared inline cap to a canonical `grep` match list: preview each
+ * retained line to `maxLineBytes` and keep the first `maxMatches`. The single
+ * retention pass both the model-facing render ({@link module:@deepseek-ai/dsh-tool-fs-search/grep}
+ * `formatGrepOutput`) and the search-card projection
+ * ({@link module:@deepseek-ai/dsh-tool-fs-search/presentation} `grepSearchMeta`)
+ * consume, so text and card never disagree about which matches survived.
+ *
+ * @param matches - every match the search parsed (the canonical value's matches).
+ * @param maxMatches - the inline match cap (the `grepMaxMatches` config).
+ * @param maxLineBytes - the per-matched-line preview budget in bytes.
+ * @returns the retention outcome over the previewed matches.
+ */
+export function retainGrepMatches(matches: GrepMatch[], maxMatches: number, maxLineBytes: number): RetainedItems {
+  const retainer = new ItemRetainer({ kind: 'head', maxItems: maxMatches })
+  for (const match of matches) retainer.push({ ...match, line: previewLine(match.line, maxLineBytes) })
+  return retainer.finish()
+}
+
+/**
+ * Apply the shared inline cap to a canonical `glob` path list: keep the first
+ * `maxResults`. The single retention pass both the model-facing render and the
+ * search-card projection consume.
+ *
+ * @param paths - every path the search discovered (the canonical value's paths).
+ * @param maxResults - the inline path cap (the `globMaxResults` config).
+ * @returns the retention outcome over the paths.
+ */
+export function retainGlobPaths(paths: string[], maxResults: number): RetainedItems {
+  const retainer = new ItemRetainer({ kind: 'head', maxItems: maxResults })
+  for (const path of paths) retainer.push(path)
+  return retainer.finish()
+}
+
 /**
  * Best-effort save of one COMPLETE formatted search result through
  * `ctx.spillStore.saveText()` — the model-facing recovery path for a capped
diff --git a/packages/fs/tool-fs-search/tests/presentation.spec.ts b/packages/fs/tool-fs-search/tests/presentation.spec.ts
index 7f3131a2ab..59c47aece2 100644
--- a/packages/fs/tool-fs-search/tests/presentation.spec.ts
+++ b/packages/fs/tool-fs-search/tests/presentation.spec.ts
@@ -2,9 +2,10 @@
  * Unit tests for the search-card presentation layer (`src/presentation.ts`): the
  * canonical value → `presentationMeta` projections (`grepSearchMeta`,
  * `globSearchMeta`, `groupMatchesByFile`) and the defensive `meta` → view
- * narrowing (`searchViewFromMeta`). These pin the by-file grouping, the inline
- * cap and `truncated`/`total` honesty, and the malformed-metadata fallback a
- * replayed or hand-edited log can deliver.
+ * narrowing (`searchViewFromMeta`). These pin the by-file grouping, the
+ * `truncated`/`total` honesty over already-retained input, the serialized-meta
+ * byte cap, and the malformed-metadata fallback a replayed or hand-edited log can
+ * deliver.
  */
 
 import { describe, expect, it } from 'vitest'
@@ -15,10 +16,14 @@ import {
   groupMatchesByFile,
   searchViewFromMeta,
 } from '../src/presentation.ts'
-import type { GrepMatch } from '../src/grep.ts'
+import type { GrepMatch } from '../src/search-core.ts'
+import { retainGlobPaths, retainGrepMatches } from '../src/search-core.ts'
 
 const match = (path: string, lineNumber: number, line: string): GrepMatch => ({ path, lineNumber, line })
 
+/** A byte cap large enough that no test payload here is meta-capped. */
+const WIDE = 1_000_000
+
 describe('groupMatchesByFile', () => {
   it('groups matches by first-seen file order, keeping line/lineNumber only', () => {
     expect(groupMatchesByFile([
@@ -38,38 +43,73 @@ describe('groupMatchesByFile', () => {
 
 describe('grepSearchMeta', () => {
   it('projects grouped matches with total and a false truncation flag within the cap', () => {
-    const meta = grepSearchMeta([match('a.ts', 1, 'one'), match('a.ts', 2, 'two')], 10, 2000)
+    const meta = grepSearchMeta(retainGrepMatches([match('a.ts', 1, 'one'), match('a.ts', 2, 'two')], 10, 2000), WIDE)
     expect(meta).toEqual({
-      kind: 'matches',
+      shape: 'matches',
       files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'one' }, { lineNumber: 2, line: 'two' }] }],
       truncated: false,
       total: 2,
     })
   })
 
-  it('caps the retained matches and reports the pre-cap total when truncated', () => {
-    const meta = grepSearchMeta([match('a.ts', 1, 'one'), match('a.ts', 2, 'two'), match('b.ts', 3, 'three')], 2, 2000)
+  it('reports the pre-cap total and truncation from the shared retention pass', () => {
+    const meta = grepSearchMeta(retainGrepMatches([match('a.ts', 1, 'one'), match('a.ts', 2, 'two'), match('b.ts', 3, 'three')], 2, 2000), WIDE)
     expect(meta).toEqual({
-      kind: 'matches',
+      shape: 'matches',
       files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'one' }, { lineNumber: 2, line: 'two' }] }],
       truncated: true,
       total: 3,
     })
   })
 
-  it('applies the per-line preview budget (UTF-8 boundary) to the projected line', () => {
-    const meta = grepSearchMeta([match('a.txt', 1, 'aéaéaéaé')], 10, 7)
-    expect(meta).toMatchObject({ kind: 'matches', files: [{ path: 'a.txt', matches: [{ lineNumber: 1, line: 'aéaéa (line truncated)' }] }] })
+  it('carries the per-line preview budget (UTF-8 boundary) the retention pass applied', () => {
+    const meta = grepSearchMeta(retainGrepMatches([match('a.txt', 1, 'aéaéaéaé')], 10, 7), WIDE)
+    expect(meta).toMatchObject({ shape: 'matches', files: [{ path: 'a.txt', matches: [{ lineNumber: 1, line: 'aéaéa (line truncated)' }] }] })
+  })
+
+  it('drops trailing file groups until the serialized meta fits the byte cap, marking it truncated', () => {
+    const retained = retainGrepMatches(
+      [match('a.ts', 1, 'x'.repeat(60)), match('b.ts', 2, 'y'.repeat(60)), match('c.ts', 3, 'z'.repeat(60))],
+      10,
+      2000,
+    )
+    // One 60-byte group serializes to ~110 bytes; a 260-byte cap holds two, not three.
+    const meta = grepSearchMeta(retained, 260)
+    expect(meta.shape).toBe('matches')
+    if (meta.shape !== 'matches') throw new Error('unreachable')
+    expect(meta.truncated).toBe(true)
+    expect(meta.total).toBe(3)
+    expect(meta.files.length).toBeLessThan(3)
+    expect(Buffer.byteLength(JSON.stringify(meta), 'utf8')).toBeLessThanOrEqual(260)
+  })
+
+  it('keeps a single oversized group rather than emit an empty card', () => {
+    const meta = grepSearchMeta(retainGrepMatches([match('a.ts', 1, 'x'.repeat(500))], 10, 2000), 50)
+    expect(meta.shape).toBe('matches')
+    if (meta.shape !== 'matches') throw new Error('unreachable')
+    expect(meta.files).toHaveLength(1)
+    expect(meta.truncated).toBe(true)
   })
 })
 
 describe('globSearchMeta', () => {
   it('projects the path list with total and a false truncation flag within the cap', () => {
-    expect(globSearchMeta(['a.ts', 'b.ts'], 10)).toEqual({ kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: false, total: 2 })
+    expect(globSearchMeta(retainGlobPaths(['a.ts', 'b.ts'], 10), WIDE)).toEqual({ shape: 'paths', paths: ['a.ts', 'b.ts'], truncated: false, total: 2 })
   })
 
-  it('caps the retained paths and reports the pre-cap total when truncated', () => {
-    expect(globSearchMeta(['a.ts', 'b.ts', 'c.ts'], 2)).toEqual({ kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3 })
+  it('reports the pre-cap total and truncation from the shared retention pass', () => {
+    expect(globSearchMeta(retainGlobPaths(['a.ts', 'b.ts', 'c.ts'], 2), WIDE)).toEqual({ shape: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3 })
+  })
+
+  it('drops trailing paths until the serialized meta fits the byte cap, marking it truncated', () => {
+    const retained = retainGlobPaths([`${'a'.repeat(100)}.ts`, `${'b'.repeat(100)}.ts`, `${'c'.repeat(100)}.ts`], 10)
+    const meta = globSearchMeta(retained, 180)
+    expect(meta.shape).toBe('paths')
+    if (meta.shape !== 'paths') throw new Error('unreachable')
+    expect(meta.truncated).toBe(true)
+    expect(meta.total).toBe(3)
+    expect(meta.paths.length).toBeLessThan(3)
+    expect(Buffer.byteLength(JSON.stringify(meta), 'utf8')).toBeLessThanOrEqual(180)
   })
 })
 
@@ -80,15 +120,22 @@ describe('searchViewFromMeta (defensive narrowing)', () => {
   const m = (value: unknown): JsonValue | undefined => value as JsonValue | undefined
 
   it('narrows a well-formed matches payload into a matches view', () => {
-    const meta = { kind: 'matches', files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'x' }] }], truncated: true, total: 5 }
+    const meta = { shape: 'matches', files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'x' }] }], truncated: true, total: 5 }
     expect(searchViewFromMeta(m(meta))).toEqual({ card: 'search', ...meta })
   })
 
   it('narrows a well-formed paths payload into a paths view', () => {
-    const meta = { kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: false, total: 2 }
+    const meta = { shape: 'paths', paths: ['a.ts', 'b.ts'], truncated: false, total: 2 }
     expect(searchViewFromMeta(m(meta))).toEqual({ card: 'search', ...meta })
   })
 
+  it('narrows a zero-result payload into a valid empty card (not a rejected projection)', () => {
+    expect(searchViewFromMeta(m({ shape: 'matches', files: [], truncated: false, total: 0 })))
+      .toEqual({ card: 'search', shape: 'matches', files: [], truncated: false, total: 0 })
+    expect(searchViewFromMeta(m({ shape: 'paths', paths: [], truncated: false, total: 0 })))
+      .toEqual({ card: 'search', shape: 'paths', paths: [], truncated: false, total: 0 })
+  })
+
   it('rejects undefined / non-object / array meta', () => {
     expect(searchViewFromMeta(undefined)).toBeUndefined()
     expect(searchViewFromMeta(null)).toBeUndefined()
@@ -97,19 +144,19 @@ describe('searchViewFromMeta (defensive narrowing)', () => {
   })
 
   it('rejects a payload with a missing / mistyped truncated or total field', () => {
-    expect(searchViewFromMeta(m({ kind: 'paths', paths: [], total: 0 }))).toBeUndefined()
-    expect(searchViewFromMeta(m({ kind: 'paths', paths: [], truncated: 'no', total: 0 }))).toBeUndefined()
-    expect(searchViewFromMeta(m({ kind: 'paths', paths: [], truncated: false }))).toBeUndefined()
-    expect(searchViewFromMeta(m({ kind: 'paths', paths: [], truncated: false, total: '0' }))).toBeUndefined()
+    expect(searchViewFromMeta(m({ shape: 'paths', paths: [], total: 0 }))).toBeUndefined()
+    expect(searchViewFromMeta(m({ shape: 'paths', paths: [], truncated: 'no', total: 0 }))).toBeUndefined()
+    expect(searchViewFromMeta(m({ shape: 'paths', paths: [], truncated: false }))).toBeUndefined()
+    expect(searchViewFromMeta(m({ shape: 'paths', paths: [], truncated: false, total: '0' }))).toBeUndefined()
   })
 
-  it('rejects an unknown or missing kind discriminant', () => {
-    expect(searchViewFromMeta(m({ kind: 'other', truncated: false, total: 0 }))).toBeUndefined()
+  it('rejects an unknown or missing shape discriminant', () => {
+    expect(searchViewFromMeta(m({ shape: 'other', truncated: false, total: 0 }))).toBeUndefined()
     expect(searchViewFromMeta(m({ truncated: false, total: 0 }))).toBeUndefined()
   })
 
   it('rejects a matches payload with a malformed files array', () => {
-    const base = { kind: 'matches', truncated: false, total: 1 }
+    const base = { shape: 'matches', truncated: false, total: 1 }
     expect(searchViewFromMeta(m({ ...base, files: 'x' }))).toBeUndefined()
     expect(searchViewFromMeta(m({ ...base, files: [null] }))).toBeUndefined()
     expect(searchViewFromMeta(m({ ...base, files: ['x'] }))).toBeUndefined()
@@ -122,7 +169,7 @@ describe('searchViewFromMeta (defensive narrowing)', () => {
   })
 
   it('rejects a paths payload with a non-array or non-string-element paths field', () => {
-    const base = { kind: 'paths', truncated: false, total: 1 }
+    const base = { shape: 'paths', truncated: false, total: 1 }
     expect(searchViewFromMeta(m({ ...base, paths: 'x' }))).toBeUndefined()
     expect(searchViewFromMeta(m({ ...base, paths: [1] }))).toBeUndefined()
   })
diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts
index 6d55395e3a..3e761531ca 100644
--- a/packages/fs/tool-fs-search/tests/tools.spec.ts
+++ b/packages/fs/tool-fs-search/tests/tools.spec.ts
@@ -817,7 +817,7 @@ describe('presentation', () => {
     if (result.isError) throw new Error('expected grep success')
     // The presentationMeta projection rides the result meta (a surface call).
     expect(result.meta).toEqual({
-      kind: 'matches',
+      shape: 'matches',
       files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'one' }, { lineNumber: 2, line: 'two' }] }],
       truncated: true,
       total: 3,
@@ -825,11 +825,10 @@ describe('presentation', () => {
     const view = presentGrepResult({ pattern: 'e' }, result)
     expect(view).toEqual({
       card: 'search',
-      kind: 'matches',
+      shape: 'matches',
       files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'one' }, { lineNumber: 2, line: 'two' }] }],
       truncated: true,
       total: 3,
-      content: result.content,
     })
   })
 
@@ -838,9 +837,9 @@ describe('presentation', () => {
     bash.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({ kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3 })
+    expect(result.meta).toEqual({ shape: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3 })
     const view = presentGlobResult({ pattern: '*.ts' }, result)
-    expect(view).toEqual({ card: 'search', kind: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3, content: result.content })
+    expect(view).toEqual({ card: 'search', shape: 'paths', paths: ['a.ts', 'b.ts'], truncated: true, total: 3 })
   })
 
   it('nested Code dispatch computes no meta, so presentResult falls back to the generic card', async () => {
@@ -860,15 +859,15 @@ describe('presentation', () => {
     expect(presentGrepResult({ pattern: 'x' }, errorResult)).toBeUndefined()
     expect(presentGlobResult({ pattern: '*' }, errorResult)).toBeUndefined()
     // A grep result carrying a paths-shaped meta (and vice versa) is not this
-    // tool's shape: each presenter narrows to its own kind and otherwise falls back.
-    const pathsResult = { content: [], isError: false, meta: { kind: 'paths', paths: ['a.ts'], truncated: false, total: 1 } }
-    const matchesResult = { content: [], isError: false, meta: { kind: 'matches', files: [], truncated: false, total: 0 } }
+    // tool's shape: each presenter narrows to its own shape and otherwise falls back.
+    const pathsResult = { content: [], isError: false, meta: { shape: 'paths', paths: ['a.ts'], truncated: false, total: 1 } }
+    const matchesResult = { content: [], isError: false, meta: { shape: 'matches', files: [], truncated: false, total: 0 } }
     expect(presentGrepResult({ pattern: 'x' }, pathsResult)).toBeUndefined()
     expect(presentGlobResult({ pattern: '*' }, matchesResult)).toBeUndefined()
   })
 
   it('presentResult falls back to the generic card on malformed replayed meta', () => {
-    const malformed = { content: [], isError: false, meta: { kind: 'matches', files: 'nope', truncated: false, total: 0 } }
+    const malformed = { content: [], isError: false, meta: { shape: 'matches', files: 'nope', truncated: false, total: 0 } }
     expect(presentGrepResult({ pattern: 'x' }, malformed)).toBeUndefined()
     expect(presentGlobResult({ pattern: '*' }, { content: [], isError: false, meta: 42 })).toBeUndefined()
   })
diff --git a/packages/ui/tui/src/components/transcript.ts b/packages/ui/tui/src/components/transcript.ts
index 58d3d6a178..77c1eb36af 100644
--- a/packages/ui/tui/src/components/transcript.ts
+++ b/packages/ui/tui/src/components/transcript.ts
@@ -389,7 +389,15 @@ export class ToolCardComponent implements Component {
     const glyph = this.result === undefined ? '○' : '●'
     const rawBody = this.renderBody()
     const view = this.resultView ?? this.callView
-    const genericContent = view.card === 'generic' ? view.content ?? this.result?.content : undefined
+    // A search card (grep/glob results) carries no dedicated TUI rendering and no
+    // result text of its own: it falls back to the same dim Markdown body as a
+    // generic card, reading the model-facing text from the raw result content.
+    // Its structured shape is consumed by capable UIs; the TUI stays
+    // byte-identical to the pre-search-card generic fallback. Terminal and diff
+    // cards keep their own body branches.
+    const genericContent = view.card === 'generic'
+      ? view.content ?? this.result?.content
+      : view.card === 'search' ? this.result?.content : undefined
     const unknownXml = this.definition === undefined && genericContent !== undefined
       ? renderUnknownXml(
         displayText(contentText(genericContent)),
@@ -502,7 +510,10 @@ export class ToolCardComponent implements Component {
       // rather than under the dim result-output color.
       return { prelude: [...hunks, footer], lines: [] }
     }
-    const content = view.content ?? this.result?.content
+    // A search card carries no result text of its own; only a generic view
+    // supplies `content`. Both fall back to the raw result content below.
+    const viewContent = view.card === 'generic' ? view.content : undefined
+    const content = viewContent ?? this.result?.content
     const prelude: string[] = []
     const lines: string[] = []
     // The presenter title headlines the body now that the header is a fixed

From 168ec609ed7b790e5b46c09005046799171b62c0 Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 21:58:25 +0800
Subject: [PATCH 10/43] docs: regenerate config catalog after master merge

---
 docs/config-catalog.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 9cd60493b8..36aea0db08 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1690,7 +1690,7 @@ export interface Config {
   grepMaxMatches?: number
   /** Max bytes retained for one matched-line preview (the cut preserves UTF-8 boundaries). */
   grepMaxLineBytes?: number
-  /** Max bytes of one search's serialized `presentationMeta`; trailing groups/paths drop past it so the persisted, re-sent card stays bounded. */
+  /** Max bytes of one search's serialized `presentationMeta`; trailing groups/paths drop past it so the persisted card stays bounded. */
   searchMetaMaxBytes?: number
   /** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
   rawOutputMaxBytes?: number

From bef8db3addac9b9cd28a069c39a56ab9d68a1089 Mon Sep 17 00:00:00 2001
From: NI0317 
Date: Thu, 30 Jul 2026 22:17:56 +0800
Subject: [PATCH 11/43] feat(web): add versioned first-run welcome

---
 ...seek-onboarding-credential-setup.i18n.yaml |   4 +-
 ...30-deepseek-onboarding-credential-setup.md |   6 +-
 ...deepseek-onboarding-credential-setup.zh.md |   6 +-
 ...versioned-gui-welcome-onboarding.i18n.yaml |   6 +
 ...-07-30-versioned-gui-welcome-onboarding.md |  35 ++++
 ...-30-versioned-gui-welcome-onboarding.zh.md |  35 ++++
 .../tests/onboarding-deepseek-config.e2e.ts   |  74 +++++++-
 .../welcome.expected.md                       |   6 +
 docs/event-producer-consumer.md               |   4 +-
 docs/module-graph.md                          |   4 +-
 packages/client/connection/src/index.ts       |   1 +
 .../client/connection/tests/node-half.spec.ts |   4 +-
 packages/client/ui-models/README.i18n.yaml    |   4 +-
 packages/client/ui-models/README.md           |   4 +-
 packages/client/ui-models/README.zh.md        |   4 +-
 .../src/client/DeepSeekOnboardingDialog.tsx   |  21 +--
 .../tests/onboarding-dialog.spec.tsx          |  21 +--
 .../ui-settings-general/README.i18n.yaml      |   6 +-
 packages/client/ui-settings-general/README.md |   4 +-
 .../client/ui-settings-general/README.zh.md   |   4 +-
 .../client/ui-settings-general/package.json   |  13 +-
 .../src/client/WelcomeNotice.module.css       |  70 ++++++++
 .../src/client/WelcomeNotice.tsx              |  69 ++++++++
 .../ui-settings-general/src/client/index.ts   |  41 ++++-
 .../ui-settings-general/src/client/locales.ts |  13 ++
 .../src/client/welcome-store.ts               | 108 ++++++++++++
 .../client/ui-settings-general/src/index.ts   |  31 +++-
 .../ui-settings-general/src/invariant.ts      |   7 +-
 .../src/onboarding-copy.ts                    |  33 ++++
 .../ui-settings-general/tests/apply.spec.ts   |  47 ++++-
 .../ui-settings-general/tests/host.spec.ts    |  29 +++
 .../tests/invariant.spec.ts                   |   6 -
 .../tests/welcome-notice.spec.tsx             | 101 +++++++++++
 .../tests/welcome-store.spec.ts               | 166 ++++++++++++++++++
 .../client/ui-settings-general/tsconfig.json  |   9 +
 packages/client/ui-settings/README.i18n.yaml  |   4 +-
 packages/client/ui-settings/README.md         |   4 +-
 packages/client/ui-settings/README.zh.md      |   4 +-
 .../ui-settings/src/client/SettingsRoot.tsx   |  29 ++-
 .../ui-settings/src/client/contract/slots.ts  |  24 ++-
 .../client/ui-settings/src/client/index.ts    |  26 ++-
 .../client/ui-settings/tests/apply.spec.ts    |  23 +++
 .../ui-settings/tests/settings-root.spec.tsx  |  32 +++-
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |   2 +-
 packages/host/apiproxy/README.zh.md           |   2 +-
 packages/host/apiproxy/src/api-proxy.ts       |  31 ++--
 .../apiproxy/tests/api-proxy-config.spec.ts   |  17 +-
 pnpm-lock.yaml                                |  13 ++
 49 files changed, 1096 insertions(+), 115 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md
 create mode 100644 .agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md
 create mode 100644 apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md
 create mode 100644 packages/client/ui-settings-general/src/client/WelcomeNotice.module.css
 create mode 100644 packages/client/ui-settings-general/src/client/WelcomeNotice.tsx
 create mode 100644 packages/client/ui-settings-general/src/client/welcome-store.ts
 create mode 100644 packages/client/ui-settings-general/src/onboarding-copy.ts
 create mode 100644 packages/client/ui-settings-general/tests/host.spec.ts
 create mode 100644 packages/client/ui-settings-general/tests/welcome-notice.spec.tsx
 create mode 100644 packages/client/ui-settings-general/tests/welcome-store.spec.ts

diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
index 8beabfa66e..47ce2b206e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.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-30-deepseek-onboarding-credential-setup.md
-2026-07-30-deepseek-onboarding-credential-setup.md: 3f75a0893623afc0908cb48f2b838321ed9dedd3
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: 62f8f0b99f167b22051aaddf7331a043bd2ea812
+2026-07-30-deepseek-onboarding-credential-setup.md: 253800b7d94c80f1809c211ad0b3788b4ae4e07c
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: 2dd4de8185d0b6c8c33ad381a1b1aa358b07e872
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
index 3f75a08936..253800b7d9 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
@@ -12,11 +12,11 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 **One readiness projection owns both Models and onboarding facts.** `ui-models` keeps a single store that joins `llm.providers({})`, redacted `settings.describe({})`, and batched `credentials.describe({refs})`. The onboarding projection selects the `deepseek-official` configurable-provider entry, resolves its `settingsNs` and `settingsPath`, reads the effective `apiKeyEnv`, and evaluates the matching credential descriptor. A configured literal `apiKey` secret sidecar is also ready, so compatibility configuration does not trigger a false prompt; a configured process-environment credential is ready and remains read-only.
 
-**The settings shell contributes navigation state, not provider policy.** `ui-settings` declares a root-scoped `settings.onboarding` list slot and tells registrants whether the current surface is the empty Hero. Its private `openSection(id)` callback opens the settings panel on one registered section. `ui-models` registers the DeepSeek overlay through the same declaration-aware deferred-registration path as its Models section, so plugin load order does not become a contract.
+**The settings shell contributes ordering and navigation, not provider policy.** `ui-settings` declares a root-scoped `settings.onboarding` list slot and mounts one ordered step at a time while the current surface is the empty Hero. The active registrant receives `complete()` and a private `openSection(id)` callback; completion transfers ownership to the next entry. `ui-models` registers the DeepSeek step through the same declaration-aware deferred-registration path as its Models section, so plugin load order does not become a contract and independently contributed dialogs cannot stack. The product-wide welcome step that precedes it is owned separately by [the versioned welcome decision](2026-07-30-versioned-gui-welcome-onboarding.md).
 
 **The prompt routes to the one credential editor.** A mounted, active adapter with a resolved, writable, unconfigured reference presents one action that opens Settings on Models. The existing DeepSeek setup card there exclusively owns the password input, `credentials.set({ref, value})`, write failures, and post-write refresh; the onboarding overlay never holds or submits a secret. An unavailable settings or credential capability keeps its deployment diagnostic and routes to the same page, while an absent adapter remains skipped because navigation cannot mount a Cordis plugin.
 
-**Unavailable states stay honest.** An absent configurable-provider entry suppresses the prompt because navigation cannot repair the composition. A present provider whose settings or credential capability cannot be resolved renders an actionable deployment diagnostic; a failed initial join names the connection problem and leads to the Models retry surface. Configure later dismisses the overlay for the current mounted surface and writes no completion fact. Settings, credential, provider-topology, and connection invalidations all refresh the shared join, so an external credential update closes an open prompt without a reload.
+**Unavailable states stay honest.** An absent configurable-provider entry completes the step because navigation cannot repair the composition. A present provider whose settings or credential capability cannot be resolved renders an actionable deployment diagnostic; a failed initial join names the connection problem and leads to the Models retry surface. Configure later completes only this mounted coordinator pass and writes no completion fact. Settings, credential, provider-topology, and connection invalidations all refresh the shared join, so an external credential update completes an open step without a reload.
 
 ## Alternatives considered
 
@@ -30,4 +30,4 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 ## Consequences
 
-The first-run flow now leads to the shipped adapter's existing editor without restarting: a keyless browser test boots the real Web composition under an isolated harness home, follows the prompt to Models, stores a generated key through that page into the home's `.env`, verifies no key reaches DOM, ARIA, or browser console output, and confirms the running page reports configured. Pure readiness and React tests pin literal, file, process-environment, missing-provider, missing-capability, navigation, cancellation, and external-invalidation behavior. The flow deliberately inherits the configuration plane's documented base limitations rather than adding local secret storage, redaction, or settings replacement workarounds.
+The ordered flow leads from the product welcome step to the shipped adapter's existing editor without restarting: a keyless browser test boots the real Web composition under an isolated harness home, acknowledges the welcome notice, follows the DeepSeek step to Models, stores a generated key through that page into the home's `.env`, verifies no key reaches DOM, ARIA, or browser console output, and confirms the running page reports configured. Pure readiness and React tests pin literal, file, process-environment, missing-provider, missing-capability, navigation, cancellation, external-invalidation, and coordinator-transfer behavior. The flow deliberately inherits the configuration plane's documented base limitations rather than adding local secret storage, redaction, or settings replacement workarounds.
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
index 62f8f0b99f..2dd4de8185 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -12,11 +12,11 @@ Status: implemented
 
 **Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store,把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取 `deepseek-official` 可配置提供方条目,解析其 `settingsNs` 与 `settingsPath`,读取生效的 `apiKeyEnv`,并检查对应的凭据描述符。若 `apiKey` 字面量对应的 secret 槽位标记为已设置,也会判定为就绪,兼容配置因此不会误触发浮层;通过进程环境提供的凭据若已配置,同样判定为就绪并保持只读。
 
-**设置外壳只贡献导航状态,不持有提供方策略。**`ui-settings` 声明一个根作用域的 `settings.onboarding` list slot,并告知注册方当前界面是否为空白 Hero。其私有 `openSection(id)` 回调会打开设置面板并切换到一个已注册分区。`ui-models` 沿用 Models 分区所使用、感知 slot 声明的延迟注册路径来注册 DeepSeek 浮层,因此插件加载顺序不会成为契约。
+**设置外壳只贡献排序与导航,不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot,并在当前界面为空白 Hero 时,每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调;完成当前步骤后,所有权转交给下一项。`ui-models` 沿用 Models 分区所使用、感知 slot 声明的延迟注册路径来注册 DeepSeek 步骤,因此插件加载顺序不会成为契约,独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
 
 **浮层只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态,其引用可解析、可写但尚未配置时,界面会显示一个操作按钮,用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新;首次使用浮层绝不持有或提交 secret。设置或凭据能力不可用时会保留部署诊断,并提供前往同一页面的入口;适配器缺失时仍直接跳过,因为导航无法挂载 Cordis 插件。
 
-**不可用状态如实呈现。**可配置提供方条目缺失时不显示浮层,因为导航无法修复当前组合。提供方存在,但设置或凭据能力无法解析时,界面会显示可采取操作的部署诊断;初始联接失败时会明确指出连接问题,并引导前往 Models 的重试界面。「稍后配置」只会在当前已挂载界面中关闭浮层,不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接,因此外部凭据更新无需重新加载页面即可关闭已打开的浮层。
+**不可用状态如实呈现。** 可配置提供方条目缺失时会完成当前步骤,因为导航无法修复当前组合。提供方存在,但设置或凭据能力无法解析时,界面会显示可采取操作的部署诊断;初始联接失败时会明确指出连接问题,并引导前往 Models 的重试界面。「稍后配置」只会完成协调器当前这一次挂载流程,不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接,因此外部凭据更新无需重新加载页面即可完成已打开的步骤。
 
 ## 曾考虑的替代方案
 
@@ -30,4 +30,4 @@ Status: implemented
 
 ## 后果
 
-首次使用流程现在无需重启即可引导用户前往随产品提供的适配器已有的编辑器:无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合,依照浮层操作前往 Models,通过该页面把生成的密钥存入该目录的 `.env`,验证密钥未进入 DOM、ARIA 或浏览器控制台输出,并确认运行中的页面报告已配置。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消和外部失效行为。该流程直接继承配置平面已记录的基础限制,不会另加局部的机密存储、脱敏或设置替换变通方案。
+有序流程从产品欢迎步骤开始,无需重启即可引导用户前往随产品提供的适配器已有的编辑器:无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合,确认欢迎通知后依照 DeepSeek 步骤前往 Models,通过该页面把生成的密钥存入该目录的 `.env`,验证密钥未进入 DOM、ARIA 或浏览器控制台输出,并确认运行中的页面报告已配置。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消、外部失效和协调器移交行为。该流程直接继承配置平面已记录的基础限制,不会另加局部的机密存储、脱敏或设置替换变通方案。
diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml
new file mode 100644
index 0000000000..24bdee3b68
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md
+2026-07-30-versioned-gui-welcome-onboarding.md: 405c6fe833d995123cd15e5694cd5ef75a0cd03d
+2026-07-30-versioned-gui-welcome-onboarding.zh.md: ea83aa958866ab3dcca749f362d43e4b29408e02
diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md
new file mode 100644
index 0000000000..405c6fe833
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md
@@ -0,0 +1,35 @@
+# Agent Note: Versioned GUI welcome onboarding
+
+Status: implemented
+
+English | [中文](2026-07-30-versioned-gui-welcome-onboarding.zh.md)
+
+## Problem
+
+The GUI's credential onboarding begins with a DeepSeek-specific readiness check, but the internal-test notice applies to every user and must precede provider setup even when a credential is already configured. Treating both as independent overlays permits simultaneous dialogs, while a process-local dismissal cannot distinguish a completed notice from a window closed before acknowledgement or intentionally present revised copy once.
+
+## Decision
+
+**The Settings shell coordinates ordered steps.** `settings.onboarding` remains a root-scoped list, but `ui-settings` projects its entry ids and order into one coordinator and mounts only the first incomplete step. The active registrant receives `complete()` and `openSection(id)`; no later step mounts until ownership transfers. The product welcome registers at order `-100`, while `ui-models` retains only the conditional DeepSeek readiness and credential-routing step at order `0`.
+
+**Ownerless product onboarding belongs to `ui-settings-general`.** `src/onboarding-copy.ts` is the single editable source for the complete Chinese notice, its faithful English counterpart, the Continue labels, and `WELCOME_NOTICE_VERSION`. Runtime locale dictionaries derive their welcome values from that file, and tests import the same owner instead of repeating paragraph text. The notice is browser UI only: it creates no Session event and contributes no model-visible content.
+
+**Acknowledgement is durable per Harness profile.** The Host half registers a `ui-onboarding` section in the user-settings seam, stored under the active `$DSH_HOME/settings.yaml`. The browser shows the notice unless `welcomeNoticeVersion` equals the owner constant exactly. Continue applies one path mutation with the current version and calls `complete()` only after the Host commits it; a failed write leaves the notice open, and closing the page or process writes nothing. Bumping the constant intentionally makes every profile acknowledge the revised copy once.
+
+**Concurrent views converge without stale replacement.** The acknowledgement write omits `expectedRevision` deliberately: every tab writes the same version to one path, so the operation is idempotent and preserves sibling fields instead of rebuilding the section. `settings/document-updated` becomes `host/settings-changed`; an already mounted tab refetches and advances when another tab or an external editor commits the current version. The API proxy exposes this one product namespace through a closed allowlist beside configurable-provider namespaces, without treating its changes as model-catalog invalidations.
+
+**The welcome modal has one completion path.** It renders no close icon or secondary action, installs no Escape handler, and assigns no click handler to the mask. Its mask starts below the 80 px top chrome and preserves `position:absolute`, zero left/right/bottom offsets, `rgba(0, 0, 0, 0.24)`, and `backdrop-filter: blur(2px)`. Continue is the sole button and receives initial focus.
+
+## Alternatives considered
+
+**Browser local storage** — rejected because acknowledgement would follow one browser profile rather than `$DSH_HOME`; a fresh Harness profile could incorrectly inherit a prior acknowledgement, and external profile edits would have no authoritative update stream.
+
+**A second independent modal in `ui-settings-general`** — rejected because list registrants would still stack whenever welcome and credential readiness were both true. Ordered ownership belongs to the shell that declares and renders the list.
+
+**Persisting on render or window close** — rejected because observation is not acknowledgement and close delivery is unreliable. Only the explicit Continue commit may suppress the next launch.
+
+**A generic public settings-exposure flag** — rejected because one product namespace does not justify widening every settings registrant's public configuration surface. The gateway keeps an explicit closed allowlist.
+
+## Consequences
+
+A fresh profile always sees the welcome notice before provider-specific onboarding; an already configured credential skips only the later DeepSeek step. Reloading after Continue stays past the acknowledged version, changing the owner version presents it again, and closing before Continue leaves the next launch unchanged. Focused store and React tests pin exact-version comparison, write failure, sole-action behavior, no-dismiss paths, coordinator ordering, conditional DeepSeek transfer, and HMR cleanup. The real Chromium scenario boots the shipped Web composition with an isolated harness home, verifies the exact mask geometry and computed styles, reloads before and after acknowledgement, continues into missing-credential setup, confirms an acknowledged-version mismatch returns while the credential is configured, and checks the browser console.
diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md
new file mode 100644
index 0000000000..ea83aa9588
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 版本化 GUI 欢迎引导
+
+Status: implemented
+
+[English](2026-07-30-versioned-gui-welcome-onboarding.md) | 中文
+
+## 问题
+
+GUI 的凭据引导从 DeepSeek 专用的就绪状态检查开始,但内部测试通知适用于每位用户,即使凭据已经配置,也必须先于提供方设置显示。若把两者作为独立浮层处理,多个对话框可能同时出现;仅存于进程内的关闭标记既无法区分通知已完成确认还是窗口在确认前已关闭,也无法在文案有意修订后重新显示一次通知。
+
+## 决策
+
+**设置外壳协调有序步骤。** `settings.onboarding` 仍是根作用域 list,但 `ui-settings` 会把其中各条目的 id 和顺序投影到一个协调器中,并且只挂载第一个未完成的步骤。当前注册方会收到 `complete()` 和 `openSection(id)`;所有权转移前,不会挂载后续步骤。产品欢迎步骤的顺序为 `-100`,`ui-models` 则只保留顺序为 `0` 的 DeepSeek 条件式就绪状态与凭据跳转步骤。
+
+**不属于单一功能的产品引导由 `ui-settings-general` 持有。** `src/onboarding-copy.ts` 是完整中文通知、忠实英文对侧文案、两种语言的「继续」按钮文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源。运行时 locale 字典从该文件派生欢迎文案,测试也导入同一个所有者,而不重复段落文本。该通知只存在于浏览器 UI:它不会创建会话事件,也不会贡献任何模型可见内容。
+
+**确认状态按 Harness profile 持久化。** 宿主端在 user-settings seam 中注册 `ui-onboarding` 分节,并存入当前 `$DSH_HOME/settings.yaml`。除非 `welcomeNoticeVersion` 与文案所有者文件中的常量精确相等,否则浏览器会显示通知。「继续」会以当前版本执行一次路径变更,并且仅在宿主端提交成功后调用 `complete()`;写入失败时通知保持打开,关闭页面或进程则不会写入任何内容。提升该常量会有意要求每个 profile 对修订后的文案重新确认一次。
+
+**并发视图无需陈旧的整体替换即可收敛。** 确认写入有意省略 `expectedRevision`:每个标签页都向同一路径写入相同版本,因此该操作是幂等的,并会保留同级字段,而不是重建整个分节。`settings/document-updated` 会转为 `host/settings-changed`;另一个标签页或外部编辑器提交当前版本后,已挂载的标签页会重新拉取状态并推进。API 网关在可配置提供方 namespace 之外,通过封闭的允许列表暴露这一个产品 namespace,同时不会把它的变更视为模型目录失效事件。
+
+**欢迎模态窗口只有一条完成路径。** 界面不渲染关闭图标或次要操作,不安装 Escape 处理器,也不为遮罩添加点击处理器。遮罩从顶部 80 px 的界面框架下方开始,并保留 `position:absolute`、left/right/bottom 偏移量为零、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。「继续」是唯一按钮,并会获得初始焦点。
+
+## 曾考虑的替代方案
+
+**浏览器本地存储**:不予采用,因为确认状态会跟随某个浏览器 profile,而不是 `$DSH_HOME`;全新的 Harness profile 可能错误继承此前的确认状态,外部 profile 编辑也没有权威更新流。
+
+**在 `ui-settings-general` 中再增加一个独立模态窗口**:不予采用,因为欢迎通知和凭据就绪状态同时为真时,list 注册方仍会堆叠。声明并渲染该 list 的外壳应当持有有序所有权。
+
+**在渲染或窗口关闭时持久化**:不予采用,因为看见通知不等于确认,窗口关闭事件也无法可靠送达。只有显式提交「继续」才能阻止通知在下次启动时再次显示。
+
+**通用的公开设置暴露标志**:不予采用,因为一个产品 namespace 不足以证明应当扩大每个 settings 注册方的公开配置面。网关保留显式的封闭允许列表。
+
+## 后果
+
+全新 profile 始终会在提供方专用引导之前看到欢迎通知;凭据已经配置时,只会跳过后续 DeepSeek 步骤。点击「继续」后重新加载不会再次显示已确认版本,更改文案所有者文件中的版本值会让通知重新出现,而确认前关闭窗口不会改变下次启动。针对性的 store 与 React 测试固化了精确版本比较、写入失败、单一操作、不可关闭路径、协调器顺序、按条件移交 DeepSeek 步骤和 HMR(热模块替换)清理行为。真实 Chromium 场景会使用隔离的 harness 家目录启动随产品提供的 Web 组合,验证遮罩的精确几何尺寸和计算样式,在确认前后分别重新加载,继续进入凭据缺失设置流程,确认凭据已配置时确认版本不匹配仍会使通知重新出现,并检查浏览器控制台。
diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts
index 62dd129982..f372910a61 100644
--- a/apps/web/tests/onboarding-deepseek-config.e2e.ts
+++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts
@@ -9,12 +9,18 @@ import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import {
-  assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
   launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import { saveFailureShot } from './support.ts'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import {
+  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_COPY, WELCOME_NOTICE_SETTINGS_NAMESPACE,
+  WELCOME_NOTICE_VERSION,
+} from '@deepseek-ai/dsh-client-ui-settings-general'
 
 const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/onboarding-deepseek-config', import.meta.url))
+const WELCOME_EXPECTED = join(SNAPSHOT_DIR, 'welcome.expected.md')
 const MISSING_EXPECTED = join(SNAPSHOT_DIR, 'missing.expected.md')
 const MODE = webSnapshotMode()
 
@@ -42,6 +48,47 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
 
   it('stores a key write-only and observes configured state without restarting', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-onboarding-deepseek-config'))
+    const welcome = page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.paragraphs[0] })
+    await welcome.waitFor({ timeout: 15_000 })
+    const welcomeAria = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(WELCOME_EXPECTED, welcomeAria, MODE)
+    expect(await welcome.getByRole('button').allTextContents()).toEqual([WELCOME_NOTICE_COPY.zh.continueLabel])
+    expect(await welcome.locator('button').count()).toBe(1)
+
+    const maskStyles = await welcome.locator('xpath=..').locator(':scope > div').first().evaluate((mask) => {
+      const style = getComputedStyle(mask)
+      const rect = mask.getBoundingClientRect()
+      return {
+        position: style.position,
+        left: style.left,
+        right: style.right,
+        top: style.top,
+        bottom: style.bottom,
+        background: style.backgroundColor,
+        backdropFilter: style.backdropFilter,
+        rect: { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom },
+      }
+    })
+    expect(maskStyles).toEqual({
+      position: 'absolute',
+      left: '0px',
+      right: '0px',
+      top: '80px',
+      bottom: '0px',
+      background: 'rgba(0, 0, 0, 0.24)',
+      backdropFilter: 'blur(2px)',
+      rect: { left: 0, top: 80, right: 1440, bottom: 960 },
+    })
+
+    // Closing the process/page before acknowledgement writes nothing, so the
+    // same durable profile presents the notice again after reload.
+    const firstReloadWarnings = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    acknowledgeReloadConnectionLoss(tripwire, firstReloadWarnings)
+    await welcome.waitFor({ timeout: 15_000 })
+
+    await welcome.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }).click()
+    await welcome.waitFor({ state: 'detached', timeout: 15_000 })
     const dialog = page.getByRole('dialog', { name: '添加一个 API Key 开始使用' })
     await dialog.waitFor({ timeout: 15_000 })
     expect(await dialog.getByRole('textbox').count()).toBe(0)
@@ -78,6 +125,29 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
       { timeout: 10_000 },
     ).toBe('已配置——输入新值可替换')
 
+    const acknowledgedSettings = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
+    expect(acknowledgedSettings).toContain(`${WELCOME_NOTICE_ACK_FIELD}: ${WELCOME_NOTICE_VERSION}`)
+
+    const secondReloadWarnings = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    acknowledgeReloadConnectionLoss(tripwire, secondReloadWarnings)
+    await page.waitForSelector('[class*="frame"]', { timeout: 15_000 })
+    expect(await page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.paragraphs[0] }).count()).toBe(0)
+    expect(await page.getByRole('dialog', { name: '添加一个 API Key 开始使用' }).count()).toBe(0)
+
+    // A different stored copy version represents an intentional version bump:
+    // the welcome step returns even though the credential is already ready.
+    await scaffold.ctx.settings.mutate(settingsNamespace(WELCOME_NOTICE_SETTINGS_NAMESPACE), [{
+      op: 'set', path: [WELCOME_NOTICE_ACK_FIELD], value: 'previous-copy-version',
+    }])
+    const thirdReloadWarnings = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    acknowledgeReloadConnectionLoss(tripwire, thirdReloadWarnings)
+    await welcome.waitFor({ timeout: 15_000 })
+    await welcome.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }).click()
+    await welcome.waitFor({ state: 'detached', timeout: 15_000 })
+    expect(await page.getByRole('dialog', { name: '添加一个 API Key 开始使用' }).count()).toBe(0)
+
     expect((await page.content()).includes(secret)).toBe(false)
     expect((await page.locator('body').ariaSnapshot()).includes(secret)).toBe(false)
     expect(browserConsole.some(line => line.includes(secret))).toBe(false)
@@ -86,6 +156,6 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
   }, 60_000)
 
   it('keeps the fixture inventory closed', async () => {
-    await assertFixtureInventory(SNAPSHOT_DIR, ['missing.expected.md'])
+    await assertFixtureInventory(SNAPSHOT_DIR, ['missing.expected.md', 'welcome.expected.md'])
   })
 })
diff --git a/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md b/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md
new file mode 100644
index 0000000000..370737df6b
--- /dev/null
+++ b/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md
@@ -0,0 +1,6 @@
+- dialog "感谢您愿意拨冗试用 DeepSeek Harness。":
+  - heading "感谢您愿意拨冗试用 DeepSeek Harness。" [level=2]
+  - paragraph: 目前的版本仍处于内部测试阶段,有些功能仍待完善,有些体验难免粗粝。
+  - paragraph: “如切如磋,如琢如磨。” 产品的成长,离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中暴露的问题,也可能促使我们重新审视,甚至推翻已有的设计。
+  - paragraph: 我们尤其希望听见那些失败、困惑与不顺手的时刻——如果它未能帮到您,甚至反而为工作平添了麻烦,请在企业微信群中留言,将使用感受告诉我们。每一条反馈,都会帮助我们把它打磨得更好。
+  - button "继续"
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 14da68499b..4690a0ca2d 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -66,14 +66,14 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | Event string | Dispatchers | Listeners |
 | --- | --- | --- |
 | `commands/changed` | `runtime` (`emit`) | `ui-command` |
-| `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models` |
+| `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-settings-general` |
 | `credentials/changed` | `runtime` (`emit`) | `ui-models` |
 | `internal/dispatch` | - | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
 | `internal/plugin` | - | `hmr`, `loader`, `modules`, `webserver` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
 | `locale/change` | `locale` (`emit`) | `locale`, `ui-models`, `ui-settings-general` |
 | `models/changed` | `runtime` (`emit`) | `ui-models` |
-| `settings/changed` | `runtime` (`emit`) | `ui-models` |
+| `settings/changed` | `runtime` (`emit`) | `ui-models`, `ui-settings-general` |
 | `slash/input-begin-command` | - | `ui-conversation` |
 | `slash/input-consume-token` | - | `ui-conversation` |
 | `slash/input-insert-reference` | - | `ui-conversation` |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 5827cf458d..602dff45c4 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -367,11 +367,13 @@ flowchart TD
   pkg_client_ui_models --> pkg_invariants
   pkg_client_ui_question --> pkg_client_locale
   pkg_client_ui_question --> pkg_invariants
+  pkg_client_ui_settings_general --> pkg_client_connection
   pkg_client_ui_settings_general --> pkg_client_locale
   pkg_client_ui_settings_general --> pkg_client_runtime
   pkg_client_ui_settings_general --> pkg_client_ui_primitives
   pkg_client_ui_settings_general --> pkg_client_ui_settings
   pkg_client_ui_settings_general --> pkg_client_ui_slots
+  pkg_client_ui_settings_general --> pkg_client_web_react
   pkg_client_ui_settings_general --> pkg_invariants
   pkg_client_ui_sidebar --> pkg_client_locale
   pkg_client_ui_sidebar --> pkg_client_runtime
@@ -1067,7 +1069,7 @@ flowchart TD
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
-| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
index cedc7d86e7..ed4af2d21f 100644
--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -54,6 +54,7 @@ const PRIVILEGED_METHODS = new Set([
   'settings.describe',
   'settings.update',
   'settings.replace',
+  'settings.mutate',
   'credentials.describe',
   'credentials.set',
   'credentials.unset',
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
index 6839d8b3ca..4910ba990c 100644
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -107,7 +107,7 @@ describe('connection node half', () => {
     // passed), but each privileged method stays loopback-only and 403s.
     for (const method of [
       'host.pickDirectory', 'host.openPath',
-      'settings.describe', 'settings.update', 'settings.replace',
+      'settings.describe', 'settings.update', 'settings.replace', 'settings.mutate',
       'credentials.describe', 'credentials.set', 'credentials.unset',
     ]) {
       const denied = fakeResponse()
@@ -191,7 +191,7 @@ describe('connection node half over a real HTTP server', () => {
       // Reads are as privileged as writes: describe returns the exposed
       // configuration, and credentials.describe probes arbitrary env-var names.
       for (const method of [
-        'settings.describe', 'settings.update', 'settings.replace',
+        'settings.describe', 'settings.update', 'settings.replace', 'settings.mutate',
         'credentials.describe', 'credentials.set', 'credentials.unset',
         'host.pickDirectory', 'host.openPath',
       ]) {
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 0355080b11..3bc6c94ec4 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-models/README.md
-README.md: aac437a13f6465196fcf1f8908b1d9ea2ccef401
-README.zh.md: 468537ac217a46395f2ec78174efa1f5d75a679d
+README.md: 2f53024df95a79862d5461d3514987a6e8257f9d
+README.zh.md: 7c95709933fa29a8fd6ed773696e9657d959f753
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index aac437a13f..2f53024df9 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-Models settings plugin: the provider configuration page and official-DeepSeek first-run routing overlay. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time.
+Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time.
 
 Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), plus `reasoningEffort` (deepseek) or `reasoning` (pi-ai); every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base).
 
-The first-run overlay projects `deepseek-official` readiness from that same joined snapshot. A configured literal `apiKey` secret sidecar or configured credential reference suppresses the prompt, including a read-only launch-environment credential. A mounted adapter with a missing writable reference shows one action that opens Settings on the Models section, whose existing setup card exclusively owns key input and `credentials.set`; the overlay never holds a secret. An absent adapter is skipped because browser navigation cannot mount Cordis plugins, while an unusable settings or credential capability produces a deployment diagnostic with the same route to Models.
+The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding steps complete. A configured literal `apiKey` secret sidecar or configured credential reference completes the step without rendering, including a read-only launch-environment credential. A mounted adapter with a missing writable reference shows one action that opens Settings on the Models section, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter is skipped because browser navigation cannot mount Cordis plugins, while an unusable settings or credential capability produces a deployment diagnostic with the same route to Models.
 
 Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index 468537ac21..7c95709933 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-模型设置插件:提供方配置页和 DeepSeek 官方首次使用跳转浮层。它把三个协议领域汇聚为一个共享快照:`llm.providers`(可配置提供方目录,含每条路由的存活/休眠状态)、`settings.describe`(序列化 schema、分层脱敏值、secret 槽位)与 `credentials.describe`(不含值的 configured/source/writable 徽标);页面据此渲染提供方行,一次只展开一张编辑卡片。
+模型设置插件:提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照:`llm.providers`(可配置提供方目录,含每条路由的存活/休眠状态)、`settings.describe`(序列化 schema、分层脱敏值、secret 槽位)与 `credentials.describe`(不含值的 configured/source/writable 徽标);页面据此渲染提供方行,一次只展开一张编辑卡片。
 
 行是*已配置*的提供方(其 profile 在所属 namespace 中解析得出);密钥未在任何地方配置的整分节提供方(DeepSeek 的首次运行姿态)会渲染为其展开的设置卡片而非一行,「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。编辑器是每个适配器家族各一张的手写卡片:主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名;键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下,profile 没有引用时便派生 `_API_KEY`,pi-ai profile 会把这次派生记录为 `apiKeyEnv`,因此 `settings.yaml` 从不携带密钥值。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`(deepseek 的占位符显示公共端点),另加 `reasoningEffort`(deepseek)或 `reasoning`(pi-ai);其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除(删除会还原组合 base)。
 
-首次使用浮层从同一个联接快照得出 `deepseek-official` 的就绪状态。若 `apiKey` 字面量对应的 secret 槽位标记为已设置,或凭据引用已配置,浮层就不再显示,其中包括来自启动环境且只读的凭据。适配器已挂载、引用可写但尚未配置时,浮层只显示一个操作按钮,用于打开「设置」的 Models 分区;密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责,浮层绝不持有 secret。适配器缺失时直接跳过,因为浏览器导航无法挂载 Cordis 插件;设置或凭据能力不可用时则显示部署诊断,并提供同一个前往 Models 的入口。
+前序首次使用引导步骤完成后,DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。若 `apiKey` 字面量对应的 secret 槽位标记为已设置,或凭据引用已配置,该步骤会直接完成而不渲染,其中包括来自启动环境且只读的凭据。适配器已挂载、引用可写但尚未配置时,该步骤只显示一个操作按钮,用于打开「设置」的 Models 分区;密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责,该步骤绝不持有 secret。适配器缺失时直接跳过,因为浏览器导航无法挂载 Cordis 插件;设置或凭据能力不可用时则显示部署诊断,并提供同一个前往 Models 的入口。
 
 每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除整行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor,因此它点名自己看得见的字段,而不是重建分节:一个它从未收到过的已存字面机密不会被任何 op 提及,也就得以留存。每次写入都携带该卡片打开时的 `revision`,因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝,卡片会请用户重新打开,而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件(`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`)上重拉,因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
 
diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
index 3d43bf2033..31ae571272 100644
--- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
@@ -4,7 +4,7 @@
  * routes the user to that page's single credential editor.
  */
 
-import { useEffect, useState } from 'react'
+import { useEffect } from 'react'
 import type { ReactNode } from 'react'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import { Button, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -64,26 +64,23 @@ function unavailableDiagnostic(
  * @returns the controlled modal or null when onboarding needs no intervention.
  */
 export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps): ReactNode {
-  const { active, openSection, controller, useSnapshot, t } = props
+  const { complete, openSection, controller, useSnapshot, t } = props
   const state = useSnapshot(snapshot => snapshot)
   const readiness = deepSeekReadiness(state)
-  const [dismissed, setDismissed] = useState(false)
 
   useEffect(() => {
-    if (active && !dismissed && state.status === 'idle') void controller.load()
-  }, [active, controller, dismissed, state.status])
+    if (state.status === 'idle') void controller.load()
+  }, [controller, state.status])
 
-  const close = (): void => {
-    setDismissed(true)
-  }
+  useEffect(() => {
+    if (readiness.kind === 'adapter-absent' || readiness.kind === 'configured') complete()
+  }, [complete, readiness.kind])
 
   const openModels = (): void => {
-    close()
+    complete()
     openSection('models')
   }
 
-  if (!active || dismissed) return null
-
   let unavailableReason: UnavailableReason | undefined
   switch (readiness.kind) {
     case 'loading':
@@ -108,7 +105,7 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
   return (
      { throw new Error('unused standard hook') }) as never
   const props: DeepSeekOnboardingDialogProps = {
-    active: true,
+    stepId: 'deepseek-official',
+    complete,
     openSection,
     useSessions: unusedHook,
     useWorkspaces: unusedHook,
@@ -102,7 +104,7 @@ function harness(options: {
     useSnapshot: bindSnapshotSelector(controller.store),
     t: key => en[key],
   }
-  return { controller, openSection, props, configure: () => { fileConfigured = true } }
+  return { controller, complete, openSection, props, configure: () => { fileConfigured = true } }
 }
 
 describe('DeepSeekOnboardingDialog', () => {
@@ -122,8 +124,8 @@ describe('DeepSeekOnboardingDialog', () => {
     render()
     await screen.findByRole('dialog')
     fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings }))
+    expect(h.complete).toHaveBeenCalledOnce()
     expect(h.openSection).toHaveBeenCalledWith('models')
-    expect(screen.queryByRole('dialog', { name: en.onboardingTitle })).toBeNull()
   })
 
   it('allows configure-later dismissal without opening settings', async () => {
@@ -131,7 +133,7 @@ describe('DeepSeekOnboardingDialog', () => {
     render()
     await screen.findByRole('dialog')
     fireEvent.click(screen.getByRole('button', { name: en.onboardingLater }))
-    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(h.complete).toHaveBeenCalledOnce()
     expect(h.openSection).not.toHaveBeenCalled()
   })
 
@@ -187,6 +189,7 @@ describe('DeepSeekOnboardingDialog', () => {
       const view = render()
       await act(async () => { await h.controller.load() })
       expect(screen.queryByRole('dialog')).toBeNull()
+      await waitFor(() => { expect(h.complete).toHaveBeenCalledOnce() })
       view.unmount()
     }
   })
@@ -198,14 +201,6 @@ describe('DeepSeekOnboardingDialog', () => {
     h.configure()
     await act(async () => { await h.controller.load() })
     await waitFor(() => { expect(screen.queryByRole('dialog')).toBeNull() })
-  })
-
-  it('stays hidden while the onboarding owner is inactive', async () => {
-    const h = harness()
-    const view = render()
-    await act(async () => { await h.controller.load() })
-    expect(screen.queryByRole('dialog')).toBeNull()
-    view.rerender()
-    expect(await screen.findByRole('dialog', { name: en.onboardingTitle })).toBeTruthy()
+    expect(h.complete).toHaveBeenCalledOnce()
   })
 })
diff --git a/packages/client/ui-settings-general/README.i18n.yaml b/packages/client/ui-settings-general/README.i18n.yaml
index 9377fc73b8..b8fd2d4025 100644
--- a/packages/client/ui-settings-general/README.i18n.yaml
+++ b/packages/client/ui-settings-general/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-README.md: c392d745021c0fc6a752cf71dd0506a435106c50
-README.zh.md: 83ab81e01eae435a74b50fa363a4de203c483002
+#   pnpm run verify-translation-pairing --write packages/client/ui-settings-general/README.md
+README.md: 3ae3f58bd00172ed9b547c01a354023c224f6a1c
+README.zh.md: ffdaf0e4314daa947a4183e2b23b7b1650de7611
diff --git a/packages/client/ui-settings-general/README.md b/packages/client/ui-settings-general/README.md
index c392d74502..3ae3f58bd0 100644
--- a/packages/client/ui-settings-general/README.md
+++ b/packages/client/ui-settings-general/README.md
@@ -2,7 +2,9 @@
 
 English | [中文](README.zh.md)
 
-Settings ownerless-copy plugin: registers everything on the Settings surface that belongs to no single feature — the shell's trigger/header/close chrome content, the General section (Permission/Tool Call skeleton rows + the `settings.general.item` slot declaration), and the `settings` dictionaries. Feature-owned rows (Language, Appearance) and sections (Models) stay with their feature packages.
+Settings ownerless-copy and product-onboarding plugin: registers everything on the Settings surface that belongs to no single feature — the shell's trigger/header/close chrome content, the General section (Permission/Tool Call skeleton rows + the `settings.general.item` slot declaration), the `settings` dictionaries, and the first ordered welcome step. Feature-owned rows (Language, Appearance), sections (Models), and conditional onboarding steps stay with their feature packages.
+
+`src/onboarding-copy.ts` is the single editable owner of the complete Chinese and English notice plus `WELCOME_NOTICE_VERSION`. The Host half registers `ui-onboarding` in the user-settings seam; the browser compares `welcomeNoticeVersion` for exact equality and writes the current value only after Continue succeeds. The path mutation is idempotent across tabs and preserves sibling settings, while `host/settings-changed` makes an externally acknowledged notice advance without a reload. A different version deliberately presents the notice again. The welcome UI has no close, Escape, mask-click, or secondary path, and none of its copy or acknowledgement enters a Session log or model request.
 
 ## Model Experience
 
diff --git a/packages/client/ui-settings-general/README.zh.md b/packages/client/ui-settings-general/README.zh.md
index 83ab81e01e..ffdaf0e431 100644
--- a/packages/client/ui-settings-general/README.zh.md
+++ b/packages/client/ui-settings-general/README.zh.md
@@ -2,7 +2,9 @@
 
 [English](README.md) | 中文
 
-设置界面文案插件:在设置界面注册所有不属于单一功能的内容,包括外壳的触发器、标题栏与关闭控件内容,「通用」分区(「权限」/「工具调用」骨架行和 `settings.general.item` slot 声明),以及 `settings` 字典。归具体功能所有的行(「语言」、「外观」)和分区(「模型」)仍由各自的功能包提供。
+设置界面无特定功能归属的文案与产品引导插件:在设置界面注册所有不属于单一功能的内容,包括外壳的触发器、标题栏与关闭控件内容,「通用」分区(「权限」/「工具调用」骨架行和 `settings.general.item` slot 声明)、`settings` 字典,以及第一个有序欢迎步骤。归具体功能所有的行(「语言」、「外观」)、分区(「模型」)和条件式首次使用引导步骤仍由各自的功能包提供。
+
+`src/onboarding-copy.ts` 是完整中英文通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源。宿主端在 user-settings seam 中注册 `ui-onboarding`;浏览器比较 `welcomeNoticeVersion` 是否精确相等,仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等,并会保留同级设置;`host/settings-changed` 则让页面在通知被外部确认后,无需重新加载即可推进。版本不同时,系统会有意重新显示通知。欢迎界面没有关闭操作、Escape、点击遮罩或次要操作路径,其文案和确认状态均不会进入会话日志或模型请求。
 
 ## 模型体验
 
diff --git a/packages/client/ui-settings-general/package.json b/packages/client/ui-settings-general/package.json
index 798a7710f0..fa380cfc83 100644
--- a/packages/client/ui-settings-general/package.json
+++ b/packages/client/ui-settings-general/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings-general",
-  "description": "Settings ownerless-copy plugin: the General section (skeleton rows + item slot), the shell trigger/header chrome content, and the settings dictionaries",
+  "description": "Settings ownerless-copy and product onboarding plugin: General, shell chrome, dictionaries, and the versioned welcome notice",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -26,7 +26,8 @@
     "inject": [
       "@deepseek-ai/dsh-client-runtime",
       "@deepseek-ai/dsh-client-ui-settings",
-      "@deepseek-ai/dsh-client-locale"
+      "@deepseek-ai/dsh-client-locale",
+      "@deepseek-ai/dsh-client-connection"
     ],
     "platform": "web"
   },
@@ -35,22 +36,30 @@
     "watch": "tsdown --watch"
   },
   "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-settings": "workspace:^",
+    "schemastery": "^3.18.0"
+  },
   "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-settings": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-client-web-react": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7",
     "react": "^18.2.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
     "cordis": "^4.0.0-rc.7",
diff --git a/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css b/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css
new file mode 100644
index 0000000000..8ad90b5fe2
--- /dev/null
+++ b/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css
@@ -0,0 +1,70 @@
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1100;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding-top: 80px;
+  box-sizing: border-box;
+}
+
+/* Mask */
+.mask {
+  position: absolute;
+  left: 0px;
+  right: 0px;
+  top: 80px;
+  bottom: 0px;
+  background: rgba(0, 0, 0, 0.24);
+  /* Mask-blur */
+  backdrop-filter: blur(2px);
+}
+
+.dialog {
+  position: relative;
+  z-index: 1;
+  width: min(640px, calc(100vw - 48px));
+  max-height: calc(100vh - 128px);
+  padding: 32px;
+  box-sizing: border-box;
+  overflow-y: auto;
+  border-radius: 24px;
+  background: var(--dsw-alias-bg-layer-2);
+  box-shadow: var(--dsw-shadow-lv3);
+  color: var(--dsw-alias-label-primary);
+}
+
+.title {
+  margin: 0;
+  font-size: 20px;
+  line-height: 30px;
+  font-weight: 600;
+}
+
+.copy {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  margin-top: 18px;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.copy p,
+.error {
+  margin: 0;
+}
+
+.error {
+  margin-top: 14px;
+  font-size: 13px;
+  line-height: 20px;
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.primary {
+  width: 100%;
+  margin-top: 24px;
+}
diff --git a/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx b/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx
new file mode 100644
index 0000000000..6255405f83
--- /dev/null
+++ b/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx
@@ -0,0 +1,69 @@
+/** Product-wide, versioned first-run welcome step. */
+
+import { useCallback, useEffect, useRef } from 'react'
+import type { ReactNode } from 'react'
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import type { WelcomeNoticeState, WelcomeNoticeStore } from './welcome-store.ts'
+import css from './WelcomeNotice.module.css'
+
+/** Registrant-owned dependencies of {@link WelcomeNotice}. */
+export interface WelcomeNoticeInjected {
+  controller: WelcomeNoticeStore
+  useSnapshot: SnapshotSelectorHook
+  t: (key: string) => string
+}
+
+/** Coordinator owner props plus the welcome step's injected face. */
+export type WelcomeNoticeProps = PropsRuntime<'settings.onboarding'> & WelcomeNoticeInjected
+
+/** Render the mandatory notice until its current version commits durably. */
+export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode {
+  const { complete, controller, useSnapshot, t } = props
+  const state = useSnapshot(snapshot => snapshot)
+  const finished = useRef(false)
+  const finish = useCallback((): void => {
+    if (finished.current) return
+    finished.current = true
+    complete()
+  }, [complete])
+
+  useEffect(() => {
+    if (state.status === 'idle') void controller.load()
+  }, [controller, state.status])
+
+  useEffect(() => {
+    if (state.acknowledged) finish()
+  }, [finish, state.acknowledged])
+
+  if (state.status === 'idle' || state.status === 'loading' || state.acknowledged) return null
+
+  const acknowledge = async (): Promise => {
+    if (await controller.acknowledge()) finish()
+  }
+
+  return (
+    
+ + ) +} diff --git a/packages/client/ui-settings-general/src/client/index.ts b/packages/client/ui-settings-general/src/client/index.ts index afb37d8b92..d2dd820ed9 100644 --- a/packages/client/ui-settings-general/src/client/index.ts +++ b/packages/client/ui-settings-general/src/client/index.ts @@ -8,13 +8,19 @@ */ import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client' import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots' +import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client' +import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react' // Type-only: pulls the shell's SlotMap merges (trigger/header/section/item). import type {} from '@deepseek-ai/dsh-client-ui-settings/client' import type { ChromeInjected } from './chrome.tsx' import { CloseLabel, HeaderContent, TriggerContent } from './chrome.tsx' import type { GeneralSectionInjected } from './GeneralSection.tsx' import { GeneralSection } from './GeneralSection.tsx' +import type { WelcomeNoticeInjected } from './WelcomeNotice.tsx' +import { WelcomeNotice } from './WelcomeNotice.tsx' +import { refreshWelcomeIfLoaded, WelcomeNoticeStore } from './welcome-store.ts' import { en, zh } from './locales.ts' +import { WELCOME_NOTICE_SETTINGS_NAMESPACE } from '../onboarding-copy.ts' export type { ChromeInjected, CloseLabelProps, HeaderContentProps, TriggerContentProps, @@ -22,6 +28,8 @@ export type { export type { GeneralSectionComponentProps, GeneralSectionInjected, } from './GeneralSection.tsx' +export type { WelcomeNoticeInjected, WelcomeNoticeProps } from './WelcomeNotice.tsx' +export type { WelcomeNoticeState } from './welcome-store.ts' /** Dictionary namespace owned by this plugin (shell chrome + General copy). */ const NS = 'settings' @@ -31,7 +39,7 @@ const NS = 'settings' * ui-settings' apply, whose activation order relative to this one is NOT * constrained; registration goes through declaration-aware deferral. */ -export const inject = ['slots', 'locale'] +export const inject = ['slots', 'locale', 'connection'] /** * Register the `settings` dictionaries, the chrome content, and the General @@ -48,8 +56,28 @@ export function apply(ctx: ClientContext): void { }, 'ui-settings-general: dictionaries') const t = ctx.locale.bind(NS) + const connection = ctx.get('connection') as ConnectionHandle + const welcomeController = new WelcomeNoticeStore(connection.api) + const useWelcomeSnapshot = bindSnapshotSelector(welcomeController.store) const chromeInjected = (): ChromeInjected => ({ t }) const generalInjected = (): GeneralSectionInjected => ({ t }) + const welcomeInjected = (): WelcomeNoticeInjected => ({ + controller: welcomeController, + useSnapshot: useWelcomeSnapshot, + t, + }) + + ctx.effect(() => { + const refresh = (ns?: string): void => { + if (ns !== undefined && ns !== WELCOME_NOTICE_SETTINGS_NAMESPACE) return + refreshWelcomeIfLoaded(welcomeController) + } + const disposers = [ + ctx.on('settings/changed', refresh), + ctx.on('connection/reset', () => { refresh() }), + ] + return () => { for (const dispose of disposers) dispose() } + }, 'ui-settings-general: welcome invalidations') // All four seats refresh on locale change: re-registration bumps each // slot's ledger version, which re-renders the outlets through their own @@ -70,11 +98,19 @@ export function apply(ctx: ClientContext): void { children: { 'settings.general.item': { kind: 'list', scope: 'root' } }, inject: generalInjected, }, GeneralSection)) + const welcome = deferRegistration(ctx.slots, 'settings.onboarding', WelcomeNotice, () => + ctx.slots.register({ + name: 'settings.onboarding', + id: 'welcome-notice', + order: -100, + inject: welcomeInjected, + }, WelcomeNotice)) const offLocale = ctx.on('locale/change', () => { trigger.refresh() header.refresh() close.refresh() general.refresh() + welcome.refresh() }) return () => { offLocale() @@ -82,6 +118,7 @@ export function apply(ctx: ClientContext): void { header.dispose() close.dispose() general.dispose() + welcome.dispose() } - }, 'ui-settings-general: chrome and section registrations') + }, 'ui-settings-general: chrome, section, and onboarding registrations') } diff --git a/packages/client/ui-settings-general/src/client/locales.ts b/packages/client/ui-settings-general/src/client/locales.ts index 6fc3295561..73c0daab58 100644 --- a/packages/client/ui-settings-general/src/client/locales.ts +++ b/packages/client/ui-settings-general/src/client/locales.ts @@ -6,6 +6,7 @@ * (Language, Appearance) ship their copy in their own packages. */ import type { LocaleDict } from '@deepseek-ai/dsh-client-locale/client' +import { WELCOME_NOTICE_COPY } from '../onboarding-copy.ts' const SHARED = { 'permission.value': 'Read only', @@ -25,6 +26,12 @@ export const zh: LocaleDict = { 'permission.title': '权限', 'permission.desc': '选择默认权限模式', 'toolcall.title': '工具调用', + 'welcome.paragraph.0': WELCOME_NOTICE_COPY.zh.paragraphs[0], + 'welcome.paragraph.1': WELCOME_NOTICE_COPY.zh.paragraphs[1], + 'welcome.paragraph.2': WELCOME_NOTICE_COPY.zh.paragraphs[2], + 'welcome.paragraph.3': WELCOME_NOTICE_COPY.zh.paragraphs[3], + 'welcome.continue': WELCOME_NOTICE_COPY.zh.continueLabel, + 'welcome.error': '暂时无法保存确认状态,请重试。', } /** English dictionary. */ @@ -37,4 +44,10 @@ export const en: LocaleDict = { 'permission.title': 'Permission', 'permission.desc': 'Choose default permission mode', 'toolcall.title': 'Tool Call', + 'welcome.paragraph.0': WELCOME_NOTICE_COPY.en.paragraphs[0], + 'welcome.paragraph.1': WELCOME_NOTICE_COPY.en.paragraphs[1], + 'welcome.paragraph.2': WELCOME_NOTICE_COPY.en.paragraphs[2], + 'welcome.paragraph.3': WELCOME_NOTICE_COPY.en.paragraphs[3], + 'welcome.continue': WELCOME_NOTICE_COPY.en.continueLabel, + 'welcome.error': 'The acknowledgement could not be saved. Please try again.', } diff --git a/packages/client/ui-settings-general/src/client/welcome-store.ts b/packages/client/ui-settings-general/src/client/welcome-store.ts new file mode 100644 index 0000000000..ad0e18305c --- /dev/null +++ b/packages/client/ui-settings-general/src/client/welcome-store.ts @@ -0,0 +1,108 @@ +/** Durable welcome-notice state over the Host settings document. */ + +import type { IApiClient, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client' +import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' +import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' +import { + WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, WELCOME_NOTICE_VERSION, +} from '../onboarding-copy.ts' + +/** State rendered by the welcome step. */ +export interface WelcomeNoticeState { + status: 'idle' | 'loading' | 'ready' | 'saving' | 'error' + acknowledged: boolean + error: string | null +} + +function messageOf(error: unknown): string { + return error instanceof Error ? error.message : String(error) +} + +function acknowledgementOf(view: SettingsNamespaceView): string | undefined { + if (typeof view.value !== 'object' || view.value === null) return undefined + const value = (view.value as Record)[WELCOME_NOTICE_ACK_FIELD] + return typeof value === 'string' ? value : undefined +} + +/** Coordinates welcome acknowledgement reads and the sole durable write. */ +export class WelcomeNoticeStore { + /** uSES-safe state source shared by the registered welcome step. */ + readonly store: SnapshotStore = createSnapshotStore({ + status: 'idle', acknowledged: false, error: null, + }) + + private generation = 0 + + /** @param api - settings wire face used for durable reads and writes. */ + constructor(private readonly api: Pick) {} + + /** Load the current acknowledgement from the Host settings document. */ + async load(): Promise { + const generation = ++this.generation + this.store.update((state) => { state.status = 'loading'; state.error = null }) + try { + const response = await this.api.settings.describe({}) + if (!response.result.ok) throw new Error(response.result.error.message) + const view = response.result.value.namespaces.find( + candidate => candidate.ns === WELCOME_NOTICE_SETTINGS_NAMESPACE, + ) + if (view === undefined) throw new Error('welcome acknowledgement settings are unavailable') + if (generation !== this.generation) return + this.store.update((state) => { + state.status = 'ready' + state.acknowledged = acknowledgementOf(view) === WELCOME_NOTICE_VERSION + state.error = null + }) + } catch (error) { + if (generation !== this.generation) return + this.store.update((state) => { + state.status = 'error' + state.acknowledged = false + state.error = messageOf(error) + }) + } + } + + /** + * Persist this copy version. The path mutation is idempotent across tabs and + * preserves every sibling setting; failure leaves the step unacknowledged. + * @returns true only when the Host committed the acknowledgement. + */ + async acknowledge(): Promise { + const generation = ++this.generation + this.store.update((state) => { state.status = 'saving'; state.error = null }) + try { + const response = await this.api.settings.mutate({ + ns: WELCOME_NOTICE_SETTINGS_NAMESPACE, + ops: [{ op: 'set', path: [WELCOME_NOTICE_ACK_FIELD], value: WELCOME_NOTICE_VERSION }], + }) + if (!response.result.ok) throw new Error(response.result.error.message) + if (generation === this.generation) { + this.store.update((state) => { + state.status = 'ready' + state.acknowledged = true + state.error = null + }) + } + return true + } catch (error) { + if (generation === this.generation) { + this.store.update((state) => { + state.status = 'error' + state.acknowledged = false + state.error = messageOf(error) + }) + } + return false + } + } +} + +/** + * Refresh only after the welcome step has begun reading durable state. + * @param controller - welcome state owner whose current status decides whether to load. + */ +export function refreshWelcomeIfLoaded(controller: WelcomeNoticeStore): void { + if (controller.store.getSnapshot().status === 'idle') return + void controller.load() +} diff --git a/packages/client/ui-settings-general/src/index.ts b/packages/client/ui-settings-general/src/index.ts index 94b9bdf674..18518c2835 100644 --- a/packages/client/ui-settings-general/src/index.ts +++ b/packages/client/ui-settings-general/src/index.ts @@ -1,4 +1,31 @@ /** Host loader entry for the browser implementation exported from `./client`. */ -/** Host plugin body — no host-side behavior for the general settings plugin. */ -export function apply(): void {} +import type { Context } from 'cordis' +import z from 'schemastery' +import { settingsNamespace } from '@deepseek-ai/dsh-settings' +import { + WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, +} from './onboarding-copy.ts' + +export { + WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_COPY, WELCOME_NOTICE_SETTINGS_NAMESPACE, + WELCOME_NOTICE_VERSION, +} from './onboarding-copy.ts' + +interface OnboardingSettings { + welcomeNoticeVersion?: string +} + +const OnboardingSettingsSchema: z = z.object({ + [WELCOME_NOTICE_ACK_FIELD]: z.string(), +}) + +/** Register the durable GUI-onboarding section when a settings provider exists. */ +export function apply(ctx: Context): void { + ctx.inject(['settings'], (settingsCtx) => { + settingsCtx.settings.register( + settingsNamespace(WELCOME_NOTICE_SETTINGS_NAMESPACE), + OnboardingSettingsSchema, + ) + }) +} diff --git a/packages/client/ui-settings-general/src/invariant.ts b/packages/client/ui-settings-general/src/invariant.ts index 29f762834d..d13ecc5cb8 100644 --- a/packages/client/ui-settings-general/src/invariant.ts +++ b/packages/client/ui-settings-general/src/invariant.ts @@ -15,10 +15,9 @@ export const name = 'client-ui-settings-general-invariant' export const inject = ['invariants'] /** - * No runtime invariant: a copy-owning registrant contributing chrome content - * and the General section into shell-declared slots — it emits no cordis - * events and owns no cross-plugin mutable relation; slot conflicts already - * fail loud in the slot core at load time. + * No runtime invariant: the settings seam validates and publishes the durable + * welcome section, while slot conflicts fail loud in the slot core; this + * package owns no additional event/data relationship between those systems. */ const install: InvariantInstaller = () => {} diff --git a/packages/client/ui-settings-general/src/onboarding-copy.ts b/packages/client/ui-settings-general/src/onboarding-copy.ts new file mode 100644 index 0000000000..04a075783e --- /dev/null +++ b/packages/client/ui-settings-general/src/onboarding-copy.ts @@ -0,0 +1,33 @@ +/** Durable settings namespace for product-wide GUI onboarding facts. */ +export const WELCOME_NOTICE_SETTINGS_NAMESPACE = 'ui-onboarding' + +/** Field storing the last welcome notice version the user acknowledged. */ +export const WELCOME_NOTICE_ACK_FIELD = 'welcomeNoticeVersion' + +/** + * Bump only when the notice changes materially and every user should see it + * again. The acknowledgement is compared for exact equality. + */ +export const WELCOME_NOTICE_VERSION = '2026-07-30.1' + +/** The complete editable welcome notice in both supported GUI locales. */ +export const WELCOME_NOTICE_COPY = { + zh: { + paragraphs: [ + '感谢您愿意拨冗试用 DeepSeek Harness。', + '目前的版本仍处于内部测试阶段,有些功能仍待完善,有些体验难免粗粝。', + '“如切如磋,如琢如磨。” 产品的成长,离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中暴露的问题,也可能促使我们重新审视,甚至推翻已有的设计。', + '我们尤其希望听见那些失败、困惑与不顺手的时刻——如果它未能帮到您,甚至反而为工作平添了麻烦,请在企业微信群中留言,将使用感受告诉我们。每一条反馈,都会帮助我们把它打磨得更好。', + ], + continueLabel: '继续', + }, + en: { + paragraphs: [ + 'Thank you for taking the time to try DeepSeek Harness.', + 'This version is still in internal testing. Some features remain unfinished, and parts of the experience may feel rough.', + '“As one cuts and files, as one chisels and polishes.” A product grows through real encounters and candid feedback. Problems you uncover in real use may prompt us to reconsider—or even overturn—our existing designs.', + 'We especially want to hear about failures, confusion, and friction. If it did not help you, or even made your work harder, please leave a message in the company WeChat group and tell us about your experience. Every piece of feedback helps us refine it.', + ], + continueLabel: 'Continue', + }, +} as const diff --git a/packages/client/ui-settings-general/tests/apply.spec.ts b/packages/client/ui-settings-general/tests/apply.spec.ts index d01be576b7..9d03ac03b8 100644 --- a/packages/client/ui-settings-general/tests/apply.spec.ts +++ b/packages/client/ui-settings-general/tests/apply.spec.ts @@ -1,12 +1,15 @@ /** Ownerless-copy registrations: the four seats, the dictionaries, locale refresh, and HMR recovery. */ import { Context } from 'cordis' -import { describe, expect, it } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client' import { LocaleService } from '@deepseek-ai/dsh-client-locale/client' import { apply, inject } from '@deepseek-ai/dsh-client-ui-settings-general/client' import type { GeneralSectionInjected } from '@deepseek-ai/dsh-client-ui-settings-general/client' import { CloseLabel, HeaderContent, TriggerContent } from '../src/client/chrome.tsx' import { GeneralSection } from '../src/client/GeneralSection.tsx' +import { WelcomeNotice } from '../src/client/WelcomeNotice.tsx' +import type { WelcomeNoticeInjected } from '../src/client/WelcomeNotice.tsx' +import { WELCOME_NOTICE_SETTINGS_NAMESPACE } from '../src/onboarding-copy.ts' /** The four seats this plugin fills (slot name → expected component). */ const SEATS = [ @@ -14,6 +17,7 @@ const SEATS = [ ['settings.header', HeaderContent], ['settings.close', CloseLabel], ['settings.section', GeneralSection], + ['settings.onboarding', WelcomeNotice], ] as const async function bench() { @@ -21,7 +25,25 @@ async function bench() { await ctx.plugin(SlotsService).await() const locale = new LocaleService(ctx) ctx.provide('locale', locale) - return { ctx, slots: ctx.get('slots') as SlotsService, locale } + const settingsDescribe = vi.fn(() => Promise.resolve({ + rpcId: 'settings-general' as never, + result: { + ok: true as const, + value: { + writable: true, + namespaces: [{ + ns: WELCOME_NOTICE_SETTINGS_NAMESPACE, + schema: {}, + value: {}, + applies: 'live' as const, + secrets: [], + revision: 0, + }], + }, + }, + })) + ctx.provide('connection', { api: { settings: { describe: settingsDescribe } } } as never) + return { ctx, slots: ctx.get('slots') as SlotsService, locale, settingsDescribe } } /** Declare the shell's four child slots the way ui-settings' entry does. */ @@ -34,6 +56,7 @@ function declare(slots: SlotsService): () => void { 'settings.header': { kind: 'single', scope: 'root' }, 'settings.close': { kind: 'single', scope: 'root' }, 'settings.section': { kind: 'list', scope: 'root' }, + 'settings.onboarding': { kind: 'list', scope: 'root' }, }, } as never, () => null, @@ -46,7 +69,7 @@ function generalEntry(slots: SlotsService) { describe('ui-settings-general apply', () => { it('declares the services it uses', () => { - expect(inject).toEqual(['slots', 'locale']) + expect(inject).toEqual(['slots', 'locale', 'connection']) }) it('fills all four seats for declarations before or after apply', async () => { @@ -61,6 +84,8 @@ describe('ui-settings-general apply', () => { expect(before.slots.spec('settings.general.item')).toEqual({ kind: 'list', scope: 'root' }) const injected = (entry.inject as unknown as () => GeneralSectionInjected)() expect(injected.t('permission.title')).toBe('权限') + const welcome = before.slots.entries('settings.onboarding')[0]! + expect(welcome.options).toEqual({ id: 'welcome-notice', order: -100 }) // The chrome seats share one inject face: the settings-ns translate. const chrome = (before.slots.entries('settings.trigger')[0]!.inject as unknown as () => GeneralSectionInjected)() expect(chrome.t('trigger')).toBe('设置') @@ -116,6 +141,22 @@ describe('ui-settings-general apply', () => { b.locale.setLocale('zh') }) + it('refreshes loaded welcome state only for its settings namespace or a reconnect', async () => { + const b = await bench() + declare(b.slots) + await b.ctx.plugin({ inject: [...inject], apply }).await() + const entry = b.slots.entries('settings.onboarding')[0]! + const { controller } = (entry.inject as unknown as () => WelcomeNoticeInjected)() + await controller.load() + expect(b.settingsDescribe).toHaveBeenCalledOnce() + b.ctx.emit('settings/changed', 'unrelated') + expect(b.settingsDescribe).toHaveBeenCalledOnce() + b.ctx.emit('settings/changed', WELCOME_NOTICE_SETTINGS_NAMESPACE) + await vi.waitFor(() => { expect(b.settingsDescribe).toHaveBeenCalledTimes(2) }) + b.ctx.emit('connection/reset') + await vi.waitFor(() => { expect(b.settingsDescribe).toHaveBeenCalledTimes(3) }) + }) + it('re-registers after an HMR collapse of the declaring chain (stale disposers must not block)', async () => { const b = await bench() const redeclare = declare(b.slots) diff --git a/packages/client/ui-settings-general/tests/host.spec.ts b/packages/client/ui-settings-general/tests/host.spec.ts new file mode 100644 index 0000000000..6434bc833a --- /dev/null +++ b/packages/client/ui-settings-general/tests/host.spec.ts @@ -0,0 +1,29 @@ +import { Context } from 'cordis' +import { describe, expect, it } from 'vitest' +import { Settings, settingsNamespace, type SettingsNamespace } from '@deepseek-ai/dsh-settings' +import { apply } from '../src/index.ts' +import { WELCOME_NOTICE_SETTINGS_NAMESPACE } from '../src/onboarding-copy.ts' + +class MemorySettings extends Settings { + readonly writable = true + protected load(): Promise> { return Promise.resolve({}) } + protected persist(_ns: SettingsNamespace, _section: Record): Promise { + return Promise.resolve() + } +} + +describe('ui-settings-general host', () => { + it('registers and disposes the durable onboarding namespace with its fiber', async () => { + const ctx = new Context() + await ctx.plugin(MemorySettings).await() + const fiber = ctx.plugin({ apply }) + await fiber.await() + expect(ctx.settings.describe().map(row => row.ns)).toContain( + settingsNamespace(WELCOME_NOTICE_SETTINGS_NAMESPACE), + ) + await fiber.dispose() + expect(ctx.settings.describe().map(row => row.ns)).not.toContain( + settingsNamespace(WELCOME_NOTICE_SETTINGS_NAMESPACE), + ) + }) +}) diff --git a/packages/client/ui-settings-general/tests/invariant.spec.ts b/packages/client/ui-settings-general/tests/invariant.spec.ts index 7b0527c0ff..59863a5794 100644 --- a/packages/client/ui-settings-general/tests/invariant.spec.ts +++ b/packages/client/ui-settings-general/tests/invariant.spec.ts @@ -9,10 +9,4 @@ describe('invariant companion', () => { await ctx.plugin(InvariantService, { enabled: true }) await expect(ctx.plugin(GeneralInvariant).await()).resolves.toBeDefined() }) - - it('node-half apply is a no-op host placeholder', async () => { - const { apply } = await import('@deepseek-ai/dsh-client-ui-settings-general') - apply() - expect(true).toBe(true) // reaching here without throw is the contract - }) }) diff --git a/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx b/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx new file mode 100644 index 0000000000..5925cf048b --- /dev/null +++ b/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx @@ -0,0 +1,101 @@ +// @vitest-environment jsdom +import { act, cleanup, fireEvent, render, screen } from '@testing-library/react' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react' +import { WelcomeNotice } from '../src/client/WelcomeNotice.tsx' +import type { WelcomeNoticeProps } from '../src/client/WelcomeNotice.tsx' +import { WelcomeNoticeStore } from '../src/client/welcome-store.ts' +import { zh } from '../src/client/locales.ts' +import { + WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_COPY, WELCOME_NOTICE_SETTINGS_NAMESPACE, + WELCOME_NOTICE_VERSION, +} from '../src/onboarding-copy.ts' + +afterEach(cleanup) + +function response(value: T) { + return { rpcId: 'welcome-rpc' as never, result: { ok: true as const, value } } +} + +function mount(version?: string, mutateImpl: () => Promise = () => Promise.resolve(response({}))) { + const mutate = vi.fn(mutateImpl) + const api = { + settings: { + describe: () => Promise.resolve(response({ + writable: true, + namespaces: [{ + ns: WELCOME_NOTICE_SETTINGS_NAMESPACE, + schema: {}, + value: version === undefined ? {} : { [WELCOME_NOTICE_ACK_FIELD]: version }, + applies: 'live' as const, + secrets: [], + revision: 0, + }], + })), + mutate, + }, + } + const controller = new WelcomeNoticeStore(api as never) + const complete = vi.fn() + const unusedHook = (() => { throw new Error('unused standard hook') }) as never + const props: WelcomeNoticeProps = { + stepId: 'welcome-notice', + complete, + openSection: vi.fn(), + useSessions: unusedHook, + useWorkspaces: unusedHook, + controller, + useSnapshot: bindSnapshotSelector(controller.store), + t: key => zh[key] ?? key, + } + return { ...render(), complete, controller, mutate } +} + +describe('WelcomeNotice', () => { + it('renders the owner copy with one primary action and no dismissal control', async () => { + const h = mount() + const dialog = await screen.findByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.paragraphs[0] }) + for (const paragraph of WELCOME_NOTICE_COPY.zh.paragraphs) { + expect(screen.getByText(paragraph)).toBeTruthy() + } + const buttons = dialog.querySelectorAll('button') + expect(buttons).toHaveLength(1) + expect(screen.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel })).toBeTruthy() + fireEvent.keyDown(document, { key: 'Escape' }) + fireEvent.click(dialog.parentElement!.firstElementChild!) + expect(h.complete).not.toHaveBeenCalled() + expect(screen.getByRole('dialog')).toBeTruthy() + }) + + it('completes only after the acknowledgement write commits', async () => { + const h = mount() + await screen.findByRole('dialog') + fireEvent.click(screen.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel })) + await act(async () => { await Promise.resolve() }) + expect(h.mutate).toHaveBeenCalledOnce() + expect(h.complete).toHaveBeenCalledOnce() + }) + + it('skips itself when this exact version was already acknowledged', async () => { + const h = mount(WELCOME_NOTICE_VERSION) + await act(async () => { await h.controller.load() }) + expect(screen.queryByRole('dialog')).toBeNull() + expect(h.complete).toHaveBeenCalledOnce() + }) + + it('keeps the sole action disabled while saving and reports a refused write', async () => { + let resolveWrite!: (value: unknown) => void + const write = new Promise((resolve) => { resolveWrite = resolve }) + const h = mount(undefined, () => write) + await screen.findByRole('dialog') + const action = screen.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }) + fireEvent.click(action) + expect(action.disabled).toBe(true) + resolveWrite({ + rpcId: 'welcome-refused' as never, + result: { ok: false, error: { code: 'settings-rejected', message: 'read only', details: { ns: WELCOME_NOTICE_SETTINGS_NAMESPACE } } }, + }) + expect((await screen.findByRole('alert')).textContent).toBe('暂时无法保存确认状态,请重试。') + expect(h.complete).not.toHaveBeenCalled() + }) +}) diff --git a/packages/client/ui-settings-general/tests/welcome-store.spec.ts b/packages/client/ui-settings-general/tests/welcome-store.spec.ts new file mode 100644 index 0000000000..28c7b0509c --- /dev/null +++ b/packages/client/ui-settings-general/tests/welcome-store.spec.ts @@ -0,0 +1,166 @@ +import { describe, expect, it, vi } from 'vitest' +import type { RpcResponse } from '@deepseek-ai/dsh-client-connection/client' +import { WelcomeNoticeStore } from '../src/client/welcome-store.ts' +import { refreshWelcomeIfLoaded } from '../src/client/welcome-store.ts' +import { + WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, WELCOME_NOTICE_VERSION, +} from '../src/onboarding-copy.ts' + +let rpc = 0 +function ok(value: T): RpcResponse { + return { rpcId: `welcome-${rpc++}` as never, result: { ok: true, value } } +} + +function namespace(version?: string) { + return { + ns: WELCOME_NOTICE_SETTINGS_NAMESPACE, + schema: {}, + value: version === undefined ? {} : { [WELCOME_NOTICE_ACK_FIELD]: version }, + applies: 'live' as const, + secrets: [], + revision: 0, + } +} + +function deferred() { + let resolve!: (value: T) => void + let reject!: (reason: unknown) => void + const promise = new Promise((res, rej) => { resolve = res; reject = rej }) + return { promise, resolve, reject } +} + +describe('WelcomeNoticeStore', () => { + it('acknowledges only the exact current copy version', async () => { + for (const [version, acknowledged] of [ + [undefined, false], + ['older-copy', false], + [WELCOME_NOTICE_VERSION, true], + ] as const) { + const api = { + settings: { + describe: vi.fn(() => Promise.resolve(ok({ writable: true, namespaces: [namespace(version)] }))), + }, + } + const controller = new WelcomeNoticeStore(api as never) + await controller.load() + expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged }) + } + }) + + it('persists the owner version through one idempotent path mutation', async () => { + const mutate = vi.fn(() => Promise.resolve(ok(namespace(WELCOME_NOTICE_VERSION)))) + const controller = new WelcomeNoticeStore({ settings: { mutate } } as never) + await expect(controller.acknowledge()).resolves.toBe(true) + expect(mutate).toHaveBeenCalledWith({ + ns: WELCOME_NOTICE_SETTINGS_NAMESPACE, + ops: [{ op: 'set', path: [WELCOME_NOTICE_ACK_FIELD], value: WELCOME_NOTICE_VERSION }], + }) + expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: true }) + }) + + it('keeps the notice pending when loading or persistence fails', async () => { + const load = new WelcomeNoticeStore({ + settings: { describe: () => Promise.reject(new Error('offline')) }, + } as never) + await load.load() + expect(load.store.getSnapshot()).toEqual({ status: 'error', acknowledged: false, error: 'offline' }) + + const save = new WelcomeNoticeStore({ + settings: { mutate: () => Promise.reject(new Error('disk full')) }, + } as never) + await expect(save.acknowledge()).resolves.toBe(false) + expect(save.store.getSnapshot()).toEqual({ status: 'error', acknowledged: false, error: 'disk full' }) + + const nonError = new WelcomeNoticeStore({ + // Durable/wire failures are unknown; exercise containment of a non-Error rejection. + // oxlint-disable-next-line typescript/prefer-promise-reject-errors + settings: { describe: () => Promise.reject('offline string') }, + } as never) + await nonError.load() + expect(nonError.store.getSnapshot().error).toBe('offline string') + }) + + it('reports business failures, missing namespaces, and malformed durable values', async () => { + for (const describe of [ + () => Promise.resolve({ + rpcId: 'failed' as never, + result: { ok: false as const, error: { code: 'internal' as const, message: 'denied', details: {} } }, + }), + () => Promise.resolve(ok({ writable: true, namespaces: [] })), + ]) { + const controller = new WelcomeNoticeStore({ settings: { describe } } as never) + await controller.load() + expect(controller.store.getSnapshot().status).toBe('error') + } + + for (const value of [null, 42, { [WELCOME_NOTICE_ACK_FIELD]: 42 }]) { + const controller = new WelcomeNoticeStore({ + settings: { describe: () => Promise.resolve(ok({ + writable: true, + namespaces: [{ ...namespace(), value }], + })) }, + } as never) + await controller.load() + expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: false }) + } + + const save = new WelcomeNoticeStore({ + settings: { mutate: () => Promise.resolve({ + rpcId: 'failed-save' as never, + result: { ok: false, error: { code: 'settings-rejected', message: 'denied', details: { ns: WELCOME_NOTICE_SETTINGS_NAMESPACE } } }, + }) }, + } as never) + await expect(save.acknowledge()).resolves.toBe(false) + expect(save.store.getSnapshot().error).toBe('denied') + }) + + it('lets the latest load win over stale success and failure', async () => { + const first = deferred>() + const describe = vi.fn() + .mockImplementationOnce(() => first.promise) + .mockImplementationOnce(() => Promise.resolve(ok({ writable: true, namespaces: [namespace()] }))) + const controller = new WelcomeNoticeStore({ settings: { describe } } as never) + const stale = controller.load() + await controller.load() + first.resolve(ok({ writable: true, namespaces: [namespace(WELCOME_NOTICE_VERSION)] })) + await stale + expect(controller.store.getSnapshot().acknowledged).toBe(false) + + const failed = deferred>() + describe + .mockImplementationOnce(() => failed.promise) + .mockImplementationOnce(() => Promise.resolve(ok({ writable: true, namespaces: [namespace(WELCOME_NOTICE_VERSION)] }))) + const staleFailure = controller.load() + await controller.load() + failed.reject('stale failure') + await staleFailure + expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: true, error: null }) + }) + + it('contains stale acknowledgement settlements and refreshes only a loaded store', async () => { + const write = deferred>() + const describe = vi.fn(() => Promise.resolve(ok({ writable: true, namespaces: [namespace()] }))) + const controller = new WelcomeNoticeStore({ + settings: { mutate: () => write.promise, describe }, + } as never) + refreshWelcomeIfLoaded(controller) + expect(describe).not.toHaveBeenCalled() + const staleWrite = controller.acknowledge() + await controller.load() + write.resolve(ok(namespace(WELCOME_NOTICE_VERSION))) + await expect(staleWrite).resolves.toBe(true) + expect(controller.store.getSnapshot().acknowledged).toBe(false) + refreshWelcomeIfLoaded(controller) + await vi.waitFor(() => { expect(describe).toHaveBeenCalledTimes(2) }) + + const failedWrite = deferred>() + const staleFailure = new WelcomeNoticeStore({ + settings: { mutate: () => failedWrite.promise, describe }, + } as never) + const pending = staleFailure.acknowledge() + await staleFailure.load() + failedWrite.reject('late failure') + await expect(pending).resolves.toBe(false) + expect(staleFailure.store.getSnapshot().status).toBe('ready') + }) +}) diff --git a/packages/client/ui-settings-general/tsconfig.json b/packages/client/ui-settings-general/tsconfig.json index 5ef01ba51c..5e37578f91 100644 --- a/packages/client/ui-settings-general/tsconfig.json +++ b/packages/client/ui-settings-general/tsconfig.json @@ -14,6 +14,9 @@ { "path": "../ui-slots" }, + { + "path": "../connection" + }, { "path": "../ui-primitives" }, @@ -23,9 +26,15 @@ { "path": "../ui-settings" }, + { + "path": "../web-react" + }, { "path": "../locale" }, + { + "path": "../../settings/settings" + }, { "path": "../../support/invariants" } diff --git a/packages/client/ui-settings/README.i18n.yaml b/packages/client/ui-settings/README.i18n.yaml index c09aed1d0a..41247a370b 100644 --- a/packages/client/ui-settings/README.i18n.yaml +++ b/packages/client/ui-settings/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-settings/README.md -README.md: 9388e9dd3a984bfcebc85b6b1a35bcce4b9b116e -README.zh.md: 57c91ac5dd0bcc0a3e5e029359bf6c3a2be58ec7 +README.md: 02d8f0e5fdc169d3a45f59d7b42d873943df2b52 +README.zh.md: 465d57847588e9ccbccc9d9067099773de63c0d0 diff --git a/packages/client/ui-settings/README.md b/packages/client/ui-settings/README.md index 9388e9dd3a..02d8f0e5fd 100644 --- a/packages/client/ui-settings/README.md +++ b/packages/client/ui-settings/README.md @@ -2,9 +2,9 @@ English | [中文](README.zh.md) -Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.section` (one page per feature), and `settings.onboarding` (feature-owned overlays on the empty Hero). The shell ships no copy and reads no locale state — all text arrives from registrants (ui-settings-general owns chrome and General; features own their sections, rows, and onboarding overlays). +Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.section` (one page per feature), and `settings.onboarding` (ordered feature-owned steps on the empty Hero). The shell ships no copy and reads no locale state — all text arrives from registrants (ui-settings-general owns chrome, General, and the product welcome step; features own their sections, rows, and conditional onboarding steps). -The shell supplies onboarding registrants only two navigation facts: whether the session surface is the empty Hero and an `openSection(id)` callback that opens the panel on a registered section. Registrants own capability readiness, dismissal, copy, and mutations; the shell therefore does not become a second configuration fact source. +The shell projects the onboarding ledger into ascending order and mounts exactly one step at a time. The active registrant receives its id, `complete()`, and an `openSection(id)` callback; completing or skipping transfers ownership to the next entry. Registrants own durable completion, capability readiness, copy, and mutations, so two independently registered dialogs cannot stack and the shell does not become a second configuration fact source. ## Model Experience diff --git a/packages/client/ui-settings/README.zh.md b/packages/client/ui-settings/README.zh.md index 57c91ac5dd..465d578475 100644 --- a/packages/client/ui-settings/README.zh.md +++ b/packages/client/ui-settings/README.zh.md @@ -2,9 +2,9 @@ [English](README.md) | 中文 -设置外壳插件:一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`,并声明由注册方填充的 slot:`settings.trigger`/`settings.header`/`settings.close`(界面框架内容)、`settings.section`(每项功能一页)和 `settings.onboarding`(由各功能持有、覆盖在空白 Hero 之上的浮层)。外壳不自带文案,也不读取 locale 状态:所有文本都来自注册方(ui-settings-general 拥有界面框架和「通用」分区;各功能拥有各自的分区、行和首次使用浮层)。 +设置外壳插件:一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`,并声明由注册方填充的 slot:`settings.trigger`/`settings.header`/`settings.close`(界面框架内容)、`settings.section`(每项功能一页)和 `settings.onboarding`(由各功能持有、显示在空白 Hero 上的有序步骤)。外壳不自带文案,也不读取 locale 状态:所有文本都来自注册方(ui-settings-general 拥有界面框架、「通用」分区和产品欢迎步骤;各功能拥有各自的分区、行和条件式首次使用引导步骤)。 -外壳只向首次使用注册方提供两个导航事实:当前会话界面是否为空白 Hero,以及一个 `openSection(id)` 回调;后者会打开设置面板并切换到已注册的指定分区。能力就绪状态、浮层关闭、文案和变更操作均由注册方持有,因此外壳不会成为第二个配置事实来源。 +外壳将首次使用引导记录按升序投影,并且每次只挂载一个步骤。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调;完成或跳过当前步骤后,所有权转交给下一项。持久化完成状态、能力就绪状态、文案和变更操作均由注册方持有,因此两个独立注册的对话框无法堆叠,外壳也不会成为第二个配置事实来源。 ## 模型体验 diff --git a/packages/client/ui-settings/src/client/SettingsRoot.tsx b/packages/client/ui-settings/src/client/SettingsRoot.tsx index cfa3ac6cef..528a633810 100644 --- a/packages/client/ui-settings/src/client/SettingsRoot.tsx +++ b/packages/client/ui-settings/src/client/SettingsRoot.tsx @@ -6,8 +6,8 @@ * names resolve to that content (trigger: its own text; dialog: * aria-labelledby the title node; close: visually-hidden slot text). Modal * open state and the active section id are component-local viewing state; - * the onboarding slot receives the sessions-derived empty-Hero fact and a - * private callback that opens one registered section. + * the onboarding coordinator mounts exactly one ordered registrant while the + * sessions-derived empty-Hero fact is active. */ import { useCallback, useEffect, useId, useRef, useState } from 'react' import clsx from 'clsx' @@ -95,9 +95,10 @@ function SettingsPanel({ rows, renderSlot, activeId, onSelect, onClose }: PanelP * @returns the settings shell element tree. */ export function SettingsRoot(props: SettingsRootComponentProps) { - const { wide, useSections, useSessions, renderSlot } = props + const { wide, useSections, useOnboardingSteps, useSessions, renderSlot } = props const [open, setOpen] = useState(false) const [activeId, setActiveId] = useState(undefined) + const [completedOnboarding, setCompletedOnboarding] = useState>(() => new Set()) const close = useCallback(() => { setOpen(false) setActiveId(undefined) @@ -111,9 +112,25 @@ export function SettingsRoot(props: SettingsRootComponentProps) { // freshly localized text on locale change, and the trigger/header/close // seats re-render through their own outlets' subscriptions. const rows = useSections(s => s) + const onboardingSteps = useOnboardingSteps(s => s) const onboardingActive = useSessions(state => state.phase === 'ready' && (state.current === undefined || state.byId[state.current]?.blank === true)) + const onboardingStep = onboardingActive + ? onboardingSteps.find(step => !completedOnboarding.has(step.id)) + : undefined + + useEffect(() => { + if (onboardingActive) return + setCompletedOnboarding(new Set()) + }, [onboardingActive]) + + const completeOnboardingStep = useCallback((id: string) => { + setCompletedOnboarding((previous) => { + if (previous.has(id)) return previous + return new Set([...previous, id]) + }) + }, []) return ( <> @@ -135,7 +152,11 @@ export function SettingsRoot(props: SettingsRootComponentProps) { onClose={close} /> )} - {renderSlot('settings.onboarding', { active: onboardingActive, openSection })} + {onboardingStep !== undefined && renderSlot('settings.onboarding', { + stepId: onboardingStep.id, + complete: () => { completeOnboardingStep(onboardingStep.id) }, + openSection, + }, { only: onboardingStep.id })} ) } diff --git a/packages/client/ui-settings/src/client/contract/slots.ts b/packages/client/ui-settings/src/client/contract/slots.ts index 37847832bf..4d5e48d80f 100644 --- a/packages/client/ui-settings/src/client/contract/slots.ts +++ b/packages/client/ui-settings/src/client/contract/slots.ts @@ -48,10 +48,10 @@ declare module '@deepseek-ai/dsh-client-ui-slots' { */ 'settings.section': { kind: 'list'; scope: 'root'; owner: SettingsSectionOwnerProps } /** - * Root-scoped onboarding overlays contributed by settings features. The - * shell supplies whether the current navigation state is the empty Hero - * and a private callback that opens one settings section; registrants own - * readiness, copy, and dialog behavior. + * Root-scoped onboarding steps contributed by settings features. The + * shell mounts one ordered step at a time; the active registrant either + * completes itself or keeps ownership until the user completes its sole + * path. Registrants own readiness, copy, and dialog behavior. */ 'settings.onboarding': { kind: 'list'; scope: 'root'; owner: SettingsOnboardingOwnerProps } } @@ -79,10 +79,12 @@ export interface SettingsSectionOwnerProps { children?: never } -/** Owner share of a settings-backed onboarding overlay. */ +/** Owner share of the currently active settings-backed onboarding step. */ export interface SettingsOnboardingOwnerProps { - /** Whether the current UI is in its empty Hero/onboarding state. */ - active: boolean + /** Stable id of the step currently selected by the coordinator. */ + stepId: string + /** Complete or skip this step and transfer ownership to the next entry. */ + complete: () => void /** Open the settings panel directly on one registered section. */ openSection: (id: string) => void } @@ -94,6 +96,12 @@ export interface SettingsSectionRow { label: string } +/** One ordered onboarding step projected from a slot registration. */ +export interface SettingsOnboardingStep { + id: string + order: number +} + /** * Registrant-private injected share of the settings shell (assembled in * apply): the ledger's nav-row projection as a hooks-compartment source — @@ -103,6 +111,8 @@ export type SettingsRootInjected = { hooks: { /** settings.section ledger projected into ordered nav rows. */ sections: HostObservable + /** settings.onboarding ledger projected into coordinator order. */ + onboardingSteps: HostObservable } } diff --git a/packages/client/ui-settings/src/client/index.ts b/packages/client/ui-settings/src/client/index.ts index dad2f89e77..5660ef389c 100644 --- a/packages/client/ui-settings/src/client/index.ts +++ b/packages/client/ui-settings/src/client/index.ts @@ -9,12 +9,15 @@ */ import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client' import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots' -import type { SettingsRootInjected, SettingsSectionRow } from './contract/slots.ts' +import type { + SettingsOnboardingStep, SettingsRootInjected, SettingsSectionRow, +} from './contract/slots.ts' import { SettingsRoot } from './SettingsRoot.tsx' export type { SettingsHeaderOwnerProps, SettingsRootComponentProps, SettingsRootInjected, - SettingsOnboardingOwnerProps, SettingsSectionOwnerProps, SettingsSectionRow, SettingsTriggerOwnerProps, + SettingsOnboardingOwnerProps, SettingsOnboardingStep, SettingsSectionOwnerProps, + SettingsSectionRow, SettingsTriggerOwnerProps, } from './contract/slots.ts' /** @@ -35,6 +38,8 @@ export function apply(ctx: ClientContext): void { // getSnapshot returns the cached rows until the ledger version moves). let rowsVersion = -1 let rows: readonly SettingsSectionRow[] = [] + let onboardingVersion = -1 + let onboardingSteps: readonly SettingsOnboardingStep[] = [] const injected = (): SettingsRootInjected => ({ hooks: { sections: { @@ -55,6 +60,23 @@ export function apply(ctx: ClientContext): void { }, subscribe: listener => ctx.slots.subscribe('settings.section', listener), }, + onboardingSteps: { + getSnapshot: () => { + const version = ctx.slots.getVersion('settings.onboarding') + if (version !== onboardingVersion) { + onboardingVersion = version + onboardingSteps = ctx.slots.entries('settings.onboarding') + .map(e => ({ + /* v8 ignore next -- list-slot registration requires id */ + id: e.options.id ?? '', + order: e.options.order ?? 0, + })) + .sort((a, b) => a.order - b.order) + } + return onboardingSteps + }, + subscribe: listener => ctx.slots.subscribe('settings.onboarding', listener), + }, }, }) ctx.effect(() => { diff --git a/packages/client/ui-settings/tests/apply.spec.ts b/packages/client/ui-settings/tests/apply.spec.ts index de50c88d87..48b63bc0a0 100644 --- a/packages/client/ui-settings/tests/apply.spec.ts +++ b/packages/client/ui-settings/tests/apply.spec.ts @@ -83,6 +83,29 @@ describe('ui-settings apply', () => { off() }) + it('projects onboarding entries into stable coordinator order', async () => { + const b = await bench() + declare(b.slots) + await b.ctx.plugin({ inject: [...inject], apply }).await() + const { onboardingSteps } = injectedOf(b.slots).hooks + b.slots.register({ name: 'settings.onboarding', id: 'credential', order: 0 } as never, () => null) + b.slots.register({ name: 'settings.onboarding', id: 'welcome', order: -100 } as never, () => null) + b.slots.register({ name: 'settings.onboarding', id: 'default-order' } as never, () => null) + const steps = onboardingSteps.getSnapshot() + expect(steps).toEqual([ + { id: 'welcome', order: -100 }, + { id: 'credential', order: 0 }, + { id: 'default-order', order: 0 }, + ]) + expect(onboardingSteps.getSnapshot()).toBe(steps) + const listener = vi.fn() + const off = onboardingSteps.subscribe(listener) + b.slots.register({ name: 'settings.onboarding', id: 'later', order: 10 } as never, () => null) + await Promise.resolve() + expect(listener).toHaveBeenCalledOnce() + off() + }) + it('re-registers after an HMR collapse re-declares the slot (stale disposer must not block)', async () => { const b = await bench() const redeclare = declare(b.slots) diff --git a/packages/client/ui-settings/tests/settings-root.spec.tsx b/packages/client/ui-settings/tests/settings-root.spec.tsx index a7df311672..3d0d2e97a4 100644 --- a/packages/client/ui-settings/tests/settings-root.spec.tsx +++ b/packages/client/ui-settings/tests/settings-root.spec.tsx @@ -8,6 +8,7 @@ import { SettingsRoot } from '../src/client/SettingsRoot.tsx' afterEach(cleanup) type Row = { id: string; order: number; label: string } +type Step = { id: string; order: number } /** Slot-content stand-ins: the shell renders whatever the seats contribute. */ const SEAT_CONTENT: Record = { @@ -23,7 +24,11 @@ function mount({ { id: 'general', order: 0, label: 'General' }, { id: 'models', order: 10, label: 'Models' }, ], -}: { wide?: boolean; onboardingActive?: boolean; rows?: Row[] } = {}) { + steps = [ + { id: 'welcome', order: -100 }, + { id: 'credential', order: 0 }, + ], +}: { wide?: boolean; onboardingActive?: boolean; rows?: Row[]; steps?: Step[] } = {}) { // Mutable row source standing in for the bound useSections hook; bump() // plays a ledger change through the same observable contract. let current = rows @@ -46,6 +51,7 @@ function mount({ useSessions, useWorkspaces: unusedHook, wide, + useOnboardingSteps: select => select(steps), useSections: (select) => { const [, force] = useState(0) useEffect(() => { @@ -164,20 +170,30 @@ describe('SettingsPanel navigation', () => { expect(screen.queryByTestId('section-general')).toBeNull() }) - it('hands Hero readiness and a direct section opener to onboarding registrants', () => { + it('mounts onboarding steps in order and transfers ownership only on completion', () => { const { renderSlot } = mount() - const onboardingCall = renderSlot.mock.calls.find(call => call[0] === 'settings.onboarding') - expect(onboardingCall?.[1]).toMatchObject({ active: true }) + const first = renderSlot.mock.calls.find(call => call[0] === 'settings.onboarding') + expect(first?.[1]).toMatchObject({ stepId: 'welcome' }) + expect(first?.[2]).toEqual({ only: 'welcome' }) act(() => { - (onboardingCall?.[1] as { openSection: (id: string) => void }).openSection('models') + (first?.[1] as { complete: () => void }).complete() + ;(first?.[1] as { complete: () => void }).complete() + }) + const onboardingCalls = renderSlot.mock.calls.filter(call => call[0] === 'settings.onboarding') + const second = onboardingCalls.at(-1) + expect(second?.[1]).toMatchObject({ stepId: 'credential' }) + expect(second?.[2]).toEqual({ only: 'credential' }) + + act(() => { + (second?.[1] as { openSection: (id: string) => void }).openSection('models') }) expect(screen.getByRole('dialog')).toBeTruthy() expect(screen.getByTestId('section-models')).toBeTruthy() cleanup() - const active = mount({ onboardingActive: false }).renderSlot.mock.calls - .find(call => call[0] === 'settings.onboarding') - expect(active?.[1]).toMatchObject({ active: false }) + const inactive = mount({ onboardingActive: false }).renderSlot.mock.calls + .filter(call => call[0] === 'settings.onboarding') + expect(inactive).toHaveLength(0) }) it('falls back to the first row when the active entry unregisters', () => { diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml index 990bb14305..7b97762c41 100644 --- a/packages/host/apiproxy/README.i18n.yaml +++ b/packages/host/apiproxy/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/host/apiproxy/README.md -README.md: 0abbeced0902471f7ff8ce9a73d188619ad2b64a -README.zh.md: 315ddb06791b8ce7723f8a5349b6cf576fe971de +README.md: bdf67f7d993df3e0ea7ccd7753c7d492d9d2d904 +README.zh.md: 7b758cfc888dc74ad136a2fc139b856705ee8168 diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md index 0abbeced09..bdf67f7d99 100644 --- a/packages/host/apiproxy/README.md +++ b/packages/host/apiproxy/README.md @@ -26,7 +26,7 @@ Directory picking delegates to the composed `ctx.directoryPicker` backend ([the The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the browser's user-selected model-reference path, so it returns only skills that are both model-invocable and user-invocable; this domain has no direct skill-loading RPC. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream; the carrier's request signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing. -The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves exactly the namespaces a registered configurable provider addresses (`ctx.llm.listConfigurableProviders()`): the seam is general, but this plane is the model-provider surface, so a namespace nothing in the directory names is neither described nor writable here and answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, and the section's `revision`. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired both by `llm/adapters-updated` and by a change to an exposed provider namespace, whose settings carry that provider's catalog and endpoint. The browser carrier restricts the whole configuration plane, reads included (`settings.describe`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin. +The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves a closed allowlist: namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus product-owned `ui-onboarding`. The seam remains general, so any other namespace is neither described nor writable here and answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, and the section's `revision`. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired both by `llm/adapters-updated` and by a change to a provider namespace, whose settings carry that provider's catalog and endpoint; `ui-onboarding` changes do not invalidate models. The browser carrier restricts the whole configuration plane, reads included (`settings.describe`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin. ## Carrier layer (`/client` + root) diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md index 315ddb0679..7b758cfc88 100644 --- a/packages/host/apiproxy/README.zh.md +++ b/packages/host/apiproxy/README.zh.md @@ -26,7 +26,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent(被服务的会话必有 Agent;`command.*` 经由与 `session.*` 相同的路径恢复冷会话,而 `skill.list` 从会话头解析项目根目录,不触碰 Agent 注册表)。`skill.list` 服务于浏览器中由用户选择的模型引用路径,因此仅返回模型和用户均可调用的 skill;该领域没有直接加载 skill 的 RPC。`command.execute` 在宿主侧运行一条斜杠命令行,语义为纯准入:响应报告该行是否解析到处理器,并在解析到时回带铸造的生命周期 `commandId`(将本次确认与流节点关联);结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载;载体的请求信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧:客户端重新拉取 `command.list` 而不是做差分。 -`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域只服务于已注册可配置提供方所指向的那些 namespace(`ctx.llm.listConfigurableProviders()`):seam 本身是通用的,但这个面是模型提供方表层,因此目录中无人点名的 namespace 在这里既不会被描述也不可写入,只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复,因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值(resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖)、`secrets` 槽位列表,以及该分节的 `revision`。`settings.update`/`settings.replace` 写入用户层;`settings.mutate` 则在已存分节上施加路径 op(`set`/`unset`),这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换,会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`;过期的期望值会以 `settings-conflict` 连同两个 revision 作答,而不是覆盖先落地的那个写方,其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应;secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图(`configured`/`source`/`writable`),`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并(休眠条目携带 `active: false`;未声明的存活路由追加在后,不带 settings 地址),`llm.models` 则是与会话无关的目录。三个失效帧让每个面无需轮询即保持收敛:`host/settings-changed {ns}`(`settings/document-updated` 透传,因此解析值未变的原始变更同样能到达客户端)、`host/credentials-changed {ref}`(只带引用名,绝不带值),以及 `host/models-changed`——它既由 `llm/adapters-updated` 触发,也由某个已暴露提供方 namespace 的变更触发,因为该提供方的设置正承载着它的目录与端点。浏览器载体把整个配置面(含读取:`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`)限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。 +`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域只服务于一个封闭的允许列表:已注册可配置提供方所指向的 namespace(`ctx.llm.listConfigurableProviders()`),以及产品持有的 `ui-onboarding`。seam 本身仍是通用的,因此其他 namespace 在这里既不会被描述也不可写入,只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复,因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值(resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖)、`secrets` 槽位列表,以及该分节的 `revision`。`settings.update`/`settings.replace` 写入用户层;`settings.mutate` 则在已存分节上施加路径 op(`set`/`unset`),这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换,会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`;过期的期望值会以 `settings-conflict` 连同两个 revision 作答,而不是覆盖先落地的那个写方,其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应;secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图(`configured`/`source`/`writable`),`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并(休眠条目携带 `active: false`;未声明的存活路由追加在后,不带 settings 地址),`llm.models` 则是与会话无关的目录。三个失效帧让每个面无需轮询即保持收敛:`host/settings-changed {ns}`(`settings/document-updated` 透传,因此解析值未变的原始变更同样能到达客户端)、`host/credentials-changed {ref}`(只带引用名,绝不带值),以及 `host/models-changed`——它既由 `llm/adapters-updated` 触发,也由提供方 namespace 的变更触发,因为该提供方的设置正承载着它的目录与端点;`ui-onboarding` 的变更不会触发模型失效事件。浏览器载体把整个配置面(含读取:`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`)限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。 ## 载体层(`/client` + 根路径) diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index 0990c5253c..364ec1c77d 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -69,6 +69,9 @@ const DEFAULT_MAX_MESSAGES = 50 /** Surface message event types (the pagination counting unit). */ const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message']) +/** Product settings intentionally exposed beside model-provider namespaces. */ +const PRODUCT_SETTINGS_NAMESPACES = new Set(['ui-onboarding']) + /** * Message-boundary pagination: count maxMessages surface messages backwards from * the window tail; the cut is the starting seq of the oldest message group @@ -1014,24 +1017,26 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro } } - /** - * The settings namespaces this proxy serves: exactly those a registered - * configurable provider addresses. The settings seam itself is general — - * any plugin may register a namespace for its own configuration — but the - * Web configuration plane is scoped to model providers, and that boundary - * has to be enforced here rather than assumed from the current plugin set. - * Without it, every future `settings.register()` would silently become - * remotely readable and writable configuration. - */ - function exposedNamespaces(): Set { + /** Settings namespaces whose values can change the model directory. */ + function providerSettingsNamespaces(): Set { return new Set(ctx.llm.listConfigurableProviders().map(entry => entry.settingsNs)) } - /** Refuse a namespace outside the model-provider boundary, naming why. */ + /** + * The settings namespaces this proxy serves: registered configurable + * providers plus a closed product-owned allowlist. The settings seam itself + * is general, so exposure stays explicit here; registering a future + * namespace never makes it remotely readable or writable by accident. + */ + function exposedNamespaces(): Set { + return new Set([...providerSettingsNamespaces(), ...PRODUCT_SETTINGS_NAMESPACES]) + } + + /** Refuse a namespace outside the explicit Web configuration boundary. */ function notExposed(request: RpcRequest, ns: string): RpcResponse { return err(request, { code: 'settings-not-exposed', - message: `settings namespace "${ns}" is not exposed to configuration clients; only a namespace a registered model provider addresses is`, + message: `settings namespace "${ns}" is not exposed to configuration clients`, details: { ns }, }) } @@ -1909,7 +1914,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro // A provider's own settings carry its model catalog and endpoint, // so a change there invalidates the model list even when the route // set is untouched — `llm/adapters-updated` alone misses it. - if (exposedNamespaces().has(String(ns))) queue.push(frame({ type: 'host/models-changed' })) + if (providerSettingsNamespaces().has(String(ns))) queue.push(frame({ type: 'host/models-changed' })) }), ctx.on('credentials/updated', (ref) => { queue.push(frame({ type: 'host/credentials-changed', ref: String(ref) })) diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts index a505f72018..bf077f4f0c 100644 --- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts @@ -222,7 +222,7 @@ describe('settings domain', () => { expect(JSON.stringify(value)).not.toContain('user-secret') }) - it('serves only namespaces a registered model provider addresses', async () => { + it('keeps arbitrary plugin namespaces outside the explicit Web allowlist', async () => { // The settings seam is general: any plugin may register a namespace for // its own configuration. The Web configuration plane is not — it is the // model-provider surface, and a namespace nothing in the provider @@ -248,6 +248,21 @@ describe('settings domain', () => { expect(ctx.settings.describe().find(d => String(d.ns) === 'some-other-plugin')?.value).toEqual({}) }) + it('serves the product onboarding namespace without invalidating the model catalog', async () => { + const ctx = await harness() + ctx.settings.register(settingsNamespace('ui-onboarding'), z.object({ welcomeNoticeVersion: z.string() })) + const api = createApiProxy(ctx, DEFAULTS) + expect(expectOk(await api.settings.describe(request({}))).namespaces.map(view => view.ns)) + .toEqual(['ui-onboarding']) + const frames = await collectHost(api, ['host/settings-changed'], 1, async () => { + expectOk(await api.settings.mutate(request({ + ns: 'ui-onboarding', + ops: [{ op: 'set', path: ['welcomeNoticeVersion'], value: 'v1' }], + }))) + }) + expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'ui-onboarding' }]) + }) + it('refuses even a model-provider namespace once its directory entry is gone', async () => { const ctx = await harness({ configurableProviders: false }) ctx.settings.register(NS, AdapterConfig) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 6dd8389a6f..5b03fca2a5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1559,7 +1559,17 @@ importers: version: 18.3.1 packages/client/ui-settings-general: + dependencies: + '@deepseek-ai/dsh-settings': + specifier: workspace:^ + version: link:../../settings/settings + schemastery: + specifier: ^3.18.0 + version: 3.18.0 devDependencies: + '@deepseek-ai/dsh-client-connection': + specifier: workspace:^ + version: link:../connection '@deepseek-ai/dsh-client-locale': specifier: workspace:^ version: link:../locale @@ -1575,6 +1585,9 @@ importers: '@deepseek-ai/dsh-client-ui-slots': specifier: workspace:^ version: link:../ui-slots + '@deepseek-ai/dsh-client-web-react': + specifier: workspace:^ + version: link:../web-react '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../support/invariants From bfde98d223eea6f2623630e31bb9b081f4057ceb Mon Sep 17 00:00:00 2001 From: Chinesezjc Date: Thu, 30 Jul 2026 22:32:06 +0800 Subject: [PATCH 12/43] test: cover the TUI search-card fallback and refresh the cordis-inspect golden - Add a search result-view scenario to the TUI tool-card test so the card:'search' fallback branch (no view content -> raw result content) is covered; restores transcript.ts branch coverage to 100%. - Refresh the cordis-inspect-jsdoc golden for the kind -> shape rename in the ToolResultView JSDoc that cordis_inspect echoes. --- .../cordis-inspect-jsdoc/session.jsonl | 2 +- packages/ui/tui/tests/tui.spec.ts | 28 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl index 6b50bb2ac0..030612bb80 100644 --- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl +++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl @@ -11,7 +11,7 @@ {"type":"assistant/chunk","seq":9,"time":1783951000009,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":10,"time":1784449176722,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"1ac37046-d1c0-4ef6-9ea9-963e4b46d1cf"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"} {"type":"tool/call","seq":11,"time":1784449176722,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}} -{"type":"tool/result","seq":12,"time":1784449176732,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n /**\n * Register globally or in the calling agent scope. Scoped tools shadow\n * globals; duplicates within one layer and the reserved `run_code` name fail.\n * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n * @returns the exact disposer that unregisters the tool.\n */\n register(definition: ToolDefinition): () => void\n /**\n * Restrict global tools for the calling agent scope. Empty filters, unknown\n * names, scope-local names, and reserved transport names fail. Restrictions\n * intersect; scoped registrations remain visible.\n * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n * @returns the exact disposer that lifts this restriction.\n */\n restrict(filter: ToolRestriction): () => void\n /**\n * Register a monotonic guard after the extensible `tools/pre-execute`\n * waterfall. A plain-context guard applies globally; one registered through\n * `agent.ctx` applies only to that agent. Any matching guard may deny by\n * returning a reason, while no guard can force-allow a call another guard\n * denied. The exact effect disposer is returned for ordered ownership and\n * HMR cleanup.\n * @param guard - synchronous check; a returned string denies the execution.\n * @returns the exact disposer that unregisters the guard.\n */\n guard(guard: ToolGuard): () => void\n /**\n * Look up a tool as one scope sees it (scoped\n * shadows global; a restricted-away global reads as absent). Presenters pass\n * the calling agent so the rendered card matches the definition that\n * actually executed.\n * @param name - the tool name as registered.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns the definition the scope resolves, or undefined when none is visible.\n */\n get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n /**\n * Project visible definitions onto the allowlisted model-facing schema fields,\n * excluding execution and presentation callbacks.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns one deep-cloned schema per visible tool.\n */\n schemas(scope?: ScopeKey): ToolSchema[]\n /**\n * Classify a pending call through the caller's visible tool definition. Only\n * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n * throwing classifiers are exclusive.\n * @param exec - call name, parsed arguments, and optional agent scope.\n * @returns the fail-closed scheduling mode.\n */\n executionMode(exec: ToolExecutionInput): ToolExecutionMode\n /**\n * Execute through pre-policy, guards, around-dispatch, post-policy,\n * definition-owned content finalization, and final notification. Tool and\n * listener failures resolve as materialized error results; an invisible tool\n * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n * snapshot final observers receive. Cancellation\n * arriving after entry and before final result materialization skips a\n * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n * successful started outcome with `ABORTED`; already-started work is still\n * drained and may retain a tool-owned structured error.\n * @param exec - the typed same-process call input. The registry assigns its\n * correlation token before policy begins.\n * @returns the materialized final result.\n */\n async execute(exec: ToolExecutionInput): Promise\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n readonly acceptsNextStep: boolean;\n readonly ctx: Context;\n send(message: UserMessage, options: SendOptions): void;\n updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n }\n export type AgentCancelCause = {\n readonly kind: 'user';\n } | {\n readonly kind: 'parent';\n };\n export interface AgentOptions {\n provider?: string;\n model?: string;\n maxTokens?: number;\n }\n export type AgentStatus = 'idle' | 'running';\n export interface AssistantMessage extends Message {\n readonly role: 'assistant';\n readonly source: ModelMessageSource;\n }\n export interface AssistantProvenance {\n provider: string;\n model: string;\n replayState?: unknown;\n }\n export type Branded = string & {\n readonly [BRAND]: B;\n };\n export type CallId = Branded<'CallId'>;\n export interface CancelOptions {\n keepInbox?: boolean;\n }\n export interface ContentBlockMap {\n 'text': TextBlock;\n 'reasoning': ReasoningBlock;\n 'tool-call': ToolCallBlock;\n 'tool-result': ToolResultBlock;\n }\n export type ContentBlockType = keyof ContentBlockMap;\n export interface DiffCallView {\n card: 'diff';\n title: string;\n diffs: FileDiff[];\n locations?: FileLocation[];\n }\n export interface DiffResultView {\n card: 'diff';\n title?: string;\n diffs: FileDiff[];\n }\n export interface EpochHeader {\n config: LlmCallConfig;\n system?: string;\n tools?: ToolSchema[];\n }\n export interface FileDiff {\n path: string;\n oldText: string | null;\n newText: string;\n }\n export interface FileLocation {\n path: string;\n line?: number;\n }\n export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n export interface FinishReasonMap {\n 'stop': {\n kind: 'stop';\n };\n 'tool-calls': {\n kind: 'tool-calls';\n };\n 'max-tokens': {\n kind: 'max-tokens';\n };\n 'aborted': {\n kind: 'aborted';\n failure: LlmFailure;\n };\n 'error': {\n kind: 'error';\n failure: LlmFailure;\n };\n }\n export interface GenericCallView {\n card: 'generic';\n title: string;\n kind?: ToolCallKind;\n rawInput?: unknown;\n content?: ContentBlock[];\n locations?: FileLocation[];\n }\n export interface GenericResultView {\n card: 'generic';\n title?: string;\n content?: ContentBlock[];\n }\n export type InboxAction = {\n readonly kind: 'edit';\n readonly content: ContentBlock[];\n } | {\n readonly kind: 'remove';\n };\n export type InboxActionResult = 'applied' | 'not-found';\n export type InboxItemId = Branded<'InboxItemId'>;\n export interface JsonSchemaNode {\n type?: JsonSchemaType;\n oneOf?: JsonSchemaNode[];\n properties?: Record;\n required?: string[];\n additionalProperties?: boolean;\n items?: JsonSchemaNode;\n enum?: JsonSchemaScalar[];\n const?: JsonSchemaScalar;\n description?: string;\n title?: string;\n default?: JsonValue;\n examples?: JsonValue;\n }\n export type JsonSchemaScalar = string | number | boolean | null;\n export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n export type JsonValue = null | boolean | number | string | JsonValue[] | {\n [key: string]: JsonValue;\n };\n export interface LlmCallConfig {\n provider: string;\n model: string;\n reasoningEffort?: ReasoningEffortId;\n temperature?: number;\n maxTokens?: number;\n stop?: string[];\n }\n export interface LlmFailure {\n readonly message: string;\n readonly code: string;\n readonly status?: number;\n readonly providerRetryAfterMs?: number;\n readonly requestId?: ProviderRequestId;\n }\n export interface Message {\n readonly id: MessageId;\n readonly role: 'system' | 'user' | 'assistant';\n readonly content: ContentBlock[];\n readonly source: MessageSource;\n }\n export type MessageId = Branded<'MessageId'>;\n export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n export interface MessageSourceMap {\n user: {\n kind: 'user';\n };\n plugin: {\n kind: 'plugin';\n plugin: string;\n };\n model: ModelMessageSource;\n tool: ToolMessageSource;\n }\n export interface ModelMessageSource extends AssistantProvenance {\n kind: 'model';\n }\n export type ProviderRequestId = Branded<'ProviderRequestId'>;\n export interface ReasoningBlock {\n type: 'reasoning';\n text: string;\n }\n export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n export type ScopeKey = object;\n export interface SearchFileMatches {\n path: string;\n matches: SearchLineMatch[];\n }\n export interface SearchLineMatch {\n lineNumber: number;\n line: string;\n }\n export interface SearchMatchesResultView {\n card: 'search';\n kind: 'matches';\n title?: string;\n files: SearchFileMatches[];\n truncated: boolean;\n total: number;\n content?: ContentBlock[];\n }\n export interface SearchPathsResultView {\n card: 'search';\n kind: 'paths';\n title?: string;\n paths: string[];\n truncated: boolean;\n total: number;\n content?: ContentBlock[];\n }\n export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n export interface SendOptions {\n target: SendTarget;\n wakeup: boolean;\n }\n export type SendTarget = 'next-turn' | 'next-step';\n export class Session {\n get surface(): SessionSurface;\n readonly header: SessionHeader;\n get id(): SessionId;\n readonly firstLiveSeq: number;\n constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n get events(): readonly SessionEvent[];\n get seq(): number;\n append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n opts: SurfaceIntent\n ] : [\n ]): SessionEvent;\n requestHeader(): EpochHeader | undefined;\n deriveMessages(): Message[];\n deriveEventMessage(event: SessionEvent): Message | null;\n }\n export type SessionEvent = {\n [K in SessionEventType]: {\n type: K;\n seq: number;\n time: number;\n data: SessionEventMap[K];\n } & (K extends SurfaceEventType ? {\n sourceEventSeqs?: number[];\n surfaceOp?: SurfaceOp;\n } : object);\n }[T];\n export interface SessionEventMap {\n 'turn/start': {\n turn: number;\n trigger: TurnTrigger;\n };\n 'turn/end': {\n turn: number;\n reason: TurnEndReason;\n };\n 'step/start': {\n turn: number;\n step: number;\n };\n 'step/end': {\n turn: number;\n step: number;\n };\n 'user/message': UserMessage;\n 'assistant/chunk': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n 'assistant/message': {\n turn: number;\n step: number;\n message: AssistantMessage;\n usage?: TokenUsage;\n };\n 'tool/call': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n 'tool/result': {\n turn: number;\n step: number;\n message: ToolResultMessage;\n error?: {\n name: string;\n code: string;\n };\n meta?: JsonValue;\n };\n 'steering/message': {\n turn: number;\n message: UserMessage;\n };\n 'todo/write': {\n todos: TodoItem[];\n };\n 'request/header': {\n header: EpochHeader;\n reason: RequestHeaderReason;\n };\n 'session/end-seed': Record;\n }\n export type SessionEventType = keyof SessionEventMap;\n export interface SessionHeader {\n readonly version: number;\n readonly id: SessionId;\n readonly createdAt: number;\n readonly cwd?: string;\n readonly parentSession?: SessionId;\n readonly seedLength?: number;\n readonly delegationDepth?: number;\n }\n export type SessionId = Branded<'SessionId'>;\n export interface SessionSurface {\n readonly nodes: readonly number[];\n readonly replaceGeneration: number;\n }\n export type StreamChunk = {\n type: 'block-start';\n index: number;\n blockType: ContentBlockType;\n } | {\n type: 'text-delta';\n index: number;\n text: string;\n } | {\n type: 'reasoning-delta';\n index: number;\n text: string;\n } | {\n type: 'tool-call-delta';\n index: number;\n id: CallId;\n name?: string;\n argumentsDelta: string;\n } | {\n type: 'block-end';\n index: number;\n block: ContentBlock;\n } | {\n type: 'usage';\n usage: TokenUsage;\n } | {\n type: 'finish';\n reason: FinishReason;\n replayState?: unknown;\n };\n export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result' | 'steering/message';\n export interface SurfaceIntent {\n surfaceOp: SurfaceOp;\n sourceEventSeqs?: number[];\n }\n export type SurfaceOp = 'append' | {\n op: 'replace';\n start: number;\n end: number;\n };\n export interface TerminalCallView {\n card: 'terminal';\n title: string;\n description?: string;\n cwd?: string;\n }\n export interface TerminalResultView {\n card: 'terminal';\n title?: string;\n output?: string;\n exitCode?: number;\n signal?: string;\n }\n export interface TodoItem {\n content: string;\n status: 'pending' | 'in_progress' | 'completed';\n }\n export interface TokenUsage {\n inputTokens: number;\n outputTokens: number;\n cacheReadTokens?: number;\n cacheWriteTokens?: number;\n reasoningTokens?: number;\n }\n export interface ToolCallBlock {\n type: 'tool-call';\n id: CallId;\n name: string;\n arguments: string;\n }\n export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n export interface ToolDefinition extends ToolSchema {\n readonly output: ToolOutputDefinition;\n execute(args: unknown, exec: ToolRunContext): Promise;\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\n timeoutMs?: number;\n isConcurrencySafe?(args: unknown): boolean;\n presentCall?(args: unknown): ToolCallView | undefined;\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n }\n export interface ToolErrorInfo {\n name: string;\n code: string;\n }\n export interface ToolExecution extends ToolExecutionInput {\n readonly token: ToolExecutionToken;\n }\n export interface ToolExecutionFailure {\n readonly isError: true;\n readonly error: ToolFailure;\n readonly value?: never;\n readonly content: ContentBlock[];\n readonly meta?: JsonValue;\n readonly additionalContexts?: UserMessage[];\n readonly concludesTurn?: never;\n }\n export interface ToolExecutionInput {\n readonly callId: CallId;\n readonly name: string;\n readonly arguments: unknown;\n readonly agent?: Agent;\n readonly parent?: ToolExecutionToken;\n readonly signal: AbortSignal;\n }\n export type ToolExecutionMode = {\n kind: 'parallel';\n } | {\n kind: 'exclusive';\n };\n export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n export interface ToolExecutionSuccess {\n readonly isError: false;\n readonly value: JsonValue;\n readonly content: ContentBlock[];\n readonly error?: never;\n readonly meta?: JsonValue;\n readonly additionalContexts?: UserMessage[];\n readonly concludesTurn?: true;\n }\n export type ToolExecutionToken = symbol & {\n readonly [toolExecutionTokenBrand]: true;\n };\n export interface ToolFailure {\n message: string;\n info?: ToolErrorInfo;\n }\n export type ToolGuard = (execution: Readonly) => string | undefined;\n export interface ToolMessageSource {\n kind: 'tool';\n callId: CallId;\n }\n export interface ToolOutputDefinition {\n readonly schema: JsonSchemaNode;\n render(args: unknown, value: JsonValue): ContentBlock[];\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n }\n export interface ToolRestriction {\n readonly allow?: readonly string[];\n readonly deny?: readonly string[];\n }\n export interface ToolResult {\n content: ContentBlock[];\n isError: boolean;\n meta?: JsonValue;\n }\n export interface ToolResultBlock {\n type: 'tool-result';\n toolCallId: CallId;\n content: ContentBlock[];\n isError?: boolean;\n }\n export interface ToolResultMessage extends Message {\n readonly role: 'user';\n readonly content: [\n ToolResultBlock\n ];\n readonly source: ToolMessageSource;\n }\n export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView;\n export interface ToolRunContext extends ToolExecution {\n deferContext(context: UserMessage): void;\n concludeTurn(): void;\n }\n export interface ToolSchema {\n name: string;\n description: string;\n parameters: Record;\n }\n export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n export interface TurnEndReasonMap {\n completed: {\n kind: 'completed';\n };\n aborted: {\n kind: 'aborted';\n };\n error: {\n kind: 'error';\n step: number;\n } & ({\n failure: LlmFailure;\n message?: never;\n code?: never;\n } | {\n message: string;\n code?: string;\n failure?: never;\n });\n disposed: {\n kind: 'disposed';\n };\n 'max-tokens': {\n kind: 'max-tokens';\n };\n interrupted: {\n kind: 'interrupted';\n };\n }\n export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n export interface TurnTriggerMap {\n message: {\n kind: 'message';\n source: MessageSource;\n };\n retry: {\n kind: 'retry';\n };\n injection: {\n kind: 'injection';\n source: MessageSource;\n };\n }\n export interface UserMessage extends Message {\n readonly role: 'user';\n }"}],"isError":false}],"role":"user","id":"1c43b8df-aae8-42e7-8253-5b275edc09bc"}},"sourceEventSeqs":[11],"surfaceOp":"append"} +{"type":"tool/result","seq":12,"time":1784449176732,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n /**\n * Register globally or in the calling agent scope. Scoped tools shadow\n * globals; duplicates within one layer and the reserved `run_code` name fail.\n * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n * @returns the exact disposer that unregisters the tool.\n */\n register(definition: ToolDefinition): () => void\n /**\n * Restrict global tools for the calling agent scope. Empty filters, unknown\n * names, scope-local names, and reserved transport names fail. Restrictions\n * intersect; scoped registrations remain visible.\n * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n * @returns the exact disposer that lifts this restriction.\n */\n restrict(filter: ToolRestriction): () => void\n /**\n * Register a monotonic guard after the extensible `tools/pre-execute`\n * waterfall. A plain-context guard applies globally; one registered through\n * `agent.ctx` applies only to that agent. Any matching guard may deny by\n * returning a reason, while no guard can force-allow a call another guard\n * denied. The exact effect disposer is returned for ordered ownership and\n * HMR cleanup.\n * @param guard - synchronous check; a returned string denies the execution.\n * @returns the exact disposer that unregisters the guard.\n */\n guard(guard: ToolGuard): () => void\n /**\n * Look up a tool as one scope sees it (scoped\n * shadows global; a restricted-away global reads as absent). Presenters pass\n * the calling agent so the rendered card matches the definition that\n * actually executed.\n * @param name - the tool name as registered.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns the definition the scope resolves, or undefined when none is visible.\n */\n get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n /**\n * Project visible definitions onto the allowlisted model-facing schema fields,\n * excluding execution and presentation callbacks.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns one deep-cloned schema per visible tool.\n */\n schemas(scope?: ScopeKey): ToolSchema[]\n /**\n * Classify a pending call through the caller's visible tool definition. Only\n * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n * throwing classifiers are exclusive.\n * @param exec - call name, parsed arguments, and optional agent scope.\n * @returns the fail-closed scheduling mode.\n */\n executionMode(exec: ToolExecutionInput): ToolExecutionMode\n /**\n * Execute through pre-policy, guards, around-dispatch, post-policy,\n * definition-owned content finalization, and final notification. Tool and\n * listener failures resolve as materialized error results; an invisible tool\n * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n * snapshot final observers receive. Cancellation\n * arriving after entry and before final result materialization skips a\n * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n * successful started outcome with `ABORTED`; already-started work is still\n * drained and may retain a tool-owned structured error.\n * @param exec - the typed same-process call input. The registry assigns its\n * correlation token before policy begins.\n * @returns the materialized final result.\n */\n async execute(exec: ToolExecutionInput): Promise\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n export interface Agent {\n readonly id: SessionId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n readonly acceptsNextStep: boolean;\n readonly ctx: Context;\n send(message: UserMessage, options: SendOptions): void;\n updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n whenIdle(): Promise;\n followup(message: UserMessage): void;\n steer(message: UserMessage): void;\n inject(message: UserMessage): void;\n }\n export type AgentCancelCause = {\n readonly kind: 'user';\n } | {\n readonly kind: 'parent';\n };\n export interface AgentOptions {\n provider?: string;\n model?: string;\n maxTokens?: number;\n }\n export type AgentStatus = 'idle' | 'running';\n export interface AssistantMessage extends Message {\n readonly role: 'assistant';\n readonly source: ModelMessageSource;\n }\n export interface AssistantProvenance {\n provider: string;\n model: string;\n replayState?: unknown;\n }\n export type Branded = string & {\n readonly [BRAND]: B;\n };\n export type CallId = Branded<'CallId'>;\n export interface CancelOptions {\n keepInbox?: boolean;\n }\n export interface ContentBlockMap {\n 'text': TextBlock;\n 'reasoning': ReasoningBlock;\n 'tool-call': ToolCallBlock;\n 'tool-result': ToolResultBlock;\n }\n export type ContentBlockType = keyof ContentBlockMap;\n export interface DiffCallView {\n card: 'diff';\n title: string;\n diffs: FileDiff[];\n locations?: FileLocation[];\n }\n export interface DiffResultView {\n card: 'diff';\n title?: string;\n diffs: FileDiff[];\n }\n export interface EpochHeader {\n config: LlmCallConfig;\n system?: string;\n tools?: ToolSchema[];\n }\n export interface FileDiff {\n path: string;\n oldText: string | null;\n newText: string;\n }\n export interface FileLocation {\n path: string;\n line?: number;\n }\n export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n export interface FinishReasonMap {\n 'stop': {\n kind: 'stop';\n };\n 'tool-calls': {\n kind: 'tool-calls';\n };\n 'max-tokens': {\n kind: 'max-tokens';\n };\n 'aborted': {\n kind: 'aborted';\n failure: LlmFailure;\n };\n 'error': {\n kind: 'error';\n failure: LlmFailure;\n };\n }\n export interface GenericCallView {\n card: 'generic';\n title: string;\n kind?: ToolCallKind;\n rawInput?: unknown;\n content?: ContentBlock[];\n locations?: FileLocation[];\n }\n export interface GenericResultView {\n card: 'generic';\n title?: string;\n content?: ContentBlock[];\n }\n export type InboxAction = {\n readonly kind: 'edit';\n readonly content: ContentBlock[];\n } | {\n readonly kind: 'remove';\n };\n export type InboxActionResult = 'applied' | 'not-found';\n export type InboxItemId = Branded<'InboxItemId'>;\n export interface JsonSchemaNode {\n type?: JsonSchemaType;\n oneOf?: JsonSchemaNode[];\n properties?: Record;\n required?: string[];\n additionalProperties?: boolean;\n items?: JsonSchemaNode;\n enum?: JsonSchemaScalar[];\n const?: JsonSchemaScalar;\n description?: string;\n title?: string;\n default?: JsonValue;\n examples?: JsonValue;\n }\n export type JsonSchemaScalar = string | number | boolean | null;\n export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n export type JsonValue = null | boolean | number | string | JsonValue[] | {\n [key: string]: JsonValue;\n };\n export interface LlmCallConfig {\n provider: string;\n model: string;\n reasoningEffort?: ReasoningEffortId;\n temperature?: number;\n maxTokens?: number;\n stop?: string[];\n }\n export interface LlmFailure {\n readonly message: string;\n readonly code: string;\n readonly status?: number;\n readonly providerRetryAfterMs?: number;\n readonly requestId?: ProviderRequestId;\n }\n export interface Message {\n readonly id: MessageId;\n readonly role: 'system' | 'user' | 'assistant';\n readonly content: ContentBlock[];\n readonly source: MessageSource;\n }\n export type MessageId = Branded<'MessageId'>;\n export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n export interface MessageSourceMap {\n user: {\n kind: 'user';\n };\n plugin: {\n kind: 'plugin';\n plugin: string;\n };\n model: ModelMessageSource;\n tool: ToolMessageSource;\n }\n export interface ModelMessageSource extends AssistantProvenance {\n kind: 'model';\n }\n export type ProviderRequestId = Branded<'ProviderRequestId'>;\n export interface ReasoningBlock {\n type: 'reasoning';\n text: string;\n }\n export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n export type ScopeKey = object;\n export interface SearchFileMatches {\n path: string;\n matches: SearchLineMatch[];\n }\n export interface SearchLineMatch {\n lineNumber: number;\n line: string;\n }\n export interface SearchMatchesResultView {\n card: 'search';\n shape: 'matches';\n title?: string;\n files: SearchFileMatches[];\n truncated: boolean;\n total: number;\n }\n export interface SearchPathsResultView {\n card: 'search';\n shape: 'paths';\n title?: string;\n paths: string[];\n truncated: boolean;\n total: number;\n }\n export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n export interface SendOptions {\n target: SendTarget;\n wakeup: boolean;\n }\n export type SendTarget = 'next-turn' | 'next-step';\n export class Session {\n get surface(): SessionSurface;\n readonly header: SessionHeader;\n get id(): SessionId;\n readonly firstLiveSeq: number;\n constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);\n get events(): readonly SessionEvent[];\n get seq(): number;\n append(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n opts: SurfaceIntent\n ] : [\n ]): SessionEvent;\n requestHeader(): EpochHeader | undefined;\n deriveMessages(): Message[];\n deriveEventMessage(event: SessionEvent): Message | null;\n }\n export type SessionEvent = {\n [K in SessionEventType]: {\n type: K;\n seq: number;\n time: number;\n data: SessionEventMap[K];\n } & (K extends SurfaceEventType ? {\n sourceEventSeqs?: number[];\n surfaceOp?: SurfaceOp;\n } : object);\n }[T];\n export interface SessionEventMap {\n 'turn/start': {\n turn: number;\n trigger: TurnTrigger;\n };\n 'turn/end': {\n turn: number;\n reason: TurnEndReason;\n };\n 'step/start': {\n turn: number;\n step: number;\n };\n 'step/end': {\n turn: number;\n step: number;\n };\n 'user/message': UserMessage;\n 'assistant/chunk': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n 'assistant/message': {\n turn: number;\n step: number;\n message: AssistantMessage;\n usage?: TokenUsage;\n };\n 'tool/call': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n 'tool/result': {\n turn: number;\n step: number;\n message: ToolResultMessage;\n error?: {\n name: string;\n code: string;\n };\n meta?: JsonValue;\n };\n 'steering/message': {\n turn: number;\n message: UserMessage;\n };\n 'todo/write': {\n todos: TodoItem[];\n };\n 'request/header': {\n header: EpochHeader;\n reason: RequestHeaderReason;\n };\n 'session/end-seed': Record;\n }\n export type SessionEventType = keyof SessionEventMap;\n export interface SessionHeader {\n readonly version: number;\n readonly id: SessionId;\n readonly createdAt: number;\n readonly cwd?: string;\n readonly parentSession?: SessionId;\n readonly seedLength?: number;\n readonly delegationDepth?: number;\n }\n export type SessionId = Branded<'SessionId'>;\n export interface SessionSurface {\n readonly nodes: readonly number[];\n readonly replaceGeneration: number;\n }\n export type StreamChunk = {\n type: 'block-start';\n index: number;\n blockType: ContentBlockType;\n } | {\n type: 'text-delta';\n index: number;\n text: string;\n } | {\n type: 'reasoning-delta';\n index: number;\n text: string;\n } | {\n type: 'tool-call-delta';\n index: number;\n id: CallId;\n name?: string;\n argumentsDelta: string;\n } | {\n type: 'block-end';\n index: number;\n block: ContentBlock;\n } | {\n type: 'usage';\n usage: TokenUsage;\n } | {\n type: 'finish';\n reason: FinishReason;\n replayState?: unknown;\n };\n export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result' | 'steering/message';\n export interface SurfaceIntent {\n surfaceOp: SurfaceOp;\n sourceEventSeqs?: number[];\n }\n export type SurfaceOp = 'append' | {\n op: 'replace';\n start: number;\n end: number;\n };\n export interface TerminalCallView {\n card: 'terminal';\n title: string;\n description?: string;\n cwd?: string;\n }\n export interface TerminalResultView {\n card: 'terminal';\n title?: string;\n output?: string;\n exitCode?: number;\n signal?: string;\n }\n export interface TodoItem {\n content: string;\n status: 'pending' | 'in_progress' | 'completed';\n }\n export interface TokenUsage {\n inputTokens: number;\n outputTokens: number;\n cacheReadTokens?: number;\n cacheWriteTokens?: number;\n reasoningTokens?: number;\n }\n export interface ToolCallBlock {\n type: 'tool-call';\n id: CallId;\n name: string;\n arguments: string;\n }\n export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n export interface ToolDefinition extends ToolSchema {\n readonly output: ToolOutputDefinition;\n execute(args: unknown, exec: ToolRunContext): Promise;\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\n timeoutMs?: number;\n isConcurrencySafe?(args: unknown): boolean;\n presentCall?(args: unknown): ToolCallView | undefined;\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n }\n export interface ToolErrorInfo {\n name: string;\n code: string;\n }\n export interface ToolExecution extends ToolExecutionInput {\n readonly token: ToolExecutionToken;\n }\n export interface ToolExecutionFailure {\n readonly isError: true;\n readonly error: ToolFailure;\n readonly value?: never;\n readonly content: ContentBlock[];\n readonly meta?: JsonValue;\n readonly additionalContexts?: UserMessage[];\n readonly concludesTurn?: never;\n }\n export interface ToolExecutionInput {\n readonly callId: CallId;\n readonly name: string;\n readonly arguments: unknown;\n readonly agent?: Agent;\n readonly parent?: ToolExecutionToken;\n readonly signal: AbortSignal;\n }\n export type ToolExecutionMode = {\n kind: 'parallel';\n } | {\n kind: 'exclusive';\n };\n export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n export interface ToolExecutionSuccess {\n readonly isError: false;\n readonly value: JsonValue;\n readonly content: ContentBlock[];\n readonly error?: never;\n readonly meta?: JsonValue;\n readonly additionalContexts?: UserMessage[];\n readonly concludesTurn?: true;\n }\n export type ToolExecutionToken = symbol & {\n readonly [toolExecutionTokenBrand]: true;\n };\n export interface ToolFailure {\n message: string;\n info?: ToolErrorInfo;\n }\n export type ToolGuard = (execution: Readonly) => string | undefined;\n export interface ToolMessageSource {\n kind: 'tool';\n callId: CallId;\n }\n export interface ToolOutputDefinition {\n readonly schema: JsonSchemaNode;\n render(args: unknown, value: JsonValue): ContentBlock[];\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n }\n export interface ToolRestriction {\n readonly allow?: readonly string[];\n readonly deny?: readonly string[];\n }\n export interface ToolResult {\n content: ContentBlock[];\n isError: boolean;\n meta?: JsonValue;\n }\n export interface ToolResultBlock {\n type: 'tool-result';\n toolCallId: CallId;\n content: ContentBlock[];\n isError?: boolean;\n }\n export interface ToolResultMessage extends Message {\n readonly role: 'user';\n readonly content: [\n ToolResultBlock\n ];\n readonly source: ToolMessageSource;\n }\n export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView;\n export interface ToolRunContext extends ToolExecution {\n deferContext(context: UserMessage): void;\n concludeTurn(): void;\n }\n export interface ToolSchema {\n name: string;\n description: string;\n parameters: Record;\n }\n export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n export interface TurnEndReasonMap {\n completed: {\n kind: 'completed';\n };\n aborted: {\n kind: 'aborted';\n };\n error: {\n kind: 'error';\n step: number;\n } & ({\n failure: LlmFailure;\n message?: never;\n code?: never;\n } | {\n message: string;\n code?: string;\n failure?: never;\n });\n disposed: {\n kind: 'disposed';\n };\n 'max-tokens': {\n kind: 'max-tokens';\n };\n interrupted: {\n kind: 'interrupted';\n };\n }\n export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];\n export interface TurnTriggerMap {\n message: {\n kind: 'message';\n source: MessageSource;\n };\n retry: {\n kind: 'retry';\n };\n injection: {\n kind: 'injection';\n source: MessageSource;\n };\n }\n export interface UserMessage extends Message {\n readonly role: 'user';\n }"}],"isError":false}],"role":"user","id":"1c43b8df-aae8-42e7-8253-5b275edc09bc"}},"sourceEventSeqs":[11],"surfaceOp":"append"} {"type":"step/end","seq":13,"time":1784449176732,"data":{"turn":1,"step":1}} {"type":"step/start","seq":14,"time":1784449176733,"data":{"turn":1,"step":2}} {"type":"assistant/chunk","seq":15,"time":1783951000015,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 445487065f..2915f600b9 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -4368,6 +4368,20 @@ describe('tool cards and surface replay', () => { presentCall: () => ({ card: 'generic', title: 'Becomes terminal' }), presentResult: () => ({ card: 'terminal', output: 'converted terminal' }), }, + // A search card carries no result text of its own; the TUI has no dedicated + // search arm and falls back to the raw result content, rendered as the same + // dim generic body a pre-search-card grep/glob result showed. + search: { + name: 'search', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [], + presentCall: () => ({ card: 'generic', title: 'Grep todo', kind: 'search' }), + presentResult: () => ({ + card: 'search', + shape: 'matches', + files: [{ path: 'a.ts', matches: [{ lineNumber: 1, line: 'todo one' }] }], + truncated: false, + total: 1, + }), + }, symbolic: { name: 'symbolic', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [], presentCall: () => ({ card: 'generic', title: 'Symbol input', rawInput: Symbol('input') }), @@ -4396,6 +4410,7 @@ describe('tool cards and surface replay', () => { ['c11', 'terminalResult', '{}'], ['c12', 'symbolic', '{}'], ['c13', 'knownXml', '{}'], + ['c16', 'search', '{"pattern":"todo"}'], ] as const appendAssistant(result.session, [ { type: 'text', text: 'Calling tools' }, @@ -4489,6 +4504,14 @@ describe('tool cards and surface replay', () => { isError: false, }), }, { surfaceOp: 'append' }) + result.session.append('tool/result', { + turn: 1, step: 1, + message: createToolResultMessage({ + callId: 'c16' as never, + content: [{ type: 'text', text: 'Found 1 match\n\na.ts\nLine 1: todo one' }], + isError: false, + }), + }, { surfaceOp: 'append' }) result.session.append('tool/result', { turn: 1, step: 1, @@ -4520,6 +4543,11 @@ describe('tool cards and surface replay', () => { expect(output).toContain('$ blank desc command') // A card whose title only repeats the name renders header-only (empty body). expect(output).toContain('Tool / emptyBody') + // A search result view carries no `content` of its own, so the card renders + // the raw model-facing result text through the same dim generic body — the + // TUI has no dedicated search arm. + expect(output).toContain('Tool / search') + expect(output).toContain('Line 1: todo one') // A diff card drops its title (the paths + change footer carry the meaning). // The first file's path is head-visible; the second file and the change // footer sit past this card's 4-line budget and appear only when expanded. From 7d97418d42b6bb705b40d614c66b9869aaba3c7c Mon Sep 17 00:00:00 2001 From: Chinesezjc Date: Thu, 30 Jul 2026 22:33:03 +0800 Subject: [PATCH 13/43] test(web): refresh code-mode-round golden for read error state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The nested read of a missing file surfaces its error state as 失败 in the code-dispatch row summary, a consequence of this PR's read-card error presentation. The golden predated it (never re-recorded while the PR was conflicting); refreshed keyless via DSH_SNAPSHOT=refresh over the existing session.jsonl. --- apps/web/tests/snapshots/code-mode-round/ui.expected.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/web/tests/snapshots/code-mode-round/ui.expected.md b/apps/web/tests/snapshots/code-mode-round/ui.expected.md index 0282a16f80..eb1e04d4c1 100644 --- a/apps/web/tests/snapshots/code-mode-round/ui.expected.md +++ b/apps/web/tests/snapshots/code-mode-round/ui.expected.md @@ -20,7 +20,7 @@ - img - text: Code Run bash echo and catch missing file read - img -- text: Bash Echo CODE_ROUND_OK Read +- text: Bash Echo CODE_ROUND_OK 失败 Read - button "missing.txt" - button "Think The program ran successfully. Let me now reply DONE as instructed.": - img From 05d48f291815f43e0eb8a018475dcfbb66248a1c Mon Sep 17 00:00:00 2001 From: Chinesezjc Date: Thu, 30 Jul 2026 22:40:39 +0800 Subject: [PATCH 14/43] fix(web-read-card): carry the base's required read offset in fixtures and specs The base's ReadResultView now requires `offset` (persisted so an empty window still knows its start). The connection fixture's read sample and read-card.spec's resultRead helper supply it (the window's first line, 41). --- packages/client/connection/src/client/fixture.ts | 2 +- packages/client/ui-conversation/tests/read-card.spec.tsx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts index 0a2379c70e..3cc7bffa78 100644 --- a/packages/client/connection/src/client/fixture.ts +++ b/packages/client/connection/src/client/fixture.ts @@ -397,7 +397,7 @@ function presentResult(name: string, argsRaw: string, resultText: string): ToolR // so `call.card` alone does not distinguish it from edit/write. if (name === 'read') { return { - card: 'read', path: READ_SAMPLE_PATH, lines: READ_SAMPLE_LINES, + card: 'read', path: READ_SAMPLE_PATH, offset: READ_SAMPLE_FIRST_LINE, lines: READ_SAMPLE_LINES, totalLines: READ_SAMPLE_TOTAL, lang: 'ts', content: text(resultText), } } diff --git a/packages/client/ui-conversation/tests/read-card.spec.tsx b/packages/client/ui-conversation/tests/read-card.spec.tsx index d5804b505b..79c7ab1392 100644 --- a/packages/client/ui-conversation/tests/read-card.spec.tsx +++ b/packages/client/ui-conversation/tests/read-card.spec.tsx @@ -46,7 +46,7 @@ const sampleLines = [ /** The read tool's own result view for a settled file read. */ const resultRead = (over?: Partial>): ToolResultView => ({ - card: 'read', path: 'src/a.ts', lines: sampleLines, totalLines: 180, lang: 'ts', ...over, + card: 'read', path: 'src/a.ts', offset: 41, lines: sampleLines, totalLines: 180, lang: 'ts', ...over, }) const running = (over?: Partial): RunningToolCall => ({ From 04f8b30db151462e9f21ecee9176c30cbfb70d36 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Thu, 30 Jul 2026 22:58:52 +0800 Subject: [PATCH 15/43] fix(web): make the welcome notice scan-first --- ...versioned-gui-welcome-onboarding.i18n.yaml | 4 +- ...-07-30-versioned-gui-welcome-onboarding.md | 2 +- ...-30-versioned-gui-welcome-onboarding.zh.md | 2 +- .../tests/onboarding-deepseek-config.e2e.ts | 4 +- .../welcome.expected.md | 12 ++- .../src/client/WelcomeNotice.module.css | 96 ++++++++++++++++--- .../src/client/WelcomeNotice.tsx | 32 ++++--- .../ui-settings-general/src/client/locales.ts | 20 ++-- .../src/onboarding-copy.ts | 26 ++--- .../tests/welcome-notice.spec.tsx | 14 ++- 10 files changed, 150 insertions(+), 62 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml index 24bdee3b68..db1397809e 100644 --- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.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-30-versioned-gui-welcome-onboarding.md -2026-07-30-versioned-gui-welcome-onboarding.md: 405c6fe833d995123cd15e5694cd5ef75a0cd03d -2026-07-30-versioned-gui-welcome-onboarding.zh.md: ea83aa958866ab3dcca749f362d43e4b29408e02 +2026-07-30-versioned-gui-welcome-onboarding.md: 06ac9fbe5c10db872c7ea3989ff2e14f756965a0 +2026-07-30-versioned-gui-welcome-onboarding.zh.md: e2d726368e6282e4f6043c225b665c1945228f2d diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md index 405c6fe833..06ac9fbe5c 100644 --- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md +++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md @@ -18,7 +18,7 @@ The GUI's credential onboarding begins with a DeepSeek-specific readiness check, **Concurrent views converge without stale replacement.** The acknowledgement write omits `expectedRevision` deliberately: every tab writes the same version to one path, so the operation is idempotent and preserves sibling fields instead of rebuilding the section. `settings/document-updated` becomes `host/settings-changed`; an already mounted tab refetches and advances when another tab or an external editor commits the current version. The API proxy exposes this one product namespace through a closed allowlist beside configurable-provider namespaces, without treating its changes as model-catalog invalidations. -**The welcome modal has one completion path.** It renders no close icon or secondary action, installs no Escape handler, and assigns no click handler to the mask. Its mask starts below the 80 px top chrome and preserves `position:absolute`, zero left/right/bottom offsets, `rgba(0, 0, 0, 0.24)`, and `backdrop-filter: blur(2px)`. Continue is the sole button and receives initial focus. +**The welcome modal is scan-first and has one completion path.** Its hierarchy is a declaration title, one status sentence, one emphasized feedback callout, one consequence sentence, and a restrained quotation; the notice version changes whenever that authored copy changes materially. It renders no close icon or secondary action, installs no Escape handler, and assigns no click handler to the mask. Its mask starts below the 80 px top chrome and preserves `position:absolute`, zero left/right/bottom offsets, `rgba(0, 0, 0, 0.24)`, and `backdrop-filter: blur(2px)`. Continue is the sole button and receives initial focus. ## Alternatives considered diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md index ea83aa9588..e2d726368e 100644 --- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md +++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md @@ -18,7 +18,7 @@ GUI 的凭据引导从 DeepSeek 专用的就绪状态检查开始,但内部测 **并发视图无需陈旧的整体替换即可收敛。** 确认写入有意省略 `expectedRevision`:每个标签页都向同一路径写入相同版本,因此该操作是幂等的,并会保留同级字段,而不是重建整个分节。`settings/document-updated` 会转为 `host/settings-changed`;另一个标签页或外部编辑器提交当前版本后,已挂载的标签页会重新拉取状态并推进。API 网关在可配置提供方 namespace 之外,通过封闭的允许列表暴露这一个产品 namespace,同时不会把它的变更视为模型目录失效事件。 -**欢迎模态窗口只有一条完成路径。** 界面不渲染关闭图标或次要操作,不安装 Escape 处理器,也不为遮罩添加点击处理器。遮罩从顶部 80 px 的界面框架下方开始,并保留 `position:absolute`、left/right/bottom 偏移量为零、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。「继续」是唯一按钮,并会获得初始焦点。 +**欢迎模态窗口以便于扫读为先,且只有一条完成路径。** 其信息层级依次为声明标题、一句状态说明、一则重点突出的反馈提示、一句影响说明和一则克制的引语;只要这份文案发生实质变化,就同步提升通知版本。界面不渲染关闭图标或次要操作,不安装 Escape 处理器,也不为遮罩添加点击处理器。遮罩从顶部 80 px 的界面框架下方开始,并保留 `position:absolute`、left/right/bottom 偏移量为零、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。「继续」是唯一按钮,并会获得初始焦点。 ## 曾考虑的替代方案 diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts index f372910a61..8731bf10e0 100644 --- a/apps/web/tests/onboarding-deepseek-config.e2e.ts +++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts @@ -48,7 +48,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup it('stores a key write-only and observes configured state without restarting', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-onboarding-deepseek-config')) - const welcome = page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.paragraphs[0] }) + const welcome = page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.title }) await welcome.waitFor({ timeout: 15_000 }) const welcomeAria = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd) await compareOrRefreshGolden(WELCOME_EXPECTED, welcomeAria, MODE) @@ -132,7 +132,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup await page.reload({ waitUntil: 'load' }) acknowledgeReloadConnectionLoss(tripwire, secondReloadWarnings) await page.waitForSelector('[class*="frame"]', { timeout: 15_000 }) - expect(await page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.paragraphs[0] }).count()).toBe(0) + expect(await page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.title }).count()).toBe(0) expect(await page.getByRole('dialog', { name: '添加一个 API Key 开始使用' }).count()).toBe(0) // A different stored copy version represents an intentional version bump: diff --git a/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md b/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md index 370737df6b..d0fcb2b68d 100644 --- a/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md +++ b/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md @@ -1,6 +1,8 @@ -- dialog "感谢您愿意拨冗试用 DeepSeek Harness。": - - heading "感谢您愿意拨冗试用 DeepSeek Harness。" [level=2] - - paragraph: 目前的版本仍处于内部测试阶段,有些功能仍待完善,有些体验难免粗粝。 - - paragraph: “如切如磋,如琢如磨。” 产品的成长,离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中暴露的问题,也可能促使我们重新审视,甚至推翻已有的设计。 - - paragraph: 我们尤其希望听见那些失败、困惑与不顺手的时刻——如果它未能帮到您,甚至反而为工作平添了麻烦,请在企业微信群中留言,将使用感受告诉我们。每一条反馈,都会帮助我们把它打磨得更好。 +- dialog "内测声明": + - heading "内测声明" [level=2] + - paragraph: 感谢您试用 DeepSeek Harness。目前仍处于内部测试阶段,部分功能与体验还在持续打磨。 + - strong: 我们最想听见:失败、困惑和不顺手 + - paragraph: 如果它没帮到您,甚至给工作添了麻烦,请在企业微信群告诉我们。 + - paragraph: 真实使用中的每一个问题,都可能促使我们重新审视,甚至推翻已有设计。 + - paragraph: “如切如磋,如琢如磨。” - button "继续" diff --git a/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css b/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css index 8ad90b5fe2..805f411918 100644 --- a/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css +++ b/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css @@ -24,7 +24,7 @@ .dialog { position: relative; z-index: 1; - width: min(640px, calc(100vw - 48px)); + width: min(600px, calc(100vw - 48px)); max-height: calc(100vh - 128px); padding: 32px; box-sizing: border-box; @@ -40,21 +40,65 @@ font-size: 20px; line-height: 30px; font-weight: 600; + letter-spacing: -0.01em; } -.copy { - display: flex; - flex-direction: column; - gap: 14px; - margin-top: 18px; - font-size: 14px; - line-height: 24px; +.lead, +.closing, +.quote, +.feedback p, +.error { + margin: 0; +} + +.lead { + margin-top: 12px; + font-size: 16px; + line-height: 25px; color: var(--dsw-alias-label-secondary); } -.copy p, -.error { - margin: 0; +.feedback { + margin-top: 20px; + padding: 16px 18px; + border-radius: 14px; + border: 1px solid var(--dsw-alias-border-l1); + background: var(--dsw-alias-bg-module-platform); + font-size: 15px; + line-height: 24px; +} + +.feedback strong { + display: block; + margin-bottom: 4px; + font-weight: 600; +} + +.feedback p, +.closing { + color: var(--dsw-alias-label-secondary); +} + +.closing { + margin-top: 16px; + font-size: 15px; + line-height: 24px; +} + +.quote { + font-size: 14px; + line-height: 22px; + color: var(--dsw-alias-label-secondary); +} + +.footer { + display: flex; + align-items: center; + justify-content: space-between; + gap: 24px; + margin-top: 24px; + padding-top: 20px; + border-top: 1px solid var(--dsw-alias-border-l1); } .error { @@ -65,6 +109,32 @@ } .primary { - width: 100%; - margin-top: 24px; + min-width: 104px; + transition: transform 140ms cubic-bezier(0.23, 1, 0.32, 1); +} + +.primary:active:not(:disabled) { + transform: scale(0.97); +} + +@media (prefers-reduced-motion: reduce) { + .primary { + transition: none; + } +} + +@media (max-width: 560px) { + .dialog { + padding: 24px; + } + + .footer { + align-items: stretch; + flex-direction: column; + gap: 14px; + } + + .primary { + width: 100%; + } } diff --git a/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx b/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx index 6255405f83..ebdab519a4 100644 --- a/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx +++ b/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx @@ -47,22 +47,26 @@ export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode {
) diff --git a/packages/client/ui-settings-general/src/client/locales.ts b/packages/client/ui-settings-general/src/client/locales.ts index 73c0daab58..f2486faea2 100644 --- a/packages/client/ui-settings-general/src/client/locales.ts +++ b/packages/client/ui-settings-general/src/client/locales.ts @@ -26,10 +26,12 @@ export const zh: LocaleDict = { 'permission.title': '权限', 'permission.desc': '选择默认权限模式', 'toolcall.title': '工具调用', - 'welcome.paragraph.0': WELCOME_NOTICE_COPY.zh.paragraphs[0], - 'welcome.paragraph.1': WELCOME_NOTICE_COPY.zh.paragraphs[1], - 'welcome.paragraph.2': WELCOME_NOTICE_COPY.zh.paragraphs[2], - 'welcome.paragraph.3': WELCOME_NOTICE_COPY.zh.paragraphs[3], + 'welcome.title': WELCOME_NOTICE_COPY.zh.title, + 'welcome.lead': WELCOME_NOTICE_COPY.zh.lead, + 'welcome.feedbackTitle': WELCOME_NOTICE_COPY.zh.feedbackTitle, + 'welcome.feedbackBody': WELCOME_NOTICE_COPY.zh.feedbackBody, + 'welcome.closing': WELCOME_NOTICE_COPY.zh.closing, + 'welcome.quote': WELCOME_NOTICE_COPY.zh.quote, 'welcome.continue': WELCOME_NOTICE_COPY.zh.continueLabel, 'welcome.error': '暂时无法保存确认状态,请重试。', } @@ -44,10 +46,12 @@ export const en: LocaleDict = { 'permission.title': 'Permission', 'permission.desc': 'Choose default permission mode', 'toolcall.title': 'Tool Call', - 'welcome.paragraph.0': WELCOME_NOTICE_COPY.en.paragraphs[0], - 'welcome.paragraph.1': WELCOME_NOTICE_COPY.en.paragraphs[1], - 'welcome.paragraph.2': WELCOME_NOTICE_COPY.en.paragraphs[2], - 'welcome.paragraph.3': WELCOME_NOTICE_COPY.en.paragraphs[3], + 'welcome.title': WELCOME_NOTICE_COPY.en.title, + 'welcome.lead': WELCOME_NOTICE_COPY.en.lead, + 'welcome.feedbackTitle': WELCOME_NOTICE_COPY.en.feedbackTitle, + 'welcome.feedbackBody': WELCOME_NOTICE_COPY.en.feedbackBody, + 'welcome.closing': WELCOME_NOTICE_COPY.en.closing, + 'welcome.quote': WELCOME_NOTICE_COPY.en.quote, 'welcome.continue': WELCOME_NOTICE_COPY.en.continueLabel, 'welcome.error': 'The acknowledgement could not be saved. Please try again.', } diff --git a/packages/client/ui-settings-general/src/onboarding-copy.ts b/packages/client/ui-settings-general/src/onboarding-copy.ts index 04a075783e..805a9d35d0 100644 --- a/packages/client/ui-settings-general/src/onboarding-copy.ts +++ b/packages/client/ui-settings-general/src/onboarding-copy.ts @@ -8,26 +8,26 @@ export const WELCOME_NOTICE_ACK_FIELD = 'welcomeNoticeVersion' * Bump only when the notice changes materially and every user should see it * again. The acknowledgement is compared for exact equality. */ -export const WELCOME_NOTICE_VERSION = '2026-07-30.1' +export const WELCOME_NOTICE_VERSION = '2026-07-30.2' /** The complete editable welcome notice in both supported GUI locales. */ export const WELCOME_NOTICE_COPY = { zh: { - paragraphs: [ - '感谢您愿意拨冗试用 DeepSeek Harness。', - '目前的版本仍处于内部测试阶段,有些功能仍待完善,有些体验难免粗粝。', - '“如切如磋,如琢如磨。” 产品的成长,离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中暴露的问题,也可能促使我们重新审视,甚至推翻已有的设计。', - '我们尤其希望听见那些失败、困惑与不顺手的时刻——如果它未能帮到您,甚至反而为工作平添了麻烦,请在企业微信群中留言,将使用感受告诉我们。每一条反馈,都会帮助我们把它打磨得更好。', - ], + title: '内测声明', + lead: '感谢您试用 DeepSeek Harness。目前仍处于内部测试阶段,部分功能与体验还在持续打磨。', + feedbackTitle: '我们最想听见:失败、困惑和不顺手', + feedbackBody: '如果它没帮到您,甚至给工作添了麻烦,请在企业微信群告诉我们。', + closing: '真实使用中的每一个问题,都可能促使我们重新审视,甚至推翻已有设计。', + quote: '“如切如磋,如琢如磨。”', continueLabel: '继续', }, en: { - paragraphs: [ - 'Thank you for taking the time to try DeepSeek Harness.', - 'This version is still in internal testing. Some features remain unfinished, and parts of the experience may feel rough.', - '“As one cuts and files, as one chisels and polishes.” A product grows through real encounters and candid feedback. Problems you uncover in real use may prompt us to reconsider—or even overturn—our existing designs.', - 'We especially want to hear about failures, confusion, and friction. If it did not help you, or even made your work harder, please leave a message in the company WeChat group and tell us about your experience. Every piece of feedback helps us refine it.', - ], + title: 'Internal Testing Notice', + lead: 'Thank you for trying DeepSeek Harness. This version is still in internal testing, and some features and experiences remain under refinement.', + feedbackTitle: 'What we most want to hear: failures, confusion, and friction', + feedbackBody: 'If it did not help—or even made your work harder—please tell us in the company WeChat group.', + closing: 'Every problem found in real use may prompt us to reconsider, or even overturn, an existing design.', + quote: '“As one cuts and files, as one chisels and polishes.”', continueLabel: 'Continue', }, } as const diff --git a/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx b/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx index 5925cf048b..d414146e47 100644 --- a/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx +++ b/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx @@ -54,10 +54,18 @@ function mount(version?: string, mutateImpl: () => Promise = () => Prom describe('WelcomeNotice', () => { it('renders the owner copy with one primary action and no dismissal control', async () => { const h = mount() - const dialog = await screen.findByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.paragraphs[0] }) - for (const paragraph of WELCOME_NOTICE_COPY.zh.paragraphs) { - expect(screen.getByText(paragraph)).toBeTruthy() + const dialog = await screen.findByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.title }) + for (const text of [ + WELCOME_NOTICE_COPY.zh.title, + WELCOME_NOTICE_COPY.zh.lead, + WELCOME_NOTICE_COPY.zh.feedbackTitle, + WELCOME_NOTICE_COPY.zh.feedbackBody, + WELCOME_NOTICE_COPY.zh.closing, + WELCOME_NOTICE_COPY.zh.quote, + ]) { + expect(screen.getByText(text)).toBeTruthy() } + expect(dialog.textContent?.match(/感谢您试用 DeepSeek Harness/g) ?? []).toHaveLength(1) const buttons = dialog.querySelectorAll('button') expect(buttons).toHaveLength(1) expect(screen.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel })).toBeTruthy() From 75a0366a526021f6e4e3164eaf5ebe030248952b Mon Sep 17 00:00:00 2001 From: NI0317 Date: Fri, 31 Jul 2026 00:28:17 +0800 Subject: [PATCH 16/43] feat(web): present onboarding as a continuous page --- ...versioned-gui-welcome-onboarding.i18n.yaml | 4 +- ...-07-30-versioned-gui-welcome-onboarding.md | 2 +- ...-30-versioned-gui-welcome-onboarding.zh.md | 2 +- .../tests/onboarding-deepseek-config.e2e.ts | 28 +-- .../missing.expected.md | 6 +- .../welcome.expected.md | 14 +- .../DeepSeekOnboardingDialog.module.css | 136 +++++++++++- .../src/client/DeepSeekOnboardingDialog.tsx | 53 +++-- .../tests/onboarding-dialog.spec.tsx | 22 +- .../ui-settings-general/README.i18n.yaml | 4 +- packages/client/ui-settings-general/README.md | 2 +- .../client/ui-settings-general/README.zh.md | 2 +- .../src/client/WelcomeNotice.module.css | 194 ++++++++++-------- .../src/client/WelcomeNotice.tsx | 66 +++--- .../ui-settings-general/src/client/locales.ts | 20 +- .../src/onboarding-copy.ts | 26 ++- .../tests/welcome-notice.spec.tsx | 28 +-- packages/client/ui-settings/README.i18n.yaml | 4 +- packages/client/ui-settings/README.md | 4 +- packages/client/ui-settings/README.zh.md | 4 +- packages/client/ui-settings/package.json | 9 +- .../src/client/SettingsRoot.module.css | 30 +++ .../ui-settings/src/client/SettingsRoot.tsx | 26 ++- .../ui-settings/tests/settings-root.spec.tsx | 11 + pnpm-lock.yaml | 6 + 25 files changed, 475 insertions(+), 228 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml index db1397809e..cdf0c3a817 100644 --- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.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-30-versioned-gui-welcome-onboarding.md -2026-07-30-versioned-gui-welcome-onboarding.md: 06ac9fbe5c10db872c7ea3989ff2e14f756965a0 -2026-07-30-versioned-gui-welcome-onboarding.zh.md: e2d726368e6282e4f6043c225b665c1945228f2d +2026-07-30-versioned-gui-welcome-onboarding.md: 0705469e02ddb9068722ae5d500c151f077c83fd +2026-07-30-versioned-gui-welcome-onboarding.zh.md: bdd21d635f824b8c4a4813e6bff7798b34ec9677 diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md index 06ac9fbe5c..0705469e02 100644 --- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md +++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md @@ -18,7 +18,7 @@ The GUI's credential onboarding begins with a DeepSeek-specific readiness check, **Concurrent views converge without stale replacement.** The acknowledgement write omits `expectedRevision` deliberately: every tab writes the same version to one path, so the operation is idempotent and preserves sibling fields instead of rebuilding the section. `settings/document-updated` becomes `host/settings-changed`; an already mounted tab refetches and advances when another tab or an external editor commits the current version. The API proxy exposes this one product namespace through a closed allowlist beside configurable-provider namespaces, without treating its changes as model-catalog invalidations. -**The welcome modal is scan-first and has one completion path.** Its hierarchy is a declaration title, one status sentence, one emphasized feedback callout, one consequence sentence, and a restrained quotation; the notice version changes whenever that authored copy changes materially. It renders no close icon or secondary action, installs no Escape handler, and assigns no click handler to the mask. Its mask starts below the 80 px top chrome and preserves `position:absolute`, zero left/right/bottom offsets, `rgba(0, 0, 0, 0.24)`, and `backdrop-filter: blur(2px)`. Continue is the sole button and receives initial focus. +**Onboarding temporarily owns the viewport as one continuous stage.** A solid product surface replaces the complete application view through a body-level portal and marks the underlying app root inert; the exact required mask remains mounted behind that surface with `position:absolute`, zero left/right/bottom offsets, `top:80px`, `rgba(0, 0, 0, 0.24)`, and `backdrop-filter: blur(2px)`. Welcome and conditional credential setup render as successive pages in this stage instead of independent modals. Both pages reuse the Web UI's black `BrandWordmark`. The welcome page preserves the four authored paragraphs verbatim under the `内测声明` title; every paragraph uses one 16/28 body scale, and only the requested action clause inside the final paragraph receives a subtle 500 weight. A short staggered opacity/vertical entrance supplies pacing without blocking interaction and disappears under reduced motion. The title receives initial focus, Continue is the sole button, and no close, Escape, or mask-click path exists. ## Alternatives considered diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md index e2d726368e..bdd21d635f 100644 --- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md +++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md @@ -18,7 +18,7 @@ GUI 的凭据引导从 DeepSeek 专用的就绪状态检查开始,但内部测 **并发视图无需陈旧的整体替换即可收敛。** 确认写入有意省略 `expectedRevision`:每个标签页都向同一路径写入相同版本,因此该操作是幂等的,并会保留同级字段,而不是重建整个分节。`settings/document-updated` 会转为 `host/settings-changed`;另一个标签页或外部编辑器提交当前版本后,已挂载的标签页会重新拉取状态并推进。API 网关在可配置提供方 namespace 之外,通过封闭的允许列表暴露这一个产品 namespace,同时不会把它的变更视为模型目录失效事件。 -**欢迎模态窗口以便于扫读为先,且只有一条完成路径。** 其信息层级依次为声明标题、一句状态说明、一则重点突出的反馈提示、一句影响说明和一则克制的引语;只要这份文案发生实质变化,就同步提升通知版本。界面不渲染关闭图标或次要操作,不安装 Escape 处理器,也不为遮罩添加点击处理器。遮罩从顶部 80 px 的界面框架下方开始,并保留 `position:absolute`、left/right/bottom 偏移量为零、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。「继续」是唯一按钮,并会获得初始焦点。 +**引导流程会暂时接管视口,形成一个连续阶段。** 纯色产品界面通过挂载到 `body` 的 portal 取代完整的应用视图,并将底层应用根节点标记为 inert;严格符合要求的遮罩仍挂载在该界面后方,并保留 `position:absolute`、left/right/bottom 偏移量为零、`top:80px`、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。欢迎页和按条件显示的凭据设置页在这一阶段中依次呈现,而不是各自作为独立的模态窗口。两个页面都复用 Web UI 的黑色 `BrandWordmark`。欢迎页在 `内测声明` 标题下逐字保留既定的四段文案;所有段落统一采用 16/28 的正文字号与行高,只有最后一段中指定的行动语句使用较为克制的 500 字重。短暂的错落式透明度与纵向位移动画营造出舒缓节奏,但不会阻碍交互,并会在用户启用减少动态效果时禁用。初始焦点落在标题上,「继续」是唯一按钮,且不存在关闭、Escape 或点击遮罩的退出路径。 ## 曾考虑的替代方案 diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts index 8731bf10e0..f7a91e8d3e 100644 --- a/apps/web/tests/onboarding-deepseek-config.e2e.ts +++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts @@ -48,14 +48,17 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup it('stores a key write-only and observes configured state without restarting', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-onboarding-deepseek-config')) - const welcome = page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.title }) + const welcome = page.getByRole('region', { name: WELCOME_NOTICE_COPY.zh.title }) await welcome.waitFor({ timeout: 15_000 }) - const welcomeAria = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd) + expect(await page.locator('#root').evaluate(root => (root as HTMLElement).inert)).toBe(true) + const welcomeAria = await captureStableAria(page, '[role="region"]', scaffold.workspaceCwd) await compareOrRefreshGolden(WELCOME_EXPECTED, welcomeAria, MODE) expect(await welcome.getByRole('button').allTextContents()).toEqual([WELCOME_NOTICE_COPY.zh.continueLabel]) expect(await welcome.locator('button').count()).toBe(1) - const maskStyles = await welcome.locator('xpath=..').locator(':scope > div').first().evaluate((mask) => { + const mask = page.locator('[class*="onboardingMask"]') + expect(await mask.count()).toBe(1) + const maskStyles = await mask.evaluate((mask) => { const style = getComputedStyle(mask) const rect = mask.getBoundingClientRect() return { @@ -89,16 +92,17 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup await welcome.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }).click() await welcome.waitFor({ state: 'detached', timeout: 15_000 }) - const dialog = page.getByRole('dialog', { name: '添加一个 API Key 开始使用' }) - await dialog.waitFor({ timeout: 15_000 }) - expect(await dialog.getByRole('textbox').count()).toBe(0) - const initial = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd) + const credentialStep = page.getByRole('region', { name: '添加一个 API Key 开始使用' }) + await credentialStep.waitFor({ timeout: 15_000 }) + expect(await credentialStep.getByRole('textbox').count()).toBe(0) + const initial = await captureStableAria(page, '[role="region"]', scaffold.workspaceCwd) await compareOrRefreshGolden(MISSING_EXPECTED, initial, MODE) - await dialog.getByRole('button', { name: '前往配置' }).click() - await dialog.waitFor({ state: 'detached', timeout: 15_000 }) + await credentialStep.getByRole('button', { name: '前往配置' }).click() + await credentialStep.waitFor({ state: 'detached', timeout: 15_000 }) const settings = page.getByRole('dialog', { name: '设置' }) await settings.waitFor({ timeout: 10_000 }) + expect(await page.locator('#root').evaluate(root => (root as HTMLElement).inert)).toBe(false) const keyInput = settings.getByLabel('API 密钥', { exact: true }) await keyInput.waitFor({ timeout: 10_000 }) @@ -132,8 +136,8 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup await page.reload({ waitUntil: 'load' }) acknowledgeReloadConnectionLoss(tripwire, secondReloadWarnings) await page.waitForSelector('[class*="frame"]', { timeout: 15_000 }) - expect(await page.getByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.title }).count()).toBe(0) - expect(await page.getByRole('dialog', { name: '添加一个 API Key 开始使用' }).count()).toBe(0) + expect(await page.getByRole('region', { name: WELCOME_NOTICE_COPY.zh.title }).count()).toBe(0) + expect(await page.getByRole('region', { name: '添加一个 API Key 开始使用' }).count()).toBe(0) // A different stored copy version represents an intentional version bump: // the welcome step returns even though the credential is already ready. @@ -146,7 +150,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup await welcome.waitFor({ timeout: 15_000 }) await welcome.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }).click() await welcome.waitFor({ state: 'detached', timeout: 15_000 }) - expect(await page.getByRole('dialog', { name: '添加一个 API Key 开始使用' }).count()).toBe(0) + expect(await page.getByRole('region', { name: '添加一个 API Key 开始使用' }).count()).toBe(0) expect((await page.content()).includes(secret)).toBe(false) expect((await page.locator('body').ariaSnapshot()).includes(secret)).toBe(false) diff --git a/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md b/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md index 102b6a7fab..89f3e009f5 100644 --- a/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md +++ b/apps/web/tests/snapshots/onboarding-deepseek-config/missing.expected.md @@ -1,6 +1,6 @@ -- dialog "添加一个 API Key 开始使用": +- region "添加一个 API Key 开始使用": - heading "添加一个 API Key 开始使用" [level=2] - - button "稍后配置": - - img - paragraph: 配置 DeepSeek 官方模型,即可开始使用。 + - text: DeepSeek deepseek-official + - button "稍后配置" - button "前往配置" diff --git a/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md b/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md index d0fcb2b68d..1fe30502c1 100644 --- a/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md +++ b/apps/web/tests/snapshots/onboarding-deepseek-config/welcome.expected.md @@ -1,8 +1,10 @@ -- dialog "内测声明": +- region "内测声明": - heading "内测声明" [level=2] - - paragraph: 感谢您试用 DeepSeek Harness。目前仍处于内部测试阶段,部分功能与体验还在持续打磨。 - - strong: 我们最想听见:失败、困惑和不顺手 - - paragraph: 如果它没帮到您,甚至给工作添了麻烦,请在企业微信群告诉我们。 - - paragraph: 真实使用中的每一个问题,都可能促使我们重新审视,甚至推翻已有设计。 - - paragraph: “如切如磋,如琢如磨。” + - paragraph: 感谢您愿意拨冗试用 DeepSeek Harness。 + - paragraph: 目前的版本仍处于内部测试阶段,有些功能仍待完善,有些体验难免粗粝。 + - blockquote: “如切如磋,如琢如磨。” 产品的成长,离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中暴露的问题,也可能促使我们重新审视,甚至推翻已有的设计。 + - paragraph: + - text: 我们尤其希望听见那些失败、困惑与不顺手的时刻—— + - strong: 如果它未能帮到您,甚至反而为工作平添了麻烦,请在企业微信群中留言 + - text: ,将使用感受告诉我们。每一条反馈,都会帮助我们把它打磨得更好。 - button "继续" diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css index 6823556903..6d8b77f8ab 100644 --- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css +++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.module.css @@ -1,14 +1,136 @@ -.dialog { - width: min(420px, 100%); +.page { + position: relative; + z-index: 1; + width: min(640px, calc(100vw - 64px)); + max-height: 100vh; + padding: clamp(64px, 9vh, 108px) 0 40px; + box-sizing: border-box; + overflow-y: auto; + color: var(--dsw-alias-label-primary); } -.diagnostic { +.brand { + display: flex; + align-items: center; + margin-bottom: 42px; + color: var(--dsw-alias-label-primary); +} + +.title { + max-width: 620px; margin: 0; - font-size: 13px; - line-height: 20px; + font-size: clamp(30px, 4vw, 42px); + line-height: 1.15; + font-weight: 600; + letter-spacing: -0.035em; + outline: none; +} + +.description, +.diagnostic { + max-width: 600px; + margin: 22px 0 0; + font-size: 17px; + line-height: 29px; color: var(--dsw-alias-label-secondary); } -.primary { - width: 100%; +.provider { + display: flex; + align-items: center; + justify-content: space-between; + max-width: 600px; + margin-top: 36px; + padding: 18px 20px; + border: 1px solid var(--dsw-alias-border-l2); + border-radius: 16px; + background: var(--dsw-alias-bg-module-platform); +} + +.providerName { + font-size: 16px; + line-height: 24px; + font-weight: 600; +} + +.providerRoute { + font-size: 13px; + line-height: 20px; + color: var(--dsw-alias-label-tertiary); +} + +.actions { + display: flex; + align-items: center; + gap: 12px; + margin-top: 40px; +} + +.primary { + min-width: 132px; +} + +.brand, +.title, +.description, +.diagnostic, +.provider, +.actions { + animation: credential-enter 280ms cubic-bezier(0.23, 1, 0.32, 1) both; +} + +.title { animation-delay: 40ms; } +.description, +.diagnostic { animation-delay: 80ms; } +.provider { animation-delay: 120ms; } +.actions { animation-delay: 160ms; } + +@keyframes credential-enter { + from { + opacity: 0; + transform: translateY(8px); + } + + to { + opacity: 1; + transform: translateY(0); + } +} + +@media (prefers-reduced-motion: reduce) { + .brand, + .title, + .description, + .diagnostic, + .provider, + .actions { + animation: none; + } +} + +@media (max-width: 560px) { + .page { + width: calc(100vw - 40px); + padding-top: 48px; + } + + .brand { + margin-bottom: 30px; + } + + .description, + .diagnostic { + font-size: 16px; + line-height: 27px; + } + + .actions { + align-items: stretch; + flex-direction: column-reverse; + } + + .primary, + .later { + width: 100%; + } } diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx index 31ae571272..54055d4bf0 100644 --- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx +++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx @@ -1,13 +1,13 @@ /** - * Official-DeepSeek first-run dialog. Readiness comes from the same + * Official-DeepSeek first-run step. Readiness comes from the same * provider/settings/credential join as the Models page; the prompt only * routes the user to that page's single credential editor. */ -import { useEffect } from 'react' +import { useEffect, useRef } from 'react' import type { ReactNode } from 'react' import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' -import { Button, Modal } from '@deepseek-ai/dsh-client-ui-primitives' +import { BrandWordmark, Button } from '@deepseek-ai/dsh-client-ui-primitives' import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react' import type { DeepSeekReadiness, ModelsSettingsState, ModelsSettingsStore } from './store.ts' import { deepSeekReadiness } from './store.ts' @@ -61,12 +61,13 @@ function unavailableDiagnostic( * Prompt a first-run user to open Models while the official adapter exists * and its effective credential is not configured. * @param props - settings-shell owner state and Models feature dependencies. - * @returns the controlled modal or null when onboarding needs no intervention. + * @returns the onboarding page or null when onboarding needs no intervention. */ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps): ReactNode { const { complete, openSection, controller, useSnapshot, t } = props const state = useSnapshot(snapshot => snapshot) const readiness = deepSeekReadiness(state) + const titleRef = useRef(null) useEffect(() => { if (state.status === 'idle') void controller.load() @@ -81,6 +82,12 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps): openSection('models') } + useEffect(() => { + if (readiness.kind === 'credential-missing' || readiness.kind === 'unavailable') { + titleRef.current?.focus() + } + }, [readiness.kind]) + let unavailableReason: UnavailableReason | undefined switch (readiness.kind) { case 'loading': @@ -102,26 +109,38 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps): ? undefined : unavailableDiagnostic(unavailableReason, t) + const title = unavailable ? t('onboardingUnavailableTitle') : t('onboardingTitle') + return ( - + +

+ {title} +

+ {unavailable + ?

{diagnostic}

+ :

{t('onboardingDescription')}

} +
+ DeepSeek + deepseek-official +
+
+ - )} - > - {diagnostic === undefined ? undefined :

{diagnostic}

} - +
+ ) } diff --git a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx index 035faf31d0..731fa2406d 100644 --- a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx +++ b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx @@ -111,18 +111,18 @@ describe('DeepSeekOnboardingDialog', () => { it('loads on first entry and presents one accessible route to Models', async () => { const h = harness() render() - expect(await screen.findByRole('dialog', { name: en.onboardingTitle })).toBeTruthy() + expect(await screen.findByRole('region', { name: en.onboardingTitle })).toBeTruthy() expect(screen.getByText(en.onboardingDescription)).toBeTruthy() const action = screen.getByRole('button', { name: en.onboardingGoToSettings }) expect(action).toBeTruthy() - expect(document.activeElement).toBe(action) + expect(document.activeElement).toBe(screen.getByRole('heading', { name: en.onboardingTitle })) expect(screen.queryByRole('textbox')).toBeNull() }) it('opens the Models section and dismisses the prompt', async () => { const h = harness() render() - await screen.findByRole('dialog') + await screen.findByRole('region') fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings })) expect(h.complete).toHaveBeenCalledOnce() expect(h.openSection).toHaveBeenCalledWith('models') @@ -131,7 +131,7 @@ describe('DeepSeekOnboardingDialog', () => { it('allows configure-later dismissal without opening settings', async () => { const h = harness() render() - await screen.findByRole('dialog') + await screen.findByRole('region') fireEvent.click(screen.getByRole('button', { name: en.onboardingLater })) expect(h.complete).toHaveBeenCalledOnce() expect(h.openSection).not.toHaveBeenCalled() @@ -140,7 +140,7 @@ describe('DeepSeekOnboardingDialog', () => { it('routes an unavailable credential deployment to Models with a diagnostic', async () => { const h = harness({ describeFailure: 'credentials service is absent' }) render() - await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle }) + await screen.findByRole('region', { name: en.onboardingUnavailableTitle }) expect(screen.getByText(en.onboardingCredentialsUnavailable)).toBeTruthy() fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings })) expect(h.openSection).toHaveBeenCalledWith('models') @@ -152,7 +152,7 @@ describe('DeepSeekOnboardingDialog', () => { harness({ settingsWritable: false }), ]) { const view = render() - await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle }) + await screen.findByRole('region', { name: en.onboardingUnavailableTitle }) expect(screen.getByText(en.onboardingReadOnly)).toBeTruthy() view.unmount() } @@ -161,7 +161,7 @@ describe('DeepSeekOnboardingDialog', () => { it('distinguishes an initial transport failure from deployment misconfiguration', async () => { const h = harness({ providersRejectOnce: true }) render() - await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle }) + await screen.findByRole('region', { name: en.onboardingUnavailableTitle }) expect(screen.getByText(en.onboardingLoadFailed)).toBeTruthy() fireEvent.click(screen.getByRole('button', { name: en.onboardingGoToSettings })) expect(h.openSection).toHaveBeenCalledWith('models') @@ -174,7 +174,7 @@ describe('DeepSeekOnboardingDialog', () => { harness({ apiKeyEnv: null }), ]) { const view = render() - await screen.findByRole('dialog', { name: en.onboardingUnavailableTitle }) + await screen.findByRole('region', { name: en.onboardingUnavailableTitle }) expect(screen.getByText(en.onboardingConfigurationUnavailable)).toBeTruthy() view.unmount() } @@ -188,7 +188,7 @@ describe('DeepSeekOnboardingDialog', () => { ]) { const view = render() await act(async () => { await h.controller.load() }) - expect(screen.queryByRole('dialog')).toBeNull() + expect(screen.queryByRole('region')).toBeNull() await waitFor(() => { expect(h.complete).toHaveBeenCalledOnce() }) view.unmount() } @@ -197,10 +197,10 @@ describe('DeepSeekOnboardingDialog', () => { it('closes when an external credential invalidation refreshes the shared join', async () => { const h = harness() render() - await screen.findByRole('dialog') + await screen.findByRole('region') h.configure() await act(async () => { await h.controller.load() }) - await waitFor(() => { expect(screen.queryByRole('dialog')).toBeNull() }) + await waitFor(() => { expect(screen.queryByRole('region')).toBeNull() }) expect(h.complete).toHaveBeenCalledOnce() }) }) diff --git a/packages/client/ui-settings-general/README.i18n.yaml b/packages/client/ui-settings-general/README.i18n.yaml index b8fd2d4025..73bae23ebd 100644 --- a/packages/client/ui-settings-general/README.i18n.yaml +++ b/packages/client/ui-settings-general/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-settings-general/README.md -README.md: 3ae3f58bd00172ed9b547c01a354023c224f6a1c -README.zh.md: ffdaf0e4314daa947a4183e2b23b7b1650de7611 +README.md: 0ec2e14bc4f483a23607de7f33ca4c35687c7c4f +README.zh.md: 9ce7136ce9a0bf384bd2b6419d52cd0da5c7dc83 diff --git a/packages/client/ui-settings-general/README.md b/packages/client/ui-settings-general/README.md index 3ae3f58bd0..0ec2e14bc4 100644 --- a/packages/client/ui-settings-general/README.md +++ b/packages/client/ui-settings-general/README.md @@ -4,7 +4,7 @@ English | [中文](README.zh.md) Settings ownerless-copy and product-onboarding plugin: registers everything on the Settings surface that belongs to no single feature — the shell's trigger/header/close chrome content, the General section (Permission/Tool Call skeleton rows + the `settings.general.item` slot declaration), the `settings` dictionaries, and the first ordered welcome step. Feature-owned rows (Language, Appearance), sections (Models), and conditional onboarding steps stay with their feature packages. -`src/onboarding-copy.ts` is the single editable owner of the complete Chinese and English notice plus `WELCOME_NOTICE_VERSION`. The Host half registers `ui-onboarding` in the user-settings seam; the browser compares `welcomeNoticeVersion` for exact equality and writes the current value only after Continue succeeds. The path mutation is idempotent across tabs and preserves sibling settings, while `host/settings-changed` makes an externally acknowledged notice advance without a reload. A different version deliberately presents the notice again. The welcome UI has no close, Escape, mask-click, or secondary path, and none of its copy or acknowledgement enters a Session log or model request. +`src/onboarding-copy.ts` is the single editable owner of the complete Chinese and English notice plus `WELCOME_NOTICE_VERSION`. The Host half registers `ui-onboarding` in the user-settings seam; the browser compares `welcomeNoticeVersion` for exact equality and writes the current value only after Continue succeeds. The path mutation is idempotent across tabs and preserves sibling settings, while `host/settings-changed` makes an externally acknowledged notice advance without a reload. A different version deliberately presents the notice again. The welcome page preserves every authored paragraph, gives the requested clause in the final paragraph the sole emphasis, initially focuses the title, and has no close, Escape, mask-click, or secondary path. None of its copy or acknowledgement enters a Session log or model request. ## Model Experience diff --git a/packages/client/ui-settings-general/README.zh.md b/packages/client/ui-settings-general/README.zh.md index ffdaf0e431..9ce7136ce9 100644 --- a/packages/client/ui-settings-general/README.zh.md +++ b/packages/client/ui-settings-general/README.zh.md @@ -4,7 +4,7 @@ 设置界面无特定功能归属的文案与产品引导插件:在设置界面注册所有不属于单一功能的内容,包括外壳的触发器、标题栏与关闭控件内容,「通用」分区(「权限」/「工具调用」骨架行和 `settings.general.item` slot 声明)、`settings` 字典,以及第一个有序欢迎步骤。归具体功能所有的行(「语言」、「外观」)、分区(「模型」)和条件式首次使用引导步骤仍由各自的功能包提供。 -`src/onboarding-copy.ts` 是完整中英文通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源。宿主端在 user-settings seam 中注册 `ui-onboarding`;浏览器比较 `welcomeNoticeVersion` 是否精确相等,仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等,并会保留同级设置;`host/settings-changed` 则让页面在通知被外部确认后,无需重新加载即可推进。版本不同时,系统会有意重新显示通知。欢迎界面没有关闭操作、Escape、点击遮罩或次要操作路径,其文案和确认状态均不会进入会话日志或模型请求。 +`src/onboarding-copy.ts` 是完整中英文通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源。宿主端在 user-settings seam 中注册 `ui-onboarding`;浏览器比较 `welcomeNoticeVersion` 是否精确相等,仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等,并会保留同级设置;`host/settings-changed` 则让页面在通知被外部确认后,无需重新加载即可推进。版本不同时,系统会有意重新显示通知。欢迎页保留原文的每个段落,仅强调最后一段中指定的句段,初始焦点落在标题上,并且没有关闭操作、Escape、点击遮罩或次要操作路径。其文案和确认状态均不会进入会话日志或模型请求。 ## 模型体验 diff --git a/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css b/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css index 805f411918..843606605e 100644 --- a/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css +++ b/packages/client/ui-settings-general/src/client/WelcomeNotice.module.css @@ -1,137 +1,161 @@ -.overlay { - position: fixed; - inset: 0; - z-index: 1100; - display: flex; - align-items: center; - justify-content: center; - padding-top: 80px; - box-sizing: border-box; -} - -/* Mask */ -.mask { - position: absolute; - left: 0px; - right: 0px; - top: 80px; - bottom: 0px; - background: rgba(0, 0, 0, 0.24); - /* Mask-blur */ - backdrop-filter: blur(2px); -} - -.dialog { +.page { position: relative; z-index: 1; - width: min(600px, calc(100vw - 48px)); - max-height: calc(100vh - 128px); - padding: 32px; + width: min(640px, calc(100vw - 64px)); + max-height: 100vh; + padding: clamp(64px, 9vh, 104px) 0 40px; box-sizing: border-box; overflow-y: auto; - border-radius: 24px; - background: var(--dsw-alias-bg-layer-2); - box-shadow: var(--dsw-shadow-lv3); + color: var(--dsw-alias-label-primary); + --welcome-ease-out: cubic-bezier(0.23, 1, 0.32, 1); +} + +.brand { + display: flex; + align-items: center; + margin-bottom: 42px; color: var(--dsw-alias-label-primary); } .title { margin: 0; - font-size: 20px; - line-height: 30px; + font-size: 28px; + line-height: 36px; font-weight: 600; - letter-spacing: -0.01em; + letter-spacing: -0.02em; + outline: none; } -.lead, -.closing, -.quote, -.feedback p, +.opening, +.status, +.reflection, +.feedback, .error { margin: 0; } -.lead { - margin-top: 12px; - font-size: 16px; - line-height: 25px; - color: var(--dsw-alias-label-secondary); +.opening { + margin-top: 30px; +} + +.status { + margin-top: 18px; +} + +.reflection { + margin-top: 36px; + padding: 0; } .feedback { - margin-top: 20px; - padding: 16px 18px; - border-radius: 14px; - border: 1px solid var(--dsw-alias-border-l1); - background: var(--dsw-alias-bg-module-platform); - font-size: 15px; - line-height: 24px; + margin-top: 30px; +} + +.opening, +.status, +.reflection, +.feedback { + font-size: 16px; + line-height: 28px; + color: var(--dsw-alias-label-secondary); } .feedback strong { - display: block; - margin-bottom: 4px; - font-weight: 600; -} - -.feedback p, -.closing { - color: var(--dsw-alias-label-secondary); -} - -.closing { - margin-top: 16px; - font-size: 15px; - line-height: 24px; -} - -.quote { - font-size: 14px; - line-height: 22px; - color: var(--dsw-alias-label-secondary); + color: inherit; + font-weight: 500; } .footer { display: flex; - align-items: center; - justify-content: space-between; - gap: 24px; - margin-top: 24px; - padding-top: 20px; - border-top: 1px solid var(--dsw-alias-border-l1); + justify-content: flex-end; + margin-top: 32px; } .error { - margin-top: 14px; - font-size: 13px; - line-height: 20px; + margin-top: 20px; + font-size: 14px; + line-height: 22px; color: var(--dsw-alias-state-error-primary); } .primary { - min-width: 104px; - transition: transform 140ms cubic-bezier(0.23, 1, 0.32, 1); + min-width: 120px; + transition: transform 140ms var(--welcome-ease-out); } .primary:active:not(:disabled) { transform: scale(0.97); } +.brand, +.title, +.opening, +.status, +.reflection, +.feedback, +.footer { + animation: welcome-enter 280ms var(--welcome-ease-out) both; +} + +.title { animation-delay: 40ms; } +.opening { animation-delay: 80ms; } +.status { animation-delay: 120ms; } +.reflection { animation-delay: 160ms; } +.feedback { animation-delay: 200ms; } +.footer { animation-delay: 240ms; } + +@keyframes welcome-enter { + from { + opacity: 0; + transform: translateY(8px); + } + + to { + opacity: 1; + transform: translateY(0); + } +} + @media (prefers-reduced-motion: reduce) { + .brand, + .title, + .opening, + .status, + .reflection, + .feedback, + .footer { + animation: none; + } + .primary { transition: none; } } @media (max-width: 560px) { - .dialog { - padding: 24px; + .page { + width: calc(100vw - 40px); + padding-top: 38px; + } + + .brand { + margin-bottom: 30px; + } + + .opening { + margin-top: 24px; + } + + .reflection { + margin-top: 28px; + } + + .feedback { + margin-top: 28px; } .footer { - align-items: stretch; - flex-direction: column; - gap: 14px; + margin-top: 30px; } .primary { diff --git a/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx b/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx index ebdab519a4..f1e14d6815 100644 --- a/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx +++ b/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx @@ -3,11 +3,24 @@ import { useCallback, useEffect, useRef } from 'react' import type { ReactNode } from 'react' import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' -import { Button } from '@deepseek-ai/dsh-client-ui-primitives' +import { BrandWordmark, Button } from '@deepseek-ai/dsh-client-ui-primitives' import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react' import type { WelcomeNoticeState, WelcomeNoticeStore } from './welcome-store.ts' import css from './WelcomeNotice.module.css' +function emphasizedFeedback(paragraph: string, emphasis: string): ReactNode { + const index = paragraph.indexOf(emphasis) + /* v8 ignore next -- both locale values derive from one owner object that contains the emphasis */ + if (index < 0) return paragraph + return ( + <> + {paragraph.slice(0, index)} + {emphasis} + {paragraph.slice(index + emphasis.length)} + + ) +} + /** Registrant-owned dependencies of {@link WelcomeNotice}. */ export interface WelcomeNoticeInjected { controller: WelcomeNoticeStore @@ -23,6 +36,7 @@ export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode { const { complete, controller, useSnapshot, t } = props const state = useSnapshot(snapshot => snapshot) const finished = useRef(false) + const titleRef = useRef(null) const finish = useCallback((): void => { if (finished.current) return finished.current = true @@ -37,6 +51,10 @@ export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode { if (state.acknowledged) finish() }, [finish, state.acknowledged]) + useEffect(() => { + if (state.status === 'ready' && !state.acknowledged) titleRef.current?.focus() + }, [state.acknowledged, state.status]) + if (state.status === 'idle' || state.status === 'loading' || state.acknowledged) return null const acknowledge = async (): Promise => { @@ -44,30 +62,26 @@ export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode { } return ( -
- +
+ +

{t('welcome.title')}

+

{t('welcome.paragraph.0')}

+

{t('welcome.paragraph.1')}

+
{t('welcome.paragraph.2')}
+

+ {emphasizedFeedback(t('welcome.paragraph.3'), t('welcome.feedbackEmphasis'))} +

+ {state.error === null ? null :

{t('welcome.error')}

} +
+ +
+
) } diff --git a/packages/client/ui-settings-general/src/client/locales.ts b/packages/client/ui-settings-general/src/client/locales.ts index f2486faea2..c3432cfe72 100644 --- a/packages/client/ui-settings-general/src/client/locales.ts +++ b/packages/client/ui-settings-general/src/client/locales.ts @@ -27,11 +27,11 @@ export const zh: LocaleDict = { 'permission.desc': '选择默认权限模式', 'toolcall.title': '工具调用', 'welcome.title': WELCOME_NOTICE_COPY.zh.title, - 'welcome.lead': WELCOME_NOTICE_COPY.zh.lead, - 'welcome.feedbackTitle': WELCOME_NOTICE_COPY.zh.feedbackTitle, - 'welcome.feedbackBody': WELCOME_NOTICE_COPY.zh.feedbackBody, - 'welcome.closing': WELCOME_NOTICE_COPY.zh.closing, - 'welcome.quote': WELCOME_NOTICE_COPY.zh.quote, + 'welcome.paragraph.0': WELCOME_NOTICE_COPY.zh.paragraphs[0], + 'welcome.paragraph.1': WELCOME_NOTICE_COPY.zh.paragraphs[1], + 'welcome.paragraph.2': WELCOME_NOTICE_COPY.zh.paragraphs[2], + 'welcome.paragraph.3': WELCOME_NOTICE_COPY.zh.paragraphs[3], + 'welcome.feedbackEmphasis': WELCOME_NOTICE_COPY.zh.feedbackEmphasis, 'welcome.continue': WELCOME_NOTICE_COPY.zh.continueLabel, 'welcome.error': '暂时无法保存确认状态,请重试。', } @@ -47,11 +47,11 @@ export const en: LocaleDict = { 'permission.desc': 'Choose default permission mode', 'toolcall.title': 'Tool Call', 'welcome.title': WELCOME_NOTICE_COPY.en.title, - 'welcome.lead': WELCOME_NOTICE_COPY.en.lead, - 'welcome.feedbackTitle': WELCOME_NOTICE_COPY.en.feedbackTitle, - 'welcome.feedbackBody': WELCOME_NOTICE_COPY.en.feedbackBody, - 'welcome.closing': WELCOME_NOTICE_COPY.en.closing, - 'welcome.quote': WELCOME_NOTICE_COPY.en.quote, + 'welcome.paragraph.0': WELCOME_NOTICE_COPY.en.paragraphs[0], + 'welcome.paragraph.1': WELCOME_NOTICE_COPY.en.paragraphs[1], + 'welcome.paragraph.2': WELCOME_NOTICE_COPY.en.paragraphs[2], + 'welcome.paragraph.3': WELCOME_NOTICE_COPY.en.paragraphs[3], + 'welcome.feedbackEmphasis': WELCOME_NOTICE_COPY.en.feedbackEmphasis, 'welcome.continue': WELCOME_NOTICE_COPY.en.continueLabel, 'welcome.error': 'The acknowledgement could not be saved. Please try again.', } diff --git a/packages/client/ui-settings-general/src/onboarding-copy.ts b/packages/client/ui-settings-general/src/onboarding-copy.ts index 805a9d35d0..21e27114d4 100644 --- a/packages/client/ui-settings-general/src/onboarding-copy.ts +++ b/packages/client/ui-settings-general/src/onboarding-copy.ts @@ -8,26 +8,30 @@ export const WELCOME_NOTICE_ACK_FIELD = 'welcomeNoticeVersion' * Bump only when the notice changes materially and every user should see it * again. The acknowledgement is compared for exact equality. */ -export const WELCOME_NOTICE_VERSION = '2026-07-30.2' +export const WELCOME_NOTICE_VERSION = '2026-07-30.3' /** The complete editable welcome notice in both supported GUI locales. */ export const WELCOME_NOTICE_COPY = { zh: { title: '内测声明', - lead: '感谢您试用 DeepSeek Harness。目前仍处于内部测试阶段,部分功能与体验还在持续打磨。', - feedbackTitle: '我们最想听见:失败、困惑和不顺手', - feedbackBody: '如果它没帮到您,甚至给工作添了麻烦,请在企业微信群告诉我们。', - closing: '真实使用中的每一个问题,都可能促使我们重新审视,甚至推翻已有设计。', - quote: '“如切如磋,如琢如磨。”', + paragraphs: [ + '感谢您愿意拨冗试用 DeepSeek Harness。', + '目前的版本仍处于内部测试阶段,有些功能仍待完善,有些体验难免粗粝。', + '“如切如磋,如琢如磨。” 产品的成长,离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中暴露的问题,也可能促使我们重新审视,甚至推翻已有的设计。', + '我们尤其希望听见那些失败、困惑与不顺手的时刻——如果它未能帮到您,甚至反而为工作平添了麻烦,请在企业微信群中留言,将使用感受告诉我们。每一条反馈,都会帮助我们把它打磨得更好。', + ], + feedbackEmphasis: '如果它未能帮到您,甚至反而为工作平添了麻烦,请在企业微信群中留言', continueLabel: '继续', }, en: { title: 'Internal Testing Notice', - lead: 'Thank you for trying DeepSeek Harness. This version is still in internal testing, and some features and experiences remain under refinement.', - feedbackTitle: 'What we most want to hear: failures, confusion, and friction', - feedbackBody: 'If it did not help—or even made your work harder—please tell us in the company WeChat group.', - closing: 'Every problem found in real use may prompt us to reconsider, or even overturn, an existing design.', - quote: '“As one cuts and files, as one chisels and polishes.”', + paragraphs: [ + 'Thank you for taking the time to try DeepSeek Harness.', + 'This version is still in internal testing. Some features remain unfinished, and parts of the experience may feel rough.', + '“As one cuts and files, as one chisels and polishes.” A product grows through real encounters and candid feedback. Problems you uncover in real use may prompt us to reconsider—or even overturn—our existing designs.', + 'We especially want to hear about failures, confusion, and friction. If it did not help you, or even made your work harder, please leave a message in the company WeChat group and tell us about your experience. Every piece of feedback helps us refine it.', + ], + feedbackEmphasis: 'If it did not help you, or even made your work harder, please leave a message in the company WeChat group', continueLabel: 'Continue', }, } as const diff --git a/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx b/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx index d414146e47..767f35ef33 100644 --- a/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx +++ b/packages/client/ui-settings-general/tests/welcome-notice.spec.tsx @@ -54,30 +54,22 @@ function mount(version?: string, mutateImpl: () => Promise = () => Prom describe('WelcomeNotice', () => { it('renders the owner copy with one primary action and no dismissal control', async () => { const h = mount() - const dialog = await screen.findByRole('dialog', { name: WELCOME_NOTICE_COPY.zh.title }) - for (const text of [ - WELCOME_NOTICE_COPY.zh.title, - WELCOME_NOTICE_COPY.zh.lead, - WELCOME_NOTICE_COPY.zh.feedbackTitle, - WELCOME_NOTICE_COPY.zh.feedbackBody, - WELCOME_NOTICE_COPY.zh.closing, - WELCOME_NOTICE_COPY.zh.quote, - ]) { - expect(screen.getByText(text)).toBeTruthy() - } - expect(dialog.textContent?.match(/感谢您试用 DeepSeek Harness/g) ?? []).toHaveLength(1) - const buttons = dialog.querySelectorAll('button') + const page = await screen.findByRole('region', { name: WELCOME_NOTICE_COPY.zh.title }) + expect(screen.getByText(WELCOME_NOTICE_COPY.zh.title)).toBeTruthy() + for (const text of WELCOME_NOTICE_COPY.zh.paragraphs) expect(page.textContent).toContain(text) + expect(page.textContent?.match(/感谢您愿意拨冗试用 DeepSeek Harness/g) ?? []).toHaveLength(1) + const buttons = page.querySelectorAll('button') expect(buttons).toHaveLength(1) expect(screen.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel })).toBeTruthy() + expect(document.activeElement).toBe(screen.getByRole('heading', { name: WELCOME_NOTICE_COPY.zh.title })) fireEvent.keyDown(document, { key: 'Escape' }) - fireEvent.click(dialog.parentElement!.firstElementChild!) expect(h.complete).not.toHaveBeenCalled() - expect(screen.getByRole('dialog')).toBeTruthy() + expect(screen.getByRole('region')).toBeTruthy() }) it('completes only after the acknowledgement write commits', async () => { const h = mount() - await screen.findByRole('dialog') + await screen.findByRole('region') fireEvent.click(screen.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel })) await act(async () => { await Promise.resolve() }) expect(h.mutate).toHaveBeenCalledOnce() @@ -87,7 +79,7 @@ describe('WelcomeNotice', () => { it('skips itself when this exact version was already acknowledged', async () => { const h = mount(WELCOME_NOTICE_VERSION) await act(async () => { await h.controller.load() }) - expect(screen.queryByRole('dialog')).toBeNull() + expect(screen.queryByRole('region')).toBeNull() expect(h.complete).toHaveBeenCalledOnce() }) @@ -95,7 +87,7 @@ describe('WelcomeNotice', () => { let resolveWrite!: (value: unknown) => void const write = new Promise((resolve) => { resolveWrite = resolve }) const h = mount(undefined, () => write) - await screen.findByRole('dialog') + await screen.findByRole('region') const action = screen.getByRole('button', { name: WELCOME_NOTICE_COPY.zh.continueLabel }) fireEvent.click(action) expect(action.disabled).toBe(true) diff --git a/packages/client/ui-settings/README.i18n.yaml b/packages/client/ui-settings/README.i18n.yaml index 41247a370b..b02b945303 100644 --- a/packages/client/ui-settings/README.i18n.yaml +++ b/packages/client/ui-settings/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-settings/README.md -README.md: 02d8f0e5fdc169d3a45f59d7b42d873943df2b52 -README.zh.md: 465d57847588e9ccbccc9d9067099773de63c0d0 +README.md: 6d784e906b937e912b56b2e85bfa32866d8cb9b8 +README.zh.md: 3c627c185db3d1d80915f19df56a8fe7257fa828 diff --git a/packages/client/ui-settings/README.md b/packages/client/ui-settings/README.md index 02d8f0e5fd..6d784e906b 100644 --- a/packages/client/ui-settings/README.md +++ b/packages/client/ui-settings/README.md @@ -2,9 +2,9 @@ English | [中文](README.zh.md) -Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.section` (one page per feature), and `settings.onboarding` (ordered feature-owned steps on the empty Hero). The shell ships no copy and reads no locale state — all text arrives from registrants (ui-settings-general owns chrome, General, and the product welcome step; features own their sections, rows, and conditional onboarding steps). +Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.section` (one page per feature), and `settings.onboarding` (ordered feature-owned pages in a full-viewport stage). The shell ships no copy and reads no locale state — all text arrives from registrants (ui-settings-general owns chrome, General, and the product notice; features own their sections, rows, and conditional onboarding pages). -The shell projects the onboarding ledger into ascending order and mounts exactly one step at a time. The active registrant receives its id, `complete()`, and an `openSection(id)` callback; completing or skipping transfers ownership to the next entry. Registrants own durable completion, capability readiness, copy, and mutations, so two independently registered dialogs cannot stack and the shell does not become a second configuration fact source. +The shell projects the onboarding ledger into ascending order and mounts exactly one page at a time in a body-level stage while marking the underlying app root inert. The active registrant receives its id, `complete()`, and an `openSection(id)` callback; completing or skipping transfers ownership to the next entry. Registrants own durable completion, capability readiness, copy, and mutations, so independently registered flows cannot stack and the shell does not become a second configuration fact source. ## Model Experience diff --git a/packages/client/ui-settings/README.zh.md b/packages/client/ui-settings/README.zh.md index 465d578475..3c627c185d 100644 --- a/packages/client/ui-settings/README.zh.md +++ b/packages/client/ui-settings/README.zh.md @@ -2,9 +2,9 @@ [English](README.md) | 中文 -设置外壳插件:一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`,并声明由注册方填充的 slot:`settings.trigger`/`settings.header`/`settings.close`(界面框架内容)、`settings.section`(每项功能一页)和 `settings.onboarding`(由各功能持有、显示在空白 Hero 上的有序步骤)。外壳不自带文案,也不读取 locale 状态:所有文本都来自注册方(ui-settings-general 拥有界面框架、「通用」分区和产品欢迎步骤;各功能拥有各自的分区、行和条件式首次使用引导步骤)。 +设置外壳插件:一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`,并声明由注册方填充的 slot:`settings.trigger`/`settings.header`/`settings.close`(界面框架内容)、`settings.section`(每项功能一页)和 `settings.onboarding`(由各功能持有、显示在全视口展示层中的有序页面)。外壳不自带文案,也不读取 locale 状态:所有文本都来自注册方(ui-settings-general 拥有界面框架、「通用」分区和产品声明;各功能拥有各自的分区、行和条件式首次使用引导页面)。 -外壳将首次使用引导记录按升序投影,并且每次只挂载一个步骤。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调;完成或跳过当前步骤后,所有权转交给下一项。持久化完成状态、能力就绪状态、文案和变更操作均由注册方持有,因此两个独立注册的对话框无法堆叠,外壳也不会成为第二个配置事实来源。 +外壳将首次使用引导记录按升序投影,在 body 层级的展示层中每次只挂载一个页面,同时将下层应用根节点标记为 `inert`。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调;完成或跳过当前页面后,所有权转交给下一项。持久化完成状态、能力就绪状态、文案和变更操作均由注册方持有,因此独立注册的流程无法堆叠,外壳也不会成为第二个配置事实来源。 ## 模型体验 diff --git a/packages/client/ui-settings/package.json b/packages/client/ui-settings/package.json index 8c65eee5b2..fa8bf78b9f 100644 --- a/packages/client/ui-settings/package.json +++ b/packages/client/ui-settings/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-client-ui-settings", - "description": "Settings shell plugin: sidebar trigger, modal panel, feature sections, and root-scoped onboarding overlays", + "description": "Settings shell plugin: sidebar trigger, modal panel, feature sections, and an ordered full-page onboarding stage", "version": "0.0.1", "private": true, "type": "module", @@ -43,7 +43,8 @@ "@deepseek-ai/dsh-client-ui-slots": "^0.0.1", "@deepseek-ai/dsh-invariants": "^0.0.1", "cordis": "^4.0.0-rc.7", - "react": "^18.2.0" + "react": "^18.2.0", + "react-dom": "^18.2.0" }, "devDependencies": { "@deepseek-ai/dsh-client-runtime": "workspace:^", @@ -51,9 +52,11 @@ "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^", "@deepseek-ai/dsh-client-ui-slots": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", + "@types/react-dom": "~18.3.0", "@types/react": "~18.3.1", "cordis": "^4.0.0-rc.7", - "react": "^18.2.0" + "react": "^18.2.0", + "react-dom": "^18.2.0" }, "files": [ "lib/index.js", diff --git a/packages/client/ui-settings/src/client/SettingsRoot.module.css b/packages/client/ui-settings/src/client/SettingsRoot.module.css index 04eaf14d2b..817ab38d9a 100644 --- a/packages/client/ui-settings/src/client/SettingsRoot.module.css +++ b/packages/client/ui-settings/src/client/SettingsRoot.module.css @@ -209,3 +209,33 @@ clip: rect(0 0 0 0); white-space: nowrap; } + +/* First-run stage: keep the product top bar visible, then let onboarding own + the complete workspace instead of presenting another settings modal. */ +.onboardingOverlay { + position: fixed; + inset: 0; + z-index: 1100; +} + +/* Mask */ +.onboardingMask { + position: absolute; + left: 0px; + right: 0px; + top: 80px; + bottom: 0px; + background: rgba(0, 0, 0, 0.24); + /* Mask-blur */ + backdrop-filter: blur(2px); +} + +.onboardingStage { + position: absolute; + z-index: 1; + inset: 0; + display: flex; + justify-content: center; + overflow: hidden; + background: var(--dsw-alias-bg-layer-1); +} diff --git a/packages/client/ui-settings/src/client/SettingsRoot.tsx b/packages/client/ui-settings/src/client/SettingsRoot.tsx index 528a633810..3eefbd4ef1 100644 --- a/packages/client/ui-settings/src/client/SettingsRoot.tsx +++ b/packages/client/ui-settings/src/client/SettingsRoot.tsx @@ -10,6 +10,7 @@ * sessions-derived empty-Hero fact is active. */ import { useCallback, useEffect, useId, useRef, useState } from 'react' +import { createPortal } from 'react-dom' import clsx from 'clsx' import { IconCloseOutline16, IconDataOutline16, IconSettingsOutline16 } from '@deepseek-ai/dsh-client-ui-primitives' import type { SettingsRootComponentProps, SettingsSectionRow } from './contract/slots.ts' @@ -132,6 +133,14 @@ export function SettingsRoot(props: SettingsRootComponentProps) { }) }, []) + useEffect(() => { + if (onboardingStep === undefined) return + const appRoot = document.getElementById('root') + if (appRoot === null) return + appRoot.inert = true + return () => { appRoot.inert = false } + }, [onboardingStep]) + return ( <>