feat(web): add durable session metrics (round 1)

packages/client/connection/src/client/api.ts

@@ -11,7 +11,7 @@ export type {
   WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, CommandExecuteResult, SkillsApi, SkillEntry,
   ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, SessionModels,
+  ModelReasoningEffort, ModelTarget, SessionMetrics, SessionModels,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
 export type {

packages/client/connection/src/client/index.ts

@@ -16,7 +16,7 @@ export type {
   ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, CommandExecuteResult, SkillsApi, SkillEntry,
   ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, SessionModels,
+  ModelReasoningEffort, ModelTarget, SessionMetrics, SessionModels,
   RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
   ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
   IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk,

packages/client/runtime/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/runtime/README.md
-README.md: 81261945cb2fd8b15f7c2f15cb1ae0b8e9928499
-README.zh.md: cbbf6eded4a5375223791275f26f3bc7b6553200
+README.md: fbb3a142b9efa50045f127d430bd2be2849f01f2
+README.zh.md: b5bd3c458ed462e01dfae5bcd7399dde5552dc8d

packages/client/runtime/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects, list/scope/history state; WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into both managers. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Contract: api-contracts v3 §4. `ConversationSnapshot` carries `todos` — the session's current todo projection: taken from the tail history page's full-log value (host-computed, independent of the page window), preserved across an older-page prepend, and overwritten by each live `todo/write` (last write wins). A tail response that omits the field means the log holds no `todo/write`, so the list resets to empty — a plan the log never kept (a write lost to a host crash) disappears on the next open or resync.
+Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects, list/scope/history state; WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into both managers. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Contract: api-contracts v3 §4. `ConversationSnapshot` carries two Host-owned full-log projections. `todos` comes from the tail history page, survives older-page prepend, and follows live `todo/write` events. `metrics` comes from tail history and live `session/metrics` frames, survives older-page prepend, and accepts only nondecreasing log and projection revisions; a subscription baseline clears it before replay so a new stream generation can restart revisions safely. Missing metrics remain `null` rather than being inferred from the visible node window.
 
 ## Workspace and Session lists
 

packages/client/runtime/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象、列表／scope／history 状态；WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给两个 manager。客户端 Session 一律由 Host 出生（一次 `session.create` 同瞬产出 Session+Agent+cwd）；客户端不持有任何实体化之前的会话状态——Agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时出生，随 prune 死亡。契约：api-contracts v3 §4。`ConversationSnapshot` 携带 `todos`——会话当前的 todo 投影：取自尾页 history 携带的全量 log 值（host 计算，独立于分页窗口），跨往前翻页保留，并被每次实时 `todo/write` 覆盖（后写胜出）。尾页响应省略该字段即表示 log 中没有任何 `todo/write`，因此列表复位为空——log 从未留下的计划（写入因 host 崩溃丢失）会在下一次打开或 resync 时消失。
+客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象、列表／scope／history 状态；WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给两个 manager。客户端 Session 一律由 Host 出生（一次 `session.create` 同瞬产出 Session+Agent+cwd）；客户端不持有任何实体化之前的会话状态——Agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时出生，随 prune 死亡。契约：api-contracts v3 §4。`ConversationSnapshot` 携带两项由 Host 拥有的完整日志投影。`todos` 来自 history 尾页，在向前加载较早页面时保留，并随实时 `todo/write` 事件更新。`metrics` 来自 history 尾页和实时 `session/metrics` 帧，在向前加载较早页面时保留，并且只接受日志修订号与投影修订号均不减小的数据；订阅基线会在回放前将其清除，使新的流代次可以安全地从头开始计数修订号。缺失的 metrics 保持为 `null`，而不是根据可见节点窗口推断。
 
 ## Workspace 与 Session 列表
 

packages/client/runtime/src/client/sessions/conversation.ts

@@ -6,7 +6,7 @@
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { TodoItem } from '@deepseek-ai/dsh-session/types'
 import type {
-  RpcError, SessionId, ToolCallView, ToolResultView,
+  RpcError, SessionId, SessionMetrics, ToolCallView, ToolResultView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { PendingInteraction } from './pending.ts'
 
@@ -246,4 +246,10 @@ export interface ConversationSnapshot {
   /** Current whole-list `todo/write` projection — the tail page's full-log value, then each live
    *  write (last write wins); empty = the log holds no plan. */
   todos: readonly TodoItem[]
+  /**
+   * Host-owned cumulative usage and current-context projection. Independent
+   * of `nodes` pagination; null until a tail response or live metrics frame
+   * supplies a current value.
+   */
+  metrics: SessionMetrics | null
 }

packages/client/runtime/src/client/sessions/session.ts

@@ -5,7 +5,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent, TodoItem } from '@deepseek-ai/dsh-session/types'
 import type {
   HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult,
-  SessionId, ToolEventView,
+  SessionId, SessionMetrics, ToolEventView,
 } from '@deepseek-ai/dsh-client-connection/client'
 // Value import from the inline-safe wire layer (not the connection plugin):
 // plugin-to-plugin value imports are a bundle purity error.
@@ -102,6 +102,8 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
   /** Current whole-list todo/write projection: each tail history response replaces it (an omitted
    *  field is the authoritative empty list) and every live write overwrites it. */
   private todos: readonly TodoItem[] = []
+  /** Host-owned metrics projection; ordering resets on each subscribed baseline. */
+  private metrics: SessionMetrics | null = null
   /** `run_code` sub-dispatches by parent callId (window-derived, like openCalls). Appends
    *  copy-on-write the per-parent array so published snapshot references never mutate. */
   private codeDispatches = new Map<string, readonly CodeSubCall[]>()
@@ -296,6 +298,7 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
     this.events = []
     this.views = []
     this.baseSeq = 0
+    this.metrics = null
     // Superseded, not settled: the baseline replay re-sends still-pending requested frames verbatim
     // (same rpcId), re-minting fresh waits; a stale reference's respond() still reaches the host.
     this.pending.clear()
@@ -364,6 +367,14 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
           this.queueRev++
           this.notifier.markDirty()
         }
+        if (this.metrics !== null) {
+          this.metrics = null
+          this.notifier.markDirty()
+        }
+        return
+      }
+      case 'session/metrics': {
+        this.installMetrics(frame.metrics)
         return
       }
       case 'approval/requested': {
@@ -482,13 +493,20 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
         this.openError = result.error
         return
       }
-      this.installWindow(result.value.events, result.value.hasMore, result.value.todos)
+      this.installWindow(result.value.events, result.value.hasMore, result.value.todos, result.value.metrics)
       // Gap detection (§D.3-4): baseline past the window tail and liveBuffer did not cover it -> pull the tail page once more.
       const tailSeq = this.windowTailSeq()
       if (this.subscribedLastSeq !== null && tailSeq !== null && this.subscribedLastSeq > tailSeq) {
         result = (await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })).result
         if (generation !== this.openGeneration) return
