fix(token-meter): close projected usage review gaps

2026-07-30 17:22:15 +08:00
parent e23cd8e406
commit 6d58953f30
43 changed files with 280 additions and 183 deletions
@@ -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: 84051dbe29503bcb20e317247db2ba2026db4528
-README.zh.md: 36a0983f95dafc55a4fc76a5bc82112fb369efce
+README.md: c5b10490abf42bcb04a675d50b3c487fdbf3f3b8
+README.zh.md: e8bca83ae56c638e7a8fb852c35164b1941d749f
@@ -22,7 +22,7 @@ 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'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop button), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `command.hint` locale namespace this package registers and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The resident no-session shell uses `DisabledInputBar` and therefore dispatches no session-scoped control seats.

-The chat stats line takes its token accounting from two generic token-meter projections read through the standard-kit `useProjection`: `tokenUsage` for full-log billing (cache hit is `cacheRead / (uncachedInput + cacheRead)`, excluding cache writes) and `contextPressure` for context occupancy. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting. A deployment without token-meter drops the token groups, and a route whose adapter advertises no capacity drops the occupancy group instead of rendering a placeholder. Occupancy is deliberately an approximation — its numerator and capacity are independent last-wins projection fields, not one atomic request observation ([rationale](../../llm/token-meter/README.md)). The inline stats row remains the sole context UI; the model selector has no circle or accessory.
+The chat stats line takes its token accounting from two generic token-meter projections read through the standard-kit `useProjection`: `tokenUsage` for full-log billing (billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total) and `contextPressure` for context occupancy. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. A deployment without token-meter drops the token groups, and occupancy stays hidden until both provider pressure and route capacity are known. Occupancy is deliberately an approximation — its numerator and capacity are independent last-wins projection fields, not one atomic request observation ([rationale](../../llm/token-meter/README.md)). The inline stats row remains the sole context UI; the model selector has no circle or accessory.

 `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).

@@ -22,7 +22,7 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插

 输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `command.hint` locale 命名空间本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。常驻无会话壳使用 `DisabledInputBar`，因此不会分发任何会话作用域的控件 seat。

-聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的两个通用 token-meter 投影：`tokenUsage` 提供完整日志计费用量（缓存命中率为 `cacheRead / (uncachedInput + cacheRead)`，不计入缓存写入），`contextPressure` 提供上下文占用率。可见节点只提供轮次与步骤计数，以及 LLM 和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目。未组合 token-meter 的部署会整组省略 token 分组；适配器未公布容量的路由会省略占用率分组，而不是渲染占位文案。占用率是刻意为之的近似值：它的分子与容量是两个相互独立的「后者胜」投影字段，并非同一次请求的原子观测（[原理](../../llm/token-meter/README.md)）。行内统计行仍是唯一的上下文 UI；模型选择器不增加圆环或附属控件。
+聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的两个通用 token-meter 投影：`tokenUsage` 提供完整日志计费用量（计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量），`contextPressure` 提供上下文占用率。可见节点只提供轮次与步骤计数，以及 LLM 和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。未组合 token-meter 的部署会整组省略 token 分组；只有提供方压力与路由容量都已知时才显示占用率。占用率是刻意为之的近似值：它的分子与容量是两个相互独立的「后者胜」投影字段，并非同一次请求的原子观测（[原理](../../llm/token-meter/README.md)）。行内统计行仍是唯一的上下文 UI；模型选择器不增加圆环或附属控件。

 `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/*` 子路径获取它们）。

@@ -78,23 +78,38 @@ export function formatDuration(ms: number): string {
 * @returns rounded integer percent, or null when no input was billed.
 */
 export function cacheHitPercent(usage: TokenUsageProjection): number | null {
-  const denominator = usage.uncachedInputTokens + usage.cacheReadTokens
+  const denominator = billedInputTokens(usage)
  return denominator === 0
    ? null
    : Math.round(usage.cacheReadTokens / denominator * 100)
 }

+/** Sum the three disjoint prompt-side billing buckets. */
+function billedInputTokens(usage: TokenUsageProjection): number {
+  return usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
+}
+
+interface ContextOccupancy {
+  percent: number
+  contextWindow: number
+}
+
 /**
 * Approximate context occupancy, using the TUI's integer rounding and upper
 * clamp. The numerator and capacity are independent last-wins projection
 * fields, so this is a reference figure rather than an exact measurement of one
 * request (see the token-meter README).
 * @param pressure - the session's context-pressure projection value.
- * @returns occupancy percent, or null when no capacity is known.
+ * @returns occupancy and its denominator, or null until both values are known.
 */
