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

packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: d6db9a9541b0727b61dbe501f7234564ffef139e
-README.zh.md: 4175c8fdb98aad2882718a2c95cd9e45825d787d
+README.md: fa6fcb17ad3f2332e71e00387034fd7196759d8f
+README.zh.md: cfdf0d772ac81a4e569a799569b5de6e509f3b6f

packages/host/apiproxy/README.md

@@ -18,7 +18,7 @@ Workspace and Session lists are separate reconnect baselines. `workspace.create`
 
 `host.pickDirectory` opens one native directory picker and returns its selected path, or `null` when the user cancels. Its host implementation invokes platform tools without a shell: `osascript` on macOS, an STA PowerShell `FolderBrowserDialog` on Windows, and Zenity with a KDialog fallback on Linux. The picker function is injectable for tests. This user-paced method is the sole unary call exempt from the default 30-second timeout; caller and connection aborts still propagate to the native process. The browser carrier separately restricts this privileged method to loopback, same-origin requests.
 
-`session.history` pages on message boundaries, and its tail page (no `beforeSeq`) carries two session-level extras the page window cannot supply: the in-flight partial's chunk events, and `todos` — the latest `todo/write` whole-list projection over the full log. Older pages omit `todos` because the projection is session-level, not per-page; a tail response that omits it means the whole log holds no `todo/write`, so clients read the absent field as the empty plan rather than as unchanged state.
+`session.history` pages on message boundaries, and its tail page (no `beforeSeq`) carries session-level projections the page window cannot supply: the in-flight partial's chunk events; `todos`, the latest `todo/write` whole-list projection; and `metrics`, full-log usage deduplicated by `(turn, step)` plus current token-meter pressure and exact selected-route capacity when available. Older pages omit the session-level projections. Live `session/metrics` mux frames carry monotonic log/projection revisions, so clients reject stale frames and preserve the counters while prepending older pages. Cache reads and writes remain disjoint buckets; the cache-hit denominator is uncached input plus cache reads.
 
 The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `command.execute` runs a slash-command line host-side and returns a detached result; the carrier's request signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
 

packages/host/apiproxy/README.zh.md

@@ -18,7 +18,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `host.pickDirectory` 会打开一个原生目录选择器并返回选中的路径；用户取消时返回 `null`。宿主实现不经 shell 调用平台工具：macOS 使用 `osascript`，Windows 使用以 STA 模式运行的 PowerShell `FolderBrowserDialog`，Linux 使用 Zenity，并以 KDialog 作为回退。选择器函数可在测试中注入。该方法需等待用户完成操作，是唯一不受默认 30 秒超时限制的一元调用；调用方发出的中止信号和连接中止仍会传播至原生进程。浏览器载体另行将这一特权方法限制为仅接受来自回环地址的同源请求。
 
-`session.history` 按消息边界分页，其尾页（不带 `beforeSeq`）额外携带两项页窗口本身无法提供的会话级数据：进行中局部消息的 chunk 事件，以及 `todos`——整份日志上最后一次 `todo/write` 的整表投影。较早的页面不带 `todos`，因为该投影是会话级而非分页级的；尾页响应缺少该字段意味着整份日志中没有任何 `todo/write`，因此客户端要把缺失字段读作空计划，而不是读作「状态未变」。
+`session.history` 按消息边界分页，其尾页（不带 `beforeSeq`）携带页窗口本身无法提供的会话级投影：进行中局部消息的分片事件；`todos`，即最后一次 `todo/write` 的整表投影；以及 `metrics`，即按 `(turn, step)` 去重的完整日志用量，并在可用时包含当前 token 计量压力和所选精确路由的容量。较早的页面省略会话级投影。实时 `session/metrics` mux 帧携带单调递增的日志修订号与投影修订号，因此客户端会拒绝陈旧帧，并在向前加载较早页面时保留计数器。缓存读取与缓存写入保持为彼此独立的计数项；缓存命中率的分母是未缓存输入加缓存读取。
 
 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`command.execute` 在宿主侧运行一条斜杠命令行并返回脱耦结果；载体的请求信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
 

packages/host/apiproxy/src/api-proxy.ts

@@ -40,6 +40,7 @@ import type {
 } from '@deepseek-ai/dsh-user-interaction'
 import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
 import { pickNativeDirectory } from './native-directory-picker.ts'
+import { affectsSessionMetrics, SessionMetricsProjector } from './session-metrics.ts'
 
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
@@ -417,6 +418,54 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     for (const queue of muxQueues) queue.push(envelope)
   }
 
