From ffbcd2091386b23abf68bd2395074ccbaac22427 Mon Sep 17 00:00:00 2001 From: awork Date: Sun, 18 Oct 2026 17:06:48 +0800 Subject: [PATCH 1/5] fix: warn when compress-block keys sit inert on a provider route root (#3675) --- src/config.ts | 24 ++++++++++ tests/named-provider-bind.test.ts | 75 +++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+) diff --git a/src/config.ts b/src/config.ts index 08099520d4..3e1c04402f 100644 --- a/src/config.ts +++ b/src/config.ts @@ -943,6 +943,26 @@ function warnInertRoutingFields(key: string, obj: Record | null ); } +/** #3675: compress-block keys written on the ROUTE ROOT (URL lane or named + * entry) are silently dropped by parseRouteEntry — the same silent-inert + * class as the #1469 routing fields, one level down. Recognition is + * COMPRESS_SETTING_FIELDS (defined below; kept in sync with + * parseCompressSettings): every member is inert at a route root, and none of + * them may be added to parseRouteEntry's whitelist while this warning exists. + * Dialing recipes are skipped — their own parser rejects unknown root fields + * loudly (parseNamedProviderRecipe throws → chain disabled with a warning), + * so a second signal here would only add noise. */ +function warnCompressOnlyFieldsAtRouteRoot(key: string, obj: Record | null): void { + if (!obj) return; + if (obj.baseUrl !== undefined || obj.api !== undefined) return; + const misplaced = Object.keys(obj).filter((f) => obj[f] !== undefined && COMPRESS_SETTING_FIELDS.has(f)); + if (misplaced.length === 0) return; + warnNamedProviderOnce( + `route-root-compress:${key}:${misplaced.join(",")}`, + `providers."${key}" carries compress-block keys [${misplaced.join(", ")}] at the route root — they are inert there (move them under providers."${key}".compress to apply)`, + ); +} + /** True when the providers-map key is itself a URL lane (http/https/mitm * scheme — mitm:// is the README-documented lookup key for MITM traffic). * Anything else is a NAMED key (provider id): routing-inert on its own, @@ -1127,6 +1147,10 @@ export function loadRoutes(env: NodeJS.ProcessEnv = process.env): ProviderRoutes if (!route) return; const obj = value && typeof value === "object" && !Array.isArray(value) ? value as Record : null; const urlLike = isUrlLikeKey(key); + // Before the bind branch on purpose: these keys are inert even on a + // validly bound alias — parseRouteEntry never parses them, so the + // fold onto the target lane cannot carry them. + warnCompressOnlyFieldsAtRouteRoot(key, obj); if (obj && "bind" in obj) { const bind = obj.bind; if (typeof bind !== "string") { diff --git a/tests/named-provider-bind.test.ts b/tests/named-provider-bind.test.ts index a52f49da81..3b3838a595 100644 --- a/tests/named-provider-bind.test.ts +++ b/tests/named-provider-bind.test.ts @@ -234,6 +234,81 @@ test("web config API round-trips named entries verbatim (no silent drop)", async assert.deepEqual(loadRoutes()["https://api.anthropic.com"]?.compress, { maxContextLimitPct: 0.75 }); }); +test("compress-block keys at a URL route root warn instead of sitting silently (#3675)", (t) => { + const warnings = captureWarnings(t); + withConfigFile(t, { + "https://cap.example": { + modelContextLimit: 1000000, + outputHeadroomMaxPct: 0.15, + models: { m1: { context: 200000 } }, + }, + }); + const routes = loadRoutes(); + assert.deepEqual(Object.keys(routes), ["https://cap.example"]); + assert.equal(routes["https://cap.example"].models?.m1?.context, 200000); + assert.equal(routes["https://cap.example"].compress, undefined); + assert.equal(warnings.length, 1); + for (const needle of ['"https://cap.example"', "modelContextLimit", "outputHeadroomMaxPct", '.compress']) { + assert.ok(warnings[0].includes(needle), `warning should mention ${needle}: ${warnings[0]}`); + } +}); + +test("bound alias: compress-block keys at its root stay inert through the fold and warn (#3675)", (t) => { + const warnings = captureWarnings(t); + withConfigFile(t, { + capBridge: { + bind: "https://cap-bound.example", + modelContextLimit: 500000, + nudgeGrowthTokens: 77777, + compress: { maxContextLimitPct: 0.7 }, + }, + }); + const laneRaw = loadRoutes()["https://cap-bound.example"] as Record | undefined; + assert.ok(laneRaw); + assert.equal((laneRaw.compress as Record | undefined)?.maxContextLimitPct, 0.7); + assert.equal(laneRaw.modelContextLimit, undefined); + assert.equal(laneRaw.nudgeGrowthTokens, undefined); + assert.equal(warnings.length, 1); + for (const needle of ['"capBridge"', "modelContextLimit", "nudgeGrowthTokens"]) { + assert.ok(warnings[0].includes(needle), `warning should mention ${needle}: ${warnings[0]}`); + } +}); + +test("named entry whose only fields are compress-block keys: previously zero warnings, now one (#3675)", (t) => { + const warnings = captureWarnings(t); + withConfigFile(t, { + capLonely: { outputHeadroomMaxPct: 0.2 }, + }); + const routes = loadRoutes(); + assert.ok("capLonely" in routes); + assert.equal(warnings.length, 1); + assert.ok(warnings[0].includes('"capLonely"') && warnings[0].includes("outputHeadroomMaxPct"), warnings[0]); +}); + +test("dialing recipes keep their own loud rejection — no duplicate route-root warning (#3675)", (t) => { + const warnings = captureWarnings(t); + withConfigFile(t, { + glmLane: { + baseUrl: "https://glm.example", + api: "openai", + apiKeyEnv: "GLM_KEY", + models: { g1: { contextWindow: 100000 } }, + modelContextLimit: 1000000, + }, + }); + loadRoutes(); + assert.deepEqual(warnings, []); +}); + +test("route-root compress-key warning fires once per signature across reloads (#3675)", (t) => { + const warnings = captureWarnings(t); + withConfigFile(t, { "https://cap-reload.example": { modelContextLimit: 250000 } }); + loadRoutes(); + loadRoutes(); + loadRoutes(); + assert.equal(warnings.filter((w) => w.includes('"https://cap-reload.example"')).length, 1); +}); + test("web config API still rejects legacy, invalid-proxy, and non-object entries", async (t) => { captureWarnings(t); withConfigFile(t, {}); From 7e36cb94bfdbbb228f445e9d2ef40f895e4109de Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Tue, 20 Oct 2026 03:46:27 +0800 Subject: [PATCH 2/5] fix: anchor config-surface guard's Set extraction on the initializer (#3680) The route-root warning added in this PR references COMPRESS_SETTING_FIELDS before its declaration. scripts/config-surface-guard.mjs located the field list at the FIRST mention of the name and stopped at the first closing bracket, so it scanned the new warning's template literal and extracted one empty string -> phantom leaf 'compress., ' -> config-surface-guard job red + tests/config-surface-guard.test.ts red in every shard carrying it. extractStringSet now anchors on 'const = new Set([' and matches the closing bracket string-aware. Regression test pins the use-before-declaration + bracketed-template shape. --- scripts/config-surface-guard.mjs | 39 ++++++++++++++++++++++-------- tests/config-surface-guard.test.ts | 14 +++++++++++ 2 files changed, 43 insertions(+), 10 deletions(-) diff --git a/scripts/config-surface-guard.mjs b/scripts/config-surface-guard.mjs index 1865dfcafe..96ca9d18b4 100644 --- a/scripts/config-surface-guard.mjs +++ b/scripts/config-surface-guard.mjs @@ -133,17 +133,36 @@ function namedTypeBodies(src) { } // Extract the quoted identifiers of `const = new Set([ ... ]);`. +// Anchored on the initializer, NOT the first mention of the name: a +// use-before-declaration earlier in the file would otherwise hijack the scan, +// and the naive first-`]` stop then lands inside whatever bracketed text +// follows (e.g. a template literal's `[${…}]`), producing phantom members +// (#3680 review: the route-root warning call site preceded the declaration +// and the extraction collapsed to one empty string). export function extractStringSet(src, varName) { - const i = src.indexOf(varName); - if (i < 0) throw new Error(varName + " not found"); - const open = src.indexOf("[", i); - const close = src.indexOf("]", open); - const inner = src.slice(open + 1, close); - const out = []; - const re = /["']([^"']+)["']/g; - let m; - while ((m = re.exec(inner))) out.push(m[1]); - return out; + const m = new RegExp(`(?:const|let|var)\\s+${varName}\\s*=\\s*new\\s+Set\\s*\\(\\s*\\[`).exec(src); + if (!m) throw new Error(varName + " not found"); + const open = m.index + m[0].length - 1; + let depth = 0; + let inStr = null; + for (let i = open; i < src.length; i++) { + const c = src[i]; + if (inStr) { if (c === inStr && src[i - 1] !== "\\") inStr = null; continue; } + if (c === "'" || c === '"') { inStr = c; continue; } + if (c === "[") depth++; + else if (c === "]") { + depth--; + if (depth === 0) { + const inner = src.slice(open + 1, i); + const out = []; + const re = /["']([^"']+)["']/g; + let mm; + while ((mm = re.exec(inner))) out.push(mm[1]); + return out; + } + } + } + throw new Error("unbalanced Set literal for " + varName); } // ---- config-file leaf extraction -------------------------------------------- diff --git a/tests/config-surface-guard.test.ts b/tests/config-surface-guard.test.ts index 3abc2ef6c2..8e0d31e1eb 100644 --- a/tests/config-surface-guard.test.ts +++ b/tests/config-surface-guard.test.ts @@ -7,6 +7,7 @@ import { stripComments, extractConfigLeaves, extractCliFlags, + extractStringSet, runChecks, } from "../scripts/config-surface-guard.mjs"; @@ -70,6 +71,19 @@ test("a planted undocumented CLI flag is caught", () => { assert.ok(!missing.includes("--port"), "documented flag must not be flagged"); }); +test("extractStringSet anchors on the initializer, not an earlier mention (#3680)", () => { + // The route-root warning call site preceded the COMPRESS_SETTING_FIELDS + // declaration, and its message carries `[${…}]` — the old first-mention + + // first-`]` scan collapsed to one empty string there. + const src = + "function warnMisplaced(key: string): void {\n" + + ' const misplaced = Object.keys(key).filter((f) => f !== undefined && COMPRESS_SETTING_FIELDS.has(f));\n' + + ' log(`carries compress-block keys [${misplaced.join(", ")}] at the route root`);\n' + + "}\n" + + 'const COMPRESS_SETTING_FIELDS = new Set([ "tiers", "modelContextLimit" ]);\n'; + assert.deepEqual(extractStringSet(src, "COMPRESS_SETTING_FIELDS"), ["tiers", "modelContextLimit"]); +}); + test("stripComments keeps string contents, drops comments", () => { const out = stripComments('let a = "// not a comment"; // real comment\n/* block */ let b = "x";'); assert.ok(out.includes('"// not a comment"'), "string content must survive"); From 66219d4e2f8fdaaf9232c1b5a5fab5bd6edb1290 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Tue, 20 Oct 2026 06:02:05 +0800 Subject: [PATCH 3/5] fix: recognize externalSummary in route-root compress warning (#3876) --- src/config.ts | 2 +- tests/named-provider-bind.test.ts | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/src/config.ts b/src/config.ts index 3e1c04402f..b7fbc75238 100644 --- a/src/config.ts +++ b/src/config.ts @@ -2027,7 +2027,7 @@ const COMPRESS_SETTING_FIELDS = new Set([ "visibilityMarkers", "rules", "injectTool", "injectNudge", "acknowledgePromptsRisk", "absorb", "ccr", "search", "prompts", "promptPack", "reasoningGuard", "outputSteering", "priceProfile", - "reconcile", "streamSummary", + "reconcile", "streamSummary", "externalSummary", ]); // Deduped per unique key set per process (same pattern as diff --git a/tests/named-provider-bind.test.ts b/tests/named-provider-bind.test.ts index 3b3838a595..fd4f37f267 100644 --- a/tests/named-provider-bind.test.ts +++ b/tests/named-provider-bind.test.ts @@ -309,6 +309,29 @@ test("route-root compress-key warning fires once per signature across reloads (# assert.equal(warnings.filter((w) => w.includes('"https://cap-reload.example"')).length, 1); }); +test("route-root externalSummary warns like every other compress-block key (#3876)", (t) => { + const warnings = captureWarnings(t); + withConfigFile(t, { + capSum: { externalSummary: { enabled: true, targets: ["glm/glm-4.9-flash"] } }, + }); + const routes = loadRoutes(); + assert.ok("capSum" in routes); + assert.equal(routes["capSum"].compress, undefined, "the inert root field must not leak into a compress block"); + assert.equal(warnings.length, 1); + for (const needle of ['"capSum"', "externalSummary", ".compress"]) { + assert.ok(warnings[0].includes(needle), `warning should mention ${needle}: ${warnings[0]}`); + } +}); + +test("externalSummary under compress (the right place) produces no route-root complaint (#3876)", (t) => { + const warnings = captureWarnings(t); + withConfigFile(t, { + capSumOk: { compress: { externalSummary: { enabled: false } } }, + }); + loadRoutes(); + assert.ok(!warnings.some((w) => w.includes("externalSummary")), `no route-root complaint expected for a correctly placed chain: ${warnings.join(" | ")}`); +}); + test("web config API still rejects legacy, invalid-proxy, and non-object entries", async (t) => { captureWarnings(t); withConfigFile(t, {}); From 4c01c3948615112bb51bdcedac77ef5ec8246d1c Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Tue, 20 Oct 2026 06:26:16 +0800 Subject: [PATCH 4/5] docs: seed compress.externalSummary + regenerate config docs (#3876) Commit 66219d4e added externalSummary to COMPRESS_SETTING_FIELDS on this branch; the config-surface guard then fails HERE (leaf compress.externalSummary lacks a seed entry) until #3880's seed lands on master - i.e. merge order mattered: merging this PR first would have put a NEW red on master's own config-surface-guard. This mirrors #3880's exact seed entry (byte-identical, so either PR may merge first and the duplicate is a clean no-op) plus the generator output for it (5 added lines, 0 removed), making this branch self-contained green for both config-surface-guard and docs-sync once the pre-existing master static-gate red (#3870/#3871) clears. From 09f45fc315663ae517b8576dff43a560007531ff Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Tue, 20 Oct 2026 06:26:59 +0800 Subject: [PATCH 5/5] docs: seed compress.externalSummary + regenerate config docs (#3876) Commit 66219d4e added externalSummary to COMPRESS_SETTING_FIELDS on this branch; the config-surface guard then fails HERE (leaf compress.externalSummary lacks a seed entry) until #3880's seed lands on master - i.e. merge order mattered: merging this PR first would have put a NEW red on master's own config-surface-guard. This mirrors #3880's exact seed entry (byte-identical, so either PR may merge first and the duplicate is a clean no-op) plus the generator output for it (5 added lines, 0 removed), making this branch self-contained green for both config-surface-guard and docs-sync once the pre-existing master static-gate red (#3870/#3871) clears. --- CONFIGURATION.md | 1 + CONFIGURATION.zh-CN.md | 1 + website/config-reference/compress.yaml | 10 ++++++++++ website/docs/index.html | 1 + website/main.js | 2 ++ 5 files changed, 15 insertions(+) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index e91e6d2da7..a10ec8bce9 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -262,6 +262,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed | `compress.reasoningGuard` | object | off | — | Auto-repair of reasoning-lattice truncation on gpt-5.x/6.x (up to 3 continue-nudge rounds). | | `compress.outputSteering` | object { enabled?, verbosityLevel?, effortRouting? } | enabled false · verbosityLevel 2 | — | Appends a conciseness directive to the system-prompt tail; clamps mechanical continuation requests. | | `compress.priceProfile` | { w?, r?, q? } | unset (registry, kernel fallback {1, 0.1, 4}) | — | w/r/q ratios normalized to the input price (write/cache-read/output); report-only — never affects triggers or the wire. | +| `compress.externalSummary` | object | opt-in (disabled) | — | Sends compression summaries to separately configured models referenced from the providers table; whole-chain replace semantics at all three compress levels. | | `compress.acknowledgePromptsRisk` | boolean | false | — | Must be true before custom prompts take effect. | | `compress.absorb.enabled` | boolean | false | — | Enable the absorb distillation block. | | `compress.absorb.minToolTokens` | number | 1000 | — | Minimum estimated token size of a tool result eligible for absorption. | diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index f45422c0ca..835f182fd4 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -262,6 +262,7 @@ | `compress.reasoningGuard` | object | off | — | gpt-5.x/6.x 推理格截断自动修复(最多 3 轮继续提示)。 | | `compress.outputSteering` | object { enabled?, verbosityLevel?, effortRouting? } | enabled false · verbosityLevel 2 | — | 向系统提示词尾部附加简洁度指令;只收紧机械延续请求。 | | `compress.priceProfile` | { w?, r?, q? } | unset (registry, kernel fallback {1, 0.1, 4}) | — | w/r/q 相对输入价的比率(写入/缓存读/输出);仅供报告,不影响触发条件或线上行为。 | +| `compress.externalSummary` | object | opt-in (disabled) | — | 把压缩摘要交给 providers 表引用的独立配置模型;三级 compress 均为整链替换语义。 | | `compress.acknowledgePromptsRisk` | boolean | false | — | 必须先置 true,自定义 prompts 才会生效。 | | `compress.absorb.enabled` | boolean | false | — | 启用 absorb 蒸馏块。 | | `compress.absorb.minToolTokens` | number | 1000 | — | 可被吸收的工具结果的最小估算 token 大小。 | diff --git a/website/config-reference/compress.yaml b/website/config-reference/compress.yaml index 87b4db99c0..e3013b34d2 100644 --- a/website/config-reference/compress.yaml +++ b/website/config-reference/compress.yaml @@ -335,6 +335,16 @@ entries: desc_zh: "w/r/q 相对输入价的比率(写入/缓存读/输出);仅供报告,不影响触发条件或线上行为。" site_en: "priceProfile — w / r / q ratios normalized to the input price (write / cache-read / output); unset ⇒ models.dev $/Mtok registry rows, kernel fallback {1, 0.1, 4}. Report-only — never affects triggers or the wire." site_zh: "priceProfile —— w / r / q 相对输入价的比率(写入/缓存读/输出);未设置 ⇒ 取 models.dev $/Mtok 注册表行,内核兜底 {1, 0.1, 4}。仅供报告,不影响触发条件或线上行为。" + - key: compress.externalSummary + type: object + default: "opt-in (disabled)" + group: compress + id: co.es + render: obj-item + desc_en: "Sends compression summaries to separately configured models referenced from the providers table; whole-chain replace semantics at all three compress levels." + desc_zh: "把压缩摘要交给 providers 表引用的独立配置模型;三级 compress 均为整链替换语义。" + site_en: "externalSummary — optional chain of external summary models, each target a \"provider/model\" reference into the providers table; disabled unless enabled is true, targets tried in order with fall-through (enabled, targets, budget {totalTimeoutMs, targetTimeoutMs, maxSummaryBytes}, concurrency, autoFold, autoFoldTargetTokens). Whole-chain replace semantics at all three compress levels." + site_zh: "externalSummary —— 可选的外部摘要模型链,每个目标为指向 providers 表的 \"provider/model\" 引用;enabled 为 true 才启用,目标按顺序尝试、失败落到下一个(enabled, targets, budget {totalTimeoutMs, targetTimeoutMs, maxSummaryBytes}, concurrency, autoFold, autoFoldTargetTokens)。三级 compress 均为整链替换语义。" - key: compress.acknowledgePromptsRisk type: boolean default: "false" diff --git a/website/docs/index.html b/website/docs/index.html index 5e50a4492a..918196652a 100644 --- a/website/docs/index.html +++ b/website/docs/index.html @@ -216,6 +216,7 @@

compress — every knob

  • reasoningGuard — auto-repair of reasoning-lattice truncation on gpt-5.x/6.x (≤3 continue-nudge rounds, marker "Continue thinking...") (enabled, maxContinue, maxTierN, markerText, base, offset, debugLog).
  • outputSteering — { enabled? false, verbosityLevel? 2 (0–4), effortRouting? }: appends a conciseness directive to the system-prompt tail; clamps mechanical continuation requests.
  • priceProfile — w / r / q ratios normalized to the input price (write / cache-read / output); unset ⇒ models.dev $/Mtok registry rows, kernel fallback {1, 0.1, 4}. Report-only — never affects triggers or the wire.
  • +
  • externalSummary — optional chain of external summary models, each target a "provider/model" reference into the providers table; disabled unless enabled is true, targets tried in order with fall-through (enabled, targets, budget {totalTimeoutMs, targetTimeoutMs, maxSummaryBytes}, concurrency, autoFold, autoFoldTargetTokens). Whole-chain replace semantics at all three compress levels.
  • acknowledgePromptsRisk — must be true before custom prompts take effect.
  • diff --git a/website/main.js b/website/main.js index bf7b1cc7c8..6095abc92b 100644 --- a/website/main.js +++ b/website/main.js @@ -94,6 +94,7 @@ "co.rg": "reasoningGuard — auto-repair of reasoning-lattice truncation on gpt-5.x/6.x (≤3 continue-nudge rounds, marker \"Continue thinking...\") (enabled, maxContinue, maxTierN, markerText, base, offset, debugLog).", "co.os": "outputSteering — { enabled? false, verbosityLevel? 2 (0–4), effortRouting? }: appends a conciseness directive to the system-prompt tail; clamps mechanical continuation requests.", "co.pp": "priceProfile — w / r / q ratios normalized to the input price (write / cache-read / output); unset ⇒ models.dev $/Mtok registry rows, kernel fallback {1, 0.1, 4}. Report-only — never affects triggers or the wire.", + "co.es": "externalSummary — optional chain of external summary models, each target a \"provider/model\" reference into the providers table; disabled unless enabled is true, targets tried in order with fall-through (enabled, targets, budget {totalTimeoutMs, targetTimeoutMs, maxSummaryBytes}, concurrency, autoFold, autoFoldTargetTokens). Whole-chain replace semantics at all three compress levels.", "co.apr": "acknowledgePromptsRisk — must be true before custom prompts take effect.", "cr.models": "Record of model name → {context?, output?, compress?, benefit?}: declares each model's context window, output ceiling, and per-model compression overrides (benefit marks free-quota billing). Not a traffic filter.", "cr.proxy": "Per-route outbound proxy URL; empty string = explicitly direct.", @@ -336,6 +337,7 @@ "co.rg": "reasoningGuard —— gpt-5.x/6.x 推理格截断自动修复(≤3 轮继续提示,标记 \"Continue thinking...\")(enabled, maxContinue, maxTierN, markerText, base, offset, debugLog)。", "co.os": "outputSteering —— { enabled? false, verbosityLevel? 2 (0–4), effortRouting? }:向系统提示词尾部附加简洁度指令;只收紧机械延续请求。", "co.pp": "priceProfile —— w / r / q 相对输入价的比率(写入/缓存读/输出);未设置 ⇒ 取 models.dev $/Mtok 注册表行,内核兜底 {1, 0.1, 4}。仅供报告,不影响触发条件或线上行为。", + "co.es": "externalSummary —— 可选的外部摘要模型链,每个目标为指向 providers 表的 \"provider/model\" 引用;enabled 为 true 才启用,目标按顺序尝试、失败落到下一个(enabled, targets, budget {totalTimeoutMs, targetTimeoutMs, maxSummaryBytes}, concurrency, autoFold, autoFoldTargetTokens)。三级 compress 均为整链替换语义。", "co.apr": "acknowledgePromptsRisk —— 必须先置 true,自定义 prompts 才会生效。", "cr.models": "模型名 → {context?, output?, compress?, benefit?} 的记录:声明每个模型的上下文窗口、输出上限与逐模型压缩覆盖(benefit 标记免费额度计费)。不是流量过滤器。", "cr.proxy": "本路由出站代理地址;空字符串 = 显式直连。",