From f3ab0124a4f5cbf33fe4cc469f19f02395a6b042 Mon Sep 17 00:00:00 2001 From: ci-check Date: Mon, 26 Oct 2026 03:52:58 +0800 Subject: [PATCH 1/2] fix(server): warn once per session/route when autoFoldTargetTokens clamps inert (#4543) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An explicit autoFoldTargetTokens at or above a route's overflow bar is clamped to the bar, which leaves growth folding silently disarmed on that route (only overflow folds run). noteAutoFoldIgnored only covers the disabled-chain no-op, so this state had no surfacing at all — an operator believes the pre-forward fold is armed when it is not (#4543 floor-1 finding). Warn once per session per distinct route bar from preflightCompressIfNeeded, naming both the configured value and the route's overflow target plus the remedy. Logging only — zero behavior change. Throttle marker rides session.metadata so a mid-session route switch re-warns for the new bar. --- src/server.ts | 12 ++- tests/external-summary-autofold.test.ts | 112 ++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 1 deletion(-) diff --git a/src/server.ts b/src/server.ts index 2dd74daee8..aca0094c12 100644 --- a/src/server.ts +++ b/src/server.ts @@ -3348,6 +3348,7 @@ export async function preflightCompressIfNeeded( // floor under the documented minimum. Clamping to the minimum disarms // auto-fold on sub-8K windows outright (target >= overflow ⇒ growthArmed // false), which matches the documented feature scope. + const configuredAutoFoldTarget = (config as ResolvedKernelConfig).externalSummary?.autoFoldTargetTokens; // [#3444] A configured target below what this session can physically reach // (system prompt + tool schemas + live tail) is UNREACHABLE: every fold // lands above it and the trigger re-fires on every request (fold storm). @@ -3359,10 +3360,19 @@ export async function preflightCompressIfNeeded( // releases via growthFoldingArmed's measuredFloor arg). const measuredFloor = autoFoldOn ? autoFoldFloor(session) : undefined; const autoFoldTarget = autoFoldOn - ? Math.min(Math.max(Math.max(AUTO_FOLD_TARGET_MIN, Math.min((config as ResolvedKernelConfig).externalSummary?.autoFoldTargetTokens ?? (overflowTarget > 0 ? Math.round(overflowTarget / 2) : 0), overflowTarget)), measuredFloor ?? 0), overflowTarget) + ? Math.min(Math.max(Math.max(AUTO_FOLD_TARGET_MIN, Math.min(configuredAutoFoldTarget ?? (overflowTarget > 0 ? Math.round(overflowTarget / 2) : 0), overflowTarget)), measuredFloor ?? 0), overflowTarget) : undefined; const growthArmed = autoFoldOn && autoFoldTarget !== undefined && autoFoldTarget > 0 && autoFoldTarget < overflowTarget; // narrowing form of growthFoldingArmed(config, overflowTarget, measuredFloor) — keep in sync (PR #2581 review) const compressionTarget = growthArmed ? autoFoldTarget : overflowTarget; + // #4543: an explicit autoFoldTargetTokens ≥ this route's overflow target clamps + // to it and leaves growth folding SILENTLY inert (noteAutoFoldIgnored only + // covers the disabled-chain no-op). Warn once per session per distinct route + // bar — logging only, no behavior change. + if (autoFoldOn && typeof configuredAutoFoldTarget === "number" && overflowTarget > 0 && configuredAutoFoldTarget >= overflowTarget + && session.metadata.autoFoldInertBarWarned !== overflowTarget) { + session.metadata.autoFoldInertBarWarned = overflowTarget; + log("warn", `[external-summary] auto-fold INERT on this route: autoFoldTargetTokens=${configuredAutoFoldTarget} is at or above this route's overflow target ${overflowTarget}; growth folding arms only while the target is below the overflow bar, so no pre-forward growth fold will run here — folding happens only at overflow. Set autoFoldTargetTokens below ${overflowTarget} (or use a wider-window route) to arm it (#4543).`); + } // A fresh session (id rotated, e.g. after a model switch) has // lastInputTokens = 0 while still carrying a full raw history; size the // trigger on the real post-fold payload too. outboundPayloadBreakdown is the diff --git a/tests/external-summary-autofold.test.ts b/tests/external-summary-autofold.test.ts index 85ce582b5f..194edd87df 100644 --- a/tests/external-summary-autofold.test.ts +++ b/tests/external-summary-autofold.test.ts @@ -9,6 +9,7 @@ import { startServer, type ProxyOptions } from "../src/server.ts"; import { defaultConfig } from "acp-kernel"; import { SessionStore, _setStoreForTest } from "../src/persist.ts"; import { _setForTest as setRegistryForTest } from "../src/registry.ts"; +import { setLogCapture } from "../src/logger.ts"; /** Anthropomorphic main upstream: records request bodies, answers SSE ok. */ function startMainUpstream(): Promise<{ server: http.Server; url: string; bodies: unknown[] }> { @@ -730,3 +731,114 @@ test("explicit autoFoldTargetTokens clamped to the window: classic nudges still const text = JSON.stringify(main.bodies.at(-1)); assert.ok(text.includes("Context breakdown:"), "classic nudge must fire when the explicit target clamps to the window"); }); + +test("explicit autoFoldTargetTokens above the route bar warns once that auto-fold is inert (#4543)", async () => { + // The operator trap: a configured target at or above the route's overflow + // bar clamps to it and silently disarms the pre-forward growth fold. The + // warn must fire exactly once per session per route bar and name both values. + // Target deliberately far ABOVE the route window: the env may floor the + // judge window upward (fallback floor for unproven models), so a value + // above every plausible bar keeps the inert condition deterministic. + const main = await startMainUpstream(); trackClose(main.server); + const sum = await startSummaryUpstream("ok"); trackClose(sum.server); + const server = await startServer({ + port: 0, + host: "127.0.0.1", + upstream: main.url, + routes: { [main.url]: { models: { "test-model": { context: 50_000 } } } }, + modelContextLimit: 50_000, + kernelConfig: defaultConfig(50_000, { preserveRecentMessages: 0, preserveRecentTokens: 0, compress: { minCompressRange: 100, maxSummaryLength: 20000, minSummaryLength: 50 } }), + compress: { + injectTool: true, + injectNudge: true, + externalSummary: { enabled: true, targets: ["sum/sm"], autoFold: true, autoFoldTargetTokens: 500_000 }, + }, + namedProviders: { sum: { baseUrl: sum.url, api: "openai", apiKeyEnv: "E2E_SUM_KEY", models: { sm: {} } } }, + promptCache: { routing: "auto" }, + sessionHeader: "x-acp-session", + log: true, + debug: false, + passthrough: false, + passthroughSource: null, + autoUpdate: false, + autoRestartOnUpdate: false, + updateTag: "latest", + advisoryCheck: false, + releaseNotesCheck: false, + compat: { roles: {} }, + streamErrorShape: "protocol", + mitm: { enabled: false, domains: [] }, + } as ProxyOptions); + trackClose(server); + await once(server, "listening"); + const port = (server.address() as AddressInfo).port; + process.env.E2E_SUM_KEY = "k"; + + const warns: string[] = []; + setLogCapture((level, msg) => { if (level === "warn") warns.push(msg); }); + try { + const first = await postTurn(port, main.url, "inert-bar", 2); + assert.equal(first.status, 200, "turn 1 forwards cleanly despite the inert config"); + let inertLines = warns.filter((m) => m.includes("auto-fold INERT")); + assert.equal(inertLines.length, 1, JSON.stringify(warns)); + assert.ok(inertLines[0].includes("autoFoldTargetTokens=500000"), inertLines[0]); + assert.ok(/overflow target \d+/.test(inertLines[0]), inertLines[0]); + assert.ok(inertLines[0].includes("#4543"), inertLines[0]); + + const second = await postTurn(port, main.url, "inert-bar", 2); + assert.equal(second.status, 200, "turn 2 forwards cleanly"); + inertLines = warns.filter((m) => m.includes("auto-fold INERT")); + assert.equal(inertLines.length, 1, `throttled to one warn per session per route bar: ${JSON.stringify(warns)}`); + } finally { + setLogCapture(null); + } +}); + +test("no inert warning while growth folding is armed (target below the window)", async () => { + // Negative arm of the same gate: an explicit target that stays below the + // overflow bar arms growth folding and must not produce the inert warning. + const main = await startMainUpstream(); trackClose(main.server); + const sum = await startSummaryUpstream("ok"); trackClose(sum.server); + const server = await startServer({ + port: 0, + host: "127.0.0.1", + upstream: main.url, + routes: { [main.url]: { models: { "test-model": { context: 50_000 } } } }, + modelContextLimit: 50_000, + kernelConfig: defaultConfig(50_000, { preserveRecentMessages: 0, preserveRecentTokens: 0, compress: { minCompressRange: 100, maxSummaryLength: 20000, minSummaryLength: 50 } }), + compress: { + injectTool: true, + injectNudge: true, + externalSummary: { enabled: true, targets: ["sum/sm"], autoFold: true, autoFoldTargetTokens: 8192 }, + }, + namedProviders: { sum: { baseUrl: sum.url, api: "openai", apiKeyEnv: "E2E_SUM_KEY", models: { sm: {} } } }, + promptCache: { routing: "auto" }, + sessionHeader: "x-acp-session", + log: true, + debug: false, + passthrough: false, + passthroughSource: null, + autoUpdate: false, + autoRestartOnUpdate: false, + updateTag: "latest", + advisoryCheck: false, + releaseNotesCheck: false, + compat: { roles: {} }, + streamErrorShape: "protocol", + mitm: { enabled: false, domains: [] }, + } as ProxyOptions); + trackClose(server); + await once(server, "listening"); + const port = (server.address() as AddressInfo).port; + process.env.E2E_SUM_KEY = "k"; + + const warns: string[] = []; + setLogCapture((level, msg) => { if (level === "warn") warns.push(msg); }); + try { + const turn = await postTurn(port, main.url, "armed-bar", 2); + assert.equal(turn.status, 200, "turn forwards cleanly with an armed target"); + assert.equal(warns.filter((m) => m.includes("auto-fold INERT")).length, 0, JSON.stringify(warns)); + } finally { + setLogCapture(null); + } +}); From 058cdc1a4c3c869171bd58ea6cab53d9486960d8 Mon Sep 17 00:00:00 2001 From: ci-check Date: Mon, 26 Oct 2026 03:52:59 +0800 Subject: [PATCH 2/2] docs(configuration): document per-route auto-fold arming caveat + CJK mitigation pointer (#4543) CONFIGURATION.md en+zh under compress.externalSummary/autoFold: state that the target clamps per-route and arms only while strictly below the overflow bar, that the one-time warning names both values, and how to set one global target for mixed-width routes; point CJK-heavy long-session operators at this rail as the documented mitigation for fold-loss amplification across mid-session model switches (#1921/#3301/#3849). --- CONFIGURATION.md | 2 +- CONFIGURATION.zh-CN.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 9e69ee04f7..e01b18ecd5 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -1282,7 +1282,7 @@ Up to 16 targets per chain are supported. Saving an enabled chain through the We Interaction with the budget: the achievable fold rate of a batch is bounded by how many calls fit in the pool (`concurrency`) and how long each may take (`targetTimeoutMs`) — the budget alone does not control the outcome. A saturated pool does not surface as a visible error: a batch still queued when its total deadline expires is discarded as `batch=deadline` with no attempts recorded (`attempts=[]`), and the fold pass stops there instead of queueing further rounds behind the congestion. For auto-fold this is treated as transient scheduler congestion, **not** a chain failure: no 10-minute backoff arms, and the next turn retries into the (hopefully drained) pool. If you see those lines while direct calls to your target succeed quickly, the pool — not the timeout — is the binding constraint. -Two optional knobs turn the chain into a **proxy-driven auto-folder** (`autoFold`): with `"autoFold": true` the proxy stops waiting for the model to call the compression tool at all — the same zero-model folding engine that guards the overflow window also folds the conversation down to `autoFoldTargetTokens` (default: half the model window) *before* forwarding, using the external chain and kernel-chosen ranges. The model never sees a nudge and never spends thinking tokens drafting compression plans. The knob rides whole-chain replace semantics like the rest of the block; it only takes effect while the chain itself is enabled — setting either knob on a disabled (or omitted-`enabled`) chain has no effect and is logged once as a warning rather than failing silently. `autoFoldTargetTokens` must be an integer in `[8192, 10000000]`. Failure is fail-open: if the chain errors at fold time, the request forwards as-is, a 10-minute backoff suppresses auto-folding, and classic advisory nudges return for that window. One exception (#2662): a zero-progress fold caused purely by queue drops — batches submitted but no summary call ever dispatched because the shared pool is saturated — does not arm the backoff, since that is scheduler congestion rather than a chain failure; auto-fold simply retries on the next turn. +Two optional knobs turn the chain into a **proxy-driven auto-folder** (`autoFold`): with `"autoFold": true` the proxy stops waiting for the model to call the compression tool at all — the same zero-model folding engine that guards the overflow window also folds the conversation down to `autoFoldTargetTokens` (default: half the model window) *before* forwarding, using the external chain and kernel-chosen ranges. The model never sees a nudge and never spends thinking tokens drafting compression plans. The knob rides whole-chain replace semantics like the rest of the block; it only takes effect while the chain itself is enabled — setting either knob on a disabled (or omitted-`enabled`) chain has no effect and is logged once as a warning rather than failing silently. `autoFoldTargetTokens` must be an integer in `[8192, 10000000]`. Failure is fail-open: if the chain errors at fold time, the request forwards as-is, a 10-minute backoff suppresses auto-folding, and classic advisory nudges return for that window. One exception (#2662): a zero-progress fold caused purely by queue drops — batches submitted but no summary call ever dispatched because the shared pool is saturated — does not arm the backoff, since that is scheduler congestion rather than a chain failure; auto-fold simply retries on the next turn. Per-route arming caveat: the target is clamped to each route's effective overflow bar (window minus any proven completion reservation), and growth folding arms only while the clamped target stays strictly below that bar — an explicit `autoFoldTargetTokens` at or above a route's bar therefore leaves auto-fold inert on that route (only overflow folds run). The proxy logs a one-time warning naming both values whenever that state is reached (#4543); if one global target must serve wide- and narrow-window routes together, set it below the narrowest route you want armed. Operators running CJK-heavy long sessions should also consider this rail as a mitigation for fold-loss amplification across mid-session model switches (#1921/#3301/#3849): with auto-fold armed, the pre-forward fold happens before a single-pass history re-send can push the payload past the window, instead of only after the first upstream refusal. #### Agent-reported providers (fallback layer) diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index 5b1947722a..90d3ab0531 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -1285,7 +1285,7 @@ URL 键通道(或带 `bind` 的命名条目)可以向上游发送**自己的 与 budget 的交互:一个批次能达到的折叠速率由池能容纳的并发数(`concurrency`)和每次调用的时限(`targetTimeoutMs`)共同决定 —— 单看 budget 并不能解释结果。池饱和不会表现为可见错误:批次还在排队就耗尽总时限的话,会被整体丢弃为 `batch=deadline` 且没有任何尝试记录(`attempts=[]`),折叠过程也会就地停止而不是继续排在拥塞后面。对 auto-fold 而言这被当作暂时的调度拥塞而**非**链路故障:不会触发下文所述的 10 分钟退避,下一个回合会在(有望已排空的)池子上重试。如果你看到这些日志行、而直接调用目标却很快成功,说明瓶颈是池而不是超时。 -两个可选旋钮可把这条链升级为**代理驱动的自动折叠器**(`autoFold`):`"autoFold": true` 后代理不再等模型调压缩工具 —— 原本只守溢出窗口的零模型折叠引擎同样会在转发前把对话折到 `autoFoldTargetTokens`(默认:模型窗口的一半)以下,范围由内核选定、摘要由外部链完成。主模型完全看不到 nudge,也不会把思考预算花在起草压缩方案上。该旋钮随整链替换语义生效,且只在链本身启用时才起作用——在链未启用(或省略 `enabled`)时设置任一旋钮均无效,并会记录一次警告而非静默失效;`autoFoldTargetTokens` 必须是 `[8192, 10000000]` 内的整数。失败时 fail-open:链在折叠时出错则照常转发请求,退避 10 分钟内暂停自动折叠并恢复经典 advisory nudge。一个例外(#2662):若零进展完全由队列丢弃造成——批次已提交但因共享池饱和、没有任何一次摘要调用真正派发——则不触发退避(那是调度拥塞而非链故障),auto-fold 在下一轮直接重试。 +两个可选旋钮可把这条链升级为**代理驱动的自动折叠器**(`autoFold`):`"autoFold": true` 后代理不再等模型调压缩工具 —— 原本只守溢出窗口的零模型折叠引擎同样会在转发前把对话折到 `autoFoldTargetTokens`(默认:模型窗口的一半)以下,范围由内核选定、摘要由外部链完成。主模型完全看不到 nudge,也不会把思考预算花在起草压缩方案上。该旋钮随整链替换语义生效,且只在链本身启用时才起作用——在链未启用(或省略 `enabled`)时设置任一旋钮均无效,并会记录一次警告而非静默失效;`autoFoldTargetTokens` 必须是 `[8192, 10000000]` 内的整数。失败时 fail-open:链在折叠时出错则照常转发请求,退避 10 分钟内暂停自动折叠并恢复经典 advisory nudge。一个例外(#2662):若零进展完全由队列丢弃造成——批次已提交但因共享池饱和、没有任何一次摘要调用真正派发——则不触发退避(那是调度拥塞而非链故障),auto-fold 在下一轮直接重试。按路由武装的注意项:目标值会被 clamp 到每条路由各自的有效溢出线(窗口减去已证实的完成量预留),且只有 clamp 后的目标严格低于该线时 growth folding 才武装——显式设置的 `autoFoldTargetTokens` 若 ≥ 某条路由的溢出线,auto-fold 在该路由上就是惰性的(只在 overflow 时折叠)。代理到达该状态时会记录一条一次性警告并写明两个数值(#4543);若同一个全局目标要同时服务宽窗口与窄窗口路由,请把它设到你想武装的最窄路由之下。运行以中文为主的长会话的运维还应把这条链作为「会话中途换模型引发的折叠损失放大」(#1921/#3301/#3849)的缓解手段:auto-fold 武装后,pre-forward 折叠发生在单轮历史重放把载荷推过窗口之前,而不是第一次上游拒绝之后。 #### Agent 上报的 providers(兜底层)