@thincoder/core 0.9.1

package/provider/google.mjs

@@ -0,0 +1,257 @@
+/**
+ * provider/google.mjs — Google Gemini API transport
+ * Endpoint: POST https://generativelanguage.googleapis.com/v1beta/models/{model}:streamGenerateContent
+ * Docs: https://ai.google.dev/gemini-api/docs
+ */
+
+import { proxyFetch } from "../proxy.mjs"
+import { requestWithRetry } from "./retry.mjs"
+import { effectiveFetchTimeoutMs } from "./core.mjs"
+import { abortError, timeoutError } from "../abort-provenance.mjs"
+
+/** OpenAI 语义 tool_choice → Gemini FunctionCallingConfig（2026-08-31 能力层）。 */
+function mapFunctionCallingConfig(choice) {
+  if (choice === "auto") return { mode: "AUTO" }
+  if (choice === "required") return { mode: "ANY" }
+  if (choice === "none") return { mode: "NONE" }
+  if (choice && typeof choice === "object" && choice.function?.name) return { mode: "ANY", allowedFunctionNames: [choice.function.name] }
+  throw new Error(`Invalid tool_choice for Gemini format: ${JSON.stringify(choice).slice(0, 120)}`)
+}
+
+
+/** Convert OpenAI-format tools to Gemini format */
+export function normalizeTools(tools) {
+  if (!tools?.length) return null
+  return [{
+    functionDeclarations: tools.map((t) => ({
+      name: t.function.name,
+      description: t.function.description || "",
+      parameters: t.function.parameters || { type: "object", properties: {} },
+    })),
+  }]
+}
+
+/**
+ * Convert OpenAI-format messages to Gemini contents array.
+ * Gemini: [{ role: "user"|"model", parts: [{ text }] }]
+ * system → systemInstruction (top-level in request body)
+ */
+export function convertMessages(messages) {
+  const contents = []
+  for (const m of messages) {
+    // system messages are hoisted to systemInstruction by the caller — check the
+    // ORIGINAL role (the remapped role below can never be "system")
+    if (m.role === "system") continue
+    const role = m.role === "assistant" ? "model" : "user"
+
+    const parts = []
+    if (typeof m.content === "string") {
+      parts.push({ text: m.content })
+    } else if (Array.isArray(m.content)) {
+      for (const part of m.content) {
+        if (part.type === "text") parts.push({ text: part.text })
+        else if (part.type === "image_url") {
+          const url = part.image_url?.url || ""
+          const mimeMatch = url.match(/^data:([^;]+);base64,(.+)$/)
+          if (mimeMatch) {
+            parts.push({ inlineData: { mimeType: mimeMatch[1], data: mimeMatch[2] } })
+          }
+        }
+      }
+    }
+    if (parts.length === 0) continue
+
+    // Gemini doesn't allow consecutive same-role messages; merge
+    const last = contents[contents.length - 1]
+    if (last?.role === role) {
+      last.parts.push(...parts)
+    } else {
+      contents.push({ role, parts })
+    }
+  }
+  return contents
+}
+
+/** Build and send a Gemini chat request. Returns the same shape as core.mjs chat.
+ *  2026-08-31 会诊 #6：接入 rateGate/recordRate（原实现完全绕过 TPM/RPM 闸门）。 */
+export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal, toolChoice }) {
+  const systemMessages = messages.filter((m) => m.role === "system")
+  const contents = convertMessages(messages)
+
+  const body = {
+    contents,
+    generationConfig: {
+      ...(provider.temperature != null ? { temperature: provider.temperature } : {}),
+      ...(provider.maxTokens ? { maxOutputTokens: provider.maxTokens } : {}),
+    },
+    safetySettings: [
+      { category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_NONE" },
+      { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_NONE" },
+      { category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "BLOCK_NONE" },
+      { category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_NONE" },
+    ],
+  }
+  if (systemMessages.length > 0) {
+    body.systemInstruction = {
+      parts: [{ text: systemMessages.map((m) => m.content).join("\n\n") }],
+    }
+  }
+  if (tools?.length) body.tools = tools
+  // 2026-08-31：tool_choice 能力层 → Gemini toolConfig.functionCallingConfig
+  if (toolChoice !== undefined) {
+    body.toolConfig = { functionCallingConfig: mapFunctionCallingConfig(toolChoice) }
+  }
+
+  // Gemini uses API key as query parameter
+  const url = `${provider.baseURL}/models/${provider.model}:streamGenerateContent?alt=sse&key=${encodeURIComponent(provider.apiKey)}`
+
+  if (signal?.aborted) throw abortError(signal, "provider", "transport-google")
+
+  // 会诊 #6：TPM/RPM 闸门 + 记账
+  const { rateGate, recordRate, estimateRequestTokens } = await import("./rate.mjs")
+  const estimated = estimateRequestTokens({ messages })
+  await rateGate(provider, estimated, onWait, signal)
+
+  // 2026-08-31：5xx/网络与 OpenAI 格式统一退避重试链（原完全无重试——Gemini 高峰
+  // 503 直接抛错崩溃整个 turn）
+  const response = await requestWithRetry(
+    () => proxyFetch(url, {
+      method: "POST",
+      headers: { ...(provider.headers ?? {}), "Content-Type": "application/json" }, // 定制头展开（PROVIDER.md §21）——定制头在前、内置头在后：内置头胜出
+      body: JSON.stringify(body),
+      // 2026-09-01：同 core.mjs——绝对墙钟废除；响应头阶段 fetchTimeoutMs（600s 默认），body 阶段读侧 idle 管
+      signal,
+      _headerTimeoutMs: effectiveFetchTimeoutMs(provider),
+      _bodyIdleMs: 120_000,
+    }, provider.proxyUri),
+    { signal, onWait, buildMessage: (status, text) => `Gemini API error ${status}: ${text}` },
+  )
+
+  const result = await parseGeminiStream(response, { onToken, onReasoning, signal })
+  recordRate(provider, estimated, result.usage)
+
+  const usage = result.usage
+  if (usage) {
+    return {
+      content: result.content,
+      reasoning: result.reasoning,
+      usage: {
+        prompt_tokens: usage.prompt_tokens ?? 0,
+        completion_tokens: usage.completion_tokens ?? 0,
+        total_tokens: usage.total_tokens ?? 0,
+      },
+      toolCalls: result.toolCalls,
+    }
+  }
+
+  return { content: result.content, reasoning: result.reasoning, toolCalls: result.toolCalls }
+}
+
+/**
+ * Parse Gemini SSE stream.
+ * Format: data: {...}\n\n (each line is a complete JSON object)
+ */
+async function parseGeminiStream(response, { onToken, onReasoning, signal }) {
+  const result = { content: "", reasoning: "", toolCalls: [], usage: null }
+  const decoder = new TextDecoder()
+  let buffer = ""
+
+  const processData = (data) => {
+    let json
+    try { json = JSON.parse(data) } catch { return }
+    if (!json) return
+
+    if (json.usageMetadata) {
+      result.usage = {
+        prompt_tokens: json.usageMetadata.promptTokenCount || 0,
+        completion_tokens: json.usageMetadata.candidatesTokenCount || 0,
+        total_tokens: json.usageMetadata.totalTokenCount || 0,
+      }
+    }
+
+    const candidate = json.candidates?.[0]
+    if (!candidate) return
+
+    const parts = candidate.content?.parts || []
+    for (const part of parts) {
+      if (part.thought === true && part.text) {
+        result.reasoning += part.text
+        onReasoning?.(part.text)
+      } else if (part.text) {
+        result.content += part.text
+        onToken?.(part.text)
+      } else if (part.functionCall) {
+        const existing = result.toolCalls.find((tc) => tc.name === part.functionCall.name)
+        if (!existing) {
+          result.toolCalls.push({
+            id: part.functionCall.name + "_" + result.toolCalls.length,
+            name: part.functionCall.name,
+            arguments: JSON.stringify(part.functionCall.args || {}),
+          })
+        }
+      }
+    }
+  }
+
+  if (!response.body) throw new Error("No stream response body")
+  // 2026-09-01 读侧 idle 超时（同 sse.mjs）：body 有数据流动即不超时；连续 120s 无新 chunk 判死
+  const READ_IDLE_MS = 120_000
+  let idleTimer = null
+  const armIdle = () => {
+    if (idleTimer) clearTimeout(idleTimer)
+    idleTimer = setTimeout(() => {
+      try { response.body?.destroy(timeoutError(`SSE idle timeout: no data for ${READ_IDLE_MS / 1000}s`, "provider", "google-sse-idle")) } catch { /* already gone */ }
+    }, READ_IDLE_MS)
+    idleTimer.unref?.()
+  }
+  armIdle()
+  try {
+    for await (const chunk of response.body) {
+      armIdle()
+      if (signal?.aborted) {
+        throw abortError(signal, "provider", "transport-google")
+      }
+      buffer += decoder.decode(chunk, { stream: true })
+      // BOM 剥除（会诊 #12）：首个 chunk 可能带 \uFEFF，否则首个 data 事件静默丢失
+      if (buffer.charCodeAt(0) === 0xfeff) buffer = buffer.slice(1)
+      const lines = buffer.split("\n")
+      buffer = lines.pop()
+
+      for (const line of lines) {
+        if (!line.startsWith("data:")) continue
+        const data = line.slice(5).trim()
+        if (!data || data === "[DONE]") continue
+        processData(data)
+      }
+    }
+    buffer += decoder.decode()
+    for (const line of buffer.split("\n")) {
+      if (!line.startsWith("data:")) continue
+      const data = line.slice(5).trim()
+      if (!data || data === "[DONE]") continue
+      processData(data)
+    }
+  } catch (e) {
+    if (idleTimer) clearTimeout(idleTimer)
+    if (e.name === "AbortError" && signal?.reason?.interrupt) {
+      result.interrupted = true
+      result.interruptMessage = signal.reason.message
+      return result
+    }
+    if (hasPartial(e)) {
+      result.partial = true
+      result.networkError = e.message ?? String(e)
+      return result
+    }
+    throw e
+  } finally {
+    if (idleTimer) clearTimeout(idleTimer)
+  }
+
+  return result
+}
+
+/** google.mjs 无 hasChoices 追踪——只有流中途死且已有内容才标 partial（同 sse.mjs 语义的简化版） */
+function hasPartial(e) {
+  return /ECONNRESET|terminated|idle timeout|network/i.test(e?.message ?? "")
+}

package/provider/index.mjs

@@ -0,0 +1,7 @@
+/**
+ * provider/index.mjs — backward-compatible re-export
+ * import { chat } from "./provider" → resolves to this file
+ */
+export { chat, createProvider, stripImagesForTextModel } from "./core.mjs"
+export { listModels } from "./list-models.mjs"
+export { RETRYABLE_STATUS, _rateHooks, estimateText, estimateRequestTokens, rateGate, recordRate } from "./rate.mjs"

package/provider/list-models.mjs

@@ -0,0 +1,163 @@
+/**
+ * list-models.mjs — provider 模型清单拉取（GET /models，按 provider.format 分派——PROVIDER.md §16 M1）。
+ *
+ * 2026-09-10 自 core.mjs 迁出（原实现仅 OpenAI 形状）+ 扩 anthropic / google 两分支：
+ * - openai（缺省/未知 format——与 chat 分派缺省一致）：`GET {baseURL}/models` + Bearer；解析 `data[].id`
+ * - anthropic：`GET {baseURL}/models?limit=1000` + `x-api-key` / `anthropic-version`；`has_more` 时以
+ *   `last_id` 作 `after_id` 翻页跟随（≤10 页——防死循环）
+ * - google：`GET {baseURL}/models?key=…&pageSize=1000`；剥 `models/` 前缀；`nextPageToken` 翻页跟随（≤10 页）
+ *
+ * URL 组合 = `{baseURL}` + 相对路径，与 chat 各 transport 同构——baseURL 自带版本段
+ * （claude 预设 `…/v1` → `…/v1/models`；gemini 预设 `…/v1beta` → `…/v1beta/models`）。
+ * 超时制度沿用原实现（整体 15s + header 15s + body idle 15s；翻页时逐页各自计时；调用方可传
+ * `signal` 短路）。HTTP 非 2xx / 网络失败**抛出**（调用方决定降级——与现实现同）；
+ * 解析保持防御性（字段缺失即跳过该项）。候选不过滤非对话模型（embedding 等——§16.6 #14）。
+ */
+import { proxyFetch } from "../proxy.mjs"
+
+const LIST_TIMEOUT_MS = 15_000
+/** 翻页上限（cursor loop 防死循环——任一分页失败即整体抛出，不部分返回）。 */
+const MAX_PAGES = 10
+const ANTHROPIC_VERSION = "2023-06-01"
+
+/** 单页 GET + JSON 解析（非 2xx → throw；非 JSON 响应 → throw——§2.5 #115 并入 VSC 明确报错）。 */
+async function fetchJson(provider, url, headers, signal) {
+  const opts = {
+    headers,
+    signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(LIST_TIMEOUT_MS)]) : AbortSignal.timeout(LIST_TIMEOUT_MS),
+    _headerTimeoutMs: LIST_TIMEOUT_MS,
+    _bodyIdleMs: LIST_TIMEOUT_MS,
+  }
+  const response = await (provider.proxyUri ? proxyFetch(url, opts, provider.proxyUri) : fetch(url, opts))
+  if (!response.ok) {
+    const text = await response.text().catch(() => "")
+    const e = new Error(`GET /models failed ${response.status}: ${text.slice(0, 200)}`)
+    e.status = response.status // 展示面可判「不可用」
+    throw e
+  }
+  const rawText = await response.text().catch(() => "")
+  try {
+    return JSON.parse(rawText)
+  } catch {
+    // 网关/代理返回 HTML 等非 JSON——拉不到清单（明确报错，不静默空清单）
+    throw new Error("GET /models failed: non-JSON response")
+  }
+}
+
+/** 防御性收集：字段缺失/非字符串项跳过。 */
+function collect(rows, pick) {
+  if (!Array.isArray(rows)) return []
+  const out = []
+  for (const row of rows) {
+    const v = pick(row)
+    if (typeof v === "string" && v) out.push(v)
+  }
+  return out
+}
+
+async function listOpenai(provider, signal) {
+  const url = `${provider.baseURL}/models`
+  const data = await fetchJson(provider, url, { ...(provider.headers ?? {}), Authorization: `Bearer ${provider.apiKey ?? ""}` }, signal)
+  return collect(data?.data, (m) => m?.id)
+}
+
+async function listAnthropic(provider, signal) {
+  const headers = { ...(provider.headers ?? {}), "x-api-key": provider.apiKey ?? "", "anthropic-version": ANTHROPIC_VERSION }
+  const base = `${provider.baseURL}/models?limit=1000`
+  const out = []
+  let afterId = null
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const url = afterId ? `${base}&after_id=${encodeURIComponent(afterId)}` : base
+    const data = await fetchJson(provider, url, headers, signal)
+    out.push(...collect(data?.data, (m) => m?.id))
+    if (!data?.has_more) return out
+    afterId = typeof data?.last_id === "string" && data.last_id ? data.last_id : null
+    if (!afterId) return out // has_more 但无游标——无法继续，避免死循环
+  }
+  return out
+}
+
+async function listGoogle(provider, signal) {
+  const headers = { ...(provider.headers ?? {}) }
+  const base = `${provider.baseURL}/models?key=${encodeURIComponent(provider.apiKey ?? "")}&pageSize=1000`
+  const out = []
+  let pageToken = null
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const url = pageToken ? `${base}&pageToken=${encodeURIComponent(pageToken)}` : base
+    const data = await fetchJson(provider, url, headers, signal)
+    out.push(...collect(data?.models, (m) => (typeof m?.name === "string" ? m.name.replace(/^models\//, "") : null)))
+    if (typeof data?.nextPageToken !== "string" || !data.nextPageToken) return out
+    pageToken = data.nextPageToken
+  }
+  return out
+}
+
+/** List available model IDs from the provider's /models endpoint (format 分派——M1)。 */
+export async function listModels(provider, { signal } = {}) {
+  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
+  const ids = format === "anthropic" ? await listAnthropic(provider, signal)
+    : format === "google" ? await listGoogle(provider, signal)
+      : await listOpenai(provider, signal)
+  // §2.5 #115 并入（VSC 排序）：返回前本端排序——UI 确定性。
+  return ids.filter((id) => typeof id === "string" && id).sort()
+}
+
+/** 渠道准入失败消息（§2.5 #115 / VSC M8 并入——逐字长句 = 消息本体；状态标签由 UI 层组合）。
+ *  {状态} = HTTP 状态或网络错误摘要。 */
+export function channelUnavailableMessage(error) {
+  const status = Number.isInteger(error?.status) ? String(error.status) : String(error?.message || error)
+  return `该渠道不提供模型列表（GET /models ${status}）——无法选择模型，请改用其他渠道`
+}
+
+// ─── 渠道准入展示态 + 探针（§2.5 #115 / VSC M9 并入）─────────────────────────
+// 记录 = 「最近一次探测的展示结果」，不是阻断缓存：任何配置动作/面板候选拉取都会重探，
+// 失败也绝不阻止重探（失败不缓存语义）。
+// F-W19（`PROVIDER.md` §6.16 M8/M9 补）：落账形态 = 成功 `{ ok: true, ts }` /
+// 失败 `{ ok: false, reason, failure, ts }`——`failure` ∈ { timeout, malformed, hostBusy }。
+const _admission = new Map() // name → { ok: true, ts } | { ok: false, reason, failure, ts }
+
+/** 探针失败分类（核侧两档——`PROVIDER.md` §6.16 M8/M9 补）：
+ *  `timeout` = 超时族（`AbortSignal.timeout` 的 TimeoutError / 代理读侧 abort `trigger"timeout"` /
+ *  消息含 timeout / AbortError）；其余（HTTP 非 2xx / 载荷畸形 / 连接类）一律 `malformed`。
+ *  `hostBusy` 不由核判（核零宿主事件循环观测）——端侧采样器以证据覆盖（`SETTINGS.md` §2.12）。 */
+export function classifyProbeFailure(error) {
+  if (error?.name === "TimeoutError" || error?.name === "AbortError") return "timeout"
+  if (error?.abortInfo?.trigger === "timeout") return "timeout"
+  return /timeout/i.test(String(error?.message ?? "")) ? "timeout" : "malformed"
+}
+
+/** 记录一次渠道准入探测结果（统一盖落账时间 `ts`——调用方显式给定则尊重：测试缝注入）。 */
+export function recordAdmission(name, result) {
+  if (!name) return
+  const rec = { ...(result ?? {}) }
+  if (!Number.isFinite(rec.ts)) rec.ts = Date.now()
+  _admission.set(name, rec)
+}
+
+/** 读取渠道准入展示态（未探过 → null）。 */
+export function admissionOf(name) {
+  return _admission.get(name) ?? null
+}
+
+// 测试缝（先例 rate.mjs `_rateHooks`）：探针实现可注入——缺省 = 真探。
+let _probeImpl = null
+export function _setProbeImplForTest(fn) { _probeImpl = fn }
+export function _resetAdmissionForTest() { _admission.clear(); _probeImpl = null }
+
+/** 配置阶段准入探针：对目标渠道探一次 GET /models 并记录结果。
+ *  探通 → 渠道可用（探得候选可直接用）；探不通 → 记录失败 + 返回失败消息。
+ *  **绝不抛出**（不阻断任何配置写）；失败不缓存——下次配置动作重探。 */
+export async function probeChannelModels(name, provider) {
+  if (_probeImpl) return _probeImpl(name, provider)
+  try {
+    const models = await listModels(provider)
+    recordAdmission(name, { ok: true })
+    return { ok: true, models }
+  } catch (e) {
+    const error = channelUnavailableMessage(e)
+    recordAdmission(name, { ok: false, reason: error, failure: classifyProbeFailure(e) })
+    return { ok: false, error }
+  }
+}

package/provider/normalize.mjs

@@ -0,0 +1,81 @@
+/**
+ * provider/normalize.mjs — pre-send payload normalization (2026-08-31 extract).
+ *
+ * Split from core.mjs (TODO #2: 420 lines, past the 300 advisory). These two
+ * pure functions sanitize the message array right before it hits the wire;
+ * no dependency on chat()/retry logic. core.mjs re-exports them so
+ * provider/index.mjs and tool-pairing.test.mjs keep their import paths.
+ * The caller passes the spec (providerSpec from core.mjs — provider-aware).
+ */
+
+const RASTER_IMAGE_URL = /^data:image\/(png|jpe?g|gif|webp);base64,/
+
+export function stripImagesForTextModel(messages, spec) {
+  let changed = false
+  const out = messages.map((m) => {
+    if (!Array.isArray(m.content) || !m.content.some((p) => p?.type === "image_url")) return m
+    let msgChanged = false
+    const parts = m.content.map((p) => {
+      if (p?.type !== "image_url") return p
+      const url = p.image_url?.url || ""
+      if (!url.startsWith("data:")) return p
+      if (spec.multimodal && RASTER_IMAGE_URL.test(url)) return p
+      msgChanged = true
+      const reason = spec.multimodal
+        ? `unsupported format ${url.match(/^data:([^;,]+)/)?.[1] || "unknown"}`
+        : "this model does not support image input"
+      return { type: "text", text: `[image omitted — ${reason}]` }
+    })
+    if (!msgChanged) return m
+    changed = true
+    return { ...m, content: parts }
+  })
+  return changed ? out : messages
+}
+
+/**
+ * Enforce the OpenAI tool-message protocol on the outgoing payload: every tool message must
+ * immediately follow the assistant message declaring its tool_call_id, and every declared
+ * tool_call must have a result. Strict providers (DeepSeek) reject the whole request with 400
+ * ("Messages with role 'tool' must be a response to a preceding message with 'tool_calls'").
+ * History can legitimately violate this — parallel read_image injects a user message between
+ * tool results, compaction splits, interrupted sessions leave dangling tool_calls — so sanitize
+ * at send time. History itself is left untouched.
+ */
+export function normalizeToolPairing(messages) {
+  // Detach all tool messages; reinsert each right after its owner assistant.
+  const toolById = new Map()
+  const rest = []
+  for (const m of messages) {
+    if (m.role === "tool") {
+      if (!toolById.has(m.tool_call_id)) toolById.set(m.tool_call_id, m)
+    } else {
+      rest.push(m)
+    }
+  }
+  if (toolById.size === 0 && !messages.some((m) => m.role === "assistant" && m.tool_calls?.length)) {
+    return messages // no tool messages AND no tool_calls declared — nothing to enforce
+  }
+  const out = []
+  for (const m of rest) {
+    out.push(m)
+    if (m.role !== "assistant" || !m.tool_calls?.length) continue
+    for (const tc of m.tool_calls) {
+      const t = toolById.get(tc.id)
+      if (t) {
+        toolById.delete(tc.id)
+        out.push(t)
+      } else {
+        // Declared tool_call with no recorded result (interrupted session / compaction split)
+        out.push({
+          role: "tool",
+          tool_call_id: tc.id,
+          content: "[Tool result missing: the call was interrupted or its result was dropped by context compaction]",
+        })
+      }
+    }
+  }
+  // Leftovers in toolById are orphans (owner assistant compacted away or never recorded) — dropped
+  return out
+}
+

package/provider/rate.mjs

@@ -0,0 +1,168 @@
+/**
+ * provider/rate.mjs — TPM/RPM proactive throttling gate
+ * Sliding-window accounting; pre-check budget before sending requests; sleep until window frees space when over budget.
+ */
+import { abortError } from "../abort-provenance.mjs"
+import { specForModel } from "../model-specs.mjs"
+
+export const RETRYABLE_STATUS = new Set([408, 409, 425, 429, 500, 502, 503, 504])
+export const MAX_RETRIES = 3
+export const MAX_CONTINUATIONS = 3
+export const RATE_LIMIT_BACKOFF_MS = [15_000, 30_000, 60_000]
+
+/**
+ * Test hooks: sleep/clock/window length are replaceable (offline tests can't really wait 60s).
+ * Production code should never call setTimeout/sleep directly — always go through these.
+ */
+export const _rateHooks = {
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now: () => Date.now(),
+  windowMs: 60_000,
+}
+
+/**
+ * Abort-aware sleep（§2.5 #114 并入——VSC 侧 `abortableSleep` 归位）：用户按 Stop 时立即
+ * 中断（拒绝 AbortError）——重试退避与限流等待不得在中断后再扣住回合最长 60s。
+ */
+export async function abortableSleep(ms, signal) {
+  if (!signal) return _rateHooks.sleep(ms)
+  if (signal.aborted) throw new DOMException("Aborted", "AbortError")
+  await new Promise((resolve, reject) => {
+    const t = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve() }, ms)
+    function onAbort() { clearTimeout(t); reject(new DOMException("Aborted", "AbortError")) }
+    signal.addEventListener("abort", onAbort, { once: true })
+  })
+}
+
+const rateWindows = new Map() // key → { tokens: [{ts, n}], requests: [ts] }
+
+function rateKey(provider) {
+  // Normalize: /beta and /v1 are treated as the same account's rate-limit window (DeepSeek prefix continuation switches to /beta endpoint)
+  const base = provider.baseURL.replace(/\/beta$/, "/v1")
+  return `${base}|${provider.apiKey ?? ""}`
+}
+
+/** Rough estimate of text token count.
+ *  ASCII ~4 chars/token; non-ASCII (CJK/emoji) ~1 char/token (conservative; measured BPE is 1.5-2.5 chars/token).
+ *  §2.5 #114 并入（token 估算取并集）：数组内容按 part 分派——text 走单串估算，
+ *  image_url part 计 85 tokens（VSC 侧口径）。 */
+export function estimateText(s) {
+  if (!s) return 0
+  if (Array.isArray(s)) {
+    let tokens = 0
+    for (const part of s) {
+      if (part?.type === "text") tokens += _estimateSingle(String(part.text ?? ""))
+      else if (part?.type === "image_url") tokens += 85
+    }
+    return tokens
+  }
+  return _estimateSingle(String(s))
+}
+
+function _estimateSingle(s) {
+  let nonAscii = 0
+  for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0x7f) nonAscii++
+  return Math.ceil((s.length - nonAscii) / 4) + nonAscii
+}
+
+/** Estimated prompt tokens for this request */
+export function estimateRequestTokens(body) {
+  let tokens = 0
+  for (const m of body.messages ?? []) {
+    tokens += estimateText(m.content)
+    if (typeof m.reasoning_content === "string") tokens += estimateText(m.reasoning_content)
+    for (const tc of m.tool_calls ?? []) {
+      tokens += estimateText(tc.function?.name ?? "") + estimateText(tc.function?.arguments ?? "")
+    }
+  }
+  if (body.tools) tokens += estimateText(JSON.stringify(body.tools))
+  // §2.5 #114 并入（token 估算取并集）：max_tokens（输出预算）计入请求估算（VSC 侧口径）。
+  if (body.max_tokens) tokens += body.max_tokens
+  return tokens
+}
+
+/** Gate: sleep until window frees space when over budget */
+export async function rateGate(provider, estimated, onWait, signal) {
+  // §2.5 #114 并入（默认限流口径取 VSC 的 spec 回退）：provider 未显式配置 tpm/rpm 时
+  // 回退到模型规格表的限流字段（当前表内无 tpm/rpm 字段 ⇒ 回退为未配置，行为不变；
+  // 表后续补字段时自动生效）。
+  const spec = specForModel(provider.model)
+  const configuredTpm = provider.tpm ?? spec?.tpm ?? null
+  const configuredRpm = provider.rpm ?? spec?.rpm ?? null
+  // 2026-08-31 会诊 #16：单请求估算已超 tpm 时原实现静默放行（必然撞服务端 429）。
+  // 保持放行（tpm 置 null 防止 overTokens 恒正值死等），但明确告警让上层/用户知情。
+  let warned = false
+  if (configuredTpm != null && estimated > configuredTpm) {
+    onWait?.({ phase: "warn", message: `estimated ${estimated} tokens > tpm ${configuredTpm} — request proceeds and may hit a server 429` })
+    warned = true
+  }
+  const tpm = configuredTpm != null && estimated <= configuredTpm ? configuredTpm : null
+  const rpm = configuredRpm
+  if (tpm == null && rpm == null) return
+  // §2.5 #114 并入（VSC 默认维度回退——A19 影响面②）：单维度配置时补另一维度默认
+  //（只配 rpm 的场景多一层 TPM 闸——限流更早触发；缺省值逐字同 VSC）。
+  const effectiveTpm = tpm ?? 1_000_000
+  const effectiveRpm = rpm ?? 500
+  // §2.5 #114 并入（VSC 防死等守护）：`estimated > effectiveTpm` 时 overTokens 恒真
+  //（usedTokens ≥ 0）⇒ 窗口等待循环永不放行（sleep 循环无限空转）——告警 + 记账 +
+  //直接放行，不再进窗口等待（VSC 同款提前放行语义）。
+  if (estimated > effectiveTpm) {
+    if (!warned) onWait?.({ phase: "warn", message: `estimated ${estimated} tokens > tpm ${effectiveTpm} — request proceeds and may hit a server 429` })
+    const wOver = rateWindows.get(rateKey(provider)) ?? { tokens: [], requests: [] }
+    rateWindows.set(rateKey(provider), wOver)
+    const nowOver = _rateHooks.now()
+    wOver.tokens.push({ ts: nowOver, n: estimated })
+    wOver.requests.push(nowOver)
+    return
+  }
+  const w = rateWindows.get(rateKey(provider)) ?? { tokens: [], requests: [] }
+  rateWindows.set(rateKey(provider), w)
+  for (;;) {
+    const now = _rateHooks.now()
+    const cutoff = now - _rateHooks.windowMs
+    w.tokens = w.tokens.filter((e) => e.ts > cutoff)
+    w.requests = w.requests.filter((ts) => ts > cutoff)
+    const usedTokens = w.tokens.reduce((s, e) => s + e.n, 0)
+    const overTokens = usedTokens + estimated - effectiveTpm
+    const overRequests = w.requests.length + 1 - effectiveRpm
+    if (overTokens <= 0 && overRequests <= 0) break
+    let waitMs = _rateHooks.windowMs
+    if (overTokens > 0) {
+      let freed = 0
+      for (const e of w.tokens) {
+        freed += e.n
+        if (freed >= overTokens) {
+          waitMs = Math.min(waitMs, e.ts + _rateHooks.windowMs - now)
+          break
+        }
+      }
+    }
+    if (overRequests > 0) {
+      waitMs = Math.min(waitMs, w.requests[overRequests - 1] + _rateHooks.windowMs - now)
+    }
+    waitMs = Math.max(waitMs, 50)
+    onWait?.({ phase: "gate", seconds: Math.ceil(waitMs / 1000) })
+    // §2.5 #114 并入：等待改为可中断实现（abortableSleep）——abort 仍走 CLI 溯源标注。
+    await abortableSleep(waitMs, signal).catch((e) => {
+      if (e?.name === "AbortError") throw abortError(signal, "provider", "rate-gate")
+      throw e
+    })
+    if (signal?.aborted) throw abortError(signal, "provider", "rate-gate")
+  }
+}
+
+/** Accounting: record measured usage after response returns */
+export function recordRate(provider, estimated, usage) {
+  if (provider.tpm == null && provider.rpm == null) return
+  const key = rateKey(provider)
+  const w = rateWindows.get(key) ?? { tokens: [], requests: [] }
+  const now = _rateHooks.now()
+  const cutoff = now - _rateHooks.windowMs
+  w.tokens = w.tokens.filter((e) => e.ts > cutoff)
+  w.requests = w.requests.filter((ts) => ts > cutoff)
+  w.requests.push(now)
+  w.tokens.push({ ts: now, n: usage ? (usage.prompt_tokens ?? estimated) + (usage.completion_tokens ?? 0) : estimated })
+  // Delete entry when window is empty, preventing unbounded Map growth across long-running provider configs
+  if (w.tokens.length === 0 && w.requests.length === 0) rateWindows.delete(key)
+  else rateWindows.set(key, w)
+}