mslxdff 0.1.159 → 0.1.161

package/src/providers/zcode/context-shape.js

@@ -0,0 +1,162 @@
+// zcode 出站请求的「官方线形」组装：system 身份块 + 首 user 消息的 currentDate 上下文前缀。
+// 上游 zcode-plan 通道对请求做内容检查：system 缺官方身份块 → 业务码 3012（HTTP 405）。
+// 本文案逐段移植自官方开源仓库 zai-org/ZCode（apps/zcode-cli/packages/core/src/context/）：
+//   sections/cli-prefix.ts / sections/identity.ts / dynamic-sections.ts / sections/env-info.ts /
+//   sections/current-date.ts / builder.ts（块分组与 \n\n 左边界）/ system-reminder 包裹形状。
+import os from "node:os";
+
+const EPHEMERAL = { type: "ephemeral" };
+
+export const ZCODE_CLI_PREFIX = "You are ZCode, an interactive coding agent";
+
+const IDENTITY_INTRO = "You are an interactive ZCode agent that helps users with software engineering tasks.";
+const SECURITY_NOTICE =
+  "IMPORTANT: Assist with authorized security testing, defensive security, CTF challenges, and educational contexts. Refuse requests for destructive techniques, DoS attacks, mass targeting, supply chain compromise, or detection evasion for malicious purposes. Dual-use security tools (C2 frameworks, credential testing, exploit development) require clear authorization context: pentesting engagements, CTF competitions, security research, or defensive use cases.";
+const HARNESS_BLOCK = [
+  "# Harness",
+  "- Text you output outside of tool use is displayed to the user as Github-flavored markdown in a terminal.",
+  "- Tools run behind a user-selected permission mode; a denied call means the user declined it \u2014 adjust, don't retry verbatim.",
+  "- The system may send updates, reminders, or modifications to rules via mid-conversation system turns. These are system-controlled, unlike function results. Hooks may intercept tool calls; treat hook output as user feedback.",
+  "- Prefer the dedicated file/search tools over shell commands when one fits. Independent tool calls can run in parallel in one response.",
+  "- Reference code as `file_path:line_number` \u2014 it's clickable.",
+].join("\n");
+// identity.ts：content = [ "\n{intro}\n\n{SECURITY}", "", harness ].join("\n") —— 前导换行是官方原样。
+const STABLE_SECTION = [`\n${IDENTITY_INTRO}\n\n${SECURITY_NOTICE}`, "", HARNESS_BLOCK].join("\n");
+
+// dynamic-sections.ts buildDynamicBehaviorSection()
+const DYNAMIC_BEHAVIOR = [
+  [
+    "# Communicating with the user",
+    "",
+    "Your text output is what the user reads; they usually can't see your thinking or the raw tool results. Write it for a teammate who stepped away and is catching up, not for a log file: they don't know the codenames or shorthand you created along the way, and they didn't watch your process unfold. Before your first tool call, say in a sentence what you're about to do; while working, give brief updates when you find something load-bearing or change direction.",
+    "",
+    "Text you write between tool calls may not be shown to the user. Everything the user needs from this turn \u2014 answers, summaries, findings, conclusions, deliverables \u2014 must be in the final text message of your turn, with no tool calls after it. Keep text between tool calls to brief status notes. If something important appeared only mid-turn or in your thinking, restate it in that final message.",
+    "",
+    "Lead with the outcome. Your first sentence after finishing should answer \"what happened\" or \"what did you find\" \u2014 the thing the user would ask for if they said \"just give me the TLDR.\" Supporting detail and reasoning come after, for readers who want them.",
+    "",
+    "Being readable and being concise are different things, and readable matters more. If the user has to reread your summary or ask you to explain, any time saved by brevity is gone. The way to keep output short is to be selective about what you include (drop details that don't change what the reader would do next), not to compress the writing into fragments, abbreviations, arrow chains like `A \u2192 B \u2192 fails`, or jargon. What you do include, write in complete sentences with the technical terms spelled out. Don't make the reader cross-reference labels or numbering you invented earlier; say what you mean in place.",
+    "",
+    "Match the response to the question: a simple question gets a direct answer in prose, not headers and sections. Use tables only for short enumerable facts, with explanations in the surrounding prose rather than the cells. Calibrate to the user \u2014 a bit tighter for an expert, more explanatory for someone newer.",
+  ].join("\n"),
+  "",
+  "Write code that reads like the surrounding code: match its comment density, naming, and idiom.",
+  "Only write a code comment to state a constraint the code itself can't show \u2014 never to say where it came from, what the next line does, or why your change is correct; that's you talking to the reviewer, not the next reader, and it's noise the moment the PR merges.",
+  "",
+  "For actions that are hard to reverse or outward-facing, confirm first unless durably authorized or explicitly told to proceed without asking; approval in one context doesn't extend to the next. Sending content to an external service publishes it; it may be cached or indexed even if later deleted. Before deleting or overwriting, look at the target \u2014 if what you find contradicts how it was described, or you didn't create it, surface that instead of proceeding. Report outcomes faithfully: if tests fail, say so with the output; if a step was skipped, say that; when something is done and verified, state it plainly without hedging.",
+].join("\n");
+
+// dynamic-sections.ts buildContextManagementSection()
+const CONTEXT_MANAGEMENT = [
+  ["# Context management", "When the conversation grows long, some or all of the current context is summarized; the summary, along with any remaining unsummarized context, is provided in the next context window so work can continue \u2014 you don't need to wrap up early or hand off mid-task."].join("\n"),
+  "",
+  "When you have enough information to act, act. Do not re-derive facts already established in the conversation, re-litigate a decision the user has already made, or narrate options you will not pursue. If you are weighing a choice, give a recommendation, not an exhaustive survey",
+  "",
+  "You are operating autonomously. The user is not watching in real time and cannot answer questions mid-task, so asking 'Want me to\u2026?' or 'Shall I\u2026?' will block the work. For reversible actions that follow from the original request, proceed without asking. Stop only for destructive actions or genuine scope changes the user must decide. Offering follow-ups after the task is done is fine; asking permission before doing the work is not.",
+  "",
+  "Exception: when the user is describing a problem, asking a question, or thinking out loud rather than requesting a change, the deliverable is your assessment. Report your findings and stop. Don't apply a fix until they ask for one.",
+  "",
+  "Before ending your turn, check your last paragraph. If it is a plan, an analysis, a question, a list of next steps, or a promise about work you have not done ('I'll\u2026', 'let me know when\u2026'), do that work now with tool calls. That includes retrying after errors and gathering missing information yourself. Do not stop because the context or session is long. End your turn only when the task is complete or you are blocked on input only the user can provide.",
+  "",
+  "Before running a command that changes system state \u2014 restarts, deletes, config edits \u2014 check that the evidence actually supports that specific action. A signal that pattern-matches to a known failure may have a different cause.",
+].join("\n");
+
+// builder.ts buildContextMetaUserBody() 的 intro/outro（current-date.ts 的正文夹在中间）
+const CONTEXT_INTRO = "As you answer the user's questions, you can use the following context:";
+const CONTEXT_OUTRO = "      IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.";
+const REMINDER_OPEN = "<system-reminder>";
+const REMINDER_CLOSE = "</system-reminder>";
+
+function localIsoDate(d = new Date()) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+function normalizeCallerSystem(system) {
+  const out = [];
+  if (typeof system === "string") {
+    if (system.trim()) out.push({ type: "text", text: system });
+  } else if (Array.isArray(system)) {
+    for (const item of system) {
+      if (typeof item === "string") {
+        if (item.trim()) out.push({ type: "text", text: item });
+      } else if (item && typeof item === "object" && item.type === "text" && typeof item.text === "string" && item.text.trim()) {
+        out.push({ type: "text", text: item.text });
+      }
+    }
+  }
+  return out;
+}
+
+// env-info.ts buildEnvInfoContent()：CLI 无 git 上下文的固定形态
+function buildEnvironmentSection({ cwd, model, provider, platform, shell, osVersion }) {
+  const lines = [
+    "# Environment",
+    "You have been invoked in the following environment:",
+    `- Primary working directory: ${cwd}`,
+    "- Is a git repository: no",
+    `- Platform: ${platform}`,
+    `- Shell: ${shell}`,
+    `- OS Version: ${osVersion}`,
+  ];
+  if (model) lines.push(`- You are powered by the model named ${provider}-api/${model}.`);
+  return lines.join("\n");
+}
+
+/**
+ * 官方式 system 块数组：cliPrefix / stable / dynamic（\n\n 左边界）三块均带 ephemeral，
+ * 调用方原 system 追加在末尾（不进官方缓存块）。
+ */
+export function buildZcodeSystemBlocks({ system, model, provider = "zai", cwd = process.cwd(), now = new Date(), platform, shell, osVersion } = {}) {
+  const env = buildEnvironmentSection({
+    cwd,
+    model,
+    provider,
+    platform: platform || process.platform,
+    shell: shell || (process.platform === "win32" ? "cmd" : (process.env.SHELL || "sh")),
+    osVersion: osVersion || os.release(),
+  });
+  const dynamic = [DYNAMIC_BEHAVIOR, env, CONTEXT_MANAGEMENT].join("\n\n");
+  const official = [
+    { type: "text", text: ZCODE_CLI_PREFIX, cache_control: { ...EPHEMERAL } },
+    { type: "text", text: STABLE_SECTION, cache_control: { ...EPHEMERAL } },
+    // builder.ts:270-271：Main Agent 的 dynamic system block 自带 \n\n 左边界
+    { type: "text", text: `\n\n${dynamic}`, cache_control: { ...EPHEMERAL } },
+  ];
+  return [...official, ...normalizeCallerSystem(system)];
+}
+
+/** 首 user 消息的 currentDate 上下文块（builder.ts meta_user → system-reminder 包裹）。 */
+export function buildZcodeContextPrefixBlock(now = new Date()) {
+  const body = [
+    CONTEXT_INTRO,
+    `# currentDate\nToday's date is ${localIsoDate(now)}.`,
+    "",
+    CONTEXT_OUTRO,
+  ].join("\n");
+  return { type: "text", text: `${REMINDER_OPEN}\n${body}\n${REMINDER_CLOSE}` };
+}
+
+/** 把上下文前缀挂到首个 user 消息 content 最前（字符串 content 升格为块数组；已挂则不动）。 */
+export function attachZcodeContextPrefix(messages, now = new Date()) {
+  if (!Array.isArray(messages) || messages.length === 0) return messages;
+  const first = messages[0];
+  if (!first || first.role !== "user") return messages;
+  const content = Array.isArray(first.content)
+    ? first.content
+    : [{ type: "text", text: String(first.content ?? "") }];
+  if (content.some((c) => c?.type === "text" && typeof c.text === "string" && c.text.startsWith(REMINDER_OPEN))) {
+    return messages;
+  }
+  return [{ ...first, content: [buildZcodeContextPrefixBlock(now), ...content] }, ...messages.slice(1)];
+}
+
+/** 内部 Anthropic 请求 → 官方出站线形：小写模型名 + 身份 system 块 + currentDate 前缀，其余透传。 */
+export function shapeZcodeWireRequest(req = {}, { cwd, provider = "zai", now = new Date() } = {}) {
+  const model = typeof req.model === "string" ? req.model.toLowerCase() : req.model;
+  return {
+    ...req,
+    model,
+    system: buildZcodeSystemBlocks({ system: req.system, model, provider, cwd, now }),
+    messages: attachZcodeContextPrefix(req.messages, now),
+  };
+}