-        if (result.ok) this.installWindow(result.value.events, result.value.hasMore, result.value.todos)
+        if (result.ok) {
+          this.installWindow(
+            result.value.events,
+            result.value.hasMore,
+            result.value.todos,
+            result.value.metrics,
+          )
+        }
       }
       this.openState = 'open'
     } catch (error) {
@@ -506,7 +524,12 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    *  Stitching MUST NOT route through acceptLiveEvent: openState is still 'loading' here
    *  (doOpen flips it after install), so recursing would push every buffered event straight
    *  back into liveBuffer where nothing ever drains it — a silent drop loop (audit S1). */
-  private installWindow(entries: HistoryEntry[], hasMore: boolean, todos: readonly TodoItem[] | undefined): void {
+  private installWindow(
+    entries: HistoryEntry[],
+    hasMore: boolean,
+    todos: readonly TodoItem[] | undefined,
+    metrics: SessionMetrics | undefined,
+  ): void {
     this.events = entries.map(e => e.event)
     this.views = entries.map(e => e.view)
     this.baseSeq = this.events[0]?.seq ?? 0
@@ -519,6 +542,7 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
     // field is the authoritative empty list, not a missing carrier. Assigning
     // it clears a plan the log never kept (a write lost to a host crash).
     this.todos = todos ?? []
+    if (metrics !== undefined) this.installMetrics(metrics)
     this.foldAdapter.reset(this.events, this.baseSeq, this.views)
     this.rebuildDerivedFromWindow()
     const buffered = this.liveBuffer
@@ -569,7 +593,12 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
       const { result } = await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })
       // Failure or superseded by a full resync: drop — the resync path rebuilds and clears the buffer itself.
       if (result.ok && generation === this.openGeneration && this.openState === 'open') {
-        this.installWindow(result.value.events, result.value.hasMore, result.value.todos)
+        this.installWindow(
+          result.value.events,
+          result.value.hasMore,
+          result.value.todos,
+          result.value.metrics,
+        )
       }
     } catch (error) {
       console.error('[web-runtime] gap repair failed:', error)
@@ -761,6 +790,20 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
     return tail === undefined ? null : tail.seq
   }
 
+  /** Install a metrics snapshot unless a newer durable or publication revision already landed. */
+  private installMetrics(metrics: SessionMetrics): void {
+    const current = this.metrics
+    if (
+      current !== null
+      && (
+        metrics.logRevision < current.logRevision
+        || metrics.projectionRevision < current.projectionRevision
+      )
+    ) return
+    this.metrics = metrics
+    this.notifier.markDirty()
+  }
+
   private buildSnapshot(): ConversationSnapshot {
     const { nodes: folded, degraded } = this.foldAdapter.nodes()
     // Frozen interrupted nodes ride fractional seqs: a stable merge keeps them in flow order.
@@ -811,6 +854,7 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
       blank: this.blankBit,
       lastAgentError: this.lastAgentError,
       todos: this.todos,
+      metrics: this.metrics,
     }
   }
 }

