Merge origin/master into feat/close-todo
Keep master's session-projection carrier for todos, and fold turn/start clearance into the tool-todo projection unit (plus TUI/fixture mirrors).
This commit is contained in:
07akioni
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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/feature/2026-07-28-sdk-max-output-tokens.md
|
||||
2026-07-28-sdk-max-output-tokens.md: 5db48f21892d56addea7b72f73319f9dbfd1e71f
|
||||
2026-07-28-sdk-max-output-tokens.zh.md: 38b172718716d100726188163ff22be9ea0a7325
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: SDK max output tokens
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-28-sdk-max-output-tokens.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The Python and TypeScript SDKs could select a provider and model but could not bound conversation-model output. The runtime therefore omitted `GenerateOptions.maxTokens`, leaving provider defaults in control even when an evaluation host required a fixed output budget. `compact-basic.maxTokens` could not fill this role because it limits only compaction-summary calls.
|
||||
|
||||
## Decision
|
||||
|
||||
The high-level SDKs expose one optional process-wide output cap: Python names it `max_tokens`, TypeScript names it `maxTokens`, and the shared `initialize` wire payload carries `maxTokens`. The JSON-RPC server rejects values that are not positive safe integers and stores the accepted cap with its provider/model route.
|
||||
|
||||
Each SDK-created root Agent receives the cap through `AgentOptions.maxTokens`. Agent Loop places that value in the initial `LlmCallConfig`, logs it in the request header, and reconstructs every dispatched conversation request from that durable header. Omitting the option leaves `maxTokens` absent so the selected provider retains its default.
|
||||
|
||||
In-process subagents inherit the parent's provider, model, and output cap. An explicit `SubagentStartRequest.agentOptions.maxTokens`, including one configured by `dsh-tool-subagent`, overrides the inherited value for that child and its descendants. Out-of-process providers own the configuration of their separate runtime; `subagent-dsh-sdk` therefore exposes its own optional `maxTokens` and forwards it through that child runtime's SDK handshake.
|
||||
|
||||
Compaction, session-title generation, web search, and other auxiliary calls keep their independently owned output limits. `maxTokensAsSuccess` remains outcome mapping only: it does not set or alter the cap.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Set an adapter environment variable.** This would be DeepSeek-adapter-specific, invisible in the session request header, ineffective for intercepted or alternate adapters, and easy to confuse with a provider default. The cap belongs in provider-neutral request configuration.
|
||||
|
||||
**Add `maxTokens` to every `session/prompt`.** Per-turn mutation would enlarge the wire and introduce request-config transitions that callers do not need for the current evaluation use case. A runtime initialization option gives every session in one SDK process the same reproducible budget.
|
||||
|
||||
**Reuse `compact-basic.maxTokens`.** The compaction value controls summary generation, not ordinary conversation requests. Sharing it would couple two different token budgets and make tuning one silently change the other.
|
||||
|
||||
## Consequences
|
||||
|
||||
SDK callers can bound model output without editing Cordis composition, and direct Agent creation uses the same validated `AgentOptions` contract. The cap is visible in durable request headers and reaches provider adapters as `GenerateOptions.maxTokens`; DeepSeek serialization maps it to `max_tokens`.
|
||||
|
||||
One SDK runtime has one default cap. A caller needing different caps runs separate runtime instances or explicitly overrides an in-process child through its agent options. Reaching the cap still produces the existing `max-tokens` stop reason, whose `ok` or `error` mapping remains deployment policy.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: SDK 最大输出 token
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-28-sdk-max-output-tokens.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
Python 与 TypeScript SDK 可以选择提供方和模型，却无法限制对话模型输出。即使评测宿主要求固定输出预算，运行时仍会省略 `GenerateOptions.maxTokens`，由提供方默认值控制。`compact-basic.maxTokens` 只限制压缩摘要调用，不能承担这一职责。
|
||||
|
||||
## Decision
|
||||
|
||||
高层 SDK 公开一个可选的进程级输出上限：Python 命名为 `max_tokens`，TypeScript 命名为 `maxTokens`，共享的 `initialize` 线载荷使用 `maxTokens`。JSON-RPC 服务端拒绝非正安全整数，并将通过校验的上限与提供方／模型路由一同保存。
|
||||
|
||||
每个由 SDK 创建的根 Agent 都通过 `AgentOptions.maxTokens` 获得该上限。Agent Loop 将它放入初始 `LlmCallConfig`、记录到请求 header，并从该持久化 header 重建每次分派的对话请求。省略该选项时，`maxTokens` 保持缺失，由所选提供方保留默认值。
|
||||
|
||||
进程内 subagent 继承父级的提供方、模型和输出上限。显式的 `SubagentStartRequest.agentOptions.maxTokens`（包括通过 `dsh-tool-subagent` 配置的值）会覆盖该子级及其后代的继承值。进程外提供方自行持有其独立运行时的配置；因此 `subagent-dsh-sdk` 公开独立的可选 `maxTokens`，并通过该子运行时自己的 SDK 握手传入。
|
||||
|
||||
压缩、会话标题生成、网页搜索和其他辅助调用继续使用各自持有的独立输出上限。`maxTokensAsSuccess` 仍然只负责结果映射，不会设置或改变上限。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**设置适配器环境变量。** 这种方式仅适用于 DeepSeek 适配器，不会出现在会话请求 header 中，对被拦截请求或其他适配器无效，也容易与提供方默认值混淆。该上限属于提供方无关的请求配置。
|
||||
|
||||
**在每个 `session/prompt` 上增加 `maxTokens`。** 按轮次修改会扩大线协议，并引入当前评测用例不需要的请求配置转换。运行时初始化选项可让一个 SDK 进程中的每个会话拥有相同、可重现的预算。
|
||||
|
||||
**复用 `compact-basic.maxTokens`。** 压缩值控制摘要生成，而非普通对话请求。共用会耦合两类不同 token 预算，调整一方时会静默改变另一方。
|
||||
|
||||
## Consequences
|
||||
|
||||
SDK 调用方无需修改 Cordis 组合即可限制模型输出，直接创建 Agent 也使用同一套经过校验的 `AgentOptions` 契约。该上限在持久化请求 header 中可见，并以 `GenerateOptions.maxTokens` 到达提供方适配器；DeepSeek 序列化会将其映射为 `max_tokens`。
|
||||
|
||||
一个 SDK 运行时只有一个默认上限。需要不同上限的调用方应运行独立的 runtime 实例，或通过 agent options 显式覆盖某个进程内子级。达到上限时仍产生现有的 `max-tokens` 停止原因；将其映射为 `ok` 还是 `error` 仍由部署策略决定。
|
||||
@@ -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/feature/2026-07-28-todo-plan-clears-on-next-turn.md
|
||||
2026-07-28-todo-plan-clears-on-next-turn.md: daf25fd92eae4c6429a07c6864a20a828fa9dbcd
|
||||
2026-07-28-todo-plan-clears-on-next-turn.zh.md: 10b1c1c6b15d54b5cc30f4bbe36bb5e23befa3b6
|
||||
2026-07-28-todo-plan-clears-on-next-turn.md: 8a2808f5023a0800fbbeb65c5e28b3495e051dbc
|
||||
2026-07-28-todo-plan-clears-on-next-turn.zh.md: 6ea6b2b4fafe4b2f695ad2d54561f164747e5694
|
||||
|
||||
@@ -6,19 +6,19 @@ English | [中文](2026-07-28-todo-plan-clears-on-next-turn.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
`todo_write` stores whole-list snapshots on the session log, and interactive hosts render the latest list as a plan strip (web TodoPanel, TUI Plan panel). After a turn finished, that strip stayed on screen into the next user turn — a completed or abandoned checklist from the previous task. Readers treat the strip as "what this turn is doing," so a stale list across the turn boundary is the wrong product lifetime. The [web todo display](2026-07-23-web-todo-display.md) and [`todo_write` tool](2026-06-29-todo-write-tool.md) notes still own event-sourcing and the two render surfaces; they described the standing plan as lasting for the whole session until the next write.
|
||||
`todo_write` stores whole-list snapshots on the session log, and interactive hosts render the latest list as a plan strip (web TodoPanel via the `todos` projection, TUI Plan panel). After a turn finished, that strip stayed on screen into the next user turn — a completed or abandoned checklist from the previous task. Readers treat the strip as "what this turn is doing," so a stale list across the turn boundary is the wrong product lifetime. The [web todo display](2026-07-23-web-todo-display.md) and [`todo_write` tool](2026-06-29-todo-write-tool.md) notes still own event-sourcing and the two render surfaces; they described the standing plan as lasting for the whole session until the next write.
|
||||
|
||||
## Decision
|
||||
|
||||
The standing plan is the latest `todo/write` that is not followed by a later `turn/start`. `turn/end` keeps the list visible so the finished checklist remains while the user reads the answer; the next `turn/start` clears it until the model writes again.
|
||||
|
||||
### Live path
|
||||
### Host projection (web)
|
||||
|
||||
Web `Session.applyEventSideEffects` and the TUI `renderEvent` switch clear the strip on `turn/start` and replace it on `todo/write`. The TUI rebuild path resets the panel before replaying the log so cold resume converges on the same rule.
|
||||
`dsh-tool-todo`'s `todos` projection unit folds the rule: `apply` takes the whole list from each `todo/write` and returns `null` on each `turn/start` (`stateVersion` 2). Carriers (`dsh-host-apiproxy`) serve that value on the history tail `projections` block and push `session/projection` frames; the web dock reads it through `useProjection('todos')`. The keyless fixture mirrors the same fold for assembled snapshots.
|
||||
|
||||
### Cold-load / history projection
|
||||
### TUI live path
|
||||
|
||||
Host `backscanTodos` (and the fixture parallel) walks the full log from the tail: the first `turn/start` means no standing plan; the first `todo/write` is the standing list. Tail `session.history` still carries that projection (or omits it for empty). Client rebuild sweeps the window from an empty plan and restores the tail-page seed only when the window itself never determined the plan (no `todo/write` and no `turn/start`); a contiguous tail window that contains a post-write `turn/start` determines empty and matches the host.
|
||||
The TUI `renderEvent` switch still clears its local plan panel on `turn/start` and replaces it on `todo/write` (TUI is not yet a projection carrier). The rebuild path resets the panel before replaying the log so cold resume converges on the same rule.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
@@ -28,4 +28,4 @@ Host `backscanTodos` (and the fixture parallel) walks the full log from the tail
|
||||
|
||||
## Consequences
|
||||
|
||||
Interactive hosts and the history projection share one lifetime rule; reopening a session restores a plan only when no later turn has started. Partial supersession of the session-long standing-plan wording in [web todo display](2026-07-23-web-todo-display.md) and [`todo_write` tool](2026-06-29-todo-write-tool.md): event-sourcing, last-write-wins replacement, and the two render surfaces stay there; this note owns turn-boundary clearance. Coverage: client session specs for live clear + replay empty, host history projection after a post-write `turn/start`, the standing-plan web todo-display snapshot (fixture turn 65 remains the log tip), plus assembled web/TUI snapshots that start the next turn and pin the strip gone.
|
||||
The host projection and the TUI panel share one lifetime rule; reopening a session restores a plan only when no later turn has started. Partial supersession of the session-long standing-plan wording in [web todo display](2026-07-23-web-todo-display.md) and [`todo_write` tool](2026-06-29-todo-write-tool.md): event-sourcing, last-write-wins replacement, and the two render surfaces stay there; this note owns turn-boundary clearance. Coverage: tool-todo projection specs for turn/start clear + turn/end keep, fixture push-frame clearance for the assembled web snapshot, plus the TUI snapshot that starts the next turn and pins the strip gone.
|
||||
|
||||
@@ -1,31 +1,31 @@
|
||||
# Agent Note: Todo 计划条在下一轮 turn 开始时清空
|
||||
# Agent Note: 下一轮开始时清空 todo 计划条
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-28-todo-plan-clears-on-next-turn.md) | 中文
|
||||
|
||||
## Problem
|
||||
## 问题
|
||||
|
||||
`todo_write` 把整份列表快照写在会话日志上，交互式宿主把最新列表渲染为计划条（web TodoPanel、TUI Plan 面板）。一轮结束后，该条会一直留到下一个用户 turn——上一任务已完成或已放弃的清单仍挂在界面上。读者把计划条理解成「本轮在做什么」，因此跨 turn 边界的陈旧列表是错误的产品生命周期。[web todo 展示](2026-07-23-web-todo-display.md) 与 [`todo_write` 工具](2026-06-29-todo-write-tool.md) 两份 Note 仍拥有事件溯源与两个渲染面；它们曾把站立计划描述为整段会话持续到下一次写入。
|
||||
`todo_write` 在会话日志中存储整表快照，交互式宿主把最新列表渲染为计划条（web TodoPanel 经 `todos` 投影，TUI Plan 面板）。一轮结束后，该条仍留在下一用户轮次的屏幕上——上一任务已完成或已放弃的清单。读者把计划条理解为「本轮正在做什么」，因此跨轮次的陈旧列表是错误的产品生命周期。[web todo 展示](2026-07-23-web-todo-display.md)与 [`todo_write` 工具](2026-06-29-todo-write-tool.md)笔记仍拥有事件溯源与两个渲染面；它们把站立计划描述为持续整段会话直至下一次写入。
|
||||
|
||||
## Decision
|
||||
## 决策
|
||||
|
||||
站立计划是「其后没有更晚 `turn/start`」的最近一次 `todo/write`。`turn/end` 仍保留列表，便于用户阅读刚结束的回答时对照已完成清单；下一个 `turn/start` 将其清空，直到模型再次写入。
|
||||
站立计划是其后没有更晚 `turn/start` 的最近一次 `todo/write`。`turn/end` 保留列表可见，以便用户阅读回答时仍能看到刚完成的清单；下一次 `turn/start` 将其清空，直至模型再次写入。
|
||||
|
||||
### 实时路径
|
||||
### Host 投影（web）
|
||||
|
||||
Web 的 `Session.applyEventSideEffects` 与 TUI 的 `renderEvent` 开关在 `turn/start` 清空计划条，在 `todo/write` 替换它。TUI 重建路径在回放日志前复位面板，使冷恢复收敛到同一规则。
|
||||
`dsh-tool-todo` 的 `todos` 投影单元折叠该规则：`apply` 从每个 `todo/write` 取整表，并在每个 `turn/start` 返回 `null`（`stateVersion` 2）。载体（`dsh-host-apiproxy`）在历史尾页的 `projections` 块与 `session/projection` 推送帧上供给该值；web dock 经 `useProjection('todos')` 读取。无密钥 fixture（测试前置数据）镜像同一折叠，供组装后的 snapshot 使用。
|
||||
|
||||
### 冷加载 / history 投影
|
||||
### TUI 实时路径
|
||||
|
||||
Host 的 `backscanTodos`（以及 fixture 平行实现）从日志尾部向前扫描：先遇到 `turn/start` 表示没有站立计划；先遇到 `todo/write` 即为站立列表。尾页 `session.history` 仍携带该投影（空则省略）。客户端重建从空计划扫过窗口，仅当窗口本身从未判定计划（无 `todo/write` 且无 `turn/start`）时恢复尾页种子；连续尾窗口若含写入之后的 `turn/start` 则判定为空，与 host 一致。
|
||||
TUI 的 `renderEvent` 分支仍在 `turn/start` 清空本地计划面板、在 `todo/write` 替换之（TUI 尚非投影载体）。重建路径在回放日志前重置面板，使冷恢复收敛到同一规则。
|
||||
|
||||
## Alternatives considered
|
||||
## 考虑过的替代方案
|
||||
|
||||
- **在 `turn/end` 清空**——用户仍在阅读刚完成的回答时清单消失；此时计划条的职责正是展示完成态，而非空 dock。
|
||||
- **仅在全部 `completed` 时清空**——未完成或中途放弃的计划仍会跨 turn 残留；计划条会继续展示另一任务的工作。
|
||||
- **在 turn 开始时追加空的 `todo/write`**——为 UI 生命周期规则改写日志，并捏造模型从未写出的写入。
|
||||
- **在 `turn/end` 清空**——用户仍在阅读刚完成的回答时就隐藏清单；此时计划条的职责是已完成计划，而非空 dock。
|
||||
- **仅在全部项为 `completed` 时清空**——会让放弃或部分完成的计划跨轮残留；计划条仍会显示另一任务的工作。
|
||||
- **在 turn start 追加空的 `todo/write`**——为 UI 生命周期规则改写日志，并捏造模型从未写出的写入。
|
||||
|
||||
## Consequences
|
||||
## 后果
|
||||
|
||||
交互式宿主与 history 投影共用同一生命周期规则；重开会话仅在其后没有更新的 turn 启动时恢复计划。对 [web todo 展示](2026-07-23-web-todo-display.md) 与 [`todo_write` 工具](2026-06-29-todo-write-tool.md) 中「会话级站立计划」表述构成部分取代：事件溯源、后写覆盖与两个渲染面仍归那两份 Note；本 Note 拥有 turn 边界清空。覆盖：客户端 session 对实时清空 + 回放为空的用例、host 在写入后的 `turn/start` 之后的 history 投影、站立计划的 web todo-display 快照（fixture 第 65 轮仍是日志末端），以及开启下一 turn 并钉住计划条消失的 assembled web／TUI 快照。
|
||||
Host 投影与 TUI 面板共用同一生命周期规则；重新打开会话仅在其后没有更晚轮次开始时恢复计划。部分取代 [web todo 展示](2026-07-23-web-todo-display.md)与 [`todo_write` 工具](2026-06-29-todo-write-tool.md)中「会话级站立计划」的表述：事件溯源、last-write-wins 替换与两个渲染面仍归那些笔记；本笔记拥有轮次边界清空。覆盖：tool-todo 投影对 turn/start 清空与 turn/end 保留的规格测试、供组装 web snapshot 的 fixture 推送帧清空，以及启动下一轮并钉住计划条消失的 TUI snapshot。
|
||||
|
||||
Reference in New Issue
Block a user