+  const pendingMetricSessions = new Set<Session>()
+  let metricFlushScheduled = false
+  let metricsDisposed = false
+  const metricsProjector = new SessionMetricsProjector(
+    ctx,
+    agent => targetFor(agent).current,
+    (agent) => { scheduleMetrics(agent.session) },
+  )
+
+  /** Queue one full-log metrics publication after synchronous session listeners drain. */
+  function scheduleMetrics(session: Session): void {
+    if (metricsDisposed || muxQueues.size === 0) return
+    pendingMetricSessions.add(session)
+    if (metricFlushScheduled) return
+    metricFlushScheduled = true
+    queueMicrotask(() => {
+      metricFlushScheduled = false
+      if (metricsDisposed) {
+        pendingMetricSessions.clear()
+        return
+      }
+      const sessions = [...pendingMetricSessions]
+      pendingMetricSessions.clear()
+      for (const current of sessions) {
+        broadcast({
+          type: 'session/metrics',
+          sessionId: current.id,
+          metrics: metricsProjector.snapshot(current, ctx.agents.get(current.id)),
+        })
+      }
+    })
+  }
+
+  ctx.effect(() => {
+    const disposers = [
+      ctx.on('session/event', (session: Session, event: SessionEvent) => {
+        if (affectsSessionMetrics(event)) scheduleMetrics(session)
+      }),
+      ctx.on('agent/created', (agent: Agent) => { scheduleMetrics(agent.session) }),
+      ctx.on('session/disposed', (session: Session) => { pendingMetricSessions.delete(session) }),
+    ]
+    return () => {
+      metricsDisposed = true
+      pendingMetricSessions.clear()
+      for (const dispose of disposers) dispose()
+    }
+  }, 'api-proxy: session metrics')
+
   /**
    * Per-session inbox mirror serving the mux-open queue snapshot (the same
    * refresh-recovery baseline as pending questions). Keyed by the stable
@@ -723,7 +772,15 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         // log (the page window may not contain the last todo/write; a paged
         // client cannot reconstruct session-level state from it).
         const todos = beforeSeq === undefined ? backscanTodos(found.agent.session.events) : undefined
-        return ok(request, { events: entries, hasMore: page.hasMore, ...todos === undefined ? {} : { todos } })
+        const metrics = beforeSeq === undefined
+          ? metricsProjector.snapshot(found.agent.session, found.agent)
+          : undefined
+        return ok(request, {
+          events: entries,
+          hasMore: page.hasMore,
+          ...todos === undefined ? {} : { todos },
+          ...metrics === undefined ? {} : { metrics },
+        })
       },
 
       async models(request) {
@@ -817,6 +874,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               : { reasoningEffort: resolved.reasoningEffort },
           }
           targetFor(found.agent).current = selected
+          broadcast({
+            type: 'session/metrics',
+            sessionId: found.agent.session.id,
+            metrics: metricsProjector.snapshot(found.agent.session, found.agent),
+          })
           return ok(request, { selected: { ...selected } })
         } catch (error: unknown) {
           return err(request, {
@@ -1102,6 +1164,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         muxQueues.add(queue)
         for (const session of ctx.sessions.list()) {
           subscribeSession(queue, session)
+          queue.push(frame({
+            type: 'session/metrics',
+            sessionId: session.id,
+            metrics: metricsProjector.snapshot(session, ctx.agents.get(session.id)),
+          }))
         }
         for (const pending of pendingQuestions.values()) {
           queue.push({
@@ -1154,6 +1221,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           }),
           ctx.on('session/created', (session: Session) => {
             subscribeSession(queue, session)
+            queue.push(frame({
+              type: 'session/metrics',
+              sessionId: session.id,
+              metrics: metricsProjector.snapshot(session, ctx.agents.get(session.id)),
+            }))
           }),
           ctx.on('session/disposed', (session: Session) => {
             openCalls.delete(session.id)

packages/host/apiproxy/src/api/events.schema.ts

@@ -10,7 +10,9 @@ import type { HostFrame, MuxFrame } from './events.ts'
 import type { Wire } from './rpc.schema.ts'
 import { rpcErrorSchema, rpcIdSchema } from './rpc.schema.ts'
 import { approvalRequestIdSchema } from './approvals.schema.ts'
-import { contentBlockSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema } from './sessions.schema.ts'
+import {
+  contentBlockSchema, sessionEventSchema, sessionIdSchema, sessionMetricsSchema, toolEventViewSchema,
+} from './sessions.schema.ts'
 import { workspaceIdSchema, workspaceViewSchema } from './workspace.schema.ts'
 
 /** Question shape validated strictly against core dsh-user-interaction. */
@@ -27,6 +29,7 @@ export const askUserQuestionItemSchema = z.object({
 export const muxFrameSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('session/event'), sessionId: sessionIdSchema, event: sessionEventSchema, view: toolEventViewSchema.optional() }),
   z.object({ type: z.literal('session/subscribed'), sessionId: sessionIdSchema, lastSeq: z.number().int() }),
