fix: 分页问题

.agents/notes/implemented/bug-fix/2026-08-12-full-session-turn-step-counts.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-12-full-session-turn-step-counts.md
+2026-08-12-full-session-turn-step-counts.md: 7cea57e429d3ffc2da49c4a1359ee3489663ccc5
+2026-08-12-full-session-turn-step-counts.zh.md: 93e46cfb7ffa4f397b85ee80b26cca9f664d246a

.agents/notes/implemented/bug-fix/2026-08-12-full-session-turn-step-counts.md

@@ -0,0 +1,38 @@
+# Agent Note: Full-session stats-strip figures through a sessionStats projection
+
+Status: implemented
+
+English | [中文](2026-08-12-full-session-turn-step-counts.zh.md)
+
+## Problem
+
+The web chat stats strip folded `StatsLine`'s loaded conversation window (`deriveStats` over `chat.legacy.nodes`) for every non-token figure: the "N turns · M steps" counter, the LLM and tool wall times, and the TTFT/throughput averages. History is paged 50 messages at a time, so each 加载更早 (Load earlier) click grew the window and every figure with it — 7 turns · 44 steps became 10 turns · 89 steps after one page, and the LLM duration climbed the same way. The product expectation is whole-session figures independent of how much history a client has loaded. Token accounting in the same strip already had the correct architecture: the durable `tokenUsage` projection.
+
+## Decision
+
+A new function plugin `@deepseek-ai/dsh-session-stats` registers a `sessionStats` projection unit on `ctx.sessionProjections`, mounted as a web-app bundle row. The value carries the strip's whole non-token figure set — `{ turns, steps, llmMs, toolMs, ttftMs, ttftSteps, decodeMs, decodeTokens }`, field names mirroring the window fold so the two swap wholesale. `steps` counts `step/end` events and `turns` counts distinct turns carrying at least one (turn numbers are monotonic, so one `lastTurn` slot suffices); `llmMs` sums `step/start` → `assistant/message`; TTFT records the first non-empty delta chunk per step (surviving in-step `llm/retry`, the window `resetForRetry` parity); decode spans first token → assembled message on usage-reporting steps; `toolMs` pairs `tool/call` → `tool/result` by callId with unresolved calls dropped at `turn/end`. The first-token predicate `isTokenDelta` moved to `@deepseek-ai/dsh-llm/message` (the `StreamChunk` vocabulary owner) so the host fold and the client timing index share one implementation; client-runtime re-exports it. Delivery is entirely the existing projection seam — history tail-page block, `session/projection` push frames, list rows — with zero changes to apiproxy, wire schemas, or the client runtime. `StatsLine` reads `useProjection('sessionStats')` and falls back to the window fold when the key is undefined (an assembly without the unit). The client connection fixture mirrors the fold as `sessionStatsOf` under its existing every-composed-key discipline.
+
+`step/end` — not `assistant/message` — is the counted event, for two correctness reasons found while reviewing the obvious message-counting design:
+
+1. A max-tokens step appends an empty-content `assistant/message` that exists only to host usage and never reaches the surface; counting messages would count a step the transcript does not show.
+2. A cancelled step aborts before its message assembles (no `assistant/message` at all), yet the client synthesizes a visible interrupted assistant node; counting messages would silently drop common cancelled steps.
+
+`step/end` is appended exactly once per entered step, in the loop's `finally`, so completed, failed, cancelled, and max-tokens steps all land one — and the counter advances at step settlement, the same moment the window fold advanced, so live behavior does not shift.
+
+## Alternatives considered
+
+**Count `assistant/message` events.** Rejected for the two correctness defects above (overcounts usage-host messages, undercounts cancelled steps).
+
+**Count `step/start` events.** Equivalent coverage (it precedes every `step/end`), but the counter would advance when a step begins instead of when it settles — a visible live-behavior change with no benefit; `step/end`'s `finally` placement gives the same completeness.
+
+**Register the unit in `core/agent-loop` (the event producer).** The loop is the product spine; a UI read model there adds a session-projection dependency to every assembly, against "plugins, not loop changes" and "keep opt-ins out of shipped defaults".
+
+**Register the unit in `token-meter` (an existing fold over the same events).** Turn/step counting is not token measurement; every projection key lives in the package owning its domain.
+
+**Fold the full log client-side.** The client holds only the paged window by design; the projection RFC's no-client-folding rule exists exactly so figures survive paging, compaction, and cold reads.
+
+**Keep wall times, TTFT, and throughput window-scoped.** The first shipped cut did, reading them as "what is on screen"; the same paging complaint immediately applied to the LLM duration, and a strip mixing whole-log counts with window-scoped times reads as one inconsistent figure set. The projection now carries the whole set, with the window fold demoted to the no-unit fallback.
+
+## Consequences
+
+The strip shows whole-log figures from the first tail page; paging leaves every group fixed. Defined edge differences from the old window semantics are documented in the package README: a step that produced no visible output (failed before content) still counts, a step truncated by a crash between `step/start` and `step/end` does not, a cancelled step is counted but contributes no wall time (no message assembled), and a max-tokens usage-host message contributes model time the surface does not show. Every web tail page and list row carries one more small key, and the unit's internal state changes on step boundaries and first-token chunks, so the change feed emits a few value-identical frames per step; TUI and headless assemblies serve no `sessionStats` key and any consumer falls back to window folding. Two e2e probes that had parsed the strip as a loaded-window measure (`chat-scroll-contract`, `complex-history.perf`) now count mounted flow rows / turn-tail footers instead. The `stats-paged-history` web scenario seeds a 28-turn log cold and pins that the whole strip reads full totals on a partial tail page and does not move across Load earlier.

.agents/notes/implemented/bug-fix/2026-08-12-full-session-turn-step-counts.zh.md

@@ -0,0 +1,38 @@
+# Agent Note: 通过 sessionStats 投影提供全会话统计条数字
+
+Status: implemented
+
+[English](2026-08-12-full-session-turn-step-counts.md) | 中文
+
+## 问题
+
+Web 聊天统计条的每个非 token 数字都折算自 `StatsLine` 已加载的会话窗口（`deriveStats` 遍历 `chat.legacy.nodes`）：「N 轮 · M 步」计数、LLM 与工具墙钟时间、TTFT／吞吐平均值。历史按每页 50 条消息分页，因此每点一次「加载更早」窗口变大、所有数字随之增长——7 轮 · 44 步在翻一页后变成 10 轮 · 89 步，LLM 时长同样攀升。产品预期是与客户端加载了多少历史无关的全会话数字。同一统计条里的 token 账目早已采用正确架构：持久的 `tokenUsage` 投影。
+
+## 决定
+
+新的函数插件 `@deepseek-ai/dsh-session-stats` 在 `ctx.sessionProjections` 上注册 `sessionStats` 投影单元，作为 web-app bundle 行挂载。值携带统计条完整的非 token 数字集——`{ turns, steps, llmMs, toolMs, ttftMs, ttftSteps, decodeMs, decodeTokens }`，字段名与窗口折叠一一对应以便整体互换。`steps` 统计 `step/end` 事件，`turns` 统计含至少一条该事件的不同 turn（turn 号单调递增，一个 `lastTurn` 槽即可）；`llmMs` 累加 `step/start` → `assistant/message`；TTFT 记录每步首个非空 delta chunk（在步内 `llm/retry` 后保留，与窗口 `resetForRetry` 对齐）；解码时长覆盖首 token → 已组装消息、仅统计上报 usage 的步；`toolMs` 按 callId 配对 `tool/call` → `tool/result`，未解决的调用在 `turn/end` 时丢弃。首 token 谓词 `isTokenDelta` 移入 `@deepseek-ai/dsh-llm/message`（`StreamChunk` 词汇的属主），Host 折叠与客户端计时索引共用同一实现；client-runtime 转发导出。投递完全复用现有投影缝——history 尾页块、`session/projection` 推送帧、列表行——apiproxy、wire schema 与客户端运行时零改动。`StatsLine` 读取 `useProjection('sessionStats')`，键为 undefined（未组合该单元的装配）时整体回退到窗口折叠。客户端 connection fixture 按其「镜像每个已组合键」的既有纪律以 `sessionStatsOf` 平行实现该折叠。
+
+计数事件选 `step/end` 而非 `assistant/message`，源于评审直觉方案（按消息计数）时发现的两个正确性问题：
+
+1. max-tokens 步会追加一条仅为承载 usage 而存在的空内容 `assistant/message`，它从不进入 surface；按消息计数会把 transcript 上看不到的步计进去。
+2. 被取消的步在消息组装前就中止（完全没有 `assistant/message`），但客户端会合成可见的 interrupted assistant 节点；按消息计数会悄悄丢掉常见的取消步。
+
+`step/end` 对每个进入的步在循环的 `finally` 中恰好追加一次，因此完成、失败、取消、max-tokens 的步都恰好落一条——且计数在步结算时推进，与窗口折算推进的时机相同，直播期行为不发生变化。
+
+## 备选方案
+
+**统计 `assistant/message` 事件。** 因上述两个正确性缺陷否决（多计 usage 宿主消息、少计被取消的步）。
+
+**统计 `step/start` 事件。** 覆盖等价（它先于每条 `step/end`），但计数会在步开始而非结算时推进——一个没有收益的可见直播期行为变化；`step/end` 的 `finally` 位置给出同等完整性。
+
+**把单元注册进 `core/agent-loop`（事件生产方）。** 循环是产品主干；把 UI 读模型放进去会给每个装配加上 session-projection 依赖，违反「用插件而非改循环」与「默认组合不带可选项」。
+
+**把单元注册进 `token-meter`（折叠同批事件的现有单元）。** 轮/步计数不是 token 度量；每个投影键都住在拥有其领域的包里。
+
+**在客户端折叠全量日志。** 客户端按设计只持有分页窗口；投影 RFC 的「不在客户端折叠」规则正是为了让数字在分页、压缩与冷读之间存活。
+
+**墙钟时间、TTFT 与吞吐保持窗口口径。** 首个交付版本如此，将其解读为「屏幕上有什么」；同样的分页问题立刻落在 LLM 时长上，且全量计数与窗口时间混在一条统计条里读起来是一套自相矛盾的数字。投影现在携带完整集合，窗口折叠降级为无单元时的回退。
+
+## 后果
+
+统计条从第一个尾页起就显示全日志数字；翻页不再改变任何分组。与旧窗口语义的已定义边缘差异记录在包 README 中：未产生可见输出的步（在内容之前失败）仍计入；崩溃恰好截断在 `step/start` 与 `step/end` 之间的步不计；被取消的步计数但不计时（没有组装出消息）；max-tokens 的 usage 宿主消息贡献 surface 上看不到的模型时间。每个 web 尾页与列表行多携带一个小键，且单元内部状态在步边界与首 token chunk 处变化，变更流每步会多发几帧值相同的推送；TUI 与 headless 装配不提供 `sessionStats` 键，其消费者回退窗口折叠。两个曾把统计条当作已加载窗口探针解析的 e2e（`chat-scroll-contract`、`complex-history.perf`）改为统计已挂载的消息流行／turn-tail 页脚。`stats-paged-history` web 场景冷种一份 28 轮日志，钉住整条统计条在不完整尾页上即读出全量数字、且「加载更早」前后不变。

