Skip to content

[PR] feat: compress tool dryRun preview mode — validate range & estimate savings before committing - #3193

Open
ranxianglei wants to merge 27 commits into
masterfrom
2026-10-14_compress-dryrun-preview
Open

ranxianglei wants to merge 27 commits into
masterfrom
2026-10-14_compress-dryrun-preview

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 14, 2026 •

Copy link
Copy Markdown
Owner

Revision 2 (de7983d50) — dryRun preview now sits behind a default-OFF switch. Per the owner request in #3185 ("需要一个开关,默认关闭"), the always-on preview from revision 1 is now opt-in. With the switch off (the default) the served compress schema and compression prompt are byte-identical to pre-feature master, and a stray dryRun: true argument is ignored — zero impact on existing deployments. The "Behavior changes (disclosed)" section further down describes revision 1 (always-on); the delta introduced by this revision is captured here.

Config surface (owner-gated)

One new config field added in this revision:

Field Type Default Env override Scope
compress.dryRunPreview boolean false BILI_COMPRESS_DRYRUN (1 / true) global level only
  • Why no existing surface can express it: there is no existing knob that toggles a single tool-surface capability (whether the compress tool advertises one optional parameter). compress.injectTool / injectNudge toggle tool/nudge injection wholesale; neither expresses "expose this one optional preview parameter". A dedicated boolean is the minimal addition.
  • Resolution order: env > file > default, via knobs.dryRunPreviewEnabled() (consistent with the 彻底整治环境变了滥用,除非必要都走配置文件 #2030 knob convention).
  • Migration / compatibility: none. Default false is back-compatible; enabling is purely additive. Documented en+zh in CONFIGURATION.md (seed-driven param-ref/env-map tables + prose) and the website seed/site.

Behavior change (this revision: old -> new)

  • Old (revision 1, head 8a775aa): dryRun preview was always on — every served compress schema carried the dryRun field and the function prompt always included the preview strategy sentence; routing honored dryRun: true.
  • New (default): dryRun is off. The kernel base schema/prompt are reverted to pre-feature bytes; separate _DRYRUN variants are served, and the prompt sentence is appended, ONLY when the switch is on. Routing auto-gates because parsed.dryRun is forced false when off (no routing-line edits needed). Both the default and lean packs share the same serving gate (lean drops the tools prompt section entirely, so only the schema field applies there).
  • Proof of zero-impact: wire-contract goldens regenerated with the switch off match master byte-for-byte (git diff against master over the golden + fixture files is empty).

kernel-change: the dry-run judgments (protected carve, turn-integrity withdrawals, min-range gate, refold decisions, savings estimate) ARE the kernel's own pre-commit computations — previewing them requires running that stage without committing, which no host-side entry exposes. Re-implementing those stages in the host would be a drifting copy of kernel logic (the #2821/#498 failure family). This change extracts the existing pre-commit stages verbatim (prepareBatch / planSingleRange / commitFoldedRange) behind them and adds a non-mutating previewCompression core entry; the non-dryRun path stays byte-identical, pinned by the full kernel suite plus the bili suite/e2e.

Closes #3185

What

The compress tool accepts an optional top-level dryRun boolean. When true (and summary omitted) the call returns a structured receipt INSTEAD of committing a block:

  • validity — the exact error text a real call would produce (fully-protected zone / turn-split / unknown refs / min-range batch gate);
  • would fold — refs (capped per category in the rendered receipt);
  • excluded by reason — protected tools / recent zone / checkpoint carriers / unrecoverable media;
  • withdrawn for turn integrity — refs + turn/pair counts;
  • absorbed blocks — refold vs already-covered;
  • estimated tokens saved + post-fold window occupancy (local estimates).

Zero side effects: no blocks, no ref allocation (id-never-reused contract), no ledger write, no dirty mark, no failure/loop tracking — pinned by state deep-equal + idempotency tests at both layers. A re-issued call without dryRun (with its summary) commits exactly what the preview reported.

Layers

  • Kernel (e5c15cb, version 0.0.122 → 0.0.123): new CompressionCore.previewCompression; applyCompression refactored around the extracted stages verbatim; the lenient parser threads the flag through every input shape (object / stringified / truncated-salvage / line-form) and relaxes the missing-summary rule under dryRun only; rebuild skips recorded dry-run calls so a preview never fabricates blocks on replay; TOOLS prompt gains one guidance line.
  • Host: applyRanges routes dryRun before any failure-tracking side effect; the external-summarizer lane short-circuits on RAW input (no placeholder summaries); the receipt renders local token estimates. Both compression modes are covered — proxy clients through applyRanges, plugin hosts registering the tool from the kernel constants and executing through the same path.

Tests

  • New kernel/tests/preview-compress.test.ts: recent-zone exclusion, fully-protected exact-error parity vs a real call, turn-integrity partial withdrawal, split-turn exact-error parity, protected-tool categorization, min-range batchError, unknown refs, already-covered, purity (caller state byte-identical), idempotency, exact savings estimate. Kernel suite 1298/1298 green.
  • Parser tests: flag detection in all input shapes; real path unchanged (missing summary still rejected without the flag).
  • New tests/compress-dryrun-preview.test.ts: object + stringified-JSON wire shapes, line-form, fully-protected preview, idempotency, and real-compress-after-preview ≡ control context.
  • The e2e codex suite runs on CI (gated) to prove the non-dryRun path regression-free end-to-end.

Config surface

None added — pure tool capability, no knob (per the issue's non-goals).

Behavior changes (disclosed)

Golden regeneration justification

tests/golden/wire-contract/{kernel,bili,manifest-default,manifest-optin}.json + kernel/tests/fixtures/prompt-function-default.txt: the schema surface intentionally widened (dryRun property, description wording, Google required relaxation). Diff inspected line-by-line: nothing beyond intent changed.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-14_compress-dryrun-preview (bbd18cc)

Latest build — install this exact version

npm install -g billion-context@0.0.5646-pr.3193.d509210

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

Recent builds (commit → version)

commit version build
bbd18cc billion-context@0.0.5646-pr.3193.d509210 build
d18ffb6 billion-context@0.0.5588-pr.3193.99730fa build
00e7dd1 billion-context@0.0.5406-pr.3193.af14043 build
fcd2aa0 billion-context@0.0.5404-pr.3193.6380bf9 build

Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei
ranxianglei force-pushed the 2026-10-14_compress-dryrun-preview branch from 673423a to 545a101 Compare October 14, 2026 15:49
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

收到上游冲突通知,已完成 rebase 并推送。PR 冲突状态已解除(API 确认 mergeable: true),CI 已在新 head(545a1013d)上运行:theorem/e2e/real-codex/real-image-billing 等 lane 已绿,其余在跑。

八问:

  1. 是什么问题:本 PR(compress 工具 dryRun 预览模式)基于旧 master 开出,master 此后前进 166 个提交,PR 分支与目标分支产生合并冲突。
  2. 什么原因导致的:两边在同一位置各自新增了代码——master 侧 [bug] 大会话 compress 持续失败:ctx has 0 message(s) 时所有 ref 被判悬空(cannot-anchor),报错归因误导 #3126(空上下文拒绝)与本 PR 的 dryRun 预览 lane 都在 src/stream.ts 同一锚点行后插入新函数;另外两侧都把 kernel 版本提到了 0.0.123([Bug] MCP compress 历史调用未被清理,长会话累积大量旧摘要与回执 #2970 vs 本 PR),形成版本碰撞。
  3. 影响范围与严重程度:只影响本 PR 分支本身,不影响任何已发布行为;解决前 PR 无法合并(merge state dirty)。
  4. 怎么修复的:rebase 到最新 master(2f22bc60c)。唯一文本冲突(stream.ts)取并集——master 的 [bug] 大会话 compress 持续失败:ctx has 0 message(s) 时所有 ref 被判悬空(cannot-anchor),报错归因误导 #3126 拒绝函数与本 PR 的预览 lane 都保留;external-summary-compress.ts 自动合并干净。版本碰撞处把 kernel 版本定为 0.0.124——这是纯解冲突之外唯一一处有意变更(kernel-guard CI 要求 kernel/src 有改动必须带版本行)。
  5. 是否有回归问题:逐一审过 diff 触碰路径的既有行为——[bug] 大会话 compress 持续失败:ctx has 0 message(s) 时所有 ref 被判悬空(cannot-anchor),报错归因误导 #3126 空视图拒绝路径保持完整(dryRun 路由在其之前,是本 PR 的设计意图:「预览不算尝试」,避免失败追踪副作用);Master red on test matrix: #1387 stop-signal tests fail after the preserveRecentMessages 5→3 flip (#3058) #3075 尾部重算路径不受影响;wire-contract golden 门禁通过。本地定向测试全绿:kernel preview/parse 104/104、host dryrun+[bug] 大会话 compress 持续失败:ctx has 0 message(s) 时所有 ref 被判悬空(cannot-anchor),报错归因误导 #3126+wire-contract 32/32、tail/receipt 13/13、external-summary 20/20;全量套件以远程 CI 为准。
  6. 是否破坏缓存:不涉及——rebase 未触碰任何缓存/去重/游标逻辑。
  7. 是否改了设计方向:没有。最终 diff 文件清单与原 PR 一致(17 文件),语义 = 原 PR + master 新功能共存。
  8. 是否引入了新的配置:无新配置项。

判定:冲突解决完毕,待 CI 全绿后由人工合并。

@ranxianglei
ranxianglei force-pushed the 2026-10-14_compress-dryrun-preview branch from 545a101 to 8a48c9e Compare October 14, 2026 15:59
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重:不重复。检索 open+closed PR(dryRun/preview 关键词)无其他实现;本 PR 是 #3185(owner 已拍板的设计 A)的唯一实现。以下为独立审核结论(未照抄开发会话的表述,diff 逐段重读、行为逐项清点)。

结构化八问

1. 是什么问题:#3185 功能需求——模型在真正提交压缩前无法知道「这个 range 能不能压、会被剔掉什么、能省多少 token」,只能试错。本 PR 给 compress 工具加 dryRun 预览模式:只验证和估算,不落地任何状态。

2. 什么原因导致的(为什么需要这个功能):内核压缩管线只有「提交后」才暴露校验/剔除信息,失败尝试还会留下副作用(dead-ref 记录、失败计数)。根因级解法是把既有的 pre-commit 规划阶段暴露为只读入口,而不是在宿主侧复制一套校验逻辑——本 PR 正是这么做的(见第 4 问),不是打补丁式地在错误层拦截。

3. 影响范围与严重程度:纯增量能力。现有用户零影响,直到模型开始使用新参数(提示词加了一句引导)。预览路径结构性零副作用(所有变更发生在一次性 clone 上,ref/block 分配只作用于 clone,clone 随后丢弃)——若做坏了后果会严重(假预览误导模型决策),但 parity 是靠代码复用保证的,不是靠两份代码各自正确。

4. 怎么修复的(机制层面):

  • 内核:applyCompression 拆成 prepareBatch(分类/门控,逐字提取)+ 每 range 的 planSingleRange/commitFoldedRange;新增 previewCompression 跑同一套 plan+commit 在丢弃型 clone 上并出报告。真实路径与预览路径共用同一决策代码,parity 是结构性的。
  • 解析器:dryRun===true 时允许缺 summary(占位空串);截断输入(salvage 模式)用正则探测 flag。
  • 宿主:applyRanges 在失败跟踪之前路由 dryRun(「预览不是尝试」,不武装熔断器);外部 summarizer 通道在 raw 输入处短路;rebuild 回放跳过已记录的预览调用(否则会凭空造 block);回执用本地 token 估算给出压缩后窗口占用。
  • 两种压缩模式都覆盖:proxy 走 applyRanges;plugin 宿主从同一组内核常量注册工具面、执行同一 API。

5. 是否有回归问题——既有行为逐项清点(改动前代码读过的,不是只读 diff):

  • 非 dryRun 路径字节级不变:重构逐块核对过——minCompressRange 门控 reject 的两种返回形态(message=null 返回原始未修改的 input.state,非 null 返回带 dead-ref tombstone 的 clone)、overlap 警告先于 per-range 警告的顺序、consumed-range 警告文案(抽到共享 helper,两边同串)、refold 流程、compress failure is self-amplifying: failed calls are hidden as orphan refs, making the same range permanently un-compressible #2362 dead-ref 墓碑,全部保持。
  • rebuild 回放:只跳过携带 dryRun flag 的调用(新调用类别);存量记录不受影响。已知边缘:截断的非 dryRun 输入若 summary 正文里恰好含字面量 "dryRun": true,salvage 模式会把整批当预览处理——代码注释已写明取舍,低概率×降级态,后果非破坏性(拿到回执而非误提交)。
  • 与 master [bug] 大会话 compress 持续失败:ctx has 0 message(s) 时所有 ref 被判悬空(cannot-anchor),报错归因误导 #3126(no-visible-context 拒绝)的交互:dryRun 路由在它之前——视图为空窗口内的预览会诚实报每 range "would fail",而不是拒绝消息。零副作用两边都保住了(拒绝路径会记失败,预览不能记)。仅降级态小窗口,可接受。
  • golden 账本只增不减:4 个 golden 文件逐行核对,只有预期三类变化(新增 dryRun 属性、summary 描述措辞、google required 放宽),零意外漂移。
  • 本地定向测试:旧 head 与新 head 均绿(内核 preview+parse 104 例;宿主 dryrun+wire-contract 26 例);typecheck 干净、build 通过。全量套件以新 head 的 CI test lane 为准(本次推送后首次真正运行,见下)。

6. 是否破坏缓存:否。预览不分配、不写账本、不动任何前缀缓存相关字节;非 dryRun 线路上字节不变;回执是临时 tool result,与其他 compress 回执同性质。

7. 是否改了设计方向:无转向。内核增加的是对既有管线的只读入口(无新管线节点、节点顺序不变)。唯一的提示词面变化:默认 function prompt 的 TOOLS 条目 compress 项追加一句 dryRun 用法引导(所有用默认 prompt 的会话可见——披露如下)。

8. 是否引入新配置:无。无 config key、无 env var、无 CLI flag(符合 #3185 设计的「零配置面」要求)。

行为变更披露(旧值→新值)

变更 旧 新 原因
compress 工具 schema 无该参数 新增可选顶层 dryRun boolean(缺省/false = 完全旧行为) 功能本体
google schema items.required ["startId","endId","summary"] ["startId","endId"] 仅 schema 层放宽;解析器对真实调用仍强制 summary——有效行为不变
默认 function prompt TOOLS 条目 无 dryRun 句 追加一句预览引导 让模型知道何时该先预览
rebuild 回放 (无此调用类别) 跳过已记录的 dry-run 调用 防止回放凭空造 block

我在分支上加的提交(审核中发现的问题,按「小问题直接修」直接修掉)

  1. CI 红的根因:kernel-guard 失败——分支切出时内核版本还是 0.0.122,PR 提到 0.0.123,但 master 已经经由 fix: route MCP compress through consumed-call cleanup (#2970) #2977 同步占到 0.0.123,于是 kernel/package.json 相对 master 无差异 → guard 规则触发。连带后果:test lane 依赖 kernel-guard,被跳过,全量套件从未在这个 head 上跑过。
  2. 并发 rebase 说明(透明起见):我审核期间分支已被另一次会话 rebase 过一次(旧 tip 545a1013d,同样基于当前 master、同样把内核 bump 到 0.0.124)。我的 rebase 在同一基线上取代了它——两者树差异仅 2 行:① 那次 rebase 漏同步 package-lock.json(lock 里 acp-kernel 还停在 0.0.123,lock-sync lane 会红),我补上了;② 下面的回执渲染修复。旧 tip 可按 sha 找回,无独有工作丢失。
  3. 我的提交(4 个中的后 2 个 + rebase 解决):
  4. 新 head 验证:typecheck 干净、npm run build 通过、定向测试绿(内核 104 / 宿主 26,含 wire-contract)。

遗留观察(不阻塞合并)

  • 以下报告分支暂无测试钉住:wouldRefold、consumedBlocks(吸收)、skippedOverlap、excluded.checkpointCarriers/media。核心契约(错误精确 parity、纯度 deep-equal、幂等、real-after-preview ≡ control)钉得很扎实,这几处只是报告字段,风险低;后续可补。
  • salvage 正则的边缘情形(上文第 5 问)——已在代码注释中声明取舍,接受。

判定

方向正确、内核边界合规(declaration/approval/kernel: 前缀/版本纪律/双层测试/golden 理由齐全)、测试有牙、重构保持字节级 parity。当前 head(8a48c9e45)CI 重跑中:kernel-guard 应转绿、test lane 首次完整运行——这两类 lane 全绿后即可合并(合并留给人;内核变更始终是人审级)。若 CI 有红我会跟进定向排查。

@ranxianglei
ranxianglei force-pushed the 2026-10-14_compress-dryrun-preview branch from 8a48c9e to ad6b337 Compare October 14, 2026 16:34
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

跟进:上一轮推送后 kernel-guard 又红了,根因已定位并修掉,分支已更新到 ad6b33740。

发生了什么:我 rebase 期间 master 又前进了——#3157(persist fsync)经 #3163 合入时把内核版本从 0.0.123 提到了 0.0.124(commit 8083f9caf,"master consumed 0.0.123 via #2970"),正好和我选中的版本号撞上。这个 guard 在 CI 里是对「PR head 合入当前 master 的 merge ref」做三点 diff:master 已占 0.0.124、我的分支也是 0.0.124 → 版本行无差异 → 触发「kernel/ source changed without bumping」。本地按旧语义复现是绿的,所以第一次没看出来——这次是按 CI 实际的 merge-ref 语义复现确认的。

处置(与上一轮同一模式,仓库先例 4fa650d80/8083f9caf):

  1. rebase 到当前 master(b2868ca68)——干净无冲突,git 自动跳过了我那个已被 master 同款变更取代的 bump commit;
  2. 内核版本提到 0.0.125(kernel/package.json + package-lock.json 同步,共 2 行),独立标注 commit ad6b33740;
  3. 重新验证:typecheck 干净、build 成功、定向测试绿(内核 preview+parse 104 例 / 宿主 dryrun+wire-contract 26 例)。

功能代码本身零改动。CI 会在新 head 上重跑——这次 kernel-guard 应转绿,test lane 将首次完整运行。有红我继续跟。

@kuviki

kuviki commented Oct 15, 2026

Copy link
Copy Markdown
Contributor

CI 卡住了?而且有12个失败了

ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
)

The first draft of the dryRun parameter carried a ~440-char description
that landed in every outbound request body of injectTool sessions
(+~820B ≈ +205 tokens per turn, permanent). That constant overhead
broke byte-pinned goldens and shifted knife-edge preflight fit
boundaries (fold timing moved ±1 turn under the flat nudge cadence).

Shortened the main + google dryRun descriptions and the TOOLS prompt
sentence to carry the same contract in less text: preview reports
validity/exclusions/withdrawals/savings, zero side effects, re-issue
with summary to commit. No behavior change — schema shape, param
name, and the 'REQUIRED unless dryRun=true' suffixes are untouched.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…n tool surface (#3193)

Intentional tool-surface growth (new dryRun boolean param on the
compress tool) changes every pinned outbound body, so both golden
sets were regenerated via scripts/update-wire-contract-goldens.ts
and scripts/update-storage-render-goldens.ts. The storage-render
regeneration was missing from the original PR head — that alone
accounted for 8 of the 14 failing tests across all 12 CI shards.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…erhead floor (#3193)

Four behavioral fixtures sat within ~205 tokens of their window limit;
the new permanent per-request tool-schema bytes pushed two of them
across the fold boundary (master decision 9984 < 10000 → tail survives;
PR head 10189 ≥ 10000 → recent-zone tail folded) and shifted fold
settlement ±1 turn under the flat 50K/500-token nudge cadence.

- #280/#568/#663-anthropic: trim filler repeat(250)→repeat(225)
  (~13k → ~12k tokens vs the 10k window) so post-fold estimates keep
  comfortable headroom below the limit while still exceeding it
  pre-fold; test intent unchanged.
- cache-proof host-compaction: the strict element-count shrink assert
  could not see a fold landing in the same body as the client's own
  user+assistant append (bytes shrank 99KB→55KB, count flat). The
  settling-fold check now compares coreLen net of CLIENT_TURN_APPENDS=2
  appends — a no-op zombie fold (count grows by exactly the appends)
  still fails.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…Run wording (#3193)

The function-mode compress system prompt is byte-pinned against a
checked-in fixture (surface-config byte-stability gate). The wording
tightening in the previous commit changed the TOOLS section, so the
fixture was regenerated from buildCompressSystemPrompt(). Only that one
line moved; the text/hybrid builders do not carry the dryRun text.
@ranxianglei
ranxianglei force-pushed the 2026-10-14_compress-dryrun-preview branch from 7281d27 to 2d8f13c Compare October 15, 2026 01:59
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
)

The first draft of the dryRun parameter carried a ~440-char description
that landed in every outbound request body of injectTool sessions
(+~820B ≈ +205 tokens per turn, permanent). That constant overhead
broke byte-pinned goldens and shifted knife-edge preflight fit
boundaries (fold timing moved ±1 turn under the flat nudge cadence).

Shortened the main + google dryRun descriptions and the TOOLS prompt
sentence to carry the same contract in less text: preview reports
validity/exclusions/withdrawals/savings, zero side effects, re-issue
with summary to commit. No behavior change — schema shape, param
name, and the 'REQUIRED unless dryRun=true' suffixes are untouched.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…n tool surface (#3193)

Intentional tool-surface growth (new dryRun boolean param on the
compress tool) changes every pinned outbound body, so both golden
sets were regenerated via scripts/update-wire-contract-goldens.ts
and scripts/update-storage-render-goldens.ts. The storage-render
regeneration was missing from the original PR head — that alone
accounted for 8 of the 14 failing tests across all 12 CI shards.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…erhead floor (#3193)

Four behavioral fixtures sat within ~205 tokens of their window limit;
the new permanent per-request tool-schema bytes pushed two of them
across the fold boundary (master decision 9984 < 10000 → tail survives;
PR head 10189 ≥ 10000 → recent-zone tail folded) and shifted fold
settlement ±1 turn under the flat 50K/500-token nudge cadence.

- #280/#568/#663-anthropic: trim filler repeat(250)→repeat(225)
  (~13k → ~12k tokens vs the 10k window) so post-fold estimates keep
  comfortable headroom below the limit while still exceeding it
  pre-fold; test intent unchanged.
- cache-proof host-compaction: the strict element-count shrink assert
  could not see a fold landing in the same body as the client's own
  user+assistant append (bytes shrank 99KB→55KB, count flat). The
  settling-fold check now compares coreLen net of CLIENT_TURN_APPENDS=2
  appends — a no-op zombie fold (count grows by exactly the appends)
  still fails.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…Run wording (#3193)

The function-mode compress system prompt is byte-pinned against a
checked-in fixture (surface-config byte-stability gate). The wording
tightening in the previous commit changed the TOOLS section, so the
fixture was regenerated from buildCompressSystemPrompt(). Only that one
line moved; the text/hybrid builders do not carry the dryRun text.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…3159 + #3193)

Rebase conflict resolution: master's #3159 re-layout (Vertex part
order) and this PR's dryRun schema growth both touch the pinned google
wire bodies. Regenerated from source so the golden carries the union —
every turn body grows a constant +565B (the dryRun tool-schema bytes),
no layout drift.
@ranxianglei
ranxianglei force-pushed the 2026-10-14_compress-dryrun-preview branch from 2d8f13c to a695201 Compare October 15, 2026 02:11
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
)

The first draft of the dryRun parameter carried a ~440-char description
that landed in every outbound request body of injectTool sessions
(+~820B ≈ +205 tokens per turn, permanent). That constant overhead
broke byte-pinned goldens and shifted knife-edge preflight fit
boundaries (fold timing moved ±1 turn under the flat nudge cadence).

Shortened the main + google dryRun descriptions and the TOOLS prompt
sentence to carry the same contract in less text: preview reports
validity/exclusions/withdrawals/savings, zero side effects, re-issue
with summary to commit. No behavior change — schema shape, param
name, and the 'REQUIRED unless dryRun=true' suffixes are untouched.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…n tool surface (#3193)

Intentional tool-surface growth (new dryRun boolean param on the
compress tool) changes every pinned outbound body, so both golden
sets were regenerated via scripts/update-wire-contract-goldens.ts
and scripts/update-storage-render-goldens.ts. The storage-render
regeneration was missing from the original PR head — that alone
accounted for 8 of the 14 failing tests across all 12 CI shards.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…erhead floor (#3193)

Four behavioral fixtures sat within ~205 tokens of their window limit;
the new permanent per-request tool-schema bytes pushed two of them
across the fold boundary (master decision 9984 < 10000 → tail survives;
PR head 10189 ≥ 10000 → recent-zone tail folded) and shifted fold
settlement ±1 turn under the flat 50K/500-token nudge cadence.

- #280/#568/#663-anthropic: trim filler repeat(250)→repeat(225)
  (~13k → ~12k tokens vs the 10k window) so post-fold estimates keep
  comfortable headroom below the limit while still exceeding it
  pre-fold; test intent unchanged.
- cache-proof host-compaction: the strict element-count shrink assert
  could not see a fold landing in the same body as the client's own
  user+assistant append (bytes shrank 99KB→55KB, count flat). The
  settling-fold check now compares coreLen net of CLIENT_TURN_APPENDS=2
  appends — a no-op zombie fold (count grows by exactly the appends)
  still fails.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…Run wording (#3193)

The function-mode compress system prompt is byte-pinned against a
checked-in fixture (surface-config byte-stability gate). The wording
tightening in the previous commit changed the TOOLS section, so the
fixture was regenerated from buildCompressSystemPrompt(). Only that one
line moved; the text/hybrid builders do not carry the dryRun text.
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
…3159 + #3193)

Rebase conflict resolution: master's #3159 re-layout (Vertex part
order) and this PR's dryRun schema growth both touch the pinned google
wire bodies. Regenerated from source so the golden carries the union —
every turn body grows a constant +565B (the dryRun tool-schema bytes),
no layout drift.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

先直接回答:CI 没有卡住——42 个 check 全部跑完了,「12 个失败」= test 矩阵的全部 12 条 lane(ubuntu/windows × node22/24 × 3 shards),去重后是 14 个失败测试,且只有一个根因。已修完并 rebase 到最新 master(head a69520189,与 master 无冲突),等新一轮 CI 出最终结论。

结构化八问

1. 是什么问题
dryRun 功能给注入的 compress 工具 schema 加了新参数 → 每个请求体永久变大约 +630830 字节(≈+150200 tokens)。这同时打爆了三种东西:① byte-pinned 的 storage-render goldens(原 PR 只重新生成了 wire-contract,漏了 storage-render);② 刀口级 fit 边界——实测 fold 判定 master 侧 9984 < 10000 停手、PR 侧 10189 ≥ 10000 继续折,preflight 多折了一轮 recent tail;③ 第三个 pin(kernel prompt fixture,static-gates 抓到的)。另有 4 个 port 测试失败是共享 runner 端口碰撞(18787 claude-native 固定端口)——master 自己的 CI(run 38606057099 @ 8d73192,同一天)同样挂这几个测试,属环境问题非本 PR 引入;master 随后已合入 #3182 zone-port bands 治这一类。

2. 什么原因导致的
功能本身的设计代价:注入工具 schema 的字节数是每请求常付的线开销。原 PR 在 40k 窗口的大 fixture 上没暴露问题(余量大),但 golden 字节比对和 10k 窗口小会话的 fit 计算对这点增长零容忍。fold 时序在 flat-500-token nudge cadence 下对 +~150 tok/req 敏感 ±1 turn。

3. 影响范围与严重程度
未发布功能,无终端用户影响;内部影响 = test 矩阵全红、阻塞合并。若按原样合入的长期代价:每个 injectTool 会话每请求多付 ~150-200 tokens(永久计费开销),小窗口会话 preflight 略激进。已通过收紧措辞把开销从 ~205 压到 ~140-180 tokens/req。

4. 怎么修复的
5 个附加 commit(不替换原作者提交):① 收紧 dryRun schema 措辞(语义不变,砍冗余枚举)+ kernel bump 0.0.126;② 重新生成两套 goldens(wire-contract ×4 + storage-render ×4)+ kernel prompt fixture;③ 校准 3 个刀口 fixture(repeat 250→225,13k→12k vs 10k 窗口,测试意图不变:pre-fold 仍远超窗口保证触发);④ cache-proof 的 shrink 断言改为 append-aware(coreLen(RB,R) < coreLen(PB,P) + CLIENT_TURN_APPENDS)——机制已实证:fold 与客户自身 append 落在同一 body 里时元素计数持平但字节从 99173→54757 大幅缩小,bili 行为正确,原断言的元素计数代理在该场景失明;zombie no-op fold 仍会被抓(teeth 保留);⑤ lockfile 同步。冲突处理:两轮 rebase 均按 union 语义解(唯一真实文件重叠 google.json = #3159 Vertex 布局 + dryRun schema,逐 turn 恒定 +565B 验证过,无漂移)。

5. 是否有回归问题
未发现。本地定向 185/185 绿(storage-render/wire-contract/preflight 全家/cache-proof/kernel preview+parse/surface-config,外加 master 新合入的 dead-ref stream 测试 3 个文件——验证合并后的 stream.ts 两侧改动共存无碍);typecheck 干净。最终 verdict = 远程 CI(§7.2)。高危模式逐项:无阈值/默认值漂移(nudge flat-50K 未动)、无 fail-fast→吞错、无输出格式变化(receipt 文案仅修掉一处 literal 'true',上一轮已披露)、无缓存策略变化。

6. 是否破坏缓存
不涉及——prefix cache 锚点(head system message)字节不变;工具 schema 增长在 messages 之后的 tools 段,不影响已建立的前缀缓存命中逻辑本身。

7. 是否改了设计方向
否。dryRun 保持零副作用(kernel 内部 clone state,preview 不写任何持久化);preview lane 仍按设计在 failure/loop tracking 之前路由("预览不是尝试")。

8. 是否引入了新的配置
无新 env/config。行为变更披露:① 永久线开销地板 old(0,无 dryRun) → new(~+140-180 tokens/request,injectTool 会话,wire 相关)——这是功能固有部分成本,已用措辞收紧缓解,无法归零除非砍参数描述;② acp-kernel 0.0.124(master) → 0.0.126;③ cache-proof 断言语义 strict-shrink → net-of-appends(仅测试代码,teeth 保留,原因见第 4 问④)。

收工判定:冲突已解(分支 = 最新 master 0cd865b19 + 10 commits,本轮 rebase 零冲突),修复 commit 已在分支上,等 head a69520189 的 CI 全绿即可由人工合并。

@kuviki

kuviki commented Oct 15, 2026

Copy link
Copy Markdown
Contributor

补充检查了 PR #3193 当前实现,整体设计没有问题,但发现几个值得在合并前确认的细节,以及一项工具提示词优化建议。

1. Google/Gemini Schema 的 dryRun 字段层级疑似错误

在 kernel/src/compress-tools.ts 的 COMPRESS_TOOL_GOOGLE 中,dryRun 被定义在 parameters 下,而不是 parameters.properties 内:

parameters: {
  type: "object",
  properties: {
    content: { /* ... */ }
  },
  dryRun: { type: "boolean" }, // 这里
  required: ["content"]
}

这不符合正常的 Schema 属性声明结构。严格校验的客户端可能拒绝该 Schema,宽松客户端也可能忽略 dryRun 参数。

建议将其移入 parameters.properties,并增加针对字段层级的断言,避免仅靠 golden 字节对比遗漏结构问题。

2. 非 Google Schema 的批量 dryRun 仍强制要求 summary

COMPRESS_PARAMETERS 的 content 数组对象分支目前仍有:

required: ["startId", "endId", "summary"]
required: ["startRef", "endRef", "summary"]

虽然解析器已经允许 dryRun: true 时不传 summary,但严格按照 Schema 校验的客户端可能拒绝无摘要的批量预览。

例如:

{
  "dryRun": true,
  "content": [
    {"startId": "m00100", "endId": "m00200"},
    {"startId": "m00300", "endId": "m00400"}
  ]
}

建议放宽这两个数组对象分支的 required,与 Google Schema 的处理方式保持一致。

真实压缩时仍由解析器强制检查 summary,避免改变原有提交行为。也不需要引入顶层 anyOf 等可能触发 #1299 兼容性问题的结构。

3. 无有效范围的 dryRun 仍可能触发失败追踪

在 src/stream.ts 的 applyRanges 中,当前执行顺序是:

  1. ranges.length === 0 时进入失败处理。
  2. 调用 recordCompressFailure 和 noteCompressLoopFailure。
  3. 之后才检查 parsed.dryRun,进入预览分支。

因此,当 dryRun: true 的参数格式有误、最终没有解析出有效范围时,仍可能增加压缩失败计数或影响循环保护状态。

这与「dryRun 是只读预览,不计入压缩失败追踪」的设计目标不完全一致。

建议在零有效范围的处理路径中也识别 dryRun,返回明确的参数错误,但不更新压缩失败计数和循环熔断状态。

4. 进一步精简提示词,同时补充模型决策策略

看到最新提交已经针对工具 Schema 的固定 Token 开销做过精简,这个方向值得保留。

目前报告的增量仍约为 140–180 Tokens/请求。对于以节省上下文为目标的工具,建议尽量避免在 Schema 和系统提示词中重复解释相同内容。

可以考虑:

  • Schema 参数描述:只保留 dryRun 的功能、输入要求和返回信息,避免重复详细介绍操作流程。
  • 系统提示词:用一条简短规则引导模型如何规划、评估与提交压缩。

例如:

For model-selected ranges, preview the entire batch with dryRun first (no summaries). Evaluate estimatedTokensSaved and exclusions; adjust or discard poor ranges. Then generate one summary per selected range and commit the batch in one call. Skip preview only when an equivalent, still-valid precheck is available.

这里希望强调:

  1. 默认先预检,不要仅凭模型主观认为范围明确、收益明显就跳过。原样使用最新 acp_status 推荐范围,可以在确认其预检保证足够时作为例外。
  2. 根据 estimatedTokensSaved 主动判断是否值得压缩,而不是只检查范围是否合法。
  3. 先完整规划、再批量提交,尽可能减少跨轮压缩带来的重复缓存成本(关联 [design] Parallel compression saves cache; both failure and success strategies account for PARTIAL fold double-seam cost | [design] 并行压缩节省缓存,失败和成功策略都考虑 PARTIAL fold double-seam cost — per-range commit makes rejected-range retry pay twice (#2997 §5) #3003)。

不建议增加新的配置、强制净收益门禁或复杂调度机制,优先通过简短的提示词充分利用现有能力。


建议优先处理前三项功能正确性与 Schema 一致性问题。第四项属于模型行为和 Token 开销优化,尽量通过替换或精简现有描述实现,而不是继续叠加提示词。

整体上不需要扩大 PR 的设计范围。

awork and others added 18 commits October 25, 2026 04:21
…#3185)

New non-mutating CompressionCore.previewCompression: runs the full pre-commit
planning (boundary resolution, protected carve, turn-integrity withdrawals,
min-range gate, refold decisions) on a throwaway state clone and returns a
per-range report with exact would-fail error text, would-fold refs, exclusion
categories, withdrawn turns and estimated tokens saved. Zero side effects: no
blocks, no ref allocation, no ledger write, idempotent.

applyCompression is refactored around the same extracted stages
(prepareBatch / planSingleRange / commitFoldedRange) verbatim — non-dryRun
behavior byte-identical, pinned by the existing suite.

Compress tool schema gains an optional top-level dryRun boolean (plain object,
no combinators, #1299); summary becomes optional under dryRun via parser
enforcement only (lenient parser threads the flag through object/string/
salvage/line-form paths). rebuild skips recorded dry-run calls so a preview
never fabricates blocks on replay.
…avings before committing (#3185)

A model can now call compress with dryRun:true (summary omitted) to get a
structured receipt BEFORE committing: whether the range is valid (exact error
text a real call would produce), what it would fold, what is excluded
(protected tools / recent zone / checkpoint carriers / media), which messages
are withdrawn for turn integrity, which blocks it absorbs, and the estimated
tokens saved plus post-fold window occupancy. The preview is routed in
applyRanges before any failure-tracking side effect and short-circuits the
external-summarizer lane on raw input, so both compression modes cover it.

Goldens regenerated for the schema surface: dryRun property added to all four
tool schemas, summary descriptions note 'REQUIRED unless dryRun=true', Google
items.required drops 'summary' (kernel still rejects missing summary on real
calls via parser diagnostics).
)

The first draft of the dryRun parameter carried a ~440-char description
that landed in every outbound request body of injectTool sessions
(+~820B ≈ +205 tokens per turn, permanent). That constant overhead
broke byte-pinned goldens and shifted knife-edge preflight fit
boundaries (fold timing moved ±1 turn under the flat nudge cadence).

Shortened the main + google dryRun descriptions and the TOOLS prompt
sentence to carry the same contract in less text: preview reports
validity/exclusions/withdrawals/savings, zero side effects, re-issue
with summary to commit. No behavior change — schema shape, param
name, and the 'REQUIRED unless dryRun=true' suffixes are untouched.
…n tool surface (#3193)

Intentional tool-surface growth (new dryRun boolean param on the
compress tool) changes every pinned outbound body, so both golden
sets were regenerated via scripts/update-wire-contract-goldens.ts
and scripts/update-storage-render-goldens.ts. The storage-render
regeneration was missing from the original PR head — that alone
accounted for 8 of the 14 failing tests across all 12 CI shards.
…erhead floor (#3193)

Four behavioral fixtures sat within ~205 tokens of their window limit;
the new permanent per-request tool-schema bytes pushed two of them
across the fold boundary (master decision 9984 < 10000 → tail survives;
PR head 10189 ≥ 10000 → recent-zone tail folded) and shifted fold
settlement ±1 turn under the flat 50K/500-token nudge cadence.

- #280/#568/#663-anthropic: trim filler repeat(250)→repeat(225)
  (~13k → ~12k tokens vs the 10k window) so post-fold estimates keep
  comfortable headroom below the limit while still exceeding it
  pre-fold; test intent unchanged.
- cache-proof host-compaction: the strict element-count shrink assert
  could not see a fold landing in the same body as the client's own
  user+assistant append (bytes shrank 99KB→55KB, count flat). The
  settling-fold check now compares coreLen net of CLIENT_TURN_APPENDS=2
  appends — a no-op zombie fold (count grows by exactly the appends)
  still fails.
…Run wording (#3193)

The function-mode compress system prompt is byte-pinned against a
checked-in fixture (surface-config byte-stability gate). The wording
tightening in the previous commit changed the TOOLS section, so the
fixture was regenerated from buildCompressSystemPrompt(). Only that one
line moved; the text/hybrid builders do not carry the dryRun text.
…d preview-first prompt strategy (#3193 review)

Per the #3193 pre-merge review, three schema-surface corrections plus the
prompt-strategy swap:
- COMPRESS_TOOL_GOOGLE: dryRun sat at the parameters level (sibling of
  properties) where it is not a valid schema key — strict validators reject
  or ignore it. Moved into properties.
- COMPRESS_PARAMETERS batch object branches: 'summary' removed from both
  required arrays so strict pre-validating hosts stop rejecting summary-less
  dryRun previews; parseCompressArgs still enforces the summary for real
  commits (behavior unchanged).
- dryRun description slimmed to function/input/return only on both wire
  shapes (the commit procedure moved to the system prompt).
- TOOLS prompt section: replaced the re-issue sentence with the preview-first
  decision strategy (preview whole batch, evaluate estimatedTokensSaved and
  exclusions, plan then commit in ONE call; skip only for fresh
  acp_status-recommended ranges verbatim). Lives in the summarization-call
  prompt only — main-request bodies carry less, not more.
Structural guard added: top-level schema keys must stay within
type/properties/required on both shapes (byte goldens alone missed the
Google misplacement).
#3193 review)

applyRanges checked parsed.dryRun AFTER the zero-valid-ranges branch had
already run recordCompressFailure + noteCompressLoopFailure — a preview with
a bad argument shape (bare flag, non-object entry) armed the repeat-failure
streak and could trip the loop breaker after 3 repeats, contradicting the
'preview is not an attempt' contract. The zero-ranges path now recognizes
dryRun first and returns a PREVIEW FAILED refused receipt with no counter
writes.
…cted dryRun schema surface (#3193 review)

Intentional tool-surface change from the kernel commit above (dryRun moved
into the Google properties object, summary dropped from the batch required
arrays, description shortened). Regenerated via scripts/update-wire-contract-goldens.ts
and scripts/update-storage-render-goldens.ts.
Owner request (issue #3185 floor 14/23): the dryRun preview added by this PR must sit behind a config switch, OFF by default, where OFF behaves exactly as if the feature were never merged.

- New knob compress.dryRunPreview (bool, default false) / env BILI_COMPRESS_DRYRUN, resolved env>file>default via knobs.dryRunPreviewEnabled().

- Kernel: base schema/prompt reverted to pre-feature bytes; separate _DRYRUN variants + prompt-sentence const exported; parser gains allowDryRun (default false).

- Host serves base-vs-_DRYRUN per request at every tool-serving site and appends the strategy sentence only when ON; routing auto-gates because parsed.dryRun is forced false when OFF.

- Regenerated wire-contract goldens prove the OFF path is byte-identical to master; docs updated en+zh (seed-driven).
Rebasing onto master left buildCompressHybridSystemPrompt both re-exported
from acp-kernel and defined locally as the withDryRunStrategy wrapper —
a duplicate export that breaks esbuild/tsx transforms of the module.
The wrapper supplies the name (byte-identical output when the switch is
off), so the re-export line goes.
The rebased golden snapshots predate master's #4252 advertised-schema
narrowing; regeneration converges them to the current served surface.
With the dryRun switch default-off the regenerated files are byte-equal
to origin/master's (verified by empty diff), i.e. zero surface drift.
)

The compress dryRun preview switch (#3185/PR #3193) reads BILI_COMPRESS_DRYRUN
in src/knobs.ts but was never added to the lifecycle ledger, tripping the
lifecycle-ledger-guard. Added as a default-off opt-in transition gate with a
release condition (retire env + move to §2 once the preview lane goes GA).
The #4316 ledger-alignment train added the refLedgerAligned state key without
refreshing these goldens on master (verified: pure-master regen produces these
exact bytes). Refresh so this branch is self-consistent with its own code.
…dRange (#3193)

The dry-run split moved the createdAt stamp out of applySingleRange into
commitFoldedRange, voiding the fn-keyed exception and red-ing verif-subset-guard.
Zhishulo and others added 9 commits October 25, 2026 09:35
…est (master born-red, #4599 sentinel)

The tier-5 train added generationBoundaryActive as injectSystem's 9th parameter
and updated every caller except this test's 'active' case: its trailing true
landed in mcpDialectNote, so the note never appeared and the assertion must fail.
Identical one-line fix already committed on PR #4559's branch (e82ccd7); drop
that commit when rebasing whichever way merges first.
…s site (#4598, #4599 sentinel)

pages.yml has failed 75/75 runs since landing: actions/configure-pages@v5 gets
'Get Pages site failed ... Not Found' because GitHub Pages was never enabled on
this repo (the earlier enablement:true attempt was reverted without a recorded
reason — not re-applied here). Stop-the-bleed per #4598 option 1: drop the push
trigger, keep manual workflow_dispatch so the deploy path stays intact and no
website push red-lines master again. Final direction (re-enable Pages vs retire
the workflow vs in-install serving) awaits owner decision.
…ne-rewrite (#4599 sentinel)

The #3719 Updates tab stayed routed (PAGES/route/loadUpdates in client.ts)
but its topbar anchor was dropped when #3536 rewrote the whole topbar line,
making nav.updates a dead catalog key (web-i18n born-red on every PR head).
Restored at the original position (after logs); identical to the sibling fix
on the panel-blog branch (900c09c), adapted to master (no blog anchor yet).
…4427 Windows red, #4599 sentinel)

maskPathsForPublish keyed off os.homedir() alone. On Windows that reads
%USERPROFILE% while git-bash-style tool output carries $HOME paths, so the
publish-boundary identity leak masked one spelling and leaked the other
(#4427 suite red on windows shards only). Now masks the deduped set of
os.homedir() + $HOME + %USERPROFILE%; POSIX behavior unchanged (values
dedupe to one root), anchored-flank semantics preserved.
… restamp flag (#4599 sentinel)

Deliberate persisted-state change: 380ef4d (#4316 layer 3 PR3/3) added the
one-time refLedgerAligned boolean to session state. All four wire digests are
UNCHANGED; only the metadata section digest moved (+refLedgerAligned state
key). Regen per the suite's own protocol (justification recorded here and in
the ci-fixes PR body).
…wed-load interface (#4599 sentinel)

#D5-5 changed buildView to call store.unifiedMessageIdRows() +
store.unifiedUncoveredRows(id, intervals) first; the pre-existing fake stores
(only unifiedTailSeqs/unifiedTailViewRows) threw TypeError, caught by the
by-design degrade net as transcript-error, turning every render-expecting
assertion red (chain 6/6, verif replay). Extended both real-JS fakes and the
symbolic harness portImpls (__method_unifiedMessageIdRows /
__method_unifiedUncoveredRows) to mirror SessionStore semantics.

This branch has not been deployed

No deployments
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.

feat: add dryRun preview mode to the compress tool (validate range & estimate savings without committing)

3 participants