package/src/providers/zcode/headers.js

@@ -53,3 +53,41 @@ export function buildZcodeHeaders(opts = {}) {
   if (token) headers["Authorization"] = `Bearer ${token}`;
   return headers;
 }
+
+// 模型请求专用形态（zcode-plan 通道）：与官方 CLI 出站同形 —— 双鉴权头、ai-sdk UA、
+// x-title=cli、production 渠道、anthropic-version、gzip；**不带** X-Device-Mid，
+// **不带** 验证码头（v3.14.4 起模型请求免校验，client/configs captcha.skip_model_request=true）。
+export function buildZcodeModelHeaders(opts = {}) {
+  const ver = normalizeHeaderValue(opts.version) ?? zcodeAppVersion();
+  const platform = normalizeHeaderValue(opts.platform) ?? process.platform;
+  const arch = normalizeHeaderValue(opts.arch) ?? process.arch;
+  const intl = (() => { try { return Intl.DateTimeFormat().resolvedOptions() || {}; } catch { return {}; } })();
+  const language = normalizeHeaderValue(opts.lang) ?? normalizeHeaderValue(intl.locale) ?? "unknown";
+  const timeZone = normalizeHeaderValue(opts.tz) ?? normalizeHeaderValue(intl.timeZone) ?? "unknown";
+  const osVersion = "osVersion" in opts ? normalizeHeaderValue(opts.osVersion) : normalizeHeaderValue(os.release());
+  const token = normalizeHeaderValue(opts.token);
+  const headers = {
+    "accept-encoding": "gzip",
+    "anthropic-version": "2023-06-01",
+    "authorization": token ? `Bearer ${token}` : undefined,
+    "http-referer": ZCODE_ORIGIN,
+    "user-agent": `ZCode/${ver} ai-sdk/anthropic/3.0.81`,
+    "x-api-key": token,
+    "x-client-language": language,
+    "x-client-timezone": timeZone,
+    "x-os-category": osCategory(platform),
+    "x-platform": `${platform}-${arch}`,
+    "x-release-channel": "production",
+    "x-request-id": normalizeHeaderValue(opts.requestId) ?? uuid(),
+    "x-title": "Z Code@cli",
+    "x-zcode-agent": "glm",
+    "x-zcode-app-version": ver,
+    "x-zcode-session-type": "main",
+    "x-zcode-trace-id": normalizeHeaderValue(opts.traceId) ?? uuid(),
+  };
+  if (osVersion) headers["x-os-version"] = osVersion;
+  for (const k of Object.keys(headers)) {
+    if (headers[k] === undefined) delete headers[k];
+  }
+  return headers;
+}

