refactor(web): publish transient model request capacity (round 1)

2026-07-28 18:35:39 +08:00
parent 3f0ba77bfa
commit 35b9c454e5
54 changed files with 765 additions and 1352 deletions
--- a/packages/client/runtime/README.i18n.yaml
+++ b/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: 935bb4908fc54fc629574963e28dc0ddcfb89a6c
-README.zh.md: 85d444ee5d973bb989232ecaf00f2312d3195c8d
+README.md: bc1149644d6112ca82c9a27912d1a58351cf84a5
+README.zh.md: 993625614061e819495b25f0851156ea20c62601
--- a/packages/client/runtime/README.md
+++ b/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 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.
+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. Durable `metrics` comes from tail history and live `session/metrics` frames, survives older-page prepend, and accepts only nondecreasing log and projection revisions. The Session separately retains capacity from the latest `session/model-request` observed on its current mux connection and overlays it onto metrics across ordinary usage/pressure updates. A later request replaces or clears that value, while `session/subscribed` clears both metrics ordering and capacity; reconnect, restore, and a new subscription therefore show no percentage until another request is observed. Missing metrics remain `null` rather than being inferred from the visible node window.

 ## Workspace and Session lists

--- a/packages/client/runtime/README.zh.md
+++ b/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` 携带两项由 Host 拥有的完整日志投影。`todos` 来自 history 尾页，在向前加载较早页面时保留，并随实时 `todo/write` 事件更新。`metrics` 来自 history 尾页和实时 `session/metrics` 帧，在向前加载较早页面时保留，并且只接受日志修订号与投影修订号均不减小的数据；订阅基线会在回放前将其清除，使新的流代次可以安全地从头开始计数修订号。缺失的 metrics 保持为 `null`，而不是根据可见节点窗口推断。
+客户端 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` 帧，在向前加载较早页面时保留，并且只接受日志修订号与投影修订号均不减小的数据。Session 另行保留当前 mux 连接观察到的最新 `session/model-request` 容量，并在普通用量／压力更新期间把它覆盖到 metrics 上。后续请求会替换或清除该值，`session/subscribed` 则同时清除指标顺序状态与容量；因此，重连、恢复和新订阅都不会显示百分比，直到观察到另一次请求。缺失的 metrics 保持为 `null`，而不是根据可见节点窗口推断。

 ## Workspace 与 Session 列表

--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -12,6 +12,15 @@ import type { PendingInteraction } from './pending.ts'

 export type { TodoItem }

+/**
+ * Durable Host metrics with the latest capacity observed on this live mux
+ * connection overlaid for presentation.
+ */
+export interface ConversationMetrics extends SessionMetrics {
+  /** Latest dispatched-request capacity; absent until observed or after reset/clear. */
+  contextWindow?: number
+}
+
 /** Assistant content blocks sorted by what the UI cares about
 *  (text body / collapsible reasoning / tool-call card head / other fallback). */
 export type AssistantBlock =