apps/web/tests/chat-scroll-contract.e2e.ts

@@ -250,13 +250,16 @@ function scrollGeometry(page: Page): Promise<ScrollGeometry> {
   }))
 }
 
-async function conversationTurns(page: Page): Promise<number> {
-  const stats = page.getByText(/\d+ turns · \d+ steps/, { exact: true }).last()
-  await stats.waitFor({ timeout: 15_000 })
-  const value = await stats.textContent()
-  const match = value?.match(/^(\d+) turns · \d+ steps$/)
-  if (match?.[1] === undefined) throw new Error(`unexpected conversation stats ${JSON.stringify(value)}`)
-  return Number(match[1])
+/**
+ * Rendered transcript rows in the loaded window. The stats strip cannot serve
+ * as this probe: its turn/step counts ride the whole-log sessionStats
+ * projection and stay fixed across paging by design, while the row count is
+ * exactly what grows when an older page prepends or a live turn streams in.
+ * @param page - the scenario page.
+ * @returns the number of mounted chat flow rows.
+ */
+async function loadedFlowRows(page: Page): Promise<number> {
+  return page.locator('[data-chat-flow-key]').count()
 }
 
 async function openSeed(page: Page, fixture: ChatScrollFixture, tailMarker?: string): Promise<void> {
@@ -425,9 +428,9 @@ async function loadEarlierWithAnchor(page: Page): Promise<void> {
   const older = page.getByRole('button', { name: 'Load earlier', exact: true })
   await older.waitFor({ timeout: 10_000 })
   const anchor = await visibleFlowAnchor(page)
-  const before = await conversationTurns(page)
+  const before = await loadedFlowRows(page)
   await older.click()
-  await expect.poll(() => conversationTurns(page), { timeout: 30_000 }).toBeGreaterThan(before)
+  await expect.poll(() => loadedFlowRows(page), { timeout: 30_000 }).toBeGreaterThan(before)
   await nextPaint(page)
   await expectSameFlowTop(page, anchor)
 }
@@ -498,7 +501,7 @@ describe('web e2e: long Chat scroll contract', () => {
         await world.page.getByRole('button', { name: 'Send message', exact: true }).click()
         await world.page.getByText(LIVE_TEXT_FIRST, { exact: false }).last().waitFor({ timeout: 15_000 })
         await wheelToHistoryStart(world.page)
-        const beforeTurns = await conversationTurns(world.page)
+        const beforeRows = await loadedFlowRows(world.page)
         await world.page.getByRole('button', { name: 'Load earlier', exact: true }).click()
         await expect.poll(() => held, { timeout: 10_000 }).toBe(true)
 
@@ -511,7 +514,7 @@ describe('web e2e: long Chat scroll contract', () => {
         ).toBeGreaterThan(chunksAfterAnchor + 5)
 
         releaseHistory()
-        await expect.poll(() => conversationTurns(world.page), { timeout: 30_000 }).toBeGreaterThan(beforeTurns)
+        await expect.poll(() => loadedFlowRows(world.page), { timeout: 30_000 }).toBeGreaterThan(beforeRows)
         await nextPaint(world.page)
         await expectSameFlowTop(world.page, readerAnchor)
       } finally {
@@ -531,7 +534,11 @@ describe('web e2e: long Chat scroll contract', () => {
         additionalPages += 1
       }
       expect(additionalPages).toBeGreaterThan(0)
-      expect(await conversationTurns(world.page)).toBe(HISTORY_FIXTURE.turns + 1)
+      // The whole log is loaded: turn 1's unique marker renders in the
+      // transcript (scoped: the sidebar search row also carries it) and no
+      // page remains.
+      expect(await world.page.locator('[data-conversation-scroll]')
+        .getByText(HISTORY_FIXTURE.markers.user(1), { exact: false }).count()).toBe(1)
       expect(await world.page.getByRole('button', { name: 'Load earlier', exact: true }).count()).toBe(0)
       assertClean(world)
     })

apps/web/tests/complex-history.perf.ts

@@ -797,12 +797,11 @@ async function stableCount(
 }
 
 async function conversationTurns(page: Page): Promise<number> {
-  const stats = page.getByText(/\d+ turns · \d+ steps/, { exact: true }).last()
-  await stats.waitFor({ timeout: 15_000 })
-  const value = await stats.textContent()
-  const match = value?.match(/^(\d+) turns · \d+ steps$/)
-  if (match?.[1] === undefined) throw new Error(`unexpected conversation stats ${JSON.stringify(value)}`)
-  return Number(match[1])
+  // Loaded-window turn count: one mounted turn-tail footer per settled turn in
+  // the window (context keys are `${kind.length}:${kind}${id}`). The stats
+  // strip cannot serve as this probe: its counts ride the whole-log
+  // sessionStats projection and stay fixed across paging by design.
+  return stableCount(page.locator('[data-chat-flow-key^="9:turn-tail"]'), count => count > 0)
 }
 
 function retainedDelta(

apps/web/tests/seeded-history.e2e.ts

@@ -256,6 +256,12 @@ describe('web e2e: seeded history renders through cold resume', () => {
     // client's "omitted key = capability absent → clear the row" rule from
     // wiping preset-owned projections on cold reads.
     expect(projections?.values).toHaveProperty('todos', null)
+    // The session-stats unit is a shipped web-app bundle row: whole-log
+    // turn/step counts ride the same tail block (the stats strip's source).
+    const sessionStats = projections?.values.sessionStats as { turns: number; steps: number } | undefined
+    expect(sessionStats).toBeDefined()
+    expect(sessionStats?.turns).toBeGreaterThanOrEqual(1)
+    expect(sessionStats?.steps).toBeGreaterThanOrEqual(sessionStats?.turns ?? 0)
   })
 
   it.skipIf(MODE === 'record')('lists the seeded session cold and renders its history from the log', async () => {

apps/web/tests/snapshots/live-interactions/error-auth.expected.md

@@ -24,3 +24,4 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
+- text: 1 turns · 1 steps Input 0 tok · Output 0 tok

apps/web/tests/snapshots/stats-paged-history/ui.expected.md

@@ -0,0 +1,242 @@
+- banner:
+  - navigation "Session hierarchy":
+    - button "{{workspace}}" [disabled]
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: m1 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r1
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m2 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r2
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m3 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r3
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m4 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r4
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m5 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r5
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m6 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r6
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m7 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r7
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m8 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r8
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m9 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r9
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m10 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r10
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m11 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r11
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m12 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r12
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m13 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r13
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m14 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r14
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m15 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r15
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m16 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r16
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m17 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r17
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m18 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r18
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m19 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r19
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m20 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r20
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m21 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r21
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m22 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r22
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m23 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r23
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m24 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r24
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m25 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r25
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m26 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r26
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m27 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r27
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}} m28 7/25 {{clock}}
+- button "Copy":
+  - img
+- paragraph: r28
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: 7/25 {{clock}} Ran for {{duration}}
+- button "Back to bottom":
+  - img
+- textbox "Message the agent"
+- button "Commands":
+  - img
+- 'button "Access mode, current: Workspace Write"': Workspace Write
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
+  - img
+- button "Send message" [disabled]
+- text: 28 turns · 28 steps LLM {{duration}} Input 0 tok · Output 0 tok

apps/web/tests/stats-paged-history.e2e.ts

@@ -0,0 +1,136 @@
+// Web e2e scenario: full-session stats over paged history. A deterministic
+// 28-turn log (56 surface messages — more than one 50-message history page)
+// seeded cold through the REAL persistence API must render whole-log turn/step
+// counts from the sessionStats projection on first open, and loading the
+// older page must NOT change them. This pins the bug the projection fixed:
+// the pre-projection window fold recounted per loaded page, so 加载更早 grew
+// the counter. Zero model calls; the seed is generated, not recorded, because
+// no line of it is model output.
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import {
+  assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/stats-paged-history', import.meta.url))
+const UI_EXPECTED = fileURLToPath(new URL('./snapshots/stats-paged-history/ui.expected.md', import.meta.url))
+const MODE = webSnapshotMode()
+const SEED_ID = 'stats-paged-history-web-e2e'
+
+/** Turn count: 2 surface messages per turn, so 28 turns overflow one 50-message page. */
+const TURNS = 28
+const FULL_COUNTS = `${TURNS} turns · ${TURNS} steps`
+
+/**
+ * Generate the seed: TURNS closed single-step turns of one short user prompt
+ * and one short assistant reply each. Times are fixed so the fixture is
+ * byte-deterministic; message ids are synthetic uuids (aria normalizes them).
+ * @param turns - closed turns to generate.
+ * @returns session.jsonl text for {@link seedSession}.
+ */
+function buildSeed(turns: number): string {
+  const lines = [JSON.stringify({
+    type: 'session', version: 0, id: '{{sessionId}}', createdAt: 1784974100000, cwd: '{{cwd}}/workspace',
+  })]
+  let seq = 0
+  let time = 1784974100000
+  const at = (event: Record<string, unknown>): void => {
+    lines.push(JSON.stringify({ ...event, seq: seq++, time: time++ }))
+  }
+  for (let turn = 1; turn <= turns; turn++) {
+    at({ type: 'turn/start', data: { turn } })
+    at({
+      type: 'user/message',
+      data: { content: [{ type: 'text', text: `m${turn}` }], source: { kind: 'user' } },
+      surfaceOp: 'append',
+    })
+    at({ type: 'step/start', data: { turn, step: 1 } })
+    at({
+      type: 'assistant/message',
+      data: {
+        turn,
+        step: 1,
+        message: {
+          id: `00000000-0000-4000-8000-${String(turn).padStart(12, '0')}`,
+          role: 'assistant',
+          content: [{ type: 'text', text: `r${turn}` }],
+          source: { kind: 'model', provider: 'snapshot', model: 'snapshot-replier' },
+        },
+      },
+      sourceEventSeqs: [],
+      surfaceOp: 'append',
+    })
+    at({ type: 'step/end', data: { turn, step: 1 } })
+    at({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
+  }
+  return `${lines.join('\n')}\n`
+}
+
+describe('web e2e: whole-session stats survive history paging', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    if (MODE === 'record') throw new Error('stats-paged-history is a keyless assembled snapshot')
+    scaffold = await launchWebScaffold({})
+    await seedSession(scaffold, buildSeed(TURNS), SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it('renders full-session counts on the partial tail page and keeps them across load-older', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-stats-paged'))
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+    // Settled barrier: the newest recorded reply renders from the tail page.
+    await expect.poll(() => page.getByText(`r${TURNS}`, { exact: true }).count(), { timeout: 15_000 }).toBe(1)
+    // The tail page is partial (56 messages > one 50-message page): the first
+    // turns are NOT loaded, yet the strip already reports the whole log —
+    // the sessionStats projection, not the window fold.
+    expect(await page.getByText('m1', { exact: true }).count()).toBe(0)
+    await expect.poll(() => page.getByText(FULL_COUNTS, { exact: false }).count(), { timeout: 10_000 }).toBe(1)
+    const strip = page.getByText(FULL_COUNTS, { exact: false }).locator('..')
+    const stripBeforePaging = await strip.textContent()
+
+    // 加载更早: prepending the older page must not move ANY strip figure —
+    // counts, wall times, or token groups.
+    await page.getByRole('button', { name: 'Load earlier' }).click()
+    await expect.poll(() => page.getByText('m1', { exact: true }).count(), { timeout: 10_000 }).toBe(1)
+    expect(await strip.textContent()).toBe(stripBeforePaging)
+    // With the whole log loaded, the window mounts one turn-tail footer per
+    // settled turn — the loaded-window probe the scroll/perf lanes count now
+    // that the strip is whole-log-scoped.
+    expect(await page.locator('[data-chat-flow-key^="9:turn-tail"]').count()).toBe(TURNS)
+  }, 60_000)
+
+  it('matches the paged-stats aria golden', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-stats-paged-aria'))
+    const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
+      .split(SEED_ID).join('{{seededId}}')
+    await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
+  })
+
+  it('issued zero model calls and stayed clean', async () => {
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+    await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
+  })
+})

apps/web/tsconfig.json

@@ -48,6 +48,7 @@
     "tests/replay-round-trip.e2e.ts",
     "tests/hmr-live.e2e.ts",
     "tests/seeded-history.e2e.ts",
+    "tests/stats-paged-history.e2e.ts",
     "tests/sidebar-scrollbar.e2e.ts",
     "tests/conversation-column-overflow.e2e.ts",
     "tests/code-mode-round.e2e.ts",

docs/config-catalog.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: 2bb1f315e02c3f4bab379593227f1c381818a9fa
-config-catalog.zh.md: 4be51942de65a7e8afdaf71a44573ba1cdd6230d
+config-catalog.md: f4feae3a31d9aa1798e0b06c2b72f43278a01281
+config-catalog.zh.md: a0068a6c0372022d05eae1a49ec6cd89f2625261

docs/config-catalog.md

@@ -2798,6 +2798,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-session` ([`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts))
 - `@deepseek-ai/dsh-session-checkpoint-policy` — requires `llm` · `sessionPersistence` · `sessions` · `tools` ([`packages/session/session-checkpoint-policy/src/index.ts`](../packages/session/session-checkpoint-policy/src/index.ts))
 - `@deepseek-ai/dsh-session-projection` ([`packages/session/session-projection/src/index.ts`](../packages/session/session-projection/src/index.ts))
+- `@deepseek-ai/dsh-session-stats` — requires `sessionProjections` ([`packages/session/session-stats/src/index.ts`](../packages/session/session-stats/src/index.ts))
 - `@deepseek-ai/dsh-skill-badge` — requires `skills` ([`packages/skill/skill-badge/src/index.ts`](../packages/skill/skill-badge/src/index.ts))
 - `@deepseek-ai/dsh-storage` ([`packages/storage/storage/src/index.ts`](../packages/storage/storage/src/index.ts))
 - `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts))

docs/config-catalog.zh.md

@@ -2799,6 +2799,7 @@ export interface Config {
 - `@deepseek-ai/dsh-session`（[`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts)）
 - `@deepseek-ai/dsh-session-checkpoint-policy` — 需要 `llm` · `sessionPersistence` · `sessions` · `tools`（[`packages/session/session-checkpoint-policy/src/index.ts`](../packages/session/session-checkpoint-policy/src/index.ts)）
 - `@deepseek-ai/dsh-session-projection`（[`packages/session/session-projection/src/index.ts`](../packages/session/session-projection/src/index.ts)）
+- `@deepseek-ai/dsh-session-stats` — 需要 `sessionProjections`（[`packages/session/session-stats/src/index.ts`](../packages/session/session-stats/src/index.ts)）
 - `@deepseek-ai/dsh-skill-badge` — 需要 `skills`（[`packages/skill/skill-badge/src/index.ts`](../packages/skill/skill-badge/src/index.ts)）
 - `@deepseek-ai/dsh-storage`（[`packages/storage/storage/src/index.ts`](../packages/storage/storage/src/index.ts)）
 - `@deepseek-ai/dsh-subagent`（[`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts)）

packages/bundle/web-app/cordis.patch.yml

@@ -74,6 +74,11 @@
         writeEveryEvents: 200
         writeIntervalMs: 5000
 
+    # Whole-log turn/step counts for the chat stats strip (the sessionStats
+    # projection key); the projection registry itself is a base-layer row.
+    - id: session-stats
+      name: '@deepseek-ai/dsh-session-stats'
+
     # Resolve bind host, SSH launch, and display once at boot, then mount the
     # matching dual-face directory picker. Mount -native or -browse directly in
     # an overlay to pin the interaction.

packages/bundle/web-app/package.json

@@ -89,6 +89,7 @@
     "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-message-feedback": "workspace:^",
     "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
+    "@deepseek-ai/dsh-session-stats": "workspace:^",
     "@deepseek-ai/dsh-storage": "workspace:^",
     "@deepseek-ai/dsh-storage-domain": "workspace:^",
     "@deepseek-ai/dsh-storage-json": "workspace:^",

packages/client/connection/src/client/fixture.ts

@@ -9,6 +9,7 @@ import {
   createAssistantMessage,
   createToolResultMessage,
   createUserMessage,
+  isTokenDelta,
 } from '@deepseek-ai/dsh-llm/message'
 import { CallId } from '@deepseek-ai/dsh-llm/brand'
 import type {
@@ -861,6 +862,76 @@ function tokenUsageOf(log: readonly SessionEvent[]): FixtureTokenUsageProjection
   return totals
 }
 
+/** Fixture parallel of session-stats' whole-log counting and wall-time fold. */
+function sessionStatsOf(log: readonly SessionEvent[]): {
+  turns: number
+  steps: number
+  llmMs: number
+  toolMs: number
+  ttftMs: number
+  ttftSteps: number
+  decodeMs: number
+  decodeTokens: number
+} {
+  const value = { turns: 0, steps: 0, llmMs: 0, toolMs: 0, ttftMs: 0, ttftSteps: 0, decodeMs: 0, decodeTokens: 0 }
+  let lastTurn: number | null = null
+  let openStep: { turn: number; step: number; startTime: number; firstTokenTime: number | null } | null = null
+  const pendingCalls = new Map<string, number>()
+  for (const event of log) {
+    switch (event.type) {
+      case 'step/start':
+        openStep = { turn: event.data.turn, step: event.data.step, startTime: event.time, firstTokenTime: null }
+        break
+      case 'assistant/chunk':
+        if (openStep !== null && openStep.turn === event.data.turn && openStep.step === event.data.step
+          && openStep.firstTokenTime === null && isTokenDelta(event.data.chunk)) {
+          openStep.firstTokenTime = event.time
+        }
+        break
+      case 'assistant/message': {
+        if (openStep === null || openStep.turn !== event.data.turn || openStep.step !== event.data.step) break
+        value.llmMs += Math.max(0, event.time - openStep.startTime)
+        if (openStep.firstTokenTime !== null) {
+          value.ttftMs += Math.max(0, openStep.firstTokenTime - openStep.startTime)
+          value.ttftSteps += 1
+          const outputTokens = event.data.usage?.outputTokens
+          if (typeof outputTokens === 'number' && Number.isFinite(outputTokens) && outputTokens >= 0) {
+            value.decodeMs += Math.max(0, event.time - openStep.firstTokenTime)
+            value.decodeTokens += outputTokens
+          }
+        }
+        openStep = null
+        break
+      }
+      case 'tool/call':
+        pendingCalls.set(event.data.callId, event.time)
+        break
+      case 'tool/result': {
+        const callId = event.data.message.source.callId
+        const dispatched = pendingCalls.get(callId)
+        if (dispatched === undefined) break
+        pendingCalls.delete(callId)
+        value.toolMs += Math.max(0, event.time - dispatched)
+        break
+      }
+      case 'step/end':
+        if (event.data.turn !== lastTurn) {
+          value.turns += 1
+          lastTurn = event.data.turn
+        }
+        value.steps += 1
+        openStep = null
+        break
+      case 'turn/end':
+        pendingCalls.clear()
+        break
+      default:
+        break
+    }
+  }
+  return value
+}
+
 interface FixtureRequestContext {
   provider: string
   model: string
@@ -979,6 +1050,8 @@ function projectionValuesOf(log: readonly SessionEvent[]): Record<string, unknow
   values['contextPressure'] = contextPressureOf(log)
   // Always present (token-meter composed): heuristic request composition.
   values['contextBreakdown'] = contextBreakdownOf(log)
+  // Always present (session-stats unit composed): whole-log turn/step counts.
+  values['sessionStats'] = sessionStatsOf(log)
   return values
 }
 
@@ -1014,6 +1087,17 @@ function projectionFramesOf(id: SessionId, log: readonly SessionEvent[], event:
       seq: event.seq,
     })
   }
+  // The stats fold's view advances on message assembly and tool settlement
+  // (wall times) and on step close (counts).
+  if (type === 'assistant/message' || type === 'tool/result' || type === 'step/end') {
+    frames.push({
+      type: 'session/projection',
+      sessionId: id,
+      key: 'sessionStats',
+      value: sessionStatsOf(log),
+      seq: event.seq,
+    })
+  }
   if (frames.length > 0) return frames
   if (type === 'session/title') {
     const values = projectionValuesOf(log)

packages/client/connection/tests/fixture.client.spec.ts

@@ -164,6 +164,10 @@ describe('createFixtureApi', () => {
           toolsTokens: 0,
           messageTokens: 0,
         },
+        // Session-stats unit composed: no figure accrues on the empty log.
+        sessionStats: {
+          turns: 0, steps: 0, llmMs: 0, toolMs: 0, ttftMs: 0, ttftSteps: 0, decodeMs: 0, decodeTokens: 0,
+        },
       } },
     })
   })
@@ -353,7 +357,7 @@ describe('createFixtureApi', () => {
       const envelopes: RpcRequest<MuxFrame>[] = []
       for await (const envelope of api.events.mux(req({}), abort.signal)) {
         envelopes.push(envelope)
-        if (envelopes.length >= 11) abort.abort()
+        if (envelopes.length >= 12) abort.abort()
       }
       return envelopes
     }
@@ -374,10 +378,12 @@ describe('createFixtureApi', () => {
       value: { systemTokens: 0, toolsTokens: 0 },
     })
     expect((first[8]?.payload as { value: { messageTokens: number } }).value.messageTokens).toBeGreaterThan(0)
-    expect(first[9]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
-    expect(second[9]?.rpcId).toBe(first[9]?.rpcId) // stable rpcId across replays (host replay semantics)
-    expect(first[10]?.payload).toMatchObject({ type: 'question/requested', sessionId: 'fx-alpha' })
-    expect(second[10]?.rpcId).toBe(first[10]?.rpcId)
+    expect(first[9]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'sessionStats' })
+    expect((first[9]?.payload as { value: { turns: number; steps: number } }).value.steps).toBeGreaterThan(0)
+    expect(first[10]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
+    expect(second[10]?.rpcId).toBe(first[10]?.rpcId) // stable rpcId across replays (host replay semantics)
+    expect(first[11]?.payload).toMatchObject({ type: 'question/requested', sessionId: 'fx-alpha' })
+    expect(second[11]?.rpcId).toBe(first[11]?.rpcId)
   })
 
   it('steer with no replay in flight falls through to a fresh queued turn; non-text blocks stringify empty', async () => {

packages/client/runtime/src/client/sessions/assistant-timing.ts

@@ -2,9 +2,14 @@
 // history fold derive AssistantTiming from the same step/start -> first token
 // delta -> assistant/message sequence.
 
+import { isTokenDelta } from '@deepseek-ai/dsh-llm/message'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { AssistantTiming } from './conversation.ts'
 
+// The first-token predicate lives with the StreamChunk vocabulary in dsh-llm;
+// re-exported here so Chat Definitions keep their client-runtime import.
+export { isTokenDelta } from '@deepseek-ai/dsh-llm/message'
+
 /** Pre-finalize timing boundaries for one assistant step (start + first token). */
 export interface AssistantStepMetadata {
   stepStartTime: number | null
@@ -21,24 +26,6 @@ export function assistantStepKey(turn: number, step: number): string {
   return `${turn}\u0000${step}`
 }
 
-/**
- * Whether a chunk carries visible model output (first-token boundary). Empty
- * deltas (heartbeats, empty tool-call frames) do not count as a first token.
- * @param chunk - the assistant/chunk payload.
- * @returns true when the chunk contains a non-empty text/reasoning/tool delta.
- */
-export function isTokenDelta(chunk: SessionEvent<'assistant/chunk'>['data']['chunk']): boolean {
-  switch (chunk.type) {
-    case 'text-delta':
-    case 'reasoning-delta':
-      return chunk.text !== ''
-    case 'tool-call-delta':
-      return chunk.argumentsDelta !== '' || chunk.name !== undefined
-    default:
-      return false
-  }
-}
-
 /**
  * Fold one event into the per-step timing index: step/start opens the entry,
  * the first non-empty token delta stamps first-token time once. Other event

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: ed8f888d35693ecaa2667ea432b462f4bb3369cf
-README.zh.md: e6a2dd0b545b66ab01b213b5ebc937e22af8ac1a
+README.md: 6d0f3d0a088ad580d55d524699a7bf8d2806b724
+README.zh.md: 70f828d29512eb5e25a873a8fce2b4ffad6380fc

packages/client/ui-conversation/package.json

@@ -70,6 +70,7 @@
     "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm-retry": "workspace:^",
+    "@deepseek-ai/dsh-session-stats": "workspace:^",
     "@deepseek-ai/dsh-token-meter": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "react": "^18.2.0"
@@ -98,6 +99,7 @@
     "@deepseek-ai/dsh-permission": "workspace:^",
     "@deepseek-ai/dsh-plan-mode": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-stats": "workspace:^",
     "@deepseek-ai/dsh-token-meter": "workspace:^",
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",

packages/client/ui-conversation/src/client/chat/StatsLine.tsx

@@ -6,6 +6,8 @@ import { Fragment, memo, useLayoutEffect, useMemo, useRef, useState } from 'reac
 import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ConversationSnapshot, UseProjection } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: merges the sessionStats key into SessionProjectionMap for useProjection.
+import type {} from '@deepseek-ai/dsh-session-stats/client'
 import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
 import type { ComposerBarProps } from '../contract/slots.ts'
 import { formatTokensPerSecond } from './message-chrome.ts'
@@ -30,14 +32,16 @@ interface WindowStats {
 }
 
 /**
- * Fold assistant and tool-result nodes into the window-scoped display totals.
+ * Fold assistant and tool-result nodes into window-scoped display totals —
+ * the FALLBACK for assemblies without the `sessionStats` projection.
  *
- * Counts and wall times describe the loaded window on purpose — they answer
- * "what is on screen". Token accounting deliberately does NOT come from here:
- * the window is paged and compaction rewrites it, so billing rides the durable
- * `tokenUsage` projection instead.
+ * Every displayed figure rides that durable whole-log projection (and token
+ * accounting rides `tokenUsage`) because the window is paged and compaction
+ * rewrites it; this fold answers "what is on screen" only when no projection
+ * value is served. Its field names deliberately mirror the projection's so
+ * the two swap wholesale.
  * @param nodes - snapshot nodes.
- * @returns visible counts and summed wall times.
+ * @returns fallback counts and summed wall times.
  */
 export function deriveStats(nodes: ConversationSnapshot['nodes']): WindowStats {
   const turns = new Set<number>()
@@ -158,8 +162,12 @@ export interface StatsLineProps {
 
 export const StatsLine = memo(function StatsLine({ useSession, useProjection, t }: StatsLineProps) {
   const settledNodes = useSession(s => s.chat.legacy.nodes)
-  const stats = useMemo(() => deriveStats(settledNodes), [settledNodes])
+  const windowStats = useMemo(() => deriveStats(settledNodes), [settledNodes])
   const usage = useProjection('tokenUsage')
+  // Every figure rides the durable sessionStats projection, so paging and
+  // compaction cannot change any of them; an assembly without the unit falls
+  // back to the window-scoped fold wholesale (same field names).
+  const stats = useProjection('sessionStats') ?? windowStats
   // Pipe-separated groups (figma stats strip); a group with no data drops out whole.
   const groups: string[] = []
   if (stats.steps > 0) {
@@ -168,7 +176,6 @@ export const StatsLine = memo(function StatsLine({ useSession, useProjection, t
     if (stats.llmMs > 0) durations.push(t('stats.llm', { duration: formatDuration(stats.llmMs) }))
     if (stats.toolMs > 0) durations.push(t('stats.toolCall', { duration: formatDuration(stats.toolMs) }))
     if (durations.length > 0) groups.push(durations.join(' · '))
-    // Window-scoped like the wall times above: averages describe loaded steps.
     const speeds: string[] = []
     if (stats.ttftSteps > 0) {
       speeds.push(t('stats.ttftAverage', { duration: formatDuration(stats.ttftMs / stats.ttftSteps) }))

packages/client/ui-conversation/tests/chat-stats.client.spec.tsx

@@ -98,9 +98,11 @@ describe('deriveStats', () => {
     ])
     expect(stats.turns).toBe(2)
     expect(stats.steps).toBe(3)
-    // Window-scoped by design: the paged window is not an accounting source, so
-    // the fold exposes no billing fields (billing rides the projection);
-    // decodeTokens is a throughput input, not a billed total.
+    // The window fold's counts are only the fallback for assemblies without
+    // the sessionStats projection; the paged window is not an accounting
+    // source either, so the fold exposes no billing fields (billing rides the
+    // tokenUsage projection); decodeTokens is a throughput input, not a
+    // billed total.
     expect(Object.keys(stats).sort()).toEqual(
       ['decodeMs', 'decodeTokens', 'llmMs', 'steps', 'toolMs', 'ttftMs', 'ttftSteps', 'turns'],
     )
@@ -169,6 +171,14 @@ describe('formatters', () => {
 describe('StatsLine', () => {
   const USAGE = { uncachedInputTokens: 10, outputTokens: 5, cacheReadTokens: 90, cacheWriteTokens: 0 }
 
+  /** A whole-log sessionStats value: zeros plus overrides. */
+  function sessionStats(overrides: Record<string, number>): Record<string, number> {
+    return {
+      turns: 0, steps: 0, llmMs: 0, toolMs: 0, ttftMs: 0, ttftSteps: 0, decodeMs: 0, decodeTokens: 0,
+      ...overrides,
+    }
+  }
+
   /** Stub the projection seat: a key-addressed table of whole values. */
   function projections(values: Record<string, unknown>): StatsLineProps['useProjection'] {
     return (key: string) => values[key]
@@ -281,6 +291,58 @@ describe('StatsLine', () => {
     expect(view.container.textContent).toBe('1 turns · 1 steps')
   })
 
+  it('renders whole-session counts from the sessionStats projection over the paged window', () => {
+    // The bug's acceptance at unit level: one loaded page must not scope the
+    // counter — the durable projection's totals win over the window fold.
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      sessionStats: sessionStats({ turns: 10, steps: 89 }),
+    })} />)
+    expect(view.container.textContent)
+      .toBe('10 turns · 89 steps| Cache hit 90%| Input 100 tok · Output 5 tok')
+  })
+
+  it('treats a defined zero-count projection as empty, not as fallback', () => {
+    // A composed unit always serves the key; all-zero genuinely means no
+    // closed step in the whole log, so nothing renders on a brand-new session.
+    const empty = makeSource()
+    const view = render(<StatsLine {...props(empty.source, {
+      tokenUsage: { uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
+      sessionStats: sessionStats({}),
+    })} />)
+    expect(view.container.textContent).toBe('')
+  })
+
+  it('keeps the counts group over an empty visible window when the projection carries totals', () => {
+    // Extends the durable-groups guarantee: full-session counts survive a
+    // window that compaction (or paging) left without assistant nodes.
+    const { source } = makeSource()
+    const view = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      sessionStats: sessionStats({ turns: 7, steps: 44 }),
+    })} />)
+    expect(view.container.textContent)
+      .toBe('7 turns · 44 steps| Cache hit 90%| Input 100 tok · Output 5 tok')
+  })
+
+  it('renders whole-log wall times and speeds from the projection, not the loaded window', () => {
+    // The 加载更早 hazard beyond counts: LLM/tool durations and the TTFT and
+    // throughput figures must not grow per loaded page either. An untimed
+    // 1-node window renders the projection's whole-log figures verbatim.
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      sessionStats: sessionStats({
+        turns: 200, steps: 200, llmMs: 100_000, toolMs: 62_000,
+        ttftMs: 1_600, ttftSteps: 2, decodeMs: 3_000, decodeTokens: 60,
+      }),
+    })} />)
+    expect(view.container.textContent).toBe(
+      '200 turns · 200 steps| LLM 1m40s · Tool call 1m2s| TTFT avg 0.8s · 20 tok/s| Cache hit 90%| Input 100 tok · Output 5 tok',
+    )
+  })
+
   it('omits cache hit when nothing was billed on the input side', () => {
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
     const view = render(<StatsLine {...props(source, {

packages/client/ui-conversation/tests/gate-branch-tails.client.spec.tsx

@@ -70,9 +70,11 @@ describe('render branch tails', () => {
     expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull()
   })
 
-  it('StatsLine counts window nodes but drops every token group without a projection', () => {
-    // Node `usage` is deliberately ignored: billing rides the durable
-    // tokenUsage projection, so an absent projection leaves counts only.
+  it('StatsLine falls back to window-node counts and drops every token group without projections', () => {
+    // No sessionStats key → the window fold supplies the counts (the
+    // assembly-without-the-unit fallback). Node `usage` is deliberately
+    // ignored: billing rides the durable tokenUsage projection, so an absent
+    // projection leaves counts only.
     const nodes = [
       { kind: 'assistant', seq: 1, time: 1, turn: 1, step: 1, blocks: [] },
       { kind: 'assistant', seq: 2, time: 2, turn: 1, step: 2, blocks: [], usage: { inputTokens: 4, outputTokens: 6 } },

packages/client/ui-conversation/tsconfig.json

@@ -44,6 +44,9 @@
     {
       "path": "../../session/session-projection"
     },
+    {
+      "path": "../../session/session-stats"
+    },
     {
       "path": "../../llm/token-meter"
     },

packages/llm/llm/src/message.ts

@@ -2,7 +2,7 @@
 
 import { MessageId, type CallId } from './brand.ts'
 import { deepFreeze } from './call-config.ts'
-import type { ContentBlock, ToolResultBlock } from './types.ts'
+import type { ContentBlock, StreamChunk, ToolResultBlock } from './types.ts'
 
 /** Provider/model identity and adapter-private replay data for an assistant message. */
 export interface AssistantProvenance {
@@ -239,3 +239,23 @@ export function createToolResultMessage(input: ToolResultMessageInput): ToolResu
     }],
   })
 }
+
+/**
+ * Whether a stream chunk carries visible model output (the first-token
+ * boundary shared by client step timing and the whole-log sessionStats
+ * projection). Empty deltas (heartbeats, empty tool-call frames) do not count
+ * as a first token.
+ * @param chunk - the stream chunk to test.
+ * @returns true when the chunk contains a non-empty text/reasoning/tool delta.
+ */
+export function isTokenDelta(chunk: StreamChunk): boolean {
+  switch (chunk.type) {
+    case 'text-delta':
+    case 'reasoning-delta':
+      return chunk.text !== ''
+    case 'tool-call-delta':
+      return chunk.argumentsDelta !== '' || chunk.name !== undefined
+    default:
+      return false
+  }
+}

packages/session/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/session/README.md
-README.md: 586d1be0286a0de935b0b08313e6965452b85376
-README.zh.md: 60e58e6d471a48d3ced03a518e96aeeae79110e8
+README.md: 64aa8e4fdf1e85d74dfa0a77803a04e881b547c4
+README.zh.md: 520e969cbf623ac4a0a3dc82b6fb54f12ba8ffa3

packages/session/README.md

@@ -25,6 +25,7 @@ Serves current, log-derived per-session state to client carriers.
 |---|---|---|
 | [`session-projection/`](session-projection/README.md) | Defines and drives session projection units | `ctx.sessionProjections` |
 | [`session-projection-cache/`](session-projection-cache/README.md) | Persists and restores projection checkpoints | `ctx.sessionProjectionCache` |
+| [`session-stats/`](session-stats/README.md) | Serves whole-log conversation counts and wall times (`sessionStats` unit) | registers on `ctx.sessionProjections` |
 
 ## Titles
 

packages/session/README.zh.md

@@ -25,6 +25,7 @@
 |---|---|---|
 | [`session-projection/`](session-projection/README.md) | 定义并驱动会话投影单元 | `ctx.sessionProjections` |
 | [`session-projection-cache/`](session-projection-cache/README.md) | 持久化并恢复投影检查点 | `ctx.sessionProjectionCache` |
+| [`session-stats/`](session-stats/README.md) | 提供全日志会话计数与墙钟时间（`sessionStats` 单元） | 注册到 `ctx.sessionProjections` |
 
 ## 标题
 

packages/session/session-stats/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/session/session-stats/README.md
+README.md: a42d5b1b6efe8ff522a43431f1ccb68b71607876
+README.zh.md: 5929280a8a619fb37a6f6468fb839962702a68c3

packages/session/session-stats/README.md

@@ -0,0 +1,39 @@
+# @deepseek-ai/dsh-session-stats
+
+English | [中文](README.zh.md)
+
+Function plugin registering the `sessionStats` projection unit: whole-log conversation figures — turn/step counts and the LLM, tool, first-token, and decode wall times — folded from step boundaries, stream chunks, tool pairs, and assembled assistant messages, and served through the session-projection seam (registry snapshot, change feed, and every projection carrier: history tail page, `session/projection` push frames, session list rows). Clients render full-session figures that paging and compaction cannot change; the reference consumer is the web chat stats strip, whose window fold mirrors these field names as its no-unit fallback.
+
+## Fold semantics
+
+- `steps` counts `step/end` events. The agent loop appends exactly one per entered step, in a `finally`, so completed, failed, cancelled, and max-tokens steps all count. Counting assembled assistant messages instead would overcount max-tokens usage-host messages (empty content, excluded from the surface) and undercount cancelled steps (aborted before the message assembles).
+- `turns` counts distinct turns carrying at least one closed step; rejected or empty turns (closed with no step) are uncounted. Turn numbers are host-assigned and monotonic per session, so the fold keeps only the last counted turn.
+- `llmMs` sums `step/start` → `assistant/message` per step that assembled a message (retry waits inside the step are model time, as in the window fold).
+- `ttftMs`/`ttftSteps` sum and count `step/start` → first non-empty delta chunk; the first attempt's boundary survives an in-step `llm/retry` (window `resetForRetry` parity).
+- `decodeMs`/`decodeTokens` sum first token → assembled message and the provider-reported output tokens, only over steps carrying both.
+- `toolMs` sums `tool/call` → `tool/result` pairs matched by callId; unresolved calls are dropped at `turn/end` (results land within their turn).
+- Every field is 0 until its first contributing event. A composed registry always serves the key, so clients read the value, never key presence.
+
+## Composition
+
+```yaml
+- id: session-stats
+  name: '@deepseek-ai/dsh-session-stats'
+```
+
+Injects `sessionProjections` — the plugin's whole purpose; in assemblies without the registry the fiber stays pending and nothing registers.
+
+## Model Experience
+
+None, as the plugin only computes a client-facing read model of already-logged session events and touches no prompt, message, schema, stream, or tool result.
+
+#### KV Cache effect
+
+None; the plugin never assembles or sends provider requests.
+
+## Known Limitations and Deferred Work
+
+- **Steps count work attempted, not visible output** — a step that failed before producing any visible content still closed with `step/end` and counts; a step truncated by a crash between `step/start` and `step/end` does not.
+- **A cancelled step is counted but untimed** — no assistant message assembles, so its partial stream time enters no wall-time figure, matching the window fold's untimed interrupted node; a max-tokens usage-host message conversely contributes model time the surface does not show.
+- **Counts are log-scoped, not surface-scoped** — steps whose messages were later compacted away stay counted; the figures describe the whole session, not the current model-visible surface.
+- **Mounted only in the web-app bundle** — other assemblies serve no `sessionStats` key, and their consumers fall back to window-scoped counting (the web stats strip's fallback path).

packages/session/session-stats/README.zh.md

@@ -0,0 +1,39 @@
+# @deepseek-ai/dsh-session-stats
+
+[English](README.md) | 中文
+
+注册 `sessionStats` projection 单元的函数插件：从步边界、流式 chunk、工具配对与已组装的 assistant 消息折叠出全日志会话数字——轮/步计数以及 LLM、工具、首 token、解码墙钟时间——经 session-projection 缝对外提供（registry 快照、变更流，以及每一个 projection 载体：history 尾页、`session/projection` 推送帧、会话列表行）。客户端由此渲染分页与压缩都无法改变的全会话数字；参考消费者是 Web 聊天统计条，其窗口折叠以相同字段名充当无单元时的回退。
+
+## 折叠语义
+
+- `steps` 统计 `step/end` 事件。agent loop 对每个进入的步在 `finally` 中恰好追加一条，因此完成、失败、取消、max-tokens 的步全部计入。若改按已组装的 assistant 消息计数，则会多算 max-tokens 的 usage 宿主消息（空内容、被排除在 surface 之外），并少算被取消的步（在消息组装前已中止）。
+- `turns` 统计含至少一个已关闭步的不同 turn；被拒绝或空轮（未进入任何步即关闭）不计。turn 号由宿主分配、按会话单调递增，因此折叠只需保留最近计入的 turn。
+- `llmMs` 按步累加 `step/start` → `assistant/message`（组装出消息的步；步内重试的等待与窗口折叠一样计入模型时间）。
+- `ttftMs`/`ttftSteps` 累加并统计 `step/start` → 首个非空 delta chunk；首次尝试的边界在步内 `llm/retry` 后保留（与窗口 `resetForRetry` 对齐）。
+- `decodeMs`/`decodeTokens` 累加首 token → 已组装消息的时长与提供方上报的输出 token，仅统计两者兼备的步。
+- `toolMs` 按 callId 配对累加 `tool/call` → `tool/result`；未解决的调用在 `turn/end` 时丢弃（结果总在其轮内落地）。
+- 每个字段在首个贡献事件之前均为 0。已装配的 registry 恒提供该键，客户端读取值本身，而非键的存在性。
+
+## 组合
+
+```yaml
+- id: session-stats
+  name: '@deepseek-ai/dsh-session-stats'
+```
+
+注入 `sessionProjections`——这是插件的全部用途；在没有 registry 的装配中 fiber 保持挂起，不注册任何内容。
+
+## 模型体验
+
+无，因为插件只计算面向客户端的、由已写入日志的会话事件派生的读模型，不触碰任何提示词、消息、schema、流或工具结果。
+
+#### KV Cache 影响
+
+无；插件从不组装或发送提供方请求。
+
+## 已知局限与延后工作
+
+- **步数统计的是已发生的工作，而非可见输出**——在产生任何可见内容前就失败的步仍以 `step/end` 关闭并计入；进程崩溃恰好截断在 `step/start` 与 `step/end` 之间的步不计。
+- **被取消的步计数但不计时**——没有组装出 assistant 消息，其部分流式时间不进入任何墙钟数字，与窗口折叠的无计时 interrupted 节点一致；反之 max-tokens 的 usage 宿主消息贡献 surface 上看不到的模型时间。
+- **计数是日志口径，不是 surface 口径**——消息后来被压缩掉的步仍然计入；数字描述整个会话，而非当前模型可见 surface。
+- **仅挂载于 web-app bundle**——其他装配不提供 `sessionStats` 键，其消费者回退到窗口口径计数（Web 统计条的回退路径）。

packages/session/session-stats/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-session-stats",
+  "description": "Whole-log conversation counts and wall times projection (sessionStats) for the DeepSeek Harness",
+  "version": "0.0.1-rc.2",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/session-stats"
+  },
+  "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"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/types/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "workspace:^",
+    "@deepseek-ai/cordis-plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^"
+  }
+}

packages/session/session-stats/src/client.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the session-stats domain: a pure re-export
+ * of the package's types outlet. Client code imports ONLY the client
+ * namespace (repo discipline), so `./client` projects the same single-source
+ * content `./types` serves to host consumers — zero duplication.
+ *
+ * @module @deepseek-ai/dsh-session-stats/client
+ */
+
+export type * from './types.ts'

packages/session/session-stats/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Function plugin registering the `sessionStats` projection unit: whole-log
+ * turn/step counts and LLM/tool/first-token/decode wall times served through
+ * the session-projection seam (registry snapshot, change feed, and every
+ * projection carrier), so clients render full-session figures that paging and
+ * compaction cannot change. The plugin owns only the fold; delivery is the
+ * seam's.
+ *
+ * @module @deepseek-ai/dsh-session-stats
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { sessionStatsProjectionDefinition } from './projection.ts'
+
+export type * from './types.ts'
+
+/** Cordis plugin name. */
+export const name = 'session-stats'
+/** The projection registry is the plugin's whole purpose; without it the fiber stays pending. */
+export const inject = ['sessionProjections']
+
+/**
+ * Register the `sessionStats` unit; the registration is an effect on this
+ * plugin's fiber, so unloading removes the key.
+ * @param ctx - registrant context carrying the projection registry.
+ */
+export function apply(ctx: Context): void {
+  ctx.sessionProjections.register(sessionStatsProjectionDefinition)
+}

packages/session/session-stats/src/invariant.ts

@@ -0,0 +1,35 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-stats`.
+ * @module @deepseek-ai/dsh-session-stats/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-stats'
+
+/** Cordis companion plugin name. */
+export const name = 'session-stats-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the package owns a single pure projection fold whose
+ * wire payload is schema-validated by the projection registry at every
+ * snapshot and change-feed emission, and the event relations the fold relies
+ * on (`step/end` exactly once per entered step, monotonic host-assigned turn
+ * numbers, chunk and tool events carrying their step coordinates and call
+ * ids) are owned and runtime-checked by dsh-agent-loop and the session
+ * surface, not here.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/session/session-stats/src/projection.ts

@@ -0,0 +1,179 @@
+/**
+ * The `sessionStats` projection unit: a pure fold of step boundaries, stream
+ * chunks, tool pairs, and assembled assistant messages into whole-log counts
+ * and wall times.
+ *
+ * `step/end` — not `assistant/message` — is the counted step event because it
+ * is the step lifecycle authority: the loop appends exactly one per entered
+ * step, in a `finally`, so completed, failed, cancelled, and max-tokens steps
+ * all land one. Counting assembled assistant messages instead would overcount
+ * max-tokens usage-host messages (empty content, excluded from the surface)
+ * and undercount cancelled steps (aborted before the message assembles).
+ *
+ * The wall-time folds mirror the client window fold field by field
+ * (`deriveStats` in dsh-client-ui-conversation, that fold's whole-window
+ * fallback role): model time is `step/start` → `assistant/message`, first
+ * token is the first non-empty delta chunk and survives an in-step
+ * `llm/retry`, decode spans first token → assembled message on steps that
+ * also report output tokens, and tool time pairs `tool/call` → `tool/result`
+ * by callId. A cancelled step assembles no message, so its partial stream
+ * time stays uncounted in every time figure — matching the window, which
+ * renders it as an untimed interrupted node.
+ *
+ * @module @deepseek-ai/dsh-session-stats/projection
+ */
+
+import { z } from 'zod'
+import { isTokenDelta } from '@deepseek-ai/dsh-llm/message'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+
+/** Accumulated whole-log figures (the view is exactly these totals). */
+interface SessionStatsTotals {
+  /** Distinct turns with at least one closed step so far. */
+  turns: number
+  /** Closed steps so far. */
+  steps: number
+  /** Summed model wall time over message-assembling steps, ms. */
+  llmMs: number
+  /** Summed matched tool call→result wall time, ms. */
+  toolMs: number
+  /** Summed first-token latency over `ttftSteps`, ms. */
+  ttftMs: number
+  /** Steps carrying a recorded first token. */
+  ttftSteps: number
+  /** Summed decode wall time over usage-reporting steps, ms. */
+  decodeMs: number
+  /** Summed provider output tokens over the same steps. */
+  decodeTokens: number
+}
+
+/**
+ * Fold state: the totals plus the in-flight boundaries they accrue from.
+ * Turn numbers are host-assigned and monotonic per session, so a single
+ * `lastTurn` slot decides "first closed step of a new turn"; the state is
+ * plain JSON per the unit contract (persisted-cache precondition).
+ */
+interface SessionStatsState extends SessionStatsTotals {
+  /** Turn of the last counted `step/end`; null before the first. */
+  lastTurn: number | null
+  /** The open step's boundary facts; null outside a step or after its message assembled. */
+  openStep: { turn: number; step: number; startTime: number; firstTokenTime: number | null } | null
+  /** Dispatch times of tool calls whose result has not landed, by callId. */
+  pendingCalls: Record<string, number>
+}
+
+const sessionStatsSchema = z.object({
+  turns: z.number().int().nonnegative(),
+  steps: z.number().int().nonnegative(),
+  llmMs: z.number().nonnegative(),
+  toolMs: z.number().nonnegative(),
+  ttftMs: z.number().nonnegative(),
+  ttftSteps: z.number().int().nonnegative(),
+  decodeMs: z.number().nonnegative(),
+  decodeTokens: z.number().nonnegative(),
+}).strict()
+
+/**
+ * Provider-reported completion tokens, guarded the way the window fold guards
+ * node usage.
+ * @param usage - the assistant/message event's optional usage record.
+ * @returns the output-token count, or null when unreported or invalid.
+ */
+function usageOutputTokens(usage: unknown): number | null {
+  if (typeof usage !== 'object' || usage === null) return null
+  const value = (usage as { outputTokens?: unknown }).outputTokens
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null
+}
+
+/** The `sessionStats` unit registered on `ctx.sessionProjections` (exported for the unit spec). */
+export const sessionStatsProjectionDefinition: ProjectionDefinition<'sessionStats', SessionStatsState> = {
+  key: 'sessionStats',
+  schema: sessionStatsSchema,
+  init: () => ({
+    turns: 0,
+    steps: 0,
+    llmMs: 0,
+    toolMs: 0,
+    ttftMs: 0,
+    ttftSteps: 0,
+    decodeMs: 0,
+    decodeTokens: 0,
+    lastTurn: null,
+    openStep: null,
+    pendingCalls: {},
+  }),
+  apply: (state, event) => {
+    // Every uninteresting event returns the same reference (Object.is gates the change feed).
+    switch (event.type) {
+      case 'step/start':
+        return {
+          ...state,
+          openStep: { turn: event.data.turn, step: event.data.step, startTime: event.time, firstTokenTime: null },
+        }
+      case 'assistant/chunk': {
+        const open = state.openStep
+        if (open === null || open.turn !== event.data.turn || open.step !== event.data.step) return state
+        if (open.firstTokenTime !== null || !isTokenDelta(event.data.chunk)) return state
+        return { ...state, openStep: { ...open, firstTokenTime: event.time } }
+      }
+      case 'assistant/message': {
+        const open = state.openStep
+        if (open === null || open.turn !== event.data.turn || open.step !== event.data.step) return state
+        // One assembled message per step: closing the boundary means a
+        // defensive duplicate cannot accrue twice.
+        const next: SessionStatsState = {
+          ...state,
+          llmMs: state.llmMs + Math.max(0, event.time - open.startTime),
+          openStep: null,
+        }
+        if (open.firstTokenTime !== null) {
+          next.ttftMs += Math.max(0, open.firstTokenTime - open.startTime)
+          next.ttftSteps += 1
+          const outputTokens = usageOutputTokens(event.data.usage)
+          if (outputTokens !== null) {
+            next.decodeMs += Math.max(0, event.time - open.firstTokenTime)
+            next.decodeTokens += outputTokens
+          }
+        }
+        return next
+      }
+      case 'tool/call':
+        return { ...state, pendingCalls: { ...state.pendingCalls, [event.data.callId]: event.time } }
+      case 'tool/result': {
+        const callId = event.data.message.source.callId
+        const dispatched = state.pendingCalls[callId]
+        if (dispatched === undefined) return state
+        const pendingCalls = Object.fromEntries(
+          Object.entries(state.pendingCalls).filter(([id]) => id !== callId),
+        )
+        return { ...state, toolMs: state.toolMs + Math.max(0, event.time - dispatched), pendingCalls }
+      }
+      case 'step/end':
+        return {
+          ...state,
+          turns: state.lastTurn === event.data.turn ? state.turns : state.turns + 1,
+          steps: state.steps + 1,
+          lastTurn: event.data.turn,
+          openStep: null,
+        }
+      case 'turn/end':
+        // A call whose result never landed belongs to a cancelled or failed
+        // turn; results always land within their turn, so drop the leftovers
+        // instead of growing persisted state forever.
+        return Object.keys(state.pendingCalls).length === 0 ? state : { ...state, pendingCalls: {} }
+      default:
+        return state
+    }
+  },
+  view: state => ({
+    turns: state.turns,
+    steps: state.steps,
+    llmMs: state.llmMs,
+    toolMs: state.toolMs,
+    ttftMs: state.ttftMs,
+    ttftSteps: state.ttftSteps,
+    decodeMs: state.decodeMs,
+    decodeTokens: state.decodeTokens,
+  }),
+  stateVersion: 2,
+}

packages/session/session-stats/src/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure types of the session-stats domain: the ONE home of the `sessionStats`
+ * projection-key declaration, free of this package's host-side value imports
+ * (cordis context, zod, the llm chunk predicate). Two namespace projections
+ * serve it — `./types` for host consumers, `./client` for client aggregates —
+ * with zero content duplication.
+ *
+ * @module @deepseek-ai/dsh-session-stats/types
+ */
+
+// Marks this file a module so the declaration below AUGMENTS the projection
+// table instead of declaring an ambient module.
+export {}
+
+/**
+ * Whole-log conversation figures, independent of how much history a client
+ * has paged in. Counts and wall times all fold from the complete durable log;
+ * every field is 0 until its first contributing event lands. Field names
+ * mirror the client window fold so an assembly without this unit can fall
+ * back to it wholesale.
+ */
+export interface SessionStatsProjection {
+  /** Distinct turns carrying at least one closed step (`step/end`); rejected or empty turns are uncounted. */
+  turns: number
+  /** Closed steps (`step/end` events) — completed, failed, and cancelled steps alike. */
+  steps: number
+  /** Summed model wall time (`step/start` → `assistant/message`) over steps that assembled a message. */
+  llmMs: number
+  /** Summed tool wall time over `tool/call` → `tool/result` pairs matched by callId. */
+  toolMs: number
+  /** Summed first-token latency (`step/start` → first non-empty delta chunk) over `ttftSteps`. */
+  ttftMs: number
+  /** Steps carrying a recorded first token. */
+  ttftSteps: number
+  /** Summed decode wall time (first token → `assistant/message`) over steps that also report output tokens. */
+  decodeMs: number
+  /** Summed provider output tokens over the same decode-timed steps. */
+  decodeTokens: number
+}
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    /** Whole-log turn/step counts and wall times; see {@link SessionStatsProjection}. */
+    sessionStats: SessionStatsProjection
+  }
+}

packages/session/session-stats/tests/loader-composition.spec.ts

@@ -0,0 +1,86 @@
+/**
+ * REAL-composition proof: the shipped YAML shape (session + projection
+ * registry + session-stats) boots through the vendored Loader, the function
+ * plugin's namespace survives (no default export), and a full logged turn
+ * serves `{turns: 1, steps: 1}` through the composed registry.
+ */
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import Include from '@deepseek-ai/cordis-plugin-include'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import * as SessionStatsPlugin from '@deepseek-ai/dsh-session-stats'
+
+let root: string | undefined
+let context: Context | undefined
+
+afterEach(async () => {
+  await context?.fiber.dispose()
+  context = undefined
+  if (root !== undefined) await rm(root, { recursive: true, force: true })
+  root = undefined
+})
+
+async function loadYaml(lines: readonly string[]): Promise<Context> {
+  root = await mkdtemp(join(tmpdir(), 'dsh-session-stats-loader-'))
+  const configPath = join(root, 'cordis.yml')
+  await writeFile(configPath, [...lines, ''].join('\n'))
+
+  context = new Context()
+  context.baseUrl = pathToFileURL(root).href + '/'
+  await context.plugin(Loader)
+  context.loader.builtins.include = Include
+  const modules = new Map<string, unknown>([
+    ['@deepseek-ai/dsh-session', SessionStore],
+    ['@deepseek-ai/dsh-session-projection', SessionProjectionRegistry],
+    ['@deepseek-ai/dsh-session-stats', SessionStatsPlugin],
+  ])
+  context.loader.internal = {
+    version: 'v2',
+    async import(specifier: string) {
+      if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+      return modules.get(specifier)
+    },
+  } as unknown as NonNullable<typeof context.loader.internal>
+  await context.loader.create({
+    name: 'cordis:include',
+    config: { path: pathToFileURL(configPath).href },
+  })
+  await context.loader.await()
+  return context
+}
+
+describe('real Loader composition', () => {
+  it('loads the shipped session-stats YAML shape and serves whole-log counts', async () => {
+    const loaded = await loadYaml([
+      "- name: '@deepseek-ai/dsh-session'",
+      "- name: '@deepseek-ai/dsh-session-projection'",
+      "- name: '@deepseek-ai/dsh-session-stats'",
+    ])
+
+    const unloaded = [...loaded.loader.entries()]
+      .filter(entry => entry.fiber === undefined && !entry.disabled)
+      .map(entry => entry.options.name)
+    expect(unloaded).toEqual([])
+
+    const session = loaded.sessions.create(SessionId('composed'))
+    session.append('turn/start', { turn: 1 })
+    session.append('step/start', { turn: 1, step: 1 })
+    session.append('step/end', { turn: 1, step: 1 })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    expect(loaded.sessionProjections.snapshot(session).values.sessionStats)
+      .toMatchObject({ turns: 1, steps: 1 })
+  })
+
+  it('keeps the function-plugin namespace free of a default export', () => {
+    // A default export beside the named form makes the Loader discard the
+    // namespace (postmortem 0001) — pin its absence.
+    expect('default' in SessionStatsPlugin).toBe(false)
+  })
+})

packages/session/session-stats/tests/projection.spec.ts

@@ -0,0 +1,271 @@
+/**
+ * The `sessionStats` projection unit: mounting the plugin beside the
+ * projection registry serves whole-log counts and wall times folded from step
+ * boundaries, chunks, tool pairs, and assembled messages; compositions
+ * without the registry are unaffected; unmounting the plugin removes the key
+ * (HMR safety). The two counting regressions pinned here are the reasons the
+ * fold counts step boundaries instead of assistant messages: a cancelled step
+ * never assembles a message but still counts, and a max-tokens usage-host
+ * message (empty content) adds no extra step. Wall-time math runs against the
+ * exported definition directly, where event times are controlled.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { createMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import * as SessionStatsPlugin from '@deepseek-ai/dsh-session-stats'
+import { sessionStatsProjectionDefinition } from '@deepseek-ai/dsh-session-stats/src/projection.ts'
+import type { SessionStatsProjection } from '@deepseek-ai/dsh-session-stats/types'
+
+async function harness(withStatsPlugin: boolean): Promise<{ ctx: Context; session: Session }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionProjectionRegistry)
+  if (withStatsPlugin) await ctx.plugin(SessionStatsPlugin)
+  return { ctx, session: ctx.sessions.create(SessionId('counted')) }
+}
+
+/** Close one step; returns the counted `step/end` seq. */
+function closeStep(session: Session, turn: number, step: number): number {
+  session.append('step/start', { turn, step })
+  return session.append('step/end', { turn, step }).seq
+}
+
+/** Append the max-tokens usage-host shape: an assistant/message with empty content. */
+function appendEmptyAssistantMessage(session: Session, turn: number, step: number): void {
+  session.append('assistant/message', {
+    turn,
+    step,
+    message: createMessage({
+      role: 'assistant',
+      content: [],
+      source: { kind: 'model', provider: 'mock', model: 'mock' },
+    }),
+  }, { surfaceOp: 'append', sourceEventSeqs: [] })
+}
+
+/** The all-zero projection value plus overrides, for exact fold expectations. */
+function totals(overrides: Partial<SessionStatsProjection> = {}): SessionStatsProjection {
+  return {
+    turns: 0, steps: 0, llmMs: 0, toolMs: 0, ttftMs: 0, ttftSteps: 0, decodeMs: 0, decodeTokens: 0,
+    ...overrides,
+  }
+}
+
+describe('sessionStats projection unit (registry drive)', () => {
+  it('serves zero figures on the empty log', async () => {
+    const { ctx, session } = await harness(true)
+    expect(ctx.sessionProjections.snapshot(session).values.sessionStats).toEqual(totals())
+  })
+
+  it('counts distinct turns and closed steps and notifies the change feed with the causing seq', async () => {
+    const { ctx, session } = await harness(true)
+    const changes: { key: string; value: unknown; seq: number }[] = []
+    ctx.sessionProjections.onChanged((_session, key, value, seq) => {
+      changes.push({ key, value, seq })
+    })
+    session.append('turn/start', { turn: 1 })
+    const firstSeq = closeStep(session, 1, 1)
+    const secondSeq = closeStep(session, 1, 2)
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    session.append('turn/start', { turn: 2 })
+    const thirdSeq = closeStep(session, 2, 1)
+    session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
+    // Boundary events that carry no figure change (turn/start, empty-prune
+    // turn/end, user input) fold to the same reference and stay silent;
+    // step/start opens a boundary (internal state) and step/end commits the
+    // counts, so each closed step notifies twice with the step/end value last.
+    const counted = changes.filter(change => (change.value as SessionStatsProjection).steps > 0
+      || change.seq === firstSeq)
+    expect(changes.every(change => change.key === 'sessionStats')).toBe(true)
+    expect(counted.map(change => ({ seq: change.seq, value: change.value }))).toContainEqual(
+      { seq: firstSeq, value: totals({ turns: 1, steps: 1 }) },
+    )
+    expect(changes.at(-1)).toEqual({ key: 'sessionStats', value: totals({ turns: 2, steps: 3 }), seq: thirdSeq })
+    const snapshot = ctx.sessionProjections.snapshot(session)
+    expect(snapshot.values.sessionStats).toEqual(totals({ turns: 2, steps: 3 }))
+    expect(snapshot.asOfSeq).toBe(session.seq - 1)
+    expect(changes.map(change => change.seq)).toContain(secondSeq)
+  })
+
+  it('does not count a rejected or empty turn that closes with no step', async () => {
+    const { ctx, session } = await harness(true)
+    session.append('turn/start', { turn: 1 })
+    session.append('turn/end', { turn: 1, reason: { kind: 'blocked' } })
+    expect(ctx.sessionProjections.snapshot(session).values.sessionStats).toEqual(totals())
+  })
+
+  it('counts a cancelled step that closed without an assistant message', async () => {
+    // Regression: an aborted stream never assembles assistant/message, but the
+    // loop's finally still appends step/end — the step happened and counts.
+    const { ctx, session } = await harness(true)
+    session.append('turn/start', { turn: 1 })
+    closeStep(session, 1, 1)
+    session.append('turn/end', { turn: 1, reason: { kind: 'aborted', reason: { kind: 'legacy' } } })
+    expect(ctx.sessionProjections.snapshot(session).values.sessionStats)
+      .toMatchObject({ turns: 1, steps: 1 })
+  })
+
+  it('adds no extra step for a max-tokens usage-host assistant message', async () => {
+    // Regression: the empty-content assistant/message exists only to host
+    // usage and is excluded from the surface; the step counts once, from its
+    // step/end, while the message contributes only its model wall time.
+    const { ctx, session } = await harness(true)
+    session.append('turn/start', { turn: 1 })
+    session.append('step/start', { turn: 1, step: 1 })
+    appendEmptyAssistantMessage(session, 1, 1)
+    session.append('step/end', { turn: 1, step: 1 })
+    session.append('turn/end', { turn: 1, reason: { kind: 'max-tokens' } })
+    expect(ctx.sessionProjections.snapshot(session).values.sessionStats)
+      .toMatchObject({ turns: 1, steps: 1, ttftSteps: 0, decodeTokens: 0 })
+  })
+
+  it('folds steps already in the log when the plugin mounts late (lazy cell build)', async () => {
+    const { ctx, session } = await harness(false)
+    session.append('turn/start', { turn: 1 })
+    closeStep(session, 1, 1)
+    closeStep(session, 1, 2)
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    await ctx.plugin(SessionStatsPlugin)
+    expect(ctx.sessionProjections.snapshot(session).values.sessionStats)
+      .toMatchObject({ turns: 1, steps: 2 })
+  })
+
+  it('has no sessionStats key without the plugin, and drops it when the plugin unloads (HMR safety)', async () => {
+    const { ctx, session } = await harness(false)
+    expect('sessionStats' in ctx.sessionProjections.snapshot(session).values).toBe(false)
+    const fiber = await ctx.plugin(SessionStatsPlugin)
+    session.append('turn/start', { turn: 1 })
+    closeStep(session, 1, 1)
+    expect(ctx.sessionProjections.snapshot(session).values.sessionStats)
+      .toMatchObject({ turns: 1, steps: 1 })
+    await fiber.dispose()
+    expect('sessionStats' in ctx.sessionProjections.snapshot(session).values).toBe(false)
+  })
+})
+
+/** Build one synthetic committed event with a controlled timestamp. */
+function at(time: number, type: string, data: unknown): SessionEvent {
+  return { type, seq: time, time, data } as unknown as SessionEvent
+}
+
+/** Fold a synthetic event list through the definition and view the result. */
+function fold(events: readonly SessionEvent[]): SessionStatsProjection {
+  const state = events.reduce(
+    (folded, event) => sessionStatsProjectionDefinition.apply(folded, event),
+    sessionStatsProjectionDefinition.init(),
+  )
+  return sessionStatsProjectionDefinition.view(state)
+}
+
+describe('sessionStats wall-time fold (controlled timestamps)', () => {
+  const message = createMessage({
+    role: 'assistant',
+    content: [{ type: 'text', text: 'answer' }],
+    source: { kind: 'model', provider: 'mock', model: 'mock' },
+  })
+
+  it('accrues model, first-token, and decode time from one fully recorded step', () => {
+    expect(fold([
+      at(1_000, 'step/start', { turn: 1, step: 1 }),
+      at(1_800, 'assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'a' } }),
+      at(4_800, 'assistant/message', { turn: 1, step: 1, message, usage: { inputTokens: 10, outputTokens: 60 } }),
+      at(4_900, 'step/end', { turn: 1, step: 1 }),
+    ])).toEqual(totals({
+      turns: 1, steps: 1, llmMs: 3_800, ttftMs: 800, ttftSteps: 1, decodeMs: 3_000, decodeTokens: 60,
+    }))
+  })
+
+  it('keeps the first attempt token boundary across an in-step retry (window resetForRetry parity)', () => {
+    expect(fold([
+      at(1_000, 'step/start', { turn: 1, step: 1 }),
+      at(1_200, 'assistant/chunk', { turn: 1, step: 1, chunk: { type: 'reasoning-delta', index: 0, text: 'x' } }),
+      at(2_000, 'llm/retry', { turn: 1, step: 1 }),
+      at(3_000, 'assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'y' } }),
+      at(5_000, 'assistant/message', { turn: 1, step: 1, message }),
+      at(5_100, 'step/end', { turn: 1, step: 1 }),
+    ])).toEqual(totals({ turns: 1, steps: 1, llmMs: 4_000, ttftMs: 200, ttftSteps: 1 }))
+  })
+
+  it('ignores empty deltas, non-token chunks, and chunks outside the open step', () => {
+    expect(fold([
+      // Chunk before any step/start: no open boundary.
+      at(500, 'assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'stray' } }),
+      at(1_000, 'step/start', { turn: 1, step: 1 }),
+      at(1_100, 'assistant/chunk', { turn: 1, step: 1, chunk: { type: 'block-start', index: 0, blockType: 'text' } }),
+      at(1_200, 'assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: '' } }),
+      at(1_300, 'assistant/chunk', { turn: 2, step: 9, chunk: { type: 'text-delta', index: 0, text: 'other' } }),
+      at(1_400, 'assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'first' } }),
+      at(2_000, 'assistant/message', { turn: 1, step: 1, message }),
+      at(2_100, 'step/end', { turn: 1, step: 1 }),
+    ])).toEqual(totals({ turns: 1, steps: 1, llmMs: 1_000, ttftMs: 400, ttftSteps: 1 }))
+  })
+
+  it('leaves a cancelled step untimed: counted by step/end, no assembled message to accrue from', () => {
+    expect(fold([
+      at(1_000, 'step/start', { turn: 1, step: 1 }),
+      at(1_500, 'assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'partial' } }),
+      at(2_000, 'step/end', { turn: 1, step: 1 }),
+    ])).toEqual(totals({ turns: 1, steps: 1 }))
+  })
+
+  it('pairs tool wall time by callId, ignores orphan results, and prunes leftovers at turn/end', () => {
+    const result = (callId: string): unknown =>
+      ({ turn: 1, step: 1, message: { source: { kind: 'tool', callId } } })
+    const paired = fold([
+      at(1_000, 'step/start', { turn: 1, step: 1 }),
+      at(1_100, 'tool/call', { turn: 1, step: 1, callId: 'a', name: 'read', arguments: '{}' }),
+      at(1_200, 'tool/call', { turn: 1, step: 1, callId: 'b', name: 'read', arguments: '{}' }),
+      // Out-of-order settlement pairs by id, not adjacency.
+      at(4_200, 'tool/result', result('b')),
+      at(1_600, 'tool/result', result('a')),
+      at(5_000, 'tool/result', result('ghost')),
+      at(5_100, 'step/end', { turn: 1, step: 1 }),
+    ])
+    expect(paired).toEqual(totals({ turns: 1, steps: 1, toolMs: 3_500 }))
+    // An unresolved call is dropped at turn/end; a later result cannot pair.
+    const pruned = fold([
+      at(1_000, 'step/start', { turn: 1, step: 1 }),
+      at(1_100, 'tool/call', { turn: 1, step: 1, callId: 'orphan', name: 'read', arguments: '{}' }),
+      at(2_000, 'step/end', { turn: 1, step: 1 }),
+      at(2_100, 'turn/end', { turn: 1, reason: { kind: 'aborted', reason: { kind: 'legacy' } } }),
+      at(9_000, 'tool/result', result('orphan')),
+    ])
+    expect(pruned).toEqual(totals({ turns: 1, steps: 1 }))
+  })
+
+  it('skips decode for an invalid usage report and ignores a duplicate assembled message', () => {
+    const events = [
+      at(1_000, 'step/start', { turn: 1, step: 1 }),
+      at(1_400, 'assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'a' } }),
+      // A malformed provider report: guarded like the window fold guards node usage.
+      at(2_000, 'assistant/message', { turn: 1, step: 1, message, usage: { inputTokens: 1, outputTokens: -5 } }),
+    ]
+    expect(fold([...events, at(2_100, 'step/end', { turn: 1, step: 1 })]))
+      .toEqual(totals({ turns: 1, steps: 1, llmMs: 1_000, ttftMs: 400, ttftSteps: 1 }))
+    // The first message closed the step boundary; a defensive duplicate finds
+    // no open step and folds to the same reference.
+    const state = events.reduce(
+      (folded, event) => sessionStatsProjectionDefinition.apply(folded, event),
+      sessionStatsProjectionDefinition.init(),
+    )
+    expect(sessionStatsProjectionDefinition.apply(
+      state,
+      at(2_050, 'assistant/message', { turn: 1, step: 1, message }),
+    )).toBe(state)
+  })
+
+  it('accrues nothing for unrelated events and clamps negative clock skew to zero', () => {
+    const state = sessionStatsProjectionDefinition.init()
+    const untouched = sessionStatsProjectionDefinition.apply(state, at(1, 'user/message', { content: [] }))
+    expect(untouched).toBe(state)
+    expect(fold([
+      at(2_000, 'step/start', { turn: 1, step: 1 }),
+      at(1_000, 'assistant/message', { turn: 1, step: 1, message }),
+      at(2_100, 'step/end', { turn: 1, step: 1 }),
+    ])).toEqual(totals({ turns: 1, steps: 1 }))
+  })
+})

packages/session/session-stats/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../session-projection"
+    }
+  ]
+}

pnpm-lock.yaml

@@ -1665,6 +1665,9 @@ importers:
       '@deepseek-ai/dsh-session-projection-cache':
         specifier: workspace:^
         version: link:../../session/session-projection-cache
+      '@deepseek-ai/dsh-session-stats':
+        specifier: workspace:^
+        version: link:../../session/session-stats
       '@deepseek-ai/dsh-storage':
         specifier: workspace:^
         version: link:../../storage/storage
@@ -2149,6 +2152,9 @@ importers:
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
         version: link:../../session/session-projection
+      '@deepseek-ai/dsh-session-stats':
+        specifier: workspace:^
+        version: link:../../session/session-stats
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:^
         version: link:../../llm/token-meter
@@ -6195,6 +6201,34 @@ importers:
         specifier: workspace:^
         version: link:../../storage/storage-domain
 
+  packages/session/session-stats:
+    dependencies:
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@deepseek-ai/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/cordis-plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@deepseek-ai/cordis-plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-projection':
+        specifier: workspace:^
+        version: link:../session-projection
+
   packages/session/session-telemetry:
     devDependencies:
       '@deepseek-ai/cordis':

scripts/verify-package-readme-model-experience.ts

@@ -120,6 +120,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/sdk/protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own model-facing behavior.' },
   'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers nothing model-facing.' },
   'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers nothing model-facing.' },
+  'packages/session/session-stats': { kind: 'none', reason: 'The sessionStats unit folds already-logged step boundaries into a client-facing read model and registers nothing model-facing.' },
   'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers nothing model-facing.' },
   'packages/session-query/session-query-sqlite': { kind: 'none', reason: 'The search backend returns hits only to callers and registers nothing model-facing.' },
   'packages/settings/settings': { kind: 'indirect', reason: 'The seam stores and resolves user settings; consumer plugins own any model-facing content fed by a value.' },

tsconfig.base.json

@@ -58,6 +58,8 @@
       "@deepseek-ai/dsh-tool-todo/client": ["./packages/todo/tool-todo/src/client.ts"],
       "@deepseek-ai/dsh-session-title/types": ["./packages/session/session-title/src/types.ts"],
       "@deepseek-ai/dsh-session-title/client": ["./packages/session/session-title/src/client.ts"],
+      "@deepseek-ai/dsh-session-stats/types": ["./packages/session/session-stats/src/types.ts"],
+      "@deepseek-ai/dsh-session-stats/client": ["./packages/session/session-stats/src/client.ts"],
       "@deepseek-ai/dsh-plan-mode/types": ["./packages/plan/plan-mode/src/types.ts"],
       "@deepseek-ai/dsh-plan-mode/client": ["./packages/plan/plan-mode/src/client.ts"],
       "@deepseek-ai/dsh-agent-presets/types": ["./packages/preset/agent-presets/src/types.ts"],

tsconfig.host.json

@@ -35,6 +35,7 @@
     "apps/web/tests/replay-round-trip.e2e.ts",
     "apps/web/tests/hmr-live.e2e.ts",
     "apps/web/tests/seeded-history.e2e.ts",
+    "apps/web/tests/stats-paged-history.e2e.ts",
     "apps/web/tests/sidebar-scrollbar.e2e.ts",
     "apps/web/tests/conversation-column-overflow.e2e.ts",
     "apps/web/tests/code-mode-round.e2e.ts",
@@ -137,6 +138,7 @@
     { "path": "./packages/session/session-persistence-sqlite" },
     { "path": "./packages/session/session-projection" },
     { "path": "./packages/session/session-projection-cache" },
+    { "path": "./packages/session/session-stats" },
     { "path": "./packages/session-query/session-query" },
     { "path": "./packages/session-query/session-query-sqlite" },
     { "path": "./packages/settings/settings" },