feat(ui): unify tool result formatting, add content-aware

   rendering & session delete reset

   - Add formatToolResultForUI() as single choke-point for
   Live + History paths
   - Content-aware formatting: JSON pretty-print, code fences
   for bash/grep/glob/read_file
   - ToolCard renders results via Markdown component with
   syntax-highlighted code blocks
   - Delete current session from sidebar resets ChatView to
   welcome page
   - Session list broadcasts on session:deleted event to all
   connected clients

Author: 王璨

openspec/changes/archive/2025-07-14-format-tool-results-in-ui/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-18

openspec/changes/archive/2025-07-14-format-tool-results-in-ui/design.md

@@ -0,0 +1,71 @@
+## Context
+
+`formatToolResultForUI`（`src/ui/shared/tool-result-formatter.ts`）是 Live 和 History 两条路径共享的扼流点，当前只做截断（`write_file` 摘要提取 + 默认 600 字符）。前端 `ToolCard` 将 `result` 字符串以纯文本渲染（`font-mono whitespace-pre-wrap`），不做任何格式化。
+
+同时，`MessageBubble` 中的 assistant 正文已通过 `<Markdown>`（基于 `react-markdown` + `remarkGfm`）完整渲染，支持代码块、表格、链接等。ToolCard 应与之一致。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 工具结果按内容类型智能格式化：JSON → pretty-print + code fence，bash/grep/read_file → code fence，Markdown → 透传
+- ToolCard 通过已有 `<Markdown>` 组件渲染结果，获得代码高亮、表格、链接等能力
+- 不引入新前端依赖
+
+**Non-Goals:**
+- 不改变 ToolCard 的容器结构（卡片尺寸、边框、圆角、工具名头部）
+- 不改变 MessageBubble 布局或 session 主界面结构
+- 不改变 agent 看到的原始 tool result（只影响 UI 展示路径）
+- 不做语法级别的 JS/TS 高亮（那是语言级的 feature，`react-markdown` + code fence 已足够）
+
+## Decisions
+
+### Decision 1: 格式化逻辑放在扼流点，不在 ToolCard
+
+**Choice:** `formatToolResultForUI` 输出时直接包含 markdown code fence；前端 ToolCard 只负责 `<Markdown>` 渲染。
+
+**Rationale:** 扼流点是所有工具结果到 UI 的必经之路。在这里做格式化，Live 和 History 两条路径自动受益。如果放在 ToolCard（前端），History 路径的 `rebuildDisplayMessages` 输出也要额外处理。
+
+**Alternatives considered:**
+- ToolCard 内做检测 + 渲染：逻辑重复，History 路径需单独处理。且前端引入 JSON 检测/pretty-print 会膨胀组件职责。
+- 新增后端中间层：过度设计，扼流点本身就是最合适的插入点。
+
+### Decision 2: JSON 检测用 JSON.parse 试探
+
+**Choice:** 检测 `rawText.trim()` 是否以 `{` / `[` 开头，然后 `JSON.parse`。成功则 pretty-print + 包 ```` ```json ````。失败则按其他规则处理。
+
+**Rationale:** 简单的 heuristic 就能覆盖绝大多数情况（grep --json、glob --json、JSON API 响应）。偶尔误判为 JSON 也不产生灾难后果（最多包个空 code fence）。
+
+**Alternatives considered:**
+- 正则检测 JSON：不够可靠，JSON 内可以含字符串 `"{"`
+- 不做 JSON 检测，所有内容统一包 ```：bash 结果包 ```sh 是对的，但纯 JSON 用 ``` 没有语言标注，语法高亮缺失
+- 正则 `/^\s*[\{\[]/` 判断：加 `JSON.parse` 只是多一个 try，成本极低，且能排除"以 { 开头的非 JSON 内容"
+
+### Decision 3: ToolCard 换用 <Markdown> 渲染
+
+**Choice:** 将 ToolCard 结果体从 `<span>→ {displayText}</span>` 改为 `<Markdown className="text-xs">{displayText}</Markdown>`。去掉 `font-mono`，让 Markdown 组件自行控制等宽代码块。
+
+**Rationale:** `<Markdown>` 已在 MessageBubble 中使用，是经过验证的成熟组件。ToolCard 结果体本身就是一个 markdown 内容区域，用同样的渲染方式保持一致性。
+
+**Alternatives considered:**
+- 保持纯文本 + 前端 JSON.pretty-print：需要额外引入 `prism` 或 `highlight.js`，增加 bundle size，且与 MessageBubble 的渲染方式不一致
+- 只在有 code fence 时用 Markdown，纯文本保持原样：分支逻辑增加了 ToolCard 复杂度，且 `<Markdown>` 对纯文本的渲染也是安全透传
+
+### Decision 4: 工具特定格式化规则
+
+**Choice:** 在 `formatToolResultForUI` 的 `switch` 中按 toolName 分派，最后统一做 JSON 检测兜底。
+
+| 工具 | 格式化规则 |
+|------|-----------|
+| `write_file` / `overwrite_file` | 保持现有摘要提取（extractWriteSummary） |
+| `bash` | 内容包 ```` ```sh ``` ````，保持截断 |
+| `grep` | JSON 检测 → pretty-print + ```` ```json ``` ````；非 JSON → ```` ``` ``` ```` |
+| `glob` | 同上 |
+| `read_file` | 内容包 ```` ``` ``` ````（可后续扩展语言检测），保持截断 |
+| 其他 | JSON 检测 → pretty-print + ```` ```json ``` ````；否则保持现有默认截断 |
+
+## Risks / Trade-offs
+
+- **Risk:** JSON.parse 在大字符串上可能耗时。**Mitigation:** grep/glob 的 JSON 输出通常较小（已截断到 600），且 `JSON.parse` 在 V8 中极快。
+- **Risk:** `write_file` 摘要中意外包含 markdown 语法字符（如 `_`、`*`）被错误渲染。**Mitigation:** 当前摘要只含 "Written X bytes to path" 和 "New file version: fv_xxx"——不含 markdown 特殊字符。如果后续摘要内容变化，用 escape 处理。
+- **Trade-off:** NDJSON（每行一个 JSON 对象）只能取首行。**Mitigation:** 大多数工具结果本身已截断到 600 字符，NDJSON 场景影响极小。
+- **Risk:** 某些工具结果本身就包含 ` ``` ` 字符，会破坏 markdown code fence。**Mitigation:** 罕见且当前 600 字符截断已大幅降低概率。可在 code fence 前后加 `\n` 作为天然分隔。

openspec/changes/archive/2025-07-14-format-tool-results-in-ui/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+工具结果在 ToolCard 中全部以纯文本（`font-mono whitespace-pre-wrap`）渲染。JSON 是一坨压缩字符串，Markdown 不解析，bash 输出没有代码块包裹——用户看到的是一堵灰墙。而同一消息气泡里的 assistant 正文已经通过 `<Markdown>` 组件完整渲染了，ToolCard 落后了。
+
+`unify-tool-result-formatting` 已经把截断逻辑收敛到 `formatToolResultForUI` 这个扼流点，现在是时候在这个基础之上让工具结果**有格式**。
+
+## What Changes
+
+- **增强** `formatToolResultForUI` — 在截断之外，增加内容感知的格式化：JSON 检测 + pretty-print + code fence、bash/read_file 包 code fence
+- **修改** `ToolCard.tsx` — 结果体从纯 `<span>` 改为 `<Markdown>` 渲染，去掉 `font-mono` 让 Markdown 控制排版
+- **不改** ToolCard 的容器结构、MessageBubble 布局、session 主界面
+
+## Capabilities
+
+### New Capabilities
+- `tool-result-content-rendering`: 工具结果按内容类型智能格式化（JSON pretty-print、代码块包裹、Markdown 透传），ToolCard 通过 Markdown 组件渲染结果文本
+
+### Modified Capabilities
+- `web-frontend`: ToolCard 的结果渲染方式从纯文本变为 Markdown 渲染
+
+## Impact
+
+- `src/ui/shared/tool-result-formatter.ts` — **修改**，增加 JSON 检测 + 内容感知格式化逻辑
+- `web/src/components/ToolCard.tsx` — **修改**，结果体换用 `<Markdown>` 组件
+- `tests/ui/tool-result-formatter.test.ts` — **修改**，补充新格式化行为的测试用例

openspec/changes/archive/2025-07-14-format-tool-results-in-ui/specs/tool-result-content-rendering/spec.md

@@ -0,0 +1,47 @@
+## ADDED Requirements
+
+### Requirement: Content-aware tool result formatting
+`formatToolResultForUI` SHALL detect the content type of tool result text and apply appropriate formatting before it reaches the frontend. The function SHALL produce markdown-ready output so that ToolCard can render it through the shared `<Markdown>` component.
+
+#### Scenario: JSON detected and pretty-printed
+- **WHEN** a tool result string starts with `{` or `[` and `JSON.parse` succeeds
+- **THEN** the function SHALL `JSON.stringify` the parsed value with 2-space indentation
+- **AND** SHALL wrap the result in a markdown code fence with `json` language tag (```` ```json ````)
+
+#### Scenario: bash tool result wrapped in code fence
+- **WHEN** a `bash` tool completes with output text
+- **THEN** the function SHALL wrap the result in a markdown code fence with `sh` language tag (```` ```sh ````)
+- **AND** SHALL preserve the existing truncation behavior (600 char default)
+
+#### Scenario: grep tool result with JSON output
+- **WHEN** a `grep` tool completes and the result is valid JSON
+- **THEN** the function SHALL pretty-print and wrap as ```` ```json ````
+- **AND** SHALL preserve the existing truncation behavior
+
+#### Scenario: grep tool result with plain text output
+- **WHEN** a `grep` tool completes and the result is not valid JSON
+- **THEN** the function SHALL wrap the result in a markdown code fence without language tag (```` ``` ````)
+- **AND** SHALL preserve the existing truncation behavior
+
+#### Scenario: glob tool result formatted
+- **WHEN** a `glob` tool completes
+- **THEN** the function SHALL apply the same JSON detection and code fence wrapping as `grep`
+
+#### Scenario: read_file tool result wrapped in code fence
+- **WHEN** a `read_file` tool completes with file content
+- **THEN** the function SHALL wrap the result in a markdown code fence without language tag (```` ``` ````)
+- **AND** SHALL preserve the existing truncation behavior
+
+#### Scenario: write_file / overwrite_file summary preserved
+- **WHEN** a `write_file` or `overwrite_file` tool completes
+- **THEN** the function SHALL continue to use the existing `extractWriteSummary` behavior
+- **AND** SHALL NOT apply additional code fence wrapping
+
+#### Scenario: Unknown tool with JSON result
+- **WHEN** an unrecognized tool produces a result that is valid JSON
+- **THEN** the function SHALL pretty-print and wrap as ```` ```json ````
+- **AND** SHALL preserve the existing 600-char truncation behavior
+
+#### Scenario: Unknown tool with non-JSON result
+- **WHEN** an unrecognized tool produces a result that is not JSON
+- **THEN** the function SHALL preserve the existing 600-char truncation behavior without code fence wrapping

openspec/changes/archive/2025-07-14-format-tool-results-in-ui/specs/web-frontend/spec.md

@@ -0,0 +1,51 @@
+## MODIFIED Requirements
+
+### Requirement: Conversation view
+The frontend SHALL display a scrollable conversation area showing user messages, assistant responses with streaming text, thinking blocks with elapsed time indicators, and tool call results, all using the warm flat design system styling. Message state management SHALL use the shared `conversationReducer` from `@dscode/shared/reducer` instead of inline event handling logic. The elapsed time display SHALL be derived from `turnStartRef` (set by `handleSend` or `loader { state: "show" }`) rather than the `processing` state flag. When an assistant message has no text content, the content area SHALL render nothing instead of a "(no content)" placeholder. The conversation scroll container SHALL use `min-height: 0` (Tailwind `min-h-0`) to allow proper flexbox constraint and prevent overflow clipping of large content. Auto-scroll to the bottom SHALL only occur when the user's scroll position is at or near the bottom of the container (within 64px threshold). When the user has manually scrolled away from the bottom, auto-scroll SHALL be suppressed until the user scrolls back to the bottom.
+
+#### Scenario: User message display
+- **WHEN** user submits a message
+- **THEN** the message appears right-aligned with a warm amber accent background and warm white text, using `border-radius: 12px` bubble shape with subtle fade-up entrance animation (disabled under `prefers-reduced-motion`)
+
+#### Scenario: Streaming assistant response
+- **WHEN** the server sends `text_delta` events
+- **THEN** the assistant message bubble updates incrementally via `conversationReducer`, using the warm surface background, `1px solid` border, and warm text colors
+
+#### Scenario: Thinking block display with timer
+- **WHEN** the server sends `thinking_delta` events
+- **THEN** the thinking content appears in a collapsible `<details>` block (open during streaming) with muted warm styling and a subtle left border accent, and the summary shows `Thinking... (Xs)` where X is the elapsed seconds since `turnStartRef` was set by `handleSend`
+
+#### Scenario: Tool call display
+- **WHEN** the server sends `tool_start` and `tool_end` events
+- **THEN** each tool call appears as an inline flat card with `border-radius: 8px`, `1px solid` warm border, tool name in monospace with amber accent, and muted pastel success/error indicators
+- **AND** the tool result text SHALL be rendered through the shared `<Markdown>` component, supporting code blocks with syntax hints, tables, links, and inline code formatting
+
+#### Scenario: Tool result rendered as Markdown
+- **WHEN** a tool call card displays its result text
+- **THEN** the result body SHALL use the `<Markdown>` component instead of plain text
+- **AND** code fences within the result SHALL render as styled code blocks with monospace font
+
+#### Scenario: Empty assistant content renders nothing
+- **WHEN** an assistant message has no text content (empty string), with or without thinking and tools
+- **THEN** the message bubble content area renders nothing; no "(no content)" placeholder is displayed
+
+#### Scenario: Large tool call result does not break scrolling
+- **WHEN** a tool call (e.g., write_file) returns a result that is larger than the viewport height
+- **THEN** the ChatView scroll container remains constrained to the viewport and the user can scroll to the bottom of the conversation to see all content, including the message input and the tail of the assistant bubble
+- **AND** the tool result body SHALL retain `max-h-40 overflow-y-auto` as a scroll-defense container
+
+#### Scenario: Auto-scroll during streaming is instant — only when at bottom
+- **WHEN** the conversation has a streaming message (hasStreaming is true) AND the user's scroll position is within 64px of the container bottom
+- **THEN** auto-scroll to the bottom uses `scrollIntoView({ behavior: "instant" })` instead of smooth behavior
+
+#### Scenario: Auto-scroll when idle is smooth — only when at bottom
+- **WHEN** the conversation has no streaming message (hasStreaming is false) AND the user's scroll position is within 64px of the container bottom
+- **THEN** auto-scroll to the bottom uses `scrollIntoView({ behavior: "smooth" })` for a polished user experience
+
+#### Scenario: Auto-scroll suppressed when user scrolls away
+- **WHEN** the user has manually scrolled more than 64px away from the container bottom AND a state change would normally trigger auto-scroll (messages update, processing toggle, permission prompt)
+- **THEN** auto-scroll does NOT fire; the user's current scroll position is preserved
+
+#### Scenario: Auto-scroll re-engages on return to bottom
+- **WHEN** the user manually scrolls back to within 64px of the container bottom
+- **THEN** subsequent state changes resume auto-scrolling to the bottom

openspec/changes/archive/2025-07-14-format-tool-results-in-ui/tasks.md

@@ -0,0 +1,32 @@
+## 1. 增强 `formatToolResultForUI` 内容感知格式化
+
+- [x] 1.1 添加 `isJSON(text)` helper — 检测 `{` / `[` 开头 + `JSON.parse` 成功
+- [x] 1.2 添加 `formatCodeBlock(text, lang?)` helper — 将文本包入 ```` ```lang ```` code fence
+- [x] 1.3 扩展 `switch` 分支：`bash` → ```` ```sh ````，`grep` → JSON 检测 + code fence，`glob` → 同 grep，`read_file` → ```` ``` ````
+- [x] 1.4 在 `default` 分支添加 JSON 检测兜底：有效 JSON → ```` ```json ```` + pretty-print
+- [x] 1.5 确保 `write_file` / `overwrite_file` 不受影响（仍走 `extractWriteSummary`）
+
+## 2. 更新测试
+
+- [x] 2.1 添加 JSON 检测 + pretty-print 的测试用例
+- [x] 2.2 添加 `bash` / `grep` / `glob` / `read_file` code fence 测试用例
+- [x] 2.3 添加 `default` JSON 兜底测试用例
+- [x] 2.4 确保 `write_file` 现有测试仍然通过
+- [x] 2.5 运行 `npx vitest run` 确认全部通过
+
+## 3. ToolCard 改用 Markdown 渲染
+
+- [x] 3.1 在 `ToolCard.tsx` 中 import `<Markdown>` 组件
+- [x] 3.2 将结果体 `displayText` 的渲染从纯 `<span>` 改为 `<Markdown className="text-xs">`
+- [x] 3.3 去掉结果容器的 `font-mono break-all whitespace-pre-wrap`（Markdown 自行处理排版）
+- [x] 3.4 保留 `max-h-40 overflow-y-auto` 作为滚动防御
+
+## 4. 验证
+
+- [x] 4.1 `npx tsc --noEmit -p tsconfig.json` 通过
+- [x] 4.2 `npx vitest run` 通过
+- [x] 4.3 手动验证：执行 `bash` 工具，确认结果有代码块样式
+- [x] 4.4 手动验证：执行 `grep` 工具（JSON 输出），确认 JSON 被 pretty-print + 语法高亮
+- [x] 4.5 手动验证：加载历史 session，确认 History 路径也正确格式化
+- [x] 4.6 手动验证：`write_file` 结果仍显示摘要（不受影响）
+- [x] 4.7 手动验证：ToolCard 卡片布局和 session 主界面结构未变化

openspec/changes/archive/2025-07-14-reset-ui-on-current-session-delete/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-17