@@ -247,9 +256,9 @@ export interface ConversationSnapshot {
   *  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.
+   * Host-owned cumulative usage/current pressure with live mux-local capacity
+   * overlaid. Independent of `nodes` pagination; null until a tail response or
+   * live metrics frame supplies a current durable value.
   */
-  metrics: SessionMetrics | null
+  metrics: ConversationMetrics | null
 }
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -12,7 +12,7 @@ import type {
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { ObservableSnapshot } from '../contract/store.ts'
 import type {
-  CodeSubCall, ComposerPhase, ConversationNode, ConversationSnapshot, OpenState,
+  CodeSubCall, ComposerPhase, ConversationMetrics, ConversationNode, ConversationSnapshot, OpenState,
  PromptError, QueuedMessage, RunningToolCall,
 } from './conversation.ts'
 import type { PendingInteraction } from './pending.ts'
@@ -102,8 +102,10 @@ 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
+  /** Host-owned metrics with current-connection request capacity overlaid. */
+  private metrics: ConversationMetrics | null = null
+  /** Latest capacity observed on this mux connection, independent of durable metrics arrival. */
+  private contextWindow: number | undefined
  /** `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[]>()
@@ -367,6 +369,7 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
          this.queueRev++
          this.notifier.markDirty()
        }
+        this.contextWindow = undefined
        if (this.metrics !== null) {
          this.metrics = null
          this.notifier.markDirty()
@@ -377,6 +380,18 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
        this.installMetrics(frame.metrics)
        return
      }
+      case 'session/model-request': {
+        if (this.contextWindow === frame.contextWindow) return
+        this.contextWindow = frame.contextWindow
+        if (this.metrics !== null) {
+          const { contextWindow: _previous, ...durable } = this.metrics
+          this.metrics = frame.contextWindow === undefined
+            ? durable
+            : { ...durable, contextWindow: frame.contextWindow }
+          this.notifier.markDirty()
+        }
+        return
+      }
      case 'approval/requested': {
        const { type: _type, sessionId: _sid, ...payload } = frame
        this.mint(new PendingWait('approval', rpcId, this.sessionId, payload, m => this.api.respond(m)))
@@ -800,7 +815,9 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
        || metrics.projectionRevision < current.projectionRevision
      )
    ) return
-    this.metrics = metrics
+    this.metrics = this.contextWindow === undefined
+      ? metrics
+      : { ...metrics, contextWindow: this.contextWindow }
    this.notifier.markDirty()
  }

--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -51,7 +51,6 @@ function metrics(
    cacheReadTokens: 90,
    cacheWriteTokens: 3,
    contextTokens: 35,
-    contextWindow: 100,
    ...over,
  }
 }
@@ -146,7 +145,7 @@ 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 () => {
+  it('retains live capacity across metrics, replaces or clears it on requests, and resets at subscription', async () => {
    const { session } = await opened()
    const current = metrics(8, 10)
    session.handleMuxEnvelope('m1' as never, {
@@ -156,6 +155,20 @@ describe('live event path', () => {
    })
    expect(session.getSnapshot().metrics).toBe(current)

+    session.handleMuxEnvelope('request-1' as never, {
+      type: 'session/model-request',
+      sessionId: SID,
+      turn: 1,
+      step: 1,
+      provider: 'test',
+      model: 'alpha',
+      contextWindow: 128_000,
+    })
+    expect(session.getSnapshot().metrics).toEqual({
+      ...current,
+      contextWindow: 128_000,
+    })
+
    session.handleMuxEnvelope('m2' as never, {
      type: 'session/metrics',
      sessionId: SID,
@@ -166,7 +179,31 @@ describe('live event path', () => {
      sessionId: SID,
      metrics: metrics(7, 11, { uncachedInputTokens: 2 }),
    })
-    expect(session.getSnapshot().metrics).toBe(current)
+    expect(session.getSnapshot().metrics).toEqual({
+      ...current,
+      contextWindow: 128_000,
+    })
+
+    const ordinaryUpdate = metrics(9, 11, { contextTokens: 40 })
+    session.handleMuxEnvelope('m4' as never, {
+      type: 'session/metrics',
+      sessionId: SID,
+      metrics: ordinaryUpdate,
+    })
+    expect(session.getSnapshot().metrics).toEqual({
+      ...ordinaryUpdate,
+      contextWindow: 128_000,
+    })
+
+    session.handleMuxEnvelope('request-2' as never, {
+      type: 'session/model-request',
+      sessionId: SID,
+      turn: 2,
+      step: 1,
+      provider: 'test',
+      model: 'without-capacity',
+    })
+    expect(session.getSnapshot().metrics).toEqual(ordinaryUpdate)

    session.handleMuxEnvelope('sub' as never, {
      type: 'session/subscribed',
@@ -174,13 +211,25 @@ describe('live event path', () => {
      lastSeq: 5,
    })
    expect(session.getSnapshot().metrics).toBeNull()
+    session.handleMuxEnvelope('request-3' as never, {
+      type: 'session/model-request',
+      sessionId: SID,
+      turn: 3,
+      step: 1,
+      provider: 'test',
+      model: 'beta',
+      contextWindow: 256_000,
+    })
    const nextGeneration = metrics(0, 10, { contextTokens: 20 })
-    session.handleMuxEnvelope('m4' as never, {
+    session.handleMuxEnvelope('m5' as never, {
      type: 'session/metrics',
      sessionId: SID,
      metrics: nextGeneration,
    })
-    expect(session.getSnapshot().metrics).toBe(nextGeneration)
+    expect(session.getSnapshot().metrics).toEqual({
+      ...nextGeneration,
+      contextWindow: 256_000,
+    })
  })

  it('accumulates chunks into partial, then finalize swaps partial out as the node lands', async () => {
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
-README.md: 0674a596353aac024824489e5ca25615c7426bcd
-README.zh.md: 65d3eba678b7190d97244a54c629b78c7d24b8c0
+README.md: 1f47260f9034f22ba560552e5a99b938bf14ed6d
+README.zh.md: 7d9a9d2ab95d93668de216d64eee704bcc569547
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -18,7 +18,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'` 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.
+The chat stats line reads durable token counters/current pressure plus the runtime's connection-local capacity overlay 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 only after the current mux connection observes a model request with capacity. Before that request, after reconnect/restore/new subscription, or after a request without capacity, the percentage is omitted and context is labeled unknown rather than queried ahead or reconstructed from history.

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

--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -18,7 +18,7 @@ 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 数据缺失时标为「未知」，绝不根据分页窗口重建。
+聊天统计行只从 `ConversationSnapshot.metrics` 读取持久的 token 计数／当前压力，以及运行时提供的连接本地容量覆盖值；可见节点仅提供既有的轮次和步骤计数。它以相互独立的紧凑值显示未缓存输入、输出与缓存读取，通过 `cacheRead / (uncachedInput + cacheRead)` 计算缓存命中率而不计入缓存写入，并且只有当前 mux 连接观察到带容量的模型请求后才显示上下文占用率。在该请求之前、重连／恢复／新订阅之后，或在请求不带容量之后，系统都会省略百分比，并把上下文标为「未知」，而不会提前查询或根据历史记录重建。

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

--- a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
+++ b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
@@ -56,7 +56,7 @@ export function cacheHitPercent(metrics: SessionMetrics): number | null {

 /**
 * Current context occupancy using the TUI's integer rounding and upper clamp.
- * @param metrics - Host-owned current pressure and exact route capacity.
+ * @param metrics - Host-owned pressure plus current-connection request capacity.
 * @returns occupancy percent, or null when either input is unavailable.
 */
 export function contextPercent(metrics: SessionMetrics): number | null {
--- a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
@@ -127,6 +127,26 @@ describe('StatsLine', () => {
    expect(emptyView.container.textContent).toBe('')
  })

+  it('renders durable counters without a percentage before live capacity is observed', () => {
+    const { source } = makeSource({
+      nodes: [assistant(1, 1)],
+      metrics: {
+        logRevision: 4,
+        projectionRevision: 1,
+        uncachedInputTokens: 120,
+        outputTokens: 20,
+        cacheReadTokens: 30,
+        cacheWriteTokens: 10,
+        contextTokens: 8_000,
+      },
+    })
+    const view = render(<StatsLine {...props(source)} />)
+    expect(view.getByText(
+      '120 uncached input · 20 output · 30 cache read · cache hit 20% · context unknown · 1 turns · 1 steps',
+    )).toBeTruthy()
+    expect(view.container.textContent).not.toContain('% of')
+  })
+
  it('renders honest unknowns when the host projection is missing', () => {
    const { source } = makeSource({ nodes: [assistant(1, 1)] })
    const view = render(<StatsLine {...props(source)} />)