@thincoder/core 0.9.4 → 0.10.1

package/provider/core.mjs

@@ -5,6 +5,7 @@
  */
 
 import { providerSpec, resolveEnableThinking } from "../config.mjs"
+import { resolveProviderSecrets } from "../env-ref.mjs"
 import { proxyFetch } from "../proxy.mjs"
 import { escapeMessages, stripLocalMessageFields } from "../escape.mjs"
 import { logEvent, errText, classifyErr, headText } from "../log.mjs"
@@ -78,7 +79,7 @@ export async function chat(provider, opts = {}) {
   // 格式分派（anthropic/google/responses）在内部——单点覆盖即 llm:* 全覆盖。
   // 续写/重试各自为独立 HTTP 请求——续写递归（下方 chatImpl 内）会再包一层（嵌套
   // llm:start/done 对——每请求一事件）；重试在 requestWithRetry 内部不可见。
-  // §18.6 完整轨迹存档（AGENT-LOOP.md §18.6 N-TR2——权威句 D-TR1）：采集点唯一=
+  // 完整轨迹存档（TRACES.md §6.1——权威句 D-TR1）：采集点唯一=
   // 本函数出口——所有 chat 调用（主回合/消化轮/compress/distill/advisor/子代理/
   // auto-think/consult）都经本函数；续写/重试在出口已合并——reasoning 全量才完整。
   const logCtx = opts.logCtx ?? {}
@@ -96,7 +97,7 @@ export async function chat(provider, opts = {}) {
       finish: result?.finishReason ?? null,
       tools: Array.isArray(result?.toolCalls) ? result.toolCalls.length : 0,
     })
-    // §18.6 D-TR1/D-TR5：出口收集——成功路径轨迹（含 content/reasoning 全文/toolCalls）
+    // TRACES.md §6.1 D-TR1/D-TR5：出口收集——成功路径轨迹（含 content/reasoning 全文/toolCalls）
     recordChatTrace(provider, opts, result, null)
     return result
   } catch (e) {
@@ -107,7 +108,7 @@ export async function chat(provider, opts = {}) {
       err: errText(deathLine(e, opts.signal), 200),
       kind: classifyErr(e, opts.signal),
     })
-    // §18.6 D-TR5：失败路径也落盘——error（errText 截断 + 类别）+ finishReason:null
+    // TRACES.md §6.1 D-TR5：失败路径也落盘——error（errText 截断 + 类别）+ finishReason:null
     recordChatTrace(provider, opts, null, e)
     throw e
   }
@@ -115,6 +116,10 @@ export async function chat(provider, opts = {}) {
 
 /** chat 本体（LOG(LLM) 事件包装之外——见上方 chat 包装器）。 */
 async function chatImpl(provider, { messages, tools, onToken, onReasoning, onWait, signal, streamRules, firedPatterns, toolChoice, parallelToolCalls, logCtx }) {
+  // #57（provider-config-family 批）：凭据值位 `${env:VAR}` 消费侧解析——单源 `../env-ref.mjs`
+  // （CONFIG.md §6.3）。格式分派之前：四 transport ∕ 续写 ∕ advisor ∕ 子代理 ∕ 压缩同享；
+  // 未设 ∕ 空串 ∕ 畸形 ⇒ 此处抛错（点名变量，无回退）。
+  provider = resolveProviderSecrets(provider)
   // Sanitize BEFORE format dispatch — image poisoning bricks anthropic/google sessions
   // the same way it bricks OpenAI-format ones (all raster-only).
   // providerSpec: spec with the provider-level context override (PROVIDER.md §6.15) — the
@@ -126,7 +131,6 @@ async function chatImpl(provider, { messages, tools, onToken, onReasoning, onWai
   // objects through verbatim (only the OpenAI path ran escapeMessages). Copy-on-write:
   // history keeps the fields, the request never sees them.
   messages = stripLocalMessageFields(messages)
-  const _debugBeforeLen = process.env.THIN_DEBUG_BODY ? JSON.stringify(messages).length : 0
 
   // Format dispatch: delegate to non-OpenAI transports
   if (provider.format === "anthropic") {
@@ -167,9 +171,6 @@ async function chatImpl(provider, { messages, tools, onToken, onReasoning, onWai
   // 转义的代码），Kimi 等会把它们当 hex escape 再解析 → "unexpected end of hex escape" 400。
   // 发送前统一 double 掉会形成非法转义的序列（合法 \xNN/\uNNNN 不受影响）。
   messages = escapeMessages(messages)
-  if (process.env.THIN_DEBUG_BODY) {
-    console.error(`[debug-body] escape: ${_debugBeforeLen} -> ${JSON.stringify(messages).length} chars, ${messages.length} msgs (provider=${provider.name}, model=${provider.model})`)
-  }
   // Compile string-pattern rules to RegExp at call time
   const rules = compileStreamRules(streamRules)
   // F-1 (MODEL-400-FIX)：请求体组装前断言 model 恒有值——见 errors.mjs assertProviderModel
@@ -179,7 +180,7 @@ async function chatImpl(provider, { messages, tools, onToken, onReasoning, onWai
     messages,
     stream: true,
   }
-  // Skip usage stream for models that don't support it (GLM, MiniMax, Gemini)
+  // 保守抑制（非能力断言）：带 `noUsageStream` 的行 = 核不主动发 stream_options.include_usage（glm 族已实测带该参数全 200）；逐族等级 = MODEL-SPECS.md §15.2
   if (!spec.noUsageStream) body.stream_options = { include_usage: true }
   if (provider.maxTokens) body.max_tokens = provider.maxTokens
   if (provider.temperature != null) {
@@ -276,7 +277,7 @@ async function chatImpl(provider, { messages, tools, onToken, onReasoning, onWai
         onReasoning,
         onWait,
         signal,
-        // §18.6：续写是同一逻辑调用的子请求——logCtx 原样透传（元数据与门控
+        // TRACES.md §6.1：续写是同一逻辑调用的子请求——logCtx 原样透传（元数据与门控
         // traces.enabled 对续写调用同样生效，不在出口静默越过开关）
         // fix round1（D-TR1）：续写子请求标记 isContinuation:true（T-TR14——true =
         // 该调用是续写链的一环；外层新调用 false）——分析"纠结"时区分续写/重试链。
@@ -362,44 +363,6 @@ function mergeRetryToolCalls(result, toolCalls) {
 // provider/index.mjs re-export 改指新文件——调用点零改。
 
 async function requestWithRetry(provider, body, signal, onWait) {
-  // THIN_DEBUG_BODY=1：发送前诊断——复现网关侧 "unexpected end of hex escape" 400 时
-  // 定位真实载荷里的毒序列（2026-08-31 slot 3 deepseek-v4-flash）。模拟网关最宽松的
-  // 爆炸条件：任何字面 "\u"/"\x" 后不足位（不看前置反斜杠）。
-  if (process.env.THIN_DEBUG_BODY) {
-    try {
-      const msgs = body?.messages ?? []
-      const raw = JSON.stringify(body)
-      const hits = []
-      for (let i = 0; i < msgs.length; i++) {
-        const m = msgs[i] ?? {}
-        const fields = []
-        if (typeof m.content === "string") fields.push(["content", m.content])
-        else if (Array.isArray(m.content)) m.content.forEach((p, pi) => { if (p && typeof p.text === "string") fields.push([`content[${pi}]`, p.text]) })
-        if (typeof m.reasoning_content === "string") fields.push(["reasoning_content", m.reasoning_content])
-        if (Array.isArray(m.tool_calls)) m.tool_calls.forEach((tc, ti) => { if (tc && typeof tc.arguments === "string") fields.push([`tool_calls[${ti}].arguments`, tc.arguments]) })
-        if (typeof m.name === "string") fields.push(["name", m.name])
-        for (const [f, t] of fields) {
-          const re = /\\[xu]/g
-          let mm
-          while ((mm = re.exec(t))) {
-            const c = t[mm.index + 1]
-            const need = c === "u" ? 4 : 2
-            const after = t.slice(mm.index + 2, mm.index + 2 + need)
-            if (!new RegExp(`^[0-9a-fA-F]{${need}}$`).test(after)) {
-              hits.push({ i, role: m.role, field: f, ctx: t.slice(Math.max(0, mm.index - 40), mm.index + 12) })
-            }
-          }
-        }
-      }
-      console.error(`[debug-body] messages=${msgs.length} bodyLen=${raw.length} suspicious=${hits.length}`)
-      for (const h of hits.slice(0, 20)) console.error("[debug-body] hit", JSON.stringify(h))
-      if (!hits.length && msgs[1151]) {
-        console.error("[debug-body] no suspicious hit; messages[1151] =", JSON.stringify({ role: msgs[1151].role, contentLen: msgs[1151].content?.length, contentHead: String(msgs[1151].content).slice(0, 150) }))
-      }
-    } catch (e) {
-      console.error("[debug-body] diag failed:", e.message)
-    }
-  }
   let lastError
   let lastStatus = 0
   let lastWas429 = false
@@ -433,7 +396,7 @@ async function requestWithRetry(provider, body, signal, onWait) {
         ? await proxyFetch(url, opts, provider.proxyUri)
         : await fetch(url, opts)
     } catch (error) {
-      // §20.3 站点 #2（第 24 批）：fetch 拒否面补标来源（undici 拒否的 AbortError 现场无 reason）
+      // AGENT-LOOP-SUBAGENT.md §6.12 站点 #2（第 24 批）：fetch 拒否面补标来源（undici 拒否的 AbortError 现场无 reason）
       if (error.name === "AbortError") throw annotateAbort(error, signal, "provider", "request")
       lastError = error
       continue

package/provider/list-models.mjs

@@ -14,6 +14,7 @@
  * 解析保持防御性（字段缺失即跳过该项）。候选不过滤非对话模型（embedding 等——§16.6 #14）。
  */
 import { proxyFetch } from "../proxy.mjs"
+import { resolveProviderSecrets } from "../env-ref.mjs"
 
 const LIST_TIMEOUT_MS = 15_000
 /** 翻页上限（cursor loop 防死循环——任一分页失败即整体抛出，不部分返回）。 */
@@ -94,6 +95,8 @@ async function listGoogle(provider, signal) {
 
 /** List available model IDs from the provider's /models endpoint (format 分派——M1)。 */
 export async function listModels(provider, { signal } = {}) {
+  // #57（provider-config-family 批）：清单拉取入口凭据值位解析（CONFIG.md §6.3）——三 format 分支共享。
+  provider = resolveProviderSecrets(provider)
   const base = String(provider?.baseURL ?? "").replace(/\/+$/, "")
   if (!base) throw new Error("GET /models failed: baseURL is missing") // §2.5 #115 并入（VSC 明确报错）
   const format = provider?.format

package/provider/responses-request.mjs

@@ -0,0 +1,237 @@
+/**
+ * provider/responses-request.mjs — Responses **请求构造面**出档（2026-09-29 structure-split-2 · 台账 #620）：自
+ * `provider/responses.mjs` 全量迁出〔原 `:22-245`〕——host 白名单判定（`isStatefulHost` ∕ `isStoreRequiredHost` ∕
+ * `isNonStatefulHost`）· `chainKey` · `builtinToolsFor` · `toItems` / `toTools` / `normalizeUsage` · `buildBody`；
+ * **结构拆分零语义**（面不变 ∕ 判据不变，只换宿主档；切点 ∕ 缝单源 = 批档 `docs/batches/2026-09-29-structure-split-2.md` §2.2-B）。
+ *
+ * 缝 = 同名再出口：宿主 `provider/responses.mjs` 转口 `buildBody` / `isStoreRequiredHost` / `builtinToolsFor` 三名
+ * 既有导出（消费者 import 面零改）；`normalizeUsage` 被宿主 `parseStream` 消费 ⇒ 随迁导出（宿主 import）。
+ * 零环：本档不引宿主（方向单行）；档外依赖 = `../config.mjs`（`specForModel` ∥ `isBailianHost`）。
+ * 链语义（双轨 ∕ 白名单 ∕ store 必开 ∥ 链重置）详述见宿主档头；本档 = 请求侧构造 ∥ 链状态机决策。
+ */
+import { specForModel, isBailianHost } from "../config.mjs"
+
+/** 白名单：已实证 previous_response_id 的官方端（2026-08-31 真机验证：
+ *  百炼 store:true 全链路 ✅；GLM（open.bigmodel.cn/api/v1）store:true 全链路 ✅）。 */
+function isStatefulHost(baseURL) {
+  try {
+    const host = new URL(baseURL).hostname
+    return /(^|\.)openai\.com$/.test(host) || isBailianHost(baseURL) || /(^|\.)bigmodel\.cn$/.test(host)
+  } catch {
+    return false
+  }
+}
+
+/** store 必开 host（链保留依赖 store:true——真机：百炼 store:false → 链 400；GLM 同）。
+ *  OpenAI 官方 store:false 链仍可用，不在内。 */
+export function isStoreRequiredHost(baseURL) {
+  try {
+    const host = new URL(baseURL).hostname
+    return isBailianHost(baseURL) || /(^|\.)bigmodel\.cn$/.test(host)
+  } catch {
+    return false
+  }
+}
+
+/** 灰名单：格式完整但链未证实/不支持——显式全量 + 一次性 warning（不靠服务端报错）。
+ *  2026-08-31 真机后仅剩 DeepSeek（官方明确 previous_response_id 不支持且参数静默忽略）。 */
+function isNonStatefulHost(baseURL) {
+  try {
+    const host = new URL(baseURL).hostname
+    return /(^|\.)deepseek\.com$/.test(host)
+  } catch {
+    return false
+  }
+}
+
+/** 链 key：system 部分 + 最后一条 user 消息（turn 内不变、跨 turn 变、压缩后变）。 */
+function chainKey(messages) {
+  let sig = "s:"
+  let lastUser = ""
+  for (const m of messages ?? []) {
+    if (m.role === "system") sig += (typeof m.content === "string" ? m.content : "") + "\u0001"
+    else if (m.role === "user") lastUser = typeof m.content === "string" ? m.content : ""
+  }
+  return sig + "\u0002u:" + lastUser
+}
+
+/** 内置工具声明（2026-08-31 用户拍板"内置工具还是要用"，一期 web_search）。
+ *  按 host 映射默认集；provider.builtinTools === false 关闭、数组显式覆盖。
+ *  注意：内置工具由**服务端执行**——绕过我们的工具权限门/审计（产品决策，用户拍板）。 */
+export function builtinToolsFor(baseURL, providerBuiltin) {
+  if (providerBuiltin === false) return []
+  if (Array.isArray(providerBuiltin)) return providerBuiltin
+  try {
+    const host = new URL(baseURL).hostname
+    if (/(^|\.)openai\.com$/.test(host) || isBailianHost(baseURL) || /(^|\.)deepseek\.com$/.test(host)) {
+      return [{ type: "web_search" }]
+    }
+  } catch { /* fallthrough */ }
+  return []
+}
+
+/** OpenAI Chat 消息 → Responses input items。system 提升为 instructions（不进 input）。
+ *  内置工具结果（web_search_call 本地化 tool 消息）→ 原样 web_search_call item 回传。 */
+function toItems(messages, { instructions } = {}) {
+  const items = []
+  for (const m of messages ?? []) {
+    if (m.role === "system") continue
+    if (typeof m.tool_call_id === "string" && m.tool_call_id.startsWith("web_search_call_") && typeof m.content === "string") {
+      // 内置工具结果本地化消息 → 原样回传（DeepSeek 官方：web_search_call 原样回传即可，
+      // 服务端自动恢复搜索结果）。id 用 content 里的原始服务端 id（msg_xxx），前缀只是本地锚点。
+      let query = ""
+      let srcs = []
+      let wsId = m.tool_call_id.slice("web_search_call_".length)
+      try {
+        const parsed = JSON.parse(m.content)
+        query = parsed.query ?? ""
+        srcs = parsed.sources ?? []
+        if (parsed.id) wsId = parsed.id
+      } catch { /* content 非 JSON（纯展示）→ query 缺省 */ }
+      items.push({ type: "web_search_call", id: wsId, status: "completed", action: { query, type: "search", sources: srcs } })
+      continue
+    }
+    if (m.role === "user") {
+      const content = m.content
+      if (Array.isArray(content)) {
+        items.push({
+          role: "user",
+          content: content
+            .map((p) => (p?.type === "image_url"
+              ? { type: "input_image", image_url: p.image_url?.url }
+              : p?.type === "text" || typeof p === "string"
+                ? { type: "input_text", text: typeof p === "string" ? p : p.text }
+                : null))
+            .filter(Boolean),
+        })
+      } else {
+        items.push({ role: "user", content: [{ type: "input_text", text: String(content ?? "") }] })
+      }
+    } else if (m.role === "assistant") {
+      const tcList = m.tool_calls ?? []
+      items.push({ role: "assistant", content: [{ type: "output_text", text: String(m.content ?? "") }] })
+      for (const tc of tcList) {
+        items.push({
+          type: "function_call",
+          call_id: tc.id ?? "",
+          name: tc.function?.name ?? "",
+          arguments: tc.function?.arguments ?? "{}",
+        })
+      }
+    } else if (m.role === "tool" || m.role === "function") {
+      items.push({
+        type: "function_call_output",
+        call_id: m.tool_call_id ?? m.name ?? "",
+        output: typeof m.content === "string" ? m.content : JSON.stringify(m.content ?? ""),
+      })
+    }
+  }
+  return { items, instructions: instructions ?? (messages ?? []).find((m) => m.role === "system")?.content ?? "" }
+}
+
+/** OpenAI 工具 schema → Responses 扁平 tools。 */
+function toTools(tools) {
+  return (tools ?? []).map((t) => ({
+    type: "function",
+    name: t.function?.name ?? t.name,
+    description: t.function?.description ?? t.description,
+    parameters: t.function?.parameters ?? t.parameters ?? { type: "object", properties: {} },
+  }))
+}
+
+/** Responses usage → 内部 cache 字段形状。 */
+export function normalizeUsage(usage) {
+  if (!usage) return null
+  return {
+    prompt_tokens: usage.input_tokens ?? 0,
+    completion_tokens: usage.output_tokens ?? 0,
+    total_tokens: usage.total_tokens ?? (usage.input_tokens ?? 0) + (usage.output_tokens ?? 0),
+    prompt_cache_hit_tokens: usage.input_tokens_details?.cached_tokens ?? 0,
+    prompt_cache_miss_tokens: Math.max(0, (usage.input_tokens ?? 0) - (usage.input_tokens_details?.cached_tokens ?? 0)),
+  }
+}
+
+/**
+ * 组装请求体 + 链状态机决策。
+ * @returns {{ body, previousResponseId, warnings, newChain: {id,key}|null }}
+ */
+export function buildBody(provider, messages, tools, opts = {}) {
+  const { instructions: extracted, items } = toItems(messages)
+  const toolsFlat = tools?.length ? toTools(tools) : undefined
+  const spec = specForModel(provider.model)
+  const warnings = []
+  const wantStateful = provider.stateful !== false && opts.stateful !== false
+  const hostStateful = isStatefulHost(provider.baseURL)
+  const hostNonStateful = isNonStatefulHost(provider.baseURL)
+
+  let chain = provider._responsesChain ?? null
+  const key = chainKey(messages)
+
+  if (!wantStateful) {
+    chain = null // stateful:false 显式覆盖：残留链（同 session 开过）必须作废
+  } else if (hostNonStateful && !opts.forceStateful) {
+    // 灰名单：链不支持/未证实（DeepSeek 静默忽略 → 无声丢上下文）——显式全量 + 一次警告
+    if (wantStateful) {
+      warnings.push({ name: "responses-stateful-unsupported", message: "endpoint 未实证支持 previous_response_id；已发送全量上下文（可 provider.stateful=false 关闭此消息）" })
+    }
+    chain = null
+  } else if (chain && chain.key !== key) {
+    chain = null // 跨 turn/压缩/换模型：链失效，全量重建
+  } else if (chain && !hostStateful && !opts.forceStateful) {
+    chain = null // 非白名单 host 且无显式 forceStateful：不冒险开链
+  }
+  // 2026-08-31 真机冒烟：百炼/GLM 开链 = 云端留存 7 天——首次知情警告（不刷屏）
+  if (wantStateful && hostStateful && isStoreRequiredHost(provider.baseURL) && !provider._responsesStoreWarned) {
+    provider._responsesStoreWarned = true
+    warnings.push({ name: "responses-store-retention", message: "链生效需要 store:true——对话将在云端留存 7 天（provider.stateful=false 可退出）" })
+  }
+
+  const body = {
+    model: provider.model,
+    input: items, // 占位：chain 有效时下方替换为增量
+    stream: true,
+    // 2026-08-31 真机冒烟实锤：百炼/GLM 链要求 R1 store:true（store:false → 链 400
+    // Not found）；OpenAI 官方 store:false 链仍可用。开链时 = 对话在云端留存 7 天
+    // （警告上报）；灰名单全量 store:false。
+    store: wantStateful && hostStateful && isStoreRequiredHost(provider.baseURL),
+    ...(extracted ? { instructions: extracted } : {}),
+    ...(toolsFlat ? { tools: toolsFlat } : {}),
+    ...(spec.maxOutput || provider.maxTokens ? { max_output_tokens: provider.maxTokens ?? spec.maxOutput } : {}),
+  }
+  // 内置工具声明追加（2026-08-31 用户拍板）：web_search 与本地 function 工具共存
+  const builtin = builtinToolsFor(provider.baseURL, provider.builtinTools)
+  if (builtin.length) body.tools = [...(toolsFlat ?? []), ...builtin]
+  if (provider.temperature != null) {
+    let t = provider.temperature
+    if (spec.tempRange) {
+      t = Math.min(spec.tempRange[1], Math.max(spec.tempRange[0], t))
+      t = Math.round(t * 100) / 100 // 与 core.mjs 同语义（round3 #7）
+    }
+    body.temperature = t
+  }
+  if (provider.reasoningEffort) body.reasoning = { effort: provider.reasoningEffort }
+  if (opts.toolChoice !== undefined) body.tool_choice = opts.toolChoice
+
+  // 链模式：turn 内增量 = 上一链轮未发送的 function_call_output（工具结果）。
+  // 注意：assistant 的 function_call item 与服务端链输出重复（服务端自动含上轮 output），
+  // 增量只发工具结果即可；新 user 消息/压缩/换模型已由 chainKey 挡掉 → 全量。
+  const outputs = items.filter((i) => i.type === "function_call_output")
+  let previousResponseId = null
+  if (chain && chain.id) {
+    const newOutputs = outputs.slice(chain.outputSent ?? 0)
+    if (newOutputs.length === 0) {
+      chain = null // 无新增（重复调用/异常重试）：退化为全量，正确性优先
+    } else {
+      body.input = newOutputs
+      previousResponseId = chain.id
+    }
+  } else {
+    body.input = items
+  }
+
+  const newChain = chain
+    ? { ...chain, key, outputSent: outputs.length }
+    : (wantStateful && (hostStateful || opts.forceStateful) ? { id: null, key, outputSent: outputs.length } : null)
+
+  return { body, previousResponseId, warnings, newChain }
+}

package/provider/responses.mjs

@@ -11,239 +11,17 @@
  * 事件流规范：流以 response.completed / response.incomplete / response.failed 结束，
  * 没有 "data: [DONE]"。
  */
-import { specForModel, isBailianHost } from "../config.mjs"
 import { effectiveFetchTimeoutMs } from "./core.mjs"
 import { proxyFetch } from "../proxy.mjs"
 import { requestWithRetry } from "./retry.mjs"
 import { rateGate, recordRate, estimateRequestTokens } from "./rate.mjs"
+import { buildBody, normalizeUsage } from "./responses-request.mjs"
+// 同名 re-export（2026-09-29 structure-split-2 · 台账 #620——缝 = 同名再出口）：请求构造面出档 `provider/responses-request.mjs`；
+// `buildBody` / `isStoreRequiredHost` / `builtinToolsFor` 三名既有导出经本档转口——消费者 import 面零改。
+export { buildBody, isStoreRequiredHost, builtinToolsFor } from "./responses-request.mjs"
 
 // 2026-09-01：FETCH_TIMEOUT_MS 常量退役（绝对墙钟废除）——经 core.mjs effectiveFetchTimeoutMs 共用
 
-/** 白名单：已实证 previous_response_id 的官方端（2026-08-31 真机验证：
- *  百炼 store:true 全链路 ✅；GLM（open.bigmodel.cn/api/v1）store:true 全链路 ✅）。 */
-function isStatefulHost(baseURL) {
-  try {
-    const host = new URL(baseURL).hostname
-    return /(^|\.)openai\.com$/.test(host) || isBailianHost(baseURL) || /(^|\.)bigmodel\.cn$/.test(host)
-  } catch {
-    return false
-  }
-}
-
-/** store 必开 host（链保留依赖 store:true——真机：百炼 store:false → 链 400；GLM 同）。
- *  OpenAI 官方 store:false 链仍可用，不在内。 */
-export function isStoreRequiredHost(baseURL) {
-  try {
-    const host = new URL(baseURL).hostname
-    return isBailianHost(baseURL) || /(^|\.)bigmodel\.cn$/.test(host)
-  } catch {
-    return false
-  }
-}
-
-/** 灰名单：格式完整但链未证实/不支持——显式全量 + 一次性 warning（不靠服务端报错）。
- *  2026-08-31 真机后仅剩 DeepSeek（官方明确 previous_response_id 不支持且参数静默忽略）。 */
-function isNonStatefulHost(baseURL) {
-  try {
-    const host = new URL(baseURL).hostname
-    return /(^|\.)deepseek\.com$/.test(host)
-  } catch {
-    return false
-  }
-}
-
-/** 链 key：system 部分 + 最后一条 user 消息（turn 内不变、跨 turn 变、压缩后变）。 */
-function chainKey(messages) {
-  let sig = "s:"
-  let lastUser = ""
-  for (const m of messages ?? []) {
-    if (m.role === "system") sig += (typeof m.content === "string" ? m.content : "") + "\u0001"
-    else if (m.role === "user") lastUser = typeof m.content === "string" ? m.content : ""
-  }
-  return sig + "\u0002u:" + lastUser
-}
-
-/** 内置工具声明（2026-08-31 用户拍板"内置工具还是要用"，一期 web_search）。
- *  按 host 映射默认集；provider.builtinTools === false 关闭、数组显式覆盖。
- *  注意：内置工具由**服务端执行**——绕过我们的工具权限门/审计（产品决策，用户拍板）。 */
-export function builtinToolsFor(baseURL, providerBuiltin) {
-  if (providerBuiltin === false) return []
-  if (Array.isArray(providerBuiltin)) return providerBuiltin
-  try {
-    const host = new URL(baseURL).hostname
-    if (/(^|\.)openai\.com$/.test(host) || isBailianHost(baseURL) || /(^|\.)deepseek\.com$/.test(host)) {
-      return [{ type: "web_search" }]
-    }
-  } catch { /* fallthrough */ }
-  return []
-}
-
-/** OpenAI Chat 消息 → Responses input items。system 提升为 instructions（不进 input）。
- *  内置工具结果（web_search_call 本地化 tool 消息）→ 原样 web_search_call item 回传。 */
-function toItems(messages, { instructions } = {}) {
-  const items = []
-  for (const m of messages ?? []) {
-    if (m.role === "system") continue
-    if (typeof m.tool_call_id === "string" && m.tool_call_id.startsWith("web_search_call_") && typeof m.content === "string") {
-      // 内置工具结果本地化消息 → 原样回传（DeepSeek 官方：web_search_call 原样回传即可，
-      // 服务端自动恢复搜索结果）。id 用 content 里的原始服务端 id（msg_xxx），前缀只是本地锚点。
-      let query = ""
-      let srcs = []
-      let wsId = m.tool_call_id.slice("web_search_call_".length)
-      try {
-        const parsed = JSON.parse(m.content)
-        query = parsed.query ?? ""
-        srcs = parsed.sources ?? []
-        if (parsed.id) wsId = parsed.id
-      } catch { /* content 非 JSON（纯展示）→ query 缺省 */ }
-      items.push({ type: "web_search_call", id: wsId, status: "completed", action: { query, type: "search", sources: srcs } })
-      continue
-    }
-    if (m.role === "user") {
-      const content = m.content
-      if (Array.isArray(content)) {
-        items.push({
-          role: "user",
-          content: content
-            .map((p) => (p?.type === "image_url"
-              ? { type: "input_image", image_url: p.image_url?.url }
-              : p?.type === "text" || typeof p === "string"
-                ? { type: "input_text", text: typeof p === "string" ? p : p.text }
-                : null))
-            .filter(Boolean),
-        })
-      } else {
-        items.push({ role: "user", content: [{ type: "input_text", text: String(content ?? "") }] })
-      }
-    } else if (m.role === "assistant") {
-      const tcList = m.tool_calls ?? []
-      items.push({ role: "assistant", content: [{ type: "output_text", text: String(m.content ?? "") }] })
-      for (const tc of tcList) {
-        items.push({
-          type: "function_call",
-          call_id: tc.id ?? "",
-          name: tc.function?.name ?? "",
-          arguments: tc.function?.arguments ?? "{}",
-        })
-      }
-    } else if (m.role === "tool" || m.role === "function") {
-      items.push({
-        type: "function_call_output",
-        call_id: m.tool_call_id ?? m.name ?? "",
-        output: typeof m.content === "string" ? m.content : JSON.stringify(m.content ?? ""),
-      })
-    }
-  }
-  return { items, instructions: instructions ?? (messages ?? []).find((m) => m.role === "system")?.content ?? "" }
-}
-
-/** OpenAI 工具 schema → Responses 扁平 tools。 */
-function toTools(tools) {
-  return (tools ?? []).map((t) => ({
-    type: "function",
-    name: t.function?.name ?? t.name,
-    description: t.function?.description ?? t.description,
-    parameters: t.function?.parameters ?? t.parameters ?? { type: "object", properties: {} },
-  }))
-}
-
-/** Responses usage → 内部 cache 字段形状。 */
-function normalizeUsage(usage) {
-  if (!usage) return null
-  return {
-    prompt_tokens: usage.input_tokens ?? 0,
-    completion_tokens: usage.output_tokens ?? 0,
-    total_tokens: usage.total_tokens ?? (usage.input_tokens ?? 0) + (usage.output_tokens ?? 0),
-    prompt_cache_hit_tokens: usage.input_tokens_details?.cached_tokens ?? 0,
-    prompt_cache_miss_tokens: Math.max(0, (usage.input_tokens ?? 0) - (usage.input_tokens_details?.cached_tokens ?? 0)),
-  }
-}
-
-/**
- * 组装请求体 + 链状态机决策。
- * @returns {{ body, previousResponseId, warnings, newChain: {id,key}|null }}
- */
-export function buildBody(provider, messages, tools, opts = {}) {
-  const { instructions: extracted, items } = toItems(messages)
-  const toolsFlat = tools?.length ? toTools(tools) : undefined
-  const spec = specForModel(provider.model)
-  const warnings = []
-  const wantStateful = provider.stateful !== false && opts.stateful !== false
-  const hostStateful = isStatefulHost(provider.baseURL)
-  const hostNonStateful = isNonStatefulHost(provider.baseURL)
-
-  let chain = provider._responsesChain ?? null
-  const key = chainKey(messages)
-
-  if (!wantStateful) {
-    chain = null // stateful:false 显式覆盖：残留链（同 session 开过）必须作废
-  } else if (hostNonStateful && !opts.forceStateful) {
-    // 灰名单：链不支持/未证实（DeepSeek 静默忽略 → 无声丢上下文）——显式全量 + 一次警告
-    if (wantStateful) {
-      warnings.push({ name: "responses-stateful-unsupported", message: "endpoint 未实证支持 previous_response_id；已发送全量上下文（可 provider.stateful=false 关闭此消息）" })
-    }
-    chain = null
-  } else if (chain && chain.key !== key) {
-    chain = null // 跨 turn/压缩/换模型：链失效，全量重建
-  } else if (chain && !hostStateful && !opts.forceStateful) {
-    chain = null // 非白名单 host 且无显式 forceStateful：不冒险开链
-  }
-  // 2026-08-31 真机冒烟：百炼/GLM 开链 = 云端留存 7 天——首次知情警告（不刷屏）
-  if (wantStateful && hostStateful && isStoreRequiredHost(provider.baseURL) && !provider._responsesStoreWarned) {
-    provider._responsesStoreWarned = true
-    warnings.push({ name: "responses-store-retention", message: "链生效需要 store:true——对话将在云端留存 7 天（provider.stateful=false 可退出）" })
-  }
-
-  const body = {
-    model: provider.model,
-    input: items, // 占位：chain 有效时下方替换为增量
-    stream: true,
-    // 2026-08-31 真机冒烟实锤：百炼/GLM 链要求 R1 store:true（store:false → 链 400
-    // Not found）；OpenAI 官方 store:false 链仍可用。开链时 = 对话在云端留存 7 天
-    // （警告上报）；灰名单全量 store:false。
-    store: wantStateful && hostStateful && isStoreRequiredHost(provider.baseURL),
-    ...(extracted ? { instructions: extracted } : {}),
-    ...(toolsFlat ? { tools: toolsFlat } : {}),
-    ...(spec.maxOutput || provider.maxTokens ? { max_output_tokens: provider.maxTokens ?? spec.maxOutput } : {}),
-  }
-  // 内置工具声明追加（2026-08-31 用户拍板）：web_search 与本地 function 工具共存
-  const builtin = builtinToolsFor(provider.baseURL, provider.builtinTools)
-  if (builtin.length) body.tools = [...(toolsFlat ?? []), ...builtin]
-  if (provider.temperature != null) {
-    let t = provider.temperature
-    if (spec.tempRange) {
-      t = Math.min(spec.tempRange[1], Math.max(spec.tempRange[0], t))
-      t = Math.round(t * 100) / 100 // 与 core.mjs 同语义（round3 #7）
-    }
-    body.temperature = t
-  }
-  if (provider.reasoningEffort) body.reasoning = { effort: provider.reasoningEffort }
-  if (opts.toolChoice !== undefined) body.tool_choice = opts.toolChoice
-
-  // 链模式：turn 内增量 = 上一链轮未发送的 function_call_output（工具结果）。
-  // 注意：assistant 的 function_call item 与服务端链输出重复（服务端自动含上轮 output），
-  // 增量只发工具结果即可；新 user 消息/压缩/换模型已由 chainKey 挡掉 → 全量。
-  const outputs = items.filter((i) => i.type === "function_call_output")
-  let previousResponseId = null
-  if (chain && chain.id) {
-    const newOutputs = outputs.slice(chain.outputSent ?? 0)
-    if (newOutputs.length === 0) {
-      chain = null // 无新增（重复调用/异常重试）：退化为全量，正确性优先
-    } else {
-      body.input = newOutputs
-      previousResponseId = chain.id
-    }
-  } else {
-    body.input = items
-  }
-
-  const newChain = chain
-    ? { ...chain, key, outputSent: outputs.length }
-    : (wantStateful && (hostStateful || opts.forceStateful) ? { id: null, key, outputSent: outputs.length } : null)
-
-  return { body, previousResponseId, warnings, newChain }
-}
-
 /** 链失效回退：404/无效 id → 返回 null 表示"应全量重发"；其他失败抛错。 */
 export function isChainInvalidError(status) {
   return status === 404 || status === 400
@@ -292,7 +70,7 @@ export async function parseStream(response, { onToken, onReasoning, signal }) {
     onCompleted: seal,
     onIncomplete: (resp) => {
       seal(resp)
-      // 非长度原因（content_filter 等）不能报成 "length"——agent 层 322 行按原因给用户提示
+      // 非长度原因（content_filter 等）不能报成 "length"——agent 层按原因给用户提示（`agent/run-stages.mjs:43`）
       result.finishReason = resp?.incomplete_details?.reason === "content_filter" ? "content_filter" : "length"
     },
     onFailed: (resp) => {
@@ -442,7 +220,7 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
   } catch (chainErr) {
     if (!isChainInvalidError(chainErr?.status)) throw chainErr
     // 链失效（404/400）：先清残留链再重建——D6 语义是真·全量重发（body.input=items）。
-    // 不清链会走 buildBody 217-224 的增量分支：body.input = 裸 function_call_output 且
+    // 不清链会走 buildBody 的增量分支（`responses-request.mjs:220-227`）：body.input = 裸 function_call_output 且
     // previousResponseId 未随 fullBody 带走 → 服务端 call_id 无归属 → 二次 400（2026-08-31 评审 #1）
     provider._responsesChain = null
     const fresh = buildBody(provider, messages, tools, { toolChoice, stateful, forceStateful: true })