-export function contextPercent(pressure: ContextPressureProjection | undefined): number | null {
-  if (pressure?.contextWindow === undefined) return null
-  return Math.min(100, Math.round(pressure.pressureTokens / pressure.contextWindow * 100))
+export function contextOccupancy(
+  pressure: ContextPressureProjection | undefined,
+): ContextOccupancy | null {
+  if (pressure?.pressureTokens === undefined || pressure.contextWindow === undefined) return null
+  return {
+    percent: Math.min(100, Math.round(pressure.pressureTokens / pressure.contextWindow * 100)),
+    contextWindow: pressure.contextWindow,
+  }
 }

 /** Props: the conversation-snapshot selector plus the projection read seat. */
@@ -108,29 +123,31 @@ export const StatsLine = memo(function StatsLine({ useSession, useProjection }:
  const usage = useProjection('tokenUsage')
  const pressure = useProjection('contextPressure')
  const stats = useMemo(() => deriveStats(nodes), [nodes])
-  if (stats.steps === 0) return null
  // Pipe-separated groups (figma stats strip); a group with no data drops out whole.
-  const groups: string[] = [`${stats.turns} turns · ${stats.steps} steps`]
-  const durations: string[] = []
-  if (stats.llmMs > 0) durations.push(`LLM ${formatDuration(stats.llmMs)}`)
-  if (stats.toolMs > 0) durations.push(`Tool call ${formatDuration(stats.toolMs)}`)
-  if (durations.length > 0) groups.push(durations.join(' · '))
-  const context = contextPercent(pressure)
-  // Capacity absent (no token-meter composed, or an adapter that advertises
-  // none) drops the group: an unknown denominator has no percentage to show.
-  if (context !== null && pressure?.contextWindow !== undefined) {
-    groups.push(`Context ${context}% of ${formatTokens(pressure.contextWindow)}`)
+  const groups: string[] = []
+  if (stats.steps > 0) {
+    groups.push(`${stats.turns} turns · ${stats.steps} steps`)
+    const durations: string[] = []
+    if (stats.llmMs > 0) durations.push(`LLM ${formatDuration(stats.llmMs)}`)
+    if (stats.toolMs > 0) durations.push(`Tool call ${formatDuration(stats.toolMs)}`)
+    if (durations.length > 0) groups.push(durations.join(' · '))
+  }
+  const context = contextOccupancy(pressure)
+  if (context !== null) {
+    groups.push(`Context ${context.percent}% of ${formatTokens(context.contextWindow)}`)
  }
  // Billing rides the durable projection, so these survive paging and
-  // compaction; a deployment without token-meter drops the groups entirely.
-  if (usage !== undefined) {
+  // compaction. Suppress the empty projection on a brand-new session.
+  if (usage !== undefined
+    && (stats.steps > 0 || billedInputTokens(usage) > 0 || usage.outputTokens > 0)) {
    const cacheHit = cacheHitPercent(usage)
    if (cacheHit !== null) groups.push(`Cache hit ${cacheHit}%`)
    groups.push(
-      `Input ${formatTokens(usage.uncachedInputTokens + usage.cacheReadTokens)} tok`
+      `Input ${formatTokens(billedInputTokens(usage))} tok`
      + ` · Output ${formatTokens(usage.outputTokens)} tok`,
    )
  }
+  if (groups.length === 0) return null
  return (
    <div className={css.root}>
      {groups.map((group, i) => (
@@ -218,8 +218,8 @@ describe('small branch tails', () => {
  })

  it('StatsLine omits the cache-hit segment when no input accounting exists at all', () => {
-    // Cache hit is null only when uncached input and cache reads are both zero
-    // (pure output accounting) — any input makes it a real 0%.
+    // Cache hit is null only when all three prompt buckets are zero (pure
+    // output accounting) — any billed input makes it a real 0%.
    const snap = {
      nodes: [{ kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [], usage: { outputTokens: 10 } }],
    }
@@ -122,17 +122,30 @@ describe('StatsLine', () => {
    return { useSession: bindSnapshotSelector(source), useProjection: projections(values) }
  }

-  it('renders the grouped stats row and hides with zero steps', () => {
+  it('renders the grouped stats row and hides a brand-new empty session', () => {
    const { source } = makeSource({ nodes: [assistant(1, 1)] })
    const view = render(<StatsLine {...props(source)} />)
    // No timing on the fixture: the duration group drops out whole. Tokens come
    // from the projection, so paging the window cannot change them.
    expect(view.container.textContent).toBe('1 turns · 1 steps|Cache hit 90%|Input 100 tok · Output 5 tok')
    const empty = makeSource()
-    const emptyView = render(<StatsLine {...props(empty.source)} />)
+    const emptyView = render(<StatsLine {...props(empty.source, {
+      tokenUsage: { uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
+      contextPressure: {},
+    })} />)
    expect(emptyView.container.textContent).toBe('')
  })

+  it('keeps durable token and context groups after the visible step window is empty', () => {
+    const { source } = makeSource()
+    const view = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
+    })} />)
+    expect(view.container.textContent)
+      .toBe('Context 25% of 128K|Cache hit 90%|Input 100 tok · Output 5 tok')
+  })
+
  it('renders context occupancy only when the projection knows a capacity', () => {
    const { source } = makeSource({ nodes: [assistant(1, 1)] })
    const withCapacity = render(<StatsLine {...props(source, {
@@ -146,6 +159,13 @@ describe('StatsLine', () => {
      contextPressure: { pressureTokens: 32_000 },
    })} />)
    expect(noCapacity.container.textContent).not.toContain('Context')
+    // Capacity arrives before usage in the log; no provider sample means there
+    // is no numerator yet, rather than a synthetic 0%.
+    const noPressure = render(<StatsLine {...props(source, {
+      tokenUsage: USAGE,
+      contextPressure: { contextWindow: 128_000 },
+    })} />)
+    expect(noPressure.container.textContent).not.toContain('Context')
  })

  it('clamps occupancy at 100% when pressure exceeds the recorded capacity', () => {
@@ -173,6 +193,20 @@ describe('StatsLine', () => {
    expect(view.container.textContent).toBe('1 turns · 1 steps|Input 0 tok · Output 7 tok')
  })

+  it('includes cache writes in billed input and the cache-hit denominator', () => {
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source, {
+      tokenUsage: {
+        uncachedInputTokens: 10,
+        outputTokens: 7,
+        cacheReadTokens: 90,
+        cacheWriteTokens: 100,
+      },
+    })} />)
+    expect(view.container.textContent)
+      .toBe('1 turns · 1 steps|Cache hit 45%|Input 200 tok · Output 7 tok')
+  })
+
  it('renders ZERO times during streaming chunk frames (RFC hard acceptance)', () => {
    const { set, source } = makeSource({ nodes: [assistant(1, 1)] })
    let renders = 0