Skip to content

[PR] fix(openai): keep provider usage fields in the synthesized completion - #7136

Closed
myfear wants to merge 1 commit into
ranxianglei:masterfrom
myfear:fix/openai-usage-fields
Closed

myfear wants to merge 1 commit into
ranxianglei:masterfrom
myfear:fix/openai-usage-fields

Conversation

@myfear

@myfear myfear commented Nov 18, 2026

Copy link
Copy Markdown

Preserve the last upstream usage object when emitting the synthesized completion chunk. OpenAI clients that price a turn from provider fields (for example cost/credits) otherwise lose them.

Forward the trailing usage-only frame to clients that set stream_options.include_usage, including text-only rounds, and reset the remembered usage per stream round so a later round cannot inherit a previous cost.

  • Read stream_options.include_usage and forward the trailing usage-only frame on text-only rounds too. The old code forwarded it only when a tool call was seen.
  • Keep the last raw upstream usage for the current round. In emitCompletion, spread it first, then overwrite the normalized token fields and merge prompt_tokens_details.
  • Reset the remembered usage at the start of parseStream, so a later round without usage cannot inherit a previous cost.
  • No config or kernel change.

Adds five regression tests in tests/openai-usage-frame-forward.test.ts.

A shared rawUsage on the usage event and EmitCompletionOpts, accumulated like terminalExtra (#1766), would give all four wires the same guarantee. This PR is the OpenAI increment.

Thanks for your consideration.
M

Preserve the last upstream usage object when emitting the synthesized completion chunk. OpenAI clients that price a turn from provider fields (for example cost/credits) otherwise lose them.

Forward the trailing usage-only frame to clients that set stream_options.include_usage, including text-only rounds, and reset the remembered usage per stream round so a later round cannot inherit a previous cost.

Adds five regression tests in tests/openai-usage-frame-forward.test.ts.
@ranxianglei ranxianglei changed the title fix(openai): keep provider usage fields in the synthesized completion [PR] fix(openai): keep provider usage fields in the synthesized completion Nov 18, 2026
@ranxianglei ranxianglei added bug Something isn't working p2 scope/wiring labels Nov 18, 2026
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Duplicate check: not a duplicate — same-family as #7084 (both edit the openai-adapter usage lines, but #7084 fixes usage-event all-zeros/loss; this PR fixes provider-field preservation) and as #4074 (same mechanism, different wire — #4074 is the anthropic side, already merged). This PR is the OpenAI increment of provider-field preservation.

CI: 12 test shards still in flight (0 failed, as of the 08:37 UTC snapshot); static-gates / mysql-contract / lock-sync / kernel-guard / lifecycle-ledger-guard already green. Local targeted verification: the PR's 5 regression tests all pass, plus 37 cases across the 5 adjacent usage test files all pass.

Headline finding — conflicts with open owner PR #7084. Both PRs edit the same two spots in src/loop/adapter-openai.ts: the finishReason usage branch (~L572-586) and emitCompletion's usage object (~L707-720). #7084 (owner, open, created 2026-11-17) wraps the finish-branch usage yield in if (u) (fixes #7061 all-undefined overwrite) and changes emitCompletion from a truthiness check to a hasUsage field check (fixes #7086 all-zeros). This PR's diff is based on master without #7084 (its finish-branch shows the unguarded yield). The two changes are compatible and combine cleanly (both guard on if (u); emitCompletion keeps the hasUsage check + adds the ...raw spread), but they will merge-conflict as-is → this PR needs a rebase onto master-with-#7084 (or coordination) before merge. This is the §7.5 stale-base / concurrent-file-churn signal.

What the PR does (verified against the diff):

  1. clientWantsUsage IIFE reads requestBody.stream_options.include_usage === true once at adapter creation. requestBody is the client's original parsed body (relay.ts:2683 → pickAdapter relay.ts:2733), so this reads the CLIENT opt-in correctly. bili forces include_usage=true upstream (prepare-openai.ts:615-616), so the upstream always sends the trailing usage-only frame; the client now receives it iff it opted in.
  2. Forward gate sawRealToolCall → sawRealToolCall || clientWantsUsage (~L539): the trailing usage-only frame is now forwarded on text-only rounds for opted-in clients (previously tool-call rounds only).
  3. lastUsageRaw closure, reset at parseStream start (L272), set at the three usage sites (L528 !choice, L572 bili drops an OpenAI-compatible stream's usage when it arrives on a non-empty choices frame with an empty delta #4488 non-empty-choices-empty-delta, L586 finishReason). In emitCompletion (L717) the raw object is spread FIRST, then the normalized prompt_tokens/completion_tokens/total_tokens overwrite it and prompt_tokens_details is merged as {...rawDetails, cached_tokens}. So provider-specific fields (cost/credits/…) survive while the normalized counts stay authoritative.

Minor findings (non-blocking):

  • Ordering: on a text-only include_usage round the forwarded usage-only frame reaches the client BEFORE the synthesized finish chunk (real OpenAI order is finish-then-usage). Assessed cosmetic — a client that stops at finish_reason has already seen the usage frame, and the finish chunk also carries the same usage, so no client loses data.
  • Test gap: none of the 5 tests exercises the finishReason-branch if (u) lastUsageRaw = u path (usage-on-finish-frame shape). The two frame-based paths are covered.
  • Scope: adapter-local lastUsageRaw (vs a shared terminalExtra-style rawUsage on the usage event + EmitCompletionOpts) is a deliberate OpenAI-only increment — acknowledged in the PR body. It leaves the anthropic/google/responses wires without the same guarantee (the anthropic twin already shipped as [PR] fix: re-carry the anthropic cache_creation breakdown on the synthetic terminal #4074).

Code quality (external-strict ⑤b): passes — clear names (clientWantsUsage/lastUsageRaw/rawDetails), no dead code / duplication / magic values, comments explain why, style consistent, no new deps, small focused diff, real regression tests with teeth. No ②a refactor warranted.

Verdict: correct, well-scoped increment — but do not merge as-is: rebase onto master-with-#7084 first (the two changes combine cleanly), then re-review. Labels applied: bug p2 scope/wiring.


八问(中文, 供人工 reviewer):

  1. 是什么问题: OpenAI 客户端若从 provider 私有字段(如 cost/credits)计费, 在 bili 合成的 completion 里会丢掉这些字段 —— 因为 emitCompletion 只输出归一化的 token 数, 不带上游原始 usage 对象里的私有字段; 且 text-only 轮次(无 tool call)时尾部 usage-only 帧根本不下发给客户端。
  2. 什么原因导致的: 两层 —— (a) emitCompletion 构造 usage 对象时只显式列了 prompt_tokens/completion_tokens/total_tokens/cached_tokens, 没有透传上游原始 usage 的其余字段; (b) 尾部 usage-only 帧的下发门是 sawRealToolCall, text-only 轮次为 false 故被吞。
  3. 影响范围与严重程度: 仅影响"用 provider 私有字段计费"的 OpenAI 客户端 + 仅 text-only 轮次丢帧; 标准 token 计费客户端不受影响。属"特定条件下有问题"(列明条件), 体验/计费瑕疵, 非不可用 → p2。
  4. 怎么修复的: 三处 —— ① 新增 clientWantsUsage(读客户端 stream_options.include_usage)把下发门放宽为 sawRealToolCall || clientWantsUsage; ② 闭包 lastUsageRaw 记住本轮最后一条原始 usage, emitCompletion 先 ...raw 展开再覆盖归一化字段并 merge prompt_tokens_details; ③ parseStream 开头重置 lastUsageRaw=null, 防止后续无 usage 轮次继承上一轮成本。
  5. 是否有回归风险: 审过既有行为 —— 归一化 token 数仍由 opts.usage 权威覆盖(不被 raw 污染); prompt_tokens_details 走 merge 不丢 raw 里的其它子字段; 无 usage 时 raw={} 展开为空对象, 不引入幻影字段; 相邻 5 个 usage 测试文件 37 例全过, 无回归。但与 [PR] fix(openai): preserve usage when it arrives on a frame before the finish frame #7084 同改两行, 直接合会 merge-conflict —— 需先 rebase 到含 [PR] fix(openai): preserve usage when it arrives on a frame before the finish frame #7084 的 master(两者可干净合并)。
  6. 是否破坏缓存: 不涉及 —— 纯 wire 层 usage 透传, 不碰缓存/重试/增量游标/去重键。
  7. 是否改了设计方向: 不涉及架构转向; 是 provider 字段保留的 OpenAI 单 wire 增量。PR 正文已声明: 四 wire 统一保证需把 rawUsage 挂到 usage event + EmitCompletionOpts(类 terminalExtra claude auto-mode-classifier-billing 适配 #1766)累积, 本 PR 只做 OpenAI 增量, 其余三 wire 暂无同等保证。
  8. 是否引入新配置: 不涉及 —— 无新 env/config/默认值。

收工判定: 代码正确、范围清晰、测试有牙, 但不可直接合并 —— 先 rebase 到含 #7084 的 master(两处改动可干净合并), rebase 后复审再合。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI update: all 30 checks now complete — 13 passed, 17 skipped (gated e2e lanes), 0 failed. The PR is mergeable (no conflict with master). The headline finding stands: it will conflict with open owner PR #7084 on the same two lines (finishReason usage branch + emitCompletion), so rebase onto master-with-#7084 before merge.

@ranxianglei

Copy link
Copy Markdown
Owner

merged by #7445

@ranxianglei

Copy link
Copy Markdown
Owner

已收编进 batch-B PR #7445(已合并,2026-11-21)。本 PR 的 OpenAI 合成 completion 保留 provider usage 字段修复已 cherry-pick 进 #7445 并保留原作者署名。本 PR 关闭。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working p2 scope/wiring

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants