Skip to content

feat: neverPreserveRecentTools config knob (acp-kernel 0.0.92) - #1332

Merged
ranxianglei merged 8 commits into
masterfrom
2026-09-25_never-preserve-recent-config
Sep 25, 2026
Merged

ranxianglei merged 8 commits into
masterfrom
2026-09-25_never-preserve-recent-config

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Exposes kernel neverPreserveRecentTools (acp-kernel #395, released in 0.0.92 — pin bumped here) as a compress config key: tool-name patterns excluded from the soft-protected recent zone, so matching tool results inside the recent window become compressible immediately instead of aging out first.

Why (#1277 / #1198)

The kernel built-in list ["decompress", "search_context", "read", "bash"] keeps read/bash compressible because they are the largest reclaimable mass — but in batch-read workflows (opencode + deepseek-v4.1-flash in #1198: window correctly detected at 1M, usage 11–18%) the flat-T1 compression cadence folds freshly-read files right away → the model re-reads them → growth triggers another fold → death loop (9 compressions in 26 min; turning compression off unblocks).

Recommended remedy (owner guidance on #1277): remove only read from the list —

{ "compress": { "neverPreserveRecentTools": ["decompress", "search_context", "bash"] } }

— fresh read results then stay in the recent zone and age out by position later (unlike protectedLatestTools, which would pin the newest read forever). Do not clear the list to [] as a habit: re-including decompress/search_context pins just-restored blocks in the recent zone where they become unreclaimable — a different disease. [] remains a valid max-protection escape hatch (deliberately NOT rejected, unlike protectedTools/protectedLatestTools which reject empty arrays).

Changes

  • src/config.ts: compress.neverPreserveRecentTools parsing + validation (separate branch — empty array passes; non-strings / empty strings reject the whole value, same policy class as the other knobs)
  • src/compress-settings.ts: mergeCompress deepest-wins whole-array replace; applyCompressSettings fallback to base
  • Kernel Config passthrough via existing resolveRequestConfig path
  • Docs: CONFIGURATION.md / CONFIGURATION.zh-CN.md new section; README.md / README.zh-CN.md one-paragraph mention
  • chore: pin acp-kernel 0.0.92

Tests

tests/never-preserve-recent-tools.test.ts (7):

  • parse: trim ok, [] valid escape hatch, "read"/[42]/[""]/[null] reject
  • mergeCompress: deepest wins, deeper [] does NOT fall back to shallower list, unset stays undefined
  • resolveRequestConfig: verbatim passthrough ([] included), unset → kernel built-in governs
  • kernel e2e (foldReadTurn): default list → fresh read pair inside the recent window folds immediately (the [bug] 读文件期间高频触发压缩,上下文被反复压回 10 万以下,任务无法完成 #1198 mechanism, proven); read removed → range refuses with /protected/i, read untouched; [] → same refusal

Plumbing tests red-on-master (key absent → undefined); e2e tests require kernel >= 0.0.92. Config-surface regression set (28 files, 553 tests incl. compress-settings/config consumers): 0 failures.

Fixes #1277

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-25_never-preserve-recent-config (ecb7856)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1332

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

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1332.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] 🏷 收到,开始按 review 规范走完整审查:① 原 issue #1277 方向核对 → ② 回归面清点(注意 master 已前进到 #1331 kernel 0.0.91,需确认 rebase 状态与冲突面)→ ③ 代码/④ 测试有效性/⑤ diff 整洁度。另外会先验证 acp-kernel 0.0.92 是否已在 npm 上(跨仓依赖必须先发布)。结论稍后回帖。

ranxianglei and others added 3 commits September 25, 2026 20:55
Config plumbing (parse/validate/merge/resolve) for kernel
neverPreserveRecentTools (#395): tool patterns excluded from the
soft-protected recent zone. Recommended remedy for the #1198/#1277
batch-read fold->re-read death loop: remove only 'read' from the
kernel default list. Empty array is a valid max-protection escape
hatch, unlike protectedTools/protectedLatestTools.

Refs #1277
…n); disambiguate zh README recent-zone clause (#1332 review)
@ranxianglei
ranxianglei force-pushed the 2026-09-25_never-preserve-recent-config branch from 7a7a694 to 9e1a889 Compare September 25, 2026 13:04
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #1332 reviewed — 可合并(feat: 范围,按 §7.4 合并动作留给你)。

① 原 issue 方向(过):#1277 是 owner 拍板的功能 —— 把内核硬编码的 NEVER_PRESERVE_RECENT_TOOLS 暴露为 compress.neverPreserveRecentTools。实现与 owner guidance 完全一致:未设置 → 走内核内置列表(行为逐字节不变);推荐解法(只移除 read)写进文档;[] 作为最大保护逃生门合法且不拒绝(与 protectedTools/protectedLatestTools 拒绝空数组的策略差异在代码注释里有说明)。跨仓时序验证:acp-kernel 0.0.92(kernel #395)已在 npm 上线,pin bump 合规。

② 回归面(清):逐项清点 —— key 未设置时路径与改动前完全一致(applyCompressSettings 的 ?? base fallback → undefined 透传 → 内核内置值主导,无行为漂移);旋钮作用于内核最近区成员判定,两种压缩模式均不受影响;无 config schema / 持久化版本变化;version 字段未动;唯一依赖变更是内联 bundle 的 acp-kernel 精确 pin 0.0.91→0.0.92。热文件提示:src/compress-settings.ts/src/config.ts 同时被其他 open PR(如 #1285 compress-price-profile)触碰,本 PR 改动均为不同区域的增量行;若并行落地按意图并集解决即可。

③ 代码(过):src/config.ts 校验独立于 sibling 循环 —— 非字符串/空白元素整体拒绝,空数组放行(有意为之,注释标明);mergeCompress 最深层整体替换,深层 [] 不会回退到浅层列表(pick 视 [] 为已定义);透传走既有 resolveRequestConfig 路径,无新增管道。

④ 测试有效性(过):tests/never-preserve-recent-tools.test.ts 7 个测试断言有牙。关键是内核 e2e(foldReadTurn,用真实 acp-kernel 导出):默认列表下最近窗口内的 fresh read 对立即被折叠 —— 在内核层面实证了 #1198 死循环机制本身;移除 read 后同范围以 /protected/i 拒绝、read 原样保留;[] 同样拒绝。plumbing 测试在 master 上为红(key 不存在 → undefined),非恒真覆盖。

⑤ diff 整洁度(过):9 个文件全部 on-purpose,无空行/重排噪音,lockfile 仅 pin 行。

门禁证据(rebase 后 head = 当前 master 994ec6c + 本 PR):npm ci OK;typecheck OK(同时证明 0.0.92 的 Config 类型确实携带该 key);全量 2591 tests / 0 fail;build OK + dist-import-annotations OK。GitHub CI 在旧 head 上全绿(e2e、ubuntu/windows 双平台、hermetic registry、real pi/codex lanes)。

已在 PR 分支直接补的小修(标注 commit 9e1a889c,另含 rebase 到当前 master —— 之前落后 3 个 docs-only commit):

  1. src/web/i18n.ts —— Web UI 的 settings.compress_desc(zh/en)列举了所有 compress 键却漏了新键([Feature] Make the recent-zone tool exclusion (NEVER_PRESERVE_RECENT_TOOLS) configurable #1277 计划里承诺了 Web UI i18n 描述),两语言各补一项;
  2. README.zh-CN.md —— 追加句「默认仅 decompress/search_context/read/bash 不受最近区豁免」语义反转(读起来像这 4 个工具受最近区保护),已改写为与英文 README 和代码语义一致的表述。

观察项(不在本 PR 内改):.tmp/(workdir clone 里的 daemon 临时目录)未被 .gitignore 覆盖,git add -A 会误暂存数百个缓存文件(我这次就踩到了,已恢复)——值得单独加一行 ignore。

中文摘要:本 PR 把内核硬编码的 neverPreserveRecentTools 暴露为 compress 配置项(方向与 #1277 owner 决策一致、未设定时行为逐字节不变、带真实内核 e2e 的回归测试),review 中直接修掉 Web UI i18n 漏列新键和中文 README 一处语义反转,rebase 到最新 master 后全套门禁通过——可以合并。

…t-zone exclusion list

The positive-facing counterpart of neverPreserveRecentTools: patterns
REMOVED from the effective exclusion list computed by the kernel.
The #1198/#1277 batch-read fold->re-read remedy becomes one entry,
["read"], without restating — or freezing a copy of — the built-in
list (acp-kernel >= 0.0.93).

Effective exclusion = (neverPreserveRecentTools ?? built-in) minus
preserveRecentTools; composable with an explicit never-list; unset
passes through; [] rejected as a near-certain typo for
neverPreserveRecentTools: [].

Refs #1277
@ranxianglei

Copy link
Copy Markdown
Owner Author

Added the positive-facing companion knob on top of the review fixes (rebased onto 9e1a889):

compress.preserveRecentTools (needs acp-kernel >= 0.0.93 — kernel PR ranxianglei/acp-kernel#428):

{ "compress": { "preserveRecentTools": ["read"] } }  // the one-entry #1198/#1277 remedy

Effective exclusion = (neverPreserveRecentTools ?? built-in) minus preserveRecentTools. This removes the verbatim-replace trap: no need to restate (or freeze a stale copy of) the built-in 4-entry list just to protect read, and the config keeps following built-in evolution. Composable with an explicit neverPreserveRecentTools; glob subtraction; unset = no-op; [] rejected (pure no-op here — a bare [] is almost certainly a typo for neverPreserveRecentTools: []).

Tests: +3 plumbing (parse/merge/resolve) and +4 kernel e2e via the packed #428 tarball — file 13/13, typecheck clean. Docs: README + CONFIGURATION (en/zh) present it as the preferred form, with the never-list repositioned as the advanced verbatim-replace form.

Kernel pin bump to a real 0.0.93 follows after acp-kernel#428 is merged & released (the tarball install is --no-save, package.json/lock still say 0.0.92).

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 新 commit 24c05626(preserveRecentTools)已审。设计本身我认可,但当前分支状态 CI 必红 —— 实证如下。

设计评估(过):正向旋钮消除了 verbatim-replace 陷阱和「手抄内置列表冻结」问题,(never ?? built-in) minus preserve 在 kernel 侧计算、bili 只透传(applyCompressSettings 一行,走既有路径),与 sibling 旋钮的 merge/校验策略一致(最深层整体替换;[] 拒绝的理由也站得住 —— 纯 no-op ≈ typo)。四份文档都到位:README en/zh 把它定位为推荐单条形式、CONFIGURATION en/zh 有完整 section 且互相交叉引用。glob 减法的边界语义(如 "bash*" 减去 bash)由 #428 的 kernel 侧测试钉住,本仓 e2e 覆盖 exact/non-match 两例,合理。

⚠ CI 红点(按 CI 同款环境复现:committed lockfile → npm ci → kernel 0.0.92):

  • typecheck 失败,2 个错误,都在 src/compress-settings.ts:313:TS2561 Object literal may only specify known properties, but 'preserveRecentTools' does not exist in type 'Config' / TS2551 Property 'preserveRecentTools' does not exist on type 'Config'
  • 测试文件 13 个里 2 个红:正是断言内核侧减法行为的两条(["read"] one-line remedy、explicit-never-list 减法);0.0.92 内核忽略未知 key,read 照折。其余 11 条(含全部 plumbing)绿。
  • 根因就是你自己注释里说的时序:acp-kernel fix(#377): re-voice mid-stream acp_summary as user messages (user-carrier) #428 目前仍是 open/unmerged,npm latest = 0.0.92(只有 0.0.92-pr.428.279/.280 预发布)。你的本地验证是拿 packed tarball(--no-save)跑的,CI 的 npm ci 装不到它。

两条路,建议 A:

  • A(推荐):先合 acp-kernel#428(mergeable_state 已是 clean)→ CI 发 0.0.93 → 我在这个分支补一个 chore: pin acp-kernel 0.0.93 commit 并重跑全套门禁 → 绿了再合本 PR。你说「pin bump follows」,我只等 0.0.93 上 npm 的那一声。
  • B(想现在就解锁绿色一半):拆 —— 前三个 commit(cd0adb6b…9e1a889c,neverPreserveRecentTools)本身是完整自洽且全绿的单元,可先合;preserveRecentTools 留作 0.0.93 之后的 follow-up PR。
  • 不建议临时钉 0.0.92-pr.428.x 预发布:未发布分支代码会变/会消失,违背「kernel 先 ship」规则。

顺手小修已推(labeled commit 6f063b02,fast-forward):src/web/i18n.ts 的 Web UI compress_desc(zh/en)上一轮补了 neverPreserveRecentTools,这一轮的新 key 又漏了 —— 两语言各补一项,web-i18n 测试通过。

中文摘要:preserveRecentTools 正向旋钮的设计与文档我都认可并已在 PR 里补上 Web UI i18n 漏项,但该半程依赖尚未发布的 acp-kernel 0.0.93(#428 还开着),当前 committed pin 0.0.92 下 typecheck 2 错 + 2 个内核 e2e 红——建议先合 kernel #428 发 0.0.93 后由我补 pin bump,或拆出绿色的 neverPreserveRecentTools 半程先合。

validateConfig probe: on older kernels the knob is an unknown config
key (no error emitted) so the four plumbing tests still run while the
kernel-behaviour tests skip; once the pin reaches >= 0.0.93 they
activate everywhere. Keeps CI green through the 0.0.92 -> 0.0.93
window (acp-kernel#428).
….0.92

ResolvedKernelConfig = Config & { preserveRecentTools?: string[] } —
applyCompressSettings/resolveRequestConfig return the intersection so
both release windows (pin 0.0.92 now, >= 0.0.93 after acp-kernel#428)
compile identically; older kernels ignore the extra key.
Skip-guarded kernel-e2e tests activate with the real npm package.
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.

[Feature] Make the recent-zone tool exclusion (NEVER_PRESERVE_RECENT_TOOLS) configurable

1 participant