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 () => {