@remodex/rmx 1.0.2

package/src/adapters/openai-chat.ts

@@ -0,0 +1,1265 @@
+import type { AdapterRequest, ProviderAdapter } from "./base";
+import type { AdapterEvent, OcxAssistantMessage, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent, OcxThinkingContent, OcxToolCall, OcxUsage } from "../types";
+import { isAllowedToolChoice, modelInList, namespacedToolName, resolveToolChoiceWireName, toolAllowedByChoice } from "../types";
+import { isReasoningEffortRequired, mapReasoningEffort, modelRecordValue, reasoningControlKindFor } from "../reasoning-effort";
+import { debugProviderDiagnostic } from "../lib/debug";
+import { sseFieldValue } from "../lib/sse-decoder";
+import { isDebugEnabled } from "../lib/debug-settings";
+import { isCyberPolicyCode } from "../lib/errors";
+import { redactSecretString } from "../lib/redact";
+import { contentPartsToText } from "./image";
+import { identifyRoutedModel } from "./identity";
+import { peekReasoningForCall } from "../responses/reasoning-replay-cache";
+import { buildNonOpenAIToolCatalogNudgeForTools, shouldInjectNonOpenAIToolCatalogNudge } from "./tool-catalog-nudge";
+import { openRouterProviderPayload, resolveOpenRouterRouting } from "../providers/openrouter-routing";
+import {
+  isTranslatorBudgetExceededError,
+  retainTranslatedEventBatch,
+  TRANSLATOR_MAX_SSE_EVENT_BYTES,
+  type TranslatorBudget,
+} from "../lib/translator-budget";
+
+// Providers may opt into stripping one trailing "[...]" group from the wire model id.
+// Z.AI needs this because its OpenAI path rejects glm-5.2[1m] with 400 code 1211;
+// unflagged OpenAI-compatible providers and the Anthropic adapter keep ids verbatim.
+export function stripBracketedModelSuffix(modelId: string): string {
+  return modelId.replace(/\[[^\]]*\]\s*$/, "");
+}
+
+// 260715 (issue #126): surface upstream error detail through the web-search sidecar loop.
+// loop.ts only appends a suffix to "Provider error N" when the adapter exposes
+// formatErrorBody; without it, strict OpenAI-compatible backends (NVIDIA NIM pydantic
+// validation, "This model only supports single tool-calls at once!", etc.) were reduced
+// to a bare status code. JSON-only extraction: recognized string fields are returned,
+// HTML/non-JSON bodies yield "" so raw markup is never echoed to the client.
+export function formatOpenAIChatErrorBody(status: number, _headers: Headers, payloadText: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payloadText);
+  } catch {
+    return "";
+  }
+  const detail = extractErrorDetail(parsed);
+  if (!detail) return "";
+  return redactSecretString(detail).slice(0, 400);
+}
+
+function extractErrorDetail(parsed: unknown): string | undefined {
+  if (typeof parsed === "string") return parsed.trim() || undefined;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  const obj = parsed as Record<string, unknown>;
+  // OpenAI shape: { error: { message } } or { error: "..." }
+  const err = obj.error;
+  if (typeof err === "string" && err.trim()) return err.trim();
+  if (err !== null && typeof err === "object" && !Array.isArray(err)) {
+    const msg = (err as Record<string, unknown>).message;
+    if (typeof msg === "string" && msg.trim()) return msg.trim();
+  }
+  // FastAPI/pydantic shape (NVIDIA NIM): { detail: "..." } or { detail: [{ msg, loc }, ...] }
+  const det = obj.detail;
+  if (typeof det === "string" && det.trim()) return det.trim();
+  if (Array.isArray(det)) {
+    const msgs = det
+      .map(item => (item !== null && typeof item === "object" && typeof (item as Record<string, unknown>).msg === "string"
+        ? ((item as Record<string, unknown>).msg as string).trim()
+        : ""))
+      .filter(m => m.length > 0);
+    if (msgs.length > 0) return msgs.join("; ");
+  }
+  // Generic fallbacks: { message } / RFC7807 { title }
+  if (typeof obj.message === "string" && obj.message.trim()) return obj.message.trim();
+  if (typeof obj.title === "string" && obj.title.trim()) return obj.title.trim();
+  return undefined;
+}
+
+// ClinePass live responses observed 2026-08-02 wrap non-stream Chat Completions in
+// `{ success, error, data }`; its public Chat Completions docs do not currently describe that
+// envelope. Keep ordinary OpenAI-shaped responses on the direct path.
+function unwrapChatCompletionPayload(json: Record<string, unknown>): Record<string, unknown> {
+  if ((json.error !== undefined && json.error !== null) || Array.isArray(json.choices)) return json;
+  const data = json.data;
+  return data !== null && typeof data === "object" && !Array.isArray(data)
+    ? data as Record<string, unknown>
+    : json;
+}
+
+interface OpenAIChatError {
+  message?: unknown;
+  code?: unknown;
+  type?: unknown;
+  status?: unknown;
+  metadata?: unknown;
+}
+
+function safeUpstreamRequestId(metadata: unknown): string | undefined {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) return undefined;
+  const record = metadata as Record<string, unknown>;
+  const value = record.request_id ?? record.requestId;
+  if (typeof value !== "string") return undefined;
+  const requestId = value.trim();
+  return /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(requestId)
+    && redactSecretString(requestId) === requestId
+    ? requestId
+    : undefined;
+}
+
+function upstreamErrorEvent(
+  error: unknown,
+  usage?: OcxUsage,
+): Extract<AdapterEvent, { type: "error" }> {
+  const details = error !== null && typeof error === "object" && !Array.isArray(error)
+    ? error as OpenAIChatError
+    : undefined;
+  const rawMessage = typeof error === "string"
+    ? error.trim() || "upstream error"
+    : typeof details?.message === "string" ? details.message : "upstream error";
+  const safeMessage = redactSecretString(rawMessage);
+  const requestId = safeUpstreamRequestId(details?.metadata);
+  const message = requestId !== undefined && !safeMessage.includes(requestId)
+    ? `${safeMessage} (request ID: ${requestId})`
+    : safeMessage;
+  const code = typeof details?.code === "string"
+    ? details.code
+    : typeof details?.code === "number" && Number.isFinite(details.code) && Number.isInteger(details.code)
+      ? String(details.code)
+      : undefined;
+  const errorType = typeof details?.type === "string" ? details.type : undefined;
+  const codeStatus = typeof details?.code === "number"
+    && Number.isInteger(details.code)
+    && details.code >= 100
+    && details.code <= 599
+    ? details.code
+    : undefined;
+  const status = isCyberPolicyCode(code)
+    ? 400
+    : typeof details?.status === "number" && Number.isInteger(details.status)
+      ? details.status
+      : codeStatus;
+  return {
+    type: "error",
+    message,
+    ...(usage !== undefined ? { usage } : {}),
+    ...(code !== undefined ? { code } : {}),
+    ...(errorType !== undefined ? { errorType } : {}),
+    ...(status !== undefined ? { status } : {}),
+  };
+}
+
+function stopReasonFor(finishReason: unknown): "max_tokens" | "content_filter" | undefined {
+  return finishReason === "length"
+    ? "max_tokens"
+    : finishReason === "content_filter"
+      ? "content_filter"
+      : undefined;
+}
+
+function reasoningTextFrom(record: Record<string, unknown>): string | undefined {
+  return typeof record.reasoning_content === "string" && record.reasoning_content.length > 0
+    ? record.reasoning_content
+    : typeof record.reasoning === "string" && record.reasoning.length > 0
+      ? record.reasoning
+      : undefined;
+}
+
+function invalidChoicesEvent(usage?: OcxUsage): Extract<AdapterEvent, { type: "error" }> {
+  return {
+    type: "error",
+    message: "upstream response contained invalid choices",
+    ...(usage !== undefined ? { usage } : {}),
+  };
+}
+
+function developerSystemText(message: OcxMessage): string | undefined {
+  if (message.role !== "developer") return undefined;
+  if (typeof message.content === "string") return message.content;
+  if (message.content.some(part => part.type === "image")) return undefined;
+  return message.content.map(part => (part as OcxTextContent).text).join("");
+}
+
+/**
+ * Chat-completions image_url parts for images carried inside a tool result (issue #888). role:"tool"
+ * content is text-only on every chat provider, so these ride in a follow-up user message instead of
+ * being flattened to the "[image]" marker the model can't actually see. Data URLs and remote https
+ * URLs are both valid in image_url.url, unlike Gemini inline_data which needs base64.
+ */
+function toolResultImageChatParts(content: string | OcxContentPart[]): unknown[] {
+  if (typeof content === "string") return [];
+  const parts: unknown[] = [];
+  for (const p of content) {
+    // Skip parts without a usable URL (the tool-output parser accepts the empty file_id shape):
+    // a {"url":""} part would fail the whole request where the "[image]" marker degrades safely.
+    if (p.type !== "image" || !p.imageUrl) continue;
+    parts.push({ type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } });
+  }
+  return parts;
+}
+
+function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] {
+  const out: unknown[] = [];
+  const { context, options } = parsed;
+  // Mirror the bridge's replay-cache scope (issue #950): provider call ids are
+  // not globally unique, so reasoning must not cross conversation boundaries.
+  const replayCacheScope = parsed._clientThreadId ?? "global";
+
+  // 260718 dangling tool_calls hardening (devlog/_plan/260718_dangling_toolcall_hardening):
+  // strict chat providers (Kimi/Moonshot) 400 when an assistant tool_call is not answered
+  // immediately by role:"tool" messages. Repair order: (1) reattach a real result to its
+  // original call (barrier messages are DEFERRED until the open tool round closes),
+  // (2) synthesize an explicit unavailable-result only when no real result exists,
+  // (3) manufacture an orphan assistant call only when no call occurrence matches at all.
+  // Occurrences are kept as an ordered list (never a Map) so duplicated ids survive.
+  interface PendingToolCall { id: string; name: string }
+  let pendingToolCalls: PendingToolCall[] = [];
+  let deferredBarrierMessages: unknown[] = [];
+  let pendingToolResultImageParts: unknown[] = [];
+  let mintedIdSeq = 0;
+  const seenWireCallIds = new Set<string>();
+
+  const mintCallId = (): string => {
+    let id = "";
+    do {
+      id = `call_ocx_minted_${++mintedIdSeq}`;
+    } while (seenWireCallIds.has(id));
+    seenWireCallIds.add(id);
+    return id;
+  };
+
+  const releaseDeferredBarriers = (): void => {
+    if (deferredBarrierMessages.length === 0) return;
+    out.push(...deferredBarrierMessages);
+    deferredBarrierMessages = [];
+  };
+
+  // Tool-result images collected during the open round land in ONE user vision message once the
+  // round closes — never inside it, where strict providers (Kimi/Moonshot) 400 on interleaved
+  // user messages. Released before deferred barriers so the images stay adjacent to the results
+  // they came from (mirrors google.ts sibling inline_data parts and the Kiro carrier images).
+  const flushToolResultImages = (): void => {
+    if (pendingToolResultImageParts.length === 0) return;
+    out.push({
+      role: "user",
+      content: [
+        { type: "text", text: "[ocx] image output from the preceding tool result(s):" },
+        ...pendingToolResultImageParts,
+      ],
+    });
+    pendingToolResultImageParts = [];
+  };
+
+  // Close an unresolved tool round with explicit unavailable-result messages. The wording
+  // must not claim interruption, success, failure, or user intent: execution status is
+  // UNKNOWN, and for user-input tools this must not read as an answer.
+  const flushPendingToolCalls = (): void => {
+    if (pendingToolCalls.length === 0) return;
+    for (const call of pendingToolCalls) {
+      out.push({
+        role: "tool",
+        tool_call_id: call.id,
+        content: `[ocx] no tool result was recorded for "${call.name}"; execution status unknown — do not treat this as success, failure, or user-provided input.`,
+      });
+    }
+    pendingToolCalls = [];
+    flushToolResultImages();
+    releaseDeferredBarriers();
+  };
+
+  const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider)
+    ? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice)
+    : undefined;
+  // Chat templates used by LM Studio, llama.cpp, and other strict OpenAI-compatible
+  // backends require every system instruction to precede conversation history. Codex can
+  // append developer reminders after user turns, so fold text-only developer messages into
+  // the single leading system message instead of emitting role:"system" in place. Developer
+  // messages with images cannot be represented as system content and remain user-compatible
+  // vision messages at their original position below.
+  const developerSystemParts = context.messages
+    .map(developerSystemText)
+    .filter((part): part is string => part !== undefined && part.length > 0);
+  const systemParts = [
+    ...(context.systemPrompt ?? []),
+    ...developerSystemParts,
+    ...(toolCatalogNudge ? [toolCatalogNudge] : []),
+  ];
+  if (systemParts.length > 0) {
+    // Codex sends its GPT-5 identity prompt for EVERY model (the per-model catalog
+    // base_instructions is ignored at request time). Neutralize that one identity line
+    // so routed, non-OpenAI models don't misreport themselves as GPT-5 / OpenAI — without
+    // leaking the proxy identity into the payload.
+    const wireModelId = provider.modelSuffixBracketStrip
+      ? stripBracketedModelSuffix(parsed.modelId)
+      : parsed.modelId;
+    const sys = identifyRoutedModel(systemParts.join("\n\n"), wireModelId);
+    out.push({ role: "system", content: sys });
+  }
+
+  for (const msg of context.messages) {
+    switch (msg.role) {
+      case "user":
+      case "developer": {
+        const parts = typeof msg.content === "string" ? undefined : msg.content as OcxContentPart[];
+        const hasImages = parts?.some(p => p.type === "image") ?? false;
+        if (msg.role === "developer" && !hasImages) break;
+        let chatMsg: Record<string, unknown>;
+        if (typeof msg.content === "string") {
+          chatMsg = { role: "user", content: msg.content };
+        } else {
+          if (!hasImages) {
+            chatMsg = { role: "user", content: parts!.map(p => (p as OcxTextContent).text).join("") };
+          } else {
+            // Vision: chat-completions content-parts array. Images are only valid on the user role,
+            // and the data URL goes straight into image_url.url (never the token-exploding text path).
+            const chatParts = parts!.map(p => p.type === "image"
+              ? { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } }
+              : { type: "text", text: (p as OcxTextContent).text });
+            chatMsg = { role: "user", content: chatParts };
+          }
+        }
+        // A barrier must not split an open tool round: defer it until the round closes
+        // (real result arrives) or the round is synthesized shut.
+        if (pendingToolCalls.length > 0) deferredBarrierMessages.push(chatMsg);
+        else out.push(chatMsg);
+        break;
+      }
+      case "assistant": {
+        const aMsg = msg as OcxAssistantMessage;
+        const textParts = aMsg.content.filter(p => p.type === "text") as OcxTextContent[];
+        const thinkingParts = aMsg.content.filter(p => p.type === "thinking") as OcxThinkingContent[];
+        const toolCalls = aMsg.content.filter(p => p.type === "toolCall") as OcxToolCall[];
+        const chatMsg: Record<string, unknown> = { role: "assistant" };
+        if (textParts.length > 0) {
+          chatMsg.content = textParts.map(p => p.text).join("");
+        }
+        let reasoningContent = thinkingParts.map(p => p.thinking).join("");
+        // History transformations (compaction, lost assistant turn, resumed
+        // threads) can strip the reasoning item while the tool round survives.
+        // Re-attach the reasoning the bridge recorded for these call ids so
+        // preserveReasoningContentModels providers (DeepSeek thinking mode)
+        // never receive a bare tool-call continuation (issue #950).
+        if (
+          reasoningContent.length === 0
+          && toolCalls.length > 0
+          && modelInList(provider.preserveReasoningContentModels, parsed.modelId)
+        ) {
+          const cached = toolCalls
+            .map(tc => (tc.id ? peekReasoningForCall(tc.id, replayCacheScope) : undefined))
+            .filter((text): text is string => typeof text === "string" && text.length > 0);
+          // Parallel calls share one preceding reasoning block, which is
+          // recorded under every call id — join unique texts only.
+          if (cached.length > 0) {
+            reasoningContent = [...new Set(cached)].join("\n");
+          }
+        }
+        if (reasoningContent.length > 0 && modelInList(provider.preserveReasoningContentModels, parsed.modelId)) {
+          chatMsg.reasoning_content = reasoningContent;
+        }
+        // Skip empty assistant messages: chat APIs like DeepSeek reject an assistant message
+        // with neither content, tool calls, nor a provider-supported reasoning_content field.
+        if (chatMsg.content === undefined && toolCalls.length === 0 && chatMsg.reasoning_content === undefined) break;
+        // A new assistant starts while a previous round is still open: close the previous
+        // round synthetically first so its tool_calls are never left dangling.
+        flushPendingToolCalls();
+        const wireToolCalls = toolCalls.map(tc => {
+          let id = tc.id;
+          if (!id) id = mintCallId();
+          else seenWireCallIds.add(id);
+          return { tc, id };
+        });
+        if (wireToolCalls.length > 0) {
+          chatMsg.tool_calls = wireToolCalls.map(({ tc, id }) => ({
+            id,
+            type: "function",
+            function: { name: namespacedToolName(tc.namespace, tc.name), arguments: JSON.stringify(tc.arguments) },
+          }));
+          // "" instead of null: strict validators (xAI: "Each message must have at least one
+          // content element", langchain#34140) reject content-less assistant history entries.
+          if (!chatMsg.content) chatMsg.content = emptyAssistantContent(provider);
+        }
+        if (chatMsg.reasoning_content !== undefined && chatMsg.content === undefined && chatMsg.tool_calls === undefined) {
+          chatMsg.content = emptyAssistantContent(provider);
+        }
+        out.push(chatMsg);
+        pendingToolCalls = wireToolCalls.map(({ tc, id }) => ({ id, name: namespacedToolName(tc.namespace, tc.name) }));
+        break;
+      }
+      case "toolResult": {
+        let toolCallId = msg.toolCallId;
+        const matchIdx = toolCallId ? pendingToolCalls.findIndex(c => c.id === toolCallId) : -1;
+        if (matchIdx >= 0 && toolCallId) {
+          // Real result reattached to its original call. Barriers were deferred, so the
+          // tool message lands immediately inside the open round.
+          out.push({
+            role: "tool",
+            tool_call_id: toolCallId,
+            content: contentPartsToText(msg.content),
+          });
+          pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content));
+          pendingToolCalls.splice(matchIdx, 1);
+          if (pendingToolCalls.length === 0) {
+            flushToolResultImages();
+            releaseDeferredBarriers();
+          }
+        } else {
+          if (!toolCallId) toolCallId = `call_orphan_${out.length}`;
+          // No matching call in the open round. Close any unresolved round first so the
+          // synthesized orphan pair never splits it, then keep the historical repair:
+          // WS turns can arrive with only tool outputs; chat-completions providers reject a bare
+          // role:"tool" message unless an assistant tool_call with the same id immediately precedes it.
+          flushPendingToolCalls();
+          const name = safeToolName(msg.toolName);
+          // The orphan repair synthesizes an assistant tool call for a result
+          // whose assistant turn was lost; carry the recorded reasoning so the
+          // replayed round stays valid for thinking-mode providers (#950).
+          const cachedReasoning =
+            toolCallId && modelInList(provider.preserveReasoningContentModels, parsed.modelId)
+              ? peekReasoningForCall(toolCallId, replayCacheScope)
+              : undefined;
+          out.push({
+            role: "assistant",
+            content: emptyAssistantContent(provider),
+            ...(cachedReasoning ? { reasoning_content: cachedReasoning } : {}),
+            tool_calls: [{
+              id: toolCallId,
+              type: "function",
+              function: { name, arguments: "{}" },
+            }],
+          });
+          seenWireCallIds.add(toolCallId);
+          out.push({
+            role: "tool",
+            tool_call_id: toolCallId,
+            content: contentPartsToText(msg.content),
+          });
+          pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content));
+          flushToolResultImages();
+        }
+        break;
+      }
+    }
+  }
+
+  // Trailing dangle: a turn interrupted after the assistant requested tools leaves the
+  // round open; close it synthetically (then release any deferred barriers in order).
+  flushPendingToolCalls();
+  releaseDeferredBarriers();
+  return out;
+}
+
+function safeToolName(name: string | undefined): string {
+  const raw = name && name.trim().length > 0 ? name : "tool_result";
+  const sanitized = raw.replace(/[^A-Za-z0-9_-]/g, "_");
+  return sanitized;
+}
+
+const ZEN_SCHEMA_MAP_KEYS = new Set(["properties", "$defs", "definitions"]);
+const ZEN_DROPPED_SCHEMA_KEYS = new Set(["encrypted"]);
+
+function sanitizeZenSchemaMap(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return sanitizeZenToolParameters(value);
+  const out: Record<string, unknown> = {};
+  for (const [name, child] of Object.entries(value as Record<string, unknown>)) {
+    out[name] = sanitizeZenToolParameters(child);
+  }
+  return out;
+}
+
+function sanitizeZenToolParameters(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sanitizeZenToolParameters);
+  if (!value || typeof value !== "object") return value;
+  const input = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(input)) {
+    if (ZEN_DROPPED_SCHEMA_KEYS.has(key)) continue;
+    if (key === "required" && Array.isArray(child) && child.length === 0) continue;
+    if (key === "type" && Array.isArray(child)) {
+      const nonNull = child.filter(entry => entry !== "null");
+      if (child.includes("null")) out.nullable = true;
+      if (nonNull.length > 0) out.type = nonNull[0];
+      continue;
+    }
+    out[key] = ZEN_SCHEMA_MAP_KEYS.has(key) ? sanitizeZenSchemaMap(child) : sanitizeZenToolParameters(child);
+  }
+  return out;
+}
+
+function ensureZenRootObjectSchema(schema: unknown): Record<string, unknown> {
+  const obj = schema && typeof schema === "object" && !Array.isArray(schema)
+    ? schema as Record<string, unknown>
+    : {};
+  const compositionKeys = ["oneOf", "anyOf", "allOf"] as const;
+  const hasComposition = compositionKeys.some(key => Array.isArray(obj[key]));
+  const rootType = obj.type;
+  const rootObjectType = rootType === "object" || (Array.isArray(rootType) && rootType.includes("object"));
+  if (!hasComposition) {
+    const base = sanitizeZenToolParameters(obj) as Record<string, unknown>;
+    return rootObjectType && base.type === "object" ? base : { ...base, type: "object" };
+  }
+
+  const props: Record<string, unknown> = {};
+  const required = new Set<string>();
+  if (obj.properties && typeof obj.properties === "object") {
+    Object.assign(props, sanitizeZenSchemaMap(obj.properties) as Record<string, unknown>);
+  }
+  if (Array.isArray(obj.required)) {
+    for (const entry of obj.required) if (typeof entry === "string") required.add(entry);
+  }
+  for (const key of compositionKeys) {
+    const variants = obj[key];
+    if (!Array.isArray(variants)) continue;
+    const mergeRequired = key === "allOf";
+    for (const variant of variants) {
+      if (!variant || typeof variant !== "object" || Array.isArray(variant)) continue;
+      const rec = variant as Record<string, unknown>;
+      if (rec.properties && typeof rec.properties === "object") {
+        Object.assign(props, sanitizeZenSchemaMap(rec.properties) as Record<string, unknown>);
+      }
+      if (mergeRequired && Array.isArray(rec.required)) {
+        for (const entry of rec.required) if (typeof entry === "string") required.add(entry);
+      }
+    }
+  }
+
+  const merged = sanitizeZenToolParameters(obj) as Record<string, unknown>;
+  delete merged.oneOf;
+  delete merged.anyOf;
+  delete merged.allOf;
+  merged.type = "object";
+  if (Object.keys(props).length > 0) merged.properties = props;
+  if (required.size > 0) merged.required = [...required];
+  return merged;
+}
+
+function shouldSanitizeZenToolParameters(provider: OcxProviderConfig): boolean {
+  const baseUrl = provider.baseUrl.replace(/\/+$/, "");
+  return baseUrl === "https://opencode.ai/zen/v1"
+    || baseUrl === "https://opencode.ai/zen/go/v1";
+}
+
+const XAI_SCHEMA_BASE_URLS = new Set(["api.x.ai", "cli-chat-proxy.grok.com"]);
+
+function isXaiSchemaTarget(provider: OcxProviderConfig): boolean {
+  try {
+    return XAI_SCHEMA_BASE_URLS.has(new URL(provider.baseUrl).hostname);
+  } catch {
+    return false;
+  }
+}
+
+// Volcengine Ark regional endpoints. Ark validates an assistant message's text field as a
+// REQUIRED parameter and treats "" as absent, so a tool-call-only assistant in history 400s with
+// `MissingParameter: input.content.text` (#796). Every other OpenAI-compatible provider accepts
+// "", and xAI actively requires it ("Each message must have at least one content element"), so
+// the two contracts are in direct conflict and this cannot be a global change.
+const VOLCENGINE_ARK_HOSTNAMES = new Set([
+  "ark.cn-beijing.volces.com",
+  "ark.ap-southeast.volces.com",
+]);
+
+function isVolcengineArkTarget(provider: OcxProviderConfig): boolean {
+  try {
+    return VOLCENGINE_ARK_HOSTNAMES.has(new URL(provider.baseUrl).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Placeholder content for an assistant history entry carrying only tool calls or reasoning.
+ *
+ * UNVERIFIED HYPOTHESIS for Ark. The reported error names `input.content.text`, a nested path,
+ * which suggests Ark wants the structured content form `[{type:"text",text:""}]` rather than a
+ * bare string — no string value, `""` or `" "`, exposes a `content.text` path at all. But Ark's
+ * published examples only show array content for MULTIMODAL USER input, never for an assistant
+ * history entry, so this shape is inferred from the error message and not confirmed by the docs
+ * or by a live request. The empty inner text at least adds no tokens either way.
+ *
+ * Confirm against a real Ark endpoint before relying on this; #796 records what is still missing.
+ *
+ * Every other provider keeps the bare `""`, which xAI's validator specifically requires ("Each
+ * message must have at least one content element"), so this cannot be applied globally.
+ */
+function emptyAssistantContent(provider: OcxProviderConfig): string | { type: "text"; text: string }[] {
+  return isVolcengineArkTarget(provider) ? [{ type: "text", text: "" }] : "";
+}
+
+/**
+ * Providers like Kimi and DeepSeek reject function parameter schemas whose root
+ * `type` is missing or `null` — JSON Schema requires `"object"` at the root of
+ * function parameters. Add `type: "object"` at the root while preserving
+ * `oneOf`, `$defs`, and every other schema key.
+ *
+ * This mirrors `normalizeFunctionToolSchema` in openai-responses.ts, which
+ * applies the same root-only normalization unconditionally on the responses
+ * path. Nested schema content is intentionally left untouched.
+ */
+function ensureRootObjectType(parameters: unknown): Record<string, unknown> {
+  if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
+    return { type: "object", properties: {} };
+  }
+  const obj = parameters as Record<string, unknown>;
+  if (obj.type === "object") return obj;
+  return { ...obj, type: "object" };
+}
+
+function expandXaiRootObjectSchemas(schema: unknown): Record<string, unknown>[] | undefined {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return undefined;
+  const obj = schema as Record<string, unknown>;
+  const compositionKey = ["oneOf", "anyOf"].find(key => Array.isArray(obj[key]));
+  if (!compositionKey) {
+    if (obj.type !== undefined && obj.type !== "object") return undefined;
+    return [{ ...obj, type: "object" }];
+  }
+
+  const siblings = Object.fromEntries(Object.entries(obj).filter(([key]) => key !== compositionKey));
+  const branches = obj[compositionKey];
+  if (!Array.isArray(branches)) return undefined;
+  const expanded: Record<string, unknown>[] = [];
+  for (const branch of branches) {
+    const variants = expandXaiRootObjectSchemas(branch);
+    if (!variants) return undefined;
+    for (const variant of variants) expanded.push({ ...siblings, ...variant });
+  }
+  return expanded.length > 0 ? expanded : undefined;
+}
+
+function normalizeXaiToolParameters(parameters: unknown): Record<string, unknown> | undefined {
+  const variants = expandXaiRootObjectSchemas(parameters);
+  if (!variants) return undefined;
+  if (variants.length === 1) return variants[0];
+  const root = parameters && typeof parameters === "object" && !Array.isArray(parameters)
+    ? parameters as Record<string, unknown>
+    : {};
+  const metadata = Object.fromEntries(Object.entries(root).filter(([key]) => key !== "oneOf" && key !== "anyOf" && key !== "type"));
+  return { ...metadata, oneOf: variants };
+}
+
+function toolsToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] | undefined {
+  if (!parsed.context.tools || parsed.context.tools.length === 0) return undefined;
+  const allowed = isAllowedToolChoice(parsed.options.toolChoice)
+    ? new Set(parsed.options.toolChoice.allowedTools)
+    : undefined;
+  const tools = allowed
+    ? parsed.context.tools.filter(t => toolAllowedByChoice(t, allowed))
+    : parsed.context.tools;
+  if (tools.length === 0) return undefined;
+  const xaiTarget = isXaiSchemaTarget(provider);
+  const formatted = tools.flatMap(t => {
+    const parameters = xaiTarget
+      ? normalizeXaiToolParameters(t.parameters)
+      : ensureRootObjectType(t.parameters);
+
+    if (parameters === undefined) return [];
+    return [{
+    type: "function",
+    function: {
+      name: namespacedToolName(t.namespace, t.name),
+      description: t.description,
+      parameters,
+      ...(t.strict !== undefined ? { strict: t.strict } : {}),
+    },
+    }];
+  });
+  return formatted.length > 0 ? formatted : undefined;
+}
+
+function toolsToChatFormatForProvider(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] | undefined {
+  const base = toolsToChatFormat(parsed, provider);
+  if (!base || !shouldSanitizeZenToolParameters(provider)) return base;
+  return base.map(tool => {
+    if (!tool || typeof tool !== "object") return tool;
+    const functionDef = (tool as { function?: Record<string, unknown> }).function;
+    if (!functionDef || typeof functionDef !== "object") return tool;
+    return {
+      ...tool,
+      function: {
+        ...functionDef,
+        parameters: ensureZenRootObjectSchema(functionDef.parameters ?? {}),
+      },
+    };
+  });
+}
+
+function toolChoiceToChatFormat(tc: OcxParsedRequest["options"]["toolChoice"], tools: OcxParsedRequest["context"]["tools"]): unknown {
+  if (!tc) return undefined;
+  if (isAllowedToolChoice(tc)) return tc.mode === "required" ? "required" : "auto";
+  if (tc === "auto" || tc === "none" || tc === "required") return tc;
+  if ("name" in tc) return { type: "function", function: { name: resolveToolChoiceWireName(tools, tc.name) } };
+  return undefined;
+}
+
+function usageFromOpenAIChat(usage: Record<string, unknown> | undefined): OcxUsage | undefined {
+  if (!usage) return undefined;
+  const promptDetails = usage.prompt_tokens_details as Record<string, number> | undefined;
+  const completionDetails = usage.completion_tokens_details as Record<string, number> | undefined;
+  return {
+    inputTokens: typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : 0,
+    outputTokens: typeof usage.completion_tokens === "number" ? usage.completion_tokens : 0,
+    ...(promptDetails?.cached_tokens !== undefined ? { cachedInputTokens: promptDetails.cached_tokens } : {}),
+    ...(completionDetails?.reasoning_tokens !== undefined ? { reasoningOutputTokens: completionDetails.reasoning_tokens } : {}),
+  };
+}
+
+function resolveMaxTokens(provider: OcxProviderConfig, parsed: OcxParsedRequest): number | undefined {
+  return parsed.options.maxOutputTokens
+    ?? modelRecordValue(provider.modelMaxOutputTokens, parsed.modelId)
+    ?? provider.defaultMaxOutputTokens;
+}
+
+function thinkingBudgetForEffort(parsed: OcxParsedRequest, reasoningEffort: string, maxOutputTokens?: number): number | undefined {
+  if (parsed.options.reasoning === "minimal") return 0;
+  const maxBudget = maxOutputTokens ?? 32768;
+  const fractions: Record<string, number> = {
+    low: 0.20,
+    medium: 0.50,
+    high: 0.75,
+    xhigh: 0.90,
+    max: 1.0,
+  };
+  const fraction = fractions[reasoningEffort];
+  return fraction === undefined ? undefined : Math.max(1, Math.floor(maxBudget * fraction));
+}
+
+export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAdapter {
+  return {
+    name: "openai-chat",
+
+    formatErrorBody: formatOpenAIChatErrorBody,
+
+    buildRequest(parsed: OcxParsedRequest) {
+      const hasCredential = typeof provider.apiKey === "string" && provider.apiKey.trim().length > 0;
+      if ((provider.authMode === "key" || provider.authMode === "oauth") && !provider.keyOptional && !hasCredential) {
+        throw new Error(`${provider.adapter} requires a non-empty credential (authMode: ${provider.authMode})`);
+      }
+
+      const messages = messagesToChatFormat(parsed, provider);
+      const tools = toolsToChatFormatForProvider(parsed, provider);
+      const toolChoice = toolChoiceToChatFormat(parsed.options.toolChoice, parsed.context.tools);
+
+      const body: Record<string, unknown> = {
+        model: provider.modelSuffixBracketStrip ? stripBracketedModelSuffix(parsed.modelId) : parsed.modelId,
+        messages,
+        stream: parsed.stream,
+      };
+      if (modelInList(provider.reasoningSplitModels, parsed.modelId)) body.reasoning_split = true;
+      const maxTokens = resolveMaxTokens(provider, parsed);
+      const openRouterRouting = resolveOpenRouterRouting(provider, parsed.modelId);
+      if (openRouterRouting) body.provider = openRouterProviderPayload(openRouterRouting);
+      if (tools) body.tools = tools;
+      if (tools && toolChoice !== undefined) {
+        body.tool_choice = modelInList(provider.autoToolChoiceOnlyModels, parsed.modelId)
+          ? (toolChoice === "none" ? "none" : "auto")
+          : toolChoice;
+      }
+      if (maxTokens !== undefined) body.max_tokens = maxTokens;
+      if (parsed.options.temperature !== undefined && !modelInList(provider.noTemperatureModels, parsed.modelId)) {
+        body.temperature = parsed.options.temperature;
+      }
+      if (parsed.options.topP !== undefined && !modelInList(provider.noTopPModels, parsed.modelId)) {
+        body.top_p = parsed.options.topP;
+      }
+      if (parsed.options.stopSequences !== undefined) body.stop = parsed.options.stopSequences;
+      const reasoningDisabled = modelInList(provider.noReasoningModels, parsed.modelId);
+      const reasoningRequired = isReasoningEffortRequired(provider, parsed.modelId);
+      const reasoningControl = reasoningControlKindFor(provider, parsed.modelId);
+      const reasoningEffort = mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning);
+      let reasoningLog: AdapterRequest["reasoningLog"];
+      // ClinePass live requests observed 2026-08-02 require this gateway-specific object; the
+      // public API docs do not currently specify its request shape.
+      if (
+        !reasoningDisabled
+        && provider.reasoningWireFormat === "gateway-object"
+        && reasoningControl === "toggle"
+        && typeof parsed.options.reasoning === "string"
+      ) {
+        const enabled = parsed.options.reasoning !== "none";
+        body.reasoning = { enabled };
+        reasoningLog = {
+          effectiveEffort: enabled ? "on" : "none",
+          wireField: "reasoning.enabled",
+          wireValue: enabled,
+        };
+      } else if (
+        !reasoningDisabled
+        && !reasoningRequired
+        && provider.reasoningWireFormat === "gateway-object"
+        && parsed.options.reasoning === "none"
+      ) {
+        body.reasoning = { enabled: false };
+        reasoningLog = {
+          effectiveEffort: "none",
+          wireField: "reasoning.enabled",
+          wireValue: false,
+        };
+      } else if (reasoningEffort !== undefined) {
+        if (provider.reasoningWireFormat === "gateway-object") {
+          body.reasoning = { enabled: true, effort: reasoningEffort };
+          reasoningLog = {
+            effectiveEffort: reasoningEffort,
+            wireField: "reasoning.effort",
+            wireValue: reasoningEffort,
+          };
+        } else if (modelInList(provider.thinkingBudgetModels, parsed.modelId)) {
+          const budget = thinkingBudgetForEffort(parsed, reasoningEffort, maxTokens);
+          if (budget !== undefined) {
+            body.thinking_budget = budget;
+            reasoningLog = {
+              effectiveEffort: parsed.options.reasoning === "minimal" ? "minimal" : reasoningEffort,
+              wireField: "thinking_budget",
+              wireValue: budget,
+            };
+          }
+        } else if (modelInList(provider.thinkingToggleModels, parsed.modelId)) {
+          // Vendor thinking-toggle wire: the mapped value is sent as `thinking: {type}` because
+          // these models ignore/reject reasoning_effort. Most use enabled/disabled; MiniMax-M3
+          // uses adaptive/disabled.
+          if (reasoningEffort === "enabled" || reasoningEffort === "disabled" || reasoningEffort === "adaptive") {
+            body.thinking = { type: reasoningEffort };
+            reasoningLog = {
+              effectiveEffort: reasoningEffort,
+              wireField: "thinking.type",
+              wireValue: reasoningEffort,
+            };
+          }
+        } else {
+          body.reasoning_effort = reasoningEffort;
+          reasoningLog = {
+            effectiveEffort: reasoningEffort,
+            wireField: "reasoning_effort",
+            wireValue: reasoningEffort,
+          };
+        }
+      }
+      if (parsed.options.presencePenalty !== undefined && !modelInList(provider.noPenaltyModels, parsed.modelId)) {
+        body.presence_penalty = parsed.options.presencePenalty;
+      }
+      if (parsed.options.frequencyPenalty !== undefined && !modelInList(provider.noPenaltyModels, parsed.modelId)) {
+        body.frequency_penalty = parsed.options.frequencyPenalty;
+      }
+      // prompt_cache_key is an OpenAI-specific chat extension; strict backends (Groq,
+      // Cerebras, etc.) reject unknown fields. Only forward when the provider opts in.
+      if (provider.promptCacheKey && parsed.options.promptCacheKey !== undefined) {
+        body.prompt_cache_key = parsed.options.promptCacheKey;
+      }
+      // Responses `text.format` -> chat `response_format`. json_object maps 1:1; json_schema
+      // re-nests the flattened Responses fields under `json_schema` — the exact inverse of
+      // responseFormatToText in src/chat/inbound.ts. Forwarded unconditionally (like `stop`):
+      // response_format is a first-class Chat Completions field, it is only present when the
+      // caller explicitly asked for structured output, and a backend that rejects it should
+      // fail loud rather than silently return prose the caller will try to JSON.parse.
+      const textFormat = parsed.options.textFormat;
+      if (textFormat?.type === "json_object") {
+        body.response_format = { type: "json_object" };
+      } else if (textFormat?.type === "json_schema") {
+        body.response_format = {
+          type: "json_schema",
+          json_schema: {
+            name: textFormat.name ?? "response",
+            ...(textFormat.description !== undefined ? { description: textFormat.description } : {}),
+            ...(textFormat.schema !== undefined ? { schema: textFormat.schema } : {}),
+            ...(textFormat.strict !== undefined ? { strict: textFormat.strict } : {}),
+          },
+        };
+      }
+
+      if (tools) {
+        // Default-ON for chat-completions providers (user decision 260709): the buffered
+        // parser assembles multi-call streams safely, so `parallelToolCalls: false` is the
+        // only per-provider opt-out; Codex's request bit can still force false per request.
+        // Rationale + provider evidence: devlog/_plan/260709_parallel_tool_calls.
+        body.parallel_tool_calls = provider.parallelToolCalls === false
+          ? false
+          : parsed.options.parallelToolCalls !== false;
+      }
+      if (parsed.stream) {
+        body.stream_options = { include_usage: true };
+      }
+
+      const url = `${provider.baseUrl}/chat/completions`;
+      const headers: Record<string, string> = { "Content-Type": "application/json" };
+      // Precedence preserved from pre-#128 behavior: apiKey Authorization first, then
+      // provider.headers may override (user/registry-configured headers win). Registry
+      // staticHeaders (e.g. opencode-free x-opencode-client) flow in via derive.ts and
+      // never carry Authorization, so keyless providers are unaffected.
+      if (hasCredential) headers["Authorization"] = `Bearer ${provider.apiKey}`;
+      if (provider.headers) Object.assign(headers, provider.headers);
+
+      const bodyJson = JSON.stringify(body);
+      // Never log pathname/query — tenant-scoped hosts (e.g. Cloudflare
+      // /accounts/<account_id>/ai/v1) would otherwise leak account identifiers (#452).
+      if (isDebugEnabled()) {
+        let host = "upstream";
+        try { host = new URL(url).host; } catch { /* keep fallback */ }
+        debugProviderDiagnostic("openai-chat", "request", {
+          host,
+          model: body.model,
+          stream: parsed.stream,
+          messageCount: Array.isArray(messages) ? messages.length : 0,
+          toolCount: Array.isArray(tools) ? tools.length : 0,
+          hasCredential,
+          bodyBytes: new TextEncoder().encode(bodyJson).length,
+        });
+      }
+
+      return {
+        url,
+        method: "POST",
+        headers,
+        body: bodyJson,
+        ...(reasoningLog ? { reasoningLog } : {}),
+      };
+    },
+
+    async *parseStream(response: Response, budget: TranslatorBudget): AsyncGenerator<AdapterEvent> {
+      if (!response.body) {
+        yield { type: "error", message: "No response body" };
+        return;
+      }
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      const budgetEncoder = new TextEncoder();
+      let buffer = "";
+      let bufferBytes = 0;
+      // Streamed tool calls are BUFFERED until a terminal signal, then flushed as atomic
+      // start/delta/end sequences. The bridge treats text/reasoning deltas as barriers that
+      // close an open tool-call item (bridge.ts closeCurrentToolCall on text_delta), so
+      // emitting calls incrementally would orphan later argument deltas whenever a provider
+      // interleaves content — and parallel tool calls (multiple ids, index-keyed continuation
+      // chunks, whole-chunk calls) cannot be represented live without overlapping sequences.
+      // Keyed by `index` (OpenAI wire standard), falling back to `id`, falling back to the
+      // last-seen call for providers that omit both on continuation chunks.
+      interface PendingToolCall { key: string; id: string; name: string; args: string; argsBytes: number }
+      const pendingToolCalls: PendingToolCall[] = [];
+      let toolCallSeq = 0;
+      const closeToolCalls = (): PendingToolCall[] => {
+        const calls = [...pendingToolCalls];
+        for (const call of calls) budget.closeCall(call.key);
+        pendingToolCalls.length = 0;
+        return calls;
+      };
+      const flushToolCalls = function* (): Generator<AdapterEvent> {
+        // Do not treat flushed tool calls as user-facing output for the finish-less EOF
+        // fallback — incomplete tool args must stay on the truncation path.
+        for (const call of closeToolCalls()) {
+          if (!call.id) call.id = `call_${++toolCallSeq}`;
+          yield { type: "tool_call_start", id: call.id, name: call.name };
+          if (call.args.length > 0) yield { type: "tool_call_delta", arguments: call.args };
+          yield { type: "tool_call_end" };
+        }
+      };
+      const terminateWithError = function* (
+        event: Extract<AdapterEvent, { type: "error" }>,
+      ): Generator<AdapterEvent, "terminate"> {
+        closeToolCalls();
+        yield event;
+        return "terminate";
+      };
+      let pendingUsage: OcxUsage | undefined;
+      // Track terminal signals so a socket EOF without any terminator can fail closed instead of
+      // being reported as a clean completion (silent truncation). A graceful close is either an
+      // explicit `[DONE]` sentinel OR a chunk carrying a non-null `finish_reason` (some
+      // OpenAI-compatible providers omit `[DONE]` but do send finish_reason).
+      let finishReason: string | undefined;
+      // Only answer text enables the finish-less EOF fallback. Reasoning-only streams can be
+      // suppressed by hideThinkingSummary and must not complete as empty successful turns.
+      let sawUserFacingOutput = false;
+
+      // Single per-line handler shared by the streaming loop and the EOF residual-frame flush, so
+      // a final frame is parsed identically wherever it lands (no duplicated, drift-prone parsing).
+      // Yields adapter events and returns "terminate" for a terminal frame ([DONE] / error) that
+      // must end the stream, or "continue" otherwise. Mutates the closure's terminal-signal state.
+      const handleDataLine = function* (line: string): Generator<AdapterEvent, "continue" | "terminate"> {
+        const rawPayload = sseFieldValue(line, "data");
+        if (rawPayload === null) return "continue";
+        const payload = rawPayload.trim();
+        // A bare `data:` line carries nothing (heartbeat-style keep-alive on some gateways);
+        // it is not a malformed frame, just nothing to parse.
+        if (payload.length === 0) return "continue";
+        if (payload === "[DONE]") {
+          yield* flushToolCalls();
+          const stopReason = stopReasonFor(finishReason);
+          yield { type: "done", usage: pendingUsage, ...(stopReason ? { stopReason } : {}) };
+          return "terminate";
+        }
+
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(payload);
+        } catch {
+          yield { type: "error", message: "malformed upstream SSE data frame" };
+          return "terminate";
+        }
+        // Validate the shape instead of asserting it. `JSON.parse` yields a value, not necessarily
+        // an object — `JSON.parse("null")` returns null without throwing, so the catch above never
+        // sees it and the `chunk.error` read below crashed the stream mid-flight.
+        //
+        // Skip rather than terminate: `data: null` is emitted as a benign padding frame BETWEEN
+        // content deltas by real OpenAI-compatible routes (issue #1219), so failing here would
+        // discard the finish_reason chunk and [DONE] still in flight and turn a healthy response
+        // into a failed turn. Skipping cannot mask a genuinely broken stream — a stream carrying
+        // only such frames still sets neither finishReason nor sawUserFacingOutput and so trips
+        // the EOF truncation guard below. An unparseable frame stays terminal.
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+          return "continue";
+        }
+        const chunk = parsed as Record<string, unknown>;
+
+        // A 200/OK chat-completions stream may carry an inline provider error envelope
+        // instead of a clean [DONE]. Surface it as a terminal error so the bridge emits a
+        // classified response.failed (bridge case "error") — never a truncated completion.
+        if (chunk.error !== undefined && chunk.error !== null) {
+          const event = upstreamErrorEvent(chunk.error, pendingUsage);
+          debugProviderDiagnostic("openai-chat", "stream-error", { message: event.message });
+          return yield* terminateWithError(event);
+        }
+
+        if (chunk.usage) {
+          // Record usage but keep parsing: some providers send usage and the final content
+          // delta in the SAME chunk; a bail here would drop that content. The choices
+          // guard below no-ops a usage-only chunk.
+          pendingUsage = usageFromOpenAIChat(chunk.usage as Record<string, unknown>);
+        }
+
+        const choices = chunk.choices;
+        if (choices === undefined) return "continue";
+        if (!Array.isArray(choices)) {
+          return yield* terminateWithError(invalidChoicesEvent(pendingUsage));
+        }
+        if (choices.length === 0) return "continue";
+        const rawChoice = choices[0];
+        if (rawChoice === null || typeof rawChoice !== "object" || Array.isArray(rawChoice)) {
+          return yield* terminateWithError(invalidChoicesEvent(pendingUsage));
+        }
+        const choice = rawChoice as {
+          delta?: Record<string, unknown>;
+          finish_reason?: string;
+          error?: unknown;
+        };
+        if (choice.finish_reason === "error") {
+          const event = upstreamErrorEvent(choice.error, pendingUsage);
+          debugProviderDiagnostic("openai-chat", "stream-error", { message: event.message });
+          return yield* terminateWithError(event);
+        }
+        // Observe the terminator BEFORE the delta guard: a finish-only chunk (finish_reason set,
+        // no delta) is a graceful close and must record finishReason even though we skip it below.
+        if (typeof choice.finish_reason === "string" && choice.finish_reason) {
+          finishReason = choice.finish_reason;
+        }
+        const delta = choice.delta;
+        if (delta) {
+          const reasoningText = reasoningTextFrom(delta);
+          if (reasoningText !== undefined) {
+            yield { type: "reasoning_raw_delta", text: reasoningText };
+          }
+          if (typeof delta.content === "string" && delta.content.length > 0) {
+            sawUserFacingOutput = true;
+            yield { type: "text_delta", text: delta.content };
+          }
+
+          const toolCalls = delta.tool_calls as { index?: number; id?: string; function?: { name?: string; arguments?: string } }[] | undefined;
+          if (toolCalls) {
+            for (const tc of toolCalls) {
+              const key = typeof tc.index === "number"
+                ? `i:${tc.index}`
+                : tc.id
+                ? `id:${tc.id}`
+                : pendingToolCalls[pendingToolCalls.length - 1]?.key;
+              let call = key !== undefined ? pendingToolCalls.find(c => c.key === key) : undefined;
+              // Mixed keying rescue: a call opened under an index key must still absorb an
+              // id-only continuation for the same provider id (and vice versa) instead of
+              // splitting into two calls that share one call_id downstream.
+              if (!call && tc.id) call = pendingToolCalls.find(c => c.id === tc.id);
+              if (!call) {
+                call = { key: key ?? `seq:${pendingToolCalls.length}`, id: "", name: "", args: "", argsBytes: 0 };
+                pendingToolCalls.push(call);
+                budget.openCall(call.key);
+              }
+              if (tc.id && !call.id) call.id = tc.id;
+              if (tc.function?.name && !call.name) call.name = tc.function.name;
+              if (tc.function?.arguments) {
+                const previousBytes = call.argsBytes;
+                const nextBytes = previousBytes + budgetEncoder.encode(tc.function.arguments).byteLength;
+                const scope = { kind: "tool_args" as const, callId: call.key };
+                const reservation = budget.reserveTransient(nextBytes, scope);
+                try {
+                  call.args += tc.function.arguments;
+                  reservation.commitRetained();
+                  budget.releaseRetained(previousBytes, scope);
+                  call.argsBytes = nextBytes;
+                } catch (error) {
+                  reservation.release();
+                  throw error;
+                }
+              }
+            }
+          }
+        }
+
+        // Any non-empty finish_reason ends the generation: flush assembled tool calls as
+        // atomic sequences (covers "tool_calls" AND providers that close tool turns with "stop").
+        if (typeof choice.finish_reason === "string" && choice.finish_reason) {
+          yield* flushToolCalls();
+        }
+        return "continue";
+      };
+
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          const decoded = decoder.decode(value, { stream: true });
+          const nextBufferBytes = bufferBytes + budgetEncoder.encode(decoded).byteLength;
+          if (nextBufferBytes > TRANSLATOR_MAX_SSE_EVENT_BYTES) {
+            throw new Error(`translation SSE event exceeded ${TRANSLATOR_MAX_SSE_EVENT_BYTES} bytes`, {
+              cause: { code: "translation_buffer_limit" },
+            });
+          }
+          const appendReservation = budget.reserveTransient(nextBufferBytes, { kind: "live_transient" });
+          try {
+            buffer += decoded;
+            appendReservation.commitRetained();
+            budget.releaseRetained(bufferBytes, { kind: "live_transient" });
+          } catch (error) {
+            appendReservation.release();
+            throw error;
+          }
+          bufferBytes = nextBufferBytes;
+
+          const lines = buffer.split("\n");
+          buffer = lines.pop() ?? "";
+          const residualBytes = budgetEncoder.encode(buffer).byteLength;
+          const residualReservation = budget.reserveTransient(residualBytes, { kind: "live_transient" });
+          residualReservation.commitRetained();
+          budget.releaseRetained(bufferBytes, { kind: "live_transient" });
+          bufferBytes = residualBytes;
+
+          for (const line of lines) {
+            if ((yield* handleDataLine(line)) === "terminate") return;
+          }
+        }
+
+        // Some providers send the terminal `data:` frame (carrying the final delta, finish_reason,
+        // and/or usage) WITHOUT a trailing newline before closing the socket, so it never crosses
+        // the split("\n") boundary and stays in `buffer`. Run it through the SAME handler so its
+        // content/tool-calls are emitted and its terminal signal observed — otherwise a genuinely
+        // complete stream loses its last frame and may be falsely failed below.
+        if (buffer.length > 0) {
+          if ((yield* handleDataLine(buffer)) === "terminate") return;
+        }
+        // Reader EOF. Prefer failing closed before flushing pending tool calls so the bridge
+        // never sees a fabricated tool_call_end on a truncated mid-assembly stream.
+        //
+        // Checked BEFORE flushToolCalls(), because that helper emits tool_call_end and there is no
+        // taking it back: a half-assembled argument string would reach the client as a completed
+        // call. Tool calls are buffered here (unlike the Anthropic adapter, which forwards
+        // fragments live), so this adapter can still decide.
+        const sawFinish = finishReason !== undefined;
+        if (!sawFinish && pendingToolCalls.length > 0) {
+          debugProviderDiagnostic("openai-chat", "stream-truncated", {
+            finishReason: null,
+            hadUsage: pendingUsage !== undefined,
+            pendingToolCalls: pendingToolCalls.length,
+          });
+          yield { type: "error", message: "upstream stream ended mid tool call without a terminal signal — possible truncation" };
+          return;
+        }
+        // Finish-less EOF is only safe when answer text was emitted. Reasoning-only / usage-only
+        // truncations must stay on the error path (hideThinkingSummary can suppress reasoning).
+        // Trailing usage alone is not a terminal signal for this adapter (#735 / restore #773).
+        if (!sawFinish && !sawUserFacingOutput) {
+          debugProviderDiagnostic("openai-chat", "stream-truncated", {
+            finishReason: finishReason ?? null,
+            hadUsage: pendingUsage !== undefined,
+          });
+          yield { type: "error", message: "upstream stream ended without a terminal signal ([DONE] or finish_reason) — possible truncation" };
+          return;
+        }
+        yield* flushToolCalls();
+        // Graceful close that omitted [DONE] but delivered finish_reason and/or answer text.
+        const stopReason = stopReasonFor(finishReason);
+        yield { type: "done", usage: pendingUsage, ...(stopReason ? { stopReason } : {}) };
+      } catch (error) {
+        if (isTranslatorBudgetExceededError(error)
+          || (error instanceof Error && (error.cause as { code?: unknown } | undefined)?.code === "translation_buffer_limit")) {
+          yield {
+            type: "error",
+            status: 502,
+            errorType: "upstream_error",
+            code: "translation_buffer_limit",
+            message: "upstream translation buffer exceeded the safe limit",
+          };
+          try { await reader.cancel(error); } catch { /* already closed */ }
+          return;
+        }
+        throw error;
+      } finally {
+        budget.releaseRetained(bufferBytes, { kind: "live_transient" });
+        closeToolCalls();
+        reader.releaseLock();
+      }
+    },
+
+    async parseResponse(response: Response, budget: TranslatorBudget): Promise<AdapterEvent[]> {
+      const json = await response.json() as Record<string, unknown>;
+      const responseBytes = new TextEncoder().encode(JSON.stringify(json)).byteLength;
+      budget.chargeRetained(responseBytes, { kind: "retained_collectors" });
+      try {
+      const payload = unwrapChatCompletionPayload(json);
+      const usage = usageFromOpenAIChat(payload.usage as Record<string, unknown> | undefined);
+      if (json.success === false && payload.error === undefined) {
+        return [{
+          type: "error",
+          message: "upstream reported failure without an error payload",
+          ...(usage ? { usage } : {}),
+        }];
+      }
+      if (payload.error !== undefined && payload.error !== null) {
+        return [upstreamErrorEvent(payload.error, usage)];
+      }
+
+      const events: AdapterEvent[] = [];
+      const choices = payload.choices as {
+        message?: Record<string, unknown>;
+        finish_reason?: unknown;
+        error?: OpenAIChatError;
+      }[] | undefined;
+      if (!Array.isArray(choices) || choices.length === 0) {
+        return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
+      }
+      const rawChoice = choices[0];
+      if (rawChoice === null || typeof rawChoice !== "object" || Array.isArray(rawChoice)) {
+        return [invalidChoicesEvent(usage)];
+      }
+      const choice = rawChoice;
+      if (choice.finish_reason === "error") return [upstreamErrorEvent(choice.error, usage)];
+      if (!choice.message) return [{ type: "error", message: "upstream response contained no choices", ...(usage ? { usage } : {}) }];
+
+      const msg = choice.message;
+      const reasoningText = reasoningTextFrom(msg);
+      if (reasoningText !== undefined) {
+        events.push({ type: "reasoning_raw_delta", text: reasoningText });
+      }
+      if (typeof msg.content === "string") {
+        events.push({ type: "text_delta", text: msg.content });
+      }
+      const toolCalls = msg.tool_calls as { id: string; function: { name: string; arguments: string } }[] | undefined;
+      if (toolCalls) {
+        for (const tc of toolCalls) {
+          events.push({ type: "tool_call_start", id: tc.id, name: tc.function.name });
+          events.push({ type: "tool_call_delta", arguments: tc.function.arguments });
+          events.push({ type: "tool_call_end" });
+        }
+      }
+      const stopReason = stopReasonFor(choice.finish_reason);
+      events.push({
+        type: "done",
+        usage,
+        ...(stopReason ? { stopReason } : {}),
+      });
+      retainTranslatedEventBatch(events, budget);
+      return events;
+      } finally {
+        budget.releaseRetained(responseBytes, { kind: "retained_collectors" });
+      }
+    },
+  };
+}