feat(prompts): per-summary length-budget guidance in rules and nudges (billion-context#888)

[ranxianglei]

Problem (ranxianglei/billion-context#888)

Dense subagent workloads repeatedly hit:

Compression FAILED: range m00001..m00260: Summary too long (27417 chars, max 20000)

validateCompressionRange rejects the WHOLE compress call atomically when any single summary exceeds maxSummaryLength. Dense ranges tempt the model into one giant monolithic summary, and no prompt surface ever mentioned the per-summary cap or that large/dense ranges should be split — so retries repeated the same failure.

The original stopgap appended a hardcoded note at the host (billion-context) after kernel rendering. Per owner review in #888, the guidance belongs in the kernel: it must ride the prompt governance layer (configurable via compress.prompts.*, overridable per prompt-pack) instead of bypassing it.

Changes

1. src/compression-rules.ts — append a PER-SUMMARY LENGTH BUDGET paragraph to HOW_TO_COMPRESS_RULES: hard cap exists; one oversized summary fails the whole call; large/dense range → split into several smaller ranges at logical boundaries, each with its own concise summary, batched in one call; prefer several tight blocks. No number is hardcoded (stays correct under any cap configuration); byte-stable for the prefix cache. All three system-prompt builders inherit it via prompts.howToCompressRules, so every host using the kernel builders gets it, including preflight-style summarization prompts.
2. src/nudge-text.ts — new tri-state nudge section summaryBudget (string replaces / null removes), defaulting to a ~140-char at-the-moment reminder emitted on all three paths (gentle, emergency, tier). Kept deliberately short so lean surfaces don't need to override it; the full rule lives once in HOW_TO_COMPRESS_RULES.
3. src/packs.ts — summaryBudget added to NUDGE_SECTION_KEYS so packs can replace/disable it; lean pack's condensed contract (LEAN_HOW_TO_COMPRESS) gains a one-line budget rule (~130 chars vs ~700 full).
4. Tests — rule present in the load-bearing default (#888 guard); reminder present on all three nudge paths + override/null behavior; pack sanitize keeps summaryBudget; lean length cap raised 2600→2800 for the added line; golden prompt fixtures re-baselined (diff is exactly the appended paragraph, verified by inspection).

Design notes

• Placement: howToCompressRules rather than compressPhilosophy — this is a HOW-TO rule, not philosophy; both are embedded in nudges anyway, so nudge cost is identical either way.
• Config/pack support comes for free: resolvePrompts({howToCompressRules}, {acknowledgeRisk:true}) already overrides the whole rule text, and pack surface.prompts.howToCompressRules / nudgeSections.summaryBudget now cover both carriers.
• No wire/message-shape change, no state format change, no config schema change (new key is additive and optional).

Verification

• npm run typecheck — clean
• npm test — 807/807 pass
• npm run build — success

Follow-up

After this publishes: billion-context PR ranxianglei/billion-context#889 will drop its local stopgap note and bump the acp-kernel pin to this version.

[github-actions]

📦 Built Package Artifact

Branch: 2026-09-17_888-summary-budget-guidance (116aa4d)

Option A — Install from npm PR tag (recommended)

In your adapter project:

npm install acp-kernel@pr-321

Each push to this PR publishes a new version under the pr-321 npm tag.

Option B — Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf acp-kernel-pr321.tgz
npm install ./package

---

This comment is automatically updated on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到。这是 [PR] 类型 issue,我先拉取对应 PR 分支核对代码、跑本地验证(typecheck/test/build)、确认 CI 状态,然后给出审查结论。稍等片刻。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #321 审查结论:可以合并(按仓库规则合并操作由人类执行)。

核对过程(非重做,仅验证):

1. 基线与整洁度 — 分支 2026-09-17_888-summary-budget-guidance 单 commit 116aa4d,父提交即当前 master 头(a679eca,v0.0.75 release merge),无需 rebase;GitHub mergeable_state: clean。diff 共 9 个文件、全部与本 PR 目的相关:3 个 src(compression-rules.ts +11/-1、nudge-text.ts +17、packs.ts +4/-2)、3 个 golden fixture(各恰好 +2 行)、3 个测试文件。无版本 bump、无锁文件/生成物 churn、无关格重排。
2. 本地验证(node v22.23.2) — npm run typecheck 干净;npm test 807/807 通过;npm run build 成功。与 issue 声称一致。
3. GitHub CI — 全部绿:test (22) ✓、test (24) ✓、pr-validation ✓、build-artifact ✓。
4. 逐行审查要点:
   • PER-SUMMARY LENGTH BUDGET 段落追加在 HOW_TO_COMPRESS_RULES 末尾,原有文本逐字未动;三个 golden fixture 的 diff 经目检确认就是且仅是该段落——版本内字节稳定(prefix cache 不受影响),不硬编码任何数字,任意 cap 配置下都成立。
   • summaryBudgetNote() 的三态语义(undefined→默认 / string→替换 / null→移除)与既有 tierGuidance 等节完全同构;默认 ~136 字符提醒在 gentle/emergency/tier 三条路径各插入一处,位置合理(tier 路径在 Example 行后、emergency 在 ranges 前、gentle 收尾)。
   • NUDGE_SECTION_KEYS 加入 summaryBudget,sanitizePackSurface(packs.ts:124 走 triStateSection)因此自动保留 pack 覆盖;lean pack 的 LEAN_HOW_TO_COMPRESS 补一行(~137 字符),长度上限测试 2600→2800 与实际增量吻合。
   • 新增守卫测试到位:prompts.test.ts 断言规则三处关键标记(#888 guard);nudge-sections.test.ts 覆盖三条路径默认存在 + override/null 行为(含无 \n\n\n 残留断言);packs.test.ts 覆盖 sanitize 保留 summaryBudget。
5. 契约评估(§7.3) — 本 PR 修改的是四条承重 Prompt 规则之一的文案(howToCompressRules),属 human-gated 面;且本身是 feat:(新提示面 + 默认值决策),不符合 auto-merge gate,由人合并即可。无 wire/message-shape 变更、无状态格式变更、config 键为纯增量可选(nudgeSections.summaryBudget)、零依赖与平台无关性未受影响。跨仓顺序正确:kernel 先发,billion-context#889 随后去 stopgap + bump pin。

两个非阻塞观察(均为存量问题,不在本 PR 范围,仅在此线程记录):

• 本地 prettier 3.9.6 下全仓 109 个文件不过 format:check(parent 与 head 对比确认:本 PR 未引入新的格式违规,tests/nudge-sections.test.ts 新增行风格与文件既有的 >80 行长一致)。CI 并不跑 format:check,故不影响合并;若想收口可另开 issue 统一处理。
• AGENTS.md §2 模块图已过时(缺 compression-rules.ts、nudge-text.ts、packs.ts、cache-report.ts 等),master 上即如此,建议后续 docs 更新时补齐。

---

中文摘要: 逐行核对了 PR 代码并本地复跑 typecheck/test(807/807)/build 全绿、GitHub CI 四项全过,改动干净且只动 Prompt 文案层(属人工合并范畴,无 wire/状态/依赖变更),可以合并。

[ranxianglei]

简述改了什么提示词

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 本 PR 新增的提示词共三处(均为纯文案,不硬编码任何数字):

1. HOW_TO_COMPRESS_RULES 末尾追加一段完整规则(src/compression-rules.ts:62,三个 system-prompt builder 都经 prompts.howToCompressRules 继承,含 preflight 式总结提示词):

PER-SUMMARY LENGTH BUDGET: every summary has a hard character cap, and a single oversized summary fails the WHOLE compress call — nothing gets folded. Dense content (many subagent results, long tool outputs) tempts you into writing one giant summary for a big range; don't. When a range is large or dense, SPLIT it into several smaller ranges at logical boundaries and give EACH its own concise, scannable summary, then batch all the ranges in one compress call (content: [{startId, endId, summary}, {...}]). Prefer several tight blocks over one bloated block: each stays under the cap, and smaller blocks are cheaper to re-send and independently searchable/decompressible.

2. Nudge 里的即时提醒(默认 ~136 字符,gentle / emergency / tier 三条 nudge 路径都会带;nudgeSections.summaryBudget 可替换或置 null 移除):

Per-summary length cap: one oversized summary fails the WHOLE call. Large/dense range → split into smaller ranges, batch all in one call.

3. Lean pack 的精简版一行(LEAN_HOW_TO_COMPRESS,~137 字符):

Per-summary length cap: one oversized summary fails the whole call — large/dense range → split into smaller ranges, batch all in one call.

设计意图:完整规则只在 #1 写一次(承重规则层),#2 只是"当下提醒",#3 给紧凑面用;三者都不带具体数字,所以 maxSummaryLength 配成多少都成立。

[ranxianglei]

Owner redirect in ranxianglei/billion-context#888: constraining the model into shorter/split summaries degrades summary quality (opencode-acp lesson). The agreed root-cause fix is instead to expand the summary length limit so it scales with the compressed range size. This PR's approach is superseded — closing without merge. Branch kept for reference.