+  z.object({ type: z.literal('session/metrics'), sessionId: sessionIdSchema, metrics: sessionMetricsSchema }),
   z.object({ type: z.literal('session/title'), sessionId: sessionIdSchema, title: z.string().min(1), eventSeq: z.number().int().nonnegative(), updatedAt: z.number() }),
   z.object({ type: z.literal('approval/requested'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, toolName: z.string(), callId: z.string().optional(), reason: z.string().optional() }),
   z.object({ type: z.literal('approval/resolved'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, outcome: z.union([z.literal('allowed-once'), z.literal('rejected'), z.literal('cancelled'), z.literal('unavailable')]) }),

packages/host/apiproxy/src/api/events.ts

@@ -13,6 +13,7 @@ import type { CallId } from '@deepseek-ai/dsh-llm/brand'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
 import type { RpcError, RpcId, RpcRequest } from './rpc.ts'
+import type { SessionMetrics } from './sessions.ts'
 import type { WorkspaceView } from './workspace.ts'
 
 // Client-side consumers take the render-intent vocabulary from the contract;
@@ -57,6 +58,7 @@ export interface EventsApi {
 export type MuxFrame =
   | { type: 'session/event'; sessionId: SessionId; event: SessionEvent; view?: ToolEventView }
   | { type: 'session/subscribed'; sessionId: SessionId; lastSeq: number }
+  | { type: 'session/metrics'; sessionId: SessionId; metrics: SessionMetrics }
   | { type: 'session/title'; sessionId: SessionId; title: string; eventSeq: number; updatedAt: number }
   | { type: 'approval/requested'; sessionId: SessionId; approvalId: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string }
   | { type: 'approval/resolved'; sessionId: SessionId; approvalId: ApprovalRequestId; outcome: ApprovalOutcome }

packages/host/apiproxy/src/api/index.ts

@@ -27,7 +27,7 @@ export interface ApiProxy {
 // ---- Domain interfaces and payload entities ----
 export type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, SessionModels, SessionsApi, SessionSummary,
+  ModelReasoningEffort, ModelTarget, SessionMetrics, SessionModels, SessionsApi, SessionSummary,
 } from './sessions.ts'
 export type { HostApi } from './host.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -11,7 +11,7 @@ import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, SessionSummary,
+  ModelReasoningEffort, ModelTarget, SessionMetrics, SessionSummary,
 } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
 import type { WorkspaceId } from './workspace.ts'
@@ -145,11 +145,24 @@ export const todoItemSchema = z.object({
   status: z.union([z.literal('pending'), z.literal('in_progress'), z.literal('completed')]),
 })
 
+/** Host-owned durable usage and current-context projection. */
+export const sessionMetricsSchema = z.object({
+  logRevision: z.number().int().nonnegative(),
+  projectionRevision: z.number().int().nonnegative(),
+  uncachedInputTokens: z.number().nonnegative(),
+  outputTokens: z.number().nonnegative(),
+  cacheReadTokens: z.number().nonnegative(),
+  cacheWriteTokens: z.number().nonnegative(),
+  contextTokens: z.number().nonnegative().optional(),
+  contextWindow: z.number().int().positive().optional(),
+}) satisfies z.ZodType<Wire<SessionMetrics>>
+
 /** session.history response value. */
 export const sessionHistoryValueSchema = z.object({
   events: z.array(historyEntrySchema),
   hasMore: z.boolean(),
   todos: z.array(todoItemSchema).optional(),
+  metrics: sessionMetricsSchema.optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.history'>>>
 
 /** session.models request payload. */

packages/host/apiproxy/src/api/sessions.ts

@@ -32,6 +32,31 @@ export interface HistoryEntry {
   view?: ToolEventView
 }
 
+/**
+ * Host-owned token metrics for one durable session revision. Provider usage
+ * buckets are cumulative across the full log; current context fields describe
+ * the replayed request surface at this revision and are absent when the Host
+ * cannot measure pressure or resolve exact-route capacity.
+ */
+export interface SessionMetrics {
+  /** Number of durable events included in this projection. */
+  logRevision: number
+  /** Monotone ordering within one Host process and mux subscription generation. */
+  projectionRevision: number
+  /** Cumulative uncached provider input. */
+  uncachedInputTokens: number
+  /** Cumulative provider output. */
+  outputTokens: number
+  /** Cumulative provider cache reads. */
+  cacheReadTokens: number
+  /** Cumulative provider cache writes; excluded from the Web cache-hit formula. */
+  cacheWriteTokens: number
+  /** Current request pressure from `ctx.tokenMeter.measure(session).totalTokens`. */
+  contextTokens?: number
+  /** Exact selected-route capacity from `ctx.llm.resolveModelInfo()`. */
+  contextWindow?: number
+}
+
 /** Complete model target selected for one session. */
 export interface ModelTarget {
   /** Registered provider route. */
@@ -153,9 +178,11 @@ export interface SessionsApi {
    * projection (latest `todo/write` over the FULL log, independent of the page window) —
    * so a paged client restores the plan without walking history; absent when the session
    * never wrote one. Older pages omit it (the projection is session-level, not per-page).
+   * The same tail-only rule carries `metrics`, whose cumulative usage and current context
+   * are Host projections over the full log rather than products of the returned page.
    */
   history(request: RpcRequest<{ sessionId: SessionId; beforeSeq?: number; maxMessages?: number }>):
-  Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean; todos?: TodoItem[] }>>
+  Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean; todos?: TodoItem[]; metrics?: SessionMetrics }>>
 
   /** Reads a fresh advisory model directory for this session. Provider lookups run independently. */
   models(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<SessionModels>>

packages/host/apiproxy/src/session-metrics.ts

@@ -0,0 +1,194 @@
+/**
+ * Full-log usage and current-context projection for Web clients.
+ *
+ * @module @deepseek-ai/dsh-host-apiproxy/session-metrics
+ */
+
+import type { Context } from 'cordis'
+import type { Agent, AgentLlmTarget } from '@deepseek-ai/dsh-agent'
+import type { TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { SessionMetrics } from './api/sessions.ts'
+
+interface UsageState {
+  logRevision: number
+  projectionRevision: number
+  uncachedInputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
+  byStep: Map<string, TokenUsage>
+}
+
+interface CapacityState {
+  routeKey: string
+  generation: number
+  status: 'pending' | 'ready'
+  contextWindow?: number
+}
+
+interface TokenMeterLike {
+  measure(session: Session): { totalTokens: number }
+}
+
+interface LlmLike {
+  resolveModelInfo(provider: string, model: string): Promise<{
+    context?: { contextWindow: number }
+  }>
+}
+
+function usageFrom(event: SessionEvent): { turn: number; step: number; usage: TokenUsage } | undefined {
+  if (event.type === 'assistant/chunk' && event.data.chunk.type === 'usage') {
+    return { turn: event.data.turn, step: event.data.step, usage: event.data.chunk.usage }
+  }
+  if (event.type === 'assistant/message' && event.data.usage !== undefined) {
+    return { turn: event.data.turn, step: event.data.step, usage: event.data.usage }
+  }
+  return undefined
+}
+
+/**
+ * Whether an appended event can change cumulative usage or token-meter
+ * pressure. Text/reasoning stream deltas remain outside both projections.
+ * @param event - appended durable event.
+ * @returns true when the Host must publish a fresh metrics snapshot.
+ */
+export function affectsSessionMetrics(event: SessionEvent): boolean {
+  if (event.type === 'assistant/chunk') return event.data.chunk.type === 'usage'
+  if (event.type === 'request/header') return true
+  return 'surfaceOp' in event
+}
+
+function recordUsage(state: UsageState, turn: number, step: number, usage: TokenUsage): void {
+  const key = `${turn}:${step}`
+  const previous = state.byStep.get(key)
+  if (previous !== undefined) {
+    state.uncachedInputTokens -= previous.inputTokens
+    state.outputTokens -= previous.outputTokens
+    state.cacheReadTokens -= previous.cacheReadTokens ?? 0
+    state.cacheWriteTokens -= previous.cacheWriteTokens ?? 0
+  }
+  state.byStep.set(key, usage)
+  state.uncachedInputTokens += usage.inputTokens
+  state.outputTokens += usage.outputTokens
+  state.cacheReadTokens += usage.cacheReadTokens ?? 0
+  state.cacheWriteTokens += usage.cacheWriteTokens ?? 0
+}
+
+/**
+ * Projects durable cumulative usage and route-aware current context without
+ * awaiting model metadata on the session append path.
+ */
+export class SessionMetricsProjector {
+  private readonly usage = new WeakMap<Session, UsageState>()
+  private readonly capacities = new WeakMap<Agent, CapacityState>()
+
+  /**
+   * @param ctx - Host context providing optional token-meter and LLM services.
+   * @param targetFor - selected route owner for one attached Web agent.
+   * @param onCapacityResolved - schedules a fresh live projection after exact-route metadata resolves.
+   */
+  constructor(
+    private readonly ctx: Context,
+    private readonly targetFor: (agent: Agent) => Pick<AgentLlmTarget, 'provider' | 'model'>,
+    private readonly onCapacityResolved: (agent: Agent) => void,
+  ) {}
+
+  /**
+   * Read a fresh detached projection through the session's durable tail.
+   * @param session - authoritative durable log owner.
+   * @param agent - attached route owner, when available.
+   * @returns cumulative usage and any currently available pressure/capacity.
+   */
+  snapshot(session: Session, agent?: Agent): SessionMetrics {
+    const state = this.syncUsage(session)
+    const tokenMeter = this.ctx.get('tokenMeter') as TokenMeterLike | undefined
+    let contextTokens: number | undefined
+    if (tokenMeter !== undefined) {
+      try {
+        contextTokens = tokenMeter.measure(session).totalTokens
+      } catch {
+        // A malformed or temporarily unmeasurable replay has no honest pressure value.
+      }
+    }
+    const contextWindow = agent === undefined ? undefined : this.capacityFor(agent)
+    return {
+      logRevision: state.logRevision,
+      projectionRevision: state.projectionRevision++,
+      uncachedInputTokens: state.uncachedInputTokens,
+      outputTokens: state.outputTokens,
+      cacheReadTokens: state.cacheReadTokens,
+      cacheWriteTokens: state.cacheWriteTokens,
+      ...contextTokens === undefined ? {} : { contextTokens },
+      ...contextWindow === undefined ? {} : { contextWindow },
+    }
+  }
+
+  private syncUsage(session: Session): UsageState {
+    let state = this.usage.get(session)
+    if (state === undefined) {
+      state = {
+        logRevision: 0,
+        projectionRevision: 0,
+        uncachedInputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        byStep: new Map(),
+      }
+      this.usage.set(session, state)
+    }
+    while (state.logRevision < session.events.length) {
+      const event = session.events[state.logRevision]
+      /* v8 ignore next -- Session events are append-only and dense; logRevision is bounded by length. */
+      if (event === undefined) break
+      const usage = usageFrom(event)
+      if (usage !== undefined) recordUsage(state, usage.turn, usage.step, usage.usage)
+      state.logRevision++
+    }
+    return state
+  }
+
+  private capacityFor(agent: Agent): number | undefined {
+    const target = this.targetFor(agent)
+    const routeKey = `${target.provider}\u0000${target.model}`
+    let state = this.capacities.get(agent)
+    if (state === undefined || state.routeKey !== routeKey) {
+      state = {
+        routeKey,
+        generation: (state?.generation ?? 0) + 1,
+        status: 'pending',
+      }
+      this.capacities.set(agent, state)
+      this.resolveCapacity(agent, target, state)
+    }
+    return state.status === 'ready' ? state.contextWindow : undefined
+  }
+
+  private resolveCapacity(
+    agent: Agent,
+    target: Pick<AgentLlmTarget, 'provider' | 'model'>,
+    pending: CapacityState,
+  ): void {
+    const llm = this.ctx.get('llm') as LlmLike | undefined
+    if (llm === undefined) {
+      pending.status = 'ready'
+      return
+    }
+    void Promise.resolve()
+      .then(() => llm.resolveModelInfo(target.provider, target.model))
+      .then(
+        (resolved) => {
+          if (this.capacities.get(agent)?.generation !== pending.generation) return
+          const current = this.targetFor(agent)
+          if (`${current.provider}\u0000${current.model}` !== pending.routeKey) return
+          pending.status = 'ready'
+          if (resolved.context !== undefined) pending.contextWindow = resolved.context.contextWindow
+          this.onCapacityResolved(agent)
+        },
+        () => {
+          if (this.capacities.get(agent)?.generation === pending.generation) pending.status = 'ready'
+        },
+      )
+  }
+}

packages/host/apiproxy/tests/api-proxy-models.spec.ts

@@ -19,6 +19,7 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { createApiProxy } from '../src/api-proxy.ts'
 
 let nextRpc = 1
@@ -52,6 +53,7 @@ class CatalogAdapter extends LlmAdapter {
       provider,
       id: model,
       name: model,
+      context: { contextWindow: model === 'private-preview' ? 128_000 : 64_000 },
       ...this.reasoning === undefined ? {} : { reasoning: this.reasoning },
     })
   }
@@ -117,6 +119,16 @@ function expectValue<T>(response: { result: { ok: true; value: T } | { ok: false
   return response.result.value
 }
 
+async function nextMetrics(
+  iterator: AsyncIterator<RpcRequest<MuxFrame>>,
+): Promise<Extract<MuxFrame, { type: 'session/metrics' }>['metrics']> {
+  for (;;) {
+    const next = await iterator.next()
+    if (next.done) throw new Error('mux ended before a metrics frame')
+    if (next.value.payload.type === 'session/metrics') return next.value.payload.metrics
+  }
+}
+
 describe('Web session model selection', () => {
   it('groups successful providers, isolates failures, and preserves an unlisted current model', async () => {
     const { ctx, sessionId } = await harness({
@@ -230,4 +242,26 @@ describe('Web session model selection', () => {
       .toEqual({ provider: 'deepseek', model: 'private-preview', reasoningEffort: 'max' })
     await ctx.fiber.dispose()
   })
+
+  it('publishes unknown capacity immediately on selection, then the exact selected route capacity', async () => {
+    const { ctx, sessionId } = await harness()
+    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const controller = new AbortController()
+    const iterator = api.events.mux(request({}), controller.signal)[Symbol.asyncIterator]()
+
+    expect((await nextMetrics(iterator)).contextWindow).toBeUndefined()
+    expect((await nextMetrics(iterator)).contextWindow).toBe(64_000)
+
+    expectValue(await api.sessions.selectModel(request({
+      sessionId,
+      provider: 'deepseek',
+      model: 'private-preview',
+    })))
+    expect((await nextMetrics(iterator)).contextWindow).toBeUndefined()
+    expect((await nextMetrics(iterator)).contextWindow).toBe(128_000)
+
+    controller.abort()
+    await iterator.return?.()
+    await ctx.fiber.dispose()
+  })
 })

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -10,7 +10,7 @@ import {
   sessionCreateValueSchema, sessionEventSchema, sessionHistoryRequestSchema, sessionHistoryValueSchema,
   sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionModelsRequestSchema,
   sessionModelsValueSchema, sessionPromptRequestSchema, sessionPromptValueSchema,
-  sessionSelectModelRequestSchema, sessionSelectModelValueSchema, sessionSummarySchema,
+  sessionSelectModelRequestSchema, sessionSelectModelValueSchema, sessionSummarySchema, sessionMetricsSchema,
 } from '../src/api/sessions.schema.ts'
 import { hostDescribeRequestSchema, hostDescribeValueSchema } from '../src/api/host.schema.ts'
 import {
@@ -138,8 +138,35 @@ describe('sessions domain schemas', () => {
     expect(sessionHistoryValueSchema.parse({
       events: [],
       hasMore: false,
+      metrics: {
+        logRevision: 12,
+        projectionRevision: 4,
+        uncachedInputTokens: 1_000,
+        outputTokens: 200,
+        cacheReadTokens: 4_000,
+        cacheWriteTokens: 500,
+        contextTokens: 8_000,
+        contextWindow: 128_000,
+      },
       modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
-    }).hasMore).toBe(false)
+    }).metrics?.contextWindow).toBe(128_000)
+    expect(() => sessionMetricsSchema.parse({
+      logRevision: 1,
+      projectionRevision: 0,
+      uncachedInputTokens: -1,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+    })).toThrow()
+    expect(() => sessionMetricsSchema.parse({
+      logRevision: 1,
+      projectionRevision: 0,
+      uncachedInputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      contextWindow: 0,
+    })).toThrow()
     expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionModelsValueSchema.parse({
       current: { provider: 'deepseek', model: 'deepseek-v4-flash', reasoningEffort: 'max' },
@@ -305,6 +332,18 @@ describe('events frame schemas', () => {
       { type: 'session/event', sessionId: 's', event: { type: 't', seq: 0, time: 1, data: null } },
       { type: 'session/subscribed', sessionId: 's', lastSeq: -1 },
       { type: 'session/title', sessionId: 's', title: 'Durable title', eventSeq: 2, updatedAt: 3 },
+      {
+        type: 'session/metrics',
+        sessionId: 's',
+        metrics: {
+          logRevision: 3,
+          projectionRevision: 1,
+          uncachedInputTokens: 100,
+          outputTokens: 20,
+          cacheReadTokens: 300,
+          cacheWriteTokens: 40,
+        },
+      },
       { type: 'approval/requested', sessionId: 's', approvalId: 'a', toolName: 'bash', callId: 'c', reason: 'r' },
       { type: 'approval/resolved', sessionId: 's', approvalId: 'a', outcome: 'allowed-once' },
       { type: 'question/requested', sessionId: 's', questions: [{ id: 'q', question: 'Q?', options: [{ label: 'L' }], multiSelect: true }] },

packages/host/apiproxy/tests/session-metrics.spec.ts

@@ -0,0 +1,277 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { Agent, AgentLlmTarget } from '@deepseek-ai/dsh-agent'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { affectsSessionMetrics, SessionMetricsProjector } from '../src/session-metrics.ts'
+
+function assistant(
+  session: Session,
+  turn: number,
+  step: number,
+  usage: {
+    inputTokens: number
+    outputTokens: number
+    cacheReadTokens?: number
+    cacheWriteTokens?: number
+  },
+): void {
+  session.append('assistant/chunk', {
+    turn,
+    step,
+    chunk: { type: 'usage', usage },
+  })
+  session.append('assistant/message', {
+    turn,
+    step,
+    content: [{ type: 'text', text: `answer-${turn}-${step}` }],
+    provenance: { provider: 'test', model: 'alpha' },
+    usage,
+  }, { surfaceOp: 'append' })
+}
+
+function agent(session: Session): Agent {
+  return { id: session.id, session } as Agent
+}
+
+describe('SessionMetricsProjector', () => {
+  it('filters text/reasoning stream deltas while retaining usage, headers, and surface mutations', () => {
+    const session = new Session(SessionId('metrics-filter'))
+    const text = session.append('assistant/chunk', {
+      turn: 1,
+      step: 1,
+      chunk: { type: 'text-delta', index: 0, text: 'x' },
+    })
+    const usage = session.append('assistant/chunk', {
+      turn: 1,
+      step: 1,
+      chunk: { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } },
+    })
+    const header = session.append('request/header', {
+      header: { config: { provider: 'test', model: 'alpha' } },
+      reason: 'initial',
+    })
+    const surface = session.append('user/message', {
+      content: [{ type: 'text', text: 'question' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    expect(affectsSessionMetrics(text)).toBe(false)
+    expect(affectsSessionMetrics(usage)).toBe(true)
+    expect(affectsSessionMetrics(header)).toBe(true)
+    expect(affectsSessionMetrics(surface)).toBe(true)
+  })
+
+  it('reconciles usage by turn:step, keeps cache writes disjoint, and survives a surface replacement', () => {
+    const ctx = new Context()
+    ctx.provide('tokenMeter', {
+      measure(session: Session) {
+        return { totalTokens: session.surface.nodes.length * 100 }
+      },
+    })
+    const session = new Session(SessionId('metrics-fold'))
+    const first = session.append('user/message', {
+      content: [{ type: 'text', text: 'large old surface' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    assistant(session, 1, 1, {
+      inputTokens: 11,
+      outputTokens: 3,
+      cacheReadTokens: 89,
+      cacheWriteTokens: 8,
+    })
+
+    const current: AgentLlmTarget = { provider: 'test', model: 'alpha' }
+    const projector = new SessionMetricsProjector(ctx, () => current, () => {})
+    const attached = agent(session)
+    const before = projector.snapshot(session, attached)
+    expect(before).toMatchObject({
+      uncachedInputTokens: 11,
+      outputTokens: 3,
+      cacheReadTokens: 89,
+      cacheWriteTokens: 8,
+      contextTokens: 200,
+    })
+
+    const assistantSeq = session.surface.nodes.at(-1)
+    if (assistantSeq === undefined) throw new Error('assistant surface missing')
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'compact summary' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }, {
+      surfaceOp: { op: 'replace', start: first.seq, end: assistantSeq },
+      sourceEventSeqs: [first.seq, assistantSeq],
+    })
+    // A replayed usage event for the same step replaces the settled value.
+    session.append('assistant/chunk', {
+      turn: 1,
+      step: 1,
+      chunk: {
+        type: 'usage',
+        usage: {
+          inputTokens: 12,
+          outputTokens: 4,
+          cacheReadTokens: 88,
+          cacheWriteTokens: 9,
+        },
+      },
+    })
+    const compacted = projector.snapshot(session, attached)
+    expect(compacted).toMatchObject({
+      uncachedInputTokens: 12,
+      outputTokens: 4,
+      cacheReadTokens: 88,
+      cacheWriteTokens: 9,
+      contextTokens: 100,
+    })
+    assistant(session, 1, 2, {
+      inputTokens: 1_000,
+      outputTokens: 500,
+      cacheReadTokens: 2_000,
+      cacheWriteTokens: 3_000,
+    })
+
+    const after = projector.snapshot(session, attached)
+    expect(after).toMatchObject({
+      logRevision: session.events.length,
+      projectionRevision: 2,
+      uncachedInputTokens: 1_012,
+      outputTokens: 504,
+      cacheReadTokens: 2_088,
+      cacheWriteTokens: 3_009,
+      contextTokens: 200,
+    })
+    expect(after.uncachedInputTokens).not.toBe(
+      after.uncachedInputTokens + after.cacheReadTokens + after.cacheWriteTokens,
+    )
+  })
+
+  it('publishes only the selected route capacity when asynchronous resolutions race', async () => {
+    const ctx = new Context()
+    const resolutions = new Map<string, (contextWindow: number) => void>()
+    ctx.provide('tokenMeter', { measure: () => ({ totalTokens: 35_000 }) })
+    ctx.provide('llm', {
+      resolveModelInfo(_provider: string, model: string) {
+        return new Promise<{ context: { contextWindow: number } }>((resolve) => {
+          resolutions.set(model, (contextWindow) => { resolve({ context: { contextWindow } }) })
+        })
+      },
+    })
+    const session = new Session(SessionId('capacity-race'))
+    const attached = agent(session)
+    let current: AgentLlmTarget = { provider: 'test', model: 'alpha' }
+    const resolved = vi.fn()
+    const projector = new SessionMetricsProjector(ctx, () => current, resolved)
+
+    expect(projector.snapshot(session, attached).contextWindow).toBeUndefined()
+    await vi.waitFor(() => { expect(resolutions.has('alpha')).toBe(true) })
+    current = { provider: 'test', model: 'beta' }
+    expect(projector.snapshot(session, attached).contextWindow).toBeUndefined()
+    await vi.waitFor(() => { expect(resolutions.has('beta')).toBe(true) })
+
+    resolutions.get('alpha')?.(64_000)
+    await Promise.resolve()
+    expect(resolved).not.toHaveBeenCalled()
+    resolutions.get('beta')?.(128_000)
+    await vi.waitFor(() => { expect(resolved).toHaveBeenCalledOnce() })
+    expect(projector.snapshot(session, attached)).toMatchObject({
+      contextTokens: 35_000,
+      contextWindow: 128_000,
+    })
+  })
+
+  it('omits current context fields when measurement or model metadata is unavailable', async () => {
+    const ctx = new Context()
+    ctx.provide('tokenMeter', { measure: () => { throw new Error('unmeasurable') } })
+    ctx.provide('llm', { resolveModelInfo: () => Promise.reject(new Error('metadata unavailable')) })
+    const session = new Session(SessionId('missing-metrics'))
+    const attached = agent(session)
+    const projector = new SessionMetricsProjector(
+      ctx,
+      () => ({ provider: 'test', model: 'missing' }),
+      () => {},
+    )
+    const metrics = projector.snapshot(session, attached)
+    expect(metrics.contextTokens).toBeUndefined()
+    expect(metrics.contextWindow).toBeUndefined()
+    await vi.waitFor(() => {
+      expect(projector.snapshot(session, attached).contextWindow).toBeUndefined()
+    })
+  })
+
+  it('keeps optional usage buckets at zero and tolerates absent host services or detached agents', async () => {
+    const ctx = new Context()
+    const session = new Session(SessionId('optional-metrics'))
+    assistant(session, 1, 0, { inputTokens: 7, outputTokens: 2 })
+    const attached = agent(session)
+    const projector = new SessionMetricsProjector(
+      ctx,
+      () => ({ provider: 'test', model: 'no-service' }),
+      () => {},
+    )
+
+    expect(projector.snapshot(session)).toMatchObject({
+      uncachedInputTokens: 7,
+      outputTokens: 2,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+    })
+    expect(projector.snapshot(session, attached).contextWindow).toBeUndefined()
+    expect(projector.snapshot(session, attached).contextWindow).toBeUndefined()
+    await Promise.resolve()
+  })
+
+  it('publishes a resolved route with no advertised capacity as unknown', async () => {
+    const ctx = new Context()
+    ctx.provide('llm', { resolveModelInfo: () => Promise.resolve({}) })
+    const session = new Session(SessionId('no-capacity'))
+    const attached = agent(session)
+    const resolved = vi.fn()
+    const projector = new SessionMetricsProjector(
+      ctx,
+      () => ({ provider: 'test', model: 'metadata-without-context' }),
+      resolved,
+    )
+
+    expect(projector.snapshot(session, attached).contextWindow).toBeUndefined()
+    await vi.waitFor(() => { expect(resolved).toHaveBeenCalledOnce() })
+    expect(projector.snapshot(session, attached).contextWindow).toBeUndefined()
+  })
+
+  it('ignores stale resolution failures and route metadata after the target moves', async () => {
+    const ctx = new Context()
+    const resolutions = new Map<string, {
+      resolve(value: { context: { contextWindow: number } }): void
+      reject(error: Error): void
+    }>()
+    ctx.provide('llm', {
+      resolveModelInfo(_provider: string, model: string) {
+        return new Promise<{ context: { contextWindow: number } }>((resolve, reject) => {
+          resolutions.set(model, { resolve, reject })
+        })
+      },
+    })
+    const session = new Session(SessionId('stale-capacity'))
+    const attached = agent(session)
+    let current: AgentLlmTarget = { provider: 'test', model: 'alpha' }
+    const resolved = vi.fn()
+    const targetFor = vi.fn(() => current)
+    const projector = new SessionMetricsProjector(ctx, targetFor, resolved)
+
+    projector.snapshot(session, attached)
+    await vi.waitFor(() => { expect(resolutions.has('alpha')).toBe(true) })
+    current = { provider: 'test', model: 'route-moved-before-snapshot' }
+    resolutions.get('alpha')?.resolve({ context: { contextWindow: 64_000 } })
+    await vi.waitFor(() => { expect(targetFor).toHaveBeenCalledTimes(2) })
+    expect(resolved).not.toHaveBeenCalled()
+
+    projector.snapshot(session, attached)
+    await vi.waitFor(() => { expect(resolutions.has('route-moved-before-snapshot')).toBe(true) })
+    current = { provider: 'test', model: 'beta' }
+    projector.snapshot(session, attached)
+    await vi.waitFor(() => { expect(resolutions.has('beta')).toBe(true) })
+    resolutions.get('route-moved-before-snapshot')?.reject(new Error('stale failure'))
+    await Promise.resolve()
+    resolutions.get('beta')?.resolve({ context: { contextWindow: 128_000 } })
+    await vi.waitFor(() => { expect(resolved).toHaveBeenCalledOnce() })
+    expect(projector.snapshot(session, attached).contextWindow).toBe(128_000)
+  })
+})