Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Hypatia May
2026-07-28 18:35:39 +08:00
parent 3f0ba77bfa
commit 35b9c454e5
54 changed files with 765 additions and 1352 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.agents/notes/implemented/architecture/2026-07-28-host-owned-web-session-metrics.i18n.yaml
View File

@@ -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 .agents/notes/implemented/architecture/2026-07-28-host-owned-web-session-metrics.md
2026-07-28-host-owned-web-session-metrics.md: 04381c7443491fd9de101a87713fa5c183800d0e
2026-07-28-host-owned-web-session-metrics.zh.md: 6ad06ea61508d3f0703c19bc7c9f14969f119334
2026-07-28-host-owned-web-session-metrics.md: e37a7635cbdae65162308bf8a3a498b5071a4910
2026-07-28-host-owned-web-session-metrics.zh.md: fd3e50c8cf8c0336a8cb2cd55f6629419bb8ad23

18
.agents/notes/implemented/architecture/2026-07-28-host-owned-web-session-metrics.md
View File

@@ -6,17 +6,19 @@ English | [中文](2026-07-28-host-owned-web-session-metrics.zh.md)
## Problem
A Web stats line derived from the currently loaded conversation nodes is window-dependent under pagination. Compaction can replace visible content without preserving historical usage, and route changes leave the browser without an authoritative context capacity. Cache-write tokens also risk being folded into a cache-hit formula whose denominator has different semantics.
A Web stats line derived from the currently loaded conversation nodes is window-dependent under pagination. Compaction can replace visible content without preserving historical usage, while the selected model does not prove that a request used its route or capacity. Cache-write tokens also risk being folded into a cache-hit formula whose denominator has different semantics.
## Decision
The Host owns one session-level metrics projection. It incrementally folds the complete durable event log, keys settled usage by `(turn, step)`, and replaces an earlier usage record for the same key instead of double-counting chunk and message forms. Uncached input, output, cache reads, and cache writes remain four disjoint cumulative buckets. Compaction can change the current prompt surface without erasing historical usage.
Current context pressure is a separate point-in-time value from `tokenMeter.measure(session).totalTokens`. Capacity comes only from `llm.resolveModelInfo(provider, model).context.contextWindow` for the agent's selected route. A route change immediately publishes metrics with capacity absent, then publishes the resolved capacity behind a route generation fence; stale metadata cannot label the new route.
Current context pressure is the point-in-time `tokenMeter.measure(session).totalTokens`. Capacity instead belongs to the latest model request observed by the current live mux connection. `LlmService.prepareCall()` retains the context metadata obtained by the exact lookup that also validates reasoning/defaults, and the loop publishes it through one contained `agent/model-request` notification only after the final route has a successfully constructed stream handle. Failed or aborted iteration still counts as a dispatched request; preparation and synchronous construction failures do not.
The tail `session.history` response carries the projection, while older pages omit it. Live changes use `session/metrics` mux frames. Both forms carry a durable-log revision and a projection revision; the client accepts only nondecreasing revisions, preserves metrics across older-page prepend, and clears them at a new subscription baseline. Missing measurement or metadata stays absent.
The tail `session.history` response carries durable usage and pressure, while older pages omit them. Live changes use `session/metrics` mux frames. Both forms carry a durable-log revision and a projection revision; the client accepts only nondecreasing revisions and preserves metrics across older-page prepend.
The Web stats line treats the projection as its sole token source. It renders uncached input, output, and cache reads separately, computes cache hit as `cacheRead / (uncachedInput + cacheRead)`, and shows current context as a percentage of the exact route capacity. Cache writes never enter that percentage. Visible nodes continue to supply only turn and step counts.
ApiProxy forwards each notification as a distinct `session/model-request` frame only to mux connections already open when dispatch occurs. It never places the frame in `session.history` or a subscription baseline. The client retains that connection-local capacity across ordinary metrics updates, replaces or explicitly clears it on the next observed request, and clears it on `session/subscribed`; reconnect, restore, and a new subscription therefore start unknown until another request is observed.
The Web stats line treats the durable projection plus live capacity overlay as its sole token source. It renders uncached input, output, and cache reads separately, computes cache hit as `cacheRead / (uncachedInput + cacheRead)`, and shows current context as a percentage only when the current connection observed a capacity. Cache writes never enter that percentage. Visible nodes continue to supply only turn and step counts.
## Alternatives considered
@@ -26,10 +28,12 @@ The Web stats line treats the projection as its sole token source. It renders un
**Reuse one total-token field for cache hit.** Cache reads, cache writes, and uncached input represent distinct provider accounting buckets; combining them would make the displayed rate misleading.
**Keep the previous capacity until the new route resolves.** The old number would temporarily claim the wrong selected model. An explicit unknown state is honest and generation-safe.
**Query the selected route before dispatch.** Selection may never produce a request, and a second metadata lookup can race the registration-bound lookup that actually validates and dispatches the call.
**Persist or replay the latest request capacity.** That would make a former request look current on reconnect or restore even though the new connection observed no request. The denominator is deliberately live and opportunistic.
## Consequences
Token totals remain stable across pagination, replay, compaction, and browser reconnect. The client stores a small detached projection instead of scanning the conversation window, and the status row remains readable for large histories through compact number formatting.
Token totals remain stable across pagination, replay, compaction, and browser reconnect. The client stores a small detached durable projection plus one connection-local denominator instead of scanning the conversation window, and the status row remains readable for large histories through compact number formatting.
The Host performs one incremental log fold per session and schedules live projection updates only for usage, request-header, or surface-changing events; text and reasoning deltas do not publish metrics. Exact capacity resolution is asynchronous and may briefly render as unknown. Deployments without a token meter or model context metadata retain the row and label the unavailable value instead of fabricating one.
The Host performs one incremental log fold per session and schedules durable projection updates only for usage, request-header, or surface-changing events; text and reasoning deltas do not publish metrics. A new connection omits the percentage until it observes a request with context metadata. A later request without metadata clears the denominator, while deployments without a token meter still retain the durable counters and label context unavailable instead of fabricating pressure.