packages/client/runtime/tests/fake-api.ts

@@ -3,7 +3,7 @@
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type {
   ClientResponse, CommandDescriptor, CommandExecuteResult, HostFrame, IApiClient, ModelTarget, MuxFrame,
-  RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SessionModels, SkillEntry,
+  RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SessionMetrics, SessionModels, SkillEntry,
   WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
@@ -63,7 +63,12 @@ export class FakeApiClient implements IApiClient {
   onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
   readonly defaultModel: ModelTarget = { provider: 'deepseek', model: 'deepseek-v4-flash' }
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
-  => Promise<RpcResponse<{ events: never[]; hasMore: boolean; todos?: { content: string; status: 'pending' | 'in_progress' | 'completed' }[] }>> =
+  => Promise<RpcResponse<{
+    events: never[]
+    hasMore: boolean
+    todos?: { content: string; status: 'pending' | 'in_progress' | 'completed' }[]
+    metrics?: SessionMetrics
+  }>> =
     () => Promise.resolve(ok({ events: [], hasMore: false }))
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({

packages/client/runtime/tests/queue-store.spec.ts

@@ -85,6 +85,13 @@ describe('queue retirement (host queuedMirror rules)', () => {
     expect(session.getSnapshot().queue).toHaveLength(1)
   })
 
+  it('an unrelated durable event leaves the queue unchanged', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('e1'), queuedFrame('留', 'p-1'))
+    session.handleMuxEnvelope(rid('e2'), { type: 'session/event', sessionId: SID, event: ev.user(0, 'unrelated') })
+    expect(session.getSnapshot().queue.map(row => row.key)).toEqual(['p-1'])
+  })
+
   it('steering/message drains the source-matched steering row only', () => {
     const session = makeSession()
     session.handleMuxEnvelope(rid('e1'), queuedFrame('普通', 'p-1')) // idle → non-steering

packages/client/runtime/tests/session.spec.ts

@@ -7,8 +7,9 @@
  */
 
 import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionId, SessionMetrics } from '@deepseek-ai/dsh-client-connection/client'
 import { Session } from '../src/client/sessions/session.ts'
 import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
 import { entries, ev, plainTurn } from './event-script.ts'
@@ -22,9 +23,37 @@ function makeSession(api = new FakeApiClient()): { api: FakeApiClient; session:
   return { api, session: new Session(SID, api) }
 }
 
-function histResponse(events: SessionEvent[], hasMore = false, todos?: { content: string; status: 'pending' | 'in_progress' | 'completed' }[]) {
+function histResponse(
+  events: SessionEvent[],
+  hasMore = false,
+  todos?: { content: string; status: 'pending' | 'in_progress' | 'completed' }[],
+  metrics?: SessionMetrics,
+) {
   // history now returns HistoryEntry[] ({event, view?}); these tests are view-less.
-  return Promise.resolve(ok({ events: entries(events) as never[], hasMore, ...todos === undefined ? {} : { todos } }))
+  return Promise.resolve(ok({
+    events: entries(events) as never[],
+    hasMore,
+    ...todos === undefined ? {} : { todos },
+    ...metrics === undefined ? {} : { metrics },
+  }))
+}
+
+function metrics(
+  projectionRevision: number,
+  logRevision: number,
+  over: Partial<SessionMetrics> = {},
+): SessionMetrics {
+  return {
+    projectionRevision,
+    logRevision,
+    uncachedInputTokens: 10,
+    outputTokens: 4,
+    cacheReadTokens: 90,
+    cacheWriteTokens: 3,
+    contextTokens: 35,
+    contextWindow: 100,
+    ...over,
+  }
 }
 
 describe('open', () => {
@@ -40,6 +69,19 @@ describe('open', () => {
     expect(snapshot.openState).toBe('open')
     expect(snapshot.hasMore).toBe(true)
     expect(snapshot.nodes.map(n => n.kind)).toEqual(['user', 'assistant'])
+    expect(snapshot.metrics).toBeNull()
+  })
+
+  it('installs full-log metrics independently of older history pages', async () => {
+    const { api, session } = makeSession()
+    const tailMetrics = metrics(4, 106)
+    api.onHistory = () => histResponse(plainTurn(100, 3, '问', '答'), true, undefined, tailMetrics)
+    await session.open()
+    expect(session.getSnapshot().metrics).toBe(tailMetrics)
+
+    api.onHistory = () => histResponse(plainTurn(94, 2, '旧问', '旧答'))
+    await session.loadOlder()
+    expect(session.getSnapshot().metrics).toBe(tailMetrics)
   })
 
   it('is idempotent: concurrent opens share one history call, reopening when open is a no-op', async () => {
@@ -104,6 +146,43 @@ describe('live event path', () => {
     expect(session.getSnapshot().nodes).toEqual(before.nodes)
   })
 
+  it('orders live metrics, rejects stale projections, and clears the value at a reconnect baseline', async () => {
+    const { session } = await opened()
+    const current = metrics(8, 10)
+    session.handleMuxEnvelope('m1' as never, {
+      type: 'session/metrics',
+      sessionId: SID,
+      metrics: current,
+    })
+    expect(session.getSnapshot().metrics).toBe(current)
+
+    session.handleMuxEnvelope('m2' as never, {
+      type: 'session/metrics',
+      sessionId: SID,
+      metrics: metrics(9, 9, { uncachedInputTokens: 1 }),
+    })
+    session.handleMuxEnvelope('m3' as never, {
+      type: 'session/metrics',
+      sessionId: SID,
+      metrics: metrics(7, 11, { uncachedInputTokens: 2 }),
+    })
+    expect(session.getSnapshot().metrics).toBe(current)
+
+    session.handleMuxEnvelope('sub' as never, {
+      type: 'session/subscribed',
+      sessionId: SID,
+      lastSeq: 5,
+    })
+    expect(session.getSnapshot().metrics).toBeNull()
+    const nextGeneration = metrics(0, 10, { contextTokens: 20 })
+    session.handleMuxEnvelope('m4' as never, {
+      type: 'session/metrics',
+      sessionId: SID,
+      metrics: nextGeneration,
+    })
+    expect(session.getSnapshot().metrics).toBe(nextGeneration)
+  })
+
   it('accumulates chunks into partial, then finalize swaps partial out as the node lands', async () => {
     const { session } = await opened()
     const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
@@ -332,6 +411,23 @@ describe('prompt and cancel errors', () => {
 })
 
 describe('pending interactions', () => {
+  it('routes an approval wait response through the original requested rpcId', async () => {
+    const { api, session } = makeSession()
+    session.handleMuxEnvelope('ra-answer' as never, {
+      type: 'approval/requested',
+      sessionId: SID,
+      approvalId: 'ap-answer' as never,
+      toolName: 'bash',
+    })
+    const wait = session.getSnapshot().pending[0]!
+    await wait.respond({ ok: true, value: { decision: 'allow' } })
+    expect(api.callsOf('respond')).toEqual([{
+      type: 'client-response',
+      rpcId: 'ra-answer',
+      result: { ok: true, value: { decision: 'allow' } },
+    }])
+  })
+
   it('adds approval/question on requested and removes them on resolved', async () => {
     const { session } = makeSession()
     session.handleMuxEnvelope('ra' as never, { type: 'approval/requested', sessionId: SID, approvalId: 'ap1' as never, toolName: 'rm' })
@@ -374,6 +470,16 @@ describe('pending interactions', () => {
 })
 
 describe('remaining branches', () => {
+  it('rejects a second scope bind and allows rebinding after explicit release', () => {
+    const { session } = makeSession()
+    const first = new Context()
+    const second = new Context()
+    session.bindScope(first)
+    expect(() => { session.bindScope(second) }).toThrow(`session ${SID} already has a bound scope`)
+    session.unbindScope()
+    expect(() => { session.bindScope(second) }).not.toThrow()
+  })
+
   it('prompt transport throw folds to internal promptError', async () => {
     const { api, session } = makeSession()
     api.onPrompt = () => Promise.reject(new Error('prompt wire down'))

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: 56a445ccfa86e0b11cf5aefc37819a30746f0739
-README.zh.md: a7c160ecdd74074257c9d149630663dacd05c070
+README.md: 9a8595e693e2b49691d0d130d4db0754e1e4829b
+README.zh.md: f5080314488e807877ebf0c93ea82cdd9725e8ed

packages/client/ui-conversation/README.md

@@ -18,6 +18,8 @@ Per-session UI state for selection and the active view lives in the declared cha
 
 The composer bar declares session-scoped single seats for `'conversation.input.plan'` and `'conversation.input.model'`, plus list slots for overlay, dock, left, and right input extensions. InputBar renders the model seat immediately before its pending indicator and send/stop button. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The resident no-session shell uses `DisabledInputBar` and therefore dispatches no session-scoped control seats.
 
+The chat stats line reads durable token counters and current-context pressure only from `ConversationSnapshot.metrics`; visible nodes supply only the existing turn/step counts. It renders uncached input, output, and cache reads as separate compact values, computes cache hit as `cacheRead / (uncachedInput + cacheRead)` without cache writes, and shows context occupancy against the selected route's exact capacity. Missing host data is labeled unknown, never reconstructed from a paged window.
+
 `src/client/` is organized for the future package split: `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations + composed slot props including the tool-row contract, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` (sample registrants) domain directories import contract files and never each other; `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components (skeleton, chat rows) and the store factory stay internal and reach the page exclusively through apply's slot registrations (tests take them via the `./src/*` subpath).
 
 ## Model Experience

packages/client/ui-conversation/README.zh.md

@@ -18,6 +18,8 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插
 
 输入栏为 `'conversation.input.plan'` 和 `'conversation.input.model'` 声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。InputBar 将模型 seat 渲染在 pending 指示器与发送／停止按钮之前。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。常驻无会话壳使用 `DisabledInputBar`，因此不会分发任何会话作用域的控件 seat。
 
+聊天统计行只从 `ConversationSnapshot.metrics` 读取持久的 token 计数与当前上下文压力；可见节点仅提供既有的轮次和步骤计数。它以相互独立的紧凑值显示未缓存输入、输出与缓存读取，通过 `cacheRead / (uncachedInput + cacheRead)` 计算缓存命中率而不计入缓存写入，并根据所选路由的精确容量显示上下文占用率。Host 数据缺失时标为「未知」，绝不根据分页窗口重建。
+
 `src/client/` 按未来的包拆分组织：`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明 + 组合后的 slot props，包括工具行契约、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/`（示例注册方）领域目录只导入 contract 文件，彼此绝不导入；`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件（骨架、聊天行）与 store factory 保持内部状态，只能通过 apply 的 slot 注册到达页面（测试通过 `./src/*` 子路径获取它们）。
 
 ## 模型体验

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

@@ -5,48 +5,63 @@ import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/clien
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import css from './StatsLine.module.css'
 
-interface UsageTotals {
+type SessionMetrics = NonNullable<ConversationSnapshot['metrics']>
+
+interface VisibleCounts {
   turns: number
   steps: number
-  tokens: number
-  cacheHitPct: number | null
-}
-
-/** Token accounting slice of assistant `usage` (typed upstream as unknown). */
-interface UsageLike {
-  inputTokens?: number
-  outputTokens?: number
-  cacheReadTokens?: number
 }
 
 /**
- * Fold assistant nodes into display totals.
+ * Count visible assistant turns and steps without treating the paged window
+ * as an accounting source.
  * @param nodes - snapshot nodes.
- * @returns totals; cacheHitPct null until any cache accounting arrives.
+ * @returns visible turn and step counts.
  */
-export function deriveStats(nodes: ConversationSnapshot['nodes']): UsageTotals {
+export function deriveVisibleCounts(nodes: ConversationSnapshot['nodes']): VisibleCounts {
   const turns = new Set<number>()
   let steps = 0
-  let tokens = 0
-  let input = 0
-  let cacheRead = 0
   for (const node of nodes) {
     if (node.kind !== 'assistant') continue
     turns.add(node.turn)
     steps += 1
-    const usage = node.usage as UsageLike | undefined
-    if (usage === undefined) continue
-    input += usage.inputTokens ?? 0
-    cacheRead += usage.cacheReadTokens ?? 0
-    tokens += (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0) + (usage.cacheReadTokens ?? 0)
-  }
-  const denom = input + cacheRead
-  return {
-    turns: turns.size,
-    steps,
-    tokens,
-    cacheHitPct: denom === 0 ? null : Math.round((cacheRead / denom) * 100),
   }
+  return { turns: turns.size, steps }
+}
+
+/**
+ * Format large token values with the status surfaces' compact suffix style.
+ * @param value - token count or model capacity.
+ * @returns locale-formatted count.
+ */
+export function formatMetricTokens(value: number): string {
+  if (value < 1_000) return value.toLocaleString('en-US')
+  return value.toLocaleString('en-US', {
+    notation: 'compact',
+    maximumFractionDigits: 1,
+  }).replace('K', 'k').replace('M', 'm').replace('B', 'b')
+}
+
+/**
+ * Existing Web cache-hit formula over disjoint uncached and cache-read input.
+ * @param metrics - Host-owned durable usage.
+ * @returns rounded integer percent, or null when no input was billed.
+ */
+export function cacheHitPercent(metrics: SessionMetrics): number | null {
+  const denominator = metrics.uncachedInputTokens + metrics.cacheReadTokens
+  return denominator === 0
+    ? null
+    : Math.round(metrics.cacheReadTokens / denominator * 100)
+}
+
+/**
+ * Current context occupancy using the TUI's integer rounding and upper clamp.
+ * @param metrics - Host-owned current pressure and exact route capacity.
+ * @returns occupancy percent, or null when either input is unavailable.
+ */
+export function contextPercent(metrics: SessionMetrics): number | null {
+  if (metrics.contextTokens === undefined || metrics.contextWindow === undefined) return null
+  return Math.min(100, Math.round(metrics.contextTokens / metrics.contextWindow * 100))
 }
 
 /** Props: the conversation-snapshot selector hook (handed down by ChatView). */
@@ -54,12 +69,33 @@ export interface StatsLineProps { useSession: SnapshotSelectorHook<ConversationS
 
 export const StatsLine = memo(function StatsLine({ useSession }: StatsLineProps) {
   const nodes = useSession(s => s.nodes)
-  const stats = useMemo(() => deriveStats(nodes), [nodes])
-  if (stats.steps === 0) return null
+  const metrics = useSession(s => s.metrics)
+  const counts = useMemo(() => deriveVisibleCounts(nodes), [nodes])
+  if (counts.steps === 0 && (
+    metrics === null
+    || (
+      metrics.uncachedInputTokens === 0
+      && metrics.outputTokens === 0
+      && metrics.cacheReadTokens === 0
+      && (metrics.contextTokens ?? 0) === 0
+    )
+  )) return null
   const parts: string[] = []
-  if (stats.cacheHitPct !== null) parts.push(`cache hit ${stats.cacheHitPct}%`)
-  parts.push(`${stats.tokens.toLocaleString('en-US')} tokens`)
-  parts.push(`${stats.turns} turns`)
-  parts.push(`${stats.steps} steps`)
+  if (metrics === null) {
+    parts.push('usage unknown')
+    parts.push('context unknown')
+  } else {
+    parts.push(`${formatMetricTokens(metrics.uncachedInputTokens)} uncached input`)
+    parts.push(`${formatMetricTokens(metrics.outputTokens)} output`)
+    parts.push(`${formatMetricTokens(metrics.cacheReadTokens)} cache read`)
+    const cacheHit = cacheHitPercent(metrics)
+    if (cacheHit !== null) parts.push(`cache hit ${cacheHit}%`)
+    const context = contextPercent(metrics)
+    parts.push(context === null
+      ? 'context unknown'
+      : `context ${context}% of ${formatMetricTokens(metrics.contextWindow as number)}`)
+  }
+  parts.push(`${counts.turns} turns`)
+  parts.push(`${counts.steps} steps`)
   return <div className={css.root}>{parts.join(' · ')}</div>
 })

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

@@ -129,15 +129,23 @@ describe('small branch tails', () => {
   })
 
   it('StatsLine omits the cache-hit segment when no input accounting exists at all', () => {
-    // cacheHitPct is null only when input+cacheRead are both zero (pure
-    // output accounting) — any input makes it a real 0%.
     const snap = {
       nodes: [{ kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [], usage: { outputTokens: 10 } }],
+      metrics: {
+        logRevision: 2,
+        projectionRevision: 0,
+        uncachedInputTokens: 0,
+        outputTokens: 10,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 5_000,
+      },
     }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
       <StatsLine useSession={bindSnapshotSelector(source) as unknown as StatsLineProps['useSession']} />,
     )
-    expect(view.getByText('10 tokens · 1 turns · 1 steps')).toBeTruthy()
+    expect(view.getByText(
+      '0 uncached input · 10 output · 0 cache read · context unknown · 1 turns · 1 steps',
+    )).toBeTruthy()
   })
 })

packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx

@@ -58,7 +58,7 @@ function snapshotWith(
     sessionId: SID, nodes, foldDegraded: false, partial: null, runningCalls, codeDispatches,
     pending: [], queue: [], todos: [], running: runningCalls.length > 0, composerPhase: 'active', removed: false,
     openState: 'open', openError: null,
-    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null,
+    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, metrics: null,
   }
 }
 

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

@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-// StatsLine (rendered inside the chat view body): totals derivation + the RFC
+// StatsLine (rendered inside the chat view body): durable metrics presentation + the RFC
 // hard acceptance — zero renders during streaming. Bash sample row: the
 // canonical sub-agent differential decided INSIDE the component off the
 // standard useSessions kit (no registry predicates — tool ring dissolved).
@@ -12,7 +12,10 @@ import type {
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { StatsLine, deriveStats, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
+import {
+  cacheHitPercent, contextPercent, deriveVisibleCounts, formatMetricTokens,
+  StatsLine, type StatsLineProps,
+} from '../src/client/chat/StatsLine.tsx'
 import { BashRow } from '../src/client/toolviews/bash-sample.tsx'
 
 afterEach(cleanup)
@@ -28,7 +31,7 @@ function snapshotBase(): ConversationSnapshot {
   return {
     sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
     pending: [], queue: [], todos: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
-    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null,
+    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, metrics: null,
   }
 }
 
@@ -50,27 +53,49 @@ function makeSource(init?: Partial<ConversationSnapshot>) {
   }
 }
 
-describe('deriveStats', () => {
-  it('folds turns/steps/tokens and cache hit percentage', () => {
-    const stats = deriveStats([
+describe('stats derivation', () => {
+  it('counts visible turns and steps without reading node usage', () => {
+    const stats = deriveVisibleCounts([
       assistant(1, 1, { inputTokens: 100, outputTokens: 50, cacheReadTokens: 900 }),
       assistant(2, 1, { inputTokens: 100, outputTokens: 50 }),
       assistant(3, 2),
     ])
     expect(stats.turns).toBe(2)
     expect(stats.steps).toBe(3)
-    expect(stats.tokens).toBe(1200)
-    expect(stats.cacheHitPct).toBe(82)
   })
 
-  it('cache hit stays null with no cache accounting; non-assistant nodes ignored', () => {
+  it('ignores non-assistant nodes', () => {
     const tool: ToolResultNode = {
       kind: 'tool-result', seq: 5, time: 5_000, callId: 'c', call: null, callTime: null, content: [],
       isError: false, callView: null, resultView: null,
     }
-    const stats = deriveStats([tool, assistant(1, 1)])
+    const stats = deriveVisibleCounts([tool, assistant(1, 1)])
     expect(stats.steps).toBe(1)
-    expect(stats.cacheHitPct).toBeNull()
+  })
+
+  it('keeps the cache formula disjoint from cache writes and rounds/clamps context like the TUI', () => {
+    const durable = {
+      logRevision: 20,
+      projectionRevision: 2,
+      uncachedInputTokens: 100,
+      outputTokens: 50,
+      cacheReadTokens: 900,
+      cacheWriteTokens: 50_000,
+      contextTokens: 34_500,
+      contextWindow: 100_000,
+    }
+    expect(cacheHitPercent(durable)).toBe(90)
+    expect(contextPercent(durable)).toBe(35)
+    expect(contextPercent({ ...durable, contextTokens: 200_000 })).toBe(100)
+    const { contextWindow: _contextWindow, ...withoutContextWindow } = durable
+    expect(contextPercent(withoutContextWindow)).toBeNull()
+    expect(cacheHitPercent({ ...durable, uncachedInputTokens: 0, cacheReadTokens: 0 })).toBeNull()
+  })
+
+  it('formats large values compactly in the existing en-US style', () => {
+    expect(formatMetricTokens(999)).toBe('999')
+    expect(formatMetricTokens(15_962)).toBe('16k')
+    expect(formatMetricTokens(2_172_544)).toBe('2.2m')
   })
 })
 
@@ -79,19 +104,65 @@ describe('StatsLine', () => {
     return { useSession: bindSnapshotSelector(source) }
   }
 
-  it('renders the joined stats row and hides with zero steps', () => {
+  it('renders separate durable counters, cache hit, context occupancy, and visible counts', () => {
     const { source } = makeSource({
       nodes: [assistant(1, 1, { inputTokens: 10, outputTokens: 5, cacheReadTokens: 90 })],
+      metrics: {
+        logRevision: 30,
+        projectionRevision: 4,
+        uncachedInputTokens: 120_237,
+        outputTokens: 13_881,
+        cacheReadTokens: 2_172_544,
+        cacheWriteTokens: 99_999,
+        contextTokens: 89_600,
+        contextWindow: 256_000,
+      },
     })
     const view = render(<StatsLine {...props(source)} />)
-    expect(view.getByText('cache hit 90% · 105 tokens · 1 turns · 1 steps')).toBeTruthy()
+    expect(view.getByText(
+      '120.2k uncached input · 13.9k output · 2.2m cache read · cache hit 95% · context 35% of 256k · 1 turns · 1 steps',
+    )).toBeTruthy()
     const empty = makeSource()
     const emptyView = render(<StatsLine {...props(empty.source)} />)
     expect(emptyView.container.textContent).toBe('')
   })
 
+  it('renders honest unknowns when the host projection is missing', () => {
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source)} />)
+    expect(view.getByText('usage unknown · context unknown · 1 turns · 1 steps')).toBeTruthy()
+  })
+
+  it.each([
+    { uncachedInputTokens: 1, outputTokens: 0, cacheReadTokens: 0, contextTokens: 0 },
+    { uncachedInputTokens: 0, outputTokens: 1, cacheReadTokens: 0, contextTokens: 0 },
+    { uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 1, contextTokens: 0 },
+    { uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, contextTokens: 1 },
+  ])('keeps a metrics-only row visible for each nonzero projection bucket', (nonzero) => {
+    const { source } = makeSource({
+      metrics: {
+        logRevision: 1,
+        projectionRevision: 0,
+        cacheWriteTokens: 0,
+        ...nonzero,
+      },
+    })
+    const view = render(<StatsLine {...props(source)} />)
+    expect(view.container.textContent).toContain('0 turns · 0 steps')
+  })
+
   it('renders ZERO times during streaming chunk frames (RFC hard acceptance)', () => {
-    const { set, source } = makeSource({ nodes: [assistant(1, 1)] })
+    const { set, source } = makeSource({
+      nodes: [assistant(1, 1)],
+      metrics: {
+        logRevision: 4,
+        projectionRevision: 0,
+        uncachedInputTokens: 1,
+        outputTokens: 1,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+      },
+    })
     let renders = 0
     function Counting(p: StatsLineProps) {
       renders += 1

packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx

@@ -41,7 +41,7 @@ function snapshotWith(nodes: ToolResultNode[]): ConversationSnapshot {
   return {
     sessionId: SID, nodes, foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
     pending: [], queue: [], todos: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
-    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null,
+    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, metrics: null,
   }
 }
 

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

@@ -31,7 +31,7 @@ function snapshotBase(): ConversationSnapshot {
   return {
     sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
     pending: [], queue: [], todos: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
-    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null,
+    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, metrics: null,
   }
 }
 

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

@@ -20,7 +20,7 @@ function snapshotBase(): ConversationSnapshot {
   return {
     sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
     pending: [], queue: [], todos: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
-    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null,
+    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, metrics: null,
   }
 }
 
@@ -36,7 +36,7 @@ describe('render branch tails', () => {
     expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull()
   })
 
-  it('StatsLine skips usage-less nodes and defaults each absent counter to zero', () => {
+  it('StatsLine takes durable counters from metrics while keeping visible node counts', () => {
     const snap = {
       nodes: [
         { kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [] },
@@ -44,12 +44,22 @@ describe('render branch tails', () => {
         // outputTokens absent: the tokens sum's ?? 0 arm for output.
         { kind: 'assistant', seq: 3, turn: 2, step: 1, blocks: [], usage: { inputTokens: 5 } },
       ],
+      metrics: {
+        logRevision: 9,
+        projectionRevision: 1,
+        uncachedInputTokens: 9,
+        outputTokens: 6,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+      },
     }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
       <StatsLine useSession={bindSnapshotSelector(source) as unknown as UseSession<ConversationSnapshot>} />,
     )
-    expect(view.getByText('cache hit 0% · 15 tokens · 2 turns · 3 steps')).toBeTruthy()
+    expect(view.getByText(
+      '9 uncached input · 6 output · 0 cache read · cache hit 0% · context unknown · 2 turns · 3 steps',
+    )).toBeTruthy()
   })
 
   it('AssistantMarkdown reasoning as the streaming tail renders the running ring', () => {

packages/client/ui-conversation/tests/input-bar.spec.tsx

@@ -23,7 +23,7 @@ function snapshotOf(overrides: Partial<ConversationSnapshot> = {}): Conversation
     sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
     pending: [], queue: [], todos: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
-    promptError: null, blank: false, lastAgentError: null,
+    promptError: null, blank: false, lastAgentError: null, metrics: null,
     ...overrides,
   }
 }

packages/client/ui-conversation/tests/input-matrix.spec.tsx

@@ -26,7 +26,7 @@ function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled
     sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
     pending: [], queue: [], todos: [], running: over?.running ?? false, composerPhase: 'active',
     removed: over?.disabled ?? false, openState: 'open', openError: null, hasMore: false,
-    loadingOlder: false, promptError: null, blank: false, lastAgentError: null,
+    loadingOlder: false, promptError: null, blank: false, lastAgentError: null, metrics: null,
   })
   const props: InputBarProps = {
     sessionId: SID,

packages/client/ui-conversation/tests/input-scenarios.spec.tsx

@@ -112,7 +112,7 @@ async function scopedBench(register?: (slash: SlashService) => void) {
     sessionId, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
     pending: [], queue: [], todos: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
-    promptError: null, blank: false, lastAgentError: null,
+    promptError: null, blank: false, lastAgentError: null, metrics: null,
   })
   const barProps: InputBarProps = {
     sessionId,

packages/client/ui-conversation/tests/queue-dock.spec.tsx

@@ -20,7 +20,7 @@ function snapshotWith(queue: QueuedMessage[]): ConversationSnapshot {
   return {
     sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
     pending: [], queue, todos: [], running: true, composerPhase: 'active', removed: false, openState: 'open', openError: null,
-    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null,
+    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null, metrics: null,
   }
 }
 

packages/client/ui-conversation/tests/skeleton.spec.tsx

@@ -50,7 +50,7 @@ function conversationSnapshot(overrides: Partial<ConversationSnapshot> = {}): Co
     sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
     pending: [], queue: [], todos: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
-    promptError: null, blank: false, lastAgentError: null,
+    promptError: null, blank: false, lastAgentError: null, metrics: null,
     ...overrides,
   }
 }