From 1674af147e5fe6990ec0f7b37a21716fd07ba174 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 8 Aug 2026 15:18:04 +0800 Subject: [PATCH 01/17] cleanup(client): detach conversation rows from Tool presentation --- .../src/client/chat/AssistantMarkdown.tsx | 34 +----- .../src/client/chat/DisclosureRow.module.css | 2 +- .../src/client/chat/DisclosureRow.tsx | 4 +- .../client/chat/GenericCommandCard.module.css | 86 +++++++++++++ .../src/client/chat/GenericCommandCard.tsx | 52 +++++--- .../src/client/chat/ReasoningRow.module.css | 81 ++++++++++++ .../src/client/chat/ReasoningRow.tsx | 62 ++++++++++ .../chat/use-throttled-visual-update.ts | 4 +- .../tests/reasoning-row.spec.tsx | 115 ++++++++++++++++++ 9 files changed, 389 insertions(+), 51 deletions(-) create mode 100644 packages/client/ui-conversation/src/client/chat/GenericCommandCard.module.css create mode 100644 packages/client/ui-conversation/src/client/chat/ReasoningRow.module.css create mode 100644 packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx create mode 100644 packages/client/ui-conversation/tests/reasoning-row.spec.tsx diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx index bc1c6c7e32..9d0c26506e 100644 --- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx +++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx @@ -12,13 +12,11 @@ import { memo, useMemo } from 'react' import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client' import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots' -import { - IconThinkOutline14, JsonBlock, MarkdownText, -} from '@deepseek-ai/dsh-client-ui-primitives' +import { JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives' import type { ChatViewSlotProps, TurnTailOwnerProps } from '../contract/slots.ts' import { hasContentText } from './chat-flow.ts' import { MessageIconActions } from './MessageIconActions.tsx' -import { ToolRow } from './ToolRow.tsx' +import { ReasoningRow } from './ReasoningRow.tsx' import css from './AssistantMarkdown.module.css' export interface AssistantMarkdownProps { @@ -49,18 +47,6 @@ export interface AssistantMarkdownProps { t: ChatViewSlotProps['t'] } -function firstLine(text: string): string { - const nl = text.indexOf('\n') - return nl === -1 ? text : text.slice(0, nl) -} - -/** Latest non-blank reasoning line while the block is still streaming. */ -function latestLine(text: string): string { - const visible = text.trimEnd() - const nl = visible.lastIndexOf('\n') - return nl === -1 ? visible : visible.slice(nl + 1) -} - /** Joined text blocks for the copy action (reasoning / tool heads stay out). */ function copyText(blocks: readonly AssistantBlock[]): string { const parts: string[] = [] @@ -71,20 +57,6 @@ function copyText(blocks: readonly AssistantBlock[]): string { } /** Reasoning block as the Think variant summary row (figma 39:28304). */ -function ThinkRow({ text, running, t }: { text: string; running: boolean; t: AssistantMarkdownProps['t'] }) { - return ( - } - title="Think" - summary={running ? latestLine(text) : firstLine(text)} - body={text} - state={running ? 'running' : 'ok'} - /> - ) -} - export const AssistantMarkdown = memo(function AssistantMarkdown({ blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail, t, }: AssistantMarkdownProps) { @@ -109,7 +81,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({ case 'text': return ( ) - case 'reasoning': return + case 'reasoning': return // Grouped into tool rows by ChatView; hasVisible above skips an empty shell. case 'tool-call': return null default: return ( diff --git a/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css b/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css index 04f2d18d0a..51937ab462 100644 --- a/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css +++ b/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css @@ -1,4 +1,4 @@ -/* Shared Tool calls disclosure header: [16px leading] gap 6 [title 14/24]. */ +/* Shared conversation disclosure header: [16px leading] gap 6 [title 14/24]. */ .root { display: flex; diff --git a/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx b/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx index 361fb24517..a95114ff2f 100644 --- a/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx +++ b/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx @@ -14,7 +14,7 @@ export interface DisclosureRowProps { expandOnRowClick?: boolean | undefined /** Replaces the collapsed icon with a chevron while the row is hovered. */ previewChevron?: boolean | undefined - /** Keeps `collapsedContent` inline while open (ToolRow's summary stays readable next to the expanded card). */ + /** Keeps `collapsedContent` inline while open. */ keepContentWhenOpen?: boolean | undefined collapsedContent?: ReactNode children?: ReactNode @@ -28,7 +28,7 @@ export interface DisclosureRowProps { /** * Render one disclosure header and its controlled expanded content. * @param props - Visual content, controlled state, and interaction policy. - * @returns The disclosure row. + * @returns the disclosure row. */ export function DisclosureRow({ icon, diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.module.css b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.module.css new file mode 100644 index 0000000000..d090c890b2 --- /dev/null +++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.module.css @@ -0,0 +1,86 @@ +.root { + display: flex; + flex-direction: column; +} + +.row { + position: relative; + overflow: hidden; +} + +.root[data-state='running'] .row::after { + content: ''; + position: absolute; + inset-block: 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-command-row-sweep 2.6s ease-out infinite; + pointer-events: none; +} + +@keyframes dsh-command-row-sweep { + 0% { left: -300px; } + 90%, 100% { left: 100%; } +} + +.leading { + flex-shrink: 0; +} + +.chevron { + color: var(--dsw-alias-label-secondary); +} + +.title { + font-weight: 400; +} + +.separator { + flex: none; + width: 2px; + height: 2px; + margin: 0 8px; + border-radius: 1px; + background: var(--dsw-alias-label-caption); +} + +.summary { + min-width: 0; + overflow: hidden; + flex: 1 1 auto; + color: var(--dsw-alias-label-tertiary); + font-size: 14px; + line-height: 24px; + text-overflow: ellipsis; + white-space: nowrap; +} + +.summary[data-error], +.body[data-error] { + color: var(--dsw-alias-state-error-primary); +} + +.body { + max-height: 260px; + margin: 4px 0 4px 4px; + padding: 12px 16px; + overflow: auto; + border: 1px solid var(--dsw-alias-border-l1); + border-radius: 12px; + background: var(--dsw-alias-markdown-code-block); + color: var(--dsw-alias-label-primary); + font: var(--dsw-font-markdown-code-block-small); + white-space: pre-wrap; +} + +@media (prefers-reduced-motion: reduce) { + .root[data-state='running'] .row::after { + animation: none; + } +} diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx index aa236c87ca..7bf7d74d2f 100644 --- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx +++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx @@ -4,23 +4,31 @@ // fallback (an unregistered command name lands here); registrants may compose // it as a base, feeding the same owner payload through. -import { ToolRow } from './ToolRow.tsx' -import type { ToolRowState } from '../contract/tool-call-model.ts' +import { useState, type ReactNode } from 'react' import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts' -import { IconApiOutline14 } from '@deepseek-ai/dsh-client-ui-primitives' +import { IconApiOutline14, StateDot } from '@deepseek-ai/dsh-client-ui-primitives' +import { DisclosureRow } from './DisclosureRow.tsx' +import css from './GenericCommandCard.module.css' + +type CommandRowState = 'running' | 'ok' | 'error' /** Node state → row state semantic (running while unsettled; outcome kind after). */ -function stateOf(outcome: CommandRowOwnerProps['node']['outcome']): ToolRowState { +function stateOf(outcome: CommandRowOwnerProps['node']['outcome']): CommandRowState { if (outcome === null) return 'running' return outcome.kind === 'error' ? 'error' : 'ok' } +function leadingFor(state: CommandRowState): ReactNode { + return state === 'error' ? : +} + /** Card props: the owner payload plus the render site's locale seat (plain prop). */ export interface GenericCommandCardProps extends CommandRowOwnerProps { t: ChatViewSlotProps['t'] } export function GenericCommandCard({ node, t }: GenericCommandCardProps) { + const [expanded, setExpanded] = useState(false) const text = node.outcome?.text const summary = node.outcome === null ? t('command.running') @@ -30,16 +38,32 @@ export function GenericCommandCard({ node, t }: GenericCommandCardProps) { // settlement text says (`permission · preset workspace-write`). A // cross-window node whose run page fell out of the window has no name. const title = node.name ?? t('command.title') + const state = stateOf(node.outcome) + const body = text !== undefined && text.includes('\n') ? text : null + const open = expanded && body !== null return ( - } - title={title} - summary={summary} - // Expandable only when the outcome text overflows a one-line summary. - body={text !== undefined && text.includes('\n') ? text : null} - state={stateOf(node.outcome)} - /> +
+ { setExpanded(value => !value) }} + collapsedContent={( + <> + + {summary} + + )} + > + 
{body}
+ +
) } diff --git a/packages/client/ui-conversation/src/client/chat/ReasoningRow.module.css b/packages/client/ui-conversation/src/client/chat/ReasoningRow.module.css new file mode 100644 index 0000000000..6b2f6c0cd3 --- /dev/null +++ b/packages/client/ui-conversation/src/client/chat/ReasoningRow.module.css @@ -0,0 +1,81 @@ +.root { + display: flex; + flex-direction: column; +} + +.row { + position: relative; + overflow: hidden; +} + +.root[data-state='running'] .row::after { + content: ''; + position: absolute; + inset-block: 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-reasoning-row-sweep 2.6s ease-out infinite; + pointer-events: none; +} + +@keyframes dsh-reasoning-row-sweep { + 0% { left: -300px; } + 90%, 100% { left: 100%; } +} + +.leading { + flex-shrink: 0; +} + +.chevron { + color: var(--dsw-alias-label-secondary); +} + +.title { + font-weight: 400; +} + +.separator { + flex: none; + width: 2px; + height: 2px; + margin: 0 8px; + border-radius: 1px; + background: var(--dsw-alias-label-caption); +} + +.summary { + min-width: 0; + overflow: hidden; + flex: 1 1 auto; + color: var(--dsw-alias-label-tertiary); + font-size: 14px; + line-height: 24px; + text-overflow: ellipsis; + white-space: nowrap; +} + +.summary[data-follow-end] { + text-overflow: clip; +} + +.thinkBody { + padding: 4px 0 4px 22px; + color: var(--dsw-alias-label-tertiary); + font-size: 14px; + line-height: 24px; + white-space: pre-wrap; + word-break: break-word; +} + +@media (prefers-reduced-motion: reduce) { + .root[data-state='running'] .row::after { + animation: none; + } +} diff --git a/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx new file mode 100644 index 0000000000..d02bd855b4 --- /dev/null +++ b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx @@ -0,0 +1,62 @@ +/** Assistant reasoning disclosure, independent of Tool-call presentation. */ +import { useEffect, useRef, useState } from 'react' +import { IconThinkOutline14 } from '@deepseek-ai/dsh-client-ui-primitives' +import { DisclosureRow } from './DisclosureRow.tsx' +import { useThrottledVisualUpdate } from './use-throttled-visual-update.ts' +import css from './ReasoningRow.module.css' + +function firstLine(text: string): string { + const newline = text.indexOf('\n') + return newline === -1 ? text : text.slice(0, newline) +} + +function latestLine(text: string): string { + const visible = text.trimEnd() + const newline = visible.lastIndexOf('\n') + return newline === -1 ? visible : visible.slice(newline + 1) +} + +/** + * Render one assistant reasoning block as the Think disclosure row. + * @param props.text - complete or streaming reasoning text. + * @param props.running - whether this block is the streaming tail. + * @returns the reasoning disclosure. + */ +export function ReasoningRow({ text, running }: { text: string; running: boolean }) { + const [expanded, setExpanded] = useState(false) + const summaryRef = useRef(null) + const summary = running ? latestLine(text) : firstLine(text) + const scheduleSummaryScroll = useThrottledVisualUpdate(() => { + const element = summaryRef.current + if (element === null) return + element.scrollLeft = running ? element.scrollWidth - element.clientWidth : 0 + }) + useEffect(() => { + scheduleSummaryScroll() + }, [running, scheduleSummaryScroll, summary]) + + return ( +
+ } + title="Think" + open={expanded} + expandable + expandOnRowClick + onToggle={() => { setExpanded(value => !value) }} + collapsedContent={( + <> + + {summary} + + )} + > +
{text}
+ +
+ ) +} diff --git a/packages/client/ui-conversation/src/client/chat/use-throttled-visual-update.ts b/packages/client/ui-conversation/src/client/chat/use-throttled-visual-update.ts index e282b4b087..8fec1832d1 100644 --- a/packages/client/ui-conversation/src/client/chat/use-throttled-visual-update.ts +++ b/packages/client/ui-conversation/src/client/chat/use-throttled-visual-update.ts @@ -1,14 +1,12 @@ /** Frame-throttled scheduling for non-essential visual alignment. */ - import { useCallback, useLayoutEffect, useRef } from 'react' const DEFAULT_INTERVAL_FRAMES = 3 /** * Return a stable scheduler that coalesces visual updates over a frame interval. - * Repeated calls retain the latest callback, and unmount cancels pending work. * @param update - DOM alignment to run after the throttle interval. - * @param intervalFrames - Frames to wait before applying the latest alignment. + * @param intervalFrames - frames to wait before applying the latest alignment. * @returns a stable function that schedules the latest update. */ export function useThrottledVisualUpdate( diff --git a/packages/client/ui-conversation/tests/reasoning-row.spec.tsx b/packages/client/ui-conversation/tests/reasoning-row.spec.tsx new file mode 100644 index 0000000000..243b665ce2 --- /dev/null +++ b/packages/client/ui-conversation/tests/reasoning-row.spec.tsx @@ -0,0 +1,115 @@ +// @vitest-environment jsdom +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { cleanup, fireEvent, render } from '@testing-library/react' +import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' +import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' +import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx' +import { zh } from '../src/client/locales.ts' + +let nextAnimationFrameId = 1 +let animationFrames = new Map() + +function flushAnimationFrames(count: number): void { + for (let index = 0; index < count; index += 1) { + const callbacks = [...animationFrames.values()] + animationFrames.clear() + for (const callback of callbacks) callback(index) + } +} + +beforeEach(() => { + nextAnimationFrameId = 1 + animationFrames = new Map() + vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => { + const id = nextAnimationFrameId + nextAnimationFrameId += 1 + animationFrames.set(id, callback) + return id + }) + vi.stubGlobal('cancelAnimationFrame', (id: number) => { + animationFrames.delete(id) + }) +}) + +afterEach(() => { + cleanup() + vi.unstubAllGlobals() +}) + +const t = makeTranslate(zh, commonZh) + +describe('ReasoningRow', () => { + it('follows the latest streaming line, scrolls to its end, then restores the settled first line', () => { + const view = render( + , + ) + const summary = view.getByText('Newest reasoning tokens') + Object.defineProperties(summary, { + scrollWidth: { configurable: true, value: 300 }, + clientWidth: { configurable: true, value: 100 }, + }) + + view.rerender( + , + ) + expect(summary.scrollLeft).toBe(0) + flushAnimationFrames(2) + expect(summary.scrollLeft).toBe(0) + flushAnimationFrames(1) + expect(summary.scrollLeft).toBe(200) + expect(summary.getAttribute('data-follow-end')).toBe('true') + + view.rerender( + , + ) + flushAnimationFrames(3) + expect(view.getByText('Inspect the session')).toBeTruthy() + expect(summary.scrollLeft).toBe(0) + expect(summary.hasAttribute('data-follow-end')).toBe(false) + }) + + it('expands from either Think or the reasoning summary', () => { + const view = render( + , + ) + const row = view.getByRole('button') + + fireEvent.click(view.getByText('Inspect the session')) + expect(row.getAttribute('aria-expanded')).toBe('true') + expect(view.getByText(/Check persistence/)).toBeTruthy() + + fireEvent.click(view.getByText('Think')) + expect(row.getAttribute('aria-expanded')).toBe('false') + }) + + it('expanded Think drops the inline summary and renders plain prose, no IN card', () => { + const view = render( + , + ) + fireEvent.click(view.getByText('Think')) + expect(view.getAllByText(/Inspect the session/)).toHaveLength(1) + expect(view.queryByText('IN')).toBeNull() + expect(view.container.querySelector('[class*="ioCard"]')).toBeNull() + expect(view.container.querySelector('[class*="thinkBody"]')).not.toBeNull() + }) +}) From 7cc554ef16b4a77aeff4d728d878160d674fb033 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 8 Aug 2026 15:18:52 +0800 Subject: [PATCH 02/17] cleanup(client): extract Tool presentation into ui-tool --- packages/bundle/web-app/cordis.patch.yml | 4 + packages/bundle/web-app/package.json | 1 + packages/client/AGENTS.md | 2 +- packages/client/README.i18n.yaml | 4 +- packages/client/README.md | 1 + packages/client/README.zh.md | 1 + .../client/connection/src/client/fixture.ts | 22 +-- packages/client/runtime/src/client/index.ts | 2 +- .../client/ui-conversation/README.i18n.yaml | 4 +- packages/client/ui-conversation/README.md | 22 +-- packages/client/ui-conversation/README.zh.md | 22 +-- packages/client/ui-conversation/package.json | 2 +- .../ui-conversation/src/client/apply.ts | 50 +----- .../src/client/chat/ChatView.module.css | 11 -- .../src/client/chat/ChatView.tsx | 135 +++------------ .../src/client/contract/slots.ts | 62 ++++--- .../src/client/contract/tool-path.ts | 15 ++ .../ui-conversation/src/client/index.ts | 7 +- .../client/skeleton/DetailsPanel.module.css | 33 ---- .../src/client/skeleton/DetailsPanel.tsx | 113 +++---------- .../client/ui-conversation/src/invariant.ts | 2 +- .../tests/assembly-surfaces.spec.tsx | 134 +-------------- .../ui-conversation/tests/chat-apply.spec.tsx | 24 ++- ...sh-sample.spec.tsx => chat-stats.spec.tsx} | 53 +----- .../ui-conversation/tests/chat-view.spec.tsx | 122 +++++++------- .../tests/coverage-tails.spec.tsx | 90 +--------- .../tests/gate-branch-tails.spec.tsx | 32 +++- .../ui-conversation/tests/todo-panel.spec.tsx | 157 +---------------- .../tests/views-type-chain.spec.tsx | 37 +--- packages/client/ui-skill/README.i18n.yaml | 4 +- packages/client/ui-skill/README.md | 2 +- packages/client/ui-skill/README.zh.md | 2 +- packages/client/ui-skill/package.json | 6 +- .../client/ui-skill/src/client/SkillRow.tsx | 12 +- packages/client/ui-skill/src/client/index.ts | 4 +- .../ui-skill/tests/browser-plugin.spec.ts | 6 +- packages/client/ui-skill/tsconfig.json | 2 +- packages/client/ui-tool/README.i18n.yaml | 6 + packages/client/ui-tool/README.md | 44 +++++ packages/client/ui-tool/README.zh.md | 44 +++++ packages/client/ui-tool/package.json | 73 ++++++++ packages/client/ui-tool/src/client/apply.ts | 43 +++++ .../ui-tool/src/client/contract/slots.ts | 39 +++++ packages/client/ui-tool/src/client/index.ts | 3 + packages/client/ui-tool/src/client/locale.ts | 2 + .../src/client/tool/ToolCallTree.module.css | 12 ++ .../ui-tool/src/client/tool/ToolCallTree.tsx | 88 ++++++++++ .../src/client/tool/ToolDetails.module.css | 46 +++++ .../ui-tool/src/client/tool/ToolDetails.tsx | 66 ++++++++ .../tool/components/DisclosureRow.module.css | 69 ++++++++ .../client/tool/components/DisclosureRow.tsx | 104 ++++++++++++ .../tool/components}/ToolRow.module.css | 18 -- .../src/client/tool/components}/ToolRow.tsx | 106 +++++------- .../client/tool/models}/diff-card-model.ts | 0 .../client/tool/models}/read-card-model.ts | 0 .../client/tool/models}/search-card-model.ts | 0 .../tool/models}/terminal-card-model.ts | 0 .../client/tool/models}/tool-call-model.ts | 10 +- .../src/client/tool/models}/web-card-model.ts | 0 .../tool/toolviews}/GenericToolCard.tsx | 28 ++-- .../tool}/toolviews/ask-question-row.tsx | 18 +- .../tool}/toolviews/bash-sample.module.css | 0 .../client/tool}/toolviews/bash-sample.tsx | 16 +- .../tool}/toolviews/file-mutation-row.tsx | 20 +-- .../client/tool}/toolviews/plan-summary.ts | 0 .../src/client/tool}/toolviews/read-row.tsx | 20 +-- .../src/client/tool}/toolviews/search-row.tsx | 22 +-- .../src/client/tool}/toolviews/todo-row.tsx | 20 +-- .../src/client/tool}/toolviews/web-row.tsx | 20 +-- packages/client/ui-tool/src/css-modules.d.ts | 4 + packages/client/ui-tool/src/index.ts | 4 + packages/client/ui-tool/src/invariant.ts | 30 ++++ .../tests/ask-question-row.spec.tsx | 8 +- .../ui-tool/tests/assembly-surfaces.spec.tsx | 149 +++++++++++++++++ .../tests/chat-code-subcalls.spec.tsx | 11 +- .../ui-tool/tests/coverage-tails.spec.tsx | 116 +++++++++++++ .../tests/diff-card.spec.tsx | 15 +- .../tests/read-card.spec.tsx | 17 +- .../tests/search-card.spec.tsx | 15 +- .../tests/terminal-card.spec.tsx | 17 +- .../client/ui-tool/tests/todo-row.spec.tsx | 158 ++++++++++++++++++ .../ui-tool/tests/tool-call-tree.spec.tsx | 63 +++++++ .../ui-tool/tests/tool-details-render.tsx | 22 +++ .../tests/tool-row-styles.spec.ts | 2 +- .../tests/tool-row.spec.tsx} | 114 +------------ .../tests/toolview-slot.spec.tsx} | 37 ++-- .../tests/toolview-type-chain.spec.tsx | 34 ++++ .../tests/web-card.spec.tsx | 20 ++- packages/client/ui-tool/tsconfig.json | 33 ++++ packages/client/ui-tool/tsdown.config.ts | 3 + pnpm-lock.yaml | 58 ++++++- tsconfig.base.json | 1 + tsconfig.client.json | 1 + vitest.config.ts | 1 + 94 files changed, 1797 insertions(+), 1275 deletions(-) create mode 100644 packages/client/ui-conversation/src/client/contract/tool-path.ts rename packages/client/ui-conversation/tests/{chat-stats-bash-sample.spec.tsx => chat-stats.spec.tsx} (87%) create mode 100644 packages/client/ui-tool/README.i18n.yaml create mode 100644 packages/client/ui-tool/README.md create mode 100644 packages/client/ui-tool/README.zh.md create mode 100644 packages/client/ui-tool/package.json create mode 100644 packages/client/ui-tool/src/client/apply.ts create mode 100644 packages/client/ui-tool/src/client/contract/slots.ts create mode 100644 packages/client/ui-tool/src/client/index.ts create mode 100644 packages/client/ui-tool/src/client/locale.ts create mode 100644 packages/client/ui-tool/src/client/tool/ToolCallTree.module.css create mode 100644 packages/client/ui-tool/src/client/tool/ToolCallTree.tsx create mode 100644 packages/client/ui-tool/src/client/tool/ToolDetails.module.css create mode 100644 packages/client/ui-tool/src/client/tool/ToolDetails.tsx create mode 100644 packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css create mode 100644 packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx rename packages/client/{ui-conversation/src/client/chat => ui-tool/src/client/tool/components}/ToolRow.module.css (94%) rename packages/client/{ui-conversation/src/client/chat => ui-tool/src/client/tool/components}/ToolRow.tsx (76%) rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/diff-card-model.ts (100%) rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/read-card-model.ts (100%) rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/search-card-model.ts (100%) rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/terminal-card-model.ts (100%) rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/tool-call-model.ts (95%) rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/web-card-model.ts (100%) rename packages/client/{ui-conversation/src/client/chat => ui-tool/src/client/tool/toolviews}/GenericToolCard.tsx (76%) rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/ask-question-row.tsx (85%) rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/bash-sample.module.css (100%) rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/bash-sample.tsx (93%) rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/file-mutation-row.tsx (77%) rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/plan-summary.ts (100%) rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/read-row.tsx (75%) rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/search-row.tsx (80%) rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/todo-row.tsx (83%) rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/web-row.tsx (77%) create mode 100644 packages/client/ui-tool/src/css-modules.d.ts create mode 100644 packages/client/ui-tool/src/index.ts create mode 100644 packages/client/ui-tool/src/invariant.ts rename packages/client/{ui-conversation => ui-tool}/tests/ask-question-row.spec.tsx (95%) create mode 100644 packages/client/ui-tool/tests/assembly-surfaces.spec.tsx rename packages/client/{ui-conversation => ui-tool}/tests/chat-code-subcalls.spec.tsx (96%) create mode 100644 packages/client/ui-tool/tests/coverage-tails.spec.tsx rename packages/client/{ui-conversation => ui-tool}/tests/diff-card.spec.tsx (97%) rename packages/client/{ui-conversation => ui-tool}/tests/read-card.spec.tsx (95%) rename packages/client/{ui-conversation => ui-tool}/tests/search-card.spec.tsx (97%) rename packages/client/{ui-conversation => ui-tool}/tests/terminal-card.spec.tsx (98%) create mode 100644 packages/client/ui-tool/tests/todo-row.spec.tsx create mode 100644 packages/client/ui-tool/tests/tool-call-tree.spec.tsx create mode 100644 packages/client/ui-tool/tests/tool-details-render.tsx rename packages/client/{ui-conversation => ui-tool}/tests/tool-row-styles.spec.ts (94%) rename packages/client/{ui-conversation/tests/chat-tool-row.spec.tsx => ui-tool/tests/tool-row.spec.tsx} (83%) rename packages/client/{ui-conversation/tests/chat-toolview-slot.spec.tsx => ui-tool/tests/toolview-slot.spec.tsx} (84%) create mode 100644 packages/client/ui-tool/tests/toolview-type-chain.spec.tsx rename packages/client/{ui-conversation => ui-tool}/tests/web-card.spec.tsx (94%) create mode 100644 packages/client/ui-tool/tsconfig.json create mode 100644 packages/client/ui-tool/tsdown.config.ts diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml index 739f045ce6..62ed35bd49 100644 --- a/packages/bundle/web-app/cordis.patch.yml +++ b/packages/bundle/web-app/cordis.patch.yml @@ -149,6 +149,10 @@ - id: ui-conversation name: '@deepseek-ai/dsh-client-ui-conversation' + # Tool call tree, generic fallback, and keyed business Tool views. + - id: ui-tool + name: '@deepseek-ai/dsh-client-ui-tool' + # Turn tail: the produced-files row under each closing assistant message. # Remove this entry to turn the surface off; the tail hole renders empty. - id: ui-deliverables diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json index 4e2d9cf70b..9b8e15fd66 100644 --- a/packages/bundle/web-app/package.json +++ b/packages/bundle/web-app/package.json @@ -55,6 +55,7 @@ "@deepseek-ai/dsh-client-ui-slash": "workspace:^", "@deepseek-ai/dsh-client-ui-subagent": "workspace:^", "@deepseek-ai/dsh-client-ui-theme": "workspace:^", + "@deepseek-ai/dsh-client-ui-tool": "workspace:^", "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^", "@deepseek-ai/dsh-client-ui-workspace": "workspace:^", "@deepseek-ai/dsh-code-runtime-worker": "workspace:^", diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md index df7374d7c7..d534e5bb83 100644 --- a/packages/client/AGENTS.md +++ b/packages/client/AGENTS.md @@ -9,7 +9,7 @@ Packages here are named with the directory prefix: `@deepseek-ai/dsh-client-..` (e.g. `'conversation.chat.toolview'`). +2. **children = declaration + authorization**: the slots your component renders are exactly the keys of your register call's `children` object (spec values: `kind`/`scope`). Rendering a slot you didn't declare, or declaring one someone else declared, fails at load — do not work around it; the conflict is the design speaking. Slot names mirror the composition path: `..` (e.g. `'tool.call.toolview'`). 3. **Component props are the four shares, all derived**: `PropsRuntime` (SlotMap: owner params + `useSession`/`sessionId` on session scope + global `useSessions`/`useWorkspaces`) & `PropsRenderSlots` (children keys) & `PropsStore` (store factory) & the inject face. Never hand-write a member a share already derives; never re-type a share locally. 4. **Hooks are framework-made only**: `useSession`, `useSessions`, `useWorkspaces`, `useStore`, `renderSlot` are the five standing seats, plus the `use` hooks the renderer binds from provide contributions and inject `hooks` compartments. Business code never creates a hook or selector as a prop value — pass plain data and callbacks. (Component-internal behavioral hooks that subscribe to nothing external are fine.) 5. **Live data has exactly three channels**: parent knows it → owner props at the renderSlot site; only the component knows it → local state; shared across entries or survives remounts → a store declared at register. Derived data is a pure function over framework-hook data (`useMemo`), never its own subscription. diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml index 503a747087..e65d5246a4 100644 --- a/packages/client/README.i18n.yaml +++ b/packages/client/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/README.md -README.md: b950772d4cad6d873426f8aee6416fa56afca2ee -README.zh.md: 8f1f7f46777b7037e8baa04c9ec16ef74ffd478d +README.md: b6fa426fbe541e2b22d2bf5f19d4397361cf0899 +README.zh.md: 5a55bb8c2c31b5215fc73e75e1c4f3aca79add64 diff --git a/packages/client/README.md b/packages/client/README.md index b950772d4c..b6fa426fbe 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -22,6 +22,7 @@ The browser side of the dsh web GUI: shell boot, browser-host communication, sha | [`ui-sidebar/`](ui-sidebar/README.md) | Presents workspace and session navigation. | | [`ui-workspace/`](ui-workspace/README.md) | Provides workspace selection and creation surfaces. | | [`ui-conversation/`](ui-conversation/README.md) | Presents the active conversation and its input surface. | +| [`ui-tool/`](ui-tool/README.md) | Composes Tool call trees and keyed per-Tool views. | | [`ui-goal/`](ui-goal/README.md) | Presents and manages the current goal. | | [`ui-trajectory/`](ui-trajectory/README.md) | Presents alternate views of agent activity. | | [`ui-command/`](ui-command/README.md) | Provides session-aware command discovery and dispatch. | diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md index 8f1f7f4677..5a55bb8c2c 100644 --- a/packages/client/README.zh.md +++ b/packages/client/README.zh.md @@ -22,6 +22,7 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U | [`ui-sidebar/`](ui-sidebar/README.md) | 展示 Workspace 与会话导航。 | | [`ui-workspace/`](ui-workspace/README.md) | 提供 Workspace 选择与创建界面。 | | [`ui-conversation/`](ui-conversation/README.md) | 展示当前会话及其输入界面。 | +| [`ui-tool/`](ui-tool/README.md) | 编排 Tool 调用树和按 Tool 键控的视图。 | | [`ui-goal/`](ui-goal/README.md) | 展示和管理当前目标。 | | [`ui-trajectory/`](ui-trajectory/README.md) | 提供 agent（智能体）活动的其他视图。 | | [`ui-command/`](ui-command/README.md) | 提供会话感知的命令发现与分发。 | diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts index a6cf9c1d7c..ec3199ee02 100644 --- a/packages/client/connection/src/client/fixture.ts +++ b/packages/client/connection/src/client/fixture.ts @@ -157,19 +157,19 @@ const SEARCH_MATCHES_FIXTURE: { path: string; matches: { lineNumber: number; lin ], }, { - path: 'packages/client/ui-conversation/src/client/contract/search-card-model.ts', + path: 'packages/client/ui-tool/src/client/tool/models/search-card-model.ts', matches: [ - { lineNumber: 24, line: 'export const CHAT_SEARCH_MAX_LINES = 8' }, - { lineNumber: 60, line: 'export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {' }, + { lineNumber: 45, line: 'export const CHAT_SEARCH_MAX_LINES = 8' }, + { lineNumber: 130, line: 'export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {' }, ], }, { - path: 'packages/client/ui-conversation/src/client/toolviews/search-row.tsx', + path: 'packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx', matches: [ - { lineNumber: 33, line: 'export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {' }, - { lineNumber: 35, line: ' const search = searchCardModel(block)' }, - { lineNumber: 52, line: ' search={search}' }, - { lineNumber: 78, line: " yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep', locale: NS }, SearchRow)" }, + { lineNumber: 34, line: 'export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {' }, + { lineNumber: 36, line: ' const search = searchCardModel(block)' }, + { lineNumber: 56, line: ' search={search}' }, + { lineNumber: 78, line: " yield ctx.slots.register({ name: 'tool.call.toolview', key: 'grep', locale: NS }, SearchRow)" }, ], }, ] @@ -197,9 +197,9 @@ const SEARCH_MATCHES_TEXT = [ const SEARCH_PATHS_FIXTURE = [ 'packages/client/ui-primitives/src/SearchBlock.tsx', 'packages/client/ui-primitives/src/SearchBlock.module.css', - 'packages/client/ui-conversation/src/client/contract/search-card-model.ts', - 'packages/client/ui-conversation/src/client/toolviews/search-row.tsx', - 'packages/client/ui-conversation/tests/search-card.spec.tsx', + 'packages/client/ui-tool/src/client/tool/models/search-card-model.ts', + 'packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx', + 'packages/client/ui-tool/tests/search-card.spec.tsx', ] /** diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts index ceee6a1f10..67e6c0e61c 100644 --- a/packages/client/runtime/src/client/index.ts +++ b/packages/client/runtime/src/client/index.ts @@ -85,7 +85,7 @@ declare module '@deepseek-ai/dsh-type-meta' { } } -/** The conversation-snapshot selector hook (ConvViewProps/ToolRowProps take this). */ +/** The conversation-snapshot selector hook supplied to session-scoped UI entries. */ export type UseConversationSession = SnapshotSelectorHook /** diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index db7db5db5f..126729ad9d 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md -README.md: 6b541b840ed67ee6fd735a0643dde8c60f1ec22d -README.zh.md: 01692c395cdb0f50e0fd41ab92f51d9e3ceecb4f +README.md: 3aade8409e74c38cb86a66076cca50d51a1ccbf8 +README.zh.md: 19d08bbc072f1f242417b91ae4dd771f970244b1 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 6b541b840e..fa0c4b7b9b 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, an animated left-to-right gradient `Deep diving...` turn status, per-tool row slot with a bash sample registrant and the todo row), composer dock (session stats sticky with the input), input dock (hairline-separated queue rows plus the todo plan strip), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares). +Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, and turn status), composer dock (session stats sticky with the input), input dock (queue rows plus the todo plan strip), details shell, and scope-addressed ConversationService. Tool presentation belongs to [`ui-tool`](../ui-tool/README.md). Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Every completed marker with structured summary provenance shows the replaced-item and estimated-token counts and discloses the summary on click. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when summary provenance is outside the loaded window, the checkpoint remains visible but non-expandable. @@ -16,27 +16,15 @@ Approvals take over the composer through the chain this package declares: `Appro The session header declares and renders the session-scoped `'conversation.session.header.actions'` list beside the title, allowing feature plugins to contribute controls without entering the skeleton. The composer chain currency includes the current conversation `session`; ui-subagent selects one-shot or parent-unavailable addressed sessions for reason-specific read-only copy, while the ordinary InputBar keeps every addressed child Send-only because the continuation service exposes no public per-Activation cancellation operation and `session.cancel` would bypass its ownership. -Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The header shares the Tool calls geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state, summary, or keyed toolview dispatch ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble. +Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The package-internal `DisclosureRow` gives this context surface the same compact geometry as other flow rows while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state or summary ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble. A Think row stays collapsed by default and exposes live reasoning throughput without expanding the chain of thought: while its reasoning block is the streaming tail, the summary switches from the settled first line to the latest non-blank line and its one-line scrollport follows each delta to the inline end. Expanding the row removes the moving summary and leaves the full reasoning in ordinary page flow, so page reading never fights an internal follower; settlement restores the stable first-line summary at the left edge ([decision](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)). -Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is an underlined link — it reads as one at rest, not only on hover, because a path styled like the surrounding prose is an affordance nobody finds — and it opens the file through the Host (`host.openPath`, relative paths resolve against the session cwd). A document a browser renders prefers the default browser where the Host platform can name one; Windows and WSL use the Windows registered association. The Host opens it on the Host's own machine: a client reached over a network sees nothing, which is the deliberate scope of this surface. Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering. - -A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card below its summary row; tool rows are summary surfaces, so the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which keeps the summary bounded; the panel stays the single-call reading surface. Inline output is licensed per render intent — the terminal and web cards, each with its own bound. A Bash execution failure that settles on the generic path instead exposes its original arguments and full error through the same bounded IN/OUT disclosure, while successful generic results such as a background-start acknowledgement remain summary-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)). - -A tool call declaring the `web` render intent renders its web retrieval inline, at both conversation render sites, through ui-primitives' `WebBlock`. `contract/web-card-model.ts` is the single derivation from the snapshot's `resultView`, mirroring the terminal card, so the sites cannot disagree about what a web call shows; it yields null — the generic path — for a running call, a non-web result view, a generic result view, a `card` tag this client version does not know, or a web card whose `kind` this client version does not know (a newer host's value, which the wire cannot be trusted to be `search` or `fetch`). The keyed `WebRow` registers one component under both `web_search` and `web_fetch`, discriminating on the tool name only for its icon and title; it composes the shared `ToolRow`, feeding the card as ToolRow's `web` body, so the retrieval is the row's collapsed-by-default expanded card (the same unified expand every card row has). A web-declaring tool without a keyed row lands on the `GenericToolCard` fallback, which routes the card through ToolRow the same way, and the details panel renders it and, below the card, the flattened model-visible result content — a fetch body is readable only there, since its card carries only the URL and status. Both render sites show the same complete source list — the one the tool returned and the model saw — bounded only by the card's own scroll container height, with no row-versus-panel cap ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md), [source scroll](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)). - -A `read` call declaring the `read` render intent renders the returned file window inline, at both conversation render sites, through ui-primitives' `ReadBlock` — the line-numbered, syntax-highlighted content the tool projects. `contract/read-card-model.ts` is the single derivation from the snapshot's `resultView`; the read card is result-side only (a call carries no file content until `execute` returns), so a running read shows its summary alone and it yields null — the generic path — for a non-read result view or a `card` tag this client version does not know. The keyed `ReadRow` composes the shared `ToolRow`, feeding the card as ToolRow's `read` body, so it is the row's collapsed-by-default expanded card; the summary stays a path link that opens the file through the host. The render-site fallback and the details panel are read-aware too. Rows cap at `CHAT_READ_MAX_LINES` (8) against the panel's 16 ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)). - -A tool call declaring the `diff` render intent (the `write`/`edit` tools) renders its applied change inline through ui-primitives' `DiffBlock`, the same four-layer shape. `contract/diff-card-model.ts` is the single derivation from the `callView`/`resultView` pair; the settled result's hunks replace the call-time diff, and it yields null — the generic path — for any other card tag or a generic result view (write/edit's execution errors). The keyed `FileMutationRow` (registered under both `write` and `edit`) composes the shared `ToolRow`, feeding the diff as ToolRow's `diff` body, so it is the row's collapsed-by-default expanded card; the summary path link still opens the file through the host, and an errored mutation (no diff card) surfaces its error text through ToolRow's Output section with the first line in the collapsed summary. The render-site fallback and the details panel are diff-aware too. Rows cap at `CHAT_DIFF_MAX_LINES` (8) against the panel's 16 ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)). +The chat view keeps Tool placement but delegates Tool presentation. It passes each ordered root call through `conversation.chat.tool`, and the details shell passes the selected call through `conversation.details.tool`. The assembled Web bundle fills the whole-Tool seat with [`ui-tool`](../ui-tool/README.md), which selects Runtime-projected Code Dispatch children and owns root/child composition, per-name dispatch, generic rendering, and render-intent cards; the details seat alone retains a raw-result fallback when that renderer is absent. The chat flow projects consecutive model-retry nodes across retry turns into one stable, muted status row updated to the latest attempt; every retry event remains in the runtime snapshot and session log. Its frontend countdown anchors the scheduled delay to client receipt, avoiding host/browser clock skew, rounds remaining time up to seconds, and has a one-second floor. The latest unresolved retry uses a left-to-right text shimmer. Subsequent turn facts distinguish an attempt that started from one cancelled during backoff, while the Host running bit only controls the live animation; the row then shows a static completed or cancelled label. Normal policy rows show the finite retry maximum; always policy rows show `∞`. Activating the row reveals the latest exact retry delay and failure message. The client runtime removes each failed step's streaming tail before its retry node arrives, while the status remains visible after a later attempt succeeds. An unretried terminal failure renders as a persistent inline status at its turn boundary, showing the display-safe durable message and optional error code without offering an action the Host cannot fulfill; AUTH copy never echoes provider-supplied credential fragments. -A `grep`/`glob` call declaring the `search` render intent renders its result inline, at the same render sites, through ui-primitives' `SearchBlock` — grep's matches grouped by file (each a collapsible header of `lineNumber: line` rows), glob's flat path list. `contract/search-card-model.ts` is the single derivation from the snapshot's `resultView`; unlike the terminal card it reads no `callView`, since a search has no matches or paths before `execute`, so a running search shows its summary alone. It yields null — the generic path — for any non-search result view, a `card` or `kind` this client version does not compile, and (because those ride the untrusted wire frame) a known kind whose `files`/`paths` is malformed. The keyed `SearchRow`, registered under both `grep` and `glob` since the derived `kind` decides the shape, composes the shared `ToolRow`, feeding the card as ToolRow's `search` body, so it is the row's collapsed-by-default expanded card; the render-site fallback routes it the same way. Both cap at `CHAT_SEARCH_MAX_LINES` (8) against the panel's 16. A capped search drops rows from the card, but the locator to the rest — grep/glob's `Full … stored at …` footer — lives only in the result text, so the derivation surfaces that as a recovery footer below the card when (and only when) the result was truncated; a settled call with no card at all (an errored search, a nested `run_code` sub-dispatch, a legacy generic result) surfaces its flattened result text through ToolRow's Output section so nothing is lost behind a bare summary ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md)). - -Tool rows use the keyed, session-scoped `'conversation.chat.toolview'` slot; its render site dispatches via `entryKey: toolName` with `GenericToolCard` as the call-site fallback. The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openFile`), and `ToolRowProps` composes it with the session standard kit. A registrant is a plain plugin with only the slot service edge: `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '', inject? }, Row))`. The declaration is the activation and reload dependency; `ConversationService` is required only by registrations that call its actions. Trajectory and waterfall toolview slots share this shape and use their own render sites; RendersCheck rejects a declaration nobody renders. - -The todo surfaces are two registrations over that shape, both using slot declaration injection without a `ConversationService` edge. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`/ completed · ` plus a `+` count of the other active ones, parsed from its args through `toolviews/plan-summary.ts` `planSummary`, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). When the deployment permits parallel work, several items may be `in_progress` at once, so `planSummary` names the first and counts the rest, and deliberately returns the two unjoined: the row ellipsizes its summary text, so a count concatenated onto the end of the task name would be the first thing a narrow row clips. The row hands the count to `ToolRow`'s `summarySuffix`, the shared row's non-shrinking slot beside that ellipsized text (an error row drops it, since its collapsed summary is the failure line). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: 0` — before Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus its own `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted; status glyphs are the figma check / progress / dashed-pending set), so it reports the parallel count without needing a name to truncate. The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included. +`TodoDock` takes the `'conversation.input.dock'` list slot at `order: 0` — before Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus its own `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted). The dock adapter owns selection so the panel stays a pure function of its props. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included. The `todo_write` Tool row belongs to [`ui-tool`](../ui-tool/README.md). `QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `" 条排队消息"` header whose button expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Each visible ordinary-session row remains a single-line preview with its exact-occurrence edit, delete, and strict-steer actions; addressed subagents retain the rows as a read-only projection because their continuation transport does not expose queue mutation. If strict steer loses to a closed window, the original occurrence remains queued for normal delivery; if the driver already claimed it, normal delivery is already underway. Neither converged race displays a failure, while transport and unknown failures do. @@ -50,7 +38,7 @@ The composer bar declares session-scoped single seats for `'conversation.input.p The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy moved off the row onto the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation. -`src/client/` is organized by domain. `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations and composed props, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` directories import contract files and never each other. `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components and the store factory stay internal and reach the page through apply's slot registrations. +`src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` export surface contains only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations. A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 01692c395c..6dc803ee72 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、带从左到右动态渐变的 `Deep diving...` 轮次状态、逐工具行 slot 及一个 bash 示例注册方与 todo 行）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（带发丝分界线的队列行加 todo 计划条）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。 +会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离与轮次状态）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（队列行加 todo 计划条）、详情壳层，以及按 scope 寻址的 ConversationService。Tool 展示属于 [`ui-tool`](../ui-tool/README.md)。 压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个具备结构化摘要溯源的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。 @@ -14,29 +14,17 @@ 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。 -已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。标题栏通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态、摘要或键控 toolview 分发（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。 +已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。包内部的 `DisclosureRow` 让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。 -通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是带下划线的链接——静止状态下就读得出是链接，而不只在悬停时，因为一条与周围正文同样样式的路径是没人会发现的交互——点击即经由 Host 打开文件（`host.openPath`，相对路径相对会话 cwd 解析）。浏览器能渲染的文档会在 Host 平台能够确定默认浏览器时优先使用它；Windows 与 WSL 则使用 Windows 注册的文件关联。Host 在它自己的机器上打开：经网络访问的客户端看不到任何东西，这是本交互面刻意划定的范围。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。 - -声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片放在摘要行下方；工具行是摘要 surface，因此卡片的复制与展开控件是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，因此摘要保持有界；面板仍是单次调用的阅读 surface。内联输出按渲染意图开放——终端卡片与 web 卡片各有自己的上限。若 Bash 执行失败时落在通用路径，则改用同样有界的 IN/OUT 展开区暴露原始参数和完整错误；后台启动确认等成功的通用结果仍只显示摘要（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。 - -声明 `web` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `WebBlock` 内联渲染其 web 检索。`contract/web-card-model.ts` 是从快照的 `resultView` 推导的唯一位置，镜像终端卡片，因此两个渲染点不可能对一次 web 调用的显示产生分歧；对运行中的调用、非 web 的 result view、generic result view、本客户端版本不认识的 `card` 标签，或本客户端版本不认识 `kind` 的 web 卡片（更新的 host 发来的值，wire 上不可信其为 `search` 或 `fetch`），它返回 null，落回通用路径。键控的 `WebRow` 把一个组件注册在 `web_search` 与 `web_fetch` 两个键下，仅根据工具名判别以选取图标与标题；它组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `web` body 传入，因此检索成为该行默认折叠的展开卡片（与每个卡片行相同的统一展开交互）。没有自己键控行的 web 声明工具落到 `GenericToolCard` 兜底，它以同样方式经 ToolRow 渲染卡片，详情面板渲染它，并在卡片下方渲染摊平的模型可见结果内容——fetch 正文只在此处可读，因为其卡片只携带 URL 和状态。两个渲染点显示同一份完整来源列表——工具返回、模型看到的那一份——仅受卡片自身滚动容器的高度约束，不存在行与面板的两级上限（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)、[来源滚动](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)）。 - -声明 `read` 渲染意图的 `read` 调用，会在两个对话渲染点上都通过 ui-primitives 的 `ReadBlock` 内联渲染返回的文件窗口——工具投影出的带行号、语法高亮的内容。`contract/read-card-model.ts` 是从快照的 `resultView` 推导的唯一位置；read 卡片是仅结果侧的(调用在 `execute` 返回前不携带文件内容)，所以运行中的 read 只显示摘要，且对非 read 的 result view 或本客户端版本不认识的 `card` 标签返回 null，落回通用路径。键控的 `ReadRow` 组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `read` body 传入，因此它是该行默认折叠的展开卡片；摘要仍是一个经 host 打开文件的路径链接。渲染点兜底行与详情面板同样感知 read。行的上限是 `CHAT_READ_MAX_LINES`（8），面板为 16（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)）。 - -声明 `diff` 渲染意图的工具调用（`write`／`edit` 工具），通过 ui-primitives 的 `DiffBlock` 内联渲染其已应用的改动，采用同一套四层结构。`contract/diff-card-model.ts` 是从 `callView`／`resultView` 对推导的唯一位置；已结算 result 的 hunk 替换 call 时 diff，对任何其他 card 标签或 generic result view（write/edit 的执行错误）它返回 null，落回通用路径。键控的 `FileMutationRow`（在 `write` 与 `edit` 下都注册）组合共享的 `ToolRow`，把 diff 作为 ToolRow 的 `diff` body 传入，因此它是该行默认折叠的展开卡片；摘要路径链接仍经 host 打开文件，而出错的改动（没有 diff 卡片）经 ToolRow 的 Output 区呈现其错误文本，首行进入折叠摘要。渲染点兜底行与详情面板同样感知 diff。行的上限是 `CHAT_DIFF_MAX_LINES`（8），面板为 16（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)）。 +聊天视图保留 Tool 的消息流位置，但委托其展示。它通过 `conversation.chat.tool` 传递每个已排序的 root call；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 由 [`ui-tool`](../ui-tool/README.md) 填充整体 Tool 席位，并由后者选择 Runtime 已投影的 Code Dispatch 子调用，负责 root/child 编排、按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。 聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。未进入重试的终态失败会在其轮次边界渲染为持久的内联状态，展示适合显示的持久消息与可选错误码，但不会提供 Host 无法兑现的操作；AUTH 文案绝不会回显提供方给出的凭据片段。 -声明 `search` 渲染意图的 `grep`／`glob` 调用，会在同样的渲染点上通过 ui-primitives 的 `SearchBlock` 内联渲染其结果——grep 的匹配按文件分组（每个是一个可折叠的头，下辖 `lineNumber: line` 行），glob 是扁平路径列表。`contract/search-card-model.ts` 是从快照的 `resultView` 推导的唯一位置；与终端卡片不同，它不读 `callView`，因为搜索在 `execute` 前没有匹配或路径，所以运行中的搜索只显示摘要。对任何非搜索的结果视图、当前客户端版本无法编译的 `card` 或 `kind`、以及（因为这些都与不可信的 wire 帧同行）一个 `files`／`paths` 格式错误的已知 kind，它都返回 null，落回通用路径。键控的 `SearchRow` 因推导出的 `kind` 决定形态而同时注册在 `grep` 与 `glob` 下，组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `search` body 传入，因此它是该行默认折叠的展开卡片；渲染点兜底行以同样方式渲染它。两者上限都是 `CHAT_SEARCH_MAX_LINES`（8），面板为 16。被截断的搜索会从卡片里丢掉一些行，但通往其余部分的定位符——grep/glob 的 `Full … stored at …` 脚注——只存在于结果文本里，因此推导在（且仅在）结果被截断时把它作为恢复脚注画在卡片下方；一个完全没有卡片的已结算调用（出错的搜索、嵌套 `run_code` 子派发、旧日志的 generic 结果）则经 ToolRow 的 Output 区呈现其压平后的结果文本，从而不让任何内容丢失在一个光秃秃的摘要之后（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md)）。 - -工具行使用键控、Session scope 的 `'conversation.chat.toolview'` slot；其渲染点通过 `entryKey: toolName` 分发，并以 `GenericToolCard` 作为调用点 fallback。owner 载荷是统一的 `ToolRowOwnerProps`（`callId`／`toolName`／`block`／`openFile`），`ToolRowProps` 将其与 Session 标准工具包组合。注册方是只依赖 slot 服务的普通插件：`ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '', inject? }, Row))`。声明本身就是激活与重载依赖；只有调用 `ConversationService` 操作的注册项才需要该服务。Trajectory 与 waterfall（瀑布式事件）工具视图 slot 共享此形状并使用各自的渲染点；RendersCheck 会拒绝没有任何渲染方的声明。 - 审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。运行时 manager 会将所有审批或问题等待通过 `SessionSummary.pendingInteraction` 投影出来，未实例化的 Session 也不例外；`ui-workspace` 负责其侧边栏呈现。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，其中 kebab-case 预设名渲染为 Title Case 标签；普通安全预设会立即经输入栏注入的 `command` 回调提交 `/permission `，而 `danger-full-access` 在界面中显示为 `Full access`，选择后先打开页面内的 Modal 风险确认。用户勾选确认项前启用按钮始终不可用；取消、Escape、关闭按钮与点击遮罩都不会提交命令。 -todo 两个面就是在该形状上的两个注册项，都使用 slot 声明注入，不依赖 `ConversationService`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 经 `toolviews/plan-summary.ts` 的 `planSummary` 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`，以及「其余活跃项的数量」`+`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。部署允许并行工作时，可以有多个条目同时处于 `in_progress`，因此 `planSummary` 给出第一个活跃条目并计数其余，且刻意不把两者拼成一个字符串：行会对摘要文本做省略号截断，把数量接在任务名末尾时，窄行最先裁掉的正是这个数量。该行把数量交给 `ToolRow` 的 `summarySuffix`——共享行在被截断文本旁的不收缩位（出错的行会丢弃它，因为其折叠摘要是失败首行）。`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加它自行计算的、以 `·` 连接的各状态计数（本地化，形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略；状态图标为 figma 的勾选／进行中／虚线未开始一组），因此它无需一个可被截断的任务名即可报告并行数量。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。 +`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），作为计划条读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`。面板接收纯列表，列表为空时自我隐藏；列表非空时默认折叠，表头显示标题及以 `·` 连接的各状态计数（如 `1 已完成 · 2 进行中 · 1 待处理`，省略零计数）。dock adapter 拥有 selection，因此面板保持为 props 的纯函数。输入区 composer 链隐藏的一切也会隐藏整个 dock。`todo_write` Tool 行属于 [`ui-tool`](../ui-tool/README.md)。 `QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `" 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。普通会话中的每条可见行仍是单行预览，并提供针对精确单次入队项的编辑、删除和严格 steering 操作；已寻址 subagent 则保留只读行，因为其继续执行传输不提供 Queue 变更。如果严格 steering 输给已关闭的窗口，原单次入队项会留在 Queue 中正常投递；如果驱动器已经认领该项，正常投递就已开始。这两种已收敛的竞态都不显示失败，传输和未知错误仍会显示。 @@ -50,7 +38,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu 聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。同一次窗口折算还会把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率从统计行移到了 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。 -`src/client/` 按领域组织。`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明与组合后的 props、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/` 目录只导入 contract 文件，彼此之间从不互相导入。`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件与 store factory 保持内部，经 apply 的 slot 注册抵达页面。 +`src/client/` 按领域组织。`contract/` 是 slot 声明、组合 props 与跨领域类型的共享表层；`skeleton/`、`chat/`、`input/`、`queue/` 和 `settings/` 保持内部实现，`apply.ts` 是它们的组装点。`/client` 导出表层只包含 loader entry、service class 和 contract 类型；组件与 store factory 经 slot 注册抵达页面。 完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。 diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json index ff4e74da5e..2ff87cc0e2 100644 --- a/packages/client/ui-conversation/package.json +++ b/packages/client/ui-conversation/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-client-ui-conversation", - "description": "Conversation domain: skeleton (header/tabs/composer), chat view, ctx.toolviews registry, minimal details panel", + "description": "Conversation domain: skeleton, ordered chat flow, composer, and details host", "version": "0.0.1", "private": true, "type": "module", diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts index b6a3fc791c..74533b5e2d 100644 --- a/packages/client/ui-conversation/src/client/apply.ts +++ b/packages/client/ui-conversation/src/client/apply.ts @@ -11,7 +11,7 @@ import type { ConversationSessionHeaderInjected, ConversationSessionInjected, DetailsInjected, } from './contract/slots.ts' import type { InputNotice } from './input/contract.ts' -import { resolveToolPath } from './contract/tool-call-model.ts' +import { resolveToolPath } from './contract/tool-path.ts' import { createChatStore } from './stores.ts' import { ConversationService } from './service.ts' import type { IConversation } from './service.ts' @@ -24,14 +24,7 @@ import { EnterBehaviorRow } from './settings/EnterBehaviorRow.tsx' import type { EnterBehaviorRowInjected } from './settings/EnterBehaviorRow.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 { fileMutationToolview } from './toolviews/file-mutation-row.tsx' -import { searchToolview } from './toolviews/search-row.tsx' -import { webToolview } from './toolviews/web-row.tsx' import { ApprovalPanel } from './skeleton/ApprovalPanel.tsx' -import { todoToolview } from './toolviews/todo-row.tsx' -import { askQuestionToolview } from './toolviews/ask-question-row.tsx' import { todoDockEntry } from './skeleton/TodoPanel.tsx' import { queueDockEntry } from './queue/QueueDock.tsx' import { ConversationRoot } from './skeleton/ConversationRoot.tsx' @@ -41,7 +34,7 @@ import { en, NS, zh, type ConversationKey } from './locales.ts' declare module '@deepseek-ai/dsh-client-ui-slots' { interface LocaleNamespaceMap { - /** The conversation surfaces' copy (skeleton, chat view, toolviews, docks). */ + /** The conversation skeleton, chat flow, commands, details, and docks copy. */ conversation: ConversationKey } } @@ -304,10 +297,8 @@ export function apply(ctx: Context): void { slots.register({ name: 'conversation.composer', select: selectApproval, priority: 1, locale: NS }, ApprovalPanel) // The chat view: first entry of the ring this package just declared. - // Declaring the keyed toolview hole here is claiming it: ChatView is the - // only component authorized to render per-tool rows. Shares the chat - // store, so its selection writes land in the same per-session instance the - // details panel reads. + // ChatView owns ordered Tool placement but delegates each whole root call + // to ui-tool, which owns root/subcall composition and atomic dispatch. slots.register({ name: 'conversation.view', id: 'chat', @@ -315,7 +306,7 @@ export function apply(ctx: Context): void { label: () => t('view.chat'), locale: NS, children: { - 'conversation.chat.toolview': { kind: 'keyed', scope: 'session' }, + 'conversation.chat.tool': { kind: 'single', scope: 'session' }, 'conversation.chat.commandview': { kind: 'keyed', scope: 'session' }, 'conversation.chat.turnTail': { kind: 'chain', scope: 'session' }, }, @@ -368,34 +359,6 @@ export function apply(ctx: Context): void { // this service remains only where conversation actions are required. ctx.plugin(ConversationService, { input: inputHub, blocks: composerBlocks }) - // The bash sample rides the same declaration seam, in third-party posture - // (ToolRow-matching Bash · {description} chrome). - 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 write/edit rows ride the same seam: a file-mutation call declares the - // diff render intent, so these rows stack the applied diff card under their - // path-link summary (the terminal card's posture, applied to diffs). - ctx.plugin(fileMutationToolview) - - // The grep/glob search row rides the same seam: one component registered - // under both tool names, since both declare the same search render intent. - ctx.plugin(searchToolview) - - // The web rows ride the same seam: one WebRow registered under both - // web_search and web_fetch, rendering the completed retrieval's web card - // resident under the summary (a product registration, not a sample). - ctx.plugin(webToolview) - - // The todo_write row rides the same seam (a product registration, not a sample). - ctx.plugin(todoToolview) - - // The ask_user_question row: waiting/answered/cancelled interaction outcome. - ctx.plugin(askQuestionToolview) - // The plan strip rides the input dock above the queue rows (same posture). ctx.plugin(todoDockEntry) @@ -406,6 +369,9 @@ export function apply(ctx: Context): void { slots.register({ name: 'details', locale: NS, + children: { + 'conversation.details.tool': { kind: 'single', scope: 'session' }, + }, store: chatStore, inject: (): DetailsInjected => ({ closeDetails: () => { layout.closeDetails() }, diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.module.css b/packages/client/ui-conversation/src/client/chat/ChatView.module.css index 1b5b58ce47..c600b3b0aa 100644 --- a/packages/client/ui-conversation/src/client/chat/ChatView.module.css +++ b/packages/client/ui-conversation/src/client/chat/ChatView.module.css @@ -64,17 +64,6 @@ /* Selection still sets data-selected for details linkage; no outline — tool rows match Think chrome (no selected ring). */ -/* run_code sub-dispatch rows: indented under the parent row, left-edged so - the code turn reads as one unit; each nested row is itself a .callRow. */ -.subCalls { - display: flex; - flex-direction: column; - gap: 4px; - margin: 4px 0 2px 22px; - padding-left: 8px; - border-left: 1px solid var(--dsw-alias-border-l2); -} - /* Turn activity keeps the former loader's one-line footprint. A pale brand-blue band sweeps from left to right; reduced-motion keeps it static. */ .turnStatus { diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx index 18fba234de..c52a4623be 100644 --- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx +++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx @@ -2,10 +2,9 @@ // assistant narration, tool summary rows grouped into step runs, pending // cards, paging, and bottom-follow. Session stats live on // 'conversation.composer.dock' (sticky with the composer). Pure component -// registered directly; its registration declares the keyed -// 'conversation.chat.toolview' hole, so tool rows render through the props -// renderSlot share (entryKey = tool name, GenericToolCard as the render-site -// fallback). +// registered directly; its registration declares the whole-Tool +// 'conversation.chat.tool' seat. ui-tool owns root/subcall composition and +// keyed per-tool dispatch behind that boundary. // // Scroll: when nested under `[data-conversation-scroll]` (active conversation // column), that host is the scrollport and this view is flow content; when @@ -25,7 +24,7 @@ import { memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode, } from 'react' import type { - CodeSubCall, CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode, + CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode, } from '@deepseek-ai/dsh-client-runtime/client' import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots' import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives' @@ -34,7 +33,6 @@ import { assistantActionsSeqs, assistantBranchSeqs, deriveChatFlow, runningTurnS import { AssistantMarkdown } from './AssistantMarkdown.tsx' import { CompactionCommandCard } from './CompactionCommandCard.tsx' import { GenericCommandCard } from './GenericCommandCard.tsx' -import { GenericToolCard } from './GenericToolCard.tsx' import { MessageItem, PendingSteeringBubble } from './MessageItem.tsx' import { formatRunDuration } from './message-chrome.ts' import { deriveTurnMetrics } from './turn-metrics.ts' @@ -104,8 +102,8 @@ type OpenFile = (path: string) => void type InspectCall = (callId: string) => void -/** The declared toolview hole's render share (stable framework binding, passed through memoized rows). */ -type RenderToolRow = ChatViewSlotProps['renderSlot'] +/** Declared child-slot render share (stable framework binding). */ +type RenderChatSlot = ChatViewSlotProps['renderSlot'] type ChatScrollPosition = NonNullable> @@ -136,129 +134,49 @@ function scrollPosition(list: HTMLElement, scrollport: HTMLElement): ChatScrollP } } -/** One `run_code` sub-dispatch row: the identical keyed-slot dispatch as a - * top-level call (same registrations, same fallback), nested by the parent. - * A started-but-unsettled sub-call arrives as the RunningToolCall shape and - * renders the running state exactly as a native in-flight row. */ -const SubCallRow = memo(function SubCallRow({ renderSlot, node, openFile, selected, cwd, inspectCall, t }: { - renderSlot: RenderToolRow - node: CodeSubCall - openFile: OpenFile - selected: boolean - cwd: string | undefined - inspectCall: InspectCall - t: ChatViewSlotProps['t'] -}) { - const settled = 'kind' in node - const toolName = settled ? node.call?.name ?? '' : node.name - const owner = useMemo(() => ({ - callId: node.callId, toolName, block: node, openFile, cwd, - inspect: () => { inspectCall(node.callId) }, - }), [node, toolName, openFile, cwd, inspectCall]) - return ( -
- {renderSlot('conversation.chat.toolview', owner, { - entryKey: toolName, - fallback: , - })} -
- ) -}) - -/** One tool call row (result or running): dispatches through the keyed - * toolview slot with the owner payload; unregistered tools fall back to - * GenericToolCard at this render site. A `run_code` call additionally - * renders its logged sub-dispatches as always-visible indented rows — - * each one the same keyed-slot dispatch as a native top-level call. */ -const CallRow = memo(function CallRow({ - renderSlot, callId, toolName, block, openFile, selected, subCalls, selectedCallId, cwd, inspectCall, t, +/** One ordered root Tool call handed intact to the Tool presentation plugin. */ +const ToolSeat = memo(function ToolSeat({ + renderSlot, callId, toolName, block, openFile, selectedCallId, cwd, inspectCall, }: { - renderSlot: RenderToolRow + renderSlot: RenderChatSlot callId: string toolName: string block: ToolResultNode | RunningToolCall openFile: OpenFile - selected: boolean - /** `run_code` sub-dispatches in dispatch order (reference-stable per - * parent; running entries settle in place); undefined for ordinary calls. */ - subCalls?: readonly CodeSubCall[] | undefined - /** The store's selected callId, matched against sub-rows (undefined when no sub-row here is selected). */ selectedCallId?: string | undefined - /** Session workspace root for path-relative summaries. */ cwd: string | undefined inspectCall: InspectCall - t: ChatViewSlotProps['t'] }) { const owner = useMemo(() => ({ - callId, toolName, block, openFile, cwd, - inspect: () => { inspectCall(callId) }, - }), [callId, toolName, block, openFile, cwd, inspectCall]) - return ( -
- {renderSlot('conversation.chat.toolview', owner, { - entryKey: toolName, - fallback: , - })} - {subCalls !== undefined && subCalls.length > 0 && ( -
- {subCalls.map(node => ( - - ))} -
- )} -
- ) + callId, toolName, block, selectedCallId, cwd, openFile, inspectCall, + }), [callId, toolName, block, selectedCallId, cwd, openFile, inspectCall]) + return renderSlot('conversation.chat.tool', owner) }) /** Consecutive tool results as one step-run group (uniform 16px rhythm). */ -const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selectedCallId, codeDispatches, cwd, inspectCall, t }: { - renderSlot: RenderToolRow +const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selectedCallId, cwd, inspectCall }: { + renderSlot: RenderChatSlot results: readonly ToolResultNode[] openFile: OpenFile - /** Only set when the selected call lives in THIS group, top-level or nested (memo economy). */ + /** Tool ownership resolves whether the selection is this root or one of its children. */ selectedCallId: string | undefined - /** Sub-dispatch index off the snapshot (map reference is chunk-storm stable). */ - codeDispatches: ReadonlyMap /** Session workspace root for path-relative summaries. */ cwd: string | undefined inspectCall: InspectCall - t: ChatViewSlotProps['t'] }) { return (
{results.map(node => ( - ))}
@@ -269,7 +187,7 @@ const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selec * generic card as the render-site fallback (zero registration required). A * run-less cross-window node has no name and always lands on the fallback. */ const CommandRow = memo(function CommandRow({ renderSlot, node, compaction, t }: { - renderSlot: RenderToolRow + renderSlot: RenderChatSlot node: CommandNode compaction?: Extract t: ChatViewSlotProps['t'] @@ -336,8 +254,8 @@ function StreamingTail({ useSession, t }: { } /** - * The chat view slot entry: pure component over the composed props (tool rows - * render through the declared keyed hole's renderSlot share). + * The chat view slot entry: pure component over the composed props; each + * ordered root Tool call crosses the declared whole-Tool render seat. */ export function ChatView({ useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt, t, @@ -350,7 +268,6 @@ export function ChatView({ const cwd = useSessions(s => s.byId[sessionId]?.cwd) const running = useSession(s => s.running) const runningCalls = useSession(s => s.runningCalls) - const codeDispatches = useSession(s => s.codeDispatches) const openState = useSession(s => s.openState) const openError = useSession(s => s.openError) const hasMore = useSession(s => s.hasMore) @@ -569,19 +486,14 @@ export function ChatView({ const renderItem = (item: ChatFlowItem): ReactNode => { if (item.kind === 'tool-group') { - const inGroup = selectedCallId !== undefined - && item.results.some(r => r.callId === selectedCallId - || codeDispatches.get(r.callId)?.some(sub => sub.callId === selectedCallId) === true) return ( ) } @@ -676,19 +588,16 @@ export function ChatView({ {runningCalls.length > 0 && (
{runningCalls.map(call => ( - ))}
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts index be57f08523..2ef67f4aa8 100644 --- a/packages/client/ui-conversation/src/client/contract/slots.ts +++ b/packages/client/ui-conversation/src/client/contract/slots.ts @@ -31,13 +31,10 @@ declare module '@deepseek-ai/dsh-client-ui-slots' { */ 'conversation.view': { kind: 'list'; scope: 'session'; owner: ConvViewOwnerProps } /** - * The chat view's per-tool row hole: keyed dispatch on the wire tool name - * (the key space is runtime-open — SlotMap declares slots, never keys). - * Declared by the chat view entry (declaring is claiming); the render - * site dispatches via `entryKey: toolName` with GenericToolCard as the - * `fallback` for unregistered tools. + * One root Tool call at its ordered ChatFlow position. The chat view owns + * placement; ui-tool owns root/subcall composition and keyed dispatch. */ - 'conversation.chat.toolview': { kind: 'keyed'; scope: 'session'; owner: ToolRowOwnerProps } + 'conversation.chat.tool': { kind: 'single'; scope: 'session'; owner: ToolTreeOwnerProps } /** * The chat view's per-command row hole: keyed dispatch on the command * name (`command/run.name`; a run-less cross-window node has none and @@ -55,6 +52,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' { * to return null; an all-declined chain renders nothing. */ 'conversation.chat.turnTail': { kind: 'chain'; scope: 'session'; owner: TurnTailOwnerProps } + /** Selected Tool call output inside the details panel. */ + 'conversation.details.tool': { kind: 'single'; scope: 'session'; owner: DetailsToolOwnerProps } /** * The composer takeover chain: entries are selector-routed replacements * of the default InputBar. Declared by this package's 'conversation' @@ -177,42 +176,36 @@ export interface TurnTailOwnerProps { openFile: (path: string) => void } -/** - * Owner share of a per-view toolview slot: the call material the rendering - * view supplies per row. Uniform across views — the trajectory/waterfall - * toolview slots (same kind/scope/owner, names fixed by the slot-naming - * discipline) land with their own row render sites; today only the chat slot - * is declared (RendersCheck rejects a declaration nobody renders). - */ -export interface ToolRowOwnerProps { - /** Tool call identity (details linkage; stable across running → settled). */ +/** Owner currency of the chat view's whole-Tool rendering seat. */ +export interface ToolTreeOwnerProps { + /** Root Tool call identity, stable across running → settled. */ callId: CallId - /** Wire tool name (also the keyed dispatch key at the render site). */ + /** Root wire Tool name. */ toolName: string - /** Frozen call slice: the running call or the settled result node. */ + /** Frozen root call slice: running call or settled result node. */ block: ToolCallBlock + /** Selected call id; the Tool owner resolves whether it is root or child. */ + selectedCallId?: CallId | undefined /** Session workspace root; path summaries display relative to it. */ cwd?: string | undefined /** * Open a tool-arg filesystem path with the host OS default application. - * The chat view resolves relative paths against the session cwd. + * The conversation owner resolves relative paths against the session cwd. */ openFile: (path: string) => void /** - * Jump to this call's record in the trajectory view (the expanded row's - * hover Inspect affordance). Undefined when no trajectory jump is wired. + * Jump to any call in this tree in the trajectory view. */ - inspect?: (() => void) | undefined + inspectCall: (callId: CallId) => void } -/** - * Full props of a registered tool-row component: the slot's runtime share - * (owner payload + session standard kit + global seat). Registrants type - * their component `FC` with `I` inferred from their inject - * factory. Declared against the chat slot; the three per-view toolview slots - * share one declaration shape, so this alias serves them all. - */ -export type ToolRowProps = PropsRuntime<'conversation.chat.toolview'> +/** Owner currency of the details panel's Tool output renderer. */ +export interface DetailsToolOwnerProps { + /** Frozen selected call slice. */ + block: ToolCallBlock + /** Session workspace root for card cwd and relative-path display. */ + cwd?: string | undefined +} /** * Owner share of the per-command row slot: the frozen {@link CommandNode} @@ -229,7 +222,7 @@ export interface CommandRowOwnerProps { compaction?: CompactionSummaryNode } -/** Full props of a registered command-row component (same shape rule as {@link ToolRowProps}). */ +/** Full props of a registered command-row component. */ export type CommandRowProps = PropsRuntime<'conversation.chat.commandview'> /** @@ -521,9 +514,9 @@ export interface ChatViewInjected { forkAt: (seq: number) => void } -/** Full chat-view component props: runtime & the declared toolview/commandview holes' render share & store & injected & locale seat. */ +/** Full chat-view component props: runtime & its Tool/command/tail render shares & store & injected & locale seat. */ export type ChatViewSlotProps = - PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.toolview' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'> + PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.tool' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'> & PropsStore & ChatViewInjected & PropsLocale<'conversation'> /** @@ -535,8 +528,9 @@ export interface DetailsInjected { closeDetails: () => void } -/** Full details-slot component props: selection rides the shared store, call material useSession; copy the locale seat. */ -export type DetailsSlotProps = PropsRuntime<'details'> & PropsStore & DetailsInjected & PropsLocale<'conversation'> +/** Full details-slot props: selection store, Tool output seat, injected close callback, and locale. */ +export type DetailsSlotProps = PropsRuntime<'details'> & PropsRenderSlots<'conversation.details.tool'> + & PropsStore & DetailsInjected & PropsLocale<'conversation'> /** Owner share common to the hero / New-Session Workspace pickers. */ export interface EmptyWorkspaceOwnerProps { diff --git a/packages/client/ui-conversation/src/client/contract/tool-path.ts b/packages/client/ui-conversation/src/client/contract/tool-path.ts new file mode 100644 index 0000000000..38a55937d3 --- /dev/null +++ b/packages/client/ui-conversation/src/client/contract/tool-path.ts @@ -0,0 +1,15 @@ +/** Resolve a Tool argument path against the session workspace. */ + +/** + * Resolve a Tool argument path for the Host opener. + * @param cwd - session workspace root, when known. + * @param path - path carried by the Tool arguments. + * @returns an absolute-or-workspace-relative Host path. + */ +export function resolveToolPath(cwd: string | undefined, path: string): string { + if (path.startsWith('/') || /^[A-Za-z]:[/\\]/.test(path) || path.startsWith('\\\\')) return path + if (cwd === undefined || cwd === '') return path + const base = cwd.replace(/[/\\]+$/, '') + const rel = path.replace(/^[/\\]+/, '') + return `${base}/${rel}` +} diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts index 725868d57a..b91628b825 100644 --- a/packages/client/ui-conversation/src/client/index.ts +++ b/packages/client/ui-conversation/src/client/index.ts @@ -10,14 +10,13 @@ export type { IConversation } from './service.ts' export type { CallId, ChatStoreState, SelectionTarget, ViewTab, } from './contract/views.ts' -export type { ToolCallBlock } from './contract/tool-call-model.ts' export type { ConversationKey } from './locales.ts' export type { ChatStore, ChatViewInjected, ChatViewSlotProps, CommandRowOwnerProps, CommandRowProps, ComposerBarInjected, ComposerChainProps, ConversationInjected, - ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps, - ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps, - EmptyWorkspaceOwnerProps, ToolRowOwnerProps, ToolRowProps, TurnTailOwnerProps, + ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps, ConvViewOwnerProps, + ConvViewProps, DetailsInjected, DetailsSlotProps, DetailsToolOwnerProps, EmptyWorkspaceOwnerProps, + ToolTreeOwnerProps, TurnTailOwnerProps, } from './contract/slots.ts' // Export discipline: packages/client/AGENTS.md. 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 fbaebd1193..abdece3e25 100644 --- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css +++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css @@ -92,36 +92,3 @@ .code[data-error] { color: var(--dsw-alias-state-error-primary); } - -/* Above the card, which is where the render-intent contract puts a terminal - call's description; the panel has no summary row to carry it. */ -.terminalDescription { - margin: 0 0 6px; - color: var(--dsw-alias-label-secondary); - font: var(--dsw-font-xs-13); -} - -/* A card body (terminal, diff, or search) sits directly under its section - label, so it drops the primitive's standalone vertical margin; the section - owns the spacing. Card-neutral: no card-kind-specific value. */ -.cardBody { - margin: 0; -} - -/* The recovery footer for a capped search: the result text (its `Full … stored - at …` locator) below the card in the muted tone, since the card holds only the - retained rows. */ -.searchRecovery { - margin: 6px 0 0; - white-space: pre-wrap; - overflow-wrap: anywhere; - color: var(--dsw-alias-label-tertiary); - font: var(--dsw-font-xs-13); -} - -/* The read and web cards sit directly under their section label, same as the - terminal card: drop the primitive's standalone vertical margin. */ -.read, -.web { - 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 1114236143..c2104c23c7 100644 --- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx +++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx @@ -7,16 +7,11 @@ // share the store seat exists for) and derives the call material from the // session snapshot — no data of its own. -import { CodeBlock, DiffBlock, ReadBlock, SearchBlock, TerminalBlock, WebBlock } from '@deepseek-ai/dsh-client-ui-primitives' +import { Fragment } from 'react' +import { CodeBlock } 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 { ConversationSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client' import type { DetailsSlotProps } from '../contract/slots.ts' -import { readCardModel } from '../contract/read-card-model.ts' -import { diffCardModel } from '../contract/diff-card-model.ts' -import { searchCardModel } from '../contract/search-card-model.ts' -import { terminalBlockLabels, terminalCardModel } from '../contract/terminal-card-model.ts' -import { webCardModel } from '../contract/web-card-model.ts' -import { resultText, type ToolCallBlock } from '../contract/tool-call-model.ts' import css from './DetailsPanel.module.css' /** Full props composed by reference from the contract (automatic shares & injected share). */ @@ -72,7 +67,15 @@ function pretty(raw: string): string { } } -export function DetailsPanel({ useSession, useSessions, sessionId, useStore, closeDetails, t }: DetailsPanelProps) { +/** Flatten a settled result for the no-ui-tool fallback. */ +function rawResultText(block: ToolCallBlock): string { + if (!('kind' in block)) return '' + const parts = block.content.map(item => item.type === 'text' ? item.text : JSON.stringify(item, null, 2)) + if (parts.length === 0 && block.error !== undefined) parts.push(`${block.error.name}: ${block.error.code}`) + return parts.join('\n') +} + +export function DetailsPanel({ useSession, useSessions, sessionId, useStore, renderSlot, closeDetails, t }: DetailsPanelProps) { const selection = useStore(s => s.selection) // Session workspace root: an omitted or relative terminal cwd resolves // against it, which the pure presenter cannot see. @@ -118,7 +121,17 @@ export function DetailsPanel({ useSession, useSessions, sessionId, useStore, clo state (the terminal card's expand and copy), which React would otherwise carry into the next selection because the panel does not unmount between calls. */} - + + {renderSlot('conversation.details.tool', { block: material.block, cwd: sessionCwd }, { + fallback: 'kind' in material.block + ? ( + 
+                            {rawResultText(material.block)}
+
+ ) + :
{t('details.running')}
, + })} + )} @@ -126,83 +139,3 @@ 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. A read-card call - * renders through the shared ReadBlock at that same full height, so the whole - * returned window is line-numbered and highlighted. A diff-card call — a - * write/edit's applied change — renders through the shared DiffBlock at the same - * full height. A search-card call — a `grep`/`glob` result view — renders - * through the shared SearchBlock at the same full height allowance, with a - * capped search's recovery footer below it. A web-card call — a - * `web_search`/`web_fetch` result — renders through WebBlock at its own full - * source-list allowance. 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. - * @param props.t - the panel's locale seat, passed down as a plain prop. - * @returns the Output section's body element. - */ -function OutputBody({ material, cwd, t }: { material: CallMaterial; cwd: string | undefined; t: DetailsPanelProps['t'] }) { - const terminal = terminalCardModel(material.block, cwd) - if (terminal !== null) { - // The contract renders the presenter's description above the card, and the - // panel has no summary row to carry it, so it is drawn here. - return ( - <> - {terminal.description !== undefined && ( -
{terminal.description}
- )} - - - ) - } - 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 - const diff = diffCardModel(material.block) - if (diff !== null) return - const search = searchCardModel(material.block) - if (search !== null) { - return ( - <> - - {/* A capped search's recovery locator lives only in the result text; - show it below the card so the dropped rows stay reachable. */} - {search.recovery !== undefined && ( -
{search.recovery}
- )} - - ) - } - const web = webCardModel(material.block) - // The card shows every source the tool returned (the same list the model saw), - // scrolling within its own capped height. Below the card the panel also renders - // the flattened result content — the model-visible text the card does not carry - // verbatim (a web_fetch card shows only the URL and status, so its fetched body - // lives only here; a search card's answer and sources are structured, so the - // flattened form repeats them as the raw text the model saw). - if (web !== null) { - const settled = 'kind' in material.block ? material.block : null - const body = settled === null ? '' : resultText(settled) - return ( - <> - - {body !== '' && 
{body}
} - - ) - } - // 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
{t('details.running')}
- const result = material.block - return ( - 
-      {resultText(result)}
-
- ) -} diff --git a/packages/client/ui-conversation/src/invariant.ts b/packages/client/ui-conversation/src/invariant.ts index f4ecd7e260..f9a7d46553 100644 --- a/packages/client/ui-conversation/src/invariant.ts +++ b/packages/client/ui-conversation/src/invariant.ts @@ -17,7 +17,7 @@ export const inject = ['invariants'] /** * No runtime invariant: the conversation service emits no cordis events, and * both rings this package owns (the 'conversation.view' tab ring and the - * 'conversation.chat.toolview' row hole) ride the slot system, whose ledger + * 'conversation.chat.tool' whole-call seat) ride the slot system, whose ledger * invariants live with the runtime slots package. */ const install: InvariantInstaller = () => {} diff --git a/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx b/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx index 16163065eb..9ea1c937ff 100644 --- a/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx +++ b/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx @@ -1,35 +1,14 @@ // @vitest-environment jsdom -/** - * Assembly-level acceptance on SlotTestRuntime (real apply, real slot - * machinery, real renderer; data fed as fixtures) for surfaces that were - * previously pinned only by the assembled-app jsdom snapshots - * (apps/web/tests/{todo-display,terminal-card,slash-flow}.snapshot.ts): - * - * - the todo_write turn reaches BOTH surfaces through the product - * registrations (keyed toolview row in the flow, plan strip in the input - * dock via the 'todos' projection) and the strip follows projection - * retirement; - * - the bash keyed row carries its resident terminal card, and the fallback - * row reaches the same card through its expand control; - * - the resident composer textarea survives the blank→active conversion as - * the SAME DOM node (focus/IME continuity rides React reconciliation: - * component identity + tree position, which this assembled tree pins). - * - * Component-level behavior (collapse interaction, card model arms, summary - * derivations) lives in todo-panel.spec.tsx / terminal-card.spec.tsx; this - * suite only proves the assembled wiring. - */ +/** Conversation assembly acceptance independent of Tool presentation. */ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { cleanup, fireEvent, waitFor, within } from '@testing-library/react' import { useState } from 'react' import { LocaleService } from '@deepseek-ai/dsh-client-locale/client' -import type { ISession, SessionId, TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client' +import type { ISession, SessionId } from '@deepseek-ai/dsh-client-runtime/client' import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots' import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime' import { apply, inject, type EmptyWorkspaceOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client' -// The service reads its initial locale from the browser; these specs assert -// the shipped Chinese copy, so they state the browser they assume. usePinnedBrowserLanguages('zh-CN') const SID = 's1' as SessionId @@ -50,30 +29,6 @@ beforeEach(() => { vi.stubGlobal('ResizeObserver', ResizeObserverStub) }) -const TODOS: TodoItem[] = [ - { content: '梳理需求', status: 'completed' }, - { content: '实现 fixture 样本', status: 'in_progress' }, - { content: '浏览器验收', status: 'pending' }, -] - -const todoResult = (seq: number): ToolResultNode => ({ - kind: 'tool-result', seq, time: seq * 1_000, callId: `todo-${seq}`, - call: { name: 'todo_write', argsRaw: JSON.stringify({ todos: TODOS }) }, - callTime: seq * 1_000 - 500, - content: [], isError: false, callView: null, resultView: null, -}) - -const bashResult = (seq: number, callId: string, over?: Partial): ToolResultNode => ({ - kind: 'tool-result', seq, time: seq * 1_000, callId, - call: { name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}' }, - callTime: seq * 1_000 - 500, - content: [{ type: 'text', text: 'total 2\ndemo.txt\n' }], isError: false, - callView: { card: 'terminal', title: 'ls -la', description: 'List files' }, - resultView: { card: 'terminal', output: 'total 2\ndemo.txt\n', exitCode: 0 }, - ...over, -}) - -/** Test-owned AppFrame role: declares and renders the resident conversation area. */ type AppRootProps = PropsRenderSlots<'conversation' | 'details'> function AppRoot({ renderSlot }: AppRootProps) { return <>{renderSlot('conversation', {})} @@ -84,7 +39,6 @@ const LAYOUT_CHILDREN = { 'details': { kind: 'single', scope: 'session' }, } as const -/** Stateful occupant proving the root-scoped Hero workspace outlet is not rebuilt. */ function WorkspaceProbe({ open }: EmptyWorkspaceOwnerProps) { const [count, setCount] = useState(0) return ( @@ -94,7 +48,7 @@ function WorkspaceProbe({ open }: EmptyWorkspaceOwnerProps) { ) } -async function bench(nodes: ToolResultNode[], opts?: { blank?: boolean }) { +async function bench(opts?: { blank?: boolean }) { const runtime = await SlotTestRuntime.create() runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() }) const locale = new LocaleService(runtime.ctx) @@ -104,7 +58,7 @@ async function bench(nodes: ToolResultNode[], opts?: { blank?: boolean }) { id: SID, summary: { title: 'S', displayTitle: 'S', cwd: '/proj' }, snapshot: { - nodes, + nodes: [], ...(opts?.blank === true ? { blank: true, composerPhase: 'blank' as const } : {}), }, session: { @@ -117,69 +71,6 @@ async function bench(nodes: ToolResultNode[], opts?: { blank?: boolean }) { return runtime } -describe('todo_write assembly (product registrations, no outlet twins)', () => { - it('reaches the keyed toolview row and the dock plan strip, and the strip follows projection retirement', async () => { - const runtime = await bench([todoResult(3)]) - // The dock strip reads the host-computed 'todos' projection. - runtime.sessions.behavior(SID).projections.set('todos', TODOS) - const view = runtime.renderRoot() - - // Keyed toolview registration took the row (summary derived from args). - const row = view.container.querySelector('[data-tool="todo_write"]') - expect(row).not.toBeNull() - expect(row!.textContent).toContain('1/3 已完成 · 实现 fixture 样本') - - // The plan strip sits in the input dock, fed by the projection - // (default-collapsed: the header summary shows; rows appear on expand). - const panel = view.container.querySelector('[data-testid="todo-panel"]') - expect(panel).not.toBeNull() - expect(panel!.textContent).toContain('1 已完成\u2002·\u20021 进行中\u2002·\u20021 待处理') - fireEvent.click(panel!.querySelector('button')!) - expect([...panel!.querySelectorAll('li')].map(li => li.getAttribute('data-status'))) - .toEqual(['completed', 'in_progress', 'pending']) - - // Next turn retires the standing plan (host pushes null): the strip - // clears while the historical row stays in the flow. - await runtime.flush() - runtime.sessions.behavior(SID).projections.set('todos', null) - await waitFor(() => { - expect(view.container.querySelector('[data-testid="todo-panel"]')).toBeNull() - }) - expect(view.container.querySelector('[data-tool="todo_write"]')).not.toBeNull() - await runtime.dispose() - }) -}) - -describe('terminal card assembly', () => { - it('both the keyed bash row and the fallback row reach the terminal card through the whole-row expand', async () => { - const runtime = await bench([ - bashResult(3, 'c-keyed'), - // An unregistered tool with terminal views: GenericToolCard fallback. - bashResult(4, 'c-fallback', { call: { name: 'fx-bash', argsRaw: '{"command":"ls -la"}' } }), - ]) - const view = runtime.renderRoot() - - // Keyed BashRow: collapsed by default, the whole summary row is the toggle. - const keyedRow = view.container.querySelector('[data-sample="bash"]') - const keyed = keyedRow?.parentElement - expect(keyed?.querySelector('[data-terminal]')).toBeNull() - fireEvent.click(keyedRow!) - await waitFor(() => { - expect(keyed!.querySelector('[data-terminal]')).not.toBeNull() - }) - - // Fallback row: same unified expand interaction. - const fallback = view.container.querySelector('[data-tool="fx-bash"]') - expect(fallback).not.toBeNull() - expect(fallback!.querySelector('[data-terminal]')).toBeNull() - fireEvent.click(fallback!.querySelector('[data-expandable]')!) - await waitFor(() => { - expect(fallback!.querySelector('[data-terminal]')).not.toBeNull() - }) - await runtime.dispose() - }) -}) - describe('resident composer', () => { it('renders the locked view state while no session exists at all', async () => { const runtime = await SlotTestRuntime.create() @@ -190,8 +81,6 @@ describe('resident composer', () => { await runtime.root.declare(LAYOUT_CHILDREN, AppRoot) await runtime.mount({ inject: [...inject], apply }) const view = runtime.renderRoot() - // No session entity: the inert twin renders (disabled textarea), and the - // workspace picker chip is the only live control. const textarea = view.container.querySelector('textarea') expect(textarea).not.toBeNull() expect(textarea!.disabled).toBe(true) @@ -242,12 +131,8 @@ describe('resident composer', () => { await runtime.dispose() }) - it('the textarea survives the blank→active conversion as the same DOM node', async () => { - const runtime = await bench([], { blank: true }) - // The hero renders the LIVE composer only when the blank session's - // workspace resolves a chip title; an ownerless blank session shows the - // disabled twin instead (deleted-workspace semantics). + const runtime = await bench({ blank: true }) await runtime.workspaces.update((draft) => { draft.items = [{ workspaceId: 'w1', title: 'Proj', path: '/proj', sessionIds: [SID] }] as never }) @@ -256,13 +141,11 @@ describe('resident composer', () => { expect(hero).not.toBeNull() expect(hero!.disabled).toBe(false) - // First acceptance: the session leaves blank and the composer docks. await runtime.sessions.updateSnapshot(SID, (draft) => { draft.blank = false draft.composerPhase = 'active' }) - const docked = view.container.querySelector('textarea') - expect(docked).toBe(hero) + expect(view.container.querySelector('textarea')).toBe(hero) await runtime.dispose() }) }) @@ -291,8 +174,6 @@ describe('prompt rejection through the assembled composer', () => { fireEvent.keyDown(composer, { key: 'Enter' }) await waitFor(() => { expect(prompt).toHaveBeenCalledOnce() }) - // The rejection lands in snapshot.promptError (the Session's own path); - // the fixture mirrors that hop — the assembled InputBar renders it. await runtime.sessions.updateSnapshot(SID, (draft) => { draft.promptError = { op: 'send', @@ -301,7 +182,6 @@ describe('prompt rejection through the assembled composer', () => { }) const alert = await view.findByRole('alert') expect(alert.textContent).toContain('prompt rejected before acceptance (agent-busy)') - // Failure restore: the machine returned the draft to the same textarea. await waitFor(() => { expect((view.container.querySelector('textarea'))!.value).toBe('do not lose this') }) @@ -311,7 +191,7 @@ describe('prompt rejection through the assembled composer', () => { describe('title projection across assembled surfaces', () => { it('one summary update re-labels the current-session crumb', async () => { - const runtime = await bench([]) + const runtime = await bench() const view = runtime.renderRoot() const hierarchy = view.getByRole('navigation', { name: '会话层级' }) expect(within(hierarchy).getByRole('button', { name: 'S' }).hasAttribute('disabled')).toBe(true) diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx index df8fff6719..00001275d2 100644 --- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx @@ -1,12 +1,9 @@ // @vitest-environment jsdom // apply wiring: the conversation service provided, the chat view registered -// as the first 'conversation.view' ring entry declaring the keyed toolview -// hole, the slot registrations land against a root entry's children -// declarations (the AppFrame role), the shared store handle rides all strict -// session entries, and the bash sample + todo row mount through declaration -// injection as keyed entries. Full-chain rendering belongs to the -// machinery spec (chat-toolview-slot.spec.tsx) and the shell e2e; this spec -// stops at the assembly surface. +// as the first 'conversation.view' ring entry declaring the whole-Tool seat, +// the slot registrations land against a root entry's children declarations +// (the AppFrame role), and the shared store handle rides all strict session +// entries. Tool composition belongs to ui-tool and its machinery spec. import { describe, expect, it, vi } from 'vitest' import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime' @@ -56,7 +53,7 @@ describe('apply wiring', () => { await b.runtime.dispose() }) - it('registers the chat view as the first ring entry, declaring the keyed toolview hole', async () => { + it('registers the chat view as the first ring entry, declaring the whole-Tool seat', async () => { const b = await bench() const entries = b.slots.entries('conversation.view') expect(entries.map(e => e.options.id)).toEqual(['chat']) @@ -65,7 +62,7 @@ describe('apply wiring', () => { expect(entries[0]?.options.order).toBe(0) // Declaring is claiming: the chat entry's registration put the hole on // the ledger with the contract's kind/scope. - expect(b.slots.spec('conversation.chat.toolview')).toEqual({ kind: 'keyed', scope: 'session' }) + expect(b.slots.spec('conversation.chat.tool')).toEqual({ kind: 'single', scope: 'session' }) await b.runtime.dispose() }) @@ -92,14 +89,13 @@ describe('apply wiring', () => { await b.runtime.dispose() }) - it('mounts the tool rows as keyed entries through declaration injection', async () => { + it('leaves per-Tool rows to the ui-tool plugin', async () => { const b = await bench() // The actual toolview declaration activates every registrant. The // file-mutation registrant claims both write and edit for the diff card; the // one search row registers under both grep and glob; the web rows register // one component under both web tool names. - const entries = b.slots.entries('conversation.chat.toolview') - expect(entries.map(e => e.options.key)).toEqual(['bash', 'read', 'edit', 'write', 'grep', 'glob', 'web_search', 'web_fetch', 'todo_write', 'ask_user_question']) + expect(b.slots.entries('conversation.chat.tool')).toHaveLength(0) // 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() @@ -112,8 +108,8 @@ describe('apply wiring', () => { // The declared ring collapses with its declaring entry, and the chat // entry's keyed hole (with the sample's registration) collapses with it. expect(b.slots.entries('conversation.view')).toHaveLength(0) - expect(b.slots.entries('conversation.chat.toolview')).toHaveLength(0) - expect(b.slots.spec('conversation.chat.toolview')).toBeUndefined() + expect(b.slots.entries('conversation.chat.tool')).toHaveLength(0) + expect(b.slots.spec('conversation.chat.tool')).toBeUndefined() expect(b.slots.entries('details')).toHaveLength(0) expect(b.slots.entries('settings.general.item')).toHaveLength(0) expect(b.runtime.ctx.get('conversation')).toBeUndefined() diff --git a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx b/packages/client/ui-conversation/tests/chat-stats.spec.tsx similarity index 87% rename from packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx rename to packages/client/ui-conversation/tests/chat-stats.spec.tsx index 7187851420..cdb0ffa8c9 100644 --- a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-stats.spec.tsx @@ -1,26 +1,21 @@ // @vitest-environment jsdom -// StatsLine (composer.dock entry): totals derivation + the RFC -// hard acceptance — zero renders during streaming. Bash sample row: ToolRow -// chrome (Bash · description) without a row click target. +// StatsLine (composer.dock entry): totals derivation + the RFC hard +// acceptance — zero renders during streaming. import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { act, cleanup, fireEvent, render } from '@testing-library/react' import type { - AssistantMessageNode, ConversationSnapshot, SessionId, SessionListState, ToolResultNode, + AssistantMessageNode, ConversationSnapshot, SessionId, ToolResultNode, } from '@deepseek-ai/dsh-client-runtime/client' -import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts' import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' import { StatsLine, contextOccupancy, deriveStats, formatDuration, formatTokens, type StatsLineProps } from '../src/client/chat/StatsLine.tsx' -import { BashRow } from '../src/client/toolviews/bash-sample.tsx' import { en, zh } from '../src/client/locales.ts' -type BashRowProps = Parameters[0] - // Mirrors the real lookup chain (conversation namespace, then common). -const t: BashRowProps['t'] = makeTranslate(zh, commonZh) +const t: StatsLineProps['t'] = makeTranslate(zh, commonZh) const tEn: StatsLineProps['t'] = makeTranslate(en, commonEn) /** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */ @@ -301,43 +296,3 @@ describe('StatsLine', () => { expect(renders).toBe(before) }) }) - -describe('bash sample row', () => { - const SID = 'root-1' as SessionId - - const result = (callId: string): ToolResultNode => ({ - kind: 'tool-result', seq: 3, time: 3_000, callId, - call: { name: 'bash', argsRaw: '{"command":"make build","description":"Build"}' }, - callTime: 2_000, - content: [], isError: false, callView: null, resultView: null, - }) - - function listStore() { - return createSnapshotStore({ - ids: [SID], - byId: { - [SID]: { id: SID, title: 'r', displayTitle: 'r', running: false, blank: false, updatedAt: 0 }, - }, - current: undefined, - phase: 'ready', - subagentsByParent: {}, - currentAddress: undefined, - }) - } - - const rowProps = (): BashRowProps => ({ - callId: 'c1', toolName: 'bash', block: result('c1'), - openFile: vi.fn(), - sessionId: SID, - useSessions: bindSnapshotSelector(listStore()), - t, - } as unknown as BashRowProps) - - it('summarizes as Bash · description without a row click target', () => { - const view = render() - const row = view.container.querySelector('[data-sample="bash"]')! - expect(row.textContent).toContain('Bash') - expect(row.textContent).toContain('Build') - expect(row.getAttribute('data-clickable')).toBeNull() - }) -}) diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx index f42aed6731..0a25e9b198 100644 --- a/packages/client/ui-conversation/tests/chat-view.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx @@ -1,7 +1,7 @@ // @vitest-environment jsdom // ChatView behavior: flow derivation, streaming isolation (Profiler counts), -// toolview dispatch and selection handoff — driven through a scripted -// ObservableSnapshot fake, no wire. +// Tool seat ownership and selection handoff — driven through a scripted +// ObservableSnapshot fake, no wire or Tool presentation plugin. import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { Profiler } from 'react' @@ -14,7 +14,7 @@ import type { import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react' import { createSnapshotStore, PendingWait } from '@deepseek-ai/dsh-client-runtime/client' import { RpcId } from '@deepseek-ai/dsh-client-connection/client' -import type { ChatViewSlotProps, SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { ChatViewSlotProps, SelectionTarget, ToolTreeOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' import { createChatStore } from '../src/client/stores.ts' @@ -137,12 +137,25 @@ function makeHarness(init?: Partial) { const forkAt = vi.fn() // Selection rides the REAL chat store (same construction path as // production; the view reads it through the PropsStore useStore share). - // renderSlot stub renders the render-site fallback (an empty keyed ledger: - // every tool lands on GenericToolCard); keyed dispatch to registered rows - // is the slot machinery's behavior, covered by its own specs. const chat = createChatStore().create() - const renderSlot = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) => - opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlot'] + const t = makeTranslate(zh, commonZh) + const toolOwners: ToolTreeOwnerProps[] = [] + const renderSlot = ((key: string, owner: object, opts?: { fallback?: React.ReactNode }) => { + if (key !== 'conversation.chat.tool') return opts?.fallback ?? null + const tool = owner as ToolTreeOwnerProps + toolOwners.push(tool) + // Tool providers own their subtree. The host double carries only the + // semantic anchor required by ChatView's prepend-position contract. + return ( +
+ {tool.toolName || '(unnamed)'}:{tool.callId} +
+ ) + }) as unknown as ChatViewSlotProps['renderSlot'] const renderSlotChain = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) => opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlotChain'] // SessionProvider seat arrives with the session-scope child declaration; @@ -168,10 +181,13 @@ function makeHarness(init?: Partial) { chatScroll, forkAt, // Mirrors the real lookup chain (conversation namespace, then common). - t: makeTranslate(zh, commonZh), + t, } const setSelection = (next: SelectionTarget | null): void => { chat.actions.select(next) } - return { set, ChatView, props, openDetails, openFile, loadOlder, inspectCall, chatScroll, forkAt, setSelection } + return { + set, ChatView, props, openDetails, openFile, loadOlder, inspectCall, + chatScroll, forkAt, setSelection, toolOwners, + } } /** Simulate reader input (any device): a delivered position that deviates @@ -374,14 +390,13 @@ describe('chat-flow derivation', () => { }) describe('ChatView', () => { - it('a windowless tool result (call head truncated) renders with an empty tool name', () => { + it('hands a windowless tool result to the Tool seat with an empty tool name', () => { const h = makeHarness({ nodes: [{ ...toolResult(3, 'w1'), call: null }], }) const view = render() - // classifyTool('') → others; the summary slot falls back to the callId. - expect(view.container.querySelector('[data-variant="others"]')).not.toBeNull() - expect(view.getByText('w1')).toBeTruthy() + expect(view.getByTestId('tool-seat-w1')).toBeTruthy() + expect(h.toolOwners[0]).toMatchObject({ callId: 'w1', toolName: '' }) }) it('prepend keeps the reader\'s latest pending-request scroll position anchored', () => { @@ -423,8 +438,8 @@ describe('ChatView', () => { const view = render() expect(view.getByText('do the thing')).toBeTruthy() expect(view.getByText('running tools')).toBeTruthy() - expect(view.getAllByText('Bash')).toHaveLength(2) - expect(view.getByText('run a')).toBeTruthy() + expect(view.getByTestId('tool-seat-a').textContent).toBe('bash:a') + expect(view.getByTestId('tool-seat-b').textContent).toBe('bash:b') expect([...view.container.querySelectorAll('[data-chat-flow-key]')].map(row => ({ key: row.getAttribute('data-chat-flow-key'), kind: row.getAttribute('data-chat-flow-kind'), @@ -590,14 +605,12 @@ describe('ChatView', () => { ]) }) - it('the expanded row Inspect pill hands the call id to inspectCall', () => { + it('hands the trajectory callback to the Tool seat', () => { const h = makeHarness({ nodes: [toolResult(3, 'a')], }) - const view = render() - fireEvent.click(view.getByRole('button', { name: /Bash/ })) - fireEvent.click(view.getByText('Inspect')) - expect(h.inspectCall).toHaveBeenCalledWith('a') + render() + expect(h.toolOwners[0]?.inspectCall).toBe(h.inspectCall) }) it('shows assistant IconActions only on the last content message of each turn', () => { @@ -822,7 +835,7 @@ describe('ChatView', () => { // not re-render, so the row's renderSlot call count freezes during chunks. let rowRenders = 0 h.props.renderSlot = ((key: string, _owner: object) => { - if (key !== 'conversation.chat.toolview') return null + if (key !== 'conversation.chat.tool') return null rowRenders += 1 return
}) @@ -838,44 +851,19 @@ describe('ChatView', () => { expect(rowRenders).toBe(afterMount) }) - it('tool row expands to the args body via the whole-row toggle', () => { + it('updates the selected call id handed to the Tool seat', () => { const h = makeHarness({ nodes: [toolResult(3, 'a')] }) - const view = render() - expect(view.queryByText(/"command": "cmd-a"/)).toBeNull() - fireEvent.click(view.container.querySelector('[data-expandable]')!) - expect(view.getByText(/"command": "cmd-a"/)).toBeTruthy() - }) - - it('clicking a bash summary does not open details; selection still marks data-selected', () => { - const h = makeHarness({ nodes: [toolResult(3, 'a')] }) - const view = render() - fireEvent.click(view.getByText('run a')) - expect(h.openDetails).not.toHaveBeenCalled() - expect(h.openFile).not.toHaveBeenCalled() - expect(view.container.querySelector('[data-selected]')).toBeNull() + render() + expect(h.toolOwners.at(-1)?.selectedCallId).toBeUndefined() act(() => { h.setSelection({ turnSeq: 3, callId: 'a', toolName: 'bash' }) }) - expect(view.container.querySelector('[data-selected]')).not.toBeNull() + expect(h.toolOwners.at(-1)?.selectedCallId).toBe('a') }) - it('clicking a file-tool path summary opens the host file, not details', () => { - const h = makeHarness({ - nodes: [{ - kind: 'tool-result', seq: 3, time: 3_000, callId: 'r1', - call: { name: 'read', argsRaw: '{"path":"src/a.ts"}' }, - callTime: 2_500, content: [], isError: false, callView: null, resultView: null, - }], - }) - const view = render() - fireEvent.click(view.getByText('src/a.ts')) - expect(h.openFile).toHaveBeenCalledWith('src/a.ts') - expect(h.openDetails).not.toHaveBeenCalled() - }) - - it('running calls render as a live tool group with the running state', () => { + it('hands running calls to a live Tool group', () => { const h = makeHarness({ runningCalls: [runningCall('r1')], running: true }) const view = render() - expect(view.container.querySelector('[data-state="running"]')).not.toBeNull() - expect(view.getByText('cmd-r1')).toBeTruthy() + expect(view.getByTestId('tool-seat-r1')).toBeTruthy() + expect(h.toolOwners[0]?.block).toMatchObject({ callId: 'r1', argsRaw: '{"command":"cmd-r1"}' }) expect(view.getByRole('status').textContent).toBe('Deep diving...') }) @@ -903,19 +891,25 @@ describe('ChatView', () => { expect(status.textContent).toMatch(/^Deep diving\.\.\.2分0\d秒$/) }) - it('dispatches each tool row through the keyed slot with the tool name as entryKey', () => { - const h = makeHarness({ nodes: [toolResult(3, 'a')] }) - const calls: { key: string; entryKey?: string }[] = [] - h.props.renderSlot = ((key: string, _owner: object, opts?: { entryKey?: string; fallback?: React.ReactNode }) => { - calls.push({ key, ...(opts?.entryKey !== undefined ? { entryKey: opts.entryKey } : {}) }) + it('hands each ordered root call to the whole-Tool slot', () => { + const block = toolResult(3, 'a') + const h = makeHarness({ nodes: [block] }) + const calls: { key: string; owner: object; entryKey?: string }[] = [] + h.props.renderSlot = ((key: string, owner: object, opts?: { entryKey?: string; fallback?: React.ReactNode }) => { + calls.push({ key, owner, ...(opts?.entryKey !== undefined ? { entryKey: opts.entryKey } : {}) }) return opts?.fallback ?? null }) render() - // Keyed dispatch: slot name is the declared hole, entryKey the wire tool - // name, and the fallback (GenericToolCard) renders on an empty ledger. - // (Registered-row takeover and live unload are slot machinery behavior, - // owned by the slot system's own specs.) - expect(calls).toEqual([{ key: 'conversation.chat.toolview', entryKey: 'bash' }]) + expect(calls).toHaveLength(1) + expect(calls[0]).toMatchObject({ + key: 'conversation.chat.tool', + owner: { callId: 'a', toolName: 'bash', selectedCallId: undefined }, + }) + const owner = calls[0]?.owner as ToolTreeOwnerProps + expect(owner.block).toBe(block) + expect(owner.openFile).toBe(h.openFile) + expect(owner.inspectCall).toBe(h.inspectCall) + expect(calls[0]?.entryKey).toBeUndefined() }) it('prepend preserves a semantic row; a trailing user node force-scrolls', () => { diff --git a/packages/client/ui-conversation/tests/coverage-tails.spec.tsx b/packages/client/ui-conversation/tests/coverage-tails.spec.tsx index c92e43db6c..88e6c04141 100644 --- a/packages/client/ui-conversation/tests/coverage-tails.spec.tsx +++ b/packages/client/ui-conversation/tests/coverage-tails.spec.tsx @@ -1,26 +1,17 @@ // @vitest-environment jsdom -// Branch tails the acceptance specs do not reach: ToolRow stopped-state dot, -// bash sample state dots, the node-half empty apply, and AssistantMarkdown -// reasoning/unknown block arms. +// Branch tails the acceptance specs do not reach: the node-half empty apply +// and AssistantMarkdown reasoning/unknown block arms. -import { afterEach, describe, expect, it, vi } from 'vitest' +import { afterEach, describe, expect, it } from 'vitest' import { cleanup, render } from '@testing-library/react' -import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' -import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react' -import type { RunningToolCall, SessionId, SessionListState, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' import { apply as nodeApply } from '../src/index.ts' -import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx' -import { ToolRow } from '../src/client/chat/ToolRow.tsx' -import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx' -import { BashRow } from '../src/client/toolviews/bash-sample.tsx' +import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx' import { zh } from '../src/client/locales.ts' -type BashRowProps = Parameters[0] - // Mirrors the real lookup chain (conversation namespace, then common). -const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh) +const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh) afterEach(cleanup) @@ -29,14 +20,6 @@ describe('tails', () => { expect(() => { nodeApply() }).not.toThrow() }) - it('ToolRow stopped state renders the warning dot in the leading slot', () => { - const view = render( - } title="Bash" summary="s" body={null} state="stopped" />, - ) - expect(view.queryByTestId('icon')).toBeNull() - expect(view.container.querySelector('[data-state="stopped"]')).not.toBeNull() - }) - it('AssistantMarkdown renders reasoning as a Think row and unknown blocks as JSON fallback', () => { const view = render( { expect(blank.container.firstChild).toBeNull() }) - it('a settled others-variant row renders the sparkle icon in the leading slot', () => { - const settled: ToolResultNode = { - kind: 'tool-result', seq: 2, time: 2_000, callId: 'c5', - call: { name: 'todo_write', argsRaw: '{"note":"x"}' }, - callTime: 1_000, - content: [], isError: false, callView: null, resultView: null, - } - const props: GenericToolCardProps = { - callId: 'c5', toolName: 'todo_write', block: settled, openFile: vi.fn(), t, - } - const view = render() - // Settled ok state keeps the variant icon (sparkle) instead of a StateDot. - expect(view.container.querySelector('[data-variant="others"] svg')).not.toBeNull() - expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull() - }) - - it('BashRow carries data-state for running (row sweep) and StateDots for error/stopped', () => { - const sid = 'root-1' as SessionId - const list = createSnapshotStore({ - ids: [sid], - byId: { [sid]: { id: sid, title: 'r', displayTitle: 'r', running: false, blank: false, updatedAt: 0 } }, - current: undefined, - phase: 'ready', - subagentsByParent: {}, - currentAddress: undefined, - }) - const props = (block: RunningToolCall | ToolResultNode) => ({ - callId: 'c1', toolName: 'bash', block, openFile: vi.fn(), - sessionId: sid, useSessions: bindSnapshotSelector(list), - t, - } as unknown as BashRowProps) - - const running: RunningToolCall = { - callId: 'c1', name: 'bash', argsRaw: '{"command":"ls","description":"List"}', - turn: 1, step: 1, time: 1_000, callView: null, - } - const errorResult: ToolResultNode = { - kind: 'tool-result', seq: 1, time: 1_000, callId: 'c1', - call: { name: 'bash', argsRaw: '{"command":"boom"}' }, - callTime: 500, - content: [], isError: true, callView: null, resultView: null, - } - const stoppedResult: ToolResultNode = { - ...errorResult, - error: { name: 'E', code: 'interrupted' }, - } - - const runningView = render() - expect(runningView.container.querySelector('[data-state="running"]')).not.toBeNull() - expect(runningView.getByText('Bash')).toBeTruthy() - expect(runningView.getByText('List')).toBeTruthy() - runningView.unmount() - - const errorView = render() - expect(errorView.container.querySelector('[data-sample="bash"]')).not.toBeNull() - expect(errorView.container.querySelector('[data-state="error"]')).not.toBeNull() - expect(errorView.getByText('失败')).toBeTruthy() - errorView.unmount() - - const stoppedView = render() - expect(stoppedView.container.querySelector('[data-state="stopped"]')).not.toBeNull() - expect(stoppedView.getByText('已停止')).toBeTruthy() - }) }) diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx index 5adb4d817e..eacd2a754a 100644 --- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx +++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx @@ -6,7 +6,8 @@ import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react' import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' import type { UseSession } from '@deepseek-ai/dsh-client-web-react' import type { ConversationSnapshot, SessionId, SessionListState, WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client' -import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { SessionProviderComponent } from '@deepseek-ai/dsh-client-ui-slots' +import type { DetailsSlotProps, DetailsToolOwnerProps, SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' import { createChatStore } from '../src/client/stores.ts' @@ -33,6 +34,17 @@ afterEach(() => { const SID = 's1' as SessionId +/** Minimal framework seat for direct DetailsPanel host tests. */ +const SessionProviderStub: SessionProviderComponent = ({ children }) => children(SID) + +/** Observe the owner currency without importing the Tool details renderer. */ +function renderToolDetailsProbe(owners?: DetailsToolOwnerProps[]): DetailsSlotProps['renderSlot'] { + return (_key, owner) => { + owners?.push(owner as DetailsToolOwnerProps) + return
+ } +} + function snapshotBase(): ConversationSnapshot { return { sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(), @@ -95,6 +107,8 @@ describe('render branch tails', () => { }) const view = render( snap, subscribe: () => () => {} })} useSessions={bindSnapshotSelector(emptyList)} @@ -130,8 +144,11 @@ describe('render branch tails', () => { items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null, baselinesReady: true, recentWorkspaceId: undefined, }) + const owners: DetailsToolOwnerProps[] = [] const view = render( snap, subscribe: () => () => {} })} useSessions={bindSnapshotSelector(emptyList)} @@ -145,10 +162,15 @@ describe('render branch tails', () => { t={t} />, ) - // Sub-call material: the sub-tool name titles the panel, args pretty-print, - // and the COMPLETE logged output renders (no truncation anywhere). + // Conversation resolves the selected sub-call and hands its complete + // frozen block to the Tool-owned details seat. expect(view.getByText('read')).toBeTruthy() - expect(view.getByText(/notes\/demo\.txt/)).toBeTruthy() - expect(view.getByText(longText)).toBeTruthy() + expect(view.getByTestId('tool-details-seat')).toBeTruthy() + expect(owners).toHaveLength(1) + expect(owners[0]?.block).toMatchObject({ + callId: 'p1:code:1', + call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' }, + content: [{ type: 'text', text: longText }], + }) }) }) diff --git a/packages/client/ui-conversation/tests/todo-panel.spec.tsx b/packages/client/ui-conversation/tests/todo-panel.spec.tsx index 3ab95168a7..445d8139e6 100644 --- a/packages/client/ui-conversation/tests/todo-panel.spec.tsx +++ b/packages/client/ui-conversation/tests/todo-panel.spec.tsx @@ -1,30 +1,20 @@ // @vitest-environment jsdom /** * Todo display acceptance: the TodoPanel plan strip (empty-hidden, status rows - * including several `in_progress` at once, collapse), its TodoDock adapter - * (selects the plan off the session snapshot and follows changes), the row's - * plan summary (counts plus the two halves of the active summary — the named - * task and the `+N` count that parallel work adds, kept apart so the row never - * ellipsizes the count away), and the todo_write toolview row (progress summary - * from args, generic fallback on malformed JSON, shared ToolRow state dots and - * leading expansion). + * including several `in_progress` at once, collapse), and its TodoDock + * adapter (selects the plan off the session snapshot and follows changes). */ 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 { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' -import type { TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client' +import type { TodoItem } from '@deepseek-ai/dsh-client-runtime/client' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' -// Export discipline: packages/client/AGENTS.md. -import { TodoRow, todoToolview } from '../src/client/toolviews/todo-row.tsx' import type { TodoDockProps } from '../src/client/skeleton/TodoPanel.tsx' import { TodoDock, TodoPanel, todoDockEntry } from '../src/client/skeleton/TodoPanel.tsx' -import { planSummary } from '../src/client/toolviews/plan-summary.ts' import { NS, zh } from '../src/client/locales.ts' -type TodoRowProps = Parameters[0] - // Mirrors the real lookup chain (conversation namespace, then common). const t: TodoDockProps['t'] = makeTranslate(zh, commonZh) @@ -45,40 +35,6 @@ const PARALLEL: TodoItem[] = [ { content: '补测试', status: 'pending' }, ] -describe('planSummary', () => { - it('counts done/total and names the single active item with no extra count', () => { - expect(planSummary(LIST)).toEqual({ done: 1, total: 3, activeContent: '写组件', activeExtra: 0 }) - }) - - it('reports the extra active count separately when several items are in progress', () => { - // Parallel work marks several: naming one and hiding the rest would lose - // them, and the count stays unjoined so the row cannot ellipsize it. - expect(planSummary(PARALLEL)).toEqual({ done: 1, total: 5, activeContent: '写组件', activeExtra: 2 }) - }) - - it('has no hint when nothing is in progress', () => { - expect(planSummary([{ content: '都完了', status: 'completed' }])) - .toEqual({ done: 1, total: 1, activeContent: null, activeExtra: 0 }) - }) - - it('has no hint when the first active item carries no usable content (model JSON)', () => { - // Unvalidated args: a missing, mistyped, empty, or whitespace-only content - // yields no hint — and no orphan count, even with a second active item to - // count. Whitespace-only is the tool's own rejection rule (trimmed - // non-empty), and a rejected call keeps its args verbatim. - expect(planSummary([{ status: 'in_progress' }, { content: 'x', status: 'in_progress' }])) - .toMatchObject({ activeContent: null, activeExtra: 0 }) - expect(planSummary([{ content: 42, status: 'in_progress' }]).activeContent).toBeNull() - expect(planSummary([{ content: '', status: 'in_progress' }]).activeContent).toBeNull() - expect(planSummary([{ content: ' ', status: 'in_progress' }, { content: 'x', status: 'in_progress' }])) - .toMatchObject({ activeContent: null, activeExtra: 0 }) - }) - - it('is empty-safe', () => { - expect(planSummary([])).toEqual({ done: 0, total: 0, activeContent: null, activeExtra: 0 }) - }) -}) - describe('TodoPanel', () => { it('renders nothing while the list is empty', () => { const { container } = render() @@ -178,110 +134,3 @@ describe('TodoDock', () => { expect(register).toHaveBeenCalledWith({ name: 'conversation.input.dock', id: 'todo', order: 0, locale: NS }, TodoDock) }) }) - -const resultNode = (argsRaw: string, over?: Partial): ToolResultNode => ({ - kind: 'tool-result', seq: 10, time: 2_000, callTime: 1_000, callId: 'c1', - call: { name: 'todo_write', argsRaw }, - content: [], isError: false, callView: null, resultView: null, ...over, -}) - -function rowProps(block: unknown): TodoRowProps { - return { - callId: 'c1', toolName: 'todo_write', block, - openFile: vi.fn(), - sessionId: 's1', - useSessions: () => undefined, - t, - } as unknown as TodoRowProps -} - -describe('TodoRow', () => { - const ARGS = JSON.stringify({ todos: LIST }) - - it('summarizes counts and the active item from the call args', () => { - render() - expect(screen.getByText('更新任务清单')).toBeTruthy() - expect(screen.getByText('1/3 已完成 · 写组件')).toBeTruthy() - }) - - it('reports the extra active count outside the ellipsized summary text', () => { - const { container } = render() - const text = screen.getByText('1/5 已完成 · 写组件') - const extra = screen.getByText('+2') - // Separate spans: .summary truncates, the count must not travel inside it. - expect(text.contains(extra)).toBe(false) - expect(container.textContent).toContain('1/5 已完成 · 写组件+2') - }) - - it('omits the active clause when no item is in progress and reads running-call args', () => { - const args = JSON.stringify({ todos: [{ content: 'x', status: 'completed' }] }) - render() - expect(screen.getByText('1/1 已完成')).toBeTruthy() - }) - - it('keeps the counts when an active item has unusable content, instead of the generic summary', () => { - // planSummary yields activeContent null here, but the counts are known good, - // so the row drops only the active clause — `?? model.summary` never runs. - const args = JSON.stringify({ todos: [{ content: 'done', status: 'completed' }, { content: 42, status: 'in_progress' }] }) - const { container } = render() - expect(screen.getByText('1/2 已完成')).toBeTruthy() - expect(container.textContent).not.toContain('+') - }) - - it('keeps the non-ok execution states visible through the shared row states', () => { - // A running call (no result yet) carries the running state (row sweep). - const args = JSON.stringify({ todos: LIST }) - const running = render() - expect(running.container.querySelector('[data-state="running"]')).not.toBeNull() - expect(running.container.querySelector('[data-state="running"] svg')).not.toBeNull() - running.unmount() - // A cancelled call wrote no todo/write: the row must not read as a completed update. - const stopped = render() - expect(stopped.container.querySelector('[data-state="stopped"]')).not.toBeNull() - }) - - it('falls back to the generic summary on malformed args and marks the error state', () => { - const view = render() - expect(view.container.querySelector('[data-state="error"]')).not.toBeNull() - // Generic others summary: " · ". - expect(screen.getByText('todo_write · not json')).toBeTruthy() - }) - - it('falls back when parsed args carry no todos array', () => { - render() - expect(screen.getByText('todo_write · {"other":1}')).toBeTruthy() - }) - - it('leading toggle expands the raw args body', () => { - render() - fireEvent.click(screen.getByRole('button', { expanded: false })) - expect(screen.getByRole('button', { expanded: true })).toBeTruthy() - // The expanded body is the pretty-printed args, not the tool output. - expect(screen.getByText(/搭骨架/)).toBeTruthy() - }) - - it.each([ - { label: 'null root', argsRaw: 'null' }, - { label: 'non-object root', argsRaw: '42' }, - { label: 'null items', argsRaw: '{"todos":[null]}' }, - ])('falls back to the generic summary on valid JSON with an invalid shape ($label)', ({ argsRaw }) => { - render() - // No throw, and the generic others summary carries the raw args verbatim. - expect(screen.getByText(`todo_write · ${argsRaw}`)).toBeTruthy() - }) - - it('window-truncated result (call head lost) falls back to the callId summary', () => { - render() - expect(screen.getByText('todo_write · c1')).toBeTruthy() - }) - - it('todoToolview injects the toolview declaration directly', () => { - expect(todoToolview.name).toBe('todo-toolview') - expect(todoToolview.inject).toEqual(['slots']) - const register = vi.fn(() => () => undefined) - const inject = vi.fn((_name: string, callback: () => () => void) => callback()) - todoToolview.apply({ slots: { inject, register } } as never) - expect(inject).toHaveBeenCalledWith('conversation.chat.toolview', expect.any(Function)) - expect(register).toHaveBeenCalledWith({ name: 'conversation.chat.toolview', key: 'todo_write', locale: NS }, TodoRow) - }) -}) diff --git a/packages/client/ui-conversation/tests/views-type-chain.spec.tsx b/packages/client/ui-conversation/tests/views-type-chain.spec.tsx index 69e8355870..b055c51560 100644 --- a/packages/client/ui-conversation/tests/views-type-chain.spec.tsx +++ b/packages/client/ui-conversation/tests/views-type-chain.spec.tsx @@ -1,16 +1,11 @@ -// View-ring + toolview-hole type-chain samples, slot form: both are declared -// slots, so the register→inject→render chain and its compile-time locks are -// the slot system's (ui-slots/tests/type-chain.spec.tsx owns the generic -// duals). This spec pins the package-specific surface: the SlotMap rows -// (kind/scope/owner), list- and keyed-kind registration shapes, the ChatView -// and tool-row composed-props contracts, and the runtime dual — a real -// SlotsService ledger driving registration/order/disposal the way -// ConversationRoot's tab projection consumes it. +// View-ring type-chain samples. This spec pins the conversation-owned SlotMap +// row, list-kind registration shape, composed view props, and the runtime +// ledger projection consumed by ConversationRoot. import { Context } from 'cordis' import { describe, expect, it } from 'vitest' import type { ReactNode } from 'react' import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client' -import type { ChatViewSlotProps, ConvViewProps, ToolRowProps } from '../src/client/contract/slots.ts' +import type { ChatViewSlotProps, ConvViewProps } from '../src/client/contract/slots.ts' describe('view-ring type negatives (compile-time; body never runs)', () => { it('holds the negative samples as expect-error sites', () => { @@ -54,30 +49,6 @@ describe('view-ring type negatives (compile-time; body never runs)', () => { return null } void chatProps - // 7. Keyed hole registration requires the key shape field. - // @ts-expect-error missing `key` on a keyed-slot registration - slots.register({ name: 'conversation.chat.toolview' }, (_p: ToolRowProps) => null) - // 8. A list-kind shape field is rejected on the keyed hole. - slots.register( - // @ts-expect-error `id`/`order` belong to list slots, not the keyed hole - { name: 'conversation.chat.toolview', key: 'k', order: 1 }, - (_p: ToolRowProps) => null) - // 9. Tool-row components stay within their composed contract: the - // owner share + standard kit supply no chat-view members. - const overreaching = (props: ToolRowProps): ReactNode => { - // @ts-expect-error loadOlder lives on ChatViewSlotProps, not the row contract - void props.loadOlder - return null - } - void overreaching - // 10. Owner-share drift is red at the row component seam: block is the - // call union, not arbitrary payload. - const drifted = (props: ToolRowProps): ReactNode => { - // @ts-expect-error the block union has no `argsParsed` member - void props.block.argsParsed - return null - } - void drifted return null as ReactNode } expect(negatives).toBeTypeOf('function') diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml index a1d1a2c9d5..5aa997d003 100644 --- a/packages/client/ui-skill/README.i18n.yaml +++ b/packages/client/ui-skill/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-skill/README.md -README.md: bdd772662acda1f8cf1b7d8a7c5532f9b37123dd -README.zh.md: 959ff0ede6d545150fb22710c8af75859966caa9 +README.md: 44953fe36ad337d0dd70e4d8c0cc2372b8924c9b +README.zh.md: 8c21ef35eded61324d139dd32b7c1e38f8709d55 diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md index bdd772662a..44953fe36a 100644 --- a/packages/client/ui-skill/README.md +++ b/packages/client/ui-skill/README.md @@ -12,7 +12,7 @@ The `/client` export surface is the plugin body (`apply`/`inject`) only; the sou ## Skill tool row -The browser plugin also registers a keyed `skill` toolview in `conversation.chat.toolview`. A collapsed row renders the 14-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from a paired call/result slice in the current runtime window, never from the current catalog, so replay remains stable when installed skills or their descriptions change. +The browser plugin also registers the `skill` wire name in `ui-tool`'s keyed `tool.call.toolview` slot. A collapsed row renders the 14-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from the frozen call/result slice supplied by `ui-tool`, never from the current catalog, so replay remains stable when installed skills or their descriptions change. ## Model Experience diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md index 959ff0ede6..8c21ef35ed 100644 --- a/packages/client/ui-skill/README.zh.md +++ b/packages/client/ui-skill/README.zh.md @@ -12,7 +12,7 @@ pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文 ## skill 工具行 -浏览器插件还会把一个 key 为 `skill` 的 toolview 注册进 `conversation.chat.toolview`。收起的行以与 Bash 行相同的中性色层级显示 14 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自当前 runtime 窗口中已配对的调用／结果片段，绝不读取当前 skill 目录，因此即使已安装的 skill 或其描述发生变化，回放仍保持稳定。 +浏览器插件还会把 `skill` wire 名称注册进 `ui-tool` 的 keyed `tool.call.toolview` slot。收起的行以与 Bash 行相同的中性色层级显示 14 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自 `ui-tool` 提供的冻结 call/result slice，绝不读取当前 skill 目录，因此即使已安装的 skill 或其描述发生变化，回放仍保持稳定。 ## 模型体验 diff --git a/packages/client/ui-skill/package.json b/packages/client/ui-skill/package.json index c9d2dd4ed8..420b1c4322 100644 --- a/packages/client/ui-skill/package.json +++ b/packages/client/ui-skill/package.json @@ -26,7 +26,7 @@ "inject": [ "@deepseek-ai/dsh-client-runtime", "@deepseek-ai/dsh-client-locale", - "@deepseek-ai/dsh-client-ui-conversation", + "@deepseek-ai/dsh-client-ui-tool", "@deepseek-ai/dsh-client-ui-slash" ], "platform": "web" @@ -40,7 +40,7 @@ "@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-conversation": "^0.0.1", + "@deepseek-ai/dsh-client-ui-tool": "^0.0.1", "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1", "@deepseek-ai/dsh-client-ui-slash": "^0.0.1", "@deepseek-ai/dsh-client-ui-slots": "^0.0.1", @@ -53,7 +53,7 @@ "@deepseek-ai/dsh-client-locale": "workspace:^", "@deepseek-ai/dsh-client-runtime": "workspace:^", "@deepseek-ai/dsh-client-test-runtime": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", + "@deepseek-ai/dsh-client-ui-tool": "workspace:^", "@deepseek-ai/dsh-client-ui-primitives": "workspace:^", "@deepseek-ai/dsh-client-ui-slash": "workspace:^", "@deepseek-ai/dsh-client-ui-slots": "workspace:^", diff --git a/packages/client/ui-skill/src/client/SkillRow.tsx b/packages/client/ui-skill/src/client/SkillRow.tsx index 65b474825a..a26c41ada5 100644 --- a/packages/client/ui-skill/src/client/SkillRow.tsx +++ b/packages/client/ui-skill/src/client/SkillRow.tsx @@ -6,7 +6,7 @@ import { useState, type KeyboardEvent, type ReactNode } from 'react' import { IconChevronDownOutline14, IconInspectOutline12, IconSkillOutline16, StateDot, } from '@deepseek-ai/dsh-client-ui-primitives' -import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client' import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots' import css from './SkillRow.module.css' @@ -14,7 +14,7 @@ import css from './SkillRow.module.css' type SkillRowState = 'running' | 'ok' | 'error' | 'stopped' /** Full row props: the toolview runtime share plus this package's locale seat. */ -type SkillRowProps = ToolRowProps & PropsLocale<'skill'> +type SkillRowProps = ToolCallViewProps & PropsLocale<'skill'> /** Compact, replay-stable view model for the dedicated row. */ interface SkillRowModel { @@ -45,9 +45,9 @@ function skillName(argsRaw: string, callId: string): string { return argsRaw === '' ? callId : firstLine(argsRaw) } -/** Flatten durable result blocks under the generic tool-row text contract. - * Keep aligned with ui-conversation's contract/tool-call-model.ts `resultText`. */ -function resultText(block: ToolRowProps['block']): string | null { +/** Flatten durable result blocks under the generic Tool-row text contract. + * Keep aligned with ui-tool's models/tool-call-model.ts `resultText`. */ +function resultText(block: ToolCallViewProps['block']): string | null { if (!('kind' in block)) return null const parts: string[] = [] for (const item of block.content) { @@ -60,7 +60,7 @@ function resultText(block: ToolRowProps['block']): string | null { } /** Derive display state without consulting the live skill catalog. */ -function skillRowModel(block: ToolRowProps['block']): SkillRowModel { +function skillRowModel(block: ToolCallViewProps['block']): SkillRowModel { const settled = 'kind' in block const argsRaw = (settled ? block.call?.argsRaw : block.argsRaw) ?? '' const state: SkillRowState = !settled diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts index 4e23be06be..139398b648 100644 --- a/packages/client/ui-skill/src/client/index.ts +++ b/packages/client/ui-skill/src/client/index.ts @@ -58,8 +58,8 @@ export const inject = ['slash', 'connection', 'sessions', 'slots', 'locale'] */ export function apply(ctx: ClientContext): void { ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-skill: dictionaries') - ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register( - { name: 'conversation.chat.toolview', key: 'skill', locale: NS }, + ctx.slots.inject('tool.call.toolview', () => ctx.slots.register( + { name: 'tool.call.toolview', key: 'skill', locale: NS }, SkillRow, )) diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts index f73a8d8bda..4679ef2c98 100644 --- a/packages/client/ui-skill/tests/browser-plugin.spec.ts +++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts @@ -41,7 +41,7 @@ function providePresentation(ctx: Context): PresentationCapture { const slots = new SlotsService(ctx) slots.register({ name: 'root', - children: { 'conversation.chat.toolview': { kind: 'keyed', scope: 'session' } }, + children: { 'tool.call.toolview': { kind: 'keyed', scope: 'session' } }, } as never, () => null) const capture: PresentationCapture = { slots, @@ -113,7 +113,7 @@ describe('apply', () => { ctx.provide('sessions', { subagentAddress: () => undefined }) const presentation = providePresentation(ctx) await ctx.plugin({ inject: [...inject], apply }).await() - const entry = presentation.slots.entries('conversation.chat.toolview')[0] + const entry = presentation.slots.entries('tool.call.toolview')[0] expect(entry?.options).toMatchObject({ key: 'skill' }) expect(entry?.locale).toBe('skill') expect(entry?.component).toBe(SkillToolRow) @@ -158,7 +158,7 @@ describe('apply', () => { // …and fiber teardown releases it. await fiber.dispose() expect(() => slash.registerSource(rival)).not.toThrow() - expect(presentation.slots.entries('conversation.chat.toolview')).toHaveLength(0) + expect(presentation.slots.entries('tool.call.toolview')).toHaveLength(0) expect(presentation.localeDisposed).toBe(true) }) }) diff --git a/packages/client/ui-skill/tsconfig.json b/packages/client/ui-skill/tsconfig.json index f83486aa36..d6ec931648 100644 --- a/packages/client/ui-skill/tsconfig.json +++ b/packages/client/ui-skill/tsconfig.json @@ -21,7 +21,7 @@ "path": "../runtime" }, { - "path": "../ui-conversation" + "path": "../ui-tool" }, { "path": "../ui-primitives" diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml new file mode 100644 index 0000000000..828cfa25ef --- /dev/null +++ b/packages/client/ui-tool/README.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 packages/client/ui-tool/README.md +README.md: 381253f4eddaa57b89318dd23da3a049505fdd15 +README.zh.md: ae539131198771bc1d0e280bbfaa76ec0ec60792 diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md new file mode 100644 index 0000000000..381253f4ed --- /dev/null +++ b/packages/client/ui-tool/README.md @@ -0,0 +1,44 @@ +# @deepseek-ai/dsh-client-ui-tool + +English | [中文](README.zh.md) + +Client Tool presentation plugin. `ui-conversation` supplies one ordered root call through `conversation.chat.tool`; this package renders that root and its Code Dispatch children, then dispatches every atomic call through the keyed `tool.call.toolview` slot. Unregistered Tool names use the generic card. + +Business UI packages register only their wire Tool names and atomic views. They do not pair Session events, rebuild the transcript, or own root/subcall topology. The Runtime remains authoritative for call/result pairing, lifecycle, and `codeDispatches`; the conversation view remains authoritative for ChatFlow placement. + +## Rendering contract + +`ToolCallTree` receives one root `ToolCallBlock`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. Through its standard session slot props it selects the Runtime-projected `codeDispatches[rootCallId]` array, then sends the root and every child through the same atomic dispatch path. The Runtime currently exposes only one Code Dispatch child level, so the renderer preserves that shape instead of inventing recursive data. + +The package also fills `conversation.details.tool` with `ToolDetails`. The row and details renderers share the same pure card models for `terminal`, `read`, `diff`, `search`, and `web` render intents. Unknown intent tags and malformed wire card data fall back to flattened Tool result text. + +Generic rows classify known Tool names into search, read, shell, write, edit, code, or generic variants. Running, successful, failed, and interrupted lifecycle states come only from the frozen call/result slice. File paths resolve against the session `cwd` only when the user invokes the Host open-file callback; presentation code does not read Session services. + +## Atomic Tool views + +An owning business package registers its wire Tool name into `tool.call.toolview`: + +```ts ignore-check +ctx.slots.inject('tool.call.toolview', () => + ctx.slots.register({ + name: 'tool.call.toolview', + key: '', + }, BusinessToolRow)) +``` + +The owner payload is `ToolCallOwnerProps`: `callId`, `toolName`, the frozen `block`, optional `cwd`, and plain `openFile`/`inspect` callbacks. The registration receives the normal session slot runtime share. It does not receive React nodes, Runtime services, or root/subcall knowledge. + +This package currently owns the generic fallback and the built-in bash/pwsh, read, write/edit, grep/glob, web, todo, question, and Code Dispatch presentations. `ui-skill` demonstrates a business-owned registration for `skill`. + +## Model Experience + +None. This package renders already logged Tool calls and results and does not alter model requests, Tool execution, or session events. + +#### KV Cache effect + +None. The package is client-only presentation. + +## Known Limitations and Deferred Work + +- The Runtime currently exposes one level of Code Dispatch children. The renderer sends roots and children through the same atomic path, but it does not claim an arbitrary recursive wire topology. +- Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot. diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md new file mode 100644 index 0000000000..ae53913119 --- /dev/null +++ b/packages/client/ui-tool/README.zh.md @@ -0,0 +1,44 @@ +# @deepseek-ai/dsh-client-ui-tool + +[English](README.md) | 中文 + +Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的 root call；本包渲染该 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。 + +业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和 `codeDispatches`；conversation view 继续负责 ChatFlow 位置。 + +## 渲染契约 + +`ToolCallTree` 接收一个 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，再让 root 与每个 child 经过同一条原子分发路径。Runtime 当前只暴露一层 Code Dispatch child，因此 renderer 保留该形状，不自行发明递归数据。 + +本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。 + +通用行把已知 Tool 名称归类为 search、read、shell、write、edit、code 或 generic 变体。运行中、成功、失败和中断状态只来自冻结的 call/result slice。只有用户调用 Host 打开文件回调时，文件路径才相对会话 `cwd` 解析；展示代码不读取 Session service。 + +## 原子 Tool 视图 + +业务所有方把自己的 wire Tool 名称注册进 `tool.call.toolview`： + +```ts ignore-check +ctx.slots.inject('tool.call.toolview', () => + ctx.slots.register({ + name: 'tool.call.toolview', + key: '', + }, BusinessToolRow)) +``` + +owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`、可选 `cwd`，以及普通的 `openFile`／`inspect` 回调。注册项会收到正常的 Session slot runtime share，但不会收到 React node、Runtime service 或 root/subcall 知识。 + +本包当前拥有 generic fallback，以及 bash/pwsh、read、write/edit、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。`ui-skill` 展示了业务包如何拥有 `skill` 注册。 + +## 模型体验 + +无。本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。 + +#### KV Cache 影响 + +无。本包只负责 Client 展示。 + +## 已知限制与后续工作 + +- Runtime 当前只暴露一层 Code Dispatch 子调用。renderer 会让 root 和 child 经过同一个原子分发路径，但不宣称 wire 拓扑已经支持任意递归。 +- 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。 diff --git a/packages/client/ui-tool/package.json b/packages/client/ui-tool/package.json new file mode 100644 index 0000000000..965a084cd2 --- /dev/null +++ b/packages/client/ui-tool/package.json @@ -0,0 +1,73 @@ +{ + "name": "@deepseek-ai/dsh-client-ui-tool", + "description": "Client Tool call-tree renderer and keyed per-tool presentation slot", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./client": { + "types": "./lib/types/client/index.d.ts", + "default": "./lib/client.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "dshClient": { + "inject": [ + "@deepseek-ai/dsh-client-runtime", + "@deepseek-ai/dsh-client-locale", + "@deepseek-ai/dsh-client-ui-conversation" + ], + "platform": "web" + }, + "scripts": { + "bundle": "tsdown", + "watch": "tsdown --watch" + }, + "license": "BSD-3-Clause", + "dependencies": { + "clsx": "^2.0.0" + }, + "peerDependencies": { + "@deepseek-ai/dsh-client-locale": "^0.0.1", + "@deepseek-ai/dsh-client-runtime": "^0.0.1", + "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1", + "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1", + "@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" + }, + "devDependencies": { + "@deepseek-ai/dsh-client-connection": "workspace:^", + "@deepseek-ai/dsh-client-locale": "workspace:^", + "@deepseek-ai/dsh-client-runtime": "workspace:^", + "@deepseek-ai/dsh-client-test-runtime": "workspace:^", + "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", + "@deepseek-ai/dsh-client-ui-primitives": "workspace:^", + "@deepseek-ai/dsh-client-ui-slots": "workspace:^", + "@deepseek-ai/dsh-client-web-react": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "@testing-library/react": "^16.1.0", + "@types/react": "~18.3.1", + "cordis": "^4.0.0-rc.7", + "react": "^18.2.0", + "react-dom": "^18.2.0" + }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/client.js", + "lib/types/**/*.d.ts" + ] +} diff --git a/packages/client/ui-tool/src/client/apply.ts b/packages/client/ui-tool/src/client/apply.ts new file mode 100644 index 0000000000..48a9a4c812 --- /dev/null +++ b/packages/client/ui-tool/src/client/apply.ts @@ -0,0 +1,43 @@ +/** Register the Tool call tree, details renderer, and built-in atomic views. */ +import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client' +import type {} from '@deepseek-ai/dsh-client-ui-conversation/client' +import { ToolCallTree } from './tool/ToolCallTree.tsx' +import { ToolDetails } from './tool/ToolDetails.tsx' +import { CONVERSATION_NS as NS } from './locale.ts' +import { askQuestionToolview } from './tool/toolviews/ask-question-row.tsx' +import { bashToolviewSample } from './tool/toolviews/bash-sample.tsx' +import { fileMutationToolview } from './tool/toolviews/file-mutation-row.tsx' +import { readToolview } from './tool/toolviews/read-row.tsx' +import { searchToolview } from './tool/toolviews/search-row.tsx' +import { todoToolview } from './tool/toolviews/todo-row.tsx' +import { webToolview } from './tool/toolviews/web-row.tsx' + +/** Required service: the slot registry that owns both Tool render seats. */ +export const inject = ['slots'] + +/** + * Mount the whole-Tool renderers and built-in atomic Tool registrations. + * @param ctx - Client root context. + */ +export function apply(ctx: ClientContext): void { + ctx.slots.inject('conversation.chat.tool', () => ctx.slots.register({ + name: 'conversation.chat.tool', + locale: NS, + children: { + 'tool.call.toolview': { kind: 'keyed', scope: 'session' }, + }, + }, ToolCallTree)) + + ctx.slots.inject('conversation.details.tool', () => ctx.slots.register({ + name: 'conversation.details.tool', + locale: NS, + }, ToolDetails)) + + ctx.plugin(bashToolviewSample) + ctx.plugin(readToolview) + ctx.plugin(fileMutationToolview) + ctx.plugin(searchToolview) + ctx.plugin(webToolview) + ctx.plugin(todoToolview) + ctx.plugin(askQuestionToolview) +} diff --git a/packages/client/ui-tool/src/client/contract/slots.ts b/packages/client/ui-tool/src/client/contract/slots.ts new file mode 100644 index 0000000000..4b74055b2c --- /dev/null +++ b/packages/client/ui-tool/src/client/contract/slots.ts @@ -0,0 +1,39 @@ +/** Tool UI slot declarations and their composed component props. */ +import type { PropsLocale, PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' +import type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client' +import type {} from '@deepseek-ai/dsh-client-ui-conversation/client' +import type {} from '@deepseek-ai/dsh-client-locale/client' + +declare module '@deepseek-ai/dsh-client-ui-slots' { + interface SlotMap { + /** Keyed atomic Tool call view, dispatched by the wire Tool name. */ + 'tool.call.toolview': { kind: 'keyed'; scope: 'session'; owner: ToolCallOwnerProps } + } +} + +/** Standard owner currency supplied to every atomic Tool view. */ +export interface ToolCallOwnerProps { + /** Tool call identity, stable across running and settled forms. */ + callId: string + /** Wire Tool name and keyed dispatch value. */ + toolName: string + /** Frozen running call or settled result node. */ + block: ToolCallBlock + /** Session workspace root for relative summaries. */ + cwd?: string | undefined + /** Open a Tool argument path through the Host. */ + openFile: (path: string) => void + /** Inspect this call in the trajectory view when available. */ + inspect?: (() => void) | undefined +} + +/** Full props of a registered atomic Tool view. */ +export type ToolCallViewProps = PropsRuntime<'tool.call.toolview'> + +/** Full props of the Tool call-tree renderer registered into the chat flow. */ +export type ToolTreeProps = PropsRuntime<'conversation.chat.tool'> + & PropsRenderSlots<'tool.call.toolview'> + & PropsLocale<'conversation'> + +/** Full props of the selected Tool output renderer in the details panel. */ +export type ToolDetailsProps = PropsRuntime<'conversation.details.tool'> & PropsLocale<'conversation'> diff --git a/packages/client/ui-tool/src/client/index.ts b/packages/client/ui-tool/src/client/index.ts new file mode 100644 index 0000000000..357506b1db --- /dev/null +++ b/packages/client/ui-tool/src/client/index.ts @@ -0,0 +1,3 @@ +/** Browser Tool plugin: whole-call composition and keyed atomic Tool views. */ +export { apply, inject } from './apply.ts' +export type { ToolCallOwnerProps, ToolCallViewProps, ToolDetailsProps, ToolTreeProps } from './contract/slots.ts' diff --git a/packages/client/ui-tool/src/client/locale.ts b/packages/client/ui-tool/src/client/locale.ts new file mode 100644 index 0000000000..0dd6721101 --- /dev/null +++ b/packages/client/ui-tool/src/client/locale.ts @@ -0,0 +1,2 @@ +/** Locale namespace supplied by the conversation owner to Tool renderers. */ +export const CONVERSATION_NS = 'conversation' diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css b/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css new file mode 100644 index 0000000000..b33fb477c1 --- /dev/null +++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css @@ -0,0 +1,12 @@ +.callRow { + border-radius: 6px; +} + +.subCalls { + display: flex; + flex-direction: column; + gap: 4px; + margin: 4px 0 2px 22px; + padding-left: 8px; + border-left: 1px solid var(--dsw-alias-border-l2); +} diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx new file mode 100644 index 0000000000..8091f26dff --- /dev/null +++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx @@ -0,0 +1,88 @@ +/** Root/subcall Tool composition with one keyed atomic dispatch path. */ +import { memo, useMemo } from 'react' +import type { CodeSubCall, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client' +import type { ToolCallOwnerProps, ToolTreeProps } from '../contract/slots.ts' +import { GenericToolCard } from './toolviews/GenericToolCard.tsx' +import css from './ToolCallTree.module.css' + +/** Resolve a Code Dispatch child's wire Tool name from either lifecycle form. */ +function subCallName(node: CodeSubCall): string { + return 'kind' in node ? node.call?.name ?? '' : node.name +} + +/** One atomic call dispatched through the Tool-owned keyed slot. */ +const ToolCall = memo(function ToolCall({ + renderSlot, callId, toolName, block, openFile, selected, cwd, inspectCall, t, +}: Pick & { + callId: string + toolName: string + block: ToolCallBlock + selected: boolean +}) { + const owner: ToolCallOwnerProps = useMemo(() => ({ + callId, + toolName, + block, + openFile, + cwd, + inspect: () => { inspectCall(callId) }, + }), [callId, toolName, block, openFile, cwd, inspectCall]) + return ( +
+ {renderSlot('tool.call.toolview', owner, { + entryKey: toolName, + fallback: , + })} +
+ ) +}) + +/** + * Render one root Tool call and its currently supported one-level Code + * Dispatch children. Root and children use the same atomic keyed dispatch. + * @param props - whole-Tool owner data and the Tool-owned child-slot share. + * @returns the Tool call tree. + */ +export function ToolCallTree({ + useSession, renderSlot, callId, toolName, block, selectedCallId, cwd, openFile, inspectCall, t, +}: ToolTreeProps) { + const subCalls = useSession(snapshot => snapshot.codeDispatches.get(callId)) + return ( + <> + + {subCalls !== undefined && subCalls.length > 0 ? ( +
+ {subCalls.map(node => ( + + ))} +
+ ) : null} + + ) +} diff --git a/packages/client/ui-tool/src/client/tool/ToolDetails.module.css b/packages/client/ui-tool/src/client/tool/ToolDetails.module.css new file mode 100644 index 0000000000..ebfb3afb07 --- /dev/null +++ b/packages/client/ui-tool/src/client/tool/ToolDetails.module.css @@ -0,0 +1,46 @@ +.description { + margin: 0 0 6px; + color: var(--dsw-alias-label-secondary); + font: var(--dsw-font-xs-13); +} + +.cardBody { + margin: 0; +} + +.recovery { + margin: 6px 0 0; + white-space: pre-wrap; + overflow-wrap: anywhere; + color: var(--dsw-alias-label-tertiary); + font: var(--dsw-font-xs-13); +} + +.code { + margin: 0; + padding: 16px; + border-radius: 12px; + background: var(--dsw-alias-markdown-code-block); + font-family: var(--ds-font-family-code); + font-size: 13px; + line-height: 22px; + color: var(--dsw-alias-label-primary); + white-space: pre-wrap; + word-break: break-word; +} + +.code[data-error] { + color: var(--dsw-alias-state-error-primary); +} + +.read, +.web { + margin: 0; +} + +.empty { + padding: 8px 0; + font-size: 13px; + line-height: 20px; + color: var(--dsw-alias-label-tertiary); +} diff --git a/packages/client/ui-tool/src/client/tool/ToolDetails.tsx b/packages/client/ui-tool/src/client/tool/ToolDetails.tsx new file mode 100644 index 0000000000..f496801daa --- /dev/null +++ b/packages/client/ui-tool/src/client/tool/ToolDetails.tsx @@ -0,0 +1,66 @@ +/** Card-aware output body for the selected Tool call in details. */ +import { DiffBlock, ReadBlock, SearchBlock, TerminalBlock, WebBlock } from '@deepseek-ai/dsh-client-ui-primitives' +import type { ToolDetailsProps } from '../contract/slots.ts' +import { diffCardModel } from './models/diff-card-model.ts' +import { readCardModel } from './models/read-card-model.ts' +import { searchCardModel } from './models/search-card-model.ts' +import { terminalBlockLabels, terminalCardModel } from './models/terminal-card-model.ts' +import { resultText } from './models/tool-call-model.ts' +import { webCardModel } from './models/web-card-model.ts' +import css from './ToolDetails.module.css' + +/** Pure details-body inputs; framework session seats stay at the slot boundary. */ +interface ToolDetailsContentProps { + block: ToolDetailsProps['block'] + cwd?: ToolDetailsProps['cwd'] + t: ToolDetailsProps['t'] +} + +/** + * Render the selected Tool call's structured output when its presentation + * intent is known, otherwise preserve the flattened result text. + * @param props - selected call slice, workspace root, and locale seat. + * @returns the details output body. + */ +export function ToolDetails({ block, cwd, t }: ToolDetailsContentProps) { + const terminal = terminalCardModel(block, cwd) + if (terminal !== null) { + return ( + <> + {terminal.description !== undefined ? ( +
{terminal.description}
+ ) : null} + + + ) + } + const read = readCardModel(block, cwd) + if (read !== null) return + const diff = diffCardModel(block) + if (diff !== null) return + const search = searchCardModel(block) + if (search !== null) { + return ( + <> + + {search.recovery !== undefined ?
{search.recovery}
: null} + + ) + } + const web = webCardModel(block) + if (web !== null) { + const body = 'kind' in block ? resultText(block) : '' + return ( + <> + + {body !== '' ? 
{body}
: null} + + ) + } + if (!('kind' in block)) return
{t('details.running')}
+ return ( + 
+      {resultText(block)}
+
+ ) +} diff --git a/packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css b/packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css new file mode 100644 index 0000000000..04f2d18d0a --- /dev/null +++ b/packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css @@ -0,0 +1,69 @@ +/* Shared Tool calls disclosure header: [16px leading] gap 6 [title 14/24]. */ + +.root { + display: flex; + flex-direction: column; + width: 100%; + min-width: 0; +} + +.row { + position: relative; + overflow: hidden; + display: flex; + align-items: center; + height: 24px; + min-width: 0; +} + +.row[data-expandable] { + cursor: pointer; +} + +.leading { + position: relative; + flex: none; + width: 16px; + height: 16px; + display: inline-flex; + align-items: center; + justify-content: center; + margin-right: 6px; + padding: 0; + border: none; + background: none; + color: var(--dsw-alias-label-tertiary); +} + +button.leading { + cursor: pointer; +} + +.iconIdle { + display: inline-flex; + opacity: 1; + transition: opacity 100ms ease; +} + +.chevronHover { + position: absolute; + inset: 0; + margin: auto; + opacity: 0; + transition: opacity 100ms ease; +} + +.row:hover .iconIdle { + opacity: 0; +} + +.row:hover .chevronHover { + opacity: 1; +} + +.title { + flex: none; + font-size: 14px; + line-height: 24px; + color: var(--dsw-alias-label-secondary); +} diff --git a/packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx b/packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx new file mode 100644 index 0000000000..361fb24517 --- /dev/null +++ b/packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx @@ -0,0 +1,104 @@ +import { type KeyboardEvent, type MouseEvent, type ReactNode } from 'react' +import clsx from 'clsx' +import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives' +import css from './DisclosureRow.module.css' + +/** Shared 24px disclosure chrome for conversation flow rows. */ +export interface DisclosureRowProps { + icon: ReactNode + title: string + open: boolean + expandable: boolean + onToggle: () => void + /** Makes the complete title row the disclosure target. */ + expandOnRowClick?: boolean | undefined + /** Replaces the collapsed icon with a chevron while the row is hovered. */ + previewChevron?: boolean | undefined + /** Keeps `collapsedContent` inline while open (ToolRow's summary stays readable next to the expanded card). */ + keepContentWhenOpen?: boolean | undefined + collapsedContent?: ReactNode + children?: ReactNode + className?: string | undefined + rowClassName?: string | undefined + leadingClassName?: string | undefined + chevronClassName?: string | undefined + titleClassName?: string | undefined +} + +/** + * Render one disclosure header and its controlled expanded content. + * @param props - Visual content, controlled state, and interaction policy. + * @returns The disclosure row. + */ +export function DisclosureRow({ + icon, + title, + open, + expandable, + onToggle, + expandOnRowClick = false, + previewChevron = expandable, + keepContentWhenOpen = false, + collapsedContent, + children, + className, + rowClassName, + leadingClassName, + chevronClassName, + titleClassName, +}: DisclosureRowProps) { + const rowExpands = expandable && expandOnRowClick + const toggleFromLeading = (event: MouseEvent) => { + event.stopPropagation() + onToggle() + } + const toggleFromKeyboard = (event: KeyboardEvent) => { + if (!rowExpands || (event.key !== 'Enter' && event.key !== ' ')) return + event.preventDefault() + onToggle() + } + const collapsedLeading = previewChevron + ? ( + <> + {icon} + + + ) + : icon + const leading = open + ? + : collapsedLeading + + return ( +
+
+ {expandable && !rowExpands ? ( + + ) : ( + + {leading} + + )} + {title} + {(keepContentWhenOpen || !open) && collapsedContent} +
+ {open && children} +
+ ) +} diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css b/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css similarity index 94% rename from packages/client/ui-conversation/src/client/chat/ToolRow.module.css rename to packages/client/ui-tool/src/client/tool/components/ToolRow.module.css index 36f4c2b76a..9d9bce9eed 100644 --- a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css +++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css @@ -84,11 +84,6 @@ color: var(--dsw-alias-label-tertiary); } -/* Live reasoning follows its one-line summary to the inline end. */ -.summary[data-follow-end] { - text-overflow: clip; -} - /* Trailing summary fragment kept out of .summary's ellipsis, for a count whose whole value is that it survives a narrow row (the todo row's parallel-active `+n`). Repeats .summary's type because it sits beside that text, and its @@ -184,19 +179,6 @@ overflow-y: auto; } -/* Think expanded body: plain indented gray reasoning prose — no IN/OUT card - (the reasoning is not an input payload), pre-wrapped at the row's indent. - Uncapped: reasoning reads as message prose, so it flows with the page - instead of scrolling in a box. */ -.thinkBody { - padding: 4px 0 4px 22px; - font-size: 14px; - line-height: 24px; - white-space: pre-wrap; - word-break: break-word; - color: var(--dsw-alias-label-tertiary); -} - /* Expanded input/output card (figma 1249:35657): the code-block surface and radius from the TerminalBlock/CodeBlock family. The card itself is a plain column — the padding and the IN/OUT gutter-label grid live on each section diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx similarity index 76% rename from packages/client/ui-conversation/src/client/chat/ToolRow.tsx rename to packages/client/ui-tool/src/client/tool/components/ToolRow.tsx index 48c0c825cb..61c677ea98 100644 --- a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx +++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx @@ -4,36 +4,32 @@ // DisclosureRow chrome with the whole row as the expand toggle (click / // Enter / Space, icon→chevron hover preview). The collapsed row is always // one line; every row with body, output, or a card material (terminal, diff, -// read, search, web) is expandable; the summary stays inline while open, -// except Think, where the running collapsed row follows the latest line at its -// scroll end and the summary yields while open to avoid repeating the body. +// read, search, web) is expandable; the summary stays inline while open. // The expanded body — an IN/OUT gutter-labeled card (figma 1249:35657) for // text input/output, the run_code program through CodeBlock, or a card // primitive (TerminalBlock, DiffBlock, ReadBlock, SearchBlock, WebBlock) for a // call that declared that render intent — lives in a max-height scroll // container so a long payload scrolls internally instead of taking over the -// message flow; Think's prose is the exception and flows uncapped like message -// text. Every card kind starts collapsed, so a run of tool calls stays +// message flow. Every card kind starts collapsed, so a run of tool calls stays // scannable; the details panel is the single-call full-height reading surface. // Expand state is component-local view state. File-tool summaries are path // links that open through the host (stopPropagation keeps the two gestures // independent); an error row's collapsed summary is the failure's first line in // the error color. -import { useEffect, useRef, useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react' +import { useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react' import clsx from 'clsx' import { CodeBlock, DiffBlock, IconInspectOutline12, ReadBlock, SearchBlock, StateDot, TerminalBlock, WebBlock, } from '@deepseek-ai/dsh-client-ui-primitives' import type { WebBlockProps } from '@deepseek-ai/dsh-client-ui-primitives' import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots' -import { CHAT_DIFF_MAX_LINES, type DiffCardModel } from '../contract/diff-card-model.ts' -import { CHAT_READ_MAX_LINES, type ReadCardModel } from '../contract/read-card-model.ts' -import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../contract/search-card-model.ts' -import { terminalBlockLabels, type TerminalCardModel } from '../contract/terminal-card-model.ts' -import type { ToolRowState, ToolRowVariant } from '../contract/tool-call-model.ts' +import { CHAT_DIFF_MAX_LINES, type DiffCardModel } from '../models/diff-card-model.ts' +import { CHAT_READ_MAX_LINES, type ReadCardModel } from '../models/read-card-model.ts' +import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../models/search-card-model.ts' +import { terminalBlockLabels, type TerminalCardModel } from '../models/terminal-card-model.ts' +import type { ToolRowState, ToolRowVariant } from '../models/tool-call-model.ts' import { DisclosureRow } from './DisclosureRow.tsx' -import { useThrottledVisualUpdate } from './use-throttled-visual-update.ts' import css from './ToolRow.module.css' export interface ToolRowProps { @@ -101,8 +97,7 @@ export interface ToolRowProps { onOpenFile?: ((path: string) => void) | undefined /** * Jump to this call in the trajectory view: a hover-revealed Inspect pill - * over the expanded body. Absent = no affordance (rows without a call - * identity, like Think). + * over the expanded body. Absent = no affordance. */ inspect?: (() => void) | undefined } @@ -153,7 +148,6 @@ export function ToolRow({ inspect, }: ToolRowProps) { const [expanded, setExpanded] = useState(false) - const summaryRef = useRef(null) const terminalBody = terminal ?? null const diffBody = diff ?? null const readBody = read ?? null @@ -178,19 +172,6 @@ export function ToolRow({ const suffix = failureLine === null ? summarySuffix ?? null : null // The failure line is error prose, not the path: no open-file affordance. const fileLink = filePath !== undefined && onOpenFile !== undefined && failureLine === null - const isThink = variant === 'think' - const followSummaryEnd = isThink && state === 'running' && !open - const scheduleSummaryScroll = useThrottledVisualUpdate(() => { - const summaryElement = summaryRef.current - if (summaryElement === null) return - summaryElement.scrollLeft = followSummaryEnd - ? summaryElement.scrollWidth - summaryElement.clientWidth - : 0 - }) - useEffect(() => { - if (!isThink) return - scheduleSummaryScroll() - }, [followSummaryEnd, isThink, scheduleSummaryScroll, summaryText]) const toggleExpand = () => { setExpanded(v => !v) } @@ -205,9 +186,6 @@ export function ToolRow({ const fileLinkKeyDown = (event: KeyboardEvent) => { if (event.key === 'Enter' || event.key === ' ') event.stopPropagation() } - // Think reasoning is prose, not an input payload: expanded, it renders as - // plain indented text (no IN/OUT card) and the inline summary yields to avoid - // repeating the body. // The code variant's program renders through CodeBlock (shiki), so only its // output joins the IN/OUT card; every other variant's input does too. const cardBody = variant === 'code' ? null : body @@ -227,7 +205,7 @@ export function ToolRow({ open={open} expandable={expandable} expandOnRowClick - keepContentWhenOpen={!isThink} + keepContentWhenOpen onToggle={toggleExpand} collapsedContent={summaryText !== '' && ( /* An empty summary drops the separator with it (a row that is only @@ -245,9 +223,7 @@ export function ToolRow({ ) : ( {summaryText} @@ -285,38 +261,36 @@ export function ToolRow({ ) : webBody !== null ? - : isThink - ?
{body}
- : ( - <> - {variant === 'code' && body !== null && ( -
- -
- )} - {(cardBody !== null || outputText !== null) && ( -
- {cardBody !== null && ( -
- IN - {cardBody} -
- )} - {cardBody !== null && outputText !== null && ( - - )} - {outputText !== null && ( -
- OUT - - {outputText} - -
- )} -
- )} - - )} + : ( + <> + {variant === 'code' && body !== null && ( +
+ +
+ )} + {(cardBody !== null || outputText !== null) && ( +
+ {cardBody !== null && ( +
+ IN + {cardBody} +
+ )} + {cardBody !== null && outputText !== null && ( + + )} + {outputText !== null && ( +
+ OUT + + {outputText} + +
+ )} +
+ )} + + )} {inspect !== undefined && ( )) const view = b.runtime.renderRoot() @@ -191,7 +193,7 @@ describe('keyed toolview hole through the real machinery', () => { }) describe('registrant declaration injection', () => { - it('runs the plugin before ui-conversation and waits on the actual toolview declaration', async () => { + it('runs a registrant before ui-tool and waits on the actual toolview declaration', async () => { const runtime = await SlotTestRuntime.create() runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() }) const locale = new LocaleService(runtime.ctx) @@ -204,8 +206,8 @@ describe('registrant declaration injection', () => { let applyRuns = 0 const registrantApply = (registrantCtx: typeof runtime.ctx): void => { applyRuns += 1 - registrantCtx.slots.inject('conversation.chat.toolview', () => registrantCtx.slots.register( - { name: 'conversation.chat.toolview', key: 'late' }, () => null)) + registrantCtx.slots.inject('tool.call.toolview', () => registrantCtx.slots.register( + { name: 'tool.call.toolview', key: 'late' }, () => null)) } const late = runtime.ctx.plugin({ name: 'late-registrant', @@ -215,11 +217,12 @@ describe('registrant declaration injection', () => { await Promise.resolve() await late.await() expect(applyRuns).toBe(1) - expect(runtime.slots.entries('conversation.chat.toolview')).toHaveLength(0) + expect(runtime.slots.entries('tool.call.toolview')).toHaveLength(0) // Mounting the package declares the slot and activates the waiting entry. - await runtime.mount({ inject: [...inject], apply }) - expect(runtime.slots.entries('conversation.chat.toolview').map(e => e.options.key)) + await runtime.mount({ inject: [...injectConversation], apply: applyConversation }) + await runtime.mount({ inject: [...injectTool], apply: applyTool }) + expect(runtime.slots.entries('tool.call.toolview').map(e => e.options.key)) .toEqual(expect.arrayContaining(['bash', 'late'])) await runtime.dispose() }) diff --git a/packages/client/ui-tool/tests/toolview-type-chain.spec.tsx b/packages/client/ui-tool/tests/toolview-type-chain.spec.tsx new file mode 100644 index 0000000000..b1aa7b9464 --- /dev/null +++ b/packages/client/ui-tool/tests/toolview-type-chain.spec.tsx @@ -0,0 +1,34 @@ +// The Tool-owned keyed-slot type chain: registration shape and composed +// atomic-view props. Generic slot-system duals live in ui-slots tests. +import { describe, expect, it } from 'vitest' +import type { ReactNode } from 'react' +import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client' +import type { ToolCallViewProps } from '../src/client/contract/slots.ts' + +describe('toolview type negatives (compile-time; body never runs)', () => { + it('holds the negative samples as expect-error sites', () => { + const negatives = (slots: SlotsService) => { + // Keyed registration requires the key shape field. + // @ts-expect-error missing `key` on a keyed-slot registration + slots.register({ name: 'tool.call.toolview' }, (_p: ToolCallViewProps) => null) + slots.register( + // @ts-expect-error `id`/`order` belong to list slots, not the keyed hole + { name: 'tool.call.toolview', key: 'k', order: 1 }, + (_p: ToolCallViewProps) => null) + const overreaching = (props: ToolCallViewProps): ReactNode => { + // @ts-expect-error loadOlder belongs to the conversation host, not an atomic Tool view + void props.loadOlder + return null + } + void overreaching + const drifted = (props: ToolCallViewProps): ReactNode => { + // @ts-expect-error the Tool call union has no pre-parsed args member + void props.block.argsParsed + return null + } + void drifted + return null as ReactNode + } + expect(negatives).toBeTypeOf('function') + }) +}) diff --git a/packages/client/ui-conversation/tests/web-card.spec.tsx b/packages/client/ui-tool/tests/web-card.spec.tsx similarity index 94% rename from packages/client/ui-conversation/tests/web-card.spec.tsx rename to packages/client/ui-tool/tests/web-card.spec.tsx index 220661ff88..743b450ca7 100644 --- a/packages/client/ui-conversation/tests/web-card.spec.tsx +++ b/packages/client/ui-tool/tests/web-card.spec.tsx @@ -16,15 +16,17 @@ import type { } from '@deepseek-ai/dsh-client-runtime/client' import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client' import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react' -import type { SelectionTarget, ToolRowOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client' -import { webCardModel } from '../src/client/contract/web-card-model.ts' -import { createChatStore } from '../src/client/stores.ts' -import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx' -import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx' -import { WebRow, webToolview } from '../src/client/toolviews/web-row.tsx' +import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { ToolCallOwnerProps } from '@deepseek-ai/dsh-client-ui-tool/client' +import { webCardModel } from '../src/client/tool/models/web-card-model.ts' +import { createChatStore } from '../../ui-conversation/src/client/stores.ts' +import { GenericToolCard } from '../src/client/tool/toolviews/GenericToolCard.tsx' +import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx' +import { WebRow, webToolview } from '../src/client/tool/toolviews/web-row.tsx' +import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' -import { zh } from '../src/client/locales.ts' +import { zh } from '../../ui-conversation/src/client/locales.ts' afterEach(cleanup) @@ -121,7 +123,7 @@ describe('webCardModel', () => { }) describe('chat row web body', () => { - const ownerProps = (block: RunningToolCall | ToolResultNode, toolName: string): ToolRowOwnerProps => ({ + const ownerProps = (block: RunningToolCall | ToolResultNode, toolName: string): ToolCallOwnerProps => ({ callId: block.callId, toolName, block, openFile: vi.fn(), }) // WebRow reads only toolName/block off the full runtime share plus the locale @@ -214,6 +216,8 @@ describe('DetailsPanel web Output section', () => { }) return render( snapshot, subscribe: () => () => {} })} useSessions={bindSnapshotSelector(sessions)} diff --git a/packages/client/ui-tool/tsconfig.json b/packages/client/ui-tool/tsconfig.json new file mode 100644 index 0000000000..17516295fb --- /dev/null +++ b/packages/client/ui-tool/tsconfig.json @@ -0,0 +1,33 @@ +{ + "extends": "../../../tsconfig.base.client.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cordis" + }, + { + "path": "../runtime" + }, + { + "path": "../locale" + }, + { + "path": "../ui-conversation" + }, + { + "path": "../ui-primitives" + }, + { + "path": "../ui-slots" + }, + { + "path": "../../support/invariants" + } + ] +} diff --git a/packages/client/ui-tool/tsdown.config.ts b/packages/client/ui-tool/tsdown.config.ts new file mode 100644 index 0000000000..1c66514f9a --- /dev/null +++ b/packages/client/ui-tool/tsdown.config.ts @@ -0,0 +1,3 @@ +import { clientBundle } from '../tsdown.client.ts' + +export default clientBundle('@deepseek-ai/dsh-client-ui-tool', ['lib/types/index.js', 'lib/types/invariant.js']) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d604545dfd..ccbc67c764 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1284,6 +1284,9 @@ importers: '@deepseek-ai/dsh-client-ui-theme': specifier: workspace:^ version: link:../../client/ui-theme + '@deepseek-ai/dsh-client-ui-tool': + specifier: workspace:^ + version: link:../../client/ui-tool '@deepseek-ai/dsh-client-ui-trajectory': specifier: workspace:^ version: link:../../client/ui-trajectory @@ -2201,9 +2204,6 @@ importers: '@deepseek-ai/dsh-client-test-runtime': specifier: workspace:^ version: link:../test-runtime - '@deepseek-ai/dsh-client-ui-conversation': - specifier: workspace:^ - version: link:../ui-conversation '@deepseek-ai/dsh-client-ui-primitives': specifier: workspace:^ version: link:../ui-primitives @@ -2213,6 +2213,9 @@ importers: '@deepseek-ai/dsh-client-ui-slots': specifier: workspace:^ version: link:../ui-slots + '@deepseek-ai/dsh-client-ui-tool': + specifier: workspace:^ + version: link:../ui-tool '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../support/invariants @@ -2355,6 +2358,55 @@ importers: specifier: ^18.2.0 version: 18.3.1 + packages/client/ui-tool: + dependencies: + clsx: + specifier: ^2.0.0 + version: 2.1.1 + devDependencies: + '@deepseek-ai/dsh-client-connection': + specifier: workspace:^ + version: link:../connection + '@deepseek-ai/dsh-client-locale': + specifier: workspace:^ + version: link:../locale + '@deepseek-ai/dsh-client-runtime': + specifier: workspace:^ + version: link:../runtime + '@deepseek-ai/dsh-client-test-runtime': + specifier: workspace:^ + version: link:../test-runtime + '@deepseek-ai/dsh-client-ui-conversation': + specifier: workspace:^ + version: link:../ui-conversation + '@deepseek-ai/dsh-client-ui-primitives': + specifier: workspace:^ + version: link:../ui-primitives + '@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 + '@testing-library/react': + specifier: ^16.1.0 + version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1) + '@types/react': + specifier: ~18.3.1 + version: 18.3.31 + cordis: + specifier: ^4.0.0-rc.7 + version: link:../../../vendor/cordis + react: + specifier: ^18.2.0 + version: 18.3.1 + react-dom: + specifier: ^18.2.0 + version: 18.3.1(react@18.3.1) + packages/client/ui-trajectory: dependencies: '@tanstack/react-virtual': diff --git a/tsconfig.base.json b/tsconfig.base.json index 75719f1ecc..de9b63459c 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -162,6 +162,7 @@ "@deepseek-ai/dsh-client-ui-layout": ["./packages/client/ui-layout/src"], "@deepseek-ai/dsh-client-ui-sidebar": ["./packages/client/ui-sidebar/src"], "@deepseek-ai/dsh-client-ui-conversation": ["./packages/client/ui-conversation/src"], + "@deepseek-ai/dsh-client-ui-tool": ["./packages/client/ui-tool/src"], "@deepseek-ai/dsh-client-ui-deliverables": ["./packages/client/ui-deliverables/src"], "@deepseek-ai/dsh-client-ui-slash": ["./packages/client/ui-slash/src"], "@deepseek-ai/dsh-client-ui-command": ["./packages/client/ui-command/src"], diff --git a/tsconfig.client.json b/tsconfig.client.json index 2a2b16e2e7..9ce72753c1 100644 --- a/tsconfig.client.json +++ b/tsconfig.client.json @@ -59,6 +59,7 @@ { "path": "./packages/client/ui-layout" }, { "path": "./packages/client/ui-sidebar" }, { "path": "./packages/client/ui-conversation" }, + { "path": "./packages/client/ui-tool" }, { "path": "./packages/client/ui-deliverables" }, { "path": "./packages/client/ui-workspace" }, { "path": "./packages/client/ui-slash" }, diff --git a/vitest.config.ts b/vitest.config.ts index f5a86ac7a9..597bca5618 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -162,6 +162,7 @@ export default defineConfig({ 'packages/client/web-react/src/*', 'packages/client/runtime/src/*', 'packages/client/ui-conversation/src/*', + 'packages/client/ui-tool/src/*', 'packages/client/ui-slots/src/*', 'packages/client/ui-layout/src/*', 'packages/client/web/src/*', From fafd54fc03d1d44e3bab07cedeb913d8e636e077 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 8 Aug 2026 15:19:27 +0800 Subject: [PATCH 03/17] docs(client): record Tool presentation ownership --- ...7-19-gui-web-client-architecture.i18n.yaml | 4 +- .../2026-07-19-gui-web-client-architecture.md | 24 ++-- ...26-07-19-gui-web-client-architecture.zh.md | 24 ++-- .../2026-07-23-toolview-dissolution.i18n.yaml | 4 +- .../2026-07-23-toolview-dissolution.md | 16 ++- .../2026-07-23-toolview-dissolution.zh.md | 16 ++- ...ient-tool-presentation-ownership.i18n.yaml | 6 + ...8-08-client-tool-presentation-ownership.md | 103 ++++++++++++++++++ ...8-client-tool-presentation-ownership.zh.md | 103 ++++++++++++++++++ 9 files changed, 256 insertions(+), 44 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml create mode 100644 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md create mode 100644 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml index 5376a626e6..2dccd44aae 100644 --- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md -2026-07-19-gui-web-client-architecture.md: 1a91d88818c374a1637b546fb3ddf6647af68570 -2026-07-19-gui-web-client-architecture.zh.md: 5c0bacde9836d45812895f5d9c89a0e8974ed7a1 +2026-07-19-gui-web-client-architecture.md: 4dc4558ea245baa17646f92b9b5e4c9a45b6a419 +2026-07-19-gui-web-client-architecture.zh.md: a306b5c82891840b96340f5464267cc9d861ef7e diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md index 1a91d88818..4dc4558ea2 100644 --- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md +++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md @@ -44,7 +44,7 @@ Implementation homes: registry core and the props-share types in `packages/clien A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer install seam), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md). -There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. A tool row is a keyed child slot each view declares for itself — today `'conversation.chat.toolview'` (keyed/session), declared by the chat entry's `children` table; the key space is runtime-open (SlotMap declares slots, never keys), which is what the tool ring's open tool-name set required. The render site dispatches per row via `entryKey: toolName` with `GenericToolCard` as the call-site `fallback`; the owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openDetails`), and `ToolRowProps` composes it with the session standard kit for registrant components. Registrants are plain plugins with zero dedicated machinery: `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '', inject? }, Row))`; the declaration is the load and reload dependency, independently from `ConversationService` ([decision](2026-08-05-slot-declaration-injection.md)). Interaction drafts and other row state ride the ordinary store seat. Trajectory/waterfall get same-shaped slots (names fixed by the slot-naming discipline `..`, one shared owner type) that land with their own row render sites — RendersCheck rejects a declaration nobody renders, so the two slots cannot be declared early. +There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: ui-conversation places each ordered root call into the single `'conversation.chat.tool'` seat and passes the Runtime-projected Code Dispatch children without interpreting their Tool names; ui-tool renders that root/child shape and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and both roots and children dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components. **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport). @@ -86,22 +86,24 @@ The glue package is the whole ctx↔React boundary; components stay framework-fr ## Directory shape -Twelve `packages/client/*` packages (ui-slots, ui-primitives, web-react, connection, runtime, ui-layout, ui-sidebar, ui-conversation, ui-trajectory, ui-theme, i18n, web) plus `apps/web` — the vite application, a thin `main` over the shell's boot export. Plugin packages keep their browser half under `src/client/`; **every build artifact lands in `lib/`** — the node half as `lib/index.js`/`lib/invariant.js`, the browser bundle as `lib/client.js` (the shared tsdown client preset emits both; there is no `dist/` directory, and `exports["./client"]` points at `./lib/client.js`). Dependency direction: `ui-slots ← web-react ← runtime ← ui-* (peers) ← web`, with ui-primitives/ui-theme/i18n as zero-dependency side paths. +Client packages live under `packages/client/*`, with `apps/web` as the thin Vite application over the shell's boot export. Plugin packages keep their browser half under `src/client/`; **every build artifact lands in `lib/`** — the node half as `lib/index.js`/`lib/invariant.js`, the browser bundle as `lib/client.js` (the shared tsdown client preset emits both; there is no `dist/` directory, and `exports["./client"]` points at `./lib/client.js`). `ui-slots`, web-react, and runtime form the infrastructure direction; feature plugins cooperate through services and slots rather than importing presentation implementations. A multi-domain plugin package additionally splits its client half by future package boundaries — ui-conversation is the exemplar: ``` src/client/ - contract/ the only shared face between domains (types + composed props shares) - service.ts cross-domain orchestration (imports contract only) - skeleton/ domain: shell components (ConversationRoot/InputBar/EmptyState/DetailsPanel) - chat/ domain: the chat view - toolviews/ domain: sample tool-row registrants (third-party posture) - apply.ts the ONLY file allowed to import across domains (assembly point) - index.ts thin re-export shell (contract + apply + components) + contract/ shared slot and cross-domain types + service.ts cross-domain orchestration + skeleton/ conversation shell and details host + chat/ ordered conversation view + input/ composer state machine + queue/ queued-message presentation + settings/ conversation settings rows + apply.ts cross-domain assembly point + index.ts public contract surface ``` -Domain implementation files never import a sibling domain — shared surfaces route through `contract/` (e.g. the toolviews samples take `ToolRowProps` from the contract, never chat internals). `scripts/verify-client-domain-graph.ts` enforces the layering (contract=0, domains=1, apply/index=2; imports may only point at levels ≤ own; sibling-domain edges fail). A future package split promotes each domain directory to a package and mechanically rewrites import paths. +Domain implementation files never import a sibling domain; shared surfaces route through `contract/`. `scripts/verify-client-domain-graph.ts` enforces the layering (contract=0, domains=1, apply/index=2; imports may only point at levels ≤ own; sibling-domain edges fail). Tool presentation is already a separate `ui-tool` package and reaches chat and details only through the slots ui-conversation declares. ## How to develop @@ -122,5 +124,5 @@ Token streams no longer shake the render tree: a frame storm costs unsubscribed | One statically-linked SPA bundle | Plugins must be host-composable at runtime (config-driven); a monolith re-couples every UI feature to one build | | window globals / import maps for shared deps | The DI require table keeps sharing explicit, fail-loud, and swappable; globals leak identity and version silently | | Business data in zustand slices | The event window/accumulator is a behavioral state machine, not a flat slice; the object layer keeps snapshot granularity and batching controllable | -| String-keyed global component registry for tool rows | Per-view keyed child slots plus in-component session branching carry the same need with the one registration model; a parallel registry does not come back ([toolview dissolution](2026-07-23-toolview-dissolution.md)) | +| Parallel string-keyed component registry for Tool rows | ui-tool's keyed child slot carries the runtime-open Tool-name set through the one slot registration model ([toolview dissolution](2026-07-23-toolview-dissolution.md)) | | Progressive/Suspense boot in P-I | One-flip boot is strictly simpler; the loader's per-plugin status face is kept so progressive lighting can land later without re-architecture | diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md index 5c0bacde98..a306b5c828 100644 --- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md @@ -44,7 +44,7 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain- 服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。 -slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。工具行是各视图自己声明的 keyed 子槽——今天是 `'conversation.chat.toolview'`（keyed/session），由 chat 条目的 `children` 表声明；key 空间运行时开放（SlotMap 声明槽、从不声明 key），这正是工具环「tool 名开放集」的原需求。渲染点逐行以 `entryKey: toolName` 分发、以 `GenericToolCard` 作调用点 `fallback`；owner 载荷是统一的 `ToolRowOwnerProps`（`callId`/`toolName`/`block`/`openDetails`），`ToolRowProps` 把它与 session 标配 kit 预组合供注册方组件取用。注册方就是普通插件、零专用设施：`ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '', inject? }, Row))`；声明本身就是加载与重载依赖，不依赖 `ConversationService`（[决策](2026-08-05-slot-declaration-injection.md)）。交互草稿等行内状态走普通 store 席位。trajectory/waterfall 得同形槽（槽名按槽名纪律 `<域>.<条目>.<孔位>` 已定死，共用一张 owner 类型），随各自的行渲染点落地——RendersCheck 拒绝无人渲染的声明，两槽无法提前声明。 +slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：ui-conversation 把每个已排序 root call 放进 single `'conversation.chat.tool'` seat，并透传 Runtime 已投影的 Code Dispatch child，不解释其 Tool 名称；ui-tool 渲染该 root/child 形状，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与 child 都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。 **scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。 @@ -86,22 +86,24 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES── ## 目录形态 -十二个 `packages/client/*` 包（ui-slots、ui-primitives、web-react、connection、runtime、ui-layout、ui-sidebar、ui-conversation、ui-trajectory、ui-theme、i18n、web）加 `apps/web`——vite 应用，壳 boot 导出之上的薄 `main`。插件包的浏览器半边在 `src/client/` 下；**一切构建产物落 `lib/`**——node 半边为 `lib/index.js`/`lib/invariant.js`，浏览器 bundle 为 `lib/client.js`（共享 tsdown client 预设两者皆出；无 `dist/` 目录，`exports["./client"]` 指向 `./lib/client.js`）。依赖方向：`ui-slots ← web-react ← runtime ← ui-*（并列）← web`，ui-primitives/ui-theme/i18n 为零依赖旁路。 +Client 包位于 `packages/client/*`，`apps/web` 是壳 boot 导出之上的薄 Vite 应用。插件包的浏览器半边在 `src/client/` 下；**一切构建产物落 `lib/`**——node 半边为 `lib/index.js`/`lib/invariant.js`，浏览器 bundle 为 `lib/client.js`（共享 tsdown client 预设两者皆出；无 `dist/` 目录，`exports["./client"]` 指向 `./lib/client.js`）。`ui-slots`、web-react 与 runtime 构成基础设施方向；功能插件通过 service 与 slot 协作，不导入展示实现。 多域插件包的 client 半边还按未来包边界再拆——ui-conversation 即样板： ``` src/client/ - contract/ the only shared face between domains (types + composed props shares) - service.ts cross-domain orchestration (imports contract only) - skeleton/ domain: shell components (ConversationRoot/InputBar/EmptyState/DetailsPanel) - chat/ domain: the chat view - toolviews/ domain: sample tool-row registrants (third-party posture) - apply.ts the ONLY file allowed to import across domains (assembly point) - index.ts thin re-export shell (contract + apply + components) + contract/ shared slot and cross-domain types + service.ts cross-domain orchestration + skeleton/ conversation shell and details host + chat/ ordered conversation view + input/ composer state machine + queue/ queued-message presentation + settings/ conversation settings rows + apply.ts cross-domain assembly point + index.ts public contract surface ``` -域实现文件永不 import 兄弟域——共享面一律走 `contract/`（如 toolviews 样例从契约取 `ToolRowProps`，永不碰 chat 内部）。`scripts/verify-client-domain-graph.ts` 把守分层（contract=0、域=1、apply/index=2；import 只准指向 ≤ 自己的层级；兄弟域边即失败）。将来拆包=每个域目录升格为包+机械改写 import 路径。 +各领域实现文件不 import 兄弟领域；共享面统一经过 `contract/`。`scripts/verify-client-domain-graph.ts` 把守分层（contract=0、domain=1、apply/index=2；import 只准指向不高于自身的层级；兄弟领域依赖会失败）。Tool 展示已经拆为独立 `ui-tool` 包，只通过 ui-conversation 声明的 slot 到达 chat 与 details。 ## 怎么开发 @@ -122,5 +124,5 @@ token 流不再震荡渲染树：帧风暴对未订阅会话只花一个脏位 | 静态链接的单 SPA bundle | 插件必须由 host 在运行时按配置组合；单体把每个 UI 功能重新耦回一次构建 | | window 全局变量 / import map 供共享依赖 | DI require 表让共享显式、大声失败、可替换；全局变量静默泄漏身份与版本 | | 业务数据进 zustand 切片 | 事件窗口/累积器是行为状态机，不是扁平切片；对象层保住快照粒度与合批的可控性 | -| 工具行走字符串键的全局组件注册表 | per-view keyed 子槽 + 组件内会话分支以唯一注册模型承载同一需求；平行 registry 不复活（[toolview 溶解](2026-07-23-toolview-dissolution.md)） | +| Tool 行使用平行的字符串键组件注册表 | ui-tool 的 keyed 子 slot 通过唯一的 slot 注册模型承载运行时开放的 Tool 名称集合（[toolview 溶解](2026-07-23-toolview-dissolution.md)） | | P-I 就做渐进/Suspense 启动 | 一次成型严格更简单；loader 的按插件状态面已保留，渐进点亮日后可落地而无需重构 | diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml index 90d13fcfea..09f0c27732 100644 --- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md -2026-07-23-toolview-dissolution.md: 97d8beb4de43d9bc6348d942e5460d0321592b32 -2026-07-23-toolview-dissolution.zh.md: db93c6252d5d42d1fd85ce81ad430d95f4324cf2 +2026-07-23-toolview-dissolution.md: be1bd9d161714194855988d76a632c667fae8c84 +2026-07-23-toolview-dissolution.zh.md: afe5e03e8345fca2a0f097d86873974f6d417ff2 diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md index 97d8beb4de..be1bd9d161 100644 --- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md +++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md @@ -4,7 +4,7 @@ Status: implemented English | [中文](2026-07-23-toolview-dissolution.zh.md) -> Scope: why the standalone tool ring (ToolViewRegistry/ctx.toolviews/outlet) was retired and what replaced it. The [web client architecture note](2026-07-19-gui-web-client-architecture.md) carries the shipped-state narrative this decision produced; the [slot system standard](2026-07-22-slot-type-chain-implementation.md) owns the registration model everything now runs on. +> Scope: why the standalone tool ring (ToolViewRegistry/ctx.toolviews/outlet) was retired and what replaced it. The [web client architecture note](2026-07-19-gui-web-client-architecture.md) carries the shipped-state narrative this decision produced; the [slot system standard](2026-07-22-slot-type-chain-implementation.md) owns the registration model everything now runs on. The later [Client Tool presentation ownership](2026-08-08-client-tool-presentation-ownership.md) decision supersedes only this note's per-view placement: Tool-name dispatch remains a keyed slot rather than a parallel registry. ## Problem @@ -14,24 +14,22 @@ After the view ring dissolved into the slot system, the client kept exactly one The tool ring is gone as independent infrastructure: a tool row is a **keyed child slot each view declares for itself**, and the client has exactly one registration model. The justification above was hollow — a keyed slot's *key space* is already runtime-open (SlotMap declares slots, never keys; the ask-user composer's `key: 'question'` was the precedent), so the open tool-name set fits `entryKey` dispatch natively. -Shipped shape (current-state narrative also in the [architecture note](2026-07-19-gui-web-client-architecture.md)): the chat entry's `children` table declares `'conversation.chat.toolview'` (keyed/session); the render site dispatches per row via `entryKey: toolName` with `GenericToolCard` as the call-site `fallback` (the default card is domain property; the fallback option is ordinary renderSlot grammar). The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openDetails` — details being a session-level facility, not chat-private), and `ToolRowProps` pre-composes it with the session standard kit for registrant components. A registrant is a plain plugin using `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '', inject? }, Row))`; the declaration itself governs activation and replacement, without a false `ConversationService` edge ([decision](2026-08-05-slot-declaration-injection.md)). The bash sample is the third-party-posture exemplar and paints the same ToolRow chrome as Think (`Bash · {description}`). Trajectory/waterfall toolview slots share this exact shape (names fixed by the slot-naming discipline `..`, one shared owner type) and land with their own row render sites — RendersCheck rejects a declaration nobody renders, so the type system, not convention, blocks early empty declarations. - -Registry-era responsibilities all have successor homes: inject caching and row error isolation ride the framework renderer (entry×scope cache, per-entry `SlotErrorBoundary`); subscribe/getVersion ride the slot core's per-key version machinery; the future "store seat" is the ordinary store seat keyed slots already have (interaction-draft durability is its first named consumer); miss fallback is the call-site `fallback` option. +This decision originally placed `'conversation.chat.toolview'` under the chat entry and made the chat render site dispatch each row. The follow-up [Tool presentation ownership](2026-08-08-client-tool-presentation-ownership.md) moves that placement into a whole-Tool seat and gives `ui-tool` one keyed `'tool.call.toolview'` child slot. That follow-up changes the presentation owner, not this decision's core constraint: Tool registration continues to use ordinary keyed-slot machinery, with framework-owned activation, replacement, caching, error isolation, versioning, and fallback behavior. ## Accepted semantic changes -Four behavioral deltas were accepted deliberately, not overlooked. Cross-view appearance is per-view registration — a row must adapt to each view's layout anyway, so one registration per view is the correct coupling, and reuse is the same component in two register calls. Same-key double registration is a loud throw where the registry let later-wins silently override — a discipline correction, not a loss. Session-dimension dispatch, when a row needs it, belongs inside the component (the standard kit already carries `useSessions`), not in registry predicates — there is no shipped session-variant exemplar today. Registry-level shape override by third parties (a scoped registration shadowing a global one) has no equivalent; a real future need routes through key-naming conventions or a small in-component resolver, never a revived parallel registry. +Four behavioral deltas were accepted deliberately, not overlooked. Cross-view appearance was initially per-view registration; the follow-up note records why root/subcall composition later justified one Tool-wide presentation owner. Same-key double registration is a loud throw where the registry let later-wins silently override — a discipline correction, not a loss. Session-dimension dispatch, when a row needs it, belongs inside the component (the standard kit already carries `useSessions`), not in registry predicates — there is no shipped session-variant exemplar today. Registry-level shape override by third parties (a scoped registration shadowing a global one) has no equivalent; a real future need routes through key-naming conventions or a small in-component resolver, never a revived parallel registry. ## Alternatives considered -**Keep the standalone registry (the original shape).** Rejected: each of its multi-dimensional dispatch axes has a more correct home — the view dimension belongs to each view's own declared child slot (declaring is claiming, so specialization ownership lands right), and the session dimension belongs inside the component, which already holds the standard kit. What remained after both moves was a second copy of slot machinery with no distinguishing capability. +**Keep the standalone registry (the original shape).** Rejected: each of its multi-dimensional dispatch axes has a more correct home — presentation ownership belongs to an explicitly declared child slot, and the session dimension belongs inside the component, which already holds the standard kit. What remains is a second copy of slot machinery with no distinguishing capability. -**Promote `renderToolView` into the standard kit and move the registry into the runtime package.** Rejected: "tool row" is a conversation-domain concept; hoisting it into runtime would leak a domain vocabulary into the framework layer and still leave two registration models. +**Promote `renderToolView` into the standard kit and move the registry into the runtime package.** Rejected: Tool presentation is Client UI vocabulary; hoisting it into runtime would leak presentation into the data object layer and still leave two registration models. **Derive slot declarations from subscription refCounts** (declare the slot implicitly when the first registrant subscribes). Rejected for implicit coupling and debounce complexity; noted as a possible revisit only if a genuinely multi-viewer surface appears. -**A thin `registerToolView` facade over slots.register.** Deferred, not rejected: after dissolution the facade would carry only compile-time sugar (slot-name literal narrowing, tool→key vocabulary, props pre-composition) with zero runtime. Per "enforce at the operation boundary" (a facade is not an enforcement point) and "don't split preemptively" (today's registrant population is one bash sample), it stays unbuilt; the type sugar ships as the exported `ToolRowProps` alias. Regret clause: if registrants grow to three-to-five or a bulk-registration pattern appears, the facade is ten lines added without disturbing direct registration. +**A thin `registerToolView` facade over slots.register.** Deferred, not rejected: after dissolution the facade would carry only compile-time sugar (slot-name literal narrowing, tool→key vocabulary, props pre-composition) with zero runtime. Per "enforce at the operation boundary" (a facade is not an enforcement point), it stays unbuilt; the useful type composition ships as the exported Tool view props alias. A later facade can be added without disturbing direct registration if repeated registration ceremony justifies it. ## Consequences -The client has one registration model; auditing who renders tool rows = reading register calls, the same audit as every other slot. Registrants get the framework's error isolation, inject caching, and store seat for free — no capability ships twice. The costs are the accepted semantic changes above (chiefly: per-view registration for cross-view rows, and no third-party registry-level override). Independent registrants name the typed slot in `ctx.slots.inject`, so the dependency is explicit and follows declaration replacement without a service-order convention. +The client has one registration model; auditing who renders Tool calls means reading slot register calls, the same audit as every other slot. Registrants get the framework's error isolation, inject caching, and store seat for free — no capability ships twice. The costs are the accepted semantic changes above, chiefly loud duplicate-key failure and no third-party registry-level override. Independent registrants name the typed slot in `ctx.slots.inject`, so the dependency is explicit and follows declaration replacement without a service-order convention. diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md index db93c6252d..afe5e03e83 100644 --- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md @@ -4,7 +4,7 @@ Status: implemented [English](2026-07-23-toolview-dissolution.md) | 中文 -> 范围：独立工具环（ToolViewRegistry/ctx.toolviews/outlet）为何退役、被什么取代。本决策产出的落地态叙述归 [Web 客户端架构注](2026-07-19-gui-web-client-architecture.md)；一切现在所运行其上的注册模型归 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 所有。 +> 范围：独立工具环（ToolViewRegistry/ctx.toolviews/outlet）为何退役、被什么取代。本决策产出的落地态叙述归 [Web 客户端架构注](2026-07-19-gui-web-client-architecture.md)；一切现在所运行其上的注册模型归 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md)所有。后续的 [Client Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)决策仅取代本篇的 per-view 放置方式：Tool 名称分发仍使用 keyed slot，而非平行注册表。 ## Problem @@ -14,24 +14,22 @@ Status: implemented 工具环作为独立基础设施已消失：工具行是**各视图为自己声明的 keyed 子槽**，client 全域只剩一种注册模型。上述理由是空的——keyed slot 的 *key 空间*本就运行时开放（SlotMap 声明槽、从不声明 key；ask-user composer 的 `key: 'question'` 即先例），开放的 tool 名集合天然适配 `entryKey` 分发。 -落地形态（现状叙述同见[架构注](2026-07-19-gui-web-client-architecture.md)）：chat 条目的 `children` 表声明 `'conversation.chat.toolview'`（keyed/session）；渲染点逐行以 `entryKey: toolName` 分发、以 `GenericToolCard` 作调用点 `fallback`（默认卡片是域产权；fallback 选项就是普通 renderSlot 文法）。owner 载荷是统一的 `ToolRowOwnerProps`（`callId`/`toolName`/`block`/`openDetails`——details 是会话级设施，非 chat 私货），`ToolRowProps` 把它与 session 标配 kit 预组合供注册方组件取用。注册方是使用 `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '', inject? }, Row))` 的普通插件；声明本身控制激活与替换，不再引入虚假的 `ConversationService` 依赖（[决策](2026-08-05-slot-declaration-injection.md)）。bash 样例即第三方姿态的样板，并与 Think 绘制同一套 ToolRow chrome（`Bash · {description}`）。trajectory/waterfall 的 toolview 槽共用这套形状（槽名按槽名纪律 `<域>.<条目>.<孔位>` 定死，共用一张 owner 类型），随各自的行渲染点落地——RendersCheck 拒绝无人渲染的声明，挡住提前空声明的是类型系统而非约定。 - -registry 时代的职责各有后继居所：inject 缓存与行错误隔离乘框架渲染器（entry×scope 缓存、per-entry `SlotErrorBoundary`）；subscribe/getVersion 乘 slot core 的 per-key 版本机；将来的「store 席位」就是 keyed slot 本就拥有的普通 store 席位（交互草稿耐久性是其首个具名消费者）；miss 兜底即调用点 `fallback` 选项。 +本决策最初把 `'conversation.chat.toolview'` 放在 chat 条目下，由 chat 渲染点逐行分发。后续的 [Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)引入整体 Tool 席位，并让 `ui-tool` 拥有唯一的 keyed `'tool.call.toolview'` 子 slot。后续决策改变的是展示所有者，而非本决策的核心约束：Tool 注册继续使用普通 keyed-slot 机制，激活、替换、缓存、错误隔离、版本与 fallback 行为仍归框架所有。 ## 接受的语义变化 -四项行为增量是刻意接受而非疏漏。跨视图出场=逐视图注册——行本须适配各视图版式，一视图一注册是正确耦合，复用即同一组件写两次 register。同 key 重复注册从注册表的 later-wins 静默覆盖变为 loud throw——纪律修正而非损失。会话维分发若行需要，归组件内部（标配 kit 已带 `useSessions`），不走注册表谓词——今天没有已落地的会话变体样例。第三方在 registry 级覆盖形态（scoped 注册压过 global）不复存在；真出现的未来需求走 key 命名空间约定或组件内小 resolver，永不复活平行注册表。 +四项行为增量是刻意接受而非疏漏。跨视图出场最初采用逐视图注册；后续 Note 记录了 root/subcall 编排为何足以支持一个 Tool 级展示所有者。同 key 重复注册从注册表的 later-wins 静默覆盖变为 loud throw——纪律修正而非损失。会话维分发若行需要，归组件内部（标配 kit 已带 `useSessions`），不走注册表谓词——今天没有已落地的会话变体样例。第三方在 registry 级覆盖形态（scoped 注册压过 global）不复存在；真出现的未来需求走 key 命名空间约定或组件内小 resolver，永不复活平行注册表。 ## Alternatives considered -**保留独立注册表（原形态）。** 拒绝：其多维分发的每一维都有更正确的家——视图维归各视图自己声明的子槽（declaring is claiming，特化面权属自然落对），会话维归已持有标配 kit 的组件内部。两步移完后剩下的只是一份没有任何独有能力的 slot 机器副本。 +**保留独立注册表（原形态）。** 拒绝：其多维分发的每一维都有更正确的家——展示所有权归显式声明的子 slot，会话维归已持有标配 kit 的组件内部。两步移完后剩下的只是一份没有任何独有能力的 slot 机器副本。 -**把 `renderToolView` 提进标配 kit、注册表迁入 runtime 包。** 拒绝：「工具行」是 conversation 域概念；上提进 runtime 会把域词汇泄漏进框架层，且依然留着两套注册模型。 +**把 `renderToolView` 提进标配 kit、注册表迁入 runtime 包。** 拒绝：Tool 展示是 Client UI 词汇；上提进 runtime 会把展示概念泄漏进数据对象层，且依然留着两套注册模型。 **以订阅 refCount 推导槽声明**（首个注册方订阅时隐式声明槽）。拒绝：隐式耦合加去抖复杂度；记为将来真出现多观看面时的备选。 -**slots.register 之上的薄 `registerToolView` 门面。** 缓建而非拒绝：溶解后该门面只剩编译期三糖（槽名字面量收窄、tool→key 词汇翻译、props 预组合），运行时为零。按「enforce at the operation boundary」（门面不是强制点）与「don't split preemptively」（今天注册方人口只有一个 bash 样例）保持不建；类型糖以导出的 `ToolRowProps` 别名兑现。后悔药条款：注册方长到三五家或出现批量注册模式时，门面十行可补，不扰直注。 +**slots.register 之上的薄 `registerToolView` 门面。** 缓建而非拒绝：溶解后该门面只剩编译期语法糖（slot 名字面量收窄、tool→key 词汇翻译、props 预组合），运行时为零。按「enforce at the operation boundary」（门面不是强制点）保持不建；有用的类型组合以导出的 Tool view props 别名兑现。若重复注册仪式今后足以证明其价值，可在不扰动直接注册的前提下补充门面。 ## Consequences -client 只有一种注册模型；审计谁渲染工具行 = 读 register 调用，与其他所有 slot 同一套审计。注册方免费获得框架的错误隔离、inject 缓存与 store 席位——没有能力要建两遍。代价即上文接受的语义变化（主要是：跨视图行要逐视图注册、第三方无 registry 级覆盖）。独立注册方在 `ctx.slots.inject` 中点名有类型约束的 slot，因此依赖关系既显式，又能跟随声明替换，无需服务顺序约定。 +client 只有一种注册模型；审计谁渲染 Tool 调用就是读 slot register 调用，与其他所有 slot 同一套审计。注册方免费获得框架的错误隔离、inject 缓存与 store 席位——没有能力要建两遍。代价即上文接受的语义变化，主要是重复 key 会 loud failure，且第三方无 registry 级覆盖。独立注册方在 `ctx.slots.inject` 中点名有类型约束的 slot，因此依赖关系既显式，又能跟随声明替换，无需服务顺序约定。 diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml new file mode 100644 index 0000000000..47adf75d40 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md +2026-08-08-client-tool-presentation-ownership.md: 4d06450a10c4198f20d7139aef815def9e7cb362 +2026-08-08-client-tool-presentation-ownership.zh.md: 3d3bf3bc3204aca6871a82c7b7ae330b6381a3e4 diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md new file mode 100644 index 0000000000..4d06450a10 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md @@ -0,0 +1,103 @@ +# Agent Note: Client Tool presentation ownership + +Status: implemented + +English | [中文](2026-08-08-client-tool-presentation-ownership.zh.md) + +## Problem + +The Client Runtime already projects Tool calls into a stable lifecycle: it pairs call/result events by `callId`, preserves running and settled forms, and indexes Code Dispatch children by their root call. The chat view nevertheless owned the entire presentation stack. It placed root calls in ChatFlow, composed each root with its subcalls, dispatched every atomic call by Tool name, carried the generic fallback and card models, registered first-party Tool views, and reused those models in the details panel. + +That ownership made `ui-conversation` interpret business Tool names and made subcalls an orphaned concern if an atomic Tool view moved elsewhere. A business package such as `ui-skill` could register a row, but it still depended on conversation's Tool-specific composition contract. Adding Tool-specific Session projection would duplicate a data model the Runtime already owns, while moving only individual React components would leave the composition and model coupling in place. + +## Decision + +Tool is a first-class Client UI concept with one presentation owner, `@deepseek-ai/dsh-client-ui-tool`. Session Event, projection, fold, `ConversationSnapshot` construction and caching, historical paging, and Code Dispatch indexing remain unchanged. + +“First-class concept” describes UI ownership only; it adds no Runtime data kind. `ConversationNode` remains the transcript projection, `ChatFlowItem` remains the render unit produced when conversation sorts and groups nodes, `ToolCallBlock` remains the standard data for one call, and `ToolCallTree` only composes root/subcall presentation within Tool. Command continues to render through the separate `'conversation.chat.commandview'` seat and does not become Tool. + +`ui-conversation` owns ordered placement. `deriveChatFlow()` still decides where a settled Tool group appears, and `ChatView` still appends running calls, maintains scroll anchors and selection, and supplies host actions. For each root call it renders the single/session `'conversation.chat.tool'` seat with the root block, selected call id, session cwd, and open-file/inspect callbacks. It does not read Code Dispatch children, branch on Tool names, or import Tool-specific views and card models. + +`ui-tool` occupies that whole-Tool seat. Through its standard session slot props, `ToolCallTree` selects the Runtime-projected `codeDispatches[rootCallId]` array, renders the root followed by that one currently supported child level, and routes both forms through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. This is deliberately one-level composition, not a claim that the Runtime supports an arbitrary recursive call graph. + +Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this seam. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently. + +The details panel is a second Tool presentation site but not a call-tree owner. `ui-conversation` delegates its selected output body through the single/session `'conversation.details.tool'` seat; `ui-tool` renders the card-aware output and the seat fallback preserves raw result text when the plugin is absent. Card models therefore have one production owner without introducing a reverse implementation import. + +The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch stays a top-level official concept because it changes `codeDispatches` and parent/child identity; ordinary Tool business differences stay at the keyed presentation seam. This package boundary does not add a Tool projector/fold registry. + +## Runtime and render path + +This boundary starts at the Client's `ConversationSnapshot`; the full render path is: + +```text +ConversationSnapshot.nodes + -> deriveChatFlow() + -> settled tool-group positions ----+ + | +ConversationSnapshot.runningCalls | + -> ChatView flow tail ---------------+-> ToolSeat + -> conversation.chat.tool + -> ToolCallTree +ConversationSnapshot.codeDispatches[rootCallId] -+ + +-> root ToolCall + one-level child ToolCall + -> tool.call.toolview(entryKey = toolName) + |- registered atomic view + `- GenericToolCard fallback +``` + +The live Session's [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) caches arrays or maps such as `nodes`, `runningCalls`, and `codeDispatches` against independent revisions. Their references stay stable when the corresponding business state has not changed, allowing React selectors and memoization to skip unrelated updates. The historical projection's [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) reconstructs the same running-call and Code Dispatch shapes from entries in its window. Tool UI consumes the snapshot shapes already unified by those paths; presentation packages do not repeat call/result pairing, historical replay, or cache indexing. + +[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) reruns [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts) only when the `nodes` reference changes. It groups consecutive settled Tool results into a `tool-group`, while running root calls append at the flow tail. Both paths ultimately enter the same `ToolSeat`, so settled and running forms share the whole-Tool seat. `ToolCallTree` selects only the current root's `codeDispatches[rootCallId]`; it does not introduce a business projector for presentation of other roots. + +## Code and responsibility boundaries + +| Owner | Primary code | Owns | Explicitly does not own | +|---|---|---|---| +| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts), [`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result pairing, running/settled lifecycle, Code Dispatch parent/child index, snapshot reference stability | Business views selected by Tool name | +| `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts), [`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx), [`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow order, settled groups, running tail, scroll anchors, selection and host actions, whole-Tool seat declaration | subcall composition, `toolName` dispatch, Generic fallback, Tool card models | +| `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts), [`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx), [`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall composition, atomic keyed dispatch, Generic fallback, Tool card models and built-in Tool views | ChatFlow ordering, Session Event fold | +| Business Tool plugins | [`ui-skill` registration example](../../../../packages/client/ui-skill/src/client/index.ts) | Atomic views for one or more wire Tool names | root/subcall placement and lifecycle pairing | +| Details path | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx), [`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected-call lookup, card-aware output, and raw fallback | chat call-tree composition | + +## Slot and owner contract + +A slot declaration also constrains render ownership. The conversation chat entry declares `'conversation.chat.tool'` through `children`, so only `ChatView` places the whole-Tool seat. When `ui-tool` registers that seat, its `children` declares `'tool.call.toolview'`, so only `ToolCallTree` renders the atomic Tool seat. Business plugins register keyed entries only; they neither participate in root/subcall composition nor establish a registry parallel to slots. + +The whole seat's `ToolTreeOwnerProps` carries the root `callId`, `toolName`, `ToolCallBlock`, `selectedCallId`, session `cwd`, `openFile(path)`, and `inspectCall(callId)`. `ToolCallTree` converts either a root or child into the same `ToolCallOwnerProps` and narrows inspect to a callback for that call. The atomic owner carries no `ReactNode`, Cordis `Context`, Session service, or projector; a business view consumes only one standard call block and host actions. + +Business plugins use one registration shape: + +```text +ctx.slots.inject('tool.call.toolview', () => + ctx.slots.register({ + name: 'tool.call.toolview', + key: '', + }, BusinessToolRow)) +``` + +`ui-tool`'s [`apply()`](../../../../packages/client/ui-tool/src/client/apply.ts) registers the whole-Tool renderer, details renderer, and existing built-in atomic views. An existing independent business package can move only its keyed registration, as `ui-skill` does, without changing `ui-conversation` or Session. + +## Details path + +[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) still locates the selected call in `nodes`, `runningCalls`, and `codeDispatches`, and it owns input arguments, empty states, and panel lifecycle. It passes only `{ block, cwd }` to `'conversation.details.tool'`; [`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) reuses Tool card models to render the output. When `ui-tool` is absent, a settled call falls back to raw result text and a running call shows conversation's running fallback, so details never imports the Tool implementation in reverse. + +## Verification + +Test ownership follows production ownership. `ui-conversation` tests install a local whole-Tool seat probe and assert only ChatFlow placement, owner payload, and host contracts such as selection, open-file, and inspect; they do not import `ui-tool` production code or test helpers. `ui-tool` tests mount a real conversation host and verify root/subcall composition, keyed dispatch, generic fallback, concrete Tool UI, and plugin lifecycle. + +## Alternatives considered + +**Keep atomic Tool slots under every conversation view.** Rejected: each view would have to reproduce root/subcall composition, and a Tool registration would be isolated by view even though its business meaning is Tool-wide. A whole-Tool seat preserves view-owned placement while giving the call tree one owner. This supersedes the per-view placement selected by the earlier [toolview dissolution](2026-07-23-toolview-dissolution.md), while retaining its keyed-slot and no-parallel-registry decisions. + +**Move only the Tool React components and card models.** Rejected: `ChatView` would still own Tool-name dispatch and Code Dispatch composition, so the dependency would change file paths without changing responsibility. + +**Add business-specific Session projectors or folds.** Rejected: ordinary Tool views consume the standard call block already reconstructed by Runtime. A second registry would create two authorities for call identity and historical replay. Only a feature that changes logged topology or lifecycle earns a Runtime-level extension. + +**Make each atomic Tool view render its own subcalls recursively.** Rejected: the atomic registrant receives one Tool call and should not know whether it is a root or child. Root/child composition belongs to `ui-tool`, and the current wire/runtime shape only supports one Code Dispatch child level. + +**Import `ui-tool` components directly from `ui-conversation`.** Rejected: it would reverse the intended feature direction and make Tool presentation mandatory. Declared slots retain lifecycle ownership, fallback behavior, and independent plugin loading. + +## Consequences + +`ui-conversation` becomes independent of Tool-name business presentation while retaining ChatFlow, selection, and host interaction responsibilities. Root calls and subcalls cannot drift onto different dispatch paths, and business packages can own atomic Tool presentation without Session changes. The cost is one new Client package and two cross-package slot seams; `ui-tool` also deliberately depends on conversation's declared seats and locale namespace. The assembled Web bundle therefore mounts `ui-tool`; omitting it leaves chat Tool seats empty while the details seat keeps its raw-result fallback, without changing Session reconstruction. diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md new file mode 100644 index 0000000000..3d3bf3bc32 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md @@ -0,0 +1,103 @@ +# Agent Note: Client Tool 展示所有权 + +Status: implemented + +[English](2026-08-08-client-tool-presentation-ownership.md) | 中文 + +## Problem + +Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。 + +这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排契约。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。 + +## Decision + +Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Session Event、projection、fold、`ConversationSnapshot` 构建与缓存、历史分页及 Code Dispatch 索引保持不变。 + +这里的“一级概念”只描述 UI 所有权，不增加 Runtime 数据种类。`ConversationNode` 仍是 transcript projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。 + +`ui-conversation` 拥有有序放置。`deriveChatFlow()` 仍决定 settled Tool group 在哪里出现，`ChatView` 仍追加 running call、维护滚动 anchor 与 selection，并提供宿主动作。对于每个 root call，它使用 root block、selected call id、session cwd 以及 open-file/inspect 回调渲染 single/session 的 `'conversation.chat.tool'` 席位。它不读取 Code Dispatch child、不按 Tool 名称分支，也不导入 Tool 专属 view 或 card model。 + +`ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，先渲染 root，再渲染当前支持的一层 child；两种调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。这里刻意只编排一层，并不声称 Runtime 已支持任意递归调用图。 + +业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。 + +details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。 + +Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 会改变 `codeDispatches` 与 parent/child identity，因此继续作为官方顶级概念；普通 Tool 业务差异停留在 keyed 展示 seam。这个包边界不会增加 Tool projector/fold registry。 + +## Runtime 与渲染链路 + +这项边界从 Client 的 `ConversationSnapshot` 开始，完整渲染链路如下： + +```text +ConversationSnapshot.nodes + -> deriveChatFlow() + -> settled tool-group positions ----+ + | +ConversationSnapshot.runningCalls | + -> ChatView flow tail ---------------+-> ToolSeat + -> conversation.chat.tool + -> ToolCallTree +ConversationSnapshot.codeDispatches[rootCallId] -+ + +-> root ToolCall + one-level child ToolCall + -> tool.call.toolview(entryKey = toolName) + |- registered atomic view + `- GenericToolCard fallback +``` + +Live Session 的 [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 按独立 revision 缓存 `nodes`、`runningCalls`、`codeDispatches` 等数组或 map；没有对应业务变化时，它们保持引用稳定，供 React selector 与 memo 跳过无关更新。历史 projection 的 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 从窗口内 entry 重建相同的 running call 与 Code Dispatch 形态。Tool UI 直接消费这两个路径已经统一的 snapshot，不在展示包中重复 call/result 配对、历史 replay 或缓存索引。 + +[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。`ToolCallTree` 只选择当前 root 的 `codeDispatches[rootCallId]`，不会因其他 root 的展示逻辑引入业务 projector。 + +## 代码与职责边界 + +| 所有者 | 主要代码 | 拥有的责任 | 明确不拥有 | +|---|---|---|---| +| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、Code Dispatch parent/child 索引、snapshot 引用稳定性 | Tool 名称对应的业务视图 | +| `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)、[`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx)、[`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow 顺序、settled group、running tail、scroll anchor、selection 与宿主动作、整体 Tool 席位声明 | subcall 组合、按 `toolName` 分发、Generic fallback、Tool card model | +| `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts)、[`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx)、[`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall 组合、原子 keyed dispatch、Generic fallback、Tool card model 与内置 Tool view | ChatFlow 排序、Session Event fold | +| 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 | +| details 路径 | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx)、[`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected call 定位、card-aware output 与 raw fallback | chat 调用树编排 | + +## Slot 与 owner 契约 + +slot 声明同时限定渲染所有权。conversation chat entry 通过 `children` 声明 `'conversation.chat.tool'`，因此只有 `ChatView` 放置整体 Tool 席位；`ui-tool` 注册该席位时再通过 `children` 声明 `'tool.call.toolview'`，因此只有 `ToolCallTree` 渲染原子 Tool 席位。业务插件只注册 keyed entry，不参与 root/subcall 编排，也不建立与 slot 平行的 registry。 + +整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。 + +业务插件遵循同一个注册形态： + +```text +ctx.slots.inject('tool.call.toolview', () => + ctx.slots.register({ + name: 'tool.call.toolview', + key: '', + }, BusinessToolRow)) +``` + +`ui-tool` 的 [`apply()`](../../../../packages/client/ui-tool/src/client/apply.ts) 注册整体 Tool renderer、details renderer 与现有内置原子 view；已有独立业务包可以像 `ui-skill` 一样只迁走自己的 keyed 注册，无需改动 `ui-conversation` 或 Session。 + +## Details 路径 + +[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) 仍从 `nodes`、`runningCalls` 与 `codeDispatches` 中定位选中的 call，并拥有 input 参数、空态和面板生命周期。它只把 `{ block, cwd }` 交给 `'conversation.details.tool'`；[`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) 复用 Tool card model 渲染 output。`ui-tool` 缺席时，settled call 回退为 raw result text，running call 显示 conversation 的 running fallback，因此 details 不反向导入 Tool 实现。 + +## Verification + +测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主契约；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。 + +## Alternatives considered + +**在每个 conversation view 下保留原子 Tool slot。** 拒绝：每个 view 都必须重复 root/subcall 编排，而且 Tool 注册会按 view 隔离，即使它的业务语义本应是 Tool 级。整体 Tool 席位保留 view 对放置位置的所有权，同时让调用树只有一个所有者。它取代了早期 [toolview 溶解](2026-07-23-toolview-dissolution.md)所选择的 per-view 放置方式，但保留 keyed slot 与不设平行 registry 的决策。 + +**只移动 Tool React 组件与 card model。** 拒绝：`ChatView` 仍会拥有 Tool 名称分发与 Code Dispatch 编排，只是改变文件路径，没有改变责任。 + +**增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的能力才应获得 Runtime 级扩展。 + +**让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。root/child 编排归 `ui-tool`，且当前 wire/runtime 形态只支持一层 Code Dispatch child。 + +**让 `ui-conversation` 直接导入 `ui-tool` 组件。** 拒绝：这会反转预期的 feature 依赖方向，并把 Tool 展示变成必选能力。声明式 slot 能保留生命周期所有权、fallback 行为与独立插件装载。 + +## Consequences + +`ui-conversation` 不再依赖 Tool 名称对应的业务展示，同时保留 ChatFlow、selection 与宿主交互责任。root call 与 subcall 不会漂移到不同分发路径，业务包无需修改 Session 即可拥有原子 Tool 展示。代价是新增一个 Client package 与两个跨包 slot seam；`ui-tool` 也明确依赖 conversation 声明的席位与 locale namespace。因此组装后的 Web bundle 会挂载 `ui-tool`；省略该插件时，chat Tool 席位为空，details 席位则保留 raw-result fallback，且 Session 重建不受影响。 From cd64cc7ecdd955ee77bc1c67cf6a36bcd1043770 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 8 Aug 2026 15:19:40 +0800 Subject: [PATCH 04/17] docs(notes): update Tool UI implementation references --- .../2026-08-05-context-meter-blind-to-compaction.i18n.yaml | 4 ++-- .../bug-fix/2026-08-05-context-meter-blind-to-compaction.md | 2 +- .../2026-08-05-context-meter-blind-to-compaction.zh.md | 2 +- .../feature/2026-07-23-web-todo-display.i18n.yaml | 4 ++-- .../implemented/feature/2026-07-23-web-todo-display.md | 2 +- .../implemented/feature/2026-07-23-web-todo-display.zh.md | 2 +- .../2026-07-26-code-mode-chat-subcall-rows.i18n.yaml | 4 ++-- .../feature/2026-07-26-code-mode-chat-subcall-rows.md | 2 +- .../feature/2026-07-26-code-mode-chat-subcall-rows.zh.md | 2 +- .../feature/2026-07-28-web-terminal-card.i18n.yaml | 4 ++-- .../implemented/feature/2026-07-28-web-terminal-card.md | 4 ++-- .../implemented/feature/2026-07-28-web-terminal-card.zh.md | 4 ++-- .../2026-07-29-ask-question-web-presentation.i18n.yaml | 4 ++-- .../feature/2026-07-29-ask-question-web-presentation.md | 2 +- .../feature/2026-07-29-ask-question-web-presentation.zh.md | 2 +- .../implemented/feature/2026-07-30-web-diff-card.i18n.yaml | 4 ++-- .../notes/implemented/feature/2026-07-30-web-diff-card.md | 4 ++-- .../implemented/feature/2026-07-30-web-diff-card.zh.md | 4 ++-- .../feature/2026-07-30-web-read-card-frontend.i18n.yaml | 4 ++-- .../feature/2026-07-30-web-read-card-frontend.md | 4 ++-- .../feature/2026-07-30-web-read-card-frontend.zh.md | 4 ++-- .../feature/2026-07-30-web-result-card-frontend.i18n.yaml | 4 ++-- .../feature/2026-07-30-web-result-card-frontend.md | 4 ++-- .../feature/2026-07-30-web-result-card-frontend.zh.md | 4 ++-- .../feature/2026-07-30-web-search-card.i18n.yaml | 4 ++-- .../notes/implemented/feature/2026-07-30-web-search-card.md | 6 +++--- .../implemented/feature/2026-07-30-web-search-card.zh.md | 6 +++--- ...-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml | 4 ++-- .../2026-07-30-web-tool-row-unified-expand-and-inspect.md | 4 ++-- ...2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md | 4 ++-- .../feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml | 4 ++-- .../feature/2026-08-02-web-thinking-tail-scroll.md | 2 +- .../feature/2026-08-02-web-thinking-tail-scroll.zh.md | 2 +- .../feature/2026-08-03-web-search-source-scroll.i18n.yaml | 4 ++-- .../feature/2026-08-03-web-search-source-scroll.md | 2 +- .../feature/2026-08-03-web-search-source-scroll.zh.md | 2 +- .../feature/2026-08-06-web-skill-tool-row.i18n.yaml | 4 ++-- .../implemented/feature/2026-08-06-web-skill-tool-row.md | 2 +- .../implemented/feature/2026-08-06-web-skill-tool-row.zh.md | 2 +- 39 files changed, 66 insertions(+), 66 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml index 3d9fef5b34..dfaaea4ab7 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.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/bug-fix/2026-08-05-context-meter-blind-to-compaction.md -2026-08-05-context-meter-blind-to-compaction.md: ab39ae4e109f238960fd60de5e5b61075344f525 -2026-08-05-context-meter-blind-to-compaction.zh.md: c93aa509530e48acf906b18ba85bab4c7d355d69 +2026-08-05-context-meter-blind-to-compaction.md: 8f4845c3c9bf52c5c3a2d39dee2ff25bda30c7bd +2026-08-05-context-meter-blind-to-compaction.zh.md: 94ada0a9118db63876d5805ef5a8197d9c764102 diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md index ab39ae4e10..8f4845c3c9 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md +++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md @@ -43,4 +43,4 @@ The panel's composition rows still do not sum to the header, and now for one cle ## Testing -`packages/llm/token-meter/tests/token-usage-projection.spec.ts` covers the carry-forward across surface growth and a compaction (the sample holding still while the projection shrinks) and the zero clamp when heuristic error would drive the figure negative. `packages/client/ui-conversation/tests/context-meter.spec.tsx` pins the ring reading the projected figure, and `chat-stats-bash-sample.spec.tsx` pins `contextOccupancy`'s preference and its fallback. The end-to-end numbers above came from driving `BasicCompactService.compactNow` through a real `AgentLoop` with the projection registry mounted. +`packages/llm/token-meter/tests/token-usage-projection.spec.ts` covers the carry-forward across surface growth and a compaction (the sample holding still while the projection shrinks) and the zero clamp when heuristic error would drive the figure negative. `packages/client/ui-conversation/tests/context-meter.spec.tsx` pins the ring reading the projected figure, and `chat-stats.spec.tsx` pins `contextOccupancy`'s preference and its fallback. The end-to-end numbers above came from driving `BasicCompactService.compactNow` through a real `AgentLoop` with the projection registry mounted. diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md index c93aa50953..94ada0a911 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md @@ -43,4 +43,4 @@ AFTER compact: ring=4% header=~4227/100000 rows=[system 18, tools 0, messag ## 测试 -`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 覆盖了样本在表层增长与一次压缩上的推进（样本保持不动而投影值缩小），以及启发式误差会把数字压到负数时的零钳制。`packages/client/ui-conversation/tests/context-meter.spec.tsx` 钉住圆环读取投影值这一点，`chat-stats-bash-sample.spec.tsx` 钉住 `contextOccupancy` 的优先级与回退。上面那组端到端数字来自在挂载了投影注册表的真实 `AgentLoop` 上驱动 `BasicCompactService.compactNow`。 +`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 覆盖了样本在表层增长与一次压缩上的推进（样本保持不动而投影值缩小），以及启发式误差会把数字压到负数时的零钳制。`packages/client/ui-conversation/tests/context-meter.spec.tsx` 钉住圆环读取投影值这一点，`chat-stats.spec.tsx` 钉住 `contextOccupancy` 的优先级与回退。上面那组端到端数字来自在挂载了投影注册表的真实 `AgentLoop` 上驱动 `BasicCompactService.compactNow`。 diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml index cc872a60c3..f90cfe79db 100644 --- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.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-23-web-todo-display.md -2026-07-23-web-todo-display.md: 9e6e4914cd24d1db9271baa3d3fb6fdc56a9ac65 -2026-07-23-web-todo-display.zh.md: 5a5ac554b37c255a7d8c1ce821ebeb1b3f9f091f +2026-07-23-web-todo-display.md: bb66ef8512badea090b3b22030eef3f43f3b1119 +2026-07-23-web-todo-display.zh.md: 7270874d1e96bb0a553d57ba24b3bc2bb38a7a71 diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md index 9e6e4914cd..bb66ef8512 100644 --- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md +++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md @@ -22,7 +22,7 @@ The panel mounts through the `conversation.input.dock` slot (a plain registrant ### TodoRow: the per-call row through the keyed toolview slot -The dedicated `todo_write` chat row is a plain registrant plugin (`todoToolview`, mounted from `apply`) that registers into the keyed `conversation.chat.toolview` slot through `ctx.slots.inject`, the same declaration-lifetime posture as the bash sample but a product registration. The summary derives from call args (`N/M done · first active item`, with a `+` count of the other active ones in `ToolRow`'s non-shrinking `summarySuffix` slot); unparseable args fall back to the generic row summary; clicking opens the details column with the raw args. No `ToolEventView` is added for todo — presentation is client-owned, and the durable list renders from the session event, not the tool card. +The dedicated `todo_write` chat row is a plain registrant plugin (`todoToolview`, mounted from `apply`) that registers into the keyed `tool.call.toolview` slot through `ctx.slots.inject`, the same declaration-lifetime posture as the bash sample but a product registration. The summary derives from call args (`N/M done · first active item`, with a `+` count of the other active ones in `ToolRow`'s non-shrinking `summarySuffix` slot); unparseable args fall back to the generic row summary; clicking opens the details column with the raw args. No `ToolEventView` is added for todo — presentation is client-owned, and the durable list renders from the session event, not the tool card. ## Alternatives considered diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md index 5a5ac554b3..7270874d1e 100644 --- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md +++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md @@ -22,7 +22,7 @@ Status: implemented ### TodoRow：经 keyed toolview slot 的逐调用行 -专用的 `todo_write` 对话行是一个普通注册者插件（`todoToolview`，由 `apply` 挂载），经 `ctx.slots.inject` 注册进 keyed 的 `conversation.chat.toolview` slot，遵循与 bash 样例相同的声明生命周期，但属产品级注册。摘要由调用 args 推导（`N/M done · first active item`，其余活跃项的 `+` 计数放在 `ToolRow` 的不收缩 `summarySuffix` 位里）；无法解析的 args 回退到通用行摘要；点击会以原始 args 打开 details 列。todo 不新增任何 `ToolEventView`——呈现归客户端所有，常驻列表从会话事件渲染，而非工具卡。 +专用的 `todo_write` 对话行是一个普通注册者插件（`todoToolview`，由 `apply` 挂载），经 `ctx.slots.inject` 注册进 keyed 的 `tool.call.toolview` slot，遵循与 bash 样例相同的声明生命周期，但属产品级注册。摘要由调用 args 推导（`N/M done · first active item`，其余活跃项的 `+` 计数放在 `ToolRow` 的不收缩 `summarySuffix` 位里）；无法解析的 args 回退到通用行摘要；点击会以原始 args 打开 details 列。todo 不新增任何 `ToolEventView`——呈现归客户端所有，常驻列表从会话事件渲染，而非工具卡。 ## 考虑过的替代方案 diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml index 9086e891db..d550ad1fb6 100644 --- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.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-26-code-mode-chat-subcall-rows.md -2026-07-26-code-mode-chat-subcall-rows.md: 7d666f0a9e4b8bdb9bd6f5d0d0984fee0c4b21e2 -2026-07-26-code-mode-chat-subcall-rows.zh.md: b6b7de6c34673a0a0fa801681d642067a324d4cd +2026-07-26-code-mode-chat-subcall-rows.md: dc09e8fda9dbfb156b6218dec67584ee7bfead75 +2026-07-26-code-mode-chat-subcall-rows.zh.md: d445ddac4704fb940550d27ef7400e79d859393b diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md index 7d666f0a9e..dc09e8fda9 100644 --- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md +++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md @@ -15,7 +15,7 @@ With Code Mode enabled, the chat view showed one opaque `run_code` row: raw prog **Sub-calls are `ToolResultNode`s indexed off the surface flow, rendered through the same keyed slot as native rows, nested always-visible under their parent.** - **Data layer**: `Session.applyEventSideEffects` folds each in-window `tool/code-dispatch` into `ConversationSnapshot.codeDispatches: ReadonlyMap`, where `CodeSubCall` IS `ToolResultNode` (the sub-call id as `callId`, the logged args JSON-stringified into `call.argsRaw`, the full logged `content`/`isError`). Live mux frames and history replay build the identical index (`rebuildDerivedFromWindow` clears and re-derives; copy-on-write per-parent arrays keep snapshot references memo-stable). Sub-calls never join `nodes` — the surface flow remains exactly the model-visible turn structure. The event is narrowed structurally at the wire-consumer boundary (dsh-tools' host types cannot enter the client program — the host/client `Context` merges collide), the same posture as every cross-wire payload. -- **Render layer**: `ChatView`'s `CallRow` renders the parent, then — for parents present in the index — a `[data-subcalls]` nest of `SubCallRow`s, each dispatching through the SAME `'conversation.chat.toolview'` keyed hole with `entryKey = sub-tool name` and the same `GenericToolCard` fallback. Identity with native rows holds by construction: a keyed registration (e.g. the bash sample) takes over sub-rows exactly as it takes over top-level rows, with zero registration changes. Running parents (`runningCalls`) nest their so-far dispatches the same way, so sub-rows stream in live during the run (PR1 logs each dispatch as it completes). +- **Render layer**: `ChatView` passes each parent and its indexed children through the whole-Tool `'conversation.chat.tool'` seat. ui-tool's `ToolCallTree` renders the parent followed by a `[data-subcalls]` nest, and every atomic call dispatches through the same `'tool.call.toolview'` keyed slot with `entryKey = Tool name` and the same `GenericToolCard` fallback. A keyed registration therefore takes over child and top-level calls without registration changes. Running parents (`runningCalls`) receive their accumulated dispatches through the same owner payload, so child rows stream in during the run. - **`run_code` presentation**: a new `code` row variant (classifier `run_code → code`, `Code` title, `IconCodeOutline16`) summarizes with the model-authored `description` and expands to the program itself (monospace on the markdown code-block fill) rather than the args JSON envelope. - **Details panel**: `materialFor` falls through nodes → runningCalls → the dispatch index, so a selected sub-callId resolves to full args and complete output through the identical rendering path as a native settled call. diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md index b6b7de6c34..d445ddac47 100644 --- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md +++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md @@ -15,7 +15,7 @@ Status: implemented **子调用在界面流之外单独索引为 `ToolResultNode`，经由与原生行相同的 keyed slot 渲染，以始终可见的方式嵌套在父行之下。** - **数据层**：`Session.applyEventSideEffects` 把窗口内的每条 `tool/code-dispatch` 折入 `ConversationSnapshot.codeDispatches: ReadonlyMap`，其中 `CodeSubCall` 本身就是 `ToolResultNode`（子调用 id 充当 `callId`，已记录的参数经 JSON 字符串化写入 `call.argsRaw`，完整记录的 `content`/`isError` 原样携带）。实时多路复用帧与历史回放构建出同一份索引（`rebuildDerivedFromWindow` 先清空再重新推导；逐父级的写时复制（copy-on-write）数组保持快照引用稳定，便于 memo 化）。子调用永不进入 `nodes`——surface 流始终精确等于模型可见的轮次结构。该事件在 wire 消费方边界作结构性收窄（dsh-tools 的宿主类型无法进入客户端程序——宿主端/客户端两侧的 `Context` 声明合并会冲突），姿态与所有跨 wire 载荷一致。 -- **渲染层**：`ChatView` 的 `CallRow` 先渲染父行，随后对索引中出现的父级渲染一组 `[data-subcalls]` 嵌套的 `SubCallRow`，每一行都经由同一个 `'conversation.chat.toolview'` keyed slot、以 `entryKey = sub-tool name` 分发，并共用同一个 `GenericToolCard` 后备组件。与原生行的同一性由构造保证：一个 keyed 注册（例如 bash 样例）接管子行与接管顶层行的方式完全相同，注册本身零改动。运行中的父调用（`runningCalls`）也以同样的方式嵌套目前已产生的分发，因此子行在运行期间实时流入（PR1 在每次分发完成时即记录该分发）。 +- **渲染层**：`ChatView` 通过整体 Tool seat `'conversation.chat.tool'` 传递每个 parent 及其已索引的 child。ui-tool 的 `ToolCallTree` 先渲染 parent，再渲染一组 `[data-subcalls]` 嵌套；每个原子调用都通过同一个 `'tool.call.toolview'` keyed slot，以 Tool 名称作为 `entryKey`，并共用 `GenericToolCard` fallback。一个 keyed 注册因此无需变化即可同时接管 child 与顶层调用。运行中的 parent（`runningCalls`）通过同一 owner 载荷接收已累积的 dispatch，使 child 行在运行期间实时流入。 - **`run_code` 的呈现**：新增一种 `code` 行变体（分类器映射 `run_code → code`、标题 `Code`、图标 `IconCodeOutline16`），以模型撰写的 `description` 作摘要，展开后显示程序本身（在 markdown 代码块的填充底色上以等宽字体呈现），而非参数的 JSON 封装。 - **详情面板**：`materialFor` 按 nodes → runningCalls → 分发索引的顺序逐级回落，因此被选中的子调用 callId 会经由与已完结的原生调用完全相同的渲染路径，解析出完整参数与完整输出。 diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml index 5e079bc180..0a7fb2b3ef 100644 --- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-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-28-web-terminal-card.md -2026-07-28-web-terminal-card.md: 0e5f3e2157ebfc4e71aead26c15b6ee91958a5d5 -2026-07-28-web-terminal-card.zh.md: 1285d3fbb46ebd32ff163feac632cd487e8a04f1 +2026-07-28-web-terminal-card.md: 0493db4b86ce869ce5e699359e66dda70e526116 +2026-07-28-web-terminal-card.zh.md: 10137f83a25860a42e80a7b807a8aed68e86ce18 diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md index 0e5f3e2157..0493db4b86 100644 --- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md +++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md @@ -12,7 +12,7 @@ The Web client ignored it. `packages/client/ui-conversation/src/client/contract/ ## Decision -`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `ui-conversation/src/client/contract/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means. +`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `ui-tool/src/client/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means. The component's contract: @@ -57,7 +57,7 @@ Inline rendering is licensed for the terminal intent alone. A future intent that `packages/client/ui-primitives/tests/ansi.spec.ts` pins the parse layer: token mapping for the basic colors, literal rgb for the values with no token, the background-run pair, every decoration and the `textDecoration` collision between two of them, the sanitizing of OSC strings and non-CSI escapes and inert controls, the cursor replay (redraws leaving a longer frame's tail standing, a trailing backspace erasing nothing, erase-in-line in all three parameter forms, tab stops, wide characters, SGR threading across lines, and a cursor/erase sequence never entering a cell style), and CRLF preservation. Each replay case was checked against a real terminal first. `packages/client/ui-primitives/tests/terminal-block.spec.tsx` pins the component: cwd shortening, the running/empty/settled arms, signal outranking exit code, the trailing-newline terminator rule, the head/tail cap with its `aria-expanded` toggle, the run-state dot across all three reachable states plus its position ahead of the prompt label, the one-row-per-command-line prompt and its single dot on the first row, and the copy control asserting raw output on both the accepted and refused clipboard paths, plus `writeClipboard` directly. -`packages/client/ui-conversation/tests/terminal-card.spec.tsx` pins the wiring at every render site: `terminalCardModel`'s derivation and each of its null arms, the result title replacing the pending one, the cwd resolving against the session workspace across all four of its cases, the panel resetting the card's expand state when the selection changes, the chat row's expand-gated body against the panel's full-height one, `BashRow`'s resident card and its agreement with its own summary row's state dot, and the panel's Output section including the run_code sub-dispatch and the out-of-window head. That file is written against no gate pressure — `packages/client/ui-conversation/src/*` sits on the coverage `exclude` list in `vitest.config.ts`, so a coverage run over this package measures none of these files. +`packages/client/ui-tool/tests/terminal-card.spec.tsx` pins the wiring at every render site: `terminalCardModel`'s derivation and each of its null arms, the result title replacing the pending one, the cwd resolving against the session workspace across all four of its cases, the panel resetting the card's expand state when the selection changes, the chat row's expand-gated body against the panel's full-height one, `BashRow`'s resident card and its agreement with its own summary row's state dot, and the panel's Output section including the run_code sub-dispatch and the out-of-window head. That file is written against no gate pressure — `packages/client/ui-tool/src/*` sits on the coverage `exclude` list in `vitest.config.ts`, so a coverage run over this package measures none of these files. `apps/web/tests/terminal-card.snapshot.ts` pins the assembled application over the built client bundles: the same render intent at both conversation render sites and in both chat-row shapes, because a bash call reaches a resident card only through the keyed `BashRow` registration and every other terminal-declaring tool name lands on the render-site fallback row, whose body is expand-gated. Fixture turn 65 was named `bash` and turn 60 left as `fx-bash` so one fixture covers both shapes, and turn 60's command was made two lines so the built-bundle snapshot pins the per-line prompt and its single dot (`dotsPerPromptRow: [1, 0]`). That terminal turn is ordered BEFORE the todo turn on purpose: the standing plan retires at the next `turn/start`, so appending it after would have emptied the dock's plan strip and taken the todo surfaces' own coverage with it; that turn also carries what turn 60's two prompt rows cannot — SGR runs resolved to `--dsw-*` tokens, output past the chat cap, a nested cwd, and a non-zero exit authored beside the sample. The sample's body deliberately carries NO `[exit code: N]` line: the real bash presenter consumes that marker out of the body precisely because the card shows the exit as its own pill, so leaving it in would pin a frame showing the exit twice — one the product path cannot produce. diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md index 1285d3fbb4..10137f83a2 100644 --- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md +++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md @@ -12,7 +12,7 @@ Web client 却对它视而不见。`packages/client/ui-conversation/src/client/c ## Decision -`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`ui-conversation/src/client/contract/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。 +`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`ui-tool/src/client/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。 该组件的契约： @@ -57,7 +57,7 @@ Web client 却对它视而不见。`packages/client/ui-conversation/src/client/c `packages/client/ui-primitives/tests/ansi.spec.ts` 固定解析层：基本色的 token 映射、无对应 token 取值的字面 rgb、带背景分段的前后景配对、每一项装饰以及其中两项之间的 `textDecoration` 冲突、OSC 串与非 CSI 转义及无显示意义控制符的剥除、光标重放（较短重绘让上一帧尾巴留存、末尾退格不擦除任何东西、行内擦除的全部三种参数形式、制表位、宽字符、SGR 跨行延续，以及光标／擦除序列绝不进入单元格样式），以及 CRLF 的保留。每一条重放用例都先对照真实终端核实过。`packages/client/ui-primitives/tests/terminal-block.spec.tsx` 固定组件：cwd 缩短、运行中／空／已落定三条分支、信号优先于退出码、末尾终止符规则、首尾高度上限及其 `aria-expanded` 开关、运行状态点全部三种可达状态及其位于提示符标签之前的位置、每条命令行一行的提示区及其位于第一行的单枚状态点，以及复制控件在剪贴板接受与拒绝两条路径上都断言原始输出，另有对 `writeClipboard` 的直接固定。 -`packages/client/ui-conversation/tests/terminal-card.spec.tsx` 固定每个渲染点上的接线：`terminalCardModel` 的推导及其每一处 null 分支、结果标题替换待定标题、cwd 针对会话 workspace 解析的全部四种情形、切换选中调用时面板重置卡片展开态、对话行受展开控制的输出体与面板的全高输出体的对比、`BashRow` 的常驻卡片及其与自身摘要行状态点的一致性，以及面板 Output 区段（含 run_code 子派发与超出窗口的调用头）。该文件在没有门禁压力的情况下写成——`packages/client/ui-conversation/src/*` 位于 `vitest.config.ts` 的覆盖率 `exclude` 列表中，因此覆盖率运行不会统计其中任何文件。 +`packages/client/ui-tool/tests/terminal-card.spec.tsx` 固定每个渲染点上的接线：`terminalCardModel` 的推导及其每一处 null 分支、结果标题替换待定标题、cwd 针对会话 workspace 解析的全部四种情形、切换选中调用时面板重置卡片展开态、对话行受展开控制的输出体与面板的全高输出体的对比、`BashRow` 的常驻卡片及其与自身摘要行状态点的一致性，以及面板 Output 区段（含 run_code 子派发与超出窗口的调用头）。该文件在没有门禁压力的情况下写成——`packages/client/ui-tool/src/*` 位于 `vitest.config.ts` 的覆盖率 `exclude` 列表中，因此覆盖率运行不会统计其中任何文件。 `apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮改名为 `bash`、第 60 轮保留 `fx-bash`，于是一份 fixture 覆盖两种形态，并把第 60 轮的命令改为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮有意排在 todo 轮**之前**：站立计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮还承载第 60 轮两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。 diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml index 161e7b7fe7..35c6e070a6 100644 --- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.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-29-ask-question-web-presentation.md -2026-07-29-ask-question-web-presentation.md: 90eeb3cdcc1a851b7d5e184c0f31cbccd82cbf55 -2026-07-29-ask-question-web-presentation.zh.md: d1d18c030fd6cd9fc7832f82c19b49e4e8e04d30 +2026-07-29-ask-question-web-presentation.md: 11471bba08b723620b83af0e14e64a759d11c520 +2026-07-29-ask-question-web-presentation.zh.md: 50f0dffa1a1f9cbd29b676cc1f21ba0298f6bf23 diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md index 90eeb3cdcc..11471bba08 100644 --- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md +++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md @@ -12,7 +12,7 @@ Separately, the composer visuals had drifted from the current design: an expand- ## Decision -A pending question owns exactly two surfaces: the composer takeover collects the answers, and a dedicated `ask_user_question` toolview row in the transcript names the interaction outcome. The row registers into the keyed `conversation.chat.toolview` hole exactly like `todo_write` and composes the shared `ToolRow` (chrome, running sweep, leading expansion). Its summary is the interaction verdict rather than args: `waiting` while running, `N/M answered` from the result JSON once settled (a skipped answer — empty `selected`, no `custom` — stays out of the count), `cancelled` for `ASK_CANCELLED`, and `interrupted` with the shared amber stopped semantics for `ASK_ABORTED`. Malformed or truncated results fall back to the generic summary. `PendingCard` narrows to `PendingWait<'approval'>` and `ChatView` filters the pending list to approval waits, so the placeholder card now exists only for the approval takeover still on the roadmap. +A pending question owns exactly two surfaces: the composer takeover collects the answers, and a dedicated `ask_user_question` toolview row in the transcript names the interaction outcome. The row registers into the keyed `tool.call.toolview` hole exactly like `todo_write` and composes the shared `ToolRow` (chrome, running sweep, leading expansion). Its summary is the interaction verdict rather than args: `waiting` while running, `N/M answered` from the result JSON once settled (a skipped answer — empty `selected`, no `custom` — stays out of the count), `cancelled` for `ASK_CANCELLED`, and `interrupted` with the shared amber stopped semantics for `ASK_ABORTED`. Malformed or truncated results fall back to the generic summary. `PendingCard` narrows to `PendingWait<'approval'>` and `ChatView` filters the pending list to approval waits, so the placeholder card now exists only for the approval takeover still on the roadmap. The composer redesign moves paging into the footer next to the actions, renders multi-select options with explicit checkboxes, keeps single-select numbered rows, and replaces the expand-to-open custom entry with an always-visible custom input row (textarea for optionless questions). The `parseQuestionTitle` multi-select suffix convention is deleted; `multi_select` is already structured metadata, so the title renders verbatim. diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md index d1d18c030f..50f0dffa1a 100644 --- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md +++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md @@ -12,7 +12,7 @@ Web GUI 已经可以通过 `QuestionComposer` 的输入区接管收集回答， ## 决定 -一个待回答的问题恰好拥有两个界面：输入区接管收集回答，会话记录中一个专门的 `ask_user_question` toolview 行陈述交互结果。该行与 `todo_write` 完全一样注册进带 key 的 `conversation.chat.toolview` 槽位，并复用共享的 `ToolRow`（外观、运行扫光、前导展开）。其摘要是交互裁决而非参数：运行中显示 `waiting`，结算后从结果 JSON 得出 `N/M answered`（被跳过的回答 —— `selected` 为空且无 `custom` —— 不计入），`ASK_CANCELLED` 显示 `cancelled`，`ASK_ABORTED` 显示 `interrupted` 并沿用共享的琥珀色 stopped 语义。畸形或截断的结果回退到通用摘要。`PendingCard` 收窄为 `PendingWait<'approval'>`，`ChatView` 将待处理列表过滤为仅审批等待，占位卡片从此只服务于仍在路线图上的审批接管。 +一个待回答的问题恰好拥有两个界面：输入区接管收集回答，会话记录中一个专门的 `ask_user_question` toolview 行陈述交互结果。该行与 `todo_write` 完全一样注册进带 key 的 `tool.call.toolview` 槽位，并复用共享的 `ToolRow`（外观、运行扫光、前导展开）。其摘要是交互裁决而非参数：运行中显示 `waiting`，结算后从结果 JSON 得出 `N/M answered`（被跳过的回答 —— `selected` 为空且无 `custom` —— 不计入），`ASK_CANCELLED` 显示 `cancelled`，`ASK_ABORTED` 显示 `interrupted` 并沿用共享的琥珀色 stopped 语义。畸形或截断的结果回退到通用摘要。`PendingCard` 收窄为 `PendingWait<'approval'>`，`ChatView` 将待处理列表过滤为仅审批等待，占位卡片从此只服务于仍在路线图上的审批接管。 输入区重设计将分页移到底部操作区旁，多选选项渲染显式复选框，单选保留编号行，并用始终可见的自定义输入行取代展开式自定义入口（无选项问题用多行文本框）。删除 `parseQuestionTitle` 的多选后缀约定；`multi_select` 已是结构化元数据，标题原样渲染。 diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml index 388a8de9cd..ef2b3e55a0 100644 --- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-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-web-diff-card.md -2026-07-30-web-diff-card.md: eb43e09d6173ca2270df97cecaab6da36c70a679 -2026-07-30-web-diff-card.zh.md: 669cd49abc8eba8637705cd7c9f331cc51607755 +2026-07-30-web-diff-card.md: c8aed2aa59d82520a2a52523edb9b66d0bb34bf0 +2026-07-30-web-diff-card.zh.md: c2127844165e5f5c162eb3707fa5c86aa3a536c0 diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md index eb43e09d61..c8aed2aa59 100644 --- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md +++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md @@ -14,7 +14,7 @@ This is the [terminal card](2026-07-28-web-terminal-card.md) done for the `diff` ## Decision -`DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-conversation/src/client/contract/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change. +`DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-tool/src/client/models/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change. The component shares the TUI's single-column framing, line-terminator rule, and distinct-path file count. Line classification differs: Web renders the complete old and new sides, while the TUI derives neutral context and exact changed rows when its bounded comparison completes and labels its whole-side fallback approximate. @@ -46,7 +46,7 @@ The multi-file arm of `DiffBlock` (one card, several path headers) has no produc `packages/client/ui-primitives/tests/diff-block.spec.tsx` pins the component: the create arm (added-only, no removed side), the edit arm (removed above added), the same-file `⋯` gap versus a new file's own header, the empty-diffs null render, the footer counts and their singular/plural, the head/tail cap with its `aria-expanded` toggle, and the copy control asserting the prefixed diff text on both the accepted and refused clipboard paths. Per-file 100%. -`packages/client/ui-conversation/tests/diff-card.spec.tsx` pins the wiring at every render site: `diffCardModel`'s derivation and each of its null arms, the result hunks replacing the call-time diff, a window-truncated call still rendering from the result, the chat row's diff body, `FileMutationRow`'s resident card and its path link opening cwd-resolved through the host, its registration under both `write` and `edit`, and the panel's Output section. +`packages/client/ui-tool/tests/diff-card.spec.tsx` pins the wiring at every render site: `diffCardModel`'s derivation and each of its null arms, the result hunks replacing the call-time diff, a window-truncated call still rendering from the result, the chat row's diff body, `FileMutationRow`'s resident card and its path link opening cwd-resolved through the host, its registration under both `write` and `edit`, and the panel's Output section. The fixture (`packages/client/connection/src/client/fixture.ts`) carries three diff turns so a `?fixture` server and the per-package wiring suite exercise all three arms at both render sites: a single-hunk edit (turn 62, keyed `FileMutationRow`), a create/write (turn 63), and a multi-hunk edit (turn 67, the `⋯` gap between two scattered hunks in one file). The built-boot snapshot (`apps/web/tests/built-boot.snapshot.ts`) is a boot-assembly smoke that asserts only that the graph mounts and reaches chat content (`data-sample="bash-global"`); by its own contract it carries no diff-behavior assertions, which the wiring suite owns. diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md index 669cd49abc..c212784416 100644 --- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md +++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md @@ -14,7 +14,7 @@ Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行 ## Decision -`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-conversation/src/client/contract/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。 +`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。 该组件与 TUI 共用单栏框架、行终止符规则和去重路径计数。两者的行分类不同：Web 渲染完整的变更前后两侧，而 TUI 会在有界比较完成时派生中性上下文和精确变更行，并把整侧回退标记为近似结果。 @@ -46,7 +46,7 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX `packages/client/ui-primitives/tests/diff-block.spec.tsx` 钉住组件：新建支路（只有新增、无删除侧）、编辑支路（删除在新增之上）、同文件 `⋯` gap 对比新文件自己的头、空 diffs 的 null 渲染、页脚计数及其单复数、头尾上限及其 `aria-expanded` 切换、以及复制控件在接受与拒绝两条剪贴板路径上断言带前缀的 diff 文本。Per-file 100%。 -`packages/client/ui-conversation/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。 +`packages/client/ui-tool/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。 fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot snapshot（`apps/web/tests/built-boot.snapshot.ts`）是启动装配 smoke，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身契约它不带 diff 行为断言，那由接线套件负责。 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 388eb85ef8..71ea2aabaf 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: 06559d70c655b86a6aa70c8a9e948f4f21a1f522 -2026-07-30-web-read-card-frontend.zh.md: 92fb724658d4c23b915f61efc3b482fdf1ce7c7b +2026-07-30-web-read-card-frontend.md: 10ed9d3eaa54c2440cf3fbd00a7e44b76c1acfe9 +2026-07-30-web-read-card-frontend.zh.md: 931316135470b7e7257f7f9d016b24fe741fdbf5 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 06559d70c6..10ed9d3eaa 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 @@ -10,7 +10,7 @@ The [read backend](2026-07-30-web-read-card.md) added a fourth render-intent car ## 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. +`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-tool/src/client/models/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.
 
@@ -42,7 +42,7 @@ A read row in the Web chat now carries the file content resident, a deliberate d
 
 `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.
+`packages/client/ui-tool/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-tool/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 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`.
 
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 92fb724658..9313161354 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
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`ReadBlock` 是一个 `ui-primitives` 组件，把一次读取结果渲染成带行号、可选语法高亮的文件视图，读取的两个 Web 渲染点都通过它消费读取渲染意图：聊天工具行（常驻在摘要行之下）与详情面板的 Output 区段。`ui-conversation/src/client/contract/read-card-model.ts` 是把快照的 `resultView` 转成组件 props 的唯一位置，因此两个渲染点不会产生分歧。
+`ReadBlock` 是一个 `ui-primitives` 组件，把一次读取结果渲染成带行号、可选语法高亮的文件视图，读取的两个 Web 渲染点都通过它消费读取渲染意图：聊天工具行（常驻在摘要行之下）与详情面板的 Output 区段。`ui-tool/src/client/models/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)` 行头部加剩余的尾部），因此长读取和长命令输出在同一处折叠。复制控件写入窗口的原始文本（各行以换行拼接），绝不含行号栏或横幅。
 
@@ -42,7 +42,7 @@ Web 聊天里的读取行现在常驻承载文件内容，是相对纯摘要行
 
 `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/*`），因此不承受门槛压力。
+`packages/client/ui-tool/tests/read-card.spec.tsx` 固定每个渲染点的接线：`readCardModel` 的派生与每条 null 分支（运行中读取、无视图、通用视图、未知卡片）、结果标题替换化简后的路径、路径相对工作区的化简、冻结行数组的复制而非别名；`GenericToolCard` 回退中与 keyed `ReadRow` 中的常驻卡片（外加其路径链接打开宿主、其 running/error/stopped 状态、以及其 `read` 键注册）；还有面板 Output 区段以全高渲染读取卡片同时保留 JSON Input 区段，含运行中读取占位与非读取摊平 pre 两条分支。该文件位于覆盖 `exclude` 列表（`ui-tool/src/*`），因此不承受门槛压力。
 
 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` 退场。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index aab320ac99..ded72420fc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-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-result-card-frontend.md
-2026-07-30-web-result-card-frontend.md: 7457f30f71e811960ecadeb49caedef276682505
-2026-07-30-web-result-card-frontend.zh.md: 5fa53c4ecbeda40bd18a3c4e59ec75bd4358662d
+2026-07-30-web-result-card-frontend.md: 1d58710dbce3ed1aa9337e1841940195f71db40a
+2026-07-30-web-result-card-frontend.zh.md: 8705aa05557c1fdf642f498939bc2ceddde91f1f
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
index 7457f30f71..1d58710dbc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
@@ -10,7 +10,7 @@ The `web_search` and `web_fetch` tools declare a `card: 'web'` result view ([web
 
 ## Decision
 
-`WebBlock` is a `ui-primitives` component that renders a completed web retrieval, and every Web render site for a web call consumes the `web` render intent through it: the keyed chat tool rows (`web_search`/`web_fetch`), the `GenericToolCard` render-site fallback, and the details panel's Output section. `ui-conversation/src/client/contract/web-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, mirroring `terminal-card-model.ts`, so no two sites disagree about what a web call shows. It returns null — the generic path — for a running call (the web card is result-only, since the tools keep a generic pending view), for a settled call whose result view is not a web card including a `card` value this client version does not know (which arrives over the wire and so cannot be trusted to be a compiled variant), for a generic result view (a web tool's error path returns the generic card, whose text the generic path preserves), and for a web card whose `kind` this client version does not know (a newer host's value off the wire, which reading as a fetch would draw as an empty URL and `HTTP undefined`).
+`WebBlock` is a `ui-primitives` component that renders a completed web retrieval, and every Web render site for a web call consumes the `web` render intent through it: the keyed chat tool rows (`web_search`/`web_fetch`), the `GenericToolCard` render-site fallback, and the details panel's Output section. `ui-tool/src/client/models/web-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, mirroring `terminal-card-model.ts`, so no two sites disagree about what a web call shows. It returns null — the generic path — for a running call (the web card is result-only, since the tools keep a generic pending view), for a settled call whose result view is not a web card including a `card` value this client version does not know (which arrives over the wire and so cannot be trusted to be a compiled variant), for a generic result view (a web tool's error path returns the generic card, whose text the generic path preserves), and for a web card whose `kind` this client version does not know (a newer host's value off the wire, which reading as a fetch would draw as an empty URL and `HTTP undefined`).
 
 One component draws both kinds, discriminated by `kind`. A `search` shows the answer as markdown above a citation list; each source is a safe external link labelled by its title, or its hostname when the provider gave none, with the snippet and publication date below it, and a `来源列表已截断` indicator when the tool capped the list. A `fetch` shows a compact summary: the linked final URL, its HTTP status, and a `内容已截断` indicator. One component rather than two because both are web retrieval rendered as one card family, which is exactly the reason the contract carries them under one `card` tag with a `kind` discriminant.
 
@@ -38,7 +38,7 @@ A separate later PR unifies the whole-row collapse/expand interaction and will f
 
 `packages/client/ui-primitives/tests/web-block.spec.tsx` pins the component per-file to the 100% gate: both kinds; the title-or-hostname-or-raw-URL label fallback; the safe-link attributes on both kinds (an http(s) URL becoming an external anchor with `target`/`rel`, a `javascript:`/`file:`/unparseable URL rendering as a plain span with no href); the snippet and date shown or omitted on present/empty/absent; the truncation indicator gated on the flag; and the full source list rendering inside one scroll container with no expand control and `
  • ` numbering every source contiguously from 1.
 
-`packages/client/ui-conversation/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring seam: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-conversation/src/*`), so a coverage run measures none of it.
+`packages/client/ui-tool/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring seam: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-tool/src/*`), so a coverage run measures none of it.
 
 The fixture (`packages/client/connection/src/client/fixture.ts`) adds turns 66 (`web_search`) and 67 (`web_fetch`), authored inline because the client-side fixture cannot import the web tool: turn 66's result view carries an answer and three sources exercising the citation list (a titled source with a snippet and date, a source with no title so its hostname labels the link, and a source with a date but no snippet) with the capped indicator on; turn 67's carries the fetched URL and a 200 status. Both keep a generic pending call view and add the `web` card only at result time, matching the contract's result-only web shape, and are named after the real tools so they hit the keyed `WebRow`. They are ordered before the todo turn (renumbered to 68) for the same reason the terminal turn is: the standing plan retires at the next `turn/start`, so a turn appended after it would empty the dock's plan strip. This drives the built-boot snapshot and a live `?fixture` server.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index 5fa53c4ecb..8705aa0555 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-conversation/src/client/contract/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
+`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
 
 一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是契约把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
 
@@ -38,7 +38,7 @@ Status: implemented
 
 `packages/client/ui-primitives/tests/web-block.spec.tsx` 把组件钉到 per-file 100% 门槛:两种 kind;标题-或-主机名-或-原始 URL 的标签回退;两种 kind 上的安全链接属性（http(s) URL 成为带 `target`/`rel` 的外链,`javascript:`/`file:`/无法解析的 URL 渲染为无 href 的纯 span）;snippet 与日期在存在/为空/缺失时的显示或省略;由标志位控制的截断提示;以及完整 source 列表渲染在单个滚动容器内、无展开控件、`
  • ` 从 1 起为每条 source 连续编号。
 
-`packages/client/ui-conversation/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-conversation/src/*`）,因此覆盖率运行不度量它。
+`packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
 
 fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配契约的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
index 2d2b338b6f..1578f0c73e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-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-web-search-card.md
-2026-07-30-web-search-card.md: 4c7ae6c8c658f4f10f0667b12853cb2e70df15b1
-2026-07-30-web-search-card.zh.md: b129d411b9b402b18d6b4ec94dad544effd3bb8c
+2026-07-30-web-search-card.md: a350756a22d2ba5da8a0ff5d3a4cb3f257ac566b
+2026-07-30-web-search-card.zh.md: d6ec2a08eb02a92a50d4742c3d87c22f42c095d4
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
index 4c7ae6c8c6..a350756a22 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
@@ -12,7 +12,7 @@ This is the follow-up the search render card note names: that PR was the backend
 
 ## Decision
 
-`SearchBlock` is a `ui-primitives` component that renders a completed search as either shape, and the Web render sites for a `grep`/`glob` call consume the search render intent through it. `ui-conversation/src/client/contract/search-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so no render site re-derives the shape. It returns null — the generic path — whenever the result view is not a search card, including a still-running call (a search card is result-time only, so there is nothing before `execute`), a generic result a `grep`/`glob` failure or a nested `run_code` dispatch produces, a terminal result view, a `card` value this client version does not know, a `card: 'search'` view whose `shape` this version does not compile, and — because `shape` and the grouped/flat contents ride the same untrusted wire frame the host schema only string-checks — a known `shape` whose `files`/`paths` is missing or malformed (which would otherwise crash `SearchBlock` at `.reduce`/`.map`). The result-view discriminant is `shape` (not `kind`, which the backend reserves for the call view's icon-picking tag); `SearchBlock`'s own prop stays `kind`, mapped from `shape` in this derivation.
+`SearchBlock` is a `ui-primitives` component that renders a completed search as either shape, and the Web render sites for a `grep`/`glob` call consume the search render intent through it. `ui-tool/src/client/models/search-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so no render site re-derives the shape. It returns null — the generic path — whenever the result view is not a search card, including a still-running call (a search card is result-time only, so there is nothing before `execute`), a generic result a `grep`/`glob` failure or a nested `run_code` dispatch produces, a terminal result view, a `card` value this client version does not know, a `card: 'search'` view whose `shape` this version does not compile, and — because `shape` and the grouped/flat contents ride the same untrusted wire frame the host schema only string-checks — a known `shape` whose `files`/`paths` is missing or malformed (which would otherwise crash `SearchBlock` at `.reduce`/`.map`). The result-view discriminant is `shape` (not `kind`, which the backend reserves for the call view's icon-picking tag); `SearchBlock`'s own prop stays `kind`, mapped from `shape` in this derivation.
 
 The asymmetry with the terminal card is deliberate and inherited from the backend contract: `terminalCardModel` reads both `callView` and `resultView` because a command, cwd, and description exist at call time; `searchCardModel` reads only `resultView` because a search's matches or paths exist only after execution. A running search row therefore shows its summary alone, with no card.
 
@@ -34,7 +34,7 @@ Geometry, radius, and fonts mirror `CodeBlock` and `TerminalBlock`, so a search
 
 Three sites consume the derivation, mirroring the terminal card's placement exactly:
 
-- **The keyed `SearchRow`** (`toolviews/search-row.tsx`) registers ONE component under both `grep` and `glob` in the `conversation.chat.toolview` keyed hole, and renders the card RESIDENT under the summary row, capped at `CHAT_SEARCH_MAX_LINES` (8) — the same posture `BashRow` takes for its terminal card. Both tool names get the same row because the derived `kind` decides the shape, so a second component would duplicate it. A capped result's recovery footer sits below the card. Because the keyed row owns this render slot, a settled call with no search card — an errored search (grep/glob emit no result view on error), a successful nested `run_code` sub-dispatch (the backend computes no `presentationMeta`, so `resultView` is null), or a legacy generic result — would otherwise show only its summary with its content lost; the row surfaces that model-facing text as a fallback body, keyed on `search === null && settled` rather than on the error state alone. (This resident posture matches the current terminal/diff cards; a separate later PR unifies the whole-row collapse/expand interaction and flips all resident cards at once — out of scope here.)
+- **The keyed `SearchRow`** (`toolviews/search-row.tsx`) registers ONE component under both `grep` and `glob` in the `tool.call.toolview` keyed hole, and renders the card RESIDENT under the summary row, capped at `CHAT_SEARCH_MAX_LINES` (8) — the same posture `BashRow` takes for its terminal card. Both tool names get the same row because the derived `kind` decides the shape, so a second component would duplicate it. A capped result's recovery footer sits below the card. Because the keyed row owns this render slot, a settled call with no search card — an errored search (grep/glob emit no result view on error), a successful nested `run_code` sub-dispatch (the backend computes no `presentationMeta`, so `resultView` is null), or a legacy generic result — would otherwise show only its summary with its content lost; the row surfaces that model-facing text as a fallback body, keyed on `search === null && settled` rather than on the error state alone. (This resident posture matches the current terminal/diff cards; a separate later PR unifies the whole-row collapse/expand interaction and flips all resident cards at once — out of scope here.)
 - **The generic fallback** (`chat/GenericToolCard` → `chat/ToolRow`) threads the derived model as an expand-gated body, the same arm `terminal` uses: a `grep`/`glob` result with no keyed row (none in the shipped app, since both are registered) still renders its card, with the recovery footer, behind the row's expand toggle.
 - **The details panel** (`skeleton/DetailsPanel`) renders the card at the primitive's own full height in the Output section, with the recovery footer below it, keeping the JSON Input section.
 
@@ -56,7 +56,7 @@ Three sites consume the derivation, mirroring the terminal card's placement exac
 
 `packages/client/ui-primitives/tests/search-block.spec.tsx` pins the component at per-file 100%: both kinds, the folded pre-cap total in the summary, the empty arm, per-file collapse/re-expand without touching neighbours, a file header counting as one capped row alongside its matches, the tail slice restoring its owning file header when the cut falls mid-file, the head/tail cap and its expand control across both shapes and the no-tail and default-cap edges, and the copy control writing the whole structured result on the accepted and refused clipboard paths.
 
-`packages/client/ui-conversation/tests/search-card.spec.tsx` pins the wiring at every render site: `searchCardModel`'s derivation for both kinds, the truncation signal, the replacement title, the recovery text surfaced only when capped, each null arm (running, no views, generic, terminal, unknown card, an uncompiled `kind`, and a known kind with a missing/malformed shape); the chat row's expand-gated matches and paths bodies through `GenericToolCard` (with the recovery footer) against the non-search args-JSON body; `SearchRow`'s resident card for both kinds, its recovery footer, its fallback body for both an errored search and a settled cardless result, its agreement with the summary row's run state, the replacement-title precedence, and the keyed registration under both `grep` and `glob` with one component; and the details panel's Output section for both kinds (with the recovery footer) against the non-search flattened form. `packages/client/ui-conversation/src/*` sits on the coverage exclude list, so this file is written against no gate pressure. `packages/client/connection/src/client/fixture.ts` gains a `grep` turn emitting `kind: 'matches'` (three files, twelve rows over the row cap, `truncated` with a spill-recovery footer, so it exercises the head/tail cap and the recovery footer in the assembled snapshot) and a `glob` turn emitting `kind: 'paths'`, both driving the built-boot snapshot and the live `?fixture` server. `apps/web/tests/search-card.snapshot.ts` is the assembled-output check the repo contract asks for: it boots the real built `client.js` bundles through the keyless fixture transport, opens the fixture session, and pins the grep card's assembled shape — kind, truncation summary, the head/tail slice, and its expand control — under `apps/web/tests/snapshots/search-card/`, so a broken SearchRow registration or a dropped card fails a golden the built-boot smoke (boot-only by contract) cannot.
+`packages/client/ui-tool/tests/search-card.spec.tsx` pins the wiring at every render site: `searchCardModel`'s derivation for both kinds, the truncation signal, the replacement title, the recovery text surfaced only when capped, each null arm (running, no views, generic, terminal, unknown card, an uncompiled `kind`, and a known kind with a missing/malformed shape); the chat row's expand-gated matches and paths bodies through `GenericToolCard` (with the recovery footer) against the non-search args-JSON body; `SearchRow`'s resident card for both kinds, its recovery footer, its fallback body for both an errored search and a settled cardless result, its agreement with the summary row's run state, the replacement-title precedence, and the keyed registration under both `grep` and `glob` with one component; and the details panel's Output section for both kinds (with the recovery footer) against the non-search flattened form. `packages/client/ui-tool/src/*` sits on the coverage exclude list, so this file is written against no gate pressure. `packages/client/connection/src/client/fixture.ts` gains a `grep` turn emitting `kind: 'matches'` (three files, twelve rows over the row cap, `truncated` with a spill-recovery footer, so it exercises the head/tail cap and the recovery footer in the assembled snapshot) and a `glob` turn emitting `kind: 'paths'`, both driving the built-boot snapshot and the live `?fixture` server. `apps/web/tests/search-card.snapshot.ts` is the assembled-output check the repo contract asks for: it boots the real built `client.js` bundles through the keyless fixture transport, opens the fixture session, and pins the grep card's assembled shape — kind, truncation summary, the head/tail slice, and its expand control — under `apps/web/tests/snapshots/search-card/`, so a broken SearchRow registration or a dropped card fails a golden the built-boot smoke (boot-only by contract) cannot.
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
index b129d411b9..d6ec2a08eb 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## Decision
 
-`SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-conversation/src/client/contract/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
+`SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-tool/src/client/models/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
 
 与终端卡片的不对称是刻意的，继承自后端契约：`terminalCardModel` 同时读 `callView` 和 `resultView`，因为命令、cwd、description 在调用时就存在；`searchCardModel` 只读 `resultView`，因为搜索的匹配或路径只在执行后存在。因此运行中的搜索行只显示摘要，没有卡片。
 
@@ -34,7 +34,7 @@ Status: implemented
 
 三个渲染点消费该推导，与终端卡片的落位完全一致：
 
-- **keyed `SearchRow`**（`toolviews/search-row.tsx`）把一个组件同时注册到 `conversation.chat.toolview` keyed hole 的 `grep` 与 `glob` 键下，并把卡片作为常驻（resident）渲染在摘要行下方，上限为 `CHAT_SEARCH_MAX_LINES`（8）—— 与 `BashRow` 对其终端卡片采取的姿态相同。两个工具名共用同一行，因为推导出的 `kind` 决定形态，第二个组件只会重复它。被截断结果的恢复脚注画在卡片下方。因为 keyed 行占据了这个渲染槽，一个没有搜索卡片的已结算调用 —— 出错的搜索（grep/glob 出错时不产出结果视图）、成功的嵌套 `run_code` 子派发（后端不为其计算 `presentationMeta`，故 `resultView` 为 null）、或旧日志的 generic 结果 —— 否则只会显示摘要而丢失内容；该行把这段面向模型的文本作为 fallback body 暴露出来，判据是 `search === null && 已结算`，而非仅凭错误状态。（该常驻姿态与当前的 terminal/diff 卡片一致；一个单独的后续 PR 会统一整行折叠/展开交互并一次性翻转所有常驻卡片 —— 不在本 PR 范围内。）
+- **keyed `SearchRow`**（`toolviews/search-row.tsx`）把一个组件同时注册到 `tool.call.toolview` keyed hole 的 `grep` 与 `glob` 键下，并把卡片作为常驻（resident）渲染在摘要行下方，上限为 `CHAT_SEARCH_MAX_LINES`（8）—— 与 `BashRow` 对其终端卡片采取的姿态相同。两个工具名共用同一行，因为推导出的 `kind` 决定形态，第二个组件只会重复它。被截断结果的恢复脚注画在卡片下方。因为 keyed 行占据了这个渲染槽，一个没有搜索卡片的已结算调用 —— 出错的搜索（grep/glob 出错时不产出结果视图）、成功的嵌套 `run_code` 子派发（后端不为其计算 `presentationMeta`，故 `resultView` 为 null）、或旧日志的 generic 结果 —— 否则只会显示摘要而丢失内容；该行把这段面向模型的文本作为 fallback body 暴露出来，判据是 `search === null && 已结算`，而非仅凭错误状态。（该常驻姿态与当前的 terminal/diff 卡片一致；一个单独的后续 PR 会统一整行折叠/展开交互并一次性翻转所有常驻卡片 —— 不在本 PR 范围内。）
 - **generic fallback**（`chat/GenericToolCard` → `chat/ToolRow`）把推导出的 model 作为展开门控的 body 传入，与 `terminal` 用的是同一分支：没有 keyed 行的 `grep`/`glob` 结果（发布应用里没有，因为两者都注册了）仍在行的展开开关后渲染其卡片，并带恢复脚注。
 - **details panel**（`skeleton/DetailsPanel`）在 Output 段以 primitive 自身的完整高度渲染卡片，恢复脚注画在其下方，保留 JSON Input 段。
 
@@ -56,7 +56,7 @@ Status: implemented
 
 `packages/client/ui-primitives/tests/search-block.spec.tsx` 以 per-file 100% 覆盖固定组件：两种 kind、折入摘要的截断前总数、空结果分支、逐文件折叠/再展开且不影响邻居、一个文件头与其匹配一起计为一个被截断行、切口落在文件中间时尾部切片恢复其所属文件头、跨两种形态的头/尾上限及其展开控件（含无尾与默认上限的边界），以及复制控件在接受与拒绝的剪贴板路径上写入整个结构化结果。
 
-`packages/client/ui-conversation/tests/search-card.spec.tsx` 固定每个渲染点的接线：`searchCardModel` 对两种 kind 的推导、截断信号、替换标题、仅在截断时暴露的恢复文本，以及每个 null 分支（运行中、无视图、generic、terminal、未知卡片、本版本无法编译的 `kind`、以及一个形态缺失/错误的已知 kind）；通过 `GenericToolCard` 的展开门控 matches 与 paths body（含恢复脚注），对照非搜索的 args-JSON body；`SearchRow` 对两种 kind 的常驻卡片、它的恢复脚注、它对出错搜索与已结算无卡片结果两者的 fallback body、它与摘要行运行状态的一致、替换标题优先级，以及一个组件在 `grep` 与 `glob` 两个键下的 keyed 注册；以及 details panel 的 Output 段对两种 kind（含恢复脚注），对照非搜索的压平形态。`packages/client/ui-conversation/src/*` 在覆盖排除清单上，因此该文件不受 gate 压力。`packages/client/connection/src/client/fixture.ts` 新增一个发出 `kind: 'matches'` 的 `grep` turn（三个文件、十二行超过行内上限、`truncated` 且带溢出恢复脚注，因此在组装快照里同时演练头/尾上限与恢复脚注）与一个发出 `kind: 'paths'` 的 `glob` turn，两者都驱动 built-boot snapshot 与实时 `?fixture` 服务。`apps/web/tests/search-card.snapshot.ts` 是仓库契约要求的组装输出检查：它通过 keyless fixture 传输启动真实构建的 `client.js` bundle，打开 fixture 会话，并把 grep 卡片的组装形态——kind、截断摘要、头/尾切片及其展开控件——固定在 `apps/web/tests/snapshots/search-card/` 下，因此一个损坏的 SearchRow 注册或被丢弃的卡片会让一个 golden 失败，而 built-boot smoke（按契约只测启动）无法捕获它。
+`packages/client/ui-tool/tests/search-card.spec.tsx` 固定每个渲染点的接线：`searchCardModel` 对两种 kind 的推导、截断信号、替换标题、仅在截断时暴露的恢复文本，以及每个 null 分支（运行中、无视图、generic、terminal、未知卡片、本版本无法编译的 `kind`、以及一个形态缺失/错误的已知 kind）；通过 `GenericToolCard` 的展开门控 matches 与 paths body（含恢复脚注），对照非搜索的 args-JSON body；`SearchRow` 对两种 kind 的常驻卡片、它的恢复脚注、它对出错搜索与已结算无卡片结果两者的 fallback body、它与摘要行运行状态的一致、替换标题优先级，以及一个组件在 `grep` 与 `glob` 两个键下的 keyed 注册；以及 details panel 的 Output 段对两种 kind（含恢复脚注），对照非搜索的压平形态。`packages/client/ui-tool/src/*` 在覆盖排除清单上，因此该文件不受 gate 压力。`packages/client/connection/src/client/fixture.ts` 新增一个发出 `kind: 'matches'` 的 `grep` turn（三个文件、十二行超过行内上限、`truncated` 且带溢出恢复脚注，因此在组装快照里同时演练头/尾上限与恢复脚注）与一个发出 `kind: 'paths'` 的 `glob` turn，两者都驱动 built-boot snapshot 与实时 `?fixture` 服务。`apps/web/tests/search-card.snapshot.ts` 是仓库契约要求的组装输出检查：它通过 keyless fixture 传输启动真实构建的 `client.js` bundle，打开 fixture 会话，并把 grep 卡片的组装形态——kind、截断摘要、头/尾切片及其展开控件——固定在 `apps/web/tests/snapshots/search-card/` 下，因此一个损坏的 SearchRow 注册或被丢弃的卡片会让一个 golden 失败，而 built-boot smoke（按契约只测启动）无法捕获它。
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
index a2710c73f9..255dd08832 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.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-tool-row-unified-expand-and-inspect.md
-2026-07-30-web-tool-row-unified-expand-and-inspect.md: 98f1595564f0bd0d22f1ca4318b4c7fe15c6900d
-2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 8f00349a975f777cc4d556ade3a9abe9676b8848
+2026-07-30-web-tool-row-unified-expand-and-inspect.md: 4fcf1e9a567b73cd04f1bbed170c391aaedd9e73
+2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 92d70f5aa6bd09e6f9e54015dafc38d8d3690a9e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
index 98f1595564..4fcf1e9a56 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
@@ -16,7 +16,7 @@ The chat view's tool rows had drifted into per-surface interaction dialects: Too
 - The expanded card (figma 1249:35657) is a column of IN/OUT sections: each section is its own scrollport (max-height 150px) with a sticky gutter label, and the l2 divider spans the full card width. Think prose and the run_code CodeBlock keep their non-card bodies; context injection reuses the row with a label-less `plainBody` card.
 - `terminalFailed` reads a settled terminal card's exit status so BashRow and GenericToolCard surface a failing command as the row's red state dot — the only failure signal the collapsed row has, since the call itself settles `isError:false`.
 - TerminalBlock's banner joins the same reading model: it shares the card surface (no banner token), an l2 hairline separates it from the body, the command column caps at 150px and scrolls with sticky copy/status controls top-aligned to the first prompt row.
-- Inspect: `ToolRowOwnerProps.inspect` (absent for rows without a call identity) renders a pill in real flow under the expanded body's bottom-left, revealed by hovering anywhere on the tool call. Clicking writes `{ callId }` to the chat store's one-shot `inspect` field and switches to the trajectory view; TrajectoryTable finds the record, opens its summary, and acknowledges by clearing the field.
+- Inspect: `ToolCallOwnerProps.inspect` (absent for rows without a call identity) renders a pill in real flow under the expanded body's bottom-left, revealed by hovering anywhere on the tool call. Clicking writes `{ callId }` to the chat store's one-shot `inspect` field and switches to the trajectory view; TrajectoryTable finds the record, opens its summary, and acknowledges by clearing the field.
 - Scroll preservation: on every non-bottom scroll, the chat view saves `{ anchorKey, anchorTop, scrollTop }` into an apply-scope per-session map exposed as `chatScroll`; a remount first uses `scrollTop` to reach the approximate window, then corrects by the stable node/call anchor's rectangle delta so width reflow keeps the same reading row in place. Every pinned path, including Back to bottom, clears the entry synchronously before a tab or session switch. The map remains deliberately unpersisted — a fresh page load keeps the open-jump-to-bottom default.
 
 ## Alternatives considered
@@ -31,4 +31,4 @@ The chat view's tool rows had drifted into per-surface interaction dialects: Too
 
 ## Consequences
 
-Any registered toolview gets input AND output inspection in place, with the details panel and trajectory remaining the deep-dive surfaces. The unified interaction is contract-visible (`ToolRowProps.output/errorSummary/inspect`), so third-party rows opt in by passing model fields through. The bash sample intentionally re-replicates the new CSS (registrant posture), so future interaction changes still touch it by hand. `--dsw-font-markdown-code-block-small` (12/18) is a hand-added token pending a design-platform export. The web-cordis `distIndex` fix (plain concatenation, not URL.pathname) unblocks preview boots from a cwd with spaces.
+Built-in ui-tool views get input and output inspection in place, with the details panel and trajectory remaining the deep-dive surfaces. The shared `ToolRow` interaction is internal to ui-tool; an external atomic view receives `ToolCallViewProps` and may expose the supplied `inspect` callback through its own chrome. The bash view keeps its separate CSS, so future interaction changes still touch it explicitly. `--dsw-font-markdown-code-block-small` (12/18) is a hand-added token pending a design-platform export. The web-cordis `distIndex` fix (plain concatenation, not URL.pathname) unblocks preview boots from a cwd with spaces.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
index 8f00349a97..92d70f5aa6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
@@ -16,7 +16,7 @@
 - 展开卡片（figma 1249:35657）是 IN/OUT 分区列：每个分区是独立滚动区（max-height 150px），侧栏标签 sticky 固定，l2 分割线横贯整卡宽度。Think 的推理文本和 run_code 的 CodeBlock 保持非卡片体；上下文注入复用此行并以无标签的 `plainBody` 卡片展开。
 - `terminalFailed` 读取已结算 terminal 卡片的退出状态，让 BashRow 和 GenericToolCard 把失败命令显示为行的红色状态点——这是折叠行唯一的失败信号，因为调用本身结算为 `isError:false`。
 - TerminalBlock 的横幅并入同一阅读模型：与卡片共用同一表面（不再用 banner token），与正文之间是 l2 细线，命令列上限 150px 内部滚动，复制/状态控件 sticky 且顶对齐第一行提示符。
-- Inspect：`ToolRowOwnerProps.inspect`（无调用身份的行不提供）在展开体左下角以真实布局位置渲染胶囊，hover 整个 tool call 任意位置显示。点击将 `{ callId }` 写入 chat store 的一次性 `inspect` 字段并切换到 trajectory 视图；TrajectoryTable 找到记录、打开其摘要，并通过清空字段确认。
+- Inspect：`ToolCallOwnerProps.inspect`（无调用身份的行不提供）在展开体左下角以真实布局位置渲染胶囊，hover 整个 tool call 任意位置显示。点击将 `{ callId }` 写入 chat store 的一次性 `inspect` 字段并切换到 trajectory 视图；TrajectoryTable 找到记录、打开其摘要，并通过清空字段确认。
 - 滚动保留：每次非贴底滚动时，聊天视图把 `{ anchorKey, anchorTop, scrollTop }` 保存到 apply 作用域的按会话 Map，并经注入 props 的 `chatScroll` 暴露；重挂载时先用 `scrollTop` 到达近似窗口，再按稳定 node／call 锚点的矩形差值校正，因此宽度重排后仍把同一阅读行保持在原位。包括「回到底部」在内的每条贴底路径都会在切换 tab 或会话前同步清除该项。Map 仍刻意不持久化——新页面加载保持打开即贴底的默认行为。
 
 ## 曾考虑的替代方案
@@ -31,4 +31,4 @@
 
 ## 后果
 
-任何已注册 toolview 都能就地查看输入与输出，详情面板和 trajectory 仍是深查表面。统一交互契约可见（`ToolRowProps.output/errorSummary/inspect`），第三方行透传模型字段即可接入。bash 示例有意重新复刻新 CSS（注册方姿态），未来交互变更仍需手动同步它。`--dsw-font-markdown-code-block-small`（12/18）是手工补充的 token，待设计平台导出后替换。web-cordis 的 `distIndex` 修复（纯拼接而非 URL.pathname）解除了含空格 cwd 下预览无法启动的问题。
+ui-tool 内置视图都能就地检查输入与输出，详情面板和 trajectory 仍是深查界面。共享 `ToolRow` 交互是 ui-tool 内部实现；外部原子视图接收 `ToolCallViewProps`，可以通过自己的 chrome 暴露其中的 `inspect` 回调。bash 视图保留独立 CSS，因此未来交互变化仍需显式同步。`--dsw-font-markdown-code-block-small`（12/18）是手工补充的 token，待设计平台导出后替换。web-cordis 的 `distIndex` 修复（纯拼接而非 URL.pathname）解除了含空格 cwd 下预览无法启动的问题。
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
index f4f0ef3891..c12de68dc8 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.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-08-02-web-thinking-tail-scroll.md
-2026-08-02-web-thinking-tail-scroll.md: c45840731153627b4ce460ee140257ba33d2c007
-2026-08-02-web-thinking-tail-scroll.zh.md: b8d0444d62294e123bec1d26cb4c07538bbf966f
+2026-08-02-web-thinking-tail-scroll.md: 18e94b2e0075bf7099b9b48177de2e274896942a
+2026-08-02-web-thinking-tail-scroll.zh.md: 9b1428af7d3ab3c25509696619de75adc1cd7b7f
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
index c458407311..18e94b2e00 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
@@ -28,4 +28,4 @@ The collapsed row now communicates provider cadence through content motion as we
 
 ## Testing
 
-`packages/client/ui-conversation/tests/chat-tool-row.spec.tsx` pins the latest-line selection, the calculated right-edge scroll position, and the settlement reset to the first line and `scrollLeft = 0`. The keyless assembled Chromium scenario in `apps/web/tests/lifecycle-chrome.e2e.ts` replays real recorded reasoning chunks at observable pacing, narrows the viewport until the summary overflows, and asserts that the live collapsed Think row reaches its actual browser scroll extent. Its settled replay golden remains unchanged, proving the historical summary contract stays stable.
+`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` pins the latest-line selection, the calculated right-edge scroll position, and the settlement reset to the first line and `scrollLeft = 0`. The keyless assembled Chromium scenario in `apps/web/tests/lifecycle-chrome.e2e.ts` replays real recorded reasoning chunks at observable pacing, narrows the viewport until the summary overflows, and asserts that the live collapsed Think row reaches its actual browser scroll extent. Its settled replay golden remains unchanged, proving the historical summary contract stays stable.
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
index b8d0444d62..9b1428af7d 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
@@ -28,4 +28,4 @@ Web Think 行在结算与流式 block 中都把 reasoning 首行渲染成折叠
 
 ## 测试
 
-`packages/client/ui-conversation/tests/chat-tool-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要契约仍然稳定。
+`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要契约仍然稳定。
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
index 80f7ed4ab4..2ba0af23c4 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
@@ -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-08-03-web-search-source-scroll.md
-2026-08-03-web-search-source-scroll.md: c11bb2317b6ae6cad8017a4b76cb0b9ccebd6fc0
-2026-08-03-web-search-source-scroll.zh.md: add012216589b33cf244d8a14053a5b6d60631a6
+2026-08-03-web-search-source-scroll.md: 3215302b2f6c7a4e6d6cd7440a0c7f5048b72a80
+2026-08-03-web-search-source-scroll.zh.md: cf75a5e34632872d09a13e1667ecac5f01428e18
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
index c11bb2317b..3215302b2f 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
@@ -36,7 +36,7 @@ Every source the tool returned is always in the DOM, so no source the view carri
 
 ## Testing
 
-`packages/client/ui-primitives/tests/web-block.spec.tsx` drops the collapse cases (head/tail slice, expand-on-click, collapsed-tail numbering, expander-out-of-numbering, head-alone, default cap) and adds: a 30-source card renders all 30 `
  • ` with no `[aria-expanded]` and no `
-        ) : (
-          
-            {leading}
-          
-        )}
-        {title}
-        {(keepContentWhenOpen || !open) && collapsedContent}
-
    • - {open && children} -
    - ) -} diff --git a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx index 61c677ea98..bd4add4234 100644 --- a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx +++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx @@ -20,7 +20,7 @@ import { useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react' import clsx from 'clsx' import { - CodeBlock, DiffBlock, IconInspectOutline12, ReadBlock, SearchBlock, StateDot, TerminalBlock, WebBlock, + CodeBlock, DiffBlock, DisclosureRow, IconInspectOutline12, ReadBlock, SearchBlock, StateDot, TerminalBlock, WebBlock, } from '@deepseek-ai/dsh-client-ui-primitives' import type { WebBlockProps } from '@deepseek-ai/dsh-client-ui-primitives' import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots' @@ -29,7 +29,6 @@ import { CHAT_READ_MAX_LINES, type ReadCardModel } from '../models/read-card-mod import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../models/search-card-model.ts' import { terminalBlockLabels, type TerminalCardModel } from '../models/terminal-card-model.ts' import type { ToolRowState, ToolRowVariant } from '../models/tool-call-model.ts' -import { DisclosureRow } from './DisclosureRow.tsx' import css from './ToolRow.module.css' export interface ToolRowProps { diff --git a/packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts b/packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts index 8a0c887990..e0609191b7 100644 --- a/packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts +++ b/packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts @@ -8,9 +8,10 @@ * are derived once. * @module */ +import { resolveWorkspacePath } from '@deepseek-ai/dsh-client-runtime/client' import type { TerminalBlockLabels, TerminalBlockProps } from '@deepseek-ai/dsh-client-ui-primitives' import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots' -import { resolveToolPath, type ToolCallBlock } from './tool-call-model.ts' +import type { ToolCallBlock } from './tool-call-model.ts' /** * Build the TerminalBlock display copy from the conversation locale seat — @@ -88,7 +89,7 @@ export function terminalFailed(model: TerminalCardModel): boolean { function resolveTerminalCwd(viewCwd: string | undefined, sessionCwd: string | undefined): string | undefined { if (viewCwd === undefined || viewCwd === '') return sessionCwd if (sessionCwd === undefined || sessionCwd === '') return normalizeSegments(viewCwd) - return normalizeSegments(resolveToolPath(sessionCwd, viewCwd)) + return normalizeSegments(resolveWorkspacePath(sessionCwd, viewCwd)) } /** diff --git a/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts b/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts index 151ef3b45f..f201f4aac4 100644 --- a/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts +++ b/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts @@ -172,21 +172,6 @@ function deriveFilePath(variant: ToolRowVariant, argsRaw: string): string | unde return picked === undefined ? undefined : firstLine(picked) } -/** - * Resolve a tool-arg path against the session cwd for host.openPath. - * Absolute POSIX/Windows paths pass through; relative paths join under cwd. - * @param cwd - session working directory (may be absent for ungrouped sessions). - * @param path - path as carried in tool args. - * @returns a host-facing path string. - */ -export function resolveToolPath(cwd: string | undefined, path: string): string { - if (path.startsWith('/') || /^[A-Za-z]:[/\\]/.test(path) || path.startsWith('\\\\')) return path - if (cwd === undefined || cwd === '') return path - const base = cwd.replace(/[/\\]+$/, '') - const rel = path.replace(/^[/\\]+/, '') - return `${base}/${rel}` -} - function deriveBody(variant: ToolRowVariant, argsRaw: string): string | null { if (argsRaw === '') return null const parsed = parseArgs(argsRaw) diff --git a/packages/client/ui-tool/tests/tool-row.spec.tsx b/packages/client/ui-tool/tests/tool-row.spec.tsx index ab7e1c80f7..f53bcb11f7 100644 --- a/packages/client/ui-tool/tests/tool-row.spec.tsx +++ b/packages/client/ui-tool/tests/tool-row.spec.tsx @@ -5,7 +5,8 @@ import { cleanup, fireEvent, render } from '@testing-library/react' import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' -import { classifyTool, resolveToolPath, resultText, toolRowModel } from '../src/client/tool/models/tool-call-model.ts' +import { resolveWorkspacePath } from '@deepseek-ai/dsh-client-runtime/client' +import { classifyTool, resultText, toolRowModel } from '../src/client/tool/models/tool-call-model.ts' import { ToolRow } from '../src/client/tool/components/ToolRow.tsx' import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx' import { zh } from '../../ui-conversation/src/client/locales.ts' @@ -87,11 +88,11 @@ describe('tool-call-model', () => { expect(toolRowModel('bash', running()).filePath).toBeUndefined() }) - it('resolveToolPath joins relative paths under cwd and passes absolute through', () => { - expect(resolveToolPath('/w', 'src/a.ts')).toBe('/w/src/a.ts') - expect(resolveToolPath('/w/', '/abs/a.ts')).toBe('/abs/a.ts') - expect(resolveToolPath(undefined, 'src/a.ts')).toBe('src/a.ts') - expect(resolveToolPath('/w', 'C:\\x\\a.ts')).toBe('C:\\x\\a.ts') + it('resolveWorkspacePath joins relative paths under cwd and passes absolute through', () => { + expect(resolveWorkspacePath('/w', 'src/a.ts')).toBe('/w/src/a.ts') + expect(resolveWorkspacePath('/w/', '/abs/a.ts')).toBe('/abs/a.ts') + expect(resolveWorkspacePath(undefined, 'src/a.ts')).toBe('src/a.ts') + expect(resolveWorkspacePath('/w', 'C:\\x\\a.ts')).toBe('C:\\x\\a.ts') }) it('displays workspace-rooted paths relative to the session cwd', () => { From 61f3982348d4117e7f99eb8ce2b20375a568c188 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 8 Aug 2026 15:31:41 +0800 Subject: [PATCH 06/17] fix: gen docs --- docs/config-catalog.md | 1 + docs/module-graph.md | 26 +++++++++++++++++--------- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 43b8bbc4d9..1f81974b21 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -2566,6 +2566,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-client-ui-slash` ([`packages/client/ui-slash/src/index.ts`](../packages/client/ui-slash/src/index.ts)) - `@deepseek-ai/dsh-client-ui-subagent` ([`packages/client/ui-subagent/src/index.ts`](../packages/client/ui-subagent/src/index.ts)) - `@deepseek-ai/dsh-client-ui-theme` ([`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts)) +- `@deepseek-ai/dsh-client-ui-tool` ([`packages/client/ui-tool/src/index.ts`](../packages/client/ui-tool/src/index.ts)) - `@deepseek-ai/dsh-client-ui-trajectory` ([`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts)) - `@deepseek-ai/dsh-client-ui-workspace` ([`packages/client/ui-workspace/src/index.ts`](../packages/client/ui-workspace/src/index.ts)) - `@deepseek-ai/dsh-command-compact` — requires `commands` · `compact` ([`packages/compact/command-compact/src/index.ts`](../packages/compact/command-compact/src/index.ts)) diff --git a/docs/module-graph.md b/docs/module-graph.md index 14cad0163a..22af77f9c5 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -184,6 +184,7 @@ flowchart TD pkg_client_ui_slots["client-ui-slots"] pkg_client_ui_subagent["client-ui-subagent"] pkg_client_ui_theme["client-ui-theme"] + pkg_client_ui_tool["client-ui-tool"] pkg_client_ui_trajectory["client-ui-trajectory"] pkg_client_ui_workspace["client-ui-workspace"] pkg_client_web["client-web"] @@ -891,14 +892,12 @@ flowchart TD pkg_client_ui_goal --> pkg_client_ui_slots pkg_client_ui_goal --> pkg_goal pkg_client_ui_goal --> pkg_invariants - pkg_client_ui_skill --> pkg_client_connection - pkg_client_ui_skill --> pkg_client_locale - pkg_client_ui_skill --> pkg_client_runtime - pkg_client_ui_skill --> pkg_client_ui_conversation - pkg_client_ui_skill --> pkg_client_ui_primitives - pkg_client_ui_skill --> pkg_client_ui_slash - pkg_client_ui_skill --> pkg_client_ui_slots - pkg_client_ui_skill --> pkg_invariants + pkg_client_ui_tool --> pkg_client_locale + pkg_client_ui_tool --> pkg_client_runtime + pkg_client_ui_tool --> pkg_client_ui_conversation + pkg_client_ui_tool --> pkg_client_ui_primitives + pkg_client_ui_tool --> pkg_client_ui_slots + pkg_client_ui_tool --> pkg_invariants pkg_session_reference --> pkg_agent pkg_session_reference --> pkg_compact pkg_session_reference --> pkg_invariants @@ -1057,6 +1056,14 @@ flowchart TD pkg_client_ui_plan --> pkg_client_ui_slots pkg_client_ui_plan --> pkg_invariants pkg_client_ui_plan --> pkg_plan_mode + pkg_client_ui_skill --> pkg_client_connection + pkg_client_ui_skill --> pkg_client_locale + pkg_client_ui_skill --> pkg_client_runtime + pkg_client_ui_skill --> pkg_client_ui_primitives + pkg_client_ui_skill --> pkg_client_ui_slash + pkg_client_ui_skill --> pkg_client_ui_slots + pkg_client_ui_skill --> pkg_client_ui_tool + pkg_client_ui_skill --> pkg_invariants pkg_client_ui_subagent --> pkg_client_locale pkg_client_ui_subagent --> pkg_client_runtime pkg_client_ui_subagent --> pkg_client_ui_conversation @@ -1310,7 +1317,7 @@ flowchart TD | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) | | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) | | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) | -| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) | +| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) | | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) | | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) | @@ -1335,6 +1342,7 @@ flowchart TD | [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) | | [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/ui/permission) | | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) | +| [`client-ui-skill`](../packages/client/ui-skill) | `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-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) | | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) | | [`sdk-protocol`](../packages/sdk/sdk-protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | From 9c109253407eb1ff5e6e668f55b3c12061db912b Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 8 Aug 2026 15:33:51 +0800 Subject: [PATCH 07/17] fix(docs): align ui-tool package contracts --- .../feature/2026-07-28-web-terminal-card.i18n.yaml | 4 ++-- .../implemented/feature/2026-07-28-web-terminal-card.md | 6 +++--- .../implemented/feature/2026-07-28-web-terminal-card.zh.md | 6 +++--- packages/client/ui-tool/README.i18n.yaml | 4 ++-- packages/client/ui-tool/README.md | 2 +- packages/client/ui-tool/README.zh.md | 2 +- scripts/verify-package-readme-model-experience.ts | 1 + 7 files changed, 13 insertions(+), 12 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml index 0a7fb2b3ef..53dba67c61 100644 --- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-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-28-web-terminal-card.md -2026-07-28-web-terminal-card.md: 0493db4b86ce869ce5e699359e66dda70e526116 -2026-07-28-web-terminal-card.zh.md: 10137f83a25860a42e80a7b807a8aed68e86ce18 +2026-07-28-web-terminal-card.md: 026b32fed2c79533abfadc58314e2844ff556414 +2026-07-28-web-terminal-card.zh.md: 4c74d880c5795cf85f32391b27e6ffd2c5074870 diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md index 0493db4b86..026b32fed2 100644 --- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md +++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md @@ -8,11 +8,11 @@ English | [中文](2026-07-28-web-terminal-card.zh.md) The bash tool declares `card: 'terminal'` for both its call and its result ([render-intent union](../architecture/2026-07-02-tool-render-intent-union.md)): the call view carries the command, an optional model-authored description, and the working directory; the result view carries the output, exit code, and terminating signal. That view already reaches the browser — host, connection, and runtime deliver it onto `ConversationSnapshot` as `callView`/`resultView` — and the former TUI rendered it as a `$`-prompt card with an exit line and a head/tail height cap. -The Web client ignored it. `packages/client/ui-conversation/src/client/contract/tool-call-model.ts` derived every row from raw tool args, and `skeleton/DetailsPanel.tsx` flattened every tool's content blocks into one `
    ` with `white-space: pre-wrap; word-break: break-word`. Two defects followed from soft-wrapping and from having no height bound: multi-column output (`ls`, a table, box drawing) folded into a paragraph and lost the column alignment that is the whole point of that output, and a long single-column listing stretched the details panel to the length of the listing.
+The Web client ignored it. `packages/client/ui-tool/src/client/tool/models/tool-call-model.ts` derived every row from raw tool args, and `skeleton/DetailsPanel.tsx` flattened every tool's content blocks into one `
    ` with `white-space: pre-wrap; word-break: break-word`. Two defects followed from soft-wrapping and from having no height bound: multi-column output (`ls`, a table, box drawing) folded into a paragraph and lost the column alignment that is the whole point of that output, and a long single-column listing stretched the details panel to the length of the listing.
 
 ## Decision
 
-`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `ui-tool/src/client/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
+`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
 
 The component's contract:
 
@@ -27,7 +27,7 @@ Geometry, radius, and fonts mirror `CodeBlock`, so a terminal card and a fenced
 
 ### Inline output in the chat row reverses a stated convention
 
-`chat/ToolRow.tsx` and `contract/tool-call-model.ts` asserted "no inline output ever — full results live in the details panel". Showing the terminal block in the row reverses that, on the owner's explicit decision.
+`packages/client/ui-tool/src/client/tool/components/ToolRow.tsx` and `packages/client/ui-tool/src/client/tool/models/tool-call-model.ts` asserted "no inline output ever — full results live in the details panel". Showing the terminal block in the row reverses that, on the owner's explicit decision.
 
 The reason the reversal holds: for a shell command the output *is* the result the user is reading, so routing it exclusively to a panel makes the common case a two-step interaction. A bounded, height-capped, non-wrapping terminal block in the row is what makes a bash-heavy transcript readable in one pass. The old rule's actual concern was a row whose height was unbounded by the length of the output, and the height cap plus expand control is what keeps that from returning.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index 10137f83a2..4c74d880c5 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -8,11 +8,11 @@ Status: implemented
 
 bash 工具的调用与结果都声明 `card: 'terminal'`（[渲染意图联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）：调用视图携带命令、一段可选的模型撰写描述以及工作目录，结果视图携带输出、退出码与终止信号。该视图早已抵达浏览器——host、connection 与 runtime 把它投递到 `ConversationSnapshot` 的 `callView`/`resultView` 上——原 TUI 曾把它渲染为带 `$` 提示符的卡片，附退出行与首尾高度上限。
 
-Web client 却对它视而不见。`packages/client/ui-conversation/src/client/contract/tool-call-model.ts` 仅从原始工具参数推导每一行，`skeleton/DetailsPanel.tsx` 则把所有工具的内容块压平进一个 `
    `，样式为 `white-space: pre-wrap; word-break: break-word`。软换行加上没有高度约束，带来两个缺陷：多列输出（`ls`、表格、制表符绘图）被折成一段文字，丢掉了这类输出赖以存在的列对齐；而单列的长列表会把详情面板拉长到与列表等长。
+Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/models/tool-call-model.ts` 仅从原始工具参数推导每一行，`skeleton/DetailsPanel.tsx` 则把所有工具的内容块压平进一个 `
    `，样式为 `white-space: pre-wrap; word-break: break-word`。软换行加上没有高度约束，带来两个缺陷：多列输出（`ls`、表格、制表符绘图）被折成一段文字，丢掉了这类输出赖以存在的列对齐；而单列的长列表会把详情面板拉长到与列表等长。
 
 ## Decision
 
-`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`ui-tool/src/client/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
+`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
 
 该组件的契约：
 
@@ -27,7 +27,7 @@ Web client 却对它视而不见。`packages/client/ui-conversation/src/client/c
 
 ### 聊天行内嵌输出推翻了一条既有约定
 
-`chat/ToolRow.tsx` 与 `contract/tool-call-model.ts` 都断言过「绝不内嵌输出——完整结果在详情面板」。在行内显示终端块推翻了这一点，依据是 owner 的明确决定。
+`packages/client/ui-tool/src/client/tool/components/ToolRow.tsx` 与 `packages/client/ui-tool/src/client/tool/models/tool-call-model.ts` 都断言过「绝不内嵌输出——完整结果在详情面板」。在行内显示终端块推翻了这一点，依据是 owner 的明确决定。
 
 这次推翻成立的理由：对 shell 命令而言，输出**就是**用户要读的结果，把它专门收进面板会让最常见的情形变成两步交互。行内一个有界、限高、不换行的终端块，正是让 bash 密集的 transcript 一遍读完的条件。旧规则真正担心的是行高不受输出长度约束，而高度上限加展开控件正是防止其复现的机制。
 
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 828cfa25ef..eca4d1cb7b 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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-tool/README.md
-README.md: 381253f4eddaa57b89318dd23da3a049505fdd15
-README.zh.md: ae539131198771bc1d0e280bbfaa76ec0ec60792
+README.md: 69d6931d33788f2df593919d160c4bfeaef8d15c
+README.zh.md: eb49465a743711bd48358bf3953a485f9ef037eb
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index 381253f4ed..69d6931d33 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -32,7 +32,7 @@ This package currently owns the generic fallback and the built-in bash/pwsh, rea
 
 ## Model Experience
 
-None. This package renders already logged Tool calls and results and does not alter model requests, Tool execution, or session events.
+None, as this package renders already logged Tool calls and results without altering model requests, Tool execution, or session events.
 
 #### KV Cache effect
 
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index ae53913119..eb49465a74 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -32,7 +32,7 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 模型体验
 
-无。本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。
+无，因为本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。
 
 #### KV Cache 影响
 
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index ddbd7b66f8..3ca0317cf4 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -63,6 +63,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = {
   'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-tool': { kind: 'none', reason: 'Browser-side Tool presentation layer; renders logged calls without changing model context.' },
   'packages/client/ui-deliverables': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-slash': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-command': { kind: 'indirect', reason: 'The dispatch paths trigger the host command.execute RPC; each command handler\'s host package owns any model-visible effect.' },

From ab50037b93008ff2ac87b5c2df6ab8f6f632a9fa Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:59:13 +0800
Subject: [PATCH 08/17] fix(client): address tool presentation review

---
 .../2026-07-19-gui-web-client-architecture.i18n.yaml     | 4 ++--
 .../2026-07-19-gui-web-client-architecture.md            | 2 +-
 .../2026-07-19-gui-web-client-architecture.zh.md         | 2 +-
 ...26-08-08-client-tool-presentation-ownership.i18n.yaml | 4 ++--
 .../2026-08-08-client-tool-presentation-ownership.md     | 2 ++
 .../2026-08-08-client-tool-presentation-ownership.zh.md  | 2 ++
 .../feature/2026-07-30-web-diff-card.i18n.yaml           | 4 ++--
 .../implemented/feature/2026-07-30-web-diff-card.md      | 2 +-
 .../implemented/feature/2026-07-30-web-diff-card.zh.md   | 2 +-
 .../feature/2026-07-30-web-read-card-frontend.i18n.yaml  | 4 ++--
 .../feature/2026-07-30-web-read-card-frontend.md         | 2 +-
 .../feature/2026-07-30-web-read-card-frontend.zh.md      | 2 +-
 .../2026-07-30-web-result-card-frontend.i18n.yaml        | 4 ++--
 .../feature/2026-07-30-web-result-card-frontend.md       | 2 +-
 .../feature/2026-07-30-web-result-card-frontend.zh.md    | 2 +-
 .../feature/2026-07-30-web-search-card.i18n.yaml         | 4 ++--
 .../implemented/feature/2026-07-30-web-search-card.md    | 2 +-
 .../implemented/feature/2026-07-30-web-search-card.zh.md | 2 +-
 .../src/client/chat/AssistantMarkdown.tsx                | 2 +-
 .../src/client/chat/GenericCommandCard.tsx               | 2 ++
 .../ui-conversation/src/client/chat/ReasoningRow.tsx     | 6 +++++-
 .../src/client/chat/accessibility.module.css             | 8 ++++++++
 .../client/ui-conversation/src/client/contract/slots.ts  | 9 ++++++++-
 packages/client/ui-conversation/tests/chat-view.spec.tsx | 1 +
 .../client/ui-conversation/tests/reasoning-row.spec.tsx  | 2 ++
 packages/client/ui-tool/README.i18n.yaml                 | 4 ++--
 packages/client/ui-tool/README.md                        | 5 +++++
 packages/client/ui-tool/README.zh.md                     | 5 +++++
 packages/client/ui-tool/tests/ask-question-row.spec.tsx  | 2 +-
 packages/client/ui-tool/tests/coverage-tails.spec.tsx    | 2 +-
 packages/client/ui-tool/tests/diff-card.spec.tsx         | 6 +++---
 packages/client/ui-tool/tests/read-card.spec.tsx         | 6 +++---
 packages/client/ui-tool/tests/search-card.spec.tsx       | 6 +++---
 packages/client/ui-tool/tests/terminal-card.spec.tsx     | 6 +++---
 packages/client/ui-tool/tests/todo-row.spec.tsx          | 2 +-
 packages/client/ui-tool/tests/tool-call-tree.spec.tsx    | 2 +-
 packages/client/ui-tool/tests/tool-details-render.tsx    | 2 +-
 packages/client/ui-tool/tests/tool-row.spec.tsx          | 2 +-
 packages/client/ui-tool/tests/web-card.spec.tsx          | 6 +++---
 vitest.config.ts                                         | 1 +
 40 files changed, 87 insertions(+), 48 deletions(-)
 create mode 100644 packages/client/ui-conversation/src/client/chat/accessibility.module.css

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index 2dccd44aae..2357aa30f2 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: 4dc4558ea245baa17646f92b9b5e4c9a45b6a419
-2026-07-19-gui-web-client-architecture.zh.md: a306b5c82891840b96340f5464267cc9d861ef7e
+2026-07-19-gui-web-client-architecture.md: cba029ea74e89b277f9079ebb3765deeeb105b47
+2026-07-19-gui-web-client-architecture.zh.md: f700cc04fe1479d43957456c14b3abb4014d99c5
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index 4dc4558ea2..cba029ea74 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -44,7 +44,7 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer install seam), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
-There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: ui-conversation places each ordered root call into the single `'conversation.chat.tool'` seat and passes the Runtime-projected Code Dispatch children without interpreting their Tool names; ui-tool renders that root/child shape and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and both roots and children dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
+There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: ui-conversation places each ordered root call into the single `'conversation.chat.tool'` seat without interpreting Tool names or Code Dispatch topology; ui-tool selects `codeDispatches[rootCallId]` from the Runtime snapshot, renders that root/child shape, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and both roots and children dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
 
 **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index a306b5c828..f700cc04fe 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -44,7 +44,7 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：ui-conversation 把每个已排序 root call 放进 single `'conversation.chat.tool'` seat，并透传 Runtime 已投影的 Code Dispatch child，不解释其 Tool 名称；ui-tool 渲染该 root/child 形状，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与 child 都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
+slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：ui-conversation 把每个已排序 root call 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或 Code Dispatch 拓扑；ui-tool 从 Runtime snapshot 选择 `codeDispatches[rootCallId]`、渲染 root/child 形状，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与 child 都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
 
 **scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index 47adf75d40..5097b9e8a9 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
-2026-08-08-client-tool-presentation-ownership.md: 4d06450a10c4198f20d7139aef815def9e7cb362
-2026-08-08-client-tool-presentation-ownership.zh.md: 3d3bf3bc3204aca6871a82c7b7ae330b6381a3e4
+2026-08-08-client-tool-presentation-ownership.md: e61c2030457cc9f0fda214e896b76afb37d0d2bc
+2026-08-08-client-tool-presentation-ownership.zh.md: 5c56b8c17ef5ca6695f3b28f6b93218dade356c7
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
index 4d06450a10..e61c203045 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
@@ -66,6 +66,8 @@ A slot declaration also constrains render ownership. The conversation chat entry
 
 The whole seat's `ToolTreeOwnerProps` carries the root `callId`, `toolName`, `ToolCallBlock`, `selectedCallId`, session `cwd`, `openFile(path)`, and `inspectCall(callId)`. `ToolCallTree` converts either a root or child into the same `ToolCallOwnerProps` and narrows inspect to a callback for that call. The atomic owner carries no `ReactNode`, Cordis `Context`, Session service, or projector; a business view consumes only one standard call block and host actions.
 
+The seat filler also preserves the conversation DOM contract on every root and child wrapper: `data-chat-anchor-key="call:"`, `data-chat-call-id`, and `data-selected="true"` on the selected call. `ChatView` consumes the anchor key to restore prepend/paging position; the Tool owner emits it because it alone composes child wrappers.
+
 Business plugins use one registration shape:
 
 ```text
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 3d3bf3bc32..5c56b8c17e 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -66,6 +66,8 @@ slot 声明同时限定渲染所有权。conversation chat entry 通过 `childre
 
 整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。
 
+席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 契约：`data-chat-anchor-key="call:"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
+
 业务插件遵循同一个注册形态：
 
 ```text
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index ef2b3e55a0..d78733bb33 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-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-web-diff-card.md
-2026-07-30-web-diff-card.md: c8aed2aa59d82520a2a52523edb9b66d0bb34bf0
-2026-07-30-web-diff-card.zh.md: c2127844165e5f5c162eb3707fa5c86aa3a536c0
+2026-07-30-web-diff-card.md: b078da8d0e688d705683599467bd98b5c6a0be48
+2026-07-30-web-diff-card.zh.md: a9c710df99c1060bbf50b591b2f62120dc7dcbef
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
index c8aed2aa59..b078da8d0e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
@@ -14,7 +14,7 @@ This is the [terminal card](2026-07-28-web-terminal-card.md) done for the `diff`
 
 ## Decision
 
-`DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-tool/src/client/models/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change.
+`DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-tool/src/client/tool/models/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change.
 
 The component shares the TUI's single-column framing, line-terminator rule, and distinct-path file count. Line classification differs: Web renders the complete old and new sides, while the TUI derives neutral context and exact changed rows when its bounded comparison completes and labels its whole-side fallback approximate.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index c212784416..a9c710df99 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -14,7 +14,7 @@ Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行
 
 ## Decision
 
-`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
+`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/tool/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
 
 该组件与 TUI 共用单栏框架、行终止符规则和去重路径计数。两者的行分类不同：Web 渲染完整的变更前后两侧，而 TUI 会在有界比较完成时派生中性上下文和精确变更行，并把整侧回退标记为近似结果。
 
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 71ea2aabaf..3415ace63b 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: 10ed9d3eaa54c2440cf3fbd00a7e44b76c1acfe9
-2026-07-30-web-read-card-frontend.zh.md: 931316135470b7e7257f7f9d016b24fe741fdbf5
+2026-07-30-web-read-card-frontend.md: e659645066b706f35709fead4c11023eb4fe9554
+2026-07-30-web-read-card-frontend.zh.md: 4fc02e23b45399c01b5c99d388f5ae1726b026c0
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 10ed9d3eaa..e659645066 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
@@ -10,7 +10,7 @@ The [read backend](2026-07-30-web-read-card.md) added a fourth render-intent car
 
 ## 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-tool/src/client/models/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.
+`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-tool/src/client/tool/models/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.
 
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 9313161354..4fc02e23b4 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
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`ReadBlock` 是一个 `ui-primitives` 组件，把一次读取结果渲染成带行号、可选语法高亮的文件视图，读取的两个 Web 渲染点都通过它消费读取渲染意图：聊天工具行（常驻在摘要行之下）与详情面板的 Output 区段。`ui-tool/src/client/models/read-card-model.ts` 是把快照的 `resultView` 转成组件 props 的唯一位置，因此两个渲染点不会产生分歧。
+`ReadBlock` 是一个 `ui-primitives` 组件，把一次读取结果渲染成带行号、可选语法高亮的文件视图，读取的两个 Web 渲染点都通过它消费读取渲染意图：聊天工具行（常驻在摘要行之下）与详情面板的 Output 区段。`ui-tool/src/client/tool/models/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)` 行头部加剩余的尾部），因此长读取和长命令输出在同一处折叠。复制控件写入窗口的原始文本（各行以换行拼接），绝不含行号栏或横幅。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index ded72420fc..6f3a5d895b 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-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-result-card-frontend.md
-2026-07-30-web-result-card-frontend.md: 1d58710dbce3ed1aa9337e1841940195f71db40a
-2026-07-30-web-result-card-frontend.zh.md: 8705aa05557c1fdf642f498939bc2ceddde91f1f
+2026-07-30-web-result-card-frontend.md: c7e63220d824cf0bd3ac3536c528707d0db379bc
+2026-07-30-web-result-card-frontend.zh.md: 4cec11371e8d0848f2f03ded0b093d80cc25a7a5
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
index 1d58710dbc..c7e63220d8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
@@ -10,7 +10,7 @@ The `web_search` and `web_fetch` tools declare a `card: 'web'` result view ([web
 
 ## Decision
 
-`WebBlock` is a `ui-primitives` component that renders a completed web retrieval, and every Web render site for a web call consumes the `web` render intent through it: the keyed chat tool rows (`web_search`/`web_fetch`), the `GenericToolCard` render-site fallback, and the details panel's Output section. `ui-tool/src/client/models/web-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, mirroring `terminal-card-model.ts`, so no two sites disagree about what a web call shows. It returns null — the generic path — for a running call (the web card is result-only, since the tools keep a generic pending view), for a settled call whose result view is not a web card including a `card` value this client version does not know (which arrives over the wire and so cannot be trusted to be a compiled variant), for a generic result view (a web tool's error path returns the generic card, whose text the generic path preserves), and for a web card whose `kind` this client version does not know (a newer host's value off the wire, which reading as a fetch would draw as an empty URL and `HTTP undefined`).
+`WebBlock` is a `ui-primitives` component that renders a completed web retrieval, and every Web render site for a web call consumes the `web` render intent through it: the keyed chat tool rows (`web_search`/`web_fetch`), the `GenericToolCard` render-site fallback, and the details panel's Output section. `ui-tool/src/client/tool/models/web-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, mirroring `terminal-card-model.ts`, so no two sites disagree about what a web call shows. It returns null — the generic path — for a running call (the web card is result-only, since the tools keep a generic pending view), for a settled call whose result view is not a web card including a `card` value this client version does not know (which arrives over the wire and so cannot be trusted to be a compiled variant), for a generic result view (a web tool's error path returns the generic card, whose text the generic path preserves), and for a web card whose `kind` this client version does not know (a newer host's value off the wire, which reading as a fetch would draw as an empty URL and `HTTP undefined`).
 
 One component draws both kinds, discriminated by `kind`. A `search` shows the answer as markdown above a citation list; each source is a safe external link labelled by its title, or its hostname when the provider gave none, with the snippet and publication date below it, and a `来源列表已截断` indicator when the tool capped the list. A `fetch` shows a compact summary: the linked final URL, its HTTP status, and a `内容已截断` indicator. One component rather than two because both are web retrieval rendered as one card family, which is exactly the reason the contract carries them under one `card` tag with a `kind` discriminant.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index 8705aa0555..4cec11371e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
+`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/tool/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
 
 一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是契约把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
index 1578f0c73e..0cfb6b01bd 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-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-web-search-card.md
-2026-07-30-web-search-card.md: a350756a22d2ba5da8a0ff5d3a4cb3f257ac566b
-2026-07-30-web-search-card.zh.md: d6ec2a08eb02a92a50d4742c3d87c22f42c095d4
+2026-07-30-web-search-card.md: e0be857df69dfd46b6e936c775c6bae1476c26dc
+2026-07-30-web-search-card.zh.md: 1704b8f04c519511d5afa32ae6683c1e48ce7992
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
index a350756a22..e0be857df6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
@@ -12,7 +12,7 @@ This is the follow-up the search render card note names: that PR was the backend
 
 ## Decision
 
-`SearchBlock` is a `ui-primitives` component that renders a completed search as either shape, and the Web render sites for a `grep`/`glob` call consume the search render intent through it. `ui-tool/src/client/models/search-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so no render site re-derives the shape. It returns null — the generic path — whenever the result view is not a search card, including a still-running call (a search card is result-time only, so there is nothing before `execute`), a generic result a `grep`/`glob` failure or a nested `run_code` dispatch produces, a terminal result view, a `card` value this client version does not know, a `card: 'search'` view whose `shape` this version does not compile, and — because `shape` and the grouped/flat contents ride the same untrusted wire frame the host schema only string-checks — a known `shape` whose `files`/`paths` is missing or malformed (which would otherwise crash `SearchBlock` at `.reduce`/`.map`). The result-view discriminant is `shape` (not `kind`, which the backend reserves for the call view's icon-picking tag); `SearchBlock`'s own prop stays `kind`, mapped from `shape` in this derivation.
+`SearchBlock` is a `ui-primitives` component that renders a completed search as either shape, and the Web render sites for a `grep`/`glob` call consume the search render intent through it. `ui-tool/src/client/tool/models/search-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so no render site re-derives the shape. It returns null — the generic path — whenever the result view is not a search card, including a still-running call (a search card is result-time only, so there is nothing before `execute`), a generic result a `grep`/`glob` failure or a nested `run_code` dispatch produces, a terminal result view, a `card` value this client version does not know, a `card: 'search'` view whose `shape` this version does not compile, and — because `shape` and the grouped/flat contents ride the same untrusted wire frame the host schema only string-checks — a known `shape` whose `files`/`paths` is missing or malformed (which would otherwise crash `SearchBlock` at `.reduce`/`.map`). The result-view discriminant is `shape` (not `kind`, which the backend reserves for the call view's icon-picking tag); `SearchBlock`'s own prop stays `kind`, mapped from `shape` in this derivation.
 
 The asymmetry with the terminal card is deliberate and inherited from the backend contract: `terminalCardModel` reads both `callView` and `resultView` because a command, cwd, and description exist at call time; `searchCardModel` reads only `resultView` because a search's matches or paths exist only after execution. A running search row therefore shows its summary alone, with no card.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
index d6ec2a08eb..1704b8f04c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## Decision
 
-`SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-tool/src/client/models/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
+`SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-tool/src/client/tool/models/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
 
 与终端卡片的不对称是刻意的，继承自后端契约：`terminalCardModel` 同时读 `callView` 和 `resultView`，因为命令、cwd、description 在调用时就存在；`searchCardModel` 只读 `resultView`，因为搜索的匹配或路径只在执行后存在。因此运行中的搜索行只显示摘要，没有卡片。
 
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index 9d0c26506e..bbd4caa2c3 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -81,7 +81,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
             case 'text': return (
               
             )
-            case 'reasoning': return 
+            case 'reasoning': return 
             // Grouped into tool rows by ChatView; hasVisible above skips an empty shell.
             case 'tool-call': return null
             default: return (
diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index b16d838e77..d487123558 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -7,6 +7,7 @@
 import { useState, type ReactNode } from 'react'
 import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
 import { DisclosureRow, IconApiOutline14, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
+import a11yCss from './accessibility.module.css'
 import css from './GenericCommandCard.module.css'
 
 type CommandRowState = 'running' | 'ok' | 'error'
@@ -42,6 +43,7 @@ export function GenericCommandCard({ node, t }: GenericCommandCardProps) {
   const open = expanded && body !== null
   return (
     
    
+      {state === 'error' && {t('row.failed')}}
       (null)
   const summary = running ? latestLine(text) : firstLine(text)
@@ -36,6 +39,7 @@ export function ReasoningRow({ text, running }: { text: string; running: boolean
 
   return (
     
    
+      {running && {t('row.running')}}
        void
 }
 
-/** Owner currency of the chat view's whole-Tool rendering seat. */
+/**
+ * Owner currency of the chat view's whole-Tool rendering seat. The filler
+ * wraps every rendered root and child with `data-chat-anchor-key="call:"`
+ * and `data-chat-call-id=""`, plus `data-selected="true"` for the selected
+ * call. ChatView consumes those anchors to restore prepend/paging position.
+ */
 export interface ToolTreeOwnerProps {
   /** Root Tool call identity, stable across running → settled. */
   callId: CallId
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 0a25e9b198..d2589122e8 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -1269,6 +1269,7 @@ describe('ChatView', () => {
     const fv = render()
     expect(fv.container.querySelector('[data-state="error"]')).not.toBeNull()
     expect(fv.getByText('命令失败')).toBeTruthy()
+    expect(fv.getByText('失败')).toBeTruthy()
 
     // Still executing: running state with the executing copy.
     const executing = makeHarness({
diff --git a/packages/client/ui-conversation/tests/reasoning-row.spec.tsx b/packages/client/ui-conversation/tests/reasoning-row.spec.tsx
index 243b665ce2..62e6ac7848 100644
--- a/packages/client/ui-conversation/tests/reasoning-row.spec.tsx
+++ b/packages/client/ui-conversation/tests/reasoning-row.spec.tsx
@@ -47,6 +47,7 @@ describe('ReasoningRow', () => {
         streaming
       />,
     )
+    expect(view.getByText('运行中')).toBeTruthy()
     const summary = view.getByText('Newest reasoning tokens')
     Object.defineProperties(summary, {
       scrollWidth: { configurable: true, value: 300 },
@@ -76,6 +77,7 @@ describe('ReasoningRow', () => {
     )
     flushAnimationFrames(3)
     expect(view.getByText('Inspect the session')).toBeTruthy()
+    expect(view.queryByText('运行中')).toBeNull()
     expect(summary.scrollLeft).toBe(0)
     expect(summary.hasAttribute('data-follow-end')).toBe(false)
   })
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index eca4d1cb7b..79a4eef640 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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-tool/README.md
-README.md: 69d6931d33788f2df593919d160c4bfeaef8d15c
-README.zh.md: eb49465a743711bd48358bf3953a485f9ef037eb
+README.md: bf6213ebfacd8f7963463b2c443524c631c28bcd
+README.zh.md: 06a46a525eead005375bcf67794a1ceecde678bc
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index 69d6931d33..bf6213ebfa 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -10,6 +10,8 @@ Business UI packages register only their wire Tool names and atomic views. They
 
 `ToolCallTree` receives one root `ToolCallBlock`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. Through its standard session slot props it selects the Runtime-projected `codeDispatches[rootCallId]` array, then sends the root and every child through the same atomic dispatch path. The Runtime currently exposes only one Code Dispatch child level, so the renderer preserves that shape instead of inventing recursive data.
 
+Each root and child wrapper preserves the `conversation.chat.tool` call-anchor DOM contract used for paging and selection.
+
 The package also fills `conversation.details.tool` with `ToolDetails`. The row and details renderers share the same pure card models for `terminal`, `read`, `diff`, `search`, and `web` render intents. Unknown intent tags and malformed wire card data fall back to flattened Tool result text.
 
 Generic rows classify known Tool names into search, read, shell, write, edit, code, or generic variants. Running, successful, failed, and interrupted lifecycle states come only from the frozen call/result slice. File paths resolve against the session `cwd` only when the user invokes the Host open-file callback; presentation code does not read Session services.
@@ -30,6 +32,8 @@ The owner payload is `ToolCallOwnerProps`: `callId`, `toolName`, the frozen `blo
 
 This package currently owns the generic fallback and the built-in bash/pwsh, read, write/edit, grep/glob, web, todo, question, and Code Dispatch presentations. `ui-skill` demonstrates a business-owned registration for `skill`.
 
+Card-specific limits and fallback rules remain in the owning [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md), [diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md), [read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md), [search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md), and [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) notes.
+
 ## Model Experience
 
 None, as this package renders already logged Tool calls and results without altering model requests, Tool execution, or session events.
@@ -42,3 +46,4 @@ None. The package is client-only presentation.
 
 - The Runtime currently exposes one level of Code Dispatch children. The renderer sends roots and children through the same atomic path, but it does not claim an arbitrary recursive wire topology.
 - Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot.
+- Tool copy temporarily reuses the `ui-conversation` locale namespace.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index eb49465a74..06a46a525e 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -10,6 +10,8 @@ Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交
 
 `ToolCallTree` 接收一个 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，再让 root 与每个 child 经过同一条原子分发路径。Runtime 当前只暴露一层 Code Dispatch child，因此 renderer 保留该形状，不自行发明递归数据。
 
+每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 契约，供分页和 selection 使用。
+
 本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。
 
 通用行把已知 Tool 名称归类为 search、read、shell、write、edit、code 或 generic 变体。运行中、成功、失败和中断状态只来自冻结的 call/result slice。只有用户调用 Host 打开文件回调时，文件路径才相对会话 `cwd` 解析；展示代码不读取 Session service。
@@ -30,6 +32,8 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 本包当前拥有 generic fallback，以及 bash/pwsh、read、write/edit、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。`ui-skill` 展示了业务包如何拥有 `skill` 注册。
 
+各类卡片的上限与 fallback 规则仍由对应的 [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)、[diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)、[read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)、[search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md) 和 [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) Note 负责。
+
 ## 模型体验
 
 无，因为本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。
@@ -42,3 +46,4 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 - Runtime 当前只暴露一层 Code Dispatch 子调用。renderer 会让 root 和 child 经过同一个原子分发路径，但不宣称 wire 拓扑已经支持任意递归。
 - 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
+- Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-tool/tests/ask-question-row.spec.tsx b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
index 745bc2ff90..f3ab8fd3fd 100644
--- a/packages/client/ui-tool/tests/ask-question-row.spec.tsx
+++ b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
@@ -14,7 +14,7 @@ import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 // Export discipline: packages/client/AGENTS.md.
 import { AskQuestionRow, askQuestionToolview } from '../src/client/tool/toolviews/ask-question-row.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
diff --git a/packages/client/ui-tool/tests/coverage-tails.spec.tsx b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
index 720fa23255..024f97ce76 100644
--- a/packages/client/ui-tool/tests/coverage-tails.spec.tsx
+++ b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
@@ -11,7 +11,7 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { ToolRow } from '../src/client/tool/components/ToolRow.tsx'
 import { BashRow } from '../src/client/tool/toolviews/bash-sample.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 type BashRowProps = Parameters[0]
 
diff --git a/packages/client/ui-tool/tests/diff-card.spec.tsx b/packages/client/ui-tool/tests/diff-card.spec.tsx
index 0fe95c9564..a0dee040c1 100644
--- a/packages/client/ui-tool/tests/diff-card.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.spec.tsx
@@ -16,12 +16,12 @@ import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/cl
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../src/client/tool/models/diff-card-model.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { FileMutationRow, fileMutationToolview } from '../src/client/tool/toolviews/file-mutation-row.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
diff --git a/packages/client/ui-tool/tests/read-card.spec.tsx b/packages/client/ui-tool/tests/read-card.spec.tsx
index 8b528355a5..826bd72892 100644
--- a/packages/client/ui-tool/tests/read-card.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.spec.tsx
@@ -19,10 +19,10 @@ import type {
 import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { CHAT_READ_MAX_LINES, readCardModel } from '../src/client/tool/models/read-card-model.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { ReadRow, readToolview } from '../src/client/tool/toolviews/read-row.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
 
diff --git a/packages/client/ui-tool/tests/search-card.spec.tsx b/packages/client/ui-tool/tests/search-card.spec.tsx
index 02d3eab476..72e25ac32b 100644
--- a/packages/client/ui-tool/tests/search-card.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.spec.tsx
@@ -18,10 +18,10 @@ import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/cl
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { CHAT_SEARCH_MAX_LINES, searchCardModel } from '../src/client/tool/models/search-card-model.ts'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { SearchRow, searchToolview } from '../src/client/tool/toolviews/search-row.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
 
diff --git a/packages/client/ui-tool/tests/terminal-card.spec.tsx b/packages/client/ui-tool/tests/terminal-card.spec.tsx
index 34c5744c01..93a538c5c0 100644
--- a/packages/client/ui-tool/tests/terminal-card.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.spec.tsx
@@ -16,12 +16,12 @@ import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/cl
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { terminalCardModel, terminalFailed } from '../src/client/tool/models/terminal-card-model.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { BashRow } from '../src/client/tool/toolviews/bash-sample.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 type BashRowProps = Parameters[0]
 
diff --git a/packages/client/ui-tool/tests/todo-row.spec.tsx b/packages/client/ui-tool/tests/todo-row.spec.tsx
index 326821fc4e..ef3253a947 100644
--- a/packages/client/ui-tool/tests/todo-row.spec.tsx
+++ b/packages/client/ui-tool/tests/todo-row.spec.tsx
@@ -8,7 +8,7 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import { TodoRow, todoToolview } from '../src/client/tool/toolviews/todo-row.tsx'
 import { planSummary } from '../src/client/tool/toolviews/plan-summary.ts'
 import { CONVERSATION_NS as NS } from '../src/client/locale.ts'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 type TodoRowProps = Parameters[0]
 
diff --git a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
index 76b24bc7ac..0720ba5642 100644
--- a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
@@ -7,7 +7,7 @@ import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import type { ToolTreeProps } from '../src/client/contract/slots.ts'
 import { ToolCallTree } from '../src/client/tool/ToolCallTree.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
diff --git a/packages/client/ui-tool/tests/tool-details-render.tsx b/packages/client/ui-tool/tests/tool-details-render.tsx
index e61cd0aaa7..0aeb3c5321 100644
--- a/packages/client/ui-tool/tests/tool-details-render.tsx
+++ b/packages/client/ui-tool/tests/tool-details-render.tsx
@@ -1,7 +1,7 @@
 /** Test adapter for the production conversation.details.tool registration. */
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionProviderComponent, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
-import type { DetailsSlotProps, DetailsToolOwnerProps } from '../../ui-conversation/src/client/contract/slots.ts'
+import type { DetailsSlotProps, DetailsToolOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/src/client/contract/slots.ts'
 import { ToolDetails } from '../src/client/tool/ToolDetails.tsx'
 
 /** Framework session-area seat used by direct DetailsPanel tests. */
diff --git a/packages/client/ui-tool/tests/tool-row.spec.tsx b/packages/client/ui-tool/tests/tool-row.spec.tsx
index f53bcb11f7..02189e3634 100644
--- a/packages/client/ui-tool/tests/tool-row.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.spec.tsx
@@ -9,7 +9,7 @@ import { resolveWorkspacePath } from '@deepseek-ai/dsh-client-runtime/client'
 import { classifyTool, resultText, toolRowModel } from '../src/client/tool/models/tool-call-model.ts'
 import { ToolRow } from '../src/client/tool/components/ToolRow.tsx'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(() => {
   cleanup()
diff --git a/packages/client/ui-tool/tests/web-card.spec.tsx b/packages/client/ui-tool/tests/web-card.spec.tsx
index 743b450ca7..b8a5a4e06c 100644
--- a/packages/client/ui-tool/tests/web-card.spec.tsx
+++ b/packages/client/ui-tool/tests/web-card.spec.tsx
@@ -19,14 +19,14 @@ import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ToolCallOwnerProps } from '@deepseek-ai/dsh-client-ui-tool/client'
 import { webCardModel } from '../src/client/tool/models/web-card-model.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { WebRow, webToolview } from '../src/client/tool/toolviews/web-row.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
diff --git a/vitest.config.ts b/vitest.config.ts
index 597bca5618..6eb1bda354 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -162,6 +162,7 @@ export default defineConfig({
         'packages/client/web-react/src/*',
         'packages/client/runtime/src/*',
         'packages/client/ui-conversation/src/*',
+        'packages/client/ui-primitives/src/DisclosureRow.tsx',
         'packages/client/ui-tool/src/*',
         'packages/client/ui-slots/src/*',
         'packages/client/ui-layout/src/*',

From 810bfc4b5e2287349256cc9a35a170b4351a9f35 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 16:27:09 +0800
Subject: [PATCH 09/17] fix: ci

---
 .../ui-conversation/src/client/chat/GenericCommandCard.tsx      | 2 +-
 .../client/ui-conversation/src/client/chat/ReasoningRow.tsx     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index d487123558..9d34ef3015 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -42,7 +42,7 @@ export function GenericCommandCard({ node, t }: GenericCommandCardProps) {
   const body = text !== undefined && text.includes('\n') ? text : null
   const open = expanded && body !== null
   return (
-    
    
+    
    
       {state === 'error' && {t('row.failed')}}
       
+    
    
       {running && {t('row.running')}}
       
Date: Sat, 8 Aug 2026 16:43:29 +0800
Subject: [PATCH 10/17] fix(client): keep compact row in conversation package

---
 .../src/client/chat/CompactionCommandCard.tsx      | 14 +-------------
 .../src/client/chat/GenericCommandCard.tsx         |  6 ++++--
 2 files changed, 5 insertions(+), 15 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
index 8012834541..c2f0191d85 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
@@ -3,11 +3,9 @@
 // generic command card so no-history, cancellation, and failures retain their
 // complete handler-authored text.
 
-import { IconApiOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
 import { CompactionItem } from './CompactionItem.tsx'
 import { GenericCommandCard } from './GenericCommandCard.tsx'
-import { ToolRow } from './ToolRow.tsx'
 
 interface CompactionCommandCardProps extends CommandRowOwnerProps {
   t: ChatViewSlotProps['t']
@@ -26,15 +24,5 @@ export function CompactionCommandCard({ node, compaction, t }: CompactionCommand
     )
   }
   if (node.outcome !== null) return 
-  return (
-    }
-      title="compact"
-      summary={t('message.compaction.running')}
-      body={null}
-      state="running"
-    />
-  )
+  return 
 }
diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index 9d34ef3015..9137181265 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -25,13 +25,15 @@ function leadingFor(state: CommandRowState): ReactNode {
 /** Card props: the owner payload plus the render site's locale seat (plain prop). */
 export interface GenericCommandCardProps extends CommandRowOwnerProps {
   t: ChatViewSlotProps['t']
+  /** Command-specific running copy; absent uses the generic command label. */
+  runningSummary?: string | undefined
 }
 
-export function GenericCommandCard({ node, t }: GenericCommandCardProps) {
+export function GenericCommandCard({ node, t, runningSummary }: GenericCommandCardProps) {
   const [expanded, setExpanded] = useState(false)
   const text = node.outcome?.text
   const summary = node.outcome === null
-    ? t('command.running')
+    ? runningSummary ?? t('command.running')
     : text ?? (node.outcome.kind === 'error' ? t('command.failed') : t('command.done'))
   // Title is the bare command name: the row already reads `name · outcome`,
   // and the dispatched line's own `/` and arguments only restate what the

From 3b31b2eba19c702ecd455ebc22ea8741c03ef2af Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 16:50:30 +0800
Subject: [PATCH 11/17] fix: ci

---
 packages/client/ui-conversation/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 2a396a8404..24e7e70f27 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
-README.md: c4c7a0363c0a2760cf478744073eab96d837b719
-README.zh.md: a34f99f7e4e50750b2ecf024ed9e898c8de09529
+README.md: 837edaa097d47ebfb72d027616a18fdfeed8a488
+README.zh.md: 419799666dc0689f8fe754d4c9de6d5dcf7fb09c

From 871c59c3bcfd0f76e671f9eba4ca1a49451db272 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:12:54 +0800
Subject: [PATCH 12/17] fix(client): address tool tree review

---
 .../src/client/chat/GenericCommandCard.tsx    |  1 +
 .../ui-conversation/tests/chat-view.spec.tsx  |  1 +
 .../ui-tool/src/client/tool/ToolCallTree.tsx  | 31 ++++++++++---------
 .../ui-tool/tests/tool-call-tree.spec.tsx     |  2 ++
 4 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index 9137181265..676e433fa5 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -45,6 +45,7 @@ export function GenericCommandCard({ node, t, runningSummary }: GenericCommandCa
   const open = expanded && body !== null
   return (
     
    
+      {state === 'running' && {t('row.running')}}
       {state === 'error' && {t('row.failed')}}
        {
     const xv = render()
     expect(xv.container.querySelector('[data-state="running"]')).not.toBeNull()
     expect(xv.getByText('执行中…')).toBeTruthy()
+    expect(xv.getByText('运行中')).toBeTruthy()
 
     // Cross-window soft-fall (run page truncated): generic title, outcome preserved.
     const orphan = makeHarness({
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
index 8091f26dff..3c71e2f4d4 100644
--- a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
@@ -1,5 +1,5 @@
 /** Root/subcall Tool composition with one keyed atomic dispatch path. */
-import { memo, useMemo } from 'react'
+import { memo, useMemo, type ReactNode } from 'react'
 import type { CodeSubCall, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ToolCallOwnerProps, ToolTreeProps } from '../contract/slots.ts'
 import { GenericToolCard } from './toolviews/GenericToolCard.tsx'
@@ -12,12 +12,13 @@ function subCallName(node: CodeSubCall): string {
 
 /** One atomic call dispatched through the Tool-owned keyed slot. */
 const ToolCall = memo(function ToolCall({
-  renderSlot, callId, toolName, block, openFile, selected, cwd, inspectCall, t,
+  renderSlot, callId, toolName, block, openFile, selected, cwd, inspectCall, t, children,
 }: Pick & {
   callId: string
   toolName: string
   block: ToolCallBlock
   selected: boolean
+  children?: ReactNode
 }) {
   const owner: ToolCallOwnerProps = useMemo(() => ({
     callId,
@@ -38,6 +39,7 @@ const ToolCall = memo(function ToolCall({
         entryKey: toolName,
         fallback: ,
       })}
+      {children}
     
    
   )
 })
@@ -53,18 +55,17 @@ export function ToolCallTree({
 }: ToolTreeProps) {
   const subCalls = useSession(snapshot => snapshot.codeDispatches.get(callId))
   return (
-    <>
-      
+    
       {subCalls !== undefined && subCalls.length > 0 ? (
         
    
           {subCalls.map(node => (
@@ -83,6 +84,6 @@ export function ToolCallTree({
           ))}
         
    
       ) : null}
-    
+        
   )
 }
diff --git a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
index 0720ba5642..c8c31ad365 100644
--- a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
@@ -57,6 +57,8 @@ describe('ToolCallTree', () => {
     const view = render(
       ,
     )
+    expect(view.container.querySelector('[data-subcalls]')?.parentElement)
+      .toBe(view.container.querySelector('[data-chat-call-id="parent"]'))
     expect(view.container.querySelector('[data-chat-call-id="parent"]')?.hasAttribute('data-selected')).toBe(false)
     expect(view.container.querySelector('[data-chat-call-id="parent:code:1"]')?.getAttribute('data-selected')).toBe('true')
   })

From 5934bbc32e34d733a81a57a9daf0e9a9a31caa9a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:17:14 +0800
Subject: [PATCH 13/17] docs(skills): preserve browser GIF evidence chains

---
 ...08-08-browser-gif-evidence-chain.i18n.yaml |  6 +++
 .../2026-08-08-browser-gif-evidence-chain.md  | 37 +++++++++++++++++++
 ...026-08-08-browser-gif-evidence-chain.zh.md | 37 +++++++++++++++++++
 .agents/skills/record-browser-gif/SKILL.md    | 32 ++++++++++------
 4 files changed, 100 insertions(+), 12 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md

diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
new file mode 100644
index 0000000000..ea763ef0e8
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.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/process/2026-08-08-browser-gif-evidence-chain.md
+2026-08-08-browser-gif-evidence-chain.md: 9fe24b211e7094d4769af50c8b0ceae5c43fb4be
+2026-08-08-browser-gif-evidence-chain.zh.md: a84ea46373d8684389ce0c8c61887906e1fdc025
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
new file mode 100644
index 0000000000..9fe24b211e
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
@@ -0,0 +1,37 @@
+# Agent Note: Browser GIFs preserve one evidence chain
+
+Status: implemented
+
+English | [中文](2026-08-08-browser-gif-evidence-chain.zh.md)
+
+## Problem
+
+A browser-demo storyboard can contain individually truthful screenshots without proving one truthful execution. Reusing global application state can admit old settings or sessions, capture automation can accidentally combine frames from separate model runs, and a chat transcript can show a successful fallback without exposing the tool rejection that caused it. Fuzzy accessible-name matching can also accept prompt echoes or descendant text instead of the intended result.
+
+Headless production recording has two further boundaries. A product default may open a native operating-system surface that automation cannot drive, while replacing that surface with a mock or test hook would change the provenance. After publication, a successful git push does not prove that a private-repository GIF is fetchable or that GitHub recognizes the pull-request Markdown as an image.
+
+## Decision
+
+The [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) workflow treats one storyboard as one evidence chain pinned to an exact pull-request head. Each run uses fresh `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, and session state, and every published frame comes from the same server and model-backed scenario run. A failed capture run is discarded and repeated from fresh roots rather than combined with another run.
+
+Browser automation waits for unique, exact semantic states. When the claim concerns a tool call, rejection, or recovery, the storyboard includes a detail or trajectory frame that identifies the tool, shows its status or stable error code, and shows the downstream result. The final encoded GIF remains the verification subject; when a viewer cannot animate it, representative frames are decoded from that GIF instead of treating source screenshots as equivalent evidence.
+
+The available browser-control workflow remains preferred. When it is unavailable, the recorder uses the repository-declared Playwright dependency in an isolated headless browser rather than installing another driver or opening the user's browser. A native production surface may be replaced only through normal application configuration with an official browser-operable production backend, and that override is stated in the provenance. Fixtures, mock transports, synthetic events, and test-only hooks do not substantiate a real-production claim.
+
+Publication verifies the boundary again. The assets branch contains media only, the staged and published bytes match the verified artifact, and a private-repository asset is checked through authenticated API or raw requests for its path, byte size, checksum, response status, and media type. This proves the repository-member review path only; the [documentation-site image decision](2026-08-06-doc-site-carries-its-images.md) owns why a public site cannot depend on a private raw URL. Immediately before the pull-request body changes, the live head must still equal the recorded head; GitHub's Markdown renderer must then produce the expected image without changing that code head.
+
+## Alternatives considered
+
+**Allow frames from separate runs when their visible states look equivalent.** Visual similarity does not establish shared state, causal order, or one scenario execution. Re-recording costs another real round but preserves the claim the storyboard makes.
+
+**Use the chat transcript as sufficient proof of tool recovery.** A final answer proves that the task completed, but it can hide which tool ran, whether the failure was structured, and whether the model recovered from that failure. A trajectory or detail frame carries those facts directly.
+
+**Replace inaccessible native UI with a fixture or test hook.** That makes automation easier by changing the product path under observation. Selecting an official production backend through normal configuration keeps the exercised implementation real and makes the narrower mode explicit.
+
+**Trust a successful assets-branch push or an anonymous fetch.** A push proves only that git accepted bytes, while private repositories intentionally reject unauthenticated raw requests. Authenticated byte verification plus GitHub Markdown rendering tests the two publication boundaries that reviewers use.
+
+## Consequences
+
+GUI evidence now establishes one causal execution rather than a collage of plausible states, and reviewers can inspect both a structured tool failure and the completed result. Publication detects stale pull-request heads, corrupted or misplaced media, and invalid image Markdown before the body is treated as finished.
+
+The workflow spends additional scratch state, may repeat a real model round after a capture failure, and usually adds a detail frame plus authenticated publication checks. Headless recordings can use fewer production backends than an interactive desktop, and every such selection remains part of the stated provenance.
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
new file mode 100644
index 0000000000..a84ea46373
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 浏览器 GIF 保留单一证据链
+
+Status: implemented
+
+[English](2026-08-08-browser-gif-evidence-chain.md) | 中文
+
+## 问题
+
+浏览器演示的分镜可以由每张都真实的截图组成，却无法证明这些截图来自同一次真实执行。复用应用全局状态可能引入旧设置或旧会话；录制自动化可能误将不同模型运行的画面合并；聊天 transcript（文本记录）可能显示降级处理成功，却没有揭示触发降级的工具拒绝。按无障碍名称进行模糊匹配，还可能误把提示词回显或后代文本当成预期结果。
+
+无头模式下的生产环境录制还有两道边界。产品默认配置可能打开自动化无法操控的原生操作系统界面，而用 mock 或测试钩子替换该界面会改变证据来源。发布之后，git 推送成功也不能证明私有仓库中的 GIF 可以获取，或 GitHub 能将 PR（Pull Request）的 Markdown 识别为图片。
+
+## 决策
+
+[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区和会话状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
+
+浏览器自动化会等待唯一且精确的语义状态。如果需要证明工具调用、拒绝或恢复，分镜就必须包含详情帧或轨迹帧：标明工具、显示其状态或稳定错误码，并展示后续结果。最终编码出的 GIF 始终是验证对象；如果查看器无法播放动画，应从该 GIF 中解码出代表性帧，而不能将源截图视为等效证据。
+
+仍应优先使用已有的浏览器控制工作流。如果该工作流不可用，录制程序应在隔离的无头浏览器中使用仓库已声明的 Playwright 依赖，而不是安装其他驱动或打开用户的浏览器。只有通过正常应用配置选用官方且可由浏览器操作的生产后端，才能替换原生生产界面，并且必须在证据来源说明中注明这一覆盖。fixture（测试前置数据）、mock 传输层、合成事件和测试专用钩子均不能支撑真实生产实现的主张。
+
+发布环节会再次验证边界。资产分支只包含媒体文件，暂存和发布的字节必须与已验证产物一致；对于私有仓库中的资产，应通过经身份验证的 API 或原始内容请求，检查其路径、字节大小、校验和、响应状态和媒体类型。这只能证明仓库成员的评审访问路径；[文档站点图片决策](2026-08-06-doc-site-carries-its-images.md)解释了公共站点为何不能依赖私有的原始内容 URL。修改 PR 正文之前，必须再次确认在线 head 仍与录制时的 head 相同；随后还必须确认 GitHub 的 Markdown 渲染器生成了预期图片，且代码 head 没有改变。
+
+## 曾考虑的替代方案
+
+**只要可见状态看起来等价，就允许使用不同运行的画面。**视觉相似不能证明各画面共享同一状态、具有因果顺序或来自同一次场景执行。重新录制需要再执行一次真实模型场景，但能维持整套分镜所表达的主张。
+
+**将聊天 transcript 视为工具恢复的充分证据。**最终答案能证明任务已经完成，却可能隐藏调用了哪个工具、失败是否为结构化失败，以及模型是否从该失败中恢复。轨迹帧或详情帧可以直接承载这些事实。
+
+**使用 fixture 或测试钩子替换无法访问的原生 UI。**这种做法通过改变被观察的产品路径来简化自动化。通过正常配置选用官方生产后端，既能保持受测实现真实，也能明确表述所采用的较窄运行模式。
+
+**相信资产分支推送成功或匿名请求成功。**推送只能证明 git 接受了相应字节，而私有仓库会有意拒绝未经身份验证的原始内容请求。经身份验证的字节校验与 GitHub Markdown 渲染验证，覆盖了评审者实际使用的两道发布边界。
+
+## 后果
+
+GUI 证据现在能证明一次具有因果关系的执行，而不是将若干可信状态拼成集合；评审者既可以检查结构化的工具失败，也可以检查最终完成的结果。在 PR 正文被视为完成之前，发布验证可以发现陈旧的 PR head、损坏或位置错误的媒体文件，以及无效的图片 Markdown。
+
+该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次由真实模型驱动的场景；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每次选择这类后端时，都必须将其写入证据来源说明。
diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md
index 074b8b176e..c34c47d9d7 100644
--- a/.agents/skills/record-browser-gif/SKILL.md
+++ b/.agents/skills/record-browser-gif/SKILL.md
@@ -7,6 +7,8 @@ description: Record browser or Web UI interaction demos as optimized GIFs using
 
 Produce a short, truthful UI demonstration as a local GIF, and — only when the task includes attaching it to a pull request — publish it through the assets-branch workflow at the end of this skill. Use the browser-control skill for interaction and the bundled encoder for repeatable timing, dimensions, and size.
 
+The [evidence-chain decision](../../notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md) owns why one storyboard comes from one isolated run and why publication revalidates both the artifact and the demonstrated pull-request head.
+
 ## Every GUI pull request includes a GIF
 
 A pull request that changes product-user-visible GUI behavior MUST include a demonstration GIF recorded with this skill and embedded in the pull request body via [the assets-branch workflow](#publish-to-an-assets-branch).
@@ -25,22 +27,24 @@ The GIF's provenance is part of the evidence and must be real: a real server boo
 A GIF for a specific pull request demonstrates that pull request's tree, so stage per pull request:
 
 1. Build the branch tree being demonstrated — here, `pnpm run build && pnpm run build:web` — from the worktree that holds that branch. A GIF recorded against another branch's build misattributes the evidence.
-2. Boot one server per port from that tree, giving each recording a fresh scratch workspace directory so leftover sessions cannot appear in frames. Source the root `.env` for the API key through the application's normal path; never echo the key.
-3. Start a new session for each recorded scenario so earlier turns do not pollute the frames.
+2. Boot one server per port from that tree with fresh scratch `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, and session state so settings or sessions from another run cannot affect the evidence. Source the root `.env` for the API key through the application's normal path; never echo the key.
+3. Treat one storyboard as one evidence run: every published frame comes from that server and those state roots, workspace, session, and model-backed scenario run. If capture automation fails, discard its frames and rerun from fresh roots; never splice frames from separate runs.
 4. When switching between pull requests, stop the old server by PID or an exact match on its command line. A broad `pkill -f` pattern can match and kill the shell that launched it — including your own.
 
 ## Record the flow
 
-1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. Use the user's existing Chrome state only when requested or required.
+1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. If it is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback in the provenance.
 2. Resolve the evidence boundary before recording: identify the exact origin, whether the app is built or in development, the transport, and any fixture or mock mode. Record only claims that the observed setup supports.
-3. Choose three to six states that tell one story, such as typed, running, settled, and detail. Prefer semantic state changes over continuous capture; omit loading churn that does not help the viewer.
-4. Keep one viewport and crop for every frame, and name frames lexically: `00-initial.png`, `01-typed.png`, and so on.
-5. Store frames under the repository's gitignored `.playwright-mcp/` directory — browser-tool screenshots can only be written under the tool's allowed roots, and relative filenames resolve against the repository root. Create the frame subdirectory first (`mkdir -p .playwright-mcp/gif-frames-