18
.agents/notes/implemented/architecture/2026-07-28-host-owned-web-session-metrics.zh.md
View File

@@ -6,17 +6,19 @@ Status: implemented
## 问题
Web 统计行若根据当前加载的会话节点推导指标，其结果会随分页窗口变化。压缩（compaction）可以替换可见内容，却无法保留历史用量；路由变更会让浏览器缺少权威的上下文容量。缓存写入 token 还可能被计入缓存命中率公式，而该公式的分母具有不同语义。
Web 统计行若根据当前加载的会话节点推导指标，其结果会随分页窗口变化。压缩（compaction）可以替换可见内容，却无法保留历史用量；所选模型也不能证明某次请求实际采用了该模型的路由或容量。缓存写入 token 还可能被计入缓存命中率公式，而该公式的分母具有不同语义。
## 决策
Host 拥有一项会话级指标投影。它以增量方式归并完整的持久事件日志，按 `(turn, step)` 标识已结算用量；同一标识再次出现时，会替换较早的用量记录，而不会重复统计分片和消息两种形态。未缓存输入、输出、缓存读取与缓存写入保持为四个彼此独立的累计计数项。压缩可以改变当前提示词表层，但不会抹除历史用量。
当前上下文压力是一个独立的即时值，取自 `tokenMeter.measure(session).totalTokens`。容量仅来自 `llm.resolveModelInfo(provider, model).context.contextWindow`，并对应 agent（智能体）所选的路由。路由变更时，Host 会立即发布不带容量的指标，再通过路由代际围栏发布解析出的容量；陈旧元数据无法标记新的路由。
当前上下文压力是即时的 `tokenMeter.measure(session).totalTokens`。容量则属于当前实时 mux 连接观察到的最新模型请求。`LlmService.prepareCall()` 会保留同一次精确查询取得的上下文元数据，该查询也负责校验推理设置与默认值；仅在最终路由的流句柄成功构造后，循环才会通过一条失败会被收容的 `agent/model-request` 通知发布这些元数据。后续迭代失败或中止仍算作已分派请求；准备阶段失败和同步构造失败则不算。
`session.history` 尾页响应携带该投影，较早页面则省略它。实时变更使用 `session/metrics` mux 帧。两种形式都携带持久日志修订号和投影修订号；客户端只接受不减小的修订号，在向前加载较早页面时保留指标，并在建立新的订阅基线时将其清除。测量值或元数据缺失时，对应字段保持缺失。
`session.history` 尾页响应携带持久用量与压力，较早页面则省略这两项。实时变更使用 `session/metrics` mux 帧。两种形式都携带持久日志修订号和投影修订号；客户端只接受不减小的修订号，并在向前加载较早页面时保留指标。
Web 统计行把该投影视为唯一的 token 数据来源。它分别呈现未缓存输入、输出与缓存读取，通过 `cacheRead / (uncachedInput + cacheRead)` 计算缓存命中率，并把当前上下文显示为精确路由容量的百分比。缓存写入绝不计入缓存命中率。可见节点仍然只提供轮次和步骤计数。
ApiProxy 只把每条通知作为独立的 `session/model-request` 帧转发给分派发生时已经打开的 mux 连接。它绝不会把该帧放入 `session.history` 或订阅基线。客户端会在普通指标更新期间保留这项连接本地容量，在观察到下一次请求时替换或显式清除它，并在收到 `session/subscribed` 时将其清除；因此，重连、恢复和新订阅都会从未知容量开始，直到观察到另一次请求。
Web 统计行把持久投影与实时容量覆盖层视为唯一的 token 数据来源。它分别呈现未缓存输入、输出与缓存读取，通过 `cacheRead / (uncachedInput + cacheRead)` 计算缓存命中率，并且只有当前连接观察到容量时，才把当前上下文显示为该容量的百分比。缓存写入绝不计入缓存命中率。可见节点仍然只提供轮次和步骤计数。
## 备选方案
@@ -26,10 +28,12 @@ Web 统计行把该投影视为唯一的 token 数据来源。它分别呈现未
**为缓存命中率复用单一的 token 总数字段。** 缓存读取、缓存写入与未缓存输入是提供方记账中的不同计数项；将它们合并会使显示的比率产生误导。
**在新路由解析完成前保留旧容量。** 旧数值会在短时间内错误标示所选模型。显式的「未知」状态能如实反映情况，并避免跨代串扰。
**在分派前查询所选路由。** 选择操作可能永远不会产生请求；第二次元数据查询还可能与实际校验并分派调用的、绑定注册项的查询发生竞态。
**持久化或回放最新请求的容量。** 即使新连接没有观察到任何请求，这也会让先前请求在重连或恢复后显得仍然有效。该分母刻意只采用实时且恰好可得的数据。
## 后果
token 总量在分页、回放、压缩和浏览器重连期间保持稳定。客户端存储一项小型脱耦投影，无需扫描会话窗口；状态行采用紧凑数字格式，因此在较长的历史记录中仍然清晰易读。
token 总量在分页、回放、压缩和浏览器重连期间保持稳定。客户端存储一项小型、脱耦的持久投影与一个连接本地分母，无需扫描会话窗口；状态行采用紧凑数字格式，因此在较长的历史记录中仍然清晰易读。
Host 为每个会话执行一次增量日志归并，仅为用量事件、请求头事件或表层变更事件调度实时投影更新；文本与推理（reasoning）增量不会发布指标。精确容量解析为异步操作，因此可能短暂显示「未知」。未部署 token 计量器或缺少模型上下文元数据时，系统仍保留该行，并标示不可用的值，而不会虚构数据。
Host 为每个会话执行一次增量日志归并，仅为用量事件、请求头事件或表层变更事件调度持久投影更新；文本与推理（reasoning）增量不会发布指标。新连接在观察到带上下文元数据的请求之前不会显示百分比。后续不带元数据的请求会清除该分母；未部署 token 计量器时，系统仍保留持久计数器，并把上下文标示为不可用，而不会虚构压力值。