Skip to content

fix: preflight summary length budget + truncate-to-cap rescue (#1775) - #1779

Closed
ranxianglei wants to merge 1 commit into
masterfrom
2026-09-30_preflight-summary-length-rescue
Closed

ranxianglei wants to merge 1 commit into
masterfrom
2026-09-30_preflight-summary-length-rescue

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #1775

Problem

On large, tool-dense histories, preflight can spend minutes generating summaries that all exceed compress.maxSummaryLength (kernel default 20,000 chars) and discarding each one: every discard halves the span and regenerates from scratch, but summary length does not scale with input size on tool-result-dense spans, so even the minimum-size span still produces over-limit output and the whole segment ends up skipped with zero compression benefit. Field incident (v0.1.175, from the #1774 follow-up): five consecutive halvings produced 29,988 / 27,086 / 26,026 / 29,308 / 22,312-char summaries against the 20,000 cap, then the segment was abandoned after ~16 minutes.

Root causes verified at master:

  1. The summarizeRange system prompt never mentions any length budget (src/preflight.ts).
  2. An over-cap assembled summary is discarded wholesale; the halving retry strategy cannot converge when the model keeps producing long output regardless of input size.
  3. (NOT addressed here — see below) maxSummaryLength is not exposed through CompressSettings, so users cannot tune the cap for an in-flight request.

Changes (src/preflight.ts only)

  1. Explicit length budget in the prompt. The assembled-summary cap is spread across the chunks that form one range summary — floor((maxSummaryLength − (chunks−1)×joinGap) / chunks) with the exact \n\n join gaps subtracted — and each summarizeRange call now gets a LENGTH BUDGET: instruction requiring its entire response to fit that character count. Only appended when a positive cap exists and the budget is ≥ minSummaryLength.
  2. Truncate-to-cap rescue. When an assembled candidate exceeds the cap but is still shorter than the folded content, it is truncated at the last line boundary within budget (hard cut if none has enough lead-in) and suffixed with \n[truncated] before folding — the kernel-acceptable form is preserved (non-empty trim, ≥ minSummaryLength, ≤ maxSummaryLength). Truncation only applies when it still nets savings; a summary ≥ the original content size (model expanded the text) keeps the old discard-and-retry path.

No wire-shape change: the summary stays plain-text acp_summary content in both compression modes; preflight runs proxy-side and is mode-agnostic.

Behavior change (disclosed per policy)

Before After
Assembled summary > maxSummaryLength, < folded content length Discarded whole; span halved and re-summarized until exhausted, then the entire segment skipped with zero output Truncated at a line boundary to the cap, marked [truncated], folded normally (warn logged with char counts)
Summarization prompt No mention of output length limits LENGTH BUDGET: … AT MOST N characters total … per chunk
Summary ≥ folded content length Discard + halving retry Unchanged (still unusable → halving/skip)

Why: the old retry loop can never converge on tool-dense spans (summary length is independent of input size there), turning a compressible segment into ~16 minutes of zero output. Truncation preserves most of the summary's information content under the same hard cap the kernel enforces anyway.

Not changed: compress.maxSummaryLength remains kernel-default-only — exposing it through the three-level CompressSettings merge is a config-surface change deferred for owner decision per Configuration Surface Discipline (issue item 3, 另议). Preflight progress/failure visibility stays tracked under #1762 (issue item 4).

Tests

  • New tests/preflight-summary-length-budget.test.ts (4 tests): per-chunk budget present in every summarization prompt (multi- and single-chunk cases); rescue folds a truncated ≤cap summary for an over-cap-but-shorter-than-content candidate (reproduces the incident shape — old code returned exhausted with zero ranges); no-rescue gate (candidate ≥ content) still exhausts/skips; cap disabled (maxSummaryLength: 0) leaves both prompt and assembly untouched.
  • Updated tests/preflight-covered-ranges.test.ts: the over-limit scenario now asserts the rescue (window fits, folded block carries the truncated [truncated] summary); the missing path is unchanged.

Pre-flight (rebased onto current master 30a23cb)

  • npm run typecheck — clean
  • npm test — 3386 pass / 0 fail / 19 skip
  • npm run build — success
  • E2E: E2E_CHECK=1 zero-token preflight passes locally; full ACP_TEST_E2E run not possible in this environment (no reachable upstream) — CI's e2e job covers pipeline changes.

summarizeRange prompt now carries an explicit per-chunk character budget
(maxSummaryLength spread across chunks minus join gaps); an assembled
summary over the cap but still shorter than the folded content is
truncated at a line boundary to the cap and folded instead of being
discarded whole after halving retries.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #1779 review — pulled 2026-09-30_preflight-summary-length-rescue @ 49836bb (base = current master 30a23cb, fresh — no stale base). Verified code, ran local gates, checked CI.

① 原 issue(方向关) — #1775 的四个根因已在其线程逐条对照 master 核实(floor 2)。本 PR 修第 1、2 项,且修在决策点(组装门,kernel cap 实际执行处),不是症状层打补丁;第 3 项(配置面)按 Configuration Surface Discipline 留待 owner,第 4 项归 #1762 —— 范围切分正确。✅

② 回归审查(触碰路径的既有行为逐项清点):

路径 结论
summarizeRange 系统提示词 cap>0 时追加 LENGTH BUDGET 段(有意变更,已披露);cap≤0 或单 chunk 预算 <50 字符时与旧提示词逐字节一致。无既有可接受输出受损——超限输出旧代码本来也是丢弃
组装接受门(cap<=0 ‖ len<=cap) 语义与旧代码完全一致(仅提取局部变量 maxSummary)
候选 > cap 且 < 折叠原文 旧 = 整体丢弃→减半重试→耗尽后整段 skip 零产出;新 = 行边界截断 + [truncated] 正常折叠。有意变更,已披露(即本 PR 的修复本体)
候选 ≥ 折叠原文 不变(仍丢弃+减半/skip);unusable 消息新增原文字符数(仅日志文案)
错误/abort/fail-fast 路径 未触碰
Wire shape / 两种压缩模式 无变化——纯文本 acp_summary 载体保留;preflight 走 proxy 侧,mode-agnostic

截断数学已验证:cut ≤ room = cap − marker长(12) ⇒ 输出恒 ≤ cap;room < minChars 早退 + 末尾 trim ≥ minChars 守卫保住 kernel 可接受形态;每 chunk 预算求和恒 ≤ cap(k·⌊(M−(k−1)·2)/k⌋+(k−1)·2 ≤ M)。

③ 代码审查 — 干净。新可选参数仅一处调用点;无 as any/@ts-ignore;注释带 #1775 溯源;日志走 deps.log 符合模块惯例;lastIndexOf("\n", room) 的含端点语义处理正确,无换行边界时硬切回退正确。

④ 测试有效性 — 有牙:多/单 chunk 的每个提示词都断言精确预算数字;事故形态复现(旧代码 exhausted 零产出 → 现在折叠 ≤cap 且带 [truncated] 的摘要、前缀保留、warn 日志在案);不救援门槛(≥原文)钉死;cap=0 零影响钉死(提示词与装配均不变)。确定性(listen(0) 随机端口)。既有靠 TASK: The conversation segment below 正则识别摘要调用的测试不受影响(前缀未动)。

⑤ diff 整洁度 — 3 文件,204+/14−,每一行都与目的相关,无锁文件/版本/空行噪音。✅

本地验证 @ 49836bb:typecheck 干净 · 全套 3386 pass / 0 fail / 19 skip(与 PR 声称一致)· build 成功。完整 ACP_TEST_E2E 本环境跑不了(无可达上游,作者已注明)——由 CI e2e lanes 覆盖。

⚠️ 热文件协调:在审 PR #1769(transient 空摘要重试)同样改 src/preflight.ts,且正落在 chunk 循环里同一个 summarizeRange 调用点上(它把该调用包进重试循环)。两者合并顺序任意均可,但后合的一方必须 rebase 并在 transient 重试的每一次尝试中都保留 perChunkBudget 实参。union 很简单,只需排序,别并行合。

CI @ 49836bb(回帖时点):version-guard ✅ · hermetic registry e2e ✅ · codex CODEX_HOME overlay ✅ · opencode/pi/codex 三条零 token e2e lane ✅ · ubuntu/windows 测试矩阵运行中 · dsh lane + build-artifact 排队中。目前无失败。

结论:代码可合并,等测试矩阵转绿。按 §7.4 不属 auto-merge 范畴(超限回退路径的行为变更 + 面向模型的提示词变更 = 产品决策区),人工合并即可。

中文一句话摘要:审核了 preflight 超长摘要修复(提示词加长度预算 + 超限但短于原文时按行截断救援)——方向正确、边界数学验证无误、测试有牙、diff 干净、本地三项门禁全绿;唯一协调点是与 #1769 在同一调用点的文本冲突需排序 rebase,CI 测试矩阵绿后可合并。

@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-30_preflight-summary-length-rescue (49836bb)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1737-pr.1779.8a82e5d

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1779.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 全绿 — 最终结论

@49836bbc 全部 12 项 check 完成,0 失败:

  • ✅ test matrix:ubuntu-latest / windows-latest × Node 22 / 24(四条全绿)
  • ✅ 零 token e2e lanes:opencode native / pi package-native / codex / dsh headless profile
  • ✅ hermetic registry e2e(本地 verdaccio,自更新链)
  • ✅ build-artifact · version-guard · codex CODEX_HOME overlay

加上此前本地验证(typecheck 干净、3386 pass / 0 fail / 19 skip、build 成功)与代码审查结论(方向正确、边界数学无误、测试有牙、diff 干净),本 PR 可以合并。

合并提醒(重申):与在审 PR #1769 在 src/preflight.ts 同一个 summarizeRange 调用点有文本冲突——两者谁后合,谁 rebase 时需在 transient 重试循环的每次尝试中都保留 perChunkBudget 实参。建议先合一个,另一个 rebase 后再合。

中文一句话摘要:PR #1779(preflight 超长摘要长度预算 + 截断救援)CI 12/12 全绿且本地三项门禁通过,审查无回归,可以合并;注意与 #1769 排序 rebase。

@ranxianglei ranxianglei mentioned this pull request Sep 30, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

冲突 这个是修复的什么

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 分两部分说清楚:

这个 PR(#1779)修的是什么

preflight(输入超窗口时的强制压缩兜底)在工具调用密集的长历史里会反复生成超过上限(kernel 默认 20,000 字符)的摘要。旧逻辑:超了 → 整段丢弃 → 把范围减半重新生成。但摘要长度在工具密集区间和输入大小基本无关,减半也不收敛——线上事故(#1775,v0.1.175)就是连续 5 次减半产出 29,988 / 27,086 / 26,026 / 29,308 / 22,312 字符的摘要全部超限,折腾约 16 分钟后整个段落被放弃,零压缩收益。本 PR 两点修复:① 提示词里明确告诉模型「总长不超过 N 字符」;② 组装后仍超限、但比原文短时,不再丢弃,而是按行边界截断到上限并加 [truncated] 标记正常折叠(保住大部分信息)。

我说的"冲突"是什么

不是这个 PR 有缺陷,是合并顺序问题:另一个在审的 PR #1769(修的是另一个独立 bug——上游偶发返回空摘要时不重试直接废掉整轮 preflight)也改了 src/preflight.ts 里同一行区域:chunk 循环中的 summarizeRange(...) 调用点。#1779 给这个调用加了 perChunkBudget 实参;#1769 把同一个调用包进了重试循环。两个改动叠在同一行上,谁后合谁需要 rebase 一下(把实参保留进重试循环的每次尝试即可),否则会产生文本冲突或静默丢掉对方改动。

两个 PR 修的是不同 bug、都需要合,功能上互不矛盾,只是别同时点合并:先合一个,另一个 rebase 后再合就完事。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Superseded by #1818 — folded in (with the rescue candidate now also passing the #1819 net-shrink gate). Tracking issue #1775 merged back into #1812.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

preflight 摘要超长重试循环:summarizeRange 提示词无长度预算,超限摘要整体丢弃而非截断救援

1 participant