feat(providers): add Responses terminal repair escape hatch for custom providers

docs-site/src/content/docs/ja/reference/configuration/providers.md

@@ -355,3 +355,15 @@ OpenRouter は、複数の推論プロバイダーを通じて 1 つのモデル
   "visionSidecar": { "enabled": true }
 }
 ```
+
+### Responses ターミナル イベント修復ポリシー
+
+これらの3つのキーは、ネイティブ Responses ストリームがターミナル イベントを配信しない場合に、制限付きの修復を必要とするカスタム プロバイダー向けの制御機能です。要求されたモデルごとに、有効なアダプター（プロバイダーのアダプターまたはその modelAdapters オーバーライド）が openai-responses である必要があります。Chat Completions やその他の配線はオプトインしません。モデルの一致は大文字と小文字を区別しません。
+
+解決の優先順位：
+
+1. 一致する modelResponsesCompatibility エントリは、モデルをターミナル修復にオプトインします。デフォルトの猶予時間は 500 ms です（一致する modelResponsesTerminalRepair が明示的な猶予時間を指定していない限り）。
+2. それ以外の場合、一致する modelResponsesTerminalRepair エントリがモデルごとの猶予時間を指定します。
+3. それ以外の場合、responsesTerminalRepair がプロバイダー レベルのフォールバックを提供します。
+
+猶予時間の値は正の有限ミリ秒であり、ランタイムは切り捨てて最大 60 秒に制限します。設定検証では無効な値を拒否し、正規の ChatGPT forward プロバイダーではこれら3つのキーを拒否します（プロバイダー名ではなく adapter、authMode、正規化 baseUrl で判定）。

docs-site/src/content/docs/ko/reference/configuration/providers.md

@@ -356,3 +356,15 @@ OpenRouter는 하나의 모델을 여러 추론 공급자로 제공할 수 있
   "visionSidecar": { "enabled": true }
 }
 ```
+
+### Responses 터미널 이벤트 복구 정책
+
+이 세 가지 키는 네이티브 Responses 스트림이 터미널 이벤트를 전달하지 않을 때 제한된 복구가 필요한 커스텀 공급자를 위한 제어 항목입니다. 요청된 각 모델에 대해 유효한 어댑터(공급자 어댑터 또는 해당 modelAdapters 재정의)가 openai-responses여야 합니다. Chat Completions 및 기타 와이어는 활성화되지 않습니다. 모델 매칭은 대소문자를 구분하지 않습니다.
+
+해석 우선순위:
+
+1. 일치하는 modelResponsesCompatibility 항목은 모델을 터미널 복구에 포함시킵니다. 기본 유예 시간은 500ms입니다(modelResponsesTerminalRepair에 명시적인 유예 시간이 제공되지 않는 한).
+2. 그렇지 않으면 일치하는 modelResponsesTerminalRepair 항목이 모델별 유예 시간을 제공합니다.
+3. 그렇지 않으면 responsesTerminalRepair가 공급자 수준의 대체값을 제공합니다.
+
+유예 시간 값은 양의 유한 밀리초여야 하며, 런타임은 이를 버림 처리하고 최대 60초로 제한합니다. 설정 검증은 잘못된 값을 거부하고 정식 ChatGPT forward 공급자에서 이 세 가지 키를 거부합니다(공급자 이름이 아닌 adapter, authMode, 정규화된 baseUrl 기준).

docs-site/src/content/docs/reference/configuration/providers.md