package/src/providers/zcode/sse.js

@@ -1,5 +1,7 @@
 // Anthropic SSE → OpenAI 形状转换（流式 / 聚合两种出口）。
-// 承诺字段：文本增量、tool_use 增量（tool_calls）、usage、finish_reason；thinking 块丢弃（不入历史）。
+// 承诺字段：文本增量、thinking 增量（reasoning_content）、tool_use 增量（tool_calls）、usage、finish_reason。
+// thinking 跨轮回填：首个 thinking block 的 signature 随 reasoning_content 挂在 assistant 历史消息上（必须，
+// 上游要求 signature 与 thinking 原文一起回传；与 reasoning_content_signature 拼写不同的上游见下兼容）。
 const ENCODER = new TextEncoder();
 const DECODER = new TextDecoder();
 const STOP_REASONS = { end_turn: "stop", max_tokens: "length", tool_use: "tool_calls", stop_sequence: "stop", pause_turn: "stop" };
@@ -26,6 +28,9 @@ export function createAnthropicTranslator({ model = "zcode", id = newId(), creat
   let inputTokens = null;
   let outputTokens = null;
   let text = "";
+  // thinking 全量文本（聚合出口回填 reasoning_content）与首个 signature（跨轮必需，见文件头）
+  let thinkingText = "";
+  let thinkingSig = null;
   let toolCount = 0;
   const toolIndexByBlock = new Map();
   const toolCalls = [];
@@ -55,7 +60,12 @@ export function createAnthropicTranslator({ model = "zcode", id = newId(), creat
       }
     } else if (evt.type === "content_block_start") {
       const block = evt.content_block || {};
-      if (block.type === "tool_use") {
+      if (block.type === "thinking") {
+        // 首个 thinking 块的 signature 留给聚合出口的跨轮回填（后续 thinking 块没有也必须回传空串占位——
+        // codearts 的 DeepSeek 同款要求，见 src/providers/codearts/chat.js）
+        if (thinkingSig === null && typeof block.signature === "string") thinkingSig = block.signature;
+        if (typeof block.thinking === "string" && block.thinking) thinkingText += block.thinking;
+      } else if (block.type === "tool_use") {
         const idx = toolCount++;
         toolIndexByBlock.set(Number(evt.index), idx);
         toolCalls.push({ id: String(block.id || `toolu_${idx}`), name: String(block.name || ""), args: "" });
@@ -66,6 +76,10 @@ export function createAnthropicTranslator({ model = "zcode", id = newId(), creat
       if (d.type === "text_delta" && typeof d.text === "string") {
         text += d.text;
         out.push(chunkLine({ content: d.text }));
+      } else if (d.type === "thinking_delta" && typeof d.thinking === "string") {
+        thinkingText += d.thinking;
+        if (typeof d.signature === "string" && d.signature && thinkingSig === null) thinkingSig = d.signature;
+        out.push(chunkLine({ reasoning_content: d.thinking }));
       } else if (d.type === "input_json_delta" && typeof d.partial_json === "string") {
         const idx = toolIndexByBlock.has(Number(evt.index)) ? toolIndexByBlock.get(Number(evt.index)) : Math.max(0, toolCount - 1);
         if (toolCalls[idx]) toolCalls[idx].args += d.partial_json;
@@ -113,6 +127,9 @@ export function createAnthropicTranslator({ model = "zcode", id = newId(), creat
 
   function result() {
     const message = { role: "assistant", content: text || null };
+    // thinking 聚合回填：跨轮必需的 signature 与原文一起带回（见文件头；codearts DeepSeek 同款）
+    if (thinkingText) message.reasoning_content = thinkingText;
+    if (thinkingSig !== null) message.reasoning_content_signature = thinkingSig;
     if (toolCalls.length) {
       message.tool_calls = toolCalls.map((t) => ({ id: t.id, type: "function", function: { name: t.name, arguments: t.args || "{}" } }));
       if (!text) message.content = null;

package/src/routes/AGENTS.md

@@ -0,0 +1,37 @@
+# src/routes — 转发链契约（改 relay / 流式 / 用量前必读）
+
+> 从 `AGENTS.md` 下沉（2026-09-29 分层，就近生效）。改完跑：`node --test --test-concurrency=1 test/stream-*.test.js test/relay-*.test.js test/usage-*.test.js` + `npm run docs:check`。
+
+## 时间量测的两条口径（ADR-0039，最易被改错）
+
+- **保护闸门的零点 = `relay()` 入口的 `t0`**（首帧超时 / stall / MAX_STREAM / keepalive 四类）。**禁止**把上报锚点接进闸门判定，否则上游排队时间会吃掉超时预算、误杀正在出字的慢模型。
+- **上报时长（usage 行）的零点 = 本次上游尝试起点**（`serial-trial` 的 `tUp`，经 `attemptStartMs` 交进 relay）；relay 入口算 `preflightMs = t0 − 锚点` 并随**全部 4 个 return 点**带出，`relay-pipeline` 落行时相加。锚点缺失/负值一律 0。
+- 报表口径与 state 口径**彻底分离**：`recordModelStats`（→ `-status`/`-model stats` 的 EMA）仍吃转发入口相对值，勿"顺手统一"。
+- 首字与总耗时同加一个常数 → `总 − 首字` 恒等 → 速度读数不变（已锁为单测）。
+- usage 行**只增字段**演进（`src/usage/record.js` 拥有行形状）；旧行缺字段 = 未知，不得当 0。
+- 模型日志里 `relay-first-chunk ttfMs=` 是**转发入口相对值**（故意与报表不同源），排查时别混。
+
+## relay 的行为契约（既有测试锁死）
+
+- **超时是显式字段 `timedOut`**，`status` 数值只是 HTTP 语义展示，不得再拿 status 当"是否可 failover"的信号。
+- **注释帧（`: keepalive`）不算首块**：不解除闸门、不触发超时救回，但照常透传；能否安全 failover 看 `detail.wrotePayload`（=是否已**提交**模型产出，见下条留口）。
+- 闸门到点后上游仍吐出真实数据 → **撤销超时判定照常转发**（cancel 是异步的，竞态窗口内已到达的数据是纯收益），记 `detail.recoveries`。
+- 任一闸门到点且未写真实数据 → 回退候选；唯一/末位候选无 failover 去向 → 闸门放宽到 `MSLXDFF_LAST_CANDIDATE_TIMEOUT_MS`（默认 120s，0=不限），防误杀慢模型。
+- **空转 200 判据单一真相** = `stream-scan.js:isEmptyTurnDetail`（`chatShaped===true` 且 `chars===0 && toolCalls===0` 且 `finish_reason ∉ {tool_calls, function_call}`）；relay 侧「要不要封口」与 pipeline 5a0「要不要重拉」都必须用它，两处各写一份必然错拍。判空 → 转 failover，不记 auto 冷却（空转≠模型坏）。错误包络暂扣 `holdableChunk` 与非 chat 形状放行同在 `stream-scan.js`（**不在 stream.js**）。
+- **空轮留口（ADR-0043）**：模型产出（正文/工具/**思考**）出现前，空 delta 帧与 `[DONE]` 一律暂扣不写（`stream-hold.js:createRevocablePrefix`）；流结束仍零产出且未断下游 → **不 `res.end()`**，返回 `heldOpen:true` 交回重拉/换候选，正文续写同一条连接。三条铁律：① 异形/解析失败帧必须立即透传（`isTrivialFrame` 白名单式），透传契约不得为救空轮让路；② `[DONE]` 是终点，错误帧要排在它之前（tail 槽）且全程只允许一个；③ 重入同一条连接时 headers 可能已 flush → `statusCode`/`setHeader` 一律门控，收场经 `endHeldFailure`/`endEmptyTurnStream`/`helpers.json` 的 `writableEnded`+`headersSent` 守卫保证**恰好一次**，禁止把 JSON 体混进 `text/event-stream`。
+- 断下游即掐上游：relay 自持 `reader`（`for-await` 会锁 ReadableStream 使 `body.cancel()` 必 reject），`reader.cancel()` 才真掐得断。
+
+## 组/组员与宽带中继（`src/routes/groups*.js`、`peers.js`、`relay-queue.js`）
+
+- 慢模型不掐当前流：首块 25s 内到即视为可用、后续无限等；stall 15s 仅作质量分，耗时 >20s 降权；`MSLXDFF_HEDGE_DELAY_MS=1000` 时 1s 并发组员赛跑，赢家 `x-mslxdff-via`；指定模型 429 时按延迟 EMA 择优切最快模型。
+- `SLOW_TOTAL_MS=20s` 标 slow 进 5 分钟冷却（普通 60s）；上游重试 `1次×100ms`；`MSLXDFF_STREAM_TIMEOUT_MS=25s`（**仅首块未到且未写出任何字节时**才 failover；`0`=显式关闭首块超时，给重思考模型用）；`MAX_STREAM_MS=120s`。
+- 宽带 `relay://` 成员走 `GET /v1/groups/relay/stream` SSE 单长连 25s ping 直推（`pushToStream`），`MSLXDFF_BROADBAND_STREAM=0` 回退 1s poll，`MSLXDFF_BROADBAND_PING_MS=25000`/`_STALE_MS=90000` 可配（空闲 -96%）；用户明确反对 1s 轮询的空轮询。
+- 组命令语义：`-group list` 序号按 state 成员顺序（过滤 leader）固定渲染，`-group remove <seq>` 用同一顺序踢人（仅组长）；组长 `-leavegroup` 提示改用 `-delgroup`，`-delgroup` 在组员节点报错并提示该组由谁领导。
+- 模型可观测面：事件用**黑名单** `TRACE_DENY`（默认全可见，只排噪声与敏感面）；决定类事件只渲染 `DECISION_FIELDS` 登记过的标量，**"加日志"≠"倒数据"**，payload/正文一律不落；回显取头单一入口 `upstreamEcho(res)`。
+
+## Responses 端点（`routes/responses-route.js` + `responses/translate.js`，ADR-0012）
+
+- 复用 ChatPipeline 全链路，只做形状翻译；stateless（`previous_response_id` 不支持，thinking reasoning 暂不透传）。
+- Codex Rust 严格解码三特例（缺一整轮作废）：① 对 codex 调用者（UA/originator `codex_*` 或 `?client_version=`）`GET /v1/models` 追加顶层 `models: []`（**必须空**，填真目录会覆盖其内置 agent prompt）；② completed 的 usage 转 Responses 口径（`input_tokens/output_tokens` + details）；③ done 事件 `text` 带累积全文。
+- `-setto chatgpt`（`src/sync-codex.js`）写三端共用 `~/.codex/config.toml`（`wire_api="responses"` 显式、鉴权绝对路径 `node + -showtoken`，换模型需重跑 setto / `codex exec -m` / 手改 `model=`，单键覆盖无需剪枝）；排障 `MSLXDFF_RESPONSES_DEBUG=1` 看 `daemon.log [responses]` 四段 + Codex 侧 `~/.codex/logs_2.sqlite`（`Request completed ... status=`）与 `thread_history_1.sqlite`（正文）。
+- `@ai-sdk/openai` 只是客户端包，替代不了服务端翻译层；Qwen 上游走 `/v1/messages`（Anthropic 协议），接 Codex 要多一跳（未做）。

package/src/routes/chat/broadband-handler.js

@@ -21,6 +21,7 @@ export async function handleBroadbandRelay({
   evt,
   mark,
   perf0,
+  attemptStartMs,
   stages,
   res,
   startedAt,
@@ -48,7 +49,7 @@ export async function handleBroadbandRelay({
   });
   const isResponse = bb.result && typeof bb.result.status === "number" && typeof bb.result.headers?.get === "function";
   if (isResponse) {
-    const r = await pipeline.execute({ res, upRes: bb.result, body, requested, actual: model, lastErr, via: "broadband", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    const r = await pipeline.execute({ res, upRes: bb.result, body, requested, actual: model, lastErr, via: "broadband", lockModel, useAuto, handlerCtx, mark, perf0, attemptStartMs, stages, startedAt });
     if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
     return { handled: true };
   }
@@ -62,7 +63,7 @@ export async function handleBroadbandRelay({
       text: async () => str,
       body: isSSE ? (async function* () { yield Buffer.from(str); })() : null,
     };
-    const r = await pipeline.execute({ res, upRes: fakeRes, body, requested, actual: model, lastErr, via: "broadband-local", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    const r = await pipeline.execute({ res, upRes: fakeRes, body, requested, actual: model, lastErr, via: "broadband-local", lockModel, useAuto, handlerCtx, mark, perf0, attemptStartMs, stages, startedAt });
     if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
     return { handled: true };
   }

package/src/routes/chat/exhausted-handler.js

@@ -1,7 +1,16 @@
 // Note: 失败收尾四分支在 result 后补 client-response，与成功路径对账口径一致（result 条数 == client-response 条数）— 见 .agents/notes/implemented/bug-fix/2026-09-25-sdk-headers-timeout-and-failure-client-response.md
 import { relay } from "../stream.js";
+import { endHeldFailure } from "../stream-hold.js"; // 终局收场出口（502 JSON 或 SSE 错误帧 + [DONE]）
 import { json } from "../helpers.js";
 import { performance } from "node:perf_hooks";
+import { recordRelayTalk } from "../../talk-log.js"; // 环形对话日志：exhausted 收尾直连 relay，落盘点必须自己补一份
+
+// 最后一站的收场：relay 的「不写响应」路径（超时 / 空轮延后封口）都汇到这里，没有上层 failover 了，
+// 必须把响应「恰好一次」地关掉。形状由 endHeldFailure 按 headers 是否已 flush 决定
+// （未 flush → 502 JSON；已 flush 的 SSE → 错误帧 + [DONE]），这里不再自己 json() 打已 flush 的流。
+function terminal(res, message) {
+  endHeldFailure(res, message || "all auto models failed");
+}
 
 export async function handleExhaustedLocal({ res, body, lastErr, order, handlerCtx, evt, logCall, mark, perf0, stages, done, requested, useAuto, deps = {} }) {
   const { relay: relayImpl = relay } = deps;
@@ -15,18 +24,22 @@ export async function handleExhaustedLocal({ res, body, lastErr, order, handlerC
       onDownstreamAbort: () => evt("client-abort", { reqId: handlerCtx.reqId, model: lastErr.model, totalMs: Math.round(performance.now() - perf0), stages: [...stages] }),
     });
     evt("relay-done", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-exhausted", status: out.status, ttfMs: out.ttfMs, totalMs: out.totalMs, aborted: out.aborted, interrupted: out.interrupted ?? false, detail: out.detail ?? null });
+    // 绕过 relay-pipeline 的最后一站：对话日志照常落盘（正文只进 talk/*.log，不进 events.log）
+    try { recordRelayTalk({ reqId: handlerCtx.reqId, model: lastErr.model, via: "local-exhausted", body, out }); } catch {}
     evt("result", { reqId: handlerCtx.reqId, model: lastErr.model, status: out.status, via: "local", timing: lastErr.upstream._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null });
     evt("client-response", { requested, actual: lastErr.model, via: "local", fallback: false, status: out.status, reqId: handlerCtx.reqId });
-    // 最后一站：relay 超时路径不写响应（设计留给上层 failover），这里没有上层，必须自己收尾
-    if (out.timedOut) {
-      json(res, 502, { error: out.detail?.upstreamError ? `upstream error: ${out.detail.upstreamError}` : `stream timed out after ${out.totalMs}ms` });
+    // 最后一站：relay 超时/空轮留口路径都不写响应，这里没有上层，必须自己收尾
+    if (out.timedOut || out.heldOpen) {
+      terminal(res, out.detail?.exitReason === "empty-turn-hold"
+        ? "EMPTY_MODEL_RESPONSE: 空轮重拉与换候选全部用尽，仍无正文"
+        : out.detail?.upstreamError ? `upstream error: ${out.detail.upstreamError}` : `stream timed out after ${out.totalMs}ms`);
     }
     return true;
   }
   evt("result", { reqId: handlerCtx.reqId, model, status: lastErr?.status ?? 502, via: "none", timing: null });
   evt("client-response", { requested, actual: model, via: "none", fallback: false, status: lastErr?.status ?? 502, reqId: handlerCtx.reqId });
   done({ via: "none", status: lastErr?.status ?? 502, error: lastErr?.message || "all auto models failed" });
-  json(res, 502, { error: lastErr?.message || "all auto models failed" });
+  terminal(res, lastErr?.message);
   return true;
 }
 
@@ -41,16 +54,18 @@ export async function handleExhaustedAll({ res, body, lastErr, order, requested,
       onDownstreamAbort: () => evt("client-abort", { reqId: handlerCtx.reqId, model: lastErr.model, totalMs: Math.round(performance.now() - perf0), stages: [...stages] }),
     });
     evt("relay-done", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-final", status: out.status, ttfMs: out.ttfMs, totalMs: out.totalMs, aborted: out.aborted, interrupted: out.interrupted ?? false, detail: out.detail ?? null });
+    // 同上：全链耗尽的最终转发也要留下问答原文
+    try { recordRelayTalk({ reqId: handlerCtx.reqId, model: lastErr.model, via: "local-final", body, out }); } catch {}
     evt("result", { reqId: handlerCtx.reqId, model: lastErr.model, status: out.status, via: "local", timing: lastErr.upstream._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null });
     evt("client-response", { requested, actual: lastErr.model, via: "local", fallback: false, status: out.status, reqId: handlerCtx.reqId });
-    // 最后一站：relay 超时路径不写响应，这里没有上层 failover，必须自己收尾
-    if (out.timedOut) {
-      json(res, 502, { error: out.detail?.upstreamError ? `upstream error: ${out.detail.upstreamError}` : `stream timed out after ${out.totalMs}ms` });
+    // 最后一站：relay 超时/空轮留口路径不写响应，这里没有上层 failover，必须自己收尾
+    if (out.timedOut || out.heldOpen) {
+      terminal(res, out.detail?.upstreamError ? `upstream error: ${out.detail.upstreamError}` : `stream timed out after ${out.totalMs}ms`);
     }
     return true;
   }
   evt("result", { reqId: handlerCtx.reqId, model: lastErr?.model ?? requested, status: lastErr?.status ?? 502, via: "none", timing: null });
   evt("client-response", { requested, actual: lastErr?.model ?? requested, via: "none", fallback: false, status: lastErr?.status ?? 502, reqId: handlerCtx.reqId });
-  json(res, 502, { error: lastErr?.message || "all auto models failed" });
+  terminal(res, lastErr?.message);
   return true;
 }

package/src/routes/chat/hedge-handler.js

@@ -22,6 +22,7 @@ export async function handleHedge({
   logError,
   mark,
   perf0,
+  attemptStartMs,
   stages,
   startedAt,
   plugins,
@@ -62,6 +63,7 @@ export async function handleHedge({
           handlerCtx,
           mark,
           perf0,
+          attemptStartMs,
           stages,
           startedAt,
         });
@@ -100,6 +102,7 @@ export async function handleHedge({
           handlerCtx: { ...handlerCtx, model: win.target },
           mark: (n) => mark(n),
           perf0,
+          attemptStartMs,
           stages,
           startedAt,
         });

package/src/routes/chat/local-handler.js

@@ -20,6 +20,7 @@ export async function handleLocalRelay({
   logError,
   mark,
   perf0,
+  attemptStartMs,
   stages,
   startedAt,
   plugins,
@@ -51,9 +52,12 @@ export async function handleLocalRelay({
     handlerCtx,
     mark,
     perf0,
+    attemptStartMs,
     stages,
     startedAt,
   });
+  // wrotePayload 是「正文真到了下游」的送达证据：serial-trial 记 empty-turn-recovered 只认它，
+  // 不认 handled 本身（handled 也覆盖下游已断开等零输出路径，见 ADR-0043）。
   if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
-  return { handled: true };
+  return { handled: true, wrotePayload: r.wrotePayload === true };
 }

package/src/routes/chat/peer-handler.js

@@ -18,6 +18,7 @@ export async function handlePeerRelay({
   logCall,
   mark,
   perf0,
+  attemptStartMs,
   stages,
   startedAt,
   plugins,
@@ -70,6 +71,7 @@ export async function handlePeerRelay({
     handlerCtx: { ...handlerCtx, model: win.target },
     mark,
     perf0,
+    attemptStartMs,
     stages,
     startedAt,
   });

package/src/routes/chat/relay-pipeline.js

@@ -5,6 +5,8 @@ import { computeMetrics } from "../../metrics.js";
 import { recordChatUsage } from "../../usage/record.js"; // 窗口报表唯一写入点（canonical 名单记防双计）— 见 .agents/notes/implemented/feature/2026-09-19-usage-report-jsonl.md
 import { recordOutput, computeOutputRow } from "../../providers/cline/usage.js"; // cline 专属旁路统计（账号×模型，流式也覆盖）
 import { upstreamEcho } from "../../model-trace.js"; // 回显头→日志字段（谁上的/哪个号/为什么/是否冷却）单一来源
+import { recordRelayTalk } from "../../talk-log.js"; // 环形对话日志（问答全文，最近 1 小时）：五段流水在此汇合，落盘点只这一个
+import { isEmptyTurnDetail } from "../stream-scan.js"; // 空轮判据单一真相（stream.js 用它决定封不封口，这里用它决定交不交回重试）
 
 // 唯一/最后候选没有 failover 去向：首块闸门退化为纯"防连接泄漏"，放宽避免误杀慢模型
 // （参考 opencode：zen 通道不设超时；openai responses 硬编码 300s headerTimeout）
@@ -66,6 +68,7 @@ export function createRelayPipeline({
     handlerCtx,
     mark: m2,
     perf0,
+    attemptStartMs,
     stages: s2,
     startedAt: sa2,
     streamTimeoutMs: ctxStreamTimeoutMs,
@@ -100,6 +103,7 @@ export function createRelayPipeline({
     const out = await _relay(res, upRes, body, {
       fallback,
       streamTimeoutMs,
+      attemptStartMs, // 本次上游尝试起点（performance.now 同源），relay 用它算 preflightMs
       onFirstChunk: (delta) => {
         try { markFn(`ttf-${actual}`); } catch {}
         _evt("relay-first-chunk", { reqId, model: actual, ttfMs: delta, via });
@@ -125,6 +129,10 @@ export function createRelayPipeline({
       detail: out.detail ?? null,
     });
 
+    // 环形对话日志：只记有真实输出的轮次（空轮交给下面的空转判定另行报错）。
+    // 纯旁路：不改闸门、不改计时、不改返回体；任何异常都吞掉，绝不影响转发。
+    try { recordRelayTalk({ reqId, model: actual, via, hops, body, out, echo: upstreamEcho(upRes) }); } catch {}
+
     // 5a0. 空转 200：流正常结束但零正文零工具调用 → 客户端会报 EMPTY_MODEL_RESPONSE
     // （"The model ended its turn without producing any output"）；转 failover 而不是
     // 把空轮递给客户端。chatShaped 是前置证据：只有看得出是 chat 轮才判空，
@@ -132,25 +140,34 @@ export function createRelayPipeline({
     // 工具轮豁免：tool_calls 无正文是合法 agent 形态；
     // finish=tool_calls/function_call 兜底豁免（防计数漏检误杀）；下游已断开不重试（写给谁看）。
     // 对标 dsh-cline-pass 的 EMPTY_RESPONSE 语义；不记 auto 冷却（空转≠模型坏，重试多半能好）。
+    // 判据单一真相在 stream-scan.js:isEmptyTurnDetail —— relay 侧「要不要封口」与这里「要不要重拉」必须同源，否则会出现留了口却不再救、或已终结却仍重拉的错拍
+    // heldOpen 也计入：非流式留口返回的是上游原状态码（2xx 变体或中继的 ≥400），只认 200 会漏判 → 没人收场，连接挂死
     const _d = out.detail || {};
-    const _emptyTurn = out.status === 200 && !out.timedOut && !out.interrupted && !_d.downstreamClosed &&
-      _d.chatShaped === true &&
-      (Number(_d.chars) || 0) === 0 && (Number(_d.toolCalls) || 0) === 0 &&
-      !["tool_calls", "function_call"].includes(_d.sawFinishReason);
+    const _emptyTurn = (out.status === 200 || out.heldOpen === true) && !out.timedOut && !out.interrupted && !_d.downstreamClosed && isEmptyTurnDetail(_d);
     if (_emptyTurn) {
       const _why = _d.sawFinishReason ? ` (finish_reason=${_d.sawFinishReason})` : " (no content, no tool calls)";
       // 错误包络暂扣后下游不再直观看到上游原文：把摘要带进最终报错（截断 200 字），排障不断线。
       const _err = _d.upstreamErrorText ? ` upstream=${String(_d.upstreamErrorText).slice(0, 200)}` : "";
-      try { _logError(actual, 502, `empty turn${_why}${_err}`); } catch {}
-      _evt("upstream-error", { reqId, model: actual, status: 502, message: "empty turn", timing: null, ...upstreamEcho(upRes) });
+      // 零正文的成因直接写进报错（不只给现象）：finish_reason=length + 大量思考 = 额度被 reasoning 吃光
+      // （实测 cline-free deepseek reasoningChars=28151、completion_tokens=8192=max_tokens、chars=0）。
+      // 同参重拉必复现，故 serial-trial 的空转重试会顺手把 max_tokens 抬一档（见 emptyRaiseCap）。
+      const _lenCapped = _d.sawFinishReason === "length";
+      const _hint = _lenCapped && (Number(_d.reasoningChars) || 0) > 0
+        ? ` [思考 ${Number(_d.reasoningChars) || 0} 字刷满 max_tokens，正文 0 字]`
+        : "";
+      try { _logError(actual, 502, `empty turn${_why}${_err}${_hint}`); } catch {}
+      _evt("upstream-error", { reqId, model: actual, status: 502, message: "empty turn", timing: null, finish: _d.sawFinishReason || null, reasoningChars: Number(_d.reasoningChars) || 0, wroteFrames: Number(_d.wroteChunks) || 0, heldOpen: out.heldOpen === true, ...upstreamEcho(upRes) });
       _evt("fallback", { reqId, from: actual, to: null, reason: "empty turn" });
-      let _errMsg = `EMPTY_MODEL_RESPONSE: upstream returned 200 with no content${_why}${_err} — retry or rephrase`;
+      let _errMsg = `EMPTY_MODEL_RESPONSE: upstream returned 200 with no content${_why}${_err}${_hint} — retry or rephrase`;
       if (_d.upstreamErrorText && _d.upstreamErrorText.includes("retryAfterSeconds")) {
         _errMsg = _d.upstreamErrorText;
       }
-      return { handled: false, upRes: null, lastErr: { model: actual, upstream: null, status: 502, message: _errMsg } };
+      return { handled: false, upRes: null, lastErr: { model: actual, upstream: null, status: 502, message: _errMsg, emptyTurn: true, heldOpen: out.heldOpen === true } };
     }
 
+    // 上报锚点偏移：relay 入口之前消耗掉的等待（上游排队、建连、provider 为取判决预读的首帧）。
+    // 只加给 usage 行的时长；闸门计时与 recordModelStats 一律不碰 —— 见 design D2 与 Non-Goals。
+    const anchorMs = Number.isFinite(out?.preflightMs) && out.preflightMs > 0 ? out.preflightMs : 0;
     // 5a. 首块超时未写字节 → 回退（显式 timedOut 字段，status 只是 HTTP 语义展示）
     if (out.timedOut === true) {
       const why = out.detail?.upstreamError ? ` (upstream read error: ${out.detail.upstreamError})` : "";
@@ -173,15 +190,15 @@ export function createRelayPipeline({
       if (out.status === 200) {
         try {
           const u = out.detail?.usage || null;
-          const t1 = Number.isFinite(out.totalMs) && out.totalMs > 0 ? out.totalMs : (Date.now() - curStartedAt);
-          const t0 = Number.isFinite(out.ttfMs) && out.ttfMs > 0 ? out.ttfMs : null;
-          recordChatUsage({ model: normalizeFullId(actual), via, usage: u, interrupted: 1, ttfbMs: t0, totalMs: t1, tps: null }).catch(() => {});
+          const endMs = Number.isFinite(out.totalMs) && out.totalMs >= 0 ? out.totalMs + anchorMs : (Date.now() - curStartedAt);
+          const firstMs = Number.isFinite(out.ttfMs) && out.ttfMs >= 0 ? out.ttfMs + anchorMs : null;
+          recordChatUsage({ model: normalizeFullId(actual), via, usage: u, interrupted: 1, ttfbMs: firstMs, totalMs: endMs, tps: null, reasoningChars: out.detail?.reasoningChars ?? 0, stream: Boolean(body?.stream) }).catch(() => {});
         } catch {}
       }
       _evt("result", { reqId, model: actual, status: out.status, via, timing: upRes?._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, interrupted: true, ...upstreamEcho(upRes), detail: out.detail ?? null, fallback, requested, actual });
       _evt("client-response", { requested, actual, via, fallback, status: out.status, reqId, interrupted: true });
       if (plugins?.length) runHook(plugins, "request:completed", { reqId, requested, useAuto, hops, stream: Boolean(body?.stream), durationMs: Date.now() - curStartedAt, via, status: out.status, actual, interrupted: true, fallback }).catch(() => {});
-      return { handled: true };
+      return { handled: true, wrotePayload: out.detail?.wrotePayload === true };
     }
 
     // 5c. 慢速计分 + ok
@@ -211,6 +228,7 @@ export function createRelayPipeline({
     if (out.status === 200) {
       try {
         const isStream = Boolean(body?.stream);
+        // —— 状态口径（-status / -model stats 的终生 EMA）：本期刻意不动，仍按转发入口量 ——
         let ttfb = isStream ? (out.ttfMs ?? upRes?._t?.ttfbMs ?? null) : null;
         // out.totalMs 为 0 时（非流式 <1ms 四舍五入）回退到 elapsed/durationMs
         const elapsedFallback = Date.now() - curStartedAt;
@@ -227,9 +245,17 @@ export function createRelayPipeline({
         const fullId = normalizeFullId(actual);
         recordModelStats(fullId, { ttfbMs: ttfb, totalMs: total, tps, completionTokens: compTok });
         if (fullId !== actual) recordModelStats(actual, { ttfbMs: ttfb, totalMs: total, tps, completionTokens: compTok });
+        // —— 报表口径（usage 行 = -stats 的唯一数据源）：把 relay 之前消耗掉的等待补回来 ——
+        // 首字 = 本次上游尝试起点 → 网关转发首帧；0ms 是有效样本，只有负值判无效；
+        // transport 的 _t.ttfbMs 本就从 fetch 起算，不再叠加锚点（否则双计）。
+        const rowTtfb = !isStream ? null
+          : Number.isFinite(out.ttfMs) ? (out.ttfMs < 0 ? null : out.ttfMs + anchorMs)
+          : (Number.isFinite(upRes?._t?.ttfbMs) ? upRes._t.ttfbMs : null);
+        const rowTotal = Number.isFinite(total) ? total + anchorMs : total;
+        // 速度恒等：首字与总耗时同加一个常数 → (总−首字) 不变，故沿用 m.tps。
         // 窗口报表：逐请求落 usage（行形状由 usage/record.js 拥有，含 prompt/total ——
         // state 的 modelStats 只存 completion 的 EMA）。只按 canonical 名记一次，避免双计。
-        recordChatUsage({ model: fullId, via, usage, ttfbMs: ttfb, totalMs: total, tps: m.tps }).catch(() => {});
+        recordChatUsage({ model: fullId, via, usage, ttfbMs: rowTtfb, totalMs: rowTotal, tps: m.tps, reasoningChars: out.detail?.reasoningChars ?? 0, stream: isStream }).catch(() => {});
         // cline 旁路记账：流式时 provider 已把账号哈希挂在 upRes 上，这里用消费完的 usage 记一笔。
         // 纯旁路：只调 recordOutput，不改转发/切号/重试；无账号或非 cline 直接跳过。
         if (upRes?.clineAccountId) {
@@ -243,7 +269,7 @@ export function createRelayPipeline({
     _evt("result", { reqId, model: actual, status: out.status, via, timing: upRes?._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, ...upstreamEcho(upRes), detail: out.detail ?? null, fallback, requested, actual });
     _evt("client-response", { requested, actual, via, fallback, status: out.status, reqId });
     if (plugins?.length) runHook(plugins, "request:completed", { reqId, requested, useAuto, hops, stream: Boolean(body?.stream), durationMs: Date.now() - curStartedAt, via, status: out.status, actual, fallback }).catch(() => {});
-    return { handled: true };
+    return { handled: true, wrotePayload: out.detail?.wrotePayload === true };
   }
 
   return { execute };

package/src/routes/chat/via-route-handler.js

@@ -25,6 +25,7 @@ export async function handleViaRoute({
   logError,
   mark,
   perf0,
+  attemptStartMs,
   stages,
   startedAt,
   plugins,
@@ -134,6 +135,7 @@ export async function handleViaRoute({
     handlerCtx: { ...handlerCtx, model },
     mark,
     perf0,
+    attemptStartMs,
     stages,
     startedAt,
     // 借道单路径无第二候选可比：按末位耐心档（默认 120s，MSLXDFF_LAST_CANDIDATE_TIMEOUT_MS 可调/0=不限）