mslxdff 0.1.199 → 0.1.203

package/src/routes/stream-scan.js

@@ -1,366 +1,366 @@
-// relay 的观测累加器：把流式 SSE chunk / 非流式 JSON 体读成 detail 上的计数事实。
-// 抽自 src/routes/stream.js（单文件 20KB 硬门，见 AGENTS.md「先拆后写」），行为与抽出前逐字一致。
-// 纯函数契约：只读写传入的 detail，不碰 res / 定时器 / 闸门 / 网络，因此可离线单测。
-// 语义钉子：detail.chars 只算正文，思考内容另计（reasoningChars）——两者相加会重复计数。
-import { extractUsageFromJson } from "../metrics.js";
-import { talkLogEnabled } from "../talk-log.js"; // 建桶判据之一（两模块都是按调用读 env，无 import 期冻结）
-import { agentLoopEnabled, talkCapChars } from "../talk-full.js"; // 上限单一真相：本文件不得再写第二份数字
-
-// 响应正文捕获桶（talk log + agent 回路共用一只）：只有 relay 建了 detail.talk 才累积，未开启时零开销。
-// 口径与 chars/reasoningChars 同源（读 delta，不读聚合帧），区别是这里存原文而不是只计数。
-// 分帧口径（openspec fix-talk-capture-frame-loss）：**按行不按 chunk** —— 未以 `\n` 收尾的尾行留在
-// talk.remain 里等下个工作拼回，凑齐的完整 `data:` 行才 parse；流收场由消费方调 captureTalkFlush
-// 回收缺尾换行的末行。历史口径「帧被 chunk 切断即弃（研究用途可接受）」已废——它让 talk/talkfull
-// 的 tool arguments 随机少 1~10 字符（现网取证 43% 路径落空），误导模型侧归因。
-// 不可逆丢弃（切点落在多字节字符内部的拼回行、超限半行）不静默：桶上 dropped 计数显式可见，
-// 语料 meta.droppedFrames / talk 头行 dropped= 透出——「看起来完整其实吃字」比缺失更危险（review P1-1）。
-const TALK_REMAIN_MAX = 2_000_000; // 半行缓冲上限（UTF-16 字符数，≈4MB）：远大于任何流式 delta 单行；超限弃半行并显式记 dropped（review P2-5）
-// 上限真相是 talkCapChars()（MSLXDFF_TALK_CAP_CHARS ＞ full 开 200 万 ＞ full 关 40 万）；
-// 下面的常数只是 createTalkBucket 未传 cap 时的历史缺省，必须与「full 关」档逐字相同（有测试锁死）。
-const TALK_CAP_DEFAULT = 400_000;
-
-function talkPush(talk, dst, v) {
-  if (typeof v !== "string" || !v) return;
-  if (talk.n >= (talk.cap ?? TALK_CAP_DEFAULT)) { talk.capped = true; return; } // 撞顶只置位不静默：读侧靠它标 truncated
-  talk.n += v.length;
-  talk[dst].push(v);
-}
-
-// 流式 tool_calls 是分片到达的（index 定位、arguments 逐段拼），按 index 合回完整调用才看得懂。
-function talkMergeToolCalls(talk, tcs) {
-  for (const tc of tcs) {
-    const i = Number.isInteger(tc?.index) ? tc.index : talk.tools.length;
-    let slot = talk.tools[i];
-    if (!slot) { slot = { id: "", type: "function", function: { name: "", arguments: "" } }; talk.tools[i] = slot; }
-    if (tc.id) slot.id = tc.id;
-    const nm = tc.function?.name;
-    const ar = tc.function?.arguments;
-    if (typeof nm === "string" && nm && !slot.function.name.includes(nm)) slot.function.name += nm;
-    if (typeof ar === "string" && ar) slot.function.arguments += ar;
-  }
-}
-
-/** 新建累积桶（n/capped 防超长生成把内存吃穿）。cap = 字符上限，未传/非法 → 400_000（现状逐字不变）。
- *  remain = 跨 chunk 半行缓冲（openspec fix-talk-capture-frame-loss 行缓冲分帧）；dropped = 不可逆丢弃帧计数（P1-1 显式读数）。 */
-export function createTalkBucket(cap) {
-  const c = Math.floor(Number(cap));
-  const use = Number.isFinite(c) && c > 0 ? c : TALK_CAP_DEFAULT;
-  return { reasoning: [], content: [], tools: [], n: 0, capped: false, cap: use, remain: "", dropped: 0 };
-}
-
-/**
- * 「该不该建桶 + 建多大」的唯一判据，收在这里是为了给 stream.js 让体积（20KB 硬门）。
- * talk.log 与 agent 回路任一开启都必须建桶：只认 talkLogEnabled() 会让「talk.log 关 + full 开」
- * 的响应正文全丢（detail.talk 为 null，capture 全程记到空气）。上限取 talkCapChars() 单一真相。
- */
-export function createTalkBucketIfEnabled() {
-  return talkLogEnabled() || agentLoopEnabled() ? createTalkBucket(talkCapChars()) : null;
-}
-
-/** 完整单行消费（talk 桶的唯一落点，从原 captureTalkSse 循环体抽出，口径逐字不变）。glued=该行由跨 chunk 拼回。 */
-function talkConsumeLine(talk, raw, glued = false) {
-  if (glued && raw.includes("\uFFFD")) { talk.dropped = (Number(talk.dropped) || 0) + 1; return; } // 字节级切点：解码损伤不可逆，整行弃但必须留数（根因在 stream.js chunkText 逐 chunk 无状态解码，真修另起 change）
-  const t = raw.trim();
-  if (!t.startsWith("data:")) return;
-  const d = t.slice(5).trim();
-  if (!d || d === "[DONE]") return;
-  let j = null;
-  try { j = JSON.parse(d); } catch { return; }
-  const c0 = Array.isArray(j?.choices) ? j.choices[0] : null;
-  if (!c0) return;
-  for (const src of [c0.delta, c0.message]) {
-    if (!src) continue;
-    talkPush(talk, "reasoning", src.reasoning_content ?? src.reasoning);
-    talkPush(talk, "content", src.content);
-    if (Array.isArray(src.tool_calls)) talkMergeToolCalls(talk, src.tool_calls);
-  }
-}
-
-// 已见工具调用 index：按 detail 对象存进 WeakMap，既不污染 detail（它会被序列化进 events/模型日志，
-// 多一个属性就是日志噪音），也不随 detail 的展开/复制丢失统计口径。
-const tcIndexes = new WeakMap();
-
-/** 工具调用去重计数：同一 `index` 的多个分片只算一次；分片缺 `index` 时退回 0。 */
-function countToolCalls(detail, txt) {
-  if (!detail || typeof detail !== "object") return;
-  let seen = tcIndexes.get(detail);
-  if (!seen) { seen = new Set(); tcIndexes.set(detail, seen); }
-  const re = /"tool_calls"\s*:\s*\[\s*\{/g;
-  let m;
-  while ((m = re.exec(txt))) {
-    // 从 tool_calls 数组起点往后取第一个 index（choices[].index 在此位置之前，不会误取）
-    const after = txt.slice(m.index + m[0].length - 1);
-    const im = after.match(/"index"\s*:\s*(\d+)/);
-    seen.add(im ? Number(im[1]) : 0);
-  }
-  if (seen.size) detail.toolCalls = seen.size;
-}
-
-/** 逐 chunk 累积一轮对话的思考/正文/工具调用。talk 为空 = 未开启，直接返回。跨 chunk 行缓冲见文件头。 */
-export function captureTalkSse(talk, txt) {
-  if (!talk) return;
-  if (talk.remain && talk.remain.length > TALK_REMAIN_MAX) { talk.remain = ""; talk.dropped = (Number(talk.dropped) || 0) + 1; } // 拼接前丢弃超限半行：内存不尖峰（review P2-5）且显式记数；本轮正常数据照常消费
-  const hadRemain = Boolean(talk.remain);
-  const buf = (hadRemain ? talk.remain : "") + String(txt ?? "");
-  talk.remain = "";
-  if (!buf) return;
-  const lines = buf.split("\n");
-  if (!buf.endsWith("\n")) talk.remain = lines.pop() ?? "";
-  for (let i = 0; i < lines.length; i++) talkConsumeLine(talk, lines[i], hadRemain && i === 0);
-}
-
-/** 流收场回收：把缓冲里缺尾换行的末行按同一单行口径入桶（截断流不静默吞末帧）。幂等；无桶/空缓冲零副作用。 */
-export function captureTalkFlush(talk) {
-  if (!talk || !talk.remain) return;
-  const raw = talk.remain;
-  talk.remain = "";
-  talkConsumeLine(talk, raw, true);
-}
-
-/** 非流式：整块 message 直接入桶（tool_calls 参数本来就是完整的）。 */
-export function captureTalkMessage(talk, msg) {
-  if (!talk || !msg) return;
-  talkPush(talk, "reasoning", msg.reasoning_content ?? msg.reasoning);
-  talkPush(talk, "content", msg.content);
-  if (Array.isArray(msg.tool_calls)) talkMergeToolCalls(talk, msg.tool_calls);
-}
-
-/** 透传兜底：无 chat 帧可解析（纯文本/未知形状）时把原文当正文收下，别让对话日志留空洞。 */
-export function captureTalkFallback(talk, text) {
-  if (!talk || !text) return;
-  if (talk.reasoning.length || talk.content.length || talk.tools.length) return;
-  if (String(text).includes('"choices"')) return;
-  talkPush(talk, "content", String(text));
-}
-
-// 判据必须跑在**完整行**上：TCP 会把一帧切两块，`"finish_reason"`/`"content"` 被切在中间时正则永不命中
-// ⇒ sawFinishReason 恒 null（正常结束的流被 endTruncatedStream 误判成截断，向客户端写假 STREAM_TRUNCATED）、
-// chars 归零（chatShaped 为真时正好命中空轮判据）。与 BUG-24/25 同型：那次是终止标记被切块，这次是观测层缺行缓冲。
-const scanRemain = new WeakMap();
-const SCAN_REMAIN_MAX = 1_000_000; // 半行上限：超限按完整行处理，宁可错判也不无界吃内存
-
-/** 流收场回收：末尾无换行的残行按同一口径扫一次，否则末帧的 finish_reason 永远读不到。幂等。 */
-export function flushScanRemainder(detail) {
-  if (!detail || typeof detail !== "object") return;
-  const rest = scanRemain.get(detail);
-  if (!rest) return;
-  scanRemain.delete(detail);
-  scanCompleteText(detail, rest);
-}
-
-// 逐 SSE chunk 扫描：done/finish_reason/chat 形状/工具调用/usage/正文字符
-export function scanSseChunk(detail, txt) {
-  if (detail.talk) { try { captureTalkSse(detail.talk, txt); } catch {} } // 纯旁路红线：捕获异常绝不外溢成转发失败（review P2-7：旧调用点裸奔在 try 外只是口头契约）
-  let buf = (scanRemain.get(detail) || "") + String(txt ?? "");
-  const rest = buf.slice(buf.lastIndexOf("\n") + 1);
-  if (rest.length > SCAN_REMAIN_MAX) { scanRemain.set(detail, ""); }
-  else { buf = buf.slice(0, buf.length - rest.length); scanRemain.set(detail, rest); }
-  if (buf) scanCompleteText(detail, buf);
-}
-
-function scanCompleteText(detail, txt) {
-  try {
-    if (txt.includes("[DONE]")) detail.sawDone = true;
-    const m = txt.match(/"finish_reason"\s*:\s*"([^"]+)"/);
-    if (m) detail.sawFinishReason = m[1];
-    // chat 形状证据：只有看得出是 chat 轮才配判空（非 chat SSE/JSON 透传是正式契约，不得误伤）
-    if (!detail.chatShaped && (txt.includes('"choices"') || txt.includes('"delta"') || txt.includes('"finish_reason"') || txt.includes('"usage"') || txt.includes('"prompt_tokens"') || txt.includes("[DONE]"))) detail.chatShaped = true;
-    // 工具调用计数（空数组不算）：tool_calls 无正文是合法 agent 轮，
-    // 空转闸门必须豁免它，否则所有工具轮都会被误判为空轮——见 relay-pipeline 4b。
-    // 口径按 `index` 去重：流式 tool_calls 的 arguments 是**分片**到达的，每个分片都含
-    // `"tool_calls":[{"index":N,...` ⇒ 按命中次数累加会把一次调用计成 N 次（实测 4894/5999 帧命中，
-    // 虚高数千倍，且与 scanNonStreamBody 的 `.length` 口径不一致）。去重后与非流式同义。
-    countToolCalls(detail, txt);
-    // 尝试提取 usage（流式末帧）：口径收口到 metrics.js，与未流式分支共用
-    if (txt.includes("\"usage\"") || txt.includes("\"prompt_tokens\"")) {
-      try {
-        const lines = txt.split("\n");
-        for (const line of lines) {
-          const t = line.trim();
-          if (!t.startsWith("data:")) continue;
-          const d = t.slice(5).trim();
-          if (d === "[DONE]" || !d) continue;
-          // 行级隔离：单行坏 JSON 不拖累同 chunk 其余行
-          try {
-            const j = JSON.parse(d);
-            if (!j || typeof j !== "object") continue;
-            const u = extractUsageFromJson(j);
-            if (u) detail.usage = u;
-            // 兜底 chars：从 choices 文本长度累加
-            const delta = j.choices?.[0]?.delta?.content || j.choices?.[0]?.message?.content || "";
-            if (delta) detail.chars += String(delta).length;
-            const rc = j.choices?.[0]?.delta?.reasoning_content || j.choices?.[0]?.delta?.reasoning
-              || j.choices?.[0]?.message?.reasoning_content || j.choices?.[0]?.message?.reasoning || "";
-            if (rc) detail.reasoningChars = (detail.reasoningChars || 0) + String(rc).length;
-          } catch { /* 单行坏帧忽略 */ }
-        }
-      } catch {}
-    } else {
-      // 非 usage 的普通 delta 也累 chars
-      try {
-        const ms = txt.match(/"content"\s*:\s*"([^"]*)"/g);
-        if (ms) for (const mm of ms) {
-          const c = JSON.parse(`{${mm}}`);
-          if (c.content) detail.chars += String(c.content).length;
-        }
-        // 同一 chunk 里的思考增量：键名两种上游都见过（reasoning_content / reasoning）
-        const rs = txt.match(/"reasoning(?:_content)?"\s*:\s*"([^"]*)"/g);
-        if (rs) for (const mm of rs) {
-          const c = JSON.parse(`{${mm}}`);
-          const v = c.reasoning_content ?? c.reasoning;
-          if (v) detail.reasoningChars = (detail.reasoningChars || 0) + String(v).length;
-        }
-      } catch {}
-    }
-  } catch { /* ignore */ }
-}
-
-// 非流式聚合 JSON 体：同源口径提 usage/chars/chat 形状/工具调用
-export function scanNonStreamBody(detail, parsed) {
-  const u = extractUsageFromJson(parsed);
-  if (u) detail.usage = u;
-  if (parsed.choices?.[0]?.message?.content) detail.chars = String(parsed.choices[0].message.content).length;
-  else if (parsed.choices?.[0]?.text) detail.chars = String(parsed.choices[0].text).length;
-  // 思考内容另记（qoder 的 stream:false 出口把思考放在 message.reasoning_content）
-  const rc = parsed.choices?.[0]?.message?.reasoning_content || parsed.choices?.[0]?.message?.reasoning || "";
-  if (rc) detail.reasoningChars = (detail.reasoningChars || 0) + String(rc).length;
-  // 非流式同样只判 chat 形状：无 choices 的任意 JSON 是透传契约（chat-route 单测锁死），不得判空
-  if (Array.isArray(parsed?.choices)) detail.chatShaped = true;
-  const _tcList = parsed.choices?.[0]?.message?.tool_calls;
-  if (Array.isArray(_tcList) && _tcList.length) detail.toolCalls = _tcList.length;
-  if (detail.talk) captureTalkMessage(detail.talk, parsed.choices?.[0]?.message || (parsed.choices?.[0]?.text ? { content: parsed.choices[0].text } : null));
-}
-
-// 上报锚点偏移：转发入口时刻 − 本次上游尝试起点（performance.now 同源）。
-// 只服务上报时长（usage 行），四类保护闸门仍用 relay 自己的 t0，绝不引用它。
-export function preflightMs(t0, attemptStartMs) {
-  // 锚点必须是与 t0 同源（performance.now）的有限 number；其余一律按「无锚点」降级为 0，
-  // 宁可退回修复前口径，也不能产出 NaN 或假高值
-  if (typeof attemptStartMs !== "number" || !Number.isFinite(attemptStartMs)) return 0;
-  const delta = Math.round(t0 - attemptStartMs);
-  return delta > 0 ? delta : 0;
-}
-
-/**
- * 空轮判据（纯函数，唯一真相）：看得 chat 形状 + 零正文 + 零工具调用 + 收尾不是工具轮。
- * stream.js 用它决定「这次要不要封口」，relay-pipeline 用它决定「交不交回重试」——两处不得各写一份。
- * chatShaped 是前置证据：非 chat SSE / 无 choices 的透传是正式契约，一律放行不判空。
- */
-export function isEmptyTurnDetail(d) {
-  if (!d || d.chatShaped !== true) return false;
-  if ((Number(d.chars) || 0) > 0 || (Number(d.toolCalls) || 0) > 0) return false;
-  if (["tool_calls", "function_call"].includes(d.sawFinishReason)) return false;
-  return true;
-}
-
-// ===== 从 stream.js 迁入（体积门：stream.js 承载 relay 本体，纯判定函数一律住这里）=====
-
-// 错误包络 chunk 判定（纯函数）：data 行 JSON 含顶层 .error 对象、或只有 finish_reason=error
-// 的空帧，且整 chunk 无任何 content/tool_calls/reasoning 输出 → 返回错误摘要（建议暂扣），
-// 否则返回 null（透传）。解析失败一律透传（默认保安全）。
-// 背景：网关把上游失败包成 HTTP 200 SSE；暂扣后下游流式 UI 不再展示瞬时错误
-//（如 Vertex 503 + google fallback 400），本轮走空转重试，客户端只看到最终结果。
-// Note: 流内错误包络捕获与 retryAfterSeconds 错误直出 — 见 .agents/notes/implemented/bug-fix/2026-09-28-retry-after-surfacing-error.md
-export function extractRetryAfterSec(obj) {
-  if (!obj) return null;
-  if (typeof obj === "number") return obj;
-  if (typeof obj === "string") {
-    const m = obj.match(/"retryAfterSeconds"\s*:\s*(\d+)/i) || obj.match(/\bretryAfterSeconds\s*[:=]\s*(\d+)/i);
-    if (m) return Number(m[1]);
-    try {
-      const parsed = JSON.parse(obj);
-      return extractRetryAfterSec(parsed);
-    } catch {}
-  }
-  if (typeof obj === "object") {
-    if (Number.isFinite(obj.retryAfterSeconds)) return Number(obj.retryAfterSeconds);
-    if (obj.message) {
-      const r = extractRetryAfterSec(obj.message);
-      if (r != null) return r;
-    }
-  }
-  return null;
-}
-
-export function holdableChunk(txt) {
-  if (typeof txt !== "string" || !txt.includes("data:")) return null;
-  let sawData = false;
-  let sawEventError = false;
-  let retrySec = null;
-  const errs = [];
-  for (const rawLine of txt.split("\n")) {
-    const t = rawLine.trim();
-    if (t.startsWith("event:") && t.slice(6).trim() === "error") {
-      sawEventError = true;
-      continue;
-    }
-    if (!t.startsWith("data:")) continue;
-    const d = t.slice(5).trim();
-    if (!d || d === "[DONE]") continue;
-    let j = null;
-    try { j = JSON.parse(d); } catch { return null; }
-    if (!j || typeof j !== "object") return null;
-    sawData = true;
-    const c0 = (Array.isArray(j.choices) && j.choices[0]) || {};
-    const delta = c0.delta || {};
-    const msg = c0.message || {};
-    const out = delta.content || msg.content || delta.tool_calls || msg.tool_calls || delta.reasoning || msg.reasoning;
-    if (out && !(Array.isArray(out) && out.length === 0)) return null;
-
-    const r = extractRetryAfterSec(j);
-    if (r != null) {
-      retrySec = r;
-      continue;
-    }
-    if (j.error && typeof j.error === "object") {
-      const m = j.error.message || j.error.code || "";
-      if (m) errs.push(String(m).slice(0, 300));
-    } else if (sawEventError && j.message) {
-      errs.push(String(j.message).slice(0, 300));
-    } else if (c0.finish_reason === "error") {
-      errs.push("finish_reason=error 空帧");
-    }
-  }
-  if (!sawData) return null;
-  if (retrySec != null) return `上游供应商触发 retryAfterSeconds: ${retrySec} ，请等候重试`;
-  if (errs.length) return errs.join(" | ");
-  if (sawEventError) return "event: error 空帧";
-  return null;
-}
-
-/**
- * 「可撤销前缀」判据（纯函数）：这个 chunk 里除空 delta 帧与 [DONE] 外不含任何信息吗？
- * 只有答案为是才允许暂扣不写——透传是正式契约：解析失败的帧、看不懂的形状一律立即透传（与
- * holdableChunk 同一口径：默认保安全，绝不因为想救空轮而扣掉本该原样转给客户端的字节）。
- */
-export function isTrivialFrame(txt) {
-  if (typeof txt !== "string" || !txt.includes("data:")) return false;
-  let sawData = false;
-  for (const rawLine of txt.split("\n")) {
-    const t = rawLine.trim();
-    if (!t.startsWith("data:")) continue;
-    const d = t.slice(5).trim();
-    if (!d) continue;
-    if (d === "[DONE]") { sawData = true; continue; } // 结束符不含模型输出，可撤销
-    let j = null;
-    try { j = JSON.parse(d); } catch { return false; } // 解析失败 → 透传，绝不撤销
-    if (!j || typeof j !== "object" || Array.isArray(j)) return false;
-    // 白名单式可撤销：只认「choices 数组、且其中没有任何文本载荷」的 chat 帧。
-    // 其余形状（choices[].text、delta.text、顶层 usage、无 choices 的自定义帧……）一律算有信息 → 透传。
-    if (!Array.isArray(j.choices)) return false;
-    sawData = true;
-    if (j.choices.some((c) => c && typeof c === "object" && (c.text || c.message?.text))) return false;
-    for (const c of j.choices) {
-      if (!c || typeof c !== "object") return false;
-      for (const src of [c.delta, c.message]) {
-        if (!src || typeof src !== "object") continue;
-        for (const [k, v] of Object.entries(src)) {
-          if (k === "role" || k === "index" || k === "function_call_name") continue; // 无信息骨架字段
-          if (v == null || v === "") continue;
-          if (Array.isArray(v) ? v.length > 0 : true) return false; // 任何非空载荷都算产出
-        }
-      }
-    }
-  }
-  return sawData;
-}
+// relay 的观测累加器：把流式 SSE chunk / 非流式 JSON 体读成 detail 上的计数事实。
+// 抽自 src/routes/stream.js（单文件 20KB 硬门，见 AGENTS.md「先拆后写」），行为与抽出前逐字一致。
+// 纯函数契约：只读写传入的 detail，不碰 res / 定时器 / 闸门 / 网络，因此可离线单测。
+// 语义钉子：detail.chars 只算正文，思考内容另计（reasoningChars）——两者相加会重复计数。
+import { extractUsageFromJson } from "../metrics.js";
+import { talkLogEnabled } from "../talk-log.js"; // 建桶判据之一（两模块都是按调用读 env，无 import 期冻结）
+import { agentLoopEnabled, talkCapChars } from "../talk-full.js"; // 上限单一真相：本文件不得再写第二份数字
+
+// 响应正文捕获桶（talk log + agent 回路共用一只）：只有 relay 建了 detail.talk 才累积，未开启时零开销。
+// 口径与 chars/reasoningChars 同源（读 delta，不读聚合帧），区别是这里存原文而不是只计数。
+// 分帧口径（openspec fix-talk-capture-frame-loss）：**按行不按 chunk** —— 未以 `\n` 收尾的尾行留在
+// talk.remain 里等下个工作拼回，凑齐的完整 `data:` 行才 parse；流收场由消费方调 captureTalkFlush
+// 回收缺尾换行的末行。历史口径「帧被 chunk 切断即弃（研究用途可接受）」已废——它让 talk/talkfull
+// 的 tool arguments 随机少 1~10 字符（现网取证 43% 路径落空），误导模型侧归因。
+// 不可逆丢弃（切点落在多字节字符内部的拼回行、超限半行）不静默：桶上 dropped 计数显式可见，
+// 语料 meta.droppedFrames / talk 头行 dropped= 透出——「看起来完整其实吃字」比缺失更危险（review P1-1）。
+const TALK_REMAIN_MAX = 2_000_000; // 半行缓冲上限（UTF-16 字符数，≈4MB）：远大于任何流式 delta 单行；超限弃半行并显式记 dropped（review P2-5）
+// 上限真相是 talkCapChars()（MSLXDFF_TALK_CAP_CHARS ＞ full 开 200 万 ＞ full 关 40 万）；
+// 下面的常数只是 createTalkBucket 未传 cap 时的历史缺省，必须与「full 关」档逐字相同（有测试锁死）。
+const TALK_CAP_DEFAULT = 400_000;
+
+function talkPush(talk, dst, v) {
+  if (typeof v !== "string" || !v) return;
+  if (talk.n >= (talk.cap ?? TALK_CAP_DEFAULT)) { talk.capped = true; return; } // 撞顶只置位不静默：读侧靠它标 truncated
+  talk.n += v.length;
+  talk[dst].push(v);
+}
+
+// 流式 tool_calls 是分片到达的（index 定位、arguments 逐段拼），按 index 合回完整调用才看得懂。
+function talkMergeToolCalls(talk, tcs) {
+  for (const tc of tcs) {
+    const i = Number.isInteger(tc?.index) ? tc.index : talk.tools.length;
+    let slot = talk.tools[i];
+    if (!slot) { slot = { id: "", type: "function", function: { name: "", arguments: "" } }; talk.tools[i] = slot; }
+    if (tc.id) slot.id = tc.id;
+    const nm = tc.function?.name;
+    const ar = tc.function?.arguments;
+    if (typeof nm === "string" && nm && !slot.function.name.includes(nm)) slot.function.name += nm;
+    if (typeof ar === "string" && ar) slot.function.arguments += ar;
+  }
+}
+
+/** 新建累积桶（n/capped 防超长生成把内存吃穿）。cap = 字符上限，未传/非法 → 400_000（现状逐字不变）。
+ *  remain = 跨 chunk 半行缓冲（openspec fix-talk-capture-frame-loss 行缓冲分帧）；dropped = 不可逆丢弃帧计数（P1-1 显式读数）。 */
+export function createTalkBucket(cap) {
+  const c = Math.floor(Number(cap));
+  const use = Number.isFinite(c) && c > 0 ? c : TALK_CAP_DEFAULT;
+  return { reasoning: [], content: [], tools: [], n: 0, capped: false, cap: use, remain: "", dropped: 0 };
+}
+
+/**
+ * 「该不该建桶 + 建多大」的唯一判据，收在这里是为了给 stream.js 让体积（20KB 硬门）。
+ * talk.log 与 agent 回路任一开启都必须建桶：只认 talkLogEnabled() 会让「talk.log 关 + full 开」
+ * 的响应正文全丢（detail.talk 为 null，capture 全程记到空气）。上限取 talkCapChars() 单一真相。
+ */
+export function createTalkBucketIfEnabled() {
+  return talkLogEnabled() || agentLoopEnabled() ? createTalkBucket(talkCapChars()) : null;
+}
+
+/** 完整单行消费（talk 桶的唯一落点，从原 captureTalkSse 循环体抽出，口径逐字不变）。glued=该行由跨 chunk 拼回。 */
+function talkConsumeLine(talk, raw, glued = false) {
+  if (glued && raw.includes("\uFFFD")) { talk.dropped = (Number(talk.dropped) || 0) + 1; return; } // 字节级切点：解码损伤不可逆，整行弃但必须留数（根因在 stream.js chunkText 逐 chunk 无状态解码，真修另起 change）
+  const t = raw.trim();
+  if (!t.startsWith("data:")) return;
+  const d = t.slice(5).trim();
+  if (!d || d === "[DONE]") return;
+  let j = null;
+  try { j = JSON.parse(d); } catch { return; }
+  const c0 = Array.isArray(j?.choices) ? j.choices[0] : null;
+  if (!c0) return;
+  for (const src of [c0.delta, c0.message]) {
+    if (!src) continue;
+    talkPush(talk, "reasoning", src.reasoning_content ?? src.reasoning);
+    talkPush(talk, "content", src.content);
+    if (Array.isArray(src.tool_calls)) talkMergeToolCalls(talk, src.tool_calls);
+  }
+}
+
+// 已见工具调用 index：按 detail 对象存进 WeakMap，既不污染 detail（它会被序列化进 events/模型日志，
+// 多一个属性就是日志噪音），也不随 detail 的展开/复制丢失统计口径。
+const tcIndexes = new WeakMap();
+
+/** 工具调用去重计数：同一 `index` 的多个分片只算一次；分片缺 `index` 时退回 0。 */
+function countToolCalls(detail, txt) {
+  if (!detail || typeof detail !== "object") return;
+  let seen = tcIndexes.get(detail);
+  if (!seen) { seen = new Set(); tcIndexes.set(detail, seen); }
+  const re = /"tool_calls"\s*:\s*\[\s*\{/g;
+  let m;
+  while ((m = re.exec(txt))) {
+    // 从 tool_calls 数组起点往后取第一个 index（choices[].index 在此位置之前，不会误取）
+    const after = txt.slice(m.index + m[0].length - 1);
+    const im = after.match(/"index"\s*:\s*(\d+)/);
+    seen.add(im ? Number(im[1]) : 0);
+  }
+  if (seen.size) detail.toolCalls = seen.size;
+}
+
+/** 逐 chunk 累积一轮对话的思考/正文/工具调用。talk 为空 = 未开启，直接返回。跨 chunk 行缓冲见文件头。 */
+export function captureTalkSse(talk, txt) {
+  if (!talk) return;
+  if (talk.remain && talk.remain.length > TALK_REMAIN_MAX) { talk.remain = ""; talk.dropped = (Number(talk.dropped) || 0) + 1; } // 拼接前丢弃超限半行：内存不尖峰（review P2-5）且显式记数；本轮正常数据照常消费
+  const hadRemain = Boolean(talk.remain);
+  const buf = (hadRemain ? talk.remain : "") + String(txt ?? "");
+  talk.remain = "";
+  if (!buf) return;
+  const lines = buf.split("\n");
+  if (!buf.endsWith("\n")) talk.remain = lines.pop() ?? "";
+  for (let i = 0; i < lines.length; i++) talkConsumeLine(talk, lines[i], hadRemain && i === 0);
+}
+
+/** 流收场回收：把缓冲里缺尾换行的末行按同一单行口径入桶（截断流不静默吞末帧）。幂等；无桶/空缓冲零副作用。 */
+export function captureTalkFlush(talk) {
+  if (!talk || !talk.remain) return;
+  const raw = talk.remain;
+  talk.remain = "";
+  talkConsumeLine(talk, raw, true);
+}
+
+/** 非流式：整块 message 直接入桶（tool_calls 参数本来就是完整的）。 */
+export function captureTalkMessage(talk, msg) {
+  if (!talk || !msg) return;
+  talkPush(talk, "reasoning", msg.reasoning_content ?? msg.reasoning);
+  talkPush(talk, "content", msg.content);
+  if (Array.isArray(msg.tool_calls)) talkMergeToolCalls(talk, msg.tool_calls);
+}
+
+/** 透传兜底：无 chat 帧可解析（纯文本/未知形状）时把原文当正文收下，别让对话日志留空洞。 */
+export function captureTalkFallback(talk, text) {
+  if (!talk || !text) return;
+  if (talk.reasoning.length || talk.content.length || talk.tools.length) return;
+  if (String(text).includes('"choices"')) return;
+  talkPush(talk, "content", String(text));
+}
+
+// 判据必须跑在**完整行**上：TCP 会把一帧切两块，`"finish_reason"`/`"content"` 被切在中间时正则永不命中
+// ⇒ sawFinishReason 恒 null（正常结束的流被 endTruncatedStream 误判成截断，向客户端写假 STREAM_TRUNCATED）、
+// chars 归零（chatShaped 为真时正好命中空轮判据）。与 BUG-24/25 同型：那次是终止标记被切块，这次是观测层缺行缓冲。
+const scanRemain = new WeakMap();
+const SCAN_REMAIN_MAX = 1_000_000; // 半行上限：超限按完整行处理，宁可错判也不无界吃内存
+
+/** 流收场回收：末尾无换行的残行按同一口径扫一次，否则末帧的 finish_reason 永远读不到。幂等。 */
+export function flushScanRemainder(detail) {
+  if (!detail || typeof detail !== "object") return;
+  const rest = scanRemain.get(detail);
+  if (!rest) return;
+  scanRemain.delete(detail);
+  scanCompleteText(detail, rest);
+}
+
+// 逐 SSE chunk 扫描：done/finish_reason/chat 形状/工具调用/usage/正文字符
+export function scanSseChunk(detail, txt) {
+  if (detail.talk) { try { captureTalkSse(detail.talk, txt); } catch {} } // 纯旁路红线：捕获异常绝不外溢成转发失败（review P2-7：旧调用点裸奔在 try 外只是口头契约）
+  let buf = (scanRemain.get(detail) || "") + String(txt ?? "");
+  const rest = buf.slice(buf.lastIndexOf("\n") + 1);
+  if (rest.length > SCAN_REMAIN_MAX) { scanRemain.set(detail, ""); }
+  else { buf = buf.slice(0, buf.length - rest.length); scanRemain.set(detail, rest); }
+  if (buf) scanCompleteText(detail, buf);
+}
+
+function scanCompleteText(detail, txt) {
+  try {
+    if (txt.includes("[DONE]")) detail.sawDone = true;
+    const m = txt.match(/"finish_reason"\s*:\s*"([^"]+)"/);
+    if (m) detail.sawFinishReason = m[1];
+    // chat 形状证据：只有看得出是 chat 轮才配判空（非 chat SSE/JSON 透传是正式契约，不得误伤）
+    if (!detail.chatShaped && (txt.includes('"choices"') || txt.includes('"delta"') || txt.includes('"finish_reason"') || txt.includes('"usage"') || txt.includes('"prompt_tokens"') || txt.includes("[DONE]"))) detail.chatShaped = true;
+    // 工具调用计数（空数组不算）：tool_calls 无正文是合法 agent 轮，
+    // 空转闸门必须豁免它，否则所有工具轮都会被误判为空轮——见 relay-pipeline 4b。
+    // 口径按 `index` 去重：流式 tool_calls 的 arguments 是**分片**到达的，每个分片都含
+    // `"tool_calls":[{"index":N,...` ⇒ 按命中次数累加会把一次调用计成 N 次（实测 4894/5999 帧命中，
+    // 虚高数千倍，且与 scanNonStreamBody 的 `.length` 口径不一致）。去重后与非流式同义。
+    countToolCalls(detail, txt);
+    // 尝试提取 usage（流式末帧）：口径收口到 metrics.js，与未流式分支共用
+    if (txt.includes("\"usage\"") || txt.includes("\"prompt_tokens\"")) {
+      try {
+        const lines = txt.split("\n");
+        for (const line of lines) {
+          const t = line.trim();
+          if (!t.startsWith("data:")) continue;
+          const d = t.slice(5).trim();
+          if (d === "[DONE]" || !d) continue;
+          // 行级隔离：单行坏 JSON 不拖累同 chunk 其余行
+          try {
+            const j = JSON.parse(d);
+            if (!j || typeof j !== "object") continue;
+            const u = extractUsageFromJson(j);
+            if (u) detail.usage = u;
+            // 兜底 chars：从 choices 文本长度累加
+            const delta = j.choices?.[0]?.delta?.content || j.choices?.[0]?.message?.content || "";
+            if (delta) detail.chars += String(delta).length;
+            const rc = j.choices?.[0]?.delta?.reasoning_content || j.choices?.[0]?.delta?.reasoning
+              || j.choices?.[0]?.message?.reasoning_content || j.choices?.[0]?.message?.reasoning || "";
+            if (rc) detail.reasoningChars = (detail.reasoningChars || 0) + String(rc).length;
+          } catch { /* 单行坏帧忽略 */ }
+        }
+      } catch {}
+    } else {
+      // 非 usage 的普通 delta 也累 chars
+      try {
+        const ms = txt.match(/"content"\s*:\s*"([^"]*)"/g);
+        if (ms) for (const mm of ms) {
+          const c = JSON.parse(`{${mm}}`);
+          if (c.content) detail.chars += String(c.content).length;
+        }
+        // 同一 chunk 里的思考增量：键名两种上游都见过（reasoning_content / reasoning）
+        const rs = txt.match(/"reasoning(?:_content)?"\s*:\s*"([^"]*)"/g);
+        if (rs) for (const mm of rs) {
+          const c = JSON.parse(`{${mm}}`);
+          const v = c.reasoning_content ?? c.reasoning;
+          if (v) detail.reasoningChars = (detail.reasoningChars || 0) + String(v).length;
+        }
+      } catch {}
+    }
+  } catch { /* ignore */ }
+}
+
+// 非流式聚合 JSON 体：同源口径提 usage/chars/chat 形状/工具调用
+export function scanNonStreamBody(detail, parsed) {
+  const u = extractUsageFromJson(parsed);
+  if (u) detail.usage = u;
+  if (parsed.choices?.[0]?.message?.content) detail.chars = String(parsed.choices[0].message.content).length;
+  else if (parsed.choices?.[0]?.text) detail.chars = String(parsed.choices[0].text).length;
+  // 思考内容另记（qoder 的 stream:false 出口把思考放在 message.reasoning_content）
+  const rc = parsed.choices?.[0]?.message?.reasoning_content || parsed.choices?.[0]?.message?.reasoning || "";
+  if (rc) detail.reasoningChars = (detail.reasoningChars || 0) + String(rc).length;
+  // 非流式同样只判 chat 形状：无 choices 的任意 JSON 是透传契约（chat-route 单测锁死），不得判空
+  if (Array.isArray(parsed?.choices)) detail.chatShaped = true;
+  const _tcList = parsed.choices?.[0]?.message?.tool_calls;
+  if (Array.isArray(_tcList) && _tcList.length) detail.toolCalls = _tcList.length;
+  if (detail.talk) captureTalkMessage(detail.talk, parsed.choices?.[0]?.message || (parsed.choices?.[0]?.text ? { content: parsed.choices[0].text } : null));
+}
+
+// 上报锚点偏移：转发入口时刻 − 本次上游尝试起点（performance.now 同源）。
+// 只服务上报时长（usage 行），四类保护闸门仍用 relay 自己的 t0，绝不引用它。
+export function preflightMs(t0, attemptStartMs) {
+  // 锚点必须是与 t0 同源（performance.now）的有限 number；其余一律按「无锚点」降级为 0，
+  // 宁可退回修复前口径，也不能产出 NaN 或假高值
+  if (typeof attemptStartMs !== "number" || !Number.isFinite(attemptStartMs)) return 0;
+  const delta = Math.round(t0 - attemptStartMs);
+  return delta > 0 ? delta : 0;
+}
+
+/**
+ * 空轮判据（纯函数，唯一真相）：看得 chat 形状 + 零正文 + 零工具调用 + 收尾不是工具轮。
+ * stream.js 用它决定「这次要不要封口」，relay-pipeline 用它决定「交不交回重试」——两处不得各写一份。
+ * chatShaped 是前置证据：非 chat SSE / 无 choices 的透传是正式契约，一律放行不判空。
+ */
+export function isEmptyTurnDetail(d) {
+  if (!d || d.chatShaped !== true) return false;
+  if ((Number(d.chars) || 0) > 0 || (Number(d.toolCalls) || 0) > 0) return false;
+  if (["tool_calls", "function_call"].includes(d.sawFinishReason)) return false;
+  return true;
+}
+
+// ===== 从 stream.js 迁入（体积门：stream.js 承载 relay 本体，纯判定函数一律住这里）=====
+
+// 错误包络 chunk 判定（纯函数）：data 行 JSON 含顶层 .error 对象、或只有 finish_reason=error
+// 的空帧，且整 chunk 无任何 content/tool_calls/reasoning 输出 → 返回错误摘要（建议暂扣），
+// 否则返回 null（透传）。解析失败一律透传（默认保安全）。
+// 背景：网关把上游失败包成 HTTP 200 SSE；暂扣后下游流式 UI 不再展示瞬时错误
+//（如 Vertex 503 + google fallback 400），本轮走空转重试，客户端只看到最终结果。
+// Note: 流内错误包络捕获与 retryAfterSeconds 错误直出 — 见 .agents/notes/implemented/bug-fix/2026-09-28-retry-after-surfacing-error.md
+export function extractRetryAfterSec(obj) {
+  if (!obj) return null;
+  if (typeof obj === "number") return obj;
+  if (typeof obj === "string") {
+    const m = obj.match(/"retryAfterSeconds"\s*:\s*(\d+)/i) || obj.match(/\bretryAfterSeconds\s*[:=]\s*(\d+)/i);
+    if (m) return Number(m[1]);
+    try {
+      const parsed = JSON.parse(obj);
+      return extractRetryAfterSec(parsed);
+    } catch {}
+  }
+  if (typeof obj === "object") {
+    if (Number.isFinite(obj.retryAfterSeconds)) return Number(obj.retryAfterSeconds);
+    if (obj.message) {
+      const r = extractRetryAfterSec(obj.message);
+      if (r != null) return r;
+    }
+  }
+  return null;
+}
+
+export function holdableChunk(txt) {
+  if (typeof txt !== "string" || !txt.includes("data:")) return null;
+  let sawData = false;
+  let sawEventError = false;
+  let retrySec = null;
+  const errs = [];
+  for (const rawLine of txt.split("\n")) {
+    const t = rawLine.trim();
+    if (t.startsWith("event:") && t.slice(6).trim() === "error") {
+      sawEventError = true;
+      continue;
+    }
+    if (!t.startsWith("data:")) continue;
+    const d = t.slice(5).trim();
+    if (!d || d === "[DONE]") continue;
+    let j = null;
+    try { j = JSON.parse(d); } catch { return null; }
+    if (!j || typeof j !== "object") return null;
+    sawData = true;
+    const c0 = (Array.isArray(j.choices) && j.choices[0]) || {};
+    const delta = c0.delta || {};
+    const msg = c0.message || {};
+    const out = delta.content || msg.content || delta.tool_calls || msg.tool_calls || delta.reasoning || msg.reasoning;
+    if (out && !(Array.isArray(out) && out.length === 0)) return null;
+
+    const r = extractRetryAfterSec(j);
+    if (r != null) {
+      retrySec = r;
+      continue;
+    }
+    if (j.error && typeof j.error === "object") {
+      const m = j.error.message || j.error.code || "";
+      if (m) errs.push(String(m).slice(0, 300));
+    } else if (sawEventError && j.message) {
+      errs.push(String(j.message).slice(0, 300));
+    } else if (c0.finish_reason === "error") {
+      errs.push("finish_reason=error 空帧");
+    }
+  }
+  if (!sawData) return null;
+  if (retrySec != null) return `上游供应商触发 retryAfterSeconds: ${retrySec} ，请等候重试`;
+  if (errs.length) return errs.join(" | ");
+  if (sawEventError) return "event: error 空帧";
+  return null;
+}
+
+/**
+ * 「可撤销前缀」判据（纯函数）：这个 chunk 里除空 delta 帧与 [DONE] 外不含任何信息吗？
+ * 只有答案为是才允许暂扣不写——透传是正式契约：解析失败的帧、看不懂的形状一律立即透传（与
+ * holdableChunk 同一口径：默认保安全，绝不因为想救空轮而扣掉本该原样转给客户端的字节）。
+ */
+export function isTrivialFrame(txt) {
+  if (typeof txt !== "string" || !txt.includes("data:")) return false;
+  let sawData = false;
+  for (const rawLine of txt.split("\n")) {
+    const t = rawLine.trim();
+    if (!t.startsWith("data:")) continue;
+    const d = t.slice(5).trim();
+    if (!d) continue;
+    if (d === "[DONE]") { sawData = true; continue; } // 结束符不含模型输出，可撤销
+    let j = null;
+    try { j = JSON.parse(d); } catch { return false; } // 解析失败 → 透传，绝不撤销
+    if (!j || typeof j !== "object" || Array.isArray(j)) return false;
+    // 白名单式可撤销：只认「choices 数组、且其中没有任何文本载荷」的 chat 帧。
+    // 其余形状（choices[].text、delta.text、顶层 usage、无 choices 的自定义帧……）一律算有信息 → 透传。
+    if (!Array.isArray(j.choices)) return false;
+    sawData = true;
+    if (j.choices.some((c) => c && typeof c === "object" && (c.text || c.message?.text))) return false;
+    for (const c of j.choices) {
+      if (!c || typeof c !== "object") return false;
+      for (const src of [c.delta, c.message]) {
+        if (!src || typeof src !== "object") continue;
+        for (const [k, v] of Object.entries(src)) {
+          if (k === "role" || k === "index" || k === "function_call_name") continue; // 无信息骨架字段
+          if (v == null || v === "") continue;
+          if (Array.isArray(v) ? v.length > 0 : true) return false; // 任何非空载荷都算产出
+        }
+      }
+    }
+  }
+  return sawData;
+}