子代理超长结果：保留首尾、持久化完整 final artifact，并支持按需恢复

[tt-a1i]

结论

OpenPI 当前对子代理最终结果采用“只保留头部”的截断策略。超过自动投递预算（约 24 KiB）后，报告结尾会被优先丢弃；父模型只能得到整个 Pi session JSONL 的路径，没有轻量、确定、低 token 的恢复方式。

这个问题真实存在，而且结尾通常承载 verdict、修改文件、风险、未完成项和下一步，信息价值往往高于报告中段。

本 Issue 收敛为一个运行时方案：

按上下文预算保留 head + tail，把完整 final answer 保存成只读语义上的纯文本 artifact，并复用 Pi 原生 read 分页读取。

不新增 OpenPI 模型工具，不重启子代理，不要求模型遵守脆弱的“摘要必须写在某个位置”提示词合同。

当前行为与根因

extensions/subagents/index.ts 的 truncatedOutput() 对 snap.finalText 调用 truncateHead()：

const truncation = truncateHead(output, {
  maxBytes: Math.min(maxBytes, DEFAULT_MAX_BYTES),
  maxLines: Math.min(600, DEFAULT_MAX_LINES),
});

截断后只追加：

Full transcript in session file: ...jsonl

这带来四个问题：

1. 确定性丢尾部：verdict、文件清单和下一步常在结尾。
2. 恢复粒度错误：缺的是最终回答的一小段，指向的却是包含完整事件流、工具调用和 JSON 转义的 session JSONL。
3. 恢复成本过高：直接读取 JSONL 需要定位 assistant message、处理一行 JSON/转义和 offset；重新 subagent_send 又会产生额外模型调用。
4. 投影不一致：自动完成投递和 subagent_wait 都复用同一个 head-only 投影，因此显式等待也无法拿到尾部。

subagent_check 只提供约 2 KiB / 20 行最近活动预览，不是最终结果分页接口。

同类实现调研

Codex CLI / Codex Core

Codex 将子代理最后一条 assistant message 保存在：

AgentStatus::Completed(Option<String>)

完成时把该 payload 作为 inter-agent completion message 发给父代理。当前成功结果路径未看到显式截断；list_agents 返回的 AgentStatus 也可能携带完整 completed message。

源码：

• https://github.com/openai/codex/blob/main/codex-rs/core/src/agent/status.rs
• https://github.com/openai/codex/blob/main/codex-rs/core/src/session_prefix.rs
• https://github.com/openai/codex/blob/main/codex-rs/core/src/context/inter_agent_completion_message.rs
• https://github.com/openai/codex/blob/main/codex-rs/core/src/agent/control.rs

优点：实现简单，结果尾部不会因为固定 head cap 被确定性丢弃。

代价：长报告会完整进入父上下文；状态查询还可能再次携带完整结果。它解决了“拿不到”，没有解决“上下文预算与按需恢复”。OpenPI 不应照搬完整注入。

Hermes Agent

Hermes 的 delegation summary 路径已经实现了更完整的预算合同：

• 静态 max_summary_chars 默认 24,000 字符；
• 根据父上下文剩余 headroom 和同批子代理数量动态缩小单份预算；
• 超限后保留约 75% head + 25% tail，并按换行边界裁切；
• 完整 summary 保存为单独纯文本文件；
• footer 明确给出完整长度、保存路径，以及 read_file offset=... limit=200 的分页方式；
• 可选 output_schema 用于真正需要机器消费的结构化委派，并允许一次有界纠正。

源码与文档：

• https://github.com/NousResearch/hermes-agent/blob/main/tools/delegate_tool.py
• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/delegation.md

Hermes 的关键边界值得复用：上下文里放有界投影，磁盘上保留完整语义结果，父模型按需读取。

OpenPI 方案

1. 一个统一的结果投影

自动投递、subagent_wait 和其他最终结果消费者共用同一个函数：

finalText
  ├─ 未超 byte/line budget → 原样返回
  └─ 超预算
       ├─ head（约 75%）
       ├─ [... middle omitted ...]
       ├─ tail（约 25%）
       └─ footer（总量、artifact、读取指引）

继续使用 Pi 已有 truncateHead / truncateTail，同时遵守 byte 与 line 两个上限，不截断 UTF-8 字符。

2. 纯文本 artifact，而不是 session JSONL

只有确实发生截断时才保存：

<agentDir>/cache/openpi/subagent-results/<content-hash>.txt

合同：

• 内容只包含该次 finalText，没有工具事件、thinking 或 JSON 包装；
• 文件名由内容 hash 得出，不使用模型生成的 title/path；
• 创建目录与文件采用受限权限和不覆盖写入；
• 相同结果可复用同一 artifact；
• 如果写入失败，投影仍返回 head + tail，但必须明确说明全文未保存，不能给出虚假路径。

这个目录是可再生 cache，不改变 Pi session 的 source of truth。

3. 复用 Pi 原生 read

footer 给父模型可执行的恢复方式，例如：

[Output truncated: showing head and tail of 31.2KB total.
Full final answer: /.../cache/openpi/subagent-results/<hash>.txt
Use read with this path and a narrow offset/limit to inspect omitted sections.]

不新增 subagent_transcript：

• 避免增大和改变 delegate 工具 Schema；
• 避免重复实现 Pi 已有文件分页能力；
• artifact 是 final answer，不再要求模型解析 JSONL；
• 子代理权限和生命周期不变。

4. 暂不把结构化输出作为默认要求

提示模型“必须把总结写在末尾”不是运行时保证；强制所有子代理使用 schema 还会增加 prompt、重试和 provider 兼容复杂度。

真正需要机器消费的 structured delegation 可以后续单独设计。本 Issue 先用确定性的运行时投影保证普通文本报告不丢首尾。

安全与产品边界

• 不写项目工作区；artifact 只进入 Pi agent cache。
• 不从模型文本生成文件路径。
• 不跟随或覆盖已有文件。
• artifact 失败不会导致子代理成功结果变成失败；但必须诚实报告恢复能力缺失。
• 不把 artifact 注入子代理工具面；只有父会话通过已有 Pi read 按需读取。
• 不改变 spawn、wait、cancel、settle、自动唤醒或 child authority 合同。

不采纳的方案

1. 完整结果始终注入父上下文（Codex 路线）：简单，但长报告与大 fan-out 会直接放大上下文和缓存成本。
2. 只增加固定 tail summary prompt：无法由运行时保证，模型/provider 漂移后仍会丢信息。
3. 新增 subagent_transcript 工具：现阶段没有必要；纯文本 artifact + Pi read 已提供更小、更通用的机制。
4. 继续指向 session JSONL：恢复对象与用户真正需要的 final answer 不一致。
5. 只把 head cap 调大：推迟而非解决问题，同时增加父上下文成本。

验收标准

结果正确性

• 未超预算的结果逐字不变，不创建 artifact。
• 超 byte 上限时同时保留可识别的开头和结尾，中段明确标记省略。
• 超 line 上限时行为一致。
• UTF-8 / 中文边界不产生替换字符或半字符。
• footer 报告完整总量、artifact 路径和按需读取方式。
• artifact 内容与原始 finalText 逐字一致。

生命周期一致性

• 自动完成投递使用新投影。
• subagent_wait 的每个结果使用同一投影，并继续遵守总输出预算。
• 相同 finalText 多次投影不会生成冲突或错误内容。
• artifact 写入失败时仍交付 head + tail，并明确 fail-closed。

安全与回归

• 不使用 title、prompt、cwd 等不可信字符串构造 artifact 文件名。
• 不覆盖既有路径，不通过 symlink 写出 cache 目录。
• 不新增模型工具，不改变 OpenPI 能力披露与 child tool 分类。
• bun run check 通过。
• bun run test 通过。

价值

• 保留首尾高价值证据，减少父模型基于不完整报告做结论的概率；
• 无额外模型调用即可恢复完整内容；
• 正常短结果零新增上下文成本；
• 不扩大工具面，保持缓存 Schema 稳定；
• 使“完整执行事实、模型可见投影、TUI 展示”继续保持清晰分层。

[tt-a1i]

补充：真实模型验证、当前预算与 Hermes 动态预算

在实现完成后，又补做了一次真实模型链路验证，并重新核对了 OpenPI 与 Hermes 当前源码。下面把预算口径和下一步机会记录清楚。

1. DeepSeek 0731 真实 smoke

运行条件：

• OpenPI checkout：PR fix(subagents): preserve recoverable long results #89 当前提交 7061bb57840ac45b5425bf3e606c46db3058076a
• Pi 唯一 OpenPI 来源：该本地 checkout
• 父/子模型：seal/deepseek-v4-flash-0731-baidu
• 链路：openpi_load_tools(delegate) -> subagent_spawn -> subagent_wait
• 子代理被要求生成 BEGIN + 420 个连续编号行 + END

结果：

• 整轮耗时：69.489 秒
• 完整 final answer：36,997 bytes，422 个逻辑行
• 420 个编号行从 0001 到 0420，连续、唯一、无缺失
• subagent_wait 的父上下文投影保留了可识别的开头和结尾，中间出现明确的 middle omitted
• 完整正文写入 content-addressed artifact；文件 SHA-256 与文件名一致，权限为 0600
• artifact 与原始 final answer 逐字一致；模型最后一行没有换行，artifact 也原样保留这一事实

因此，PR #89 的结果不是只有单元测试证据：真实 provider、真实父子 Agent、真实长输出、投影和恢复路径均已贯通。

2. OpenPI 当前预算的准确口径

投递面	当前预算	说明
自动完成投递 / btw 结果	24 KiB / 子代理	同时受 600 行限制
subagent_wait	16 KiB / 子代理	同时受 600 行限制
单次 subagent_wait 总量	48 KiB	多个 section 共享
subagent_check 运行中预览	2 KiB / 20 行	不是最终结果恢复接口

这里的 KiB 是 UTF-8 bytes，不是字符或 token。24 KiB 对 ASCII 约等于 24,576 字符；对常见中文正文则大约只有三分之一的字符数。页脚、artifact 路径和省略标记是少量附加元数据，所以这些常量更准确地说是“首尾正文预算”，不是最终序列化 tool result 的绝对字节封顶。

本次 smoke 走 subagent_wait，因此使用 16 KiB 单代理预算；实际正文投影显示约 15.9 KiB，而不是自动完成投递面的 24 KiB。

3. 75/25 的含义与依据

75% head + 25% tail 是展示预算的分配，不是原始正文的保留比例。例如 36 KiB 原文遇到 16 KiB 展示预算，大致是 12 KiB 头部 + 4 KiB 尾部，中间约 20 KiB 省略。

这个比例不是理论最优值，而是针对 Agent 报告结构的可恢复工程启发式：

• 开头通常是任务理解、范围、前提和主要依据；
• 结尾通常是 verdict、修改文件、测试、风险、未完成项和下一步；
• 中间通常是更长的过程和逐项证据，需要时可以从 artifact 分页读取。

比例应服从内容语义，而不是成为通用定律。例如 Hermes 对 terminal 输出使用 40% head + 60% tail，因为错误、退出码和测试汇总更常出现在日志结尾；对子代理 summary 则使用约 75% + 25%。

4. Hermes 当前实现

核对基线：NousResearch/hermes-agent main，提交 30d4555085ec684ff140d5841b5456b5d2291a72。

Hermes 子代理 summary 当前合同：

• 静态上限 DEFAULT_MAX_SUMMARY_CHARS = 24000，单位是 characters；
• 最低可用预算 _MIN_SUMMARY_CHARS = 2000；
• 整批 summary 最多使用父上下文剩余 headroom 的 50%；
• 该批预算按同批子代理数量均分；
• 单份最终预算取 min(静态 24000 字符, 动态单份预算)；
• 超限后保留约 75% head + 25% tail，按换行边界裁切；
• 完整 summary 写入纯文本文件，footer 给出精确分页读取方式。

源码：

• 常量和 headroom 比例
• 75/25 投影与 artifact footer
• 动态预算算法

其核心近似公式是：

headroom_tokens = context_length - used_tokens - reserved_output_tokens
batch_tokens = headroom_tokens * 0.5
per_summary_chars = batch_tokens / child_count * 4

effective_cap = min(24000, max(2000, per_summary_chars))

例如父上下文只剩约 10,000 tokens，同批返回 4 个子代理：整批取 5,000 tokens，每份约 1,250 tokens，即约 5,000 字符，而不是让每份都占满 24,000 字符。

5. OpenPI 是否应该学习动态预算

结论：值得学习，但应作为当前 artifact/head-tail 基础之上的第二层，而不是替代它。

当前 PR 已解决“长结果确定性丢尾部、无法低成本恢复”的问题；动态预算解决的是另一个问题：当父上下文已经很满，或多个子代理同时完成时，如何避免一批本来合法的长结果共同挤爆父上下文。

OpenPI 已有一半基础：显式 subagent_wait 有 48 KiB 整体上限和 16 KiB 单份上限。主要缺口是自动完成批量投递：当前每个结果可各使用 24 KiB；若 4 个长结果在父 Agent 忙碌期间积累后一起 flush，理论正文投影可接近 96 KiB，尚未根据父上下文余量动态收缩。

建议采用两层边界：

1. 确定性静态兜底

   • 保留当前单份上限；
   • 给自动完成批量 flush 增加明确的 batch 总预算；
   • 无法取得可信上下文数据时仍能稳定、可测试地工作。

2. 有权威数据时动态收缩

   • 从 Pi 的 authoritative usage/context 状态读取父上下文容量、已用 tokens 和必要的输出保留；
   • 只使用剩余 headroom 的一部分，并按同批结果数量分配；
   • 单份预算取静态 cap、动态 cap 和 batch 剩余额度的最小值；
   • 保留最低可读窗口，完整正文始终由 artifact 承担恢复。

不要仅从 transcript 字符数猜 token，也不要为了动态预算引入第二套上下文 source of truth。若 Pi 当前没有稳定、同步、provider-neutral 的 headroom 数据，应先落静态 batch cap，再等待正确的 Pi seam。

6. 建议的后续验收

• 单个短结果仍逐字不变，不创建 artifact。
• 单个长结果仍遵守当前 75/25 + artifact 合同。
• N 个同时完成的自动投递不会超过明确的 batch 投影预算。
• 父上下文余量下降时，同一批结果的单份投影预算会确定性下降。
• 无法获得可信 headroom 时退回静态 batch cap，而不是失控或拒绝投递。
• 动态预算不能低于最小可读窗口；被省略内容始终可从 artifact 恢复。
• 中英文/UTF-8、byte/line 双限制、footer 元数据都计入端到端测试。
• 自动投递与显式 wait 使用同一个预算/投影原语，不再产生语义漂移。

范围判断

PR #89 可以继续被视为 #64 的第一阶段完成：先保证结果正确、首尾不丢、全文可恢复。动态 headroom 属于有价值的第二阶段优化；是否并入同一个 PR，应取决于能否找到 Pi 已有且权威的上下文余量 seam，而不是为了模仿 Hermes 临时复制一套 token 估算器。

[tt-a1i]

实现与验证已完成，已推送到 PR #89 的 3417cab。

实现

• 新增批次预算分配器：以 Pi 的 ctx.getContextUsage() 为唯一父上下文来源，不维护第二套 token 计数。
• 静态安全上限保持不变：
  • 自动投递：48 KiB/批、24 KiB/结果；
  • subagent_wait：48 KiB/批、16 KiB/结果。
• 有有效上下文读数时，最多使用父会话剩余 headroom 的 50%，按 4 UTF-8 bytes/token 估算，并先扣除标题、错误、分隔符等固定包装成本。
• 小结果会把未用预算让给长结果；上下文读数未知、压缩后暂不可用或非法时，确定性回退静态上限。
• 每个长结果仍保留约 75% 头部 + 25% 尾部；完整答案落为 content-addressed 私有 artifact。
• 修正了旧投影器的边界：maxBytes 现在约束完整投影（正文、省略标记、恢复说明、artifact 路径），不再只约束正文。

确定性验证

• 专项：26/26
• 全量：Node 844/844 + Vitest 30/30
• lint：通过
• typecheck：通过（仅保留 file-search 既有 Effect warnings）
• bun run check 唯一失败来自用户工作区已有、未纳入本 PR 的 extensions/sessions/index.ts 格式差异。

DeepSeek 0731 真实多子代理烟测

模型：seal/deepseek-v4-flash-0731-baidu，thinking=off。

• 一次启动并等待 4 个子代理；
• 每份完整结果 21,333 bytes、262 个逻辑行；
• subagent_wait 最终工具结果 48,773 bytes，低于 48 KiB 硬上限；
• 4/4 结果均保留 BEGIN 与 END；
• 4/4 均显示 middle omitted；
• 4/4 均给出独立 artifact；
• artifact 权限均为 0600，SHA-256 均与内容寻址文件名一致。

真实烟测验证了 Pi 运行时接线、四结果共享批次预算和完整 artifact 恢复。低 headroom 的动态收窄分支由确定性测试覆盖；没有通过人为灌入巨量上下文来伪造模型侧证据。