Skip to content

[PR] fix(summary): unwrap single data envelope from OpenAI-compatible relays - #2552

Closed
DDjian wants to merge 3 commits into
ranxianglei:masterfrom
DDjian:data-envelope-fix
Closed

DDjian wants to merge 3 commits into
ranxianglei:masterfrom
DDjian:data-envelope-fix

Conversation

@DDjian

@DDjian DDjian commented Oct 9, 2026

Copy link
Copy Markdown

Problem

Some OpenAI-compatible relays wrap a successful chat-completion body in a single data envelope:

{ "data": { "choices": [ { "finish_reason": "stop", "index": 0, "message": { "role": "assistant", "content": "..." } } ] } }

Observed live on api.cline.bot (2026-10, both cline-glm-5.3-flash and cline-deepseek-v4.1-flash).

The body parses as valid JSON, so parseSummary treats it as a plain-JSON completion — but completed() sees no choices and extractSummaryText finds no summary text. The successful payload is then rejected as "contains no summary", and the preflight retry chain shrinks ranges and re-queries until its whole budget is burned. In production (agent session backed by that relay) this produced 55 failed summary parses and a 32-replay burn with a 715-second first round while the model answers were actually fine.

Fix

unwrapDataEnvelope removes exactly one such shell before parsing, and only when it is unambiguous:

  • outer object carries none of the known body shapes (choices / content / output / output_text / candidates),
  • data is a plain object exposing one of those shapes,
  • the outer object is not itself an error (error present → untouched).

Everything else passes through untouched: double envelopes, {data: [...]} arrays, foreign data payloads, error bodies wearing a data costume, and all standard bodies (no behavior change on the happy paths).

Applied at the four parse entry points:

  • completed() openai branch (completeness check)
  • parseSummary JSON entry
  • extractSummaryText (non-SSE extraction)
  • extractSummaryFromSse per-frame (envelopes can wrap individual SSE frames)

Tests

tests/data-envelope-summary.test.ts (6 cases):

  • helper: strips the envelope; leaves standard bodies / error objects / arrays / foreign data untouched
  • extractor: reads choices through the envelope; still returns empty for an error body wearing one
  • end-to-end: createSummaryHttpCandidate accepts a data-enveloped completion body and still rejects an error body

npm run typecheck clean; full suite unchanged versus baseline (summary-path tests all green; the 9 pre-existing zcode-native failures on this machine reproduce on pristine master without the patch — environment-dependent, unrelated).

Related

Fixes the production failure mode where a relay's non-standard success shape converts a healthy summary response into a full retry-budget burn; complements the existing rejection/diagnosis chain (#726/#727/#780/#784) which correctly treats incomplete bodies as failures but had no path for complete-but-wrapped ones.

Some relays (api.cline.bot observed 2026-10) return a successful
chat-completion summary as { "data": { choices: [...] } } with nothing
else at the top level. The body parses as valid JSON, so completeness
checking and every summary extractor see no choices/content/output and
report an empty summary — the request then burns its entire retry
budget (32 replays observed in production) on a payload that actually
succeeded.

unwrapDataEnvelope removes exactly one such shell before parsing:
only when the outer object carries none of the known body shapes
(choices/content/output/output_text/candidates), data is a plain
object exposing one of those shapes, and the outer object is not an
error. Double envelopes, data arrays, foreign data payloads, error
bodies and standard responses all pass through untouched.

Applied at the four parse entry points: completed() openai branch,
parseSummary JSON entry, extractSummaryText and extractSummaryFromSse
(per-frame, since envelopes may wrap individual SSE frames).
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review in progress — fetched the branch, reading all four application points plus every other caller of the touched extractors (requestSummary, [acp-decide] side-channel, external-summary candidate). Will run the targeted suite locally and come back with the full structured verdict. One thing already spotted: the decide path (extractDecisionText) may sit in the same mechanism family — checking.

awork added 2 commits October 9, 2026 23:42
…h too

Review supplement for the data-envelope fix: runNudgeDecision (ranxianglei#2228) reads its non-streaming answer through extractDecisionText, which had the same blind spot as the summary extractors — a relay that wraps successful completions in a single data envelope makes every decision call fail to parse, so the ladder silently degrades model-decided timing to the legacy advisory nudge after DECIDE_FALLBACK_THRESHOLD strikes. Apply the same unambiguous single-shell unwrap at the entry of extractDecisionText (no import cycle: preflight does not import nudge-decide).
The four application points of unwrapDataEnvelope previously left extractSummaryFromSse's per-frame unwrap without a direct regression test. Add: an openai SSE stream whose frame is data-enveloped now yields its delta text (and a double envelope still yields nothing), plus extractDecisionText reading a model answer through the envelope while standard bodies stay untouched.
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — verdict: 可合 (mergeable), pending CI green on the new head.

先说验证(审核三步):

  1. 复现/查证:问题成立。{data:{choices:[...]}} 是合法 JSON,parseSummary 按 plain-JSON 处理,但 completed() 找不到顶层 choices → 判未完成 → extractSummaryText 返回空 → 落入 [Bug] Codex 额度中断后恢复长会话,preflight SSE 摘要为空并持续 502 #726 halving/cooldown 链烧光预算。代码路径已逐点核实(src/external-summary-http.ts parseSummary/completed,src/preflight.ts requestSummary)。
  2. 层次判断:作者修的是解析层——bili 对自己出站 summary 请求响应的解释。字节的生产者是外部 relay(不可修),"bili 拒绝一个合法 completion"才是本仓内的真实缺陷。这不是 opencode 插件模式下 render tag 注入消息正文,模型回显漏网后原样渲染进 TUI(元数据与正文同层问题) #933/[bug] 插件透传会剥掉工具调用参数里的 render tag(arguments 流挂了 tag-echo 过滤器) #1039 的 mask 模式:这里解析的是 bili 自己出站调用的响应,提取结果成为 summary block,不触碰 tool-call arguments、客户端可见历史或 thinking 签名通道。
  3. 方案评估:unwrap 门控严格且幂等——外层无任何已知 body shape + data 为 plain object 且直接暴露已知 shape + 外层非 error;只剥单层(parseSummary→completed→extractSummaryText 的重复调用不会二次剥)。方向正确,打到了核心。

结构化八问:

  1. 是什么问题:部分 OpenAI 兼容 relay(api.cline.bot 实测)把成功的 chat-completion 包在单层 {data:{...}} 里,bili 的 summary 解析器把成功响应当成"无摘要",整个 preflight 重试预算被健康响应烧光(生产观测:55 次解析失败、32 次 replay、首轮 715s)。
  2. 什么原因导致的:四个解析入口(completed openai 分支 / parseSummary JSON 入口 / extractSummaryText / extractSummaryFromSse 逐帧)都假定 body shape 在顶层;多一层壳后所有入口都找不到 choices/content/output/output_text/candidates。根因在 relay 的非标准 success shape;bili 对"完整但被包裹"的 body 没有归一化路径([Bug] Codex 额度中断后恢复长会话,preflight SSE 摘要为空并持续 502 #726/fix: recover preflight from empty SSE summaries + dead-end cooldown (#726) #727/[Bug] preflight 摘要抽取层:被截断的 SSE 会被当成完整摘要,delta-less 终端会被当成空摘要(#726 的恢复链路仍未闭环) #780/fix: preflight SSE extraction rejects truncated and failure streams (#780) #784 链只覆盖了"不完整")。
  3. 影响范围与严重程度:上游是此类 relay 的用户——proxy 模式下每次 summary 请求烧光重试预算,压缩停滞、turn fail-fast("context exceeds the model window"),会话卡死或严重延迟;主对话流量不受影响(流式帧是标准形状,与"模型回答其实正常"的现场观测一致)。对受影响用户严重,其他用户零影响。
  4. 怎么修复的:解析前剥掉恰好一层无歧义的 data 壳(三门控条件),在四个 summary 解析入口统一应用;其余一切 passthrough 不变。
  5. 是否有回归问题(逐项清点既有行为):
    • 标准 body(四协议顶层 shape)→ 守卫直通,行为不变 ✓
    • error body(顶层 error)→ 原样保留、仍被拒 ✓(测试用引用相等钉住)
    • 数组(google 非 SSE chunk 数组)、{data:[...]}、外部 data → 原样保留 ✓
    • 双层信封 → 仍被拒(单壳契约)✓(新增测试钉住)
    • extractSummaryFromSse 的另一调用方 server.ts:1999([acp-decide] SSE 臂)→ 同机制同受益;标准帧无顶层 data,不受影响
    • fail-fast 语义未漂移:裹了壳的 error 仍被拒并进诊断链(e2e 测试钉住)
    • 残留风险(不拦):假设某网关给带 type 的 SSE 帧同时挂 body-shape 的 data 字段,会被误判为信封;未见此类 wire 形状,失败模式有界(帧贡献为空或 summary 被拒重试),不构成静默数据损坏。记录在案,不强制改。
    • review 中顺手补的修复(已推 PR 分支,独立标注 commit):#2228 model-decided nudge 路径的 extractDecisionText 存在同一盲点——此类 relay 上每次 decide 调用都解析失败,连续 3 次后 ladder 静默退化为 legacy advisory nudge。同一机制家族,按机制完整性在本 PR 内补齐:5256edd2e(src/nudge-decide.ts 两行)+ d9249e930(补 per-frame SSE unwrap 此前缺失的直接回归测试 ×2,decide 路径覆盖 ×1)。
  6. 是否破坏缓存:不涉及——不碰 prefix cache、会话身份、持久化格式、增量游标。重试预算行为唯一变化是"曾被成功响应烧光的预算"现在一次通过(即修复目的本身)。
  7. 是否改了设计方向:不涉及——bili 自有解释边界上的归一化,不改 wire、不加配置面、plugin/proxy 双模式均受益或不受影响。
  8. 是否引入新配置:不涉及。

验证证据:本地定向套件 90/90 绿(envelope 6 例 + preflight-sse-extraction + preflight-empty-summary + external-summary-http + nudge-decide + nudge-model-decided),typecheck clean;全量回归交远程 CI(新 head d9249e930 运行中;作者报告本机 9 个 zcode-native 失败在 pristine master 同样复现,环境相关)。分支落后 master 两个提交(均 launcher-only,无文件交集,mergeable=true)。

判定:可合。 方向正确、范围收敛、测试有牙(happy-path passthrough 与各拒绝形态均有引用相等断言)、diff 干净。合并由人执行;请盯一眼新 head 的 CI。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 更新:新 head d9249e930(含两个 review 补充 commit)的 25/25 check runs 全绿——含 kernel-guard / pi-subagents-guard / version-guard、四平台 test 矩阵(u22/u24/win22/win24)、hermetic registry e2e、real-client lanes。上一条判定中的 CI 前提已满足:可合,等人工合并。

@ranxianglei

Copy link
Copy Markdown
Owner

(ai: zhipuai-lb/glm-5.3)

孤儿票清理:提交两周未更新、无 issue 关联,且相关领域已有后续修复落地。为避免重复劳动关闭;如果你想继续推进,请 reopen 并补一个关联 issue(Fixes #N),我们会优先审查。感谢贡献!

@ranxianglei ranxianglei changed the title fix(summary): unwrap single data envelope from OpenAI-compatible relays [PR] fix(summary): unwrap single data envelope from OpenAI-compatible relays Oct 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants