Skip to content

docs(tools): the bare-string compress form may carry a whole batch - #472

Merged
ranxianglei merged 5 commits into
masterfrom
2026-09-27_compress-string-batch-docs
Sep 28, 2026
Merged

ranxianglei merged 5 commits into
masterfrom
2026-09-27_compress-string-batch-docs

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

Refs ranxianglei/billion-context#1495 (owner re-review: after the #1497/#1499 receipt fixes, models stopped batching compress and issued one call per range).

The lenient parser (splitLineEntries, src/parse-compress-input.ts:432) has always accepted one plain string holding MULTIPLE ranges — each block starting with its own m00150–m00220 optional topic header line:

parseCompressArgs({ content: "m00001–m00005 topic one\nsummary…\nm00006–m00008 topic two\nsummary…" })
→ ok:true, 2 ranges

…verified live against this branch. But every tool description said “one STRING per range” (tool description, content param description, lean pack param description, anyOf string alternative), so no model knew it could batch this way. Under lossy gateways that stringify/truncate array arguments, models rationally retreated to single-range calls — which works, but multiplies compress turns (the owner's complaint).

Change (description text only — 4 sites, no behavior)

  • src/compress-tools.ts COMPRESS_TOOL.description: “content as a single string (bare line form — one string may hold ALL ranges, each block starting with its refs header line — or JSON-encoded array)” + “Batch multiple ranges into ONE call.”
  • src/compress-tools.ts content param description: single-string form marked PREFERRED for multi-range batches (“plain text survives lossy gateways best”), + “do not split into one call per range”.
  • anyOf array-item string alternative: “a single string may carry MULTIPLE ranges — each block starts with its own refs header line”.
  • src/packs.ts lean param description: “ONE string may hold several ranges (new header line per range)”.

Rationale for preferring the string form for batches: the line form needs structure only in the refs header lines, so it has no array nesting for a gateway to stringify, and truncation salvage recovers every complete leading block.

Validation

  • tsc --noEmit 0; full suite 1188/1188 pass (incl. compress-schema-contract 31/31, packs).
  • No tests pin the description strings; bili's wire-contract goldens will be regenerated in the follow-up bili pin-bump PR.

Downstream: bili receipt wording (teaching lost-range re-issue as ONE single-string call) + pin bump lands as a separate bili PR after this releases.

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-27_compress-string-batch-docs (7b68d49)

Option A — Install from npm PR tag (recommended)

In your adapter project:

npm install acp-kernel@pr-472

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

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf acp-kernel-pr472.tgz
npm install ./package

This comment is automatically updated on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR verified — review conclusion: mergeable (two non-blocking flags below).

This is already-built PR work, so I pulled branch 2026-09-27_compress-string-batch-docs (head f381f3b, exactly 2 commits ahead of current master) and checked code + CI rather than redoing it.

What I verified

  1. Core claim reproduced live: parseCompressArgs({ content: "m00001–m00005 topic one\nsummary A\nm00006–m00008 topic two\nsummary B" }) → ok, 2 ranges. En-dash and hyphen separators both accepted; optional topic works. The lenient parser (splitLineEntries, src/parse-compress-input.ts:432) capability is real and untouched by this PR — the fix correctly targets the descriptions that hid it. Layer judgment: root cause was tool text saying "one STRING per range" at every surface while the parser always accepted a whole batch in one string; teaching the existing capability is the right fix, no behavior change needed.
  2. Local pre-flight on the branch (Node 22): tsc --noEmit clean; 1188/1188 tests pass; build OK; format:check OK.
  3. CI on head f381f3b: all 4 checks green (test 22, test 24, pr-validation, build-artifact).
  4. Diff vs master is exactly 3 files / 5 lines, every line on-topic; branch is up to date with master (fast-forwardable).

Existing-behavior audit (regression pass)

  • Wire schema shape (COMPRESS_PARAMETERS / COMPRESS_TOOL): keys/types/required untouched — only description strings changed; wire-schema tests (which assert shape) still pass. Accepted language unchanged (parser not touched). → preserved.
  • Gentle nudge text (src/nudge-text.ts:305): intentional change, flagged per policy — old: "fold the ranges you keep in ONE call (pass multiple content entries: content: [{...}, {...}])"; new additionally teaches "or ONE plain string holding every range, each block starting with its 'mNNNNN–mNNNNN topic' header line (most robust through lossy gateways)". This is advisory gentle-nudge wording (not one of the four load-bearing prompt rules), and the nudge path has no length guard, so the ~20 extra words are safe.
  • Lean pack param description (src/packs.ts:184): same kind of advisory surface-text update. → intentional.
  • No thresholds / defaults / timing / output-format / state-schema changes anywhere in the diff.

Flags (non-blocking)

  1. Scope delta vs the issue body: body says "4 sites"; the branch carries a 5th — the nudge fold-hint (commit f381f3b). It's within the PR's intent (that hint is precisely where the model learns how to batch) and low-risk, but it wasn't in the stated scope — surfacing for the record.
  2. Test gap: the multi-range bare-string form is now marked PREFERRED for batches, yet tests/parse-compress-input.test.ts (71 tests) has no case pinning a single string with multiple refs-header lines (today's single-string cases cover only JSON-encoded arrays, garbage "123", and ""). If a future strictness pass touches splitLineEntries, the recommended batch path would break silently with no kernel-side test failing. Suggest adding one small regression test:
    const r = parseCompressArgs({ content: "m00001–m00005 t\nA\nm00006–m00008 u\nB" });
    assert.equal(r.ranges.length, 2);
    Say the word and I'll land it as a separate commit on the branch.

Downstream ordering (bili receipt wording + pin bump after this releases) matches the kernel-first cross-repo rule — nothing needed here.


中文摘要:核对了 PR #472——仅改 5 处面向模型的描述文案,教模型用单个字符串一次传多个压缩区间(解析器本就支持,已实测复现);本地 typecheck / 1188 测试 / build / format 全绿,CI 四项全绿,无行为回归(nudge 文案加长属有意变更,已按旧值→新值标注),可以合并;唯一建议是补一条「多区间单字符串」解析的回归测试。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Amended: lean pack coverage audit (asked during review) —

surface default lean
tool description ✅ 5033779 ✅ 285e506 (one-liner now teaches batch multiple ranges into ONE call (a single string may hold every range))
content param description ✅ 5033779 ✅ 5033779 (paramDescriptions)
anyOf string-item description ✅ 5033779 ✅ inherited — cloneWithDescriptions only replaces named properties, the anonymous anyOf item keeps the shared (edited) schema text
nudge fold hint ✅ f381f3b ✅ shared — leanPack leaves nudgeSections untouched
how-to rules N/A (summary-content contract, no wire-form teaching) N/A (LEAN_HOW_TO_COMPRESS same)

tests/packs.test.ts one-line-description pin updated deliberately; full suite 1188/1188.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Amended head 285e506 re-verified — verdict stands: mergeable.

What I checked on the amendment:

  1. Commit content — 285e506 is exactly 2 lines: src/packs.ts:181 (lean one-liner now ends with ; batch multiple ranges into ONE call (a single string may hold every range).) + the matching pin update in tests/packs.test.ts:86. Nothing else touched.
  2. anyOf-inheritance claim verified in code — cloneWithDescriptions (src/surface-config.ts:85-107) only replaces a description when the property name matches an override key (Object.hasOwn(overrides, name)); anyOf items are array elements (anonymous), so they pass through untouched and keep the shared edited string-item text from src/compress-tools.ts. The table's "inherited" row holds.
  3. Local pre-flight on 285e506 (Node 22): tsc --noEmit clean; 1188/1188 pass; build OK; format:check OK.
  4. CI on 285e506: all 4 checks green (pr-validation, test 22, test 24, build-artifact). Branch is still exactly origin/master (3519e08, unchanged) + 3 commits — fast-forwardable. Full diff vs master: 4 files / 7 lines, all description text or its test pin.

Round-1 flags after the amendment:

  • (a) scope delta (nudge fold-hint = 5th site) — resolved by your coverage table; no further action.
  • (b) still open: no kernel-side regression test pins the multi-range bare-string parse form that every surface now recommends (tests/parse-compress-input.test.ts has no single-string multi-header case). Suggestion unchanged — one small test:
    const r = parseCompressArgs({ content: "m00001–m00005 t\nA\nm00006–m00008 u\nB" });
    assert.equal(r.ranges.length, 2);
    Say the word and I land it as a separate commit on the branch before merge.

中文摘要:复核了补交提交 285e506(lean 包单行工具描述同步教一次性批量 + 对应测试 pin 更新,共 2 行),并在代码层面核实了「cloneWithDescriptions 只按属性名替换、anyOf 匿名项继承共享文案」的论断;本地 typecheck / 1188 测试 / build / format 全绿,CI 四项全绿,分支仍可快进合并,可以合并;唯一遗留建议是补一条「多区间单字符串」解析回归测试。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Suggestion (b) landed in 87185e8 — tests/parse-compress-input.test.ts now pins the one-string-whole-batch form deeply: kind=ok, invalidItems=0, 2 ranges with exact startRef/endRef/topic/summary extraction (including the topic-less header variant). Full suite 1189/1189.

ranxianglei pushed a commit that referenced this pull request Sep 28, 2026
87185e8 added the one-string-whole-batch regression test with lines that violate the repo Prettier style; CI format:check fails before typecheck/test ever run. This commit applies prettier --write to that block only — pure line-wrapping, zero semantic change.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Test commit verified — one CI break found and fixed directly on the branch; head is now 17c56b7, all green, mergeable.

On 87185e8 itself — the test has teeth: kind="ok", invalidItems=0, exactly 2 ranges, and deepEqual pins of startRef/endRef/topic/summary per range including the topic-less header variant (m00006–m00008 with no topic). If someone ever tightens splitLineEntries or breaks header detection, this fails loudly. Good.

But CI went red on it: test (24) failed at the npm run format:check step (typecheck/test/build were skipped behind it), and test (22) was cancelled. Root cause confirmed by job log + local repro: the new test block in tests/parse-compress-input.test.ts violated Prettier style (long lines), so the repo's "never commit while format:check is red" gate tripped before anything else ran.

Fix I landed — since CI was failing I took the small fix myself, per review convention:

  • Commit 17c56b7 test(parse): prettier-format the batch-form pin (#472): ran Prettier on that block only. Verified by diff that it is pure line-wrapping of the new test — zero semantic change, assertions byte-identical.
  • Local pre-flight on the fixed head: format:check ✅, tsc --noEmit ✅, 1189/1189 ✅.
  • Pushed to the PR branch; CI on 17c56b7: all 4 checks success (test 22, test 24, pr-validation, build-artifact). Branch remains fast-forwardable onto master.

Full diff vs master is now 5 files / ~30 lines: 4 description-text sites (+ its packs pin) and the regression test. Both earlier flags are closed — scope delta resolved by your coverage table, test gap pinned in 87185e8. Nothing left open on my side.


中文摘要:复核了测试提交 87185e8(断言有牙:kind/invalidItems/双区间精确提取含无 topic 变体),但发现它没过 Prettier 导致 CI format:check 红、后续步骤全被跳过;已直接在分支上补了纯换行格式的提交 17c56b7(断言语义零改动),本地与 CI 四项全绿,可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Deep review — verdict: MERGEABLE (reviewed on the PR head).

Verified

  • Full kernel suite 1186→1189: 1189/1189 on the branch, typecheck clean, tree clean.
  • Targeted: packs + parse-compress-input + prompt-function 94/94 — including the fixture golden (prompt-function-default.txt) which is updated in-PR.
  • Mutation (splitter truncated to first entry → the taught multi-range bare string dies): 2 red — the documented form is now pinned and cannot silently regress.

What this PR is (and correctly stays)

Pure documentation surface: default-pack tool description, lean-pack description + param description, the nudge 💡 hint, and the prompt-function fixture — all now teach that ONE bare string may carry the whole batch (one refs-header line per range), positioned as the gateway-robust form. Zero runtime logic change; the parser has supported this shape all along, the PR makes it a taught + pinned contract instead of an accident.

Why it matters (ties the chain together)

#1495/#1497/#1499 showed lossy gateways and drift produce wrapped/stringified/mangled content — the bare line form is the shape that survives all of them (no JSON structure to mangle, refs anchored at line starts). Teaching it at every surface (default pack, lean pack, nudge) is the prompt-side complement to the parser-side salvage ladder (#471). The new pin test documents the exact expected parse (2 ranges, topic'd + topic-less, derived topics).

Notes: description growth is ~1 line per surface — fine. The fixture update is the golden itself, regenerated in-PR (no drift). Non-blocking: none.

Sibling note for the owner: #471 (parser salvage, Fixes #470) and this PR are independent — merge in either order; both belong to the #1494/#1495 hardening chain.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Confirmed on the final head 6bb0782 — agree with MERGEABLE.

Re-verified the new commit and the full state:

  • 6bb0782 inspected: the FUNCTION_PROMPT_SECTIONS TOOLS example (src/compress-tools.ts, the strongest surface — rides every request) now shows the same batch as ONE plain string with the escaped \n visible, marked most robust through lossy gateways. The fixture tests/fixtures/prompt-function-default.txt is regenerated in-PR and its diff mirrors the source line byte-for-byte — legitimate golden regen, no drift. Text/hybrid protocol sections untouched (their model-emitted text isn't gateway-corrupted) — sound scoping.
  • CI on 6bb0782: 4/4 success (test 22, test 24, pr-validation, build-artifact). Local suite on the head: 1189/1189.
  • One number correction for the record: the baseline is 1188, not 1186 — I measured origin/master (3519e08, unchanged) directly just now: 1188/1188. So the delta across this PR is +1 (the batch-form pin block): 1188 → 1189. Substance unaffected.
  • Final PR shape: 6 files / +43 −9 — five taught surfaces (default tool desc, content param, anyOf item, lean pack desc+param, nudge hint, prompt TOOLS example), its fixture golden, and the deep pin test. Zero runtime logic change; the parser supported this shape all along — it's now a taught + pinned contract.

Sibling note acknowledged: #471 is independent, merge order doesn't matter. Nothing left open on my side — ready for human merge whenever.


中文摘要:在最终头 6bb0782 上复核确认——系统提示 TOOLS 示例新增单字符串批量形式、fixture 为 PR 内再生且与源码逐字一致(非漂移),本地 1189/1189、CI 4/4 全绿,同意 MERGEABLE;仅更正一处数字:master 基线实测为 1188 而非 1186(本 PR 净增 1 个测试块)。

The lenient parser (splitLineEntries) has always accepted one plain string
holding MULTIPLE ranges — each block starting with its own refs header
line — but every tool description said 'one STRING per range', so models
retreated to one-call-per-range after lossy gateways corrupted their
array batches (ranxianglei/billion-context#1495: batched calls died,
models adapted by splitting, compress turns multiplied).

Document the single-string batch form and steer multi-range batches to
ONE call: plain text survives stringify/truncate gateways best because
the line form needs structure only in the refs header lines.
The system-prompt tools section (FUNCTION_PROMPT_SECTIONS, the strongest
surface — it rides every request) taught batching with the object-array
example only. Show the same batch as ONE plain string with the escaped
\n visible, marked most robust through lossy gateways.

Fixture prompt-function-default.txt regenerated (byte-stability pin).
Text/hybrid protocol sections untouched: no gateway corrupts their
model-emitted text, and they already teach one-trigger batching.
@ranxianglei
ranxianglei force-pushed the 2026-09-27_compress-string-batch-docs branch from 6bb0782 to 7b68d49 Compare September 28, 2026 05:25
@ranxianglei

Copy link
Copy Markdown
Owner Author

Rebase onto master (post-#471 merge) — head 7b68d49, mergeable ✅

Conflict was the tail-append seam in tests/parse-compress-input.test.ts (both #471 and #472 append tests at EOF); resolved by union — the resolved file is byte-identical to the locally-tested union tree. The prettify commit folded into the test commit (no-op after union).

Gates on the rebased head: parse+surface 85/85, full suite 1202/1202, typecheck clean. User validated the combined build (#471+#472) live in a real pi session: one-string 3-block batch compressed m00059–m00060 / m00083–m00090 / m00098–m00099 → 3 blocks, ~14818 tok saved; per-summary cap proven NOT shared across the batch (3 × 19 000-char summaries parse fine).

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Rebased head 7b68d49 verified — MERGEABLE confirmed.

What I checked on the rebase:

  1. Shape — 5 commits on fresh master 2d6ff22 (post-fix: salvage single-entry object in the compress content slot (#470) #471 merge), fast-forwardable; content diff identical to the pre-rebase state (6 files / +43 −9). Prettify commit folded into 0e89c43 as described.
  2. Conflict resolution verified byte-exact — the diff of tests/parse-compress-input.test.ts against the new master is a pure tail-append: 34 lines added, 0 removed (fix: salvage single-entry object in the compress content slot (#470) #471's salvage tests untouched), and the appended block is byte-identical to the prettier-formatted version I tested at 17c56b7. Union resolution, no silent content change.
  3. Local gates on 7b68d49: tsc --noEmit clean; full suite 1202/1202; build OK; format:check OK.
  4. CI on 7b68d49: 4/4 success (test 22, test 24, pr-validation, build-artifact).

The live pi-session validation is the right capstone: one-string 3-block batch → 3 blocks, ~14818 tok saved, and the per-summary cap proven NOT shared across the batch — that's exactly the taught behavior this PR exists to make default.

Nothing open on my side — ready for human merge.


中文摘要:复核了 rebase 后的头 7b68d49——冲突按并集解决且逐字节核实(pin 测试与 rebase 前版本完全一致、#471 的测试原样保留、纯尾部追加零删除),本地 tsc / 1202 测试 / build / format 全绿,CI 4/4 全绿,可以合并。

@ranxianglei
ranxianglei merged commit 86c9b92 into master Sep 28, 2026
4 checks passed
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.

1 participant