fix #648: add hostUsageCredit switch to opt out of #408 host-usage backfill

[ranxianglei]

What

Plain proxy clients (ZCode on the anthropic wire — base-url → proxy, no x-bili-plugin header, no special UA) fell through every #408 backfill exemption (pi/omp by pluginAgent, codex by UA in the in-flight #647) and got the full uncompressed-baseline backfill armed. Their UI then showed a cumulative, drifting baseline (real folded value + per-compression backfill) instead of the actually-forwarded context: it overstates real pressure, and the per-round est drift makes it non-monotonic on pure-append turns.

Add a hostUsageCredit config option (auto | off, default auto = current behavior). off disables the #408 backfill entirely so the usage reported to the host is the actually-forwarded (folded) request, matching [acp-usage] input=.

Changes

• src/config.ts: hostUsageCredit: "auto" | "off" on ProxyOptions + FileConfig, parseHostUsageCredit(), wired in loadOptions from BILI_HOST_USAGE_CREDIT env / hostUsageCredit file key.
• src/server.ts: armHostUsageCredit() takes the mode and returns early on "off" (before the pi/omp pluginAgent check); all three call sites (prepareAnthropic/prepareOpenai/prepareResponses) pass opts.hostUsageCredit.
• tests/host-usage-backfill.test.ts: two anthropic-wire regression tests with a real kernel fold (relay emits a compress tool_use) — off reports the folded request's own usage (no backfill), and the auto control still gets the 代理压缩不上报改写量,宿主上下文会计塌缩至 ~0(omps recordAnchoredHistoryRewrite 零调用);且持久化 lastInputTokens 恢复无钳制,旧版负值升级后复活 #408 backfill.
• CONFIGURATION.md: document BILI_HOST_USAGE_CREDIT.

Why a switch (not a hard exemption)

The #408 backfill exists to keep a host's native auto-compact alive by showing the uncompressed baseline. Whether that helps or hurts depends on the host: pi/omp cancel it (exempted), codex keys off total_tokens which the backfill never touches (exempted in #647). For plain proxy clients like ZCode the value is host-specific and not knowable from the proxy — so an explicit switch (the issue's recommended primary mechanism) is the safe default rather than guessing. auto keeps today's behavior for everyone; ZCode users set hostUsageCredit: "off" (or BILI_HOST_USAGE_CREDIT=off) to get the actually-forwarded value.

Pre-flight

• npm run typecheck — clean
• npm test — 1241/1242 pass; the single failure (launcher.test.ts resolveClientCommand: codex/claude resolve to themselves) is a pre-existing environment issue (this box has codex at /usr/bin/codex) and fails identically on the base commit 5836f78 — unrelated to this change. All 23 host-usage-backfill tests pass, including the 2 new ones and the existing pi plugin 模式宿主 usage 回填未压缩基线:footer 显示 302.7%/1M 与实际请求(折叠后 ~57K)不符 #590/omp 插件会话原生压缩被扩展全部取消后仍收 #408 usage 回填: omp footer 只增不减 (205%/1M) #623 pi/omp tests.
• npm run build — success

Fixes #648

[github-actions]

📦 Built Package Artifact

Branch: 2026-09-08_zcode-host-usage-credit (6fba944)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-649

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

Option B — Download artifact

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

tar xzf billion-context-pr649.tgz
npm install -g package

---

This comment is automatically updated on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #649 审核完成 ✅

结论:技术正确、预检通过、无重复;按当前 auto 默认可直接合并。 我已补上缺失的 CHANGELOG 条目(见下)。

审核(在 PR head 上逐项重验)

1. 代码正确性

• parseHostUsageCredit(src/config.ts):仅精确匹配 "off" → off,其余(typo/大写/空串)一律 auto —— 与既有 parseUpstreamProxyMode 的严格匹配风格一致;loadOptions 接线 env.BILI_HOST_USAGE_CREDIT ?? fileConfig.hostUsageCredit(env 优先)正确。
• armHostUsageCredit(src/server.ts:1822):先 hostCreditTokens = 0,再 if (hostUsageCredit === "off") return;(在 pi/omp pluginAgent 检查之前)→ off 彻底关闭回填。三个调用点(prepareAnthropic:1983 / prepareOpenai:2236 / prepareResponses:2490)全部传入 opts.hostUsageCredit。
• 消费侧(src/server.ts:3880 + src/loop/core.ts:182):credit = hostCreditTokens ?? 0,off 时恒 0 → backfillHostUsage 不触发 → 回报宿主 usage = 实际转发(折叠)请求 = [acp-usage] input=。与声明一致。
• 两种压缩模式都覆盖:改动只影响"回报宿主的 usage",不碰 wire 消息重建。plugin 模式(pi/omp)本就被 pluginAgent 检查豁免,off 在那里是 no-op;proxy 模式 off 关闭回填。无 [Bug] ACP: ≥2 compressed blocks render as multiple system messages → SGLang (vLLM-compatible) upstreams return 400 #377 类单模式回归。

2. 预检(我在 PR head 重跑)