@@ -100,6 +100,9 @@ differing backup and rewrites known legacy namespaced selected ids to bare ids.
 | `modelSupportsReasoningSummaries?` | `Record<string, boolean>` | Set a model to `false` to stop advertising summaries and strip summary-delivery fields. |
 | `modelReasoningSummaryDelivery?` | `Record<string, "sequential" \| "sequential_cutoff" \| "concurrent" \| "concurrent_cutoff">` | Per-model Responses delivery enum; rewrites an existing delivery field. |
 | `modelAdapters?` | `Record<string, string>` | Per-model `openai-chat` or `openai-responses` wire override for mixed-wire gateways. Explicit entries beat registry defaults. The OpenCode Go preset selects Responses for `gpt-5.6-luna` while leaving sibling models on their documented wires; DeepSeek can select native Responses for `deepseek-v4-flash`; and GitHub Copilot declares Responses-only defaults for its GPT-5 family (`gpt-5.3-codex`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`) because those models reject `/chat/completions` for agent traffic. Models without a built-in default (for example `gpt-5.4-nano`) can be opted in here. Single-wire upstream pins and canonical ChatGPT forward reject overrides. |
+| `modelResponsesCompatibility?` | `Record<string, "terminal-repair">` | Case-insensitive per-model opt-in for the Responses terminal-repair policy on custom providers. A matching model gets the 500 ms default grace unless `modelResponsesTerminalRepair` supplies an explicit grace. The effective model wire must be `openai-responses`; canonical ChatGPT forward rejects this key. |
+| `modelResponsesTerminalRepair?` | `Record<string, number \| { graceMs: number }>` | Case-insensitive per-model terminal-repair grace in milliseconds. It overrides the compatibility default and takes precedence over `responsesTerminalRepair`; positive values are floored and capped at 60 seconds. Invalid or ambiguous case-folded entries fail closed at resolution. |
+| `responsesTerminalRepair?` | `"terminal-repair" \| number \| { graceMs: number }` | Provider-level terminal-repair fallback for models using the `openai-responses` wire. The string selects the 500 ms default; numeric/object values set the grace and are capped at 60 seconds. It is considered only after compatibility and explicit per-model settings, and is rejected on the canonical ChatGPT forward provider. |
 | xAI Responses opt-in (dashboard) | switch | For `xai` only, atomically sets or clears the `grok-4.5` and `grok-4.6` `modelAdapters` entries. A hand-edited single entry appears as mixed until the next switch write normalizes both. Other overrides and tier behavior are unchanged. |
 | `modelPreferHostedTools?` | `Record<string,string[]>` | Exact-model opt-in for non-forward Responses gateways that reserve a hosted-tool namespace. Currently accepts only `["image_generation"]`; a matching model must use the `openai-responses` wire and support that hosted tool. It removes colliding client `image_gen` declarations and rewrites their selectors to preserve caller tool choice. For OpenAI API virtual `-pro` models, the selected public ID is matched first and the resolved base wire-model ID is a fallback. `modelAdapters` resolves the public ID first, then the base ID; the second resolution determines the final wire. Other models retain normal alias behavior. |
 | `reasoningEffortMap?` | `Record<string, string>` | Provider-wide wire aliases for reasoning labels. |
@@ -132,6 +135,36 @@ differing backup and rewrites known legacy namespaced selected ids to bare ids.
 | `unsafeAllowNativeLocalExec?` | `boolean` | Cursor legacy boolean, equivalent to `nativeLocalExec: "on"` only when the newer field is unset. |
 | `nativeLocalExec?` | `"off" \| "codex-sandbox" \| "on"` | Cursor local-exec policy. `off` is default; `codex-sandbox` currently fails closed like `off`. |
 
+### Responses terminal-repair policy
+
+These three keys are overlapping controls for custom providers that need a bounded repair when a
+native Responses stream does not deliver its terminal event. For each requested model, the
+effective adapter (the provider adapter or its `modelAdapters` override) must be
+`openai-responses`; Chat Completions and other wires never opt in. Model matching is
+case-insensitive.
+
+Resolution uses this precedence:
+
+1. A matching `modelResponsesCompatibility` entry opts the model into terminal repair. Its
+   default grace is 500 ms, unless a matching `modelResponsesTerminalRepair` entry supplies an
+   explicit grace.
+2. Otherwise, a matching `modelResponsesTerminalRepair` entry supplies the per-model grace.
+3. Otherwise, `responsesTerminalRepair` supplies the provider-level fallback.
+
+Grace values are positive finite milliseconds, and the runtime floors them and caps any result at
+60 seconds. Config validation rejects malformed values and rejects all three keys on the canonical
+ChatGPT forward provider (matching by adapter, authMode, and normalized baseUrl configuration, not provider name). The runtime resolver is defense in depth: an invalid or ambiguous
+case-folded per-model entry is not selected, so resolution fails closed instead of choosing an
+arbitrary entry.
+
+#### Decision Log: why three overlapping knobs?
+
+`modelResponsesCompatibility` provides a readable opt-in with a safe default, while
+`modelResponsesTerminalRepair` handles models that need a different grace period. The
+provider-level `responsesTerminalRepair` covers a gateway whose Responses models share one policy.
+Keeping all three preserves simple compatibility migration without giving a broad default priority
+over an explicit per-model choice.
+
 ### FastWire B1 capability migration
 
 Fast capability and arbitrary Chat caller-tier forwarding are independent after FastWire B1. The

docs-site/src/content/docs/ru/reference/configuration/providers.md

@@ -441,3 +441,15 @@ Pool/Direct рекламирует `922000`; синхронизированны
   "visionSidecar": { "enabled": true }
 }
 ```
+
+### Политика восстановления терминальных событий Responses
+
+Эти три ключа представляют собой перекрывающиеся элементы управления для кастомных провайдеров, которым требуется ограниченное восстановление, когда нативный поток Responses не доставляет свое терминальное событие. Для каждой запрошенной модели эффективный адаптер (адаптер провайдера или его переопределение modelAdapters) должен быть openai-responses. Сопоставление моделей нечувствительно к регистру.
+
+Приоритет разрешения:
+
+1. Соответствующая запись modelResponsesCompatibility включает модель в восстановление (default 500 ms, если modelResponsesTerminalRepair не задает явный grace).
+2. Иначе соответствующая запись modelResponsesTerminalRepair задает grace для конкретной модели.
+3. Иначе responsesTerminalRepair задает значение fallback на уровне провайдера.
+
+Значения grace — положительные конечные миллисекунды (максимум 60 секунд). Валидация конфигурации отклоняет некорректные значения и запрещает эти ключи для canonical ChatGPT forward (по adapter, authMode и baseUrl).

docs-site/src/content/docs/zh-cn/reference/configuration/providers.md

@@ -358,3 +358,15 @@ OpenRouter 可以通过多个推理提供者来提供同一个模型。`openRout
   "visionSidecar": { "enabled": true }
 }
 ```
+
+### Responses 终端事件修复策略 (Terminal-Repair Policy)
+
+这三个配置键是针对自定义 Provider 提供的重叠控制项，用于在原生 Responses 流未送达终端事件时提供有界的修复机制。对于每个请求的模型，有效适配器（Provider 的 adapter 或其 modelAdapters 覆盖）必须为 openai-responses；Chat Completions 与其他线协议绝不启用。模型匹配不区分大小写。
+
+解析优先级如下：
+
+1. 匹配的 modelResponsesCompatibility 条目为模型启用终端修复，默认宽限期为 500 毫秒（除非匹配的 modelResponsesTerminalRepair 提供显式宽限期）。
+2. 否则，匹配的 modelResponsesTerminalRepair 条目提供 per-model 宽限期。
+3. 否则，由 responsesTerminalRepair 提供 Provider 级别的回退值。
+
+宽限期数值必须为正有限毫秒数，Runtime 会对其取整并将上限约束在 60 秒。配置验证会拒绝格式错误的值，并在规范的 ChatGPT forward Provider 上拒绝这三个键（通过 adapter、authMode 与规范化 baseUrl 判定，而非 Provider 名称启发式）。Runtime 解析器实施纵深防御：无效或大小写冲突的 per-model 条目不会被选取，从而 fail-closed 拒绝，而非任意挑选条目。

docs-site/src/content/docs/zh-tw/reference/configuration/providers.md

@@ -326,3 +326,15 @@ OpenRouter 可透過多個推論供應商提供一個模型。`openRouterRouting
   "visionSidecar": { "enabled": true }
 }
 ```
+
+### Responses 終端事件修復策略 (Terminal-Repair Policy)
+
+這三個設定鍵是針對自定義 Provider 所提供的重疊控制項，用於在原生 Responses 串流未送達終端事件時提供有界的修復機制。對於每個請求的模型，有效適配器（Provider 的 adapter 或其 modelAdapters 覆寫）必須為 openai-responses；Chat Completions 與其他 wire 格式絕不啟用。模型匹配不區分大小寫。
+
+解析優先級如下：
+
+1. 匹配的 modelResponsesCompatibility 項目為模型啟用終端修復，預設寬限期為 500 毫秒（除非匹配的 modelResponsesTerminalRepair 提供明確寬限期）。
+2. 否則，匹配的 modelResponsesTerminalRepair 項目提供 per-model 寬限期。
+3. 否則，由 responsesTerminalRepair 提供 Provider 級別的回退值。
+
+寬限期數值必須為正有限毫秒數，Runtime 會對其取整並將上限約束在 60 秒。設定驗證會拒絕格式錯誤的值，並在規範的 ChatGPT forward Provider 上拒絕這三個鍵（透過 adapter、authMode 與正規化 baseUrl 判定，而非 Provider 名稱啟發式）。Runtime 解析器實施深度防禦：無效或大小寫衝突的 per-model 項目不會被選取，從而 fail-closed 拒絕，而非任意挑選項目。

src/config.ts

@@ -72,7 +72,7 @@ import {
   type FastWire,
   type ProviderCostOverlay,
 } from "./types";
-import { OPENAI_CODEX_PROVIDER_ID } from "./providers/openai-tiers";
+import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "./providers/openai-tiers";
 import { modelAutoCompactTokenLimitsConfigError } from "./providers/auto-compact-budget";
 import { fastWireDeclarationError, hasFastWireCapabilityConflict } from "./providers/fastwire";
 import {
@@ -709,6 +709,92 @@ export function modelPreferHostedToolsConfigError(
   return null;
 }
 
+/**
+ * Validate a provider's per-model wire override map (#404).
+ *
+ * Rejects, rather than silently ignoring, configurations the resolver would refuse:
+ * a value outside the allowed wires, a model the upstream pins to one wire, and any
+ * override on a canonical forward provider (where switching wires would drop the
+ * caller's forwarded credential). Silently dropping them would leave the user
+ * believing an override is in effect.
+ */
+export function modelResponsesCompatibilityConfigError(
+  value: unknown,
+  field = "modelResponsesCompatibility",
+  providerName?: string,
+  provider?: { adapter?: unknown; authMode?: unknown; baseUrl?: unknown },
+): string | null {
+  if (value === undefined) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
+  const entries = Object.entries(value);
+  if (entries.length > 0 && provider && isCanonicalOpenAiForwardProvider(provider as OcxProviderConfig)) {
+    return `${field} is not supported on the canonical ChatGPT forward provider`;
+  }
+  const seen = new Set<string>();
+  for (const [key, entry] of entries) {
+    const lower = key.toLowerCase();
+    if (seen.has(lower)) {
+      return `${field} contains duplicate case-insensitive model id "${key}"`;
+    }
+    seen.add(lower);
+    if (!key.trim() || key !== key.trim()) return `${field} keys must be nonblank trimmed model ids`;
+    if (entry !== "terminal-repair") {
+      return `${field}.${key} must be "terminal-repair"`;
+    }
+  }
+  return null;
+}
+
+export function modelResponsesTerminalRepairConfigError(
+  value: unknown,
+  field = "modelResponsesTerminalRepair",
+  providerName?: string,
+  provider?: { adapter?: unknown; authMode?: unknown; baseUrl?: unknown },
+): string | null {
+  if (value === undefined) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
+  const entries = Object.entries(value);
+  if (entries.length > 0 && provider && isCanonicalOpenAiForwardProvider(provider as OcxProviderConfig)) {
+    return `${field} is not supported on the canonical ChatGPT forward provider`;
+  }
+  const seen = new Set<string>();
+  for (const [key, entry] of entries) {
+    const lower = key.toLowerCase();
+    if (seen.has(lower)) {
+      return `${field} contains duplicate case-insensitive model id "${key}"`;
+    }
+    seen.add(lower);
+    if (!key.trim() || key !== key.trim()) return `${field} keys must be nonblank trimmed model ids`;
+    const grace = typeof entry === "number" ? entry : (typeof entry === "object" && entry ? (entry as { graceMs?: unknown }).graceMs : null);
+    if (typeof grace !== "number" || !Number.isFinite(grace) || Math.floor(grace) <= 0) {
+      return `${field}.${key} must be a positive number of milliseconds or { graceMs: number }`;
+    }
+  }
+  return null;
+}
+
+export function responsesTerminalRepairConfigError(
+  value: unknown,
+  field = "responsesTerminalRepair",
+  providerName?: string,
+  provider?: { adapter?: unknown; authMode?: unknown; baseUrl?: unknown },
+): string | null {
+  if (value === undefined) return null;
+  if (provider && isCanonicalOpenAiForwardProvider(provider as OcxProviderConfig)) {
+    return `${field} is not supported on the canonical ChatGPT forward provider`;
+  }
+  if (value === "terminal-repair") return null;
+  const grace = typeof value === "number" ? value : (typeof value === "object" && value ? (value as { graceMs?: unknown }).graceMs : null);
+  if (typeof grace !== "number" || !Number.isFinite(grace) || Math.floor(grace) <= 0) {
+    return `${field} must be "terminal-repair", a positive number of milliseconds, or { graceMs: number }`;
+  }
+  return null;
+}
+
 const CODEX_ACCOUNT_NAMESPACES_RECORD_ERROR =
   "codexAccountNamespaces must be a plain object mapping account selectors to Codex account ids";
 const CODEX_ACCOUNT_NAMESPACE_KEY_ERROR =
@@ -1081,6 +1167,45 @@ const configSchema = z.object({
         message: modelAdaptersError,
       });
     }
+    const compatError = modelResponsesCompatibilityConfigError(
+      (provider as { modelResponsesCompatibility?: unknown }).modelResponsesCompatibility,
+      "modelResponsesCompatibility",
+      name,
+      provider,
+    );
+    if (compatError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "modelResponsesCompatibility"],
+        message: compatError,
+      });
+    }
+    const modelRepairError = modelResponsesTerminalRepairConfigError(
+      (provider as { modelResponsesTerminalRepair?: unknown }).modelResponsesTerminalRepair,
+      "modelResponsesTerminalRepair",
+      name,
+      provider,
+    );
+    if (modelRepairError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "modelResponsesTerminalRepair"],
+        message: modelRepairError,
+      });
+    }
+    const repairError = responsesTerminalRepairConfigError(
+      (provider as { responsesTerminalRepair?: unknown }).responsesTerminalRepair,
+      "responsesTerminalRepair",
+      name,
+      provider,
+    );
+    if (repairError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "responsesTerminalRepair"],
+        message: repairError,
+      });
+    }
     const preferHostedToolsError = modelPreferHostedToolsConfigError(
       (provider as { modelPreferHostedTools?: unknown }).modelPreferHostedTools,
       "modelPreferHostedTools",