feat: per-provider/per-model overrides for ALL compress fields via nested compress.providers (issue #344)

[ranxianglei]

Model: Claude Sonnet 4.6

Summary

Every tunable compress field now supports a three-level cascade override — model > provider > global, field-by-field — via the nested compress.providers map (issue #344 follow-up; scope extended per maintainer request: "应该所有字段都需要三级别 而不是仅仅一个字段").

{
  "compress": {
    "nudgeGrowthTokens": 20000,           // global default
    "providers": {
      "anthropic": {                       // provider-level
        "nudgeGrowthTokens": 5000,
        "models": {
          "claude-sonnet-4-6": {           // model-level (wins per field)
            "minNudgeContextPercent": 30,
            "maxContextLimit": "20%"
          }
        }
      }
    }
  }
}

Overridable fields (23)

maxContextLimit, emergencyThresholdPercent, nudgeFrequency, iterationNudgeThreshold, toolOutputNudgeThreshold, nudgeGrowthTokens, minNudgeGrowthRatio, minNudgeGrowthFloor, minNudgeContextPercent, nudgeForce, protectedTools, showCompression, summaryBuffer, protectTags, protectUserMessages, maxSummaryLengthHard, minCompressRange, maxVisibleSegments, keepEmbedMaxChars, lastSegmentSoftBlock, preserveRecentMessages, preserveRecentTokens, preserveLastUserMessage.

Not overridable: permission (tool registration precedes model info), deprecated minContextLimit/modelMinLimits family (see #352), flat modelMaxLimits (legacy map, still honored), providers itself.

Semantics

• Resolution per field: model entry > provider entry > global. Unknown provider/model ids fall back up the cascade.
• maxContextLimit precedence chain: nested override > flat modelMaxLimits > global (enforced explicitly in resolveContextTokenLimit).
• providers maps deep-merge across the three config file layers per provider/model key (unlike flat maps' replace-inherit).
• Mechanism: applyCompressOverrides() builds the effective config once per turn (identity return, zero allocation, when nothing applies); injected at the two points where model info is known — nudge injection (inject.ts) and the compress tool (range.ts, after prepareSession).
• Exception: the system-prompt protected-tools listing always reflects the global value (prompt is built before model info exists).

Validation

• Per-field type table (OVERRIDE_FIELD_TYPES) covering every overridable field; unknown fields rejected at both levels; dcp.schema.json nested schema with additionalProperties: false at both levels.

Tests — 1062/1062 (typecheck ✓, build ✓)

• Resolver: all-field cascade precedence, identity swap, maxContextLimit excluded from blanket apply, nested-max beats flat map.
• Inject gates (§5.7 multi-turn + side-effect assertions): model-level maxContextLimit lowers the over-max band; provider-level nudgeGrowthTokens tightens the growth threshold; model-level 0 disables the floor.
• Includes reviewer commit 6576fcf (§5.7.1 production-config growth-cycle test with preserveRecentMessages > 0 + PR fix: preserve growth baseline when nothingToCompress #207 regression lock), merged conflict-free-keep-both.
• Mutation-verified M1–M5 (each mutation kills exactly the expected tests).

Docs

CONFIGURATION.md / CONFIGURATION.zh-CN.md: rewritten compress.providers section + new recipe "Per-model tuning of any compress field". Supersedes #345 (closed).

Stack

Includes #343 (merged). Merge this before #352 (deprecation annotations reference the same family).

[github-actions]

📦 Built Plugin Artifact

Branch: 2026-08-29_min-nudge-providers-models (694eb88)

Option A — Install from npm PR tag (recommended)

opencode plugin opencode-acp@pr-351 --global

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

Option B — Install from GitHub

opencode plugin "github:ranxianglei/opencode-acp#2026-08-29_min-nudge-providers-models" --global

Option C — Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf opencode-acp-pr351.tgz
cp -r package/dist ~/.cache/opencode/packages/opencode-acp@latest/node_modules/opencode-acp/dist

3. Restart opencode to pick up changes.

---

This comment is automatically updated on each push.

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] On it — reviewing PR #351 (branch 2026-08-29_min-nudge-providers-models). Checking #343 merge status, the diff, tests, and the mutation-verification claims. Will report findings here.

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] ## Review complete — PR #351 ✅ (2 findings fixed, branch updated to 6576fcf)

Claim verification (all confirmed against the code)

Check	Result
npm run typecheck	✅ clean
npm run test	✅ 1053/1053 on PR tip (1036 baseline + 17 new) → 1054/1054 after review fix
npm run build	✅ tsup ESM success
scripts/ci/check-pr.sh	✅ branch name, devlog REQ+WORKLOG, version unchanged (1.14.25)
Mutation M1 (skip model-level in resolveMinNudgeContextPercent)	✅ exactly 5 fail (cascade, 0-disable, clamp, multi-turn model floor, model-level-0 gate)
Mutation M2 (DEFAULT_MIN_NUDGE_CONTEXT_PERCENT 5→15)	✅ exactly 2 fail (#342 default-lock + #344 unset-everywhere)
Mutation M3 (mergeProviderOverrides deep-merge→replace)	✅ exactly 2 fail (no-wipe + cannot-clear)

Design checks all pass: cascade model > provider > global field-by-field (lib/messages/inject/utils.ts), 0 = explicit disable, unknown ids → global fallback, getModelInfo window resolution, per-provider/model deep merge across the 3 config layers (lib/config.ts mergeProviderOverrides/mergeModelOverrides), additionalProperties: false typo-safety in both lib/config-validation.ts and dcp.schema.json, docs complete in both languages.

Findings fixed (commit 6576fcf, pushed)

1. §5.7.1 gap (mandatory) — none of the 17 new tests used preserveRecentMessages > 0 (all used the buildConfig() default of 0, which disables the nothingToCompress path — exactly the scenario that triggered the fix: preserve growth baseline when nothingToCompress #207 baseline-reset bug). Added a 5-turn production-config test to tests/inject.test.ts (preserveRecentMessages: 2, model-level 30% floor on a 1M window): baseline 100K → 200K suppressed below floor → 320K fires → compress resets baseline to 200K → 400K fires again from the new baseline → fully-protected 2-message turn is silent with baseline and lastNudgeShownTokens preserved (fix: preserve growth baseline when nothingToCompress #207 regression lock). Mutation-verified: reintroducing the fix: preserve growth baseline when nothingToCompress #207 reset fails this test + the 5 pre-existing fix: preserve growth baseline when nothingToCompress #207 tests.
2. Unrelated .gitignore change (node_modules/ → node_modules) bundled into e14193c with unsubstantiated "symlink fix" rationale (no tracked symlink exists) — reverted to the f081b28 state.

Dual-agent review (§5.3 code + §5.6 tests)

Two independent agents reviewed the final diff (f081b28..6576fcf). Each raised one P1; both were false positives on verification:

• Code agent: "deepCloneConfig aliases compress.protectedTools" — it doesn't: lib/config.ts:504 and :532 already clone both commands.protectedTools and compress.protectedTools; every nested mutable field is covered.
• Test agent: "new feat: per-model growth-nudge floor (modelMinNudgeLimits) for mixed-context installs #344 test lacks lastPerMessageNudgeTokens assertions on turns 2/4" — it has them: tests/inject.test.ts:2448 (100K) and :2484 (200K); every turn asserts all three side-effect fields.

One P2 accepted as-is: as any in tests/config-providers.test.ts:135 — consistent with existing test conventions (tests are excluded from tsconfig typechecking; the legacy experimental.allowSubAgents shape is accepted by the loader at lib/config.ts:602).

Status

Branch 2026-08-29_min-nudge-providers-models @ 6576fcf pushed, working tree clean, 1054/1054 green. Ready for human merge — stacked on #343, so #343 needs to land first (per §5.1.1.2 I won't merge either).

[ranxianglei]

ework再review下看是否会引入回归问题

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] ## 回归专项复查（f081b28..6576fcf 逐行 diff 追踪）

结论：对现有用户（配置中无 compress.providers）零行为变化，不会引入回归。 依据如下：

1. 无 providers 时新旧代码逐点等价

代码点	#343 基线	本 PR	等价性
百分比解析（inject.ts:300）	config.compress?.minNudgeContextPercent ?? 5	resolveMinNudgeContextPercent(config, providerId, modelId) ?? DEFAULT_MIN_NUDGE_CONTEXT_PERCENT	providers 未设置/未知 id 时，resolver 返回值就是 config.compress?.minNudgeContextPercent（lib/messages/inject/utils.ts:274），默认值同为 5 → 输入完全相同
floor 计算（inject.ts:331）	Math.round((percent/100) * modelContextLimit)	resolveMinNudgeFloorTokens(...)，多了 Math.min(100, Math.max(0, percent)) 钳制	对 0–100 范围内的值钳制是 no-op → 逐位相同；窗口未知时两者都返回 undefined（growth-only）
provider/model 来源（inject.ts:90）	getModelInfo 已存在（#343 引入）	未改动	无新增每轮开销；无 model 信息时返回 undefined → 回落全局，与基线一致
配置合并（config.ts:417-418）	无此字段	mergeProviderOverrides(undefined, undefined) → undefined	合并后配置形状不变（不会凭空多出 providers: {}）；{} 也不会抹掉浅层 providers
持久化状态	—	本 PR 未触碰 lib/state/ 任何文件	无状态格式变化、无迁移风险

2. 验证/告警面

• 全局 minNudgeContextPercent 在基线和 HEAD 都没有范围校验（validatePercentField 只作用于新增的 provider/model 级字段）→ 现有配置不会新增任何告警。
• 校验本身是 warning-only（toast，不阻断加载，lib/config.ts:151-194）。
• getConfigKeyPaths 的 skip 只针对 compress.providers 本身；拼错成 compress.provider 仍会触发 unknown-key 告警（typo 安全）。

3. 仅有的两处边界差异（都只影响非法配置，且方向更合理）

1. 全局 percent 超出 0–100（如手写了 150，该字段两版都不校验）：旧代码 floor = 150% 窗口（实际永远打不开）→ 新代码钳到 100%（窗口满时打开）。负值两版行为一致（floor 恒开）。
2. 理论情况：若用户旧配置里已有 compress.providers 键且是别的项目的结构（如从 billion-context-pi 复制），现在会收到一条非阻断的结构告警。

4. 测试证据

• 1054/1054 全绿，其中 1036 个基线测试全部跑过新代码路径（含 fix: gate T1 growth nudges on minContextLimit (issue #342) #343 的全局 floor 测试，现在经由新 resolver 执行）。
• M2 变异（默认 5→15）精确失败 2 个测试，证明默认回落路径有测试覆盖。

总评：可安全合并（仍需先合 #343；按 §5.1.1.2 合并操作由人工执行）。