From ffc9fd999d673f23cbe8fea2c7bbc126813614f6 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Sun, 27 Sep 2026 23:41:13 +0800 Subject: [PATCH 1/5] docs(tools): the bare-string compress form may carry a whole batch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- src/compress-tools.ts | 6 +++--- src/packs.ts | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/compress-tools.ts b/src/compress-tools.ts index c2c8d56..49bf397 100644 --- a/src/compress-tools.ts +++ b/src/compress-tools.ts @@ -96,7 +96,7 @@ export const COMPRESS_PARAMETERS = { }, content: { description: - "One or more ranges to compress into separate summary blocks. Array form (preferred): one entry per range — line form (one STRING per range: first line 'm00150–m00220 optional topic', remaining lines the markdown summary verbatim) or object form {startId,endId,summary,topic?}. String form also accepted: bare line-form text, or a JSON-encoded array of ranges (some gateways stringify arrays). REQUIRED unless the flat single-range form is used.", + "One or more ranges to compress into separate summary blocks. Array form: one entry per range — line form (one STRING per range: first line 'm00150–m00220 optional topic', remaining lines the markdown summary verbatim) or object form {startId,endId,summary,topic?}. Single-string form (PREFERRED for multi-range batches — plain text survives lossy gateways best): ONE plain string holding ALL ranges, each block starting with its 'm00150–m00220 optional topic' header line followed by that block's summary. A JSON-encoded array of ranges as that string is also accepted (some gateways stringify arrays). Batch multiple ranges into ONE call — do not split into one call per range. REQUIRED unless the flat single-range form is used.", anyOf: [ { type: "array", @@ -105,7 +105,7 @@ export const COMPRESS_PARAMETERS = { { type: "string", description: - "Line form: first line 'm00150–m00220 optional topic', remaining lines the summary markdown, verbatim (no JSON escaping)", + "Line form: first line 'm00150–m00220 optional topic', remaining lines the summary markdown, verbatim (no JSON escaping). A single string may carry MULTIPLE ranges — each block starts with its own refs header line", }, { ...COMPRESS_RANGE_OBJECT, @@ -150,7 +150,7 @@ export const COMPRESS_PARAMETERS = { export const COMPRESS_TOOL = { name: COMPRESS_TOOL_NAME, description: - "Replace consumed conversation ranges with self-contained summaries you write, identified by their refs. Line form (preferred): content = one STRING per range — first line 'm00150–m00220 optional topic', remaining lines the markdown summary written verbatim (no JSON structure, no escaping). Also accepted: object entries {startId,endId,summary,topic?} in the content array, content as a single string (bare line form or JSON-encoded array), and a flat single-range call {startId,endId,summary,topic?} without content. Use when content is genuinely consumed. REQUIRED — compress without content or flat range fields is invalid.", + "Replace consumed conversation ranges with self-contained summaries you write, identified by their refs. Line form (preferred): content = one STRING per range — first line 'm00150–m00220 optional topic', remaining lines the markdown summary written verbatim (no JSON structure, no escaping). Also accepted: object entries {startId,endId,summary,topic?} in the content array, 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), and a flat single-range call {startId,endId,summary,topic?} without content. Batch multiple ranges into ONE call. Use when content is genuinely consumed. REQUIRED — compress without content or flat range fields is invalid.", input_schema: COMPRESS_PARAMETERS, }; diff --git a/src/packs.ts b/src/packs.ts index 3b93876..9e13deb 100644 --- a/src/packs.ts +++ b/src/packs.ts @@ -181,7 +181,7 @@ const LEAN_TOOL_PROMPTS: ToolPrompts = { "Replace consumed conversation ranges with self-contained summaries using mNNNNN or bN refs.", paramDescriptions: { content: - "One string per range: first line 'm00150–m00220 optional topic', remaining lines the summary markdown. Object form also accepted.", + "One string per range: first line 'm00150–m00220 optional topic', remaining lines the summary markdown; ONE string may hold several ranges (new header line per range). Object form also accepted.", startId: "Inclusive first mNNNNN or bN ref.", endId: "Inclusive last mNNNNN or bN ref.", summary: "Self-contained replacement preserving exact technical details.", From e3436c2cea25923725419d2d65df751b99cdc067 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Sun, 27 Sep 2026 23:42:56 +0800 Subject: [PATCH 2/5] docs(nudge): teach the single-string batch form in the fold hint --- src/nudge-text.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/nudge-text.ts b/src/nudge-text.ts index cf7c321..891845c 100644 --- a/src/nudge-text.ts +++ b/src/nudge-text.ts @@ -302,7 +302,7 @@ export function renderNudgeText( rangesStr, ...(blockMapStr ? ["", blockMapStr] : []), "", - `💡 If you compress, fold the ranges you keep in ONE call (pass multiple content entries: \`content: [{...}, {...}]\`). Ranges the task still needs can wait — they reappear in later nudges.`, + `💡 If you compress, fold the ranges you keep in ONE call — pass multiple content entries (\`content: [{...}, {...}]\`) or ONE plain string holding every range, each block starting with its 'mNNNNN–mNNNNN topic' header line (most robust through lossy gateways). Ranges the task still needs can wait — they reappear in later nudges.`, ]).join("\n"), }; } From b871e2671ce42379373313bf8934f472f25ca859 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Sun, 27 Sep 2026 23:59:35 +0800 Subject: [PATCH 3/5] docs(packs): lean compress one-liner teaches ONE-call batching too --- src/packs.ts | 2 +- tests/packs.test.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/packs.ts b/src/packs.ts index 9e13deb..732ef3c 100644 --- a/src/packs.ts +++ b/src/packs.ts @@ -178,7 +178,7 @@ export const defaultPack: Pack = { const LEAN_TOOL_PROMPTS: ToolPrompts = { compress: { description: - "Replace consumed conversation ranges with self-contained summaries using mNNNNN or bN refs.", + "Replace consumed conversation ranges with self-contained summaries using mNNNNN or bN refs; batch multiple ranges into ONE call (a single string may hold every range).", paramDescriptions: { content: "One string per range: first line 'm00150–m00220 optional topic', remaining lines the summary markdown; ONE string may hold several ranges (new header line per range). Object form also accepted.", diff --git a/tests/packs.test.ts b/tests/packs.test.ts index 9f12c64..4765b12 100644 --- a/tests/packs.test.ts +++ b/tests/packs.test.ts @@ -83,7 +83,7 @@ test("lean pack keeps rules default, one-line tool descriptions, adapters namesp assert.deepEqual(leanPack.surface.prompts ?? {}, {}); assert.equal( leanPack.surface.toolPrompts?.compress?.description, - "Replace consumed conversation ranges with self-contained summaries using mNNNNN or bN refs.", + "Replace consumed conversation ranges with self-contained summaries using mNNNNN or bN refs; batch multiple ranges into ONE call (a single string may hold every range).", ); assert.ok( leanPack.surface.adapters && typeof leanPack.surface.adapters === "object", From 0e89c43987bbde835f33c7cb435897be7f93a9ae Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Mon, 28 Sep 2026 09:05:47 +0800 Subject: [PATCH 4/5] test(parse): pin the one-string-whole-batch form every surface teaches --- tests/parse-compress-input.test.ts | 34 ++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/tests/parse-compress-input.test.ts b/tests/parse-compress-input.test.ts index 8f32df1..8a2e6ec 100644 --- a/tests/parse-compress-input.test.ts +++ b/tests/parse-compress-input.test.ts @@ -1168,3 +1168,37 @@ test("rebuildCompressionState rebuilds from a single-object content tool-call (# result.state.blocks.find((b) => b.summary.includes("single object")), ); }); + +test("one bare string may carry a whole batch: every tool surface recommends it (#472)", () => { + // The default/lean packs + the nudge hint now teach this form as the + // gateway-robust way to batch — pin the parse so it cannot regress. + const { ranges, diagnostics } = parseCompressArgs({ + content: + "m00001–m00005 topic one\nsummary one line.\nm00006–m00008\ntopic-less summary.", + }); + assert.equal(diagnostics.kind, "ok"); + assert.equal(diagnostics.invalidItems, 0); + assert.equal(ranges.length, 2); + assert.deepEqual( + { + start: ranges[0]?.startRef, + end: ranges[0]?.endRef, + topic: ranges[0]?.topic, + summary: ranges[0]?.summary, + }, + { + start: "m00001", + end: "m00005", + topic: "topic one", + summary: "summary one line.", + }, + ); + assert.deepEqual( + { + start: ranges[1]?.startRef, + end: ranges[1]?.endRef, + summary: ranges[1]?.summary, + }, + { start: "m00006", end: "m00008", summary: "topic-less summary." }, + ); +}); From 7b68d49fb053ec439f7533d2c5cf970474590985 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Mon, 28 Sep 2026 09:23:42 +0800 Subject: [PATCH 5/5] docs(philosophy): show the one-string batch form in the TOOLS example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- src/compress-tools.ts | 2 +- tests/fixtures/prompt-function-default.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/compress-tools.ts b/src/compress-tools.ts index 49bf397..a6dd4a9 100644 --- a/src/compress-tools.ts +++ b/src/compress-tools.ts @@ -252,7 +252,7 @@ Each message in the conversation is annotated with a