• npm run typecheck — 干净
• npm test — 1241/1242;唯一失败 launcher.test.ts 的 resolveClientCommand: codex/claude resolve to themselves 已确认在基线 5836f78 上同样失败(此机 codex 在 /usr/bin/codex),与本改动无关
• npm run build — 成功
• host-usage-backfill 全 23 条通过(含 2 条新增 ZCode 宿主 usage 回填未压缩基线:压缩后上下文显示成累加值,非实际转发量(v0.1.88 起;#645 的 ZCode 面) #648 + ZCode 宿主 usage 回填未压缩基线:压缩后上下文显示成累加值,非实际转发量(v0.1.88 起;#645 的 ZCode 面) #648 control,及既有 pi plugin 模式宿主 usage 回填未压缩基线:footer 显示 302.7%/1M 与实际请求(折叠后 ~57K)不符 #590/omp 插件会话原生压缩被扩展全部取消后仍收 #408 usage 回填: omp footer 只增不减 (205%/1M) #623)
• 版本:base 与 head 均 0.1.95,未改 version ✓(本地 master 停在 0.1.92 是 stale,真实 origin/master 即 base 5836f78)

3. 重复判定 — 与在飞的 #647(codex UA 豁免,fix #645)互补而非重复:#647 按 UA 豁免 codex(其 total_tokens 不被回填触碰),#649 是通用配置开关覆盖 ZCode 等无稳定 UA/无插件头的普通代理客户端,语义正交。⚠️ 注意:两者都改 armHostUsageCredit(server.ts)+ config.ts + host-usage-backfill.test.ts + CONFIGURATION.md → 合并顺序决定谁需 rebase(先合的干净,后合的需 rebase),非本 PR 正确性问题。

待你拍板的一点(我给出明确建议)

建议:保持 auto 默认(即当前实现),不要翻 off。 理由:

1. 向后兼容 —— 不改变任何既有宿主(pi/omp/codex/其他普通代理)行为;
2. 代理压缩不上报改写量,宿主上下文会计塌缩至 ~0(omps recordAnchoredHistoryRewrite 零调用);且持久化 lastInputTokens 恢复无钳制,旧版负值升级后复活 #408 回填的初衷是让宿主原生 auto-compact 看到未压缩基线而保持存活,对"确实依赖原生压缩"的普通代理客户端有价值,一刀切翻 off 会误伤;
3. ZCode 用户显式 hostUsageCredit: "off" 即可拿到实收值,完全满足 ZCode 宿主 usage 回填未压缩基线:压缩后上下文显示成累加值,非实际转发量(v0.1.88 起;#645 的 ZCode 面) #648 验收;
4. 若日后证据表明更多普通代理客户端需要 off,翻默认只是一行 follow-up。

你定。若拍板保持 auto,本 PR 现状即可合并。

小项

• CHANGELOG 缺失(已补):本仓惯例是每个 feature/fix 在 CHANGELOG.md [Unreleased] 下加一条(lenient compress-arg parsing: salvage salvageable model output #603/PR #489 后续: 默认图片计费 b64/4 在像素 tile 计费上游(官方 Anthropic/OpenAI)会硬 502 误杀多模态会话 #496/多模态会话上下文控制失效 + preflight 救援 502（codex responses store:false） #488 都加了),原 PR 漏了。我已补条目并推送到分支(新 head 1fd8806,措辞与默认值无关,auto/off 拍板后不受影响)。
• env 值未 .trim()(不改,仅记录):BILI_HOST_USAGE_CREDIT="off "(尾随空格)或 =Off(大写)会静默落到 auto。与 parseUpstreamProxyMode 的宽松风格一致,属边界情况,维持现状。

[ranxianglei]

解决冲突

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 ✅ 冲突已解决,PR 现在 mergeable: True(不再 dirty)。

冲突点(很小)

master 从 v0.1.95(5836f78)推进到 v0.1.99(6282f35) 后,唯一冲突在 CHANGELOG.md:上游在 [Unreleased] → ### Fixes 顶部新增了 #651 条目,和我上一轮加的 #648 条目落在同一位置。代码文件(config.ts / server.ts / tests / CONFIGURATION.md)rebase 时无冲突 —— 我上轮担心的 #651 对 armHostUsageCredit 的改动与本 PR 不重叠。

解决方式

• 两条 CHANGELOG 条目都保留(Protected-message exemption inflates the incompressible context floor: per-compression reasoning is never reclaimable (~83.5% of measured residual) #651 在上,ZCode 宿主 usage 回填未压缩基线:压缩后上下文显示成累加值,非实际转发量(v0.1.88 起;#645 的 ZCode 面) #648 紧随其后),删掉三行冲突标记。
• 把分支 rebase 到最新 master(v0.1.99),用 --force-with-lease 推回(新 head 6fba944,2 commits / 5 files)。这是 PR 分支的常规 rebase,非 master,不涉及 force-push master 禁令。

预检(rebased head 重跑)

• npm run typecheck — 干净
• npm run build — 成功
• npm test — 1270/1270 全绿(测试数从 1242→1270 是 master 新增用例;之前那个 launcher.test.ts codex 环境预存失败现在也过了 —— 上游 test: make resolveClientCommand codex/claude tests hermetic (#642) #643 把该测试改成了 hermetic,所以那个环境问题已消失)

现状

• PR mergeable: True;mergeable_state: blocked 只是等人工 review/合并(合并始终人工,我不代合)。
• ⚠️ 备注:fix #645: suppress #408 host-usage backfill for codex (report folded usage) #647(codex UA 豁免)目前还没进 master,所以本次没和它撞车;若之后 fix #645: suppress #408 host-usage backfill for codex (report folded usage) #647 先合、fix #648: add hostUsageCredit switch to opt out of #408 host-usage backfill #649 后合,两者都改 armHostUsageCredit,届时可能要在同一函数处再解一次小冲突。

可以安排 review/合并了。