Model-relative session-reference budgets
模型相对会话引用预算
A fixed 64 KiB reference budget discards useful source context on large-context models. The target session header describes a prior request, while agent options seed routing; neither necessarily identifies the model selected for the entering step.
English
Problem
A fixed 64 KiB reference budget discards useful source context on large-context models. The target session header describes a prior request, while agent options seed routing; neither necessarily identifies the model selected for the entering step.
Decision
Session-reference observes the completed system-prompt/assemble waterfall with a local prepend listener and stores its provider/model pair in a WeakMap keyed by Agent. Preparation resolves that route through the optional LLM service; direct preparation before any assembly uses agent options. Diagnostics without an Agent do not update the map.
Each source receives max(65536, floor(contextWindow × 4 × referenceContextFraction)) bytes, with a default fraction of 0.2. Four bytes per token is a sizing heuristic. Explicit maxReferenceBytes bypasses model lookup and remains exact. Missing route, service, adapter, or capacity retains the floor; other lookup failures and cancellation propagate. An absent adapter does not prevent stream middleware from serving the route.
Alternatives considered
Read the header or options for every step. Either can select a stale model after a live switch. The completed assembly exposes the route captured by model selection.
Reassemble or redispatch request routing during pre-step. These operations repeat plugin effects and can capture a different selection. A local observer needs neither loop changes nor another public routing API.
Consequences
The budget grows with model capacity without changing projection, retention, or preview policy. It remains per source, not an aggregate token reservation. The listener is effect-owned and disposable; the map does not retain agents. Focused tests cover the floor, fractional conversion, explicit overrides, live selection, absent metadata, cancellation, lookup errors, and listener removal.
中文
Problem
固定的 64 KiB 引用预算会在大上下文模型上丢弃有用的来源上下文。目标会话头描述上一次请求，而 agent options 为路由提供初始值；两者都不一定标识当前进入步骤所选的模型。
Decision
Session-reference 通过本地 prepend 监听器观察已完成的 system-prompt/assemble 瀑布，并把 provider/model 对存入以 Agent 为键的 WeakMap。准备阶段通过可选 LLM 服务解析该路由；首次组装前直接准备则使用 agent options。不带 Agent 的诊断不会更新映射。
每个来源获得 max(65536, floor(contextWindow × 4 × referenceContextFraction)) 字节，默认比例为 0.2。每个 token 四字节是容量估算。显式 maxReferenceBytes 跳过模型查询并保持精确值。缺少路由、服务、适配器或容量时保留下限；其他查询失败和取消会传播。缺少适配器不妨碍流中间件处理该路由。
Alternatives considered
每步读取会话头或 options。 实时切换后，两者都可能选中旧模型。完成的组装公开模型选择所捕获的路由。
在 pre-step 中重新组装或重新分派请求路由。 这些操作会重复插件效果，并可能捕获不同的选择。本地观察器不需要修改循环或增加公共路由 API。
Consequences
预算随模型容量增长，不改变投影、保留或预览策略。它仍按来源计算，而不是聚合 token 预留。监听器由 effect 持有并可释放；映射不会保留 agent。聚焦测试覆盖下限、比例换算、显式覆盖、实时选择、元数据缺失、取消、查询错误与监听器移除。