@iislee/opencodex 2.11.0 → 2.31.0

package/src/adapters/openai-chat.ts

@@ -1,15 +1,31 @@
 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 { isAllowedToolChoice, modelInList, namespacedToolName, resolveToolChoiceWireName, toolChoiceToolPredicate } from "../types";
 import { mapReasoningEffort, modelRecordValue } 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 { neutralizeIdentity } from "./identity";
+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 {
+  canForwardForeignServiceTierForChatModel,
+  fastPolicyForModel,
+  supportsServiceTierForModel,
+} from "../providers/service-tier";
+import {
+  canonicalFastTierMarker,
+  createAdapterTierMetadata,
+  decideTier,
+  type AdapterTierMetadata,
+  type ResolvedFastPolicy,
+} from "../providers/fastwire";
+import { openaiChatCompletionsUrl } from "./openai-chat-url";
+import { stripResponsesOnlyEncryptedMarker } from "./responses-tool-schema";
 import {
   isTranslatorBudgetExceededError,
   retainTranslatedEventBatch,
@@ -21,7 +37,148 @@ import {
 // 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*$/, "");
+  const suffixEnd = modelId.trimEnd().length;
+  if (suffixEnd === 0 || modelId[suffixEnd - 1] !== "]") return modelId;
+
+  let suffixStart = -1;
+  for (let i = suffixEnd - 2; i >= 0 && modelId[i] !== "]"; i--) {
+    if (modelId[i] === "[") suffixStart = i;
+  }
+  return suffixStart === -1 ? modelId : modelId.slice(0, suffixStart);
+}
+
+const CHAT_PASSTHROUGH_FIELDS = [
+  "audio",
+  "frequency_penalty",
+  "logit_bias",
+  "logprobs",
+  "max_completion_tokens",
+  "max_tokens",
+  "metadata",
+  "modalities",
+  "n",
+  "prediction",
+  "presence_penalty",
+  "reasoning_effort",
+  "response_format",
+  "seed",
+  "stop",
+  "store",
+  "temperature",
+  "tool_choice",
+  "tools",
+  "top_logprobs",
+  "top_p",
+  "user",
+  "web_search_options",
+] as const;
+
+function openAIChatTransport(provider: OcxProviderConfig): {
+  url: string;
+  headers: Record<string, string>;
+  hasCredential: boolean;
+} {
+  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 headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (hasCredential) headers.Authorization = `Bearer ${provider.apiKey}`;
+  if (provider.headers) Object.assign(headers, provider.headers);
+  return { url: openaiChatCompletionsUrl(provider.baseUrl), headers, hasCredential };
+}
+
+/**
+ * Build a provider request from an inbound Chat Completions body without translating it
+ * through the Responses contract. This is deliberately a whitelist: Chat-only caller
+ * fields retain their exact wire representation, while provider capability gates remain
+ * centralized beside the ordinary openai-chat adapter.
+ */
+export function buildOpenAIChatPassthroughRequest(
+  provider: OcxProviderConfig,
+  rawBody: Record<string, unknown>,
+  modelId: string,
+  stream: boolean,
+  fastPolicy: ResolvedFastPolicy = fastPolicyForModel(provider, modelId, undefined, "chat"),
+  fastMode?: boolean,
+): AdapterRequest {
+  const { url, headers, hasCredential } = openAIChatTransport(provider);
+
+  const body: Record<string, unknown> = {
+    model: provider.modelSuffixBracketStrip ? stripBracketedModelSuffix(modelId) : modelId,
+    messages: rawBody.messages,
+    stream,
+  };
+  for (const field of CHAT_PASSTHROUGH_FIELDS) {
+    if (rawBody[field] !== undefined) body[field] = rawBody[field];
+  }
+
+  const openRouterRouting = resolveOpenRouterRouting(provider, modelId);
+  if (openRouterRouting) body.provider = openRouterProviderPayload(openRouterRouting);
+
+  if (modelInList(provider.noTemperatureModels, modelId)) delete body.temperature;
+  if (modelInList(provider.noTopPModels, modelId)) delete body.top_p;
+  if (modelInList(provider.noPenaltyModels, modelId)) {
+    delete body.presence_penalty;
+    delete body.frequency_penalty;
+  }
+  // Exact match, unlike the gates above: `noStructuredOutputModels` is documented as
+  // "only an exact requested-model match omits the field" (#1424), and the Responses
+  // ingress enforces exactly that. A prefix match here would strip response_format from
+  // `<listed>:<tag>` siblings the operator never opted out, silently returning prose.
+  if (provider.noStructuredOutputModels?.includes(modelId)) delete body.response_format;
+
+  // Run the same complete Fast policy as the translated Chat path, including explicit
+  // fastMode and foreign-tier handling. On inherited canonical Fast, the passthrough still
+  // retains the caller's exact spelling; forced Fast uses the policy-owned wire value.
+  const callerTier = typeof rawBody.service_tier === "string" ? rawBody.service_tier : undefined;
+  const tierDecision = decideTier(fastPolicy, fastMode, callerTier);
+  if (tierDecision.kind === "set") {
+    body.service_tier = fastMode === undefined && canonicalFastTierMarker(callerTier) !== undefined
+      ? callerTier
+      : tierDecision.value;
+  } else if (tierDecision.kind === "forward-caller" && rawBody.service_tier !== undefined) {
+    body.service_tier = rawBody.service_tier;
+  }
+  if (provider.promptCacheKey && rawBody.prompt_cache_key !== undefined) {
+    body.prompt_cache_key = rawBody.prompt_cache_key;
+  }
+  if (Array.isArray(rawBody.tools) && rawBody.tools.length > 0) {
+    if (provider.parallelToolCalls === true) {
+      body.parallel_tool_calls = rawBody.parallel_tool_calls !== false;
+    } else if (provider.parallelToolCalls === false
+        && (provider.baseUrl === "https://integrate.api.nvidia.com/v1" || provider.pinParallelToolCallsFalse === true)) {
+      body.parallel_tool_calls = false;
+    }
+  }
+  if (stream) {
+    const callerOptions = rawBody.stream_options !== null
+        && typeof rawBody.stream_options === "object"
+        && !Array.isArray(rawBody.stream_options)
+      ? rawBody.stream_options as Record<string, unknown>
+      : {};
+    body.stream_options = { ...callerOptions, include_usage: true };
+  } else if (rawBody.stream_options !== undefined) {
+    body.stream_options = rawBody.stream_options;
+  }
+
+  const bodyJson = JSON.stringify(body);
+
+  if (isDebugEnabled()) {
+    let host = "upstream";
+    try { host = new URL(url).host; } catch { /* keep fallback */ }
+    debugProviderDiagnostic("openai-chat", "passthrough-request", {
+      host,
+      model: body.model,
+      stream,
+      messageCount: Array.isArray(body.messages) ? body.messages.length : 0,
+      toolCount: Array.isArray(body.tools) ? body.tools.length : 0,
+      hasCredential,
+      bodyBytes: new TextEncoder().encode(bodyJson).length,
+    });
+  }
+
+  return { url, method: "POST", headers, body: bodyJson };
 }
 
 // 260715 (issue #126): surface upstream error detail through the web-search sidecar loop.
@@ -46,14 +203,12 @@ 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)) {
@@ -64,12 +219,349 @@ function extractErrorDetail(parsed: unknown): string | undefined {
       .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;
 }
 
+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 invalidToolCallsEvent(
+  rawToolCalls: unknown,
+  mode: "stream" | "response",
+  usage?: OcxUsage,
+  diagnosticOverride?: InvalidToolCallDiagnostic,
+): Extract<AdapterEvent, { type: "error" }> {
+  // The streamed accumulator knows things a rescan cannot: which field on which pending call
+  // was actually rejected. Without the override, a stream carrying accepted padding on call 0
+  // and a real defect on call 1 blames call 0, because the stateless scan stops at the first
+  // structurally odd value it sees.
+  const diagnostic = diagnosticOverride ?? diagnoseInvalidToolCalls(rawToolCalls, mode);
+  const detail = diagnostic
+    ? ` (${diagnostic.reason}${diagnostic.callIndex !== undefined ? `; callIndex=${diagnostic.callIndex}` : ""}; valueType=${diagnostic.valueType})`
+    : "";
+  return {
+    type: "error",
+    status: 502,
+    errorType: "upstream_error",
+    message: `upstream response contained invalid tool calls${detail}`,
+    ...(usage !== undefined ? { usage } : {}),
+  };
+}
+
+/**
+ * A streamed tool call is only dispatchable once the upstream has named the function.
+ *
+ * The OpenAI streaming convention puts `function.name` in the first chunk for a tool-call
+ * index and leaves later chunks carrying only `arguments` deltas, so a stream that never
+ * sends a name is non-conforming for every provider rather than quirky for one. The
+ * reference implementations accumulate such a call with an empty name and let the caller
+ * fail; we sit at the boundary where it would become a Codex tool-call contract event, so
+ * the equivalent is to refuse to emit it.
+ *
+ * Failing closed rather than dropping is deliberate, and matches #1325: a claimed tool call
+ * that silently disappears can leave the matching result orphaned on the next turn. Naming
+ * it ourselves is worse still — the id is synthesizable because it is an opaque correlation
+ * handle, but a function name is a guess at intent.
+ */
+function unnamedToolCallEvent(usage?: OcxUsage): Extract<AdapterEvent, { type: "error" }> {
+  return {
+    type: "error",
+    message: "upstream streamed a tool call without a function name — cannot dispatch",
+    ...(usage !== undefined ? { usage } : {}),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+type InvalidToolCallReason =
+  | "tool_calls_not_array"
+  | "tool_call_not_object"
+  | "tool_call_id_invalid"
+  | "tool_call_function_not_object"
+  | "tool_call_function_name_invalid"
+  | "tool_call_function_name_blank"
+  | "tool_call_function_arguments_invalid";
+
+type InvalidToolCallDiagnostic = {
+  reason: InvalidToolCallReason;
+  callIndex?: number;
+  valueType: string;
+};
+
+type InvalidFieldShape =
+  | {
+      kind: "object";
+      knownKeys: string[];
+      knownFieldTypes: Record<string, string>;
+      hasUnknownKeys: boolean;
+    }
+  | {
+      kind: "array";
+      length: number;
+    };
+
+const SAFE_TOOL_CALL_SHAPE_KEYS = [
+  "name",
+  "type",
+  "value",
+  "function",
+  "arguments",
+  "id",
+  "index",
+] as const;
+const SAFE_TOOL_CALL_SHAPE_KEY_SET = new Set<string>(SAFE_TOOL_CALL_SHAPE_KEYS);
+
+function structuralValueType(value: unknown): string {
+  return value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+}
+
+function invalidToolCallField(rawToolCalls: unknown, diagnostic: InvalidToolCallDiagnostic): unknown {
+  if (diagnostic.reason === "tool_calls_not_array") return rawToolCalls;
+  if (!Array.isArray(rawToolCalls) || diagnostic.callIndex === undefined) return undefined;
+
+  const rawToolCall = rawToolCalls[diagnostic.callIndex];
+  if (diagnostic.reason === "tool_call_not_object") return rawToolCall;
+  if (!isRecord(rawToolCall)) return undefined;
+  if (diagnostic.reason === "tool_call_function_not_object") return rawToolCall.function;
+
+  const rawFunction = rawToolCall.function;
+  switch (diagnostic.reason) {
+    case "tool_call_id_invalid":
+      return rawToolCall.id;
+    case "tool_call_function_name_invalid":
+      return isRecord(rawFunction) ? rawFunction.name : undefined;
+    case "tool_call_function_arguments_invalid":
+      return isRecord(rawFunction) ? rawFunction.arguments : undefined;
+    default:
+      return undefined;
+  }
+}
+
+function fingerprintInvalidField(value: unknown): InvalidFieldShape | undefined {
+  if (Array.isArray(value)) return { kind: "array", length: value.length };
+  if (!isRecord(value)) return undefined;
+
+  const knownKeys: string[] = [];
+  const knownFieldTypes: Record<string, string> = {};
+  for (const key of SAFE_TOOL_CALL_SHAPE_KEYS) {
+    if (!Object.hasOwn(value, key)) continue;
+    knownKeys.push(key);
+    knownFieldTypes[key] = structuralValueType(value[key]);
+  }
+
+  let hasUnknownKeys = false;
+  for (const key of Object.keys(value)) {
+    if (!SAFE_TOOL_CALL_SHAPE_KEY_SET.has(key)) {
+      hasUnknownKeys = true;
+      break;
+    }
+  }
+  return { kind: "object", knownKeys, knownFieldTypes, hasUnknownKeys };
+}
+
+/**
+ * Streamed string fields are absent when null or undefined (#1731): OpenAI-compatible
+ * streamers repeat already-sent `id`/`name`/`arguments` as null on continuation deltas.
+ * The accumulator and this diagnostic share this predicate so they cannot disagree about
+ * which delta was the invalid one.
+ */
+function isInvalidStreamStringField(value: unknown): boolean {
+  return value != null && typeof value !== "string";
+}
+
+/**
+ * Explain only the rejected wire shape, never its values. This diagnostic exists so provider
+ * compatibility can be tightened from evidence without retaining tool arguments or credentials.
+ */
+function diagnoseInvalidToolCalls(
+  rawToolCalls: unknown,
+  mode: "stream" | "response",
+): InvalidToolCallDiagnostic | undefined {
+  if (!Array.isArray(rawToolCalls)) {
+    return { reason: "tool_calls_not_array", valueType: rawToolCalls === null ? "null" : typeof rawToolCalls };
+  }
+  for (let callIndex = 0; callIndex < rawToolCalls.length; callIndex++) {
+    const rawToolCall = rawToolCalls[callIndex];
+    if (!isRecord(rawToolCall)) {
+      return {
+        reason: "tool_call_not_object",
+        callIndex,
+        valueType: rawToolCall === null ? "null" : Array.isArray(rawToolCall) ? "array" : typeof rawToolCall,
+      };
+    }
+    if (mode === "stream") {
+      // The streamed path validates the pieces it is about to store (#1531): a present
+      // `function` must be a record, and a present `name`/`arguments`/`id` must be a string.
+      // Blank names are caught later at flush, not here, so they are not diagnosed on this
+      // branch. Describe exactly that boundary rather than tightening compatibility in a
+      // diagnostic change.
+      // #1731: "present" means the same thing here as in the accumulator — null and undefined
+      // are both absent, because some OpenAI-compatible streamers repeat already-sent fields
+      // as null on continuation deltas. A separate predicate here would diagnose accepted
+      // padding as the failure and point compatibility work at the wrong delta.
+      const streamFunction = (rawToolCall as { function?: unknown }).function;
+      if (streamFunction !== undefined && streamFunction !== null) {
+        if (!isRecord(streamFunction)) {
+          return {
+            reason: "tool_call_function_not_object",
+            callIndex,
+            valueType: Array.isArray(streamFunction) ? "array" : typeof streamFunction,
+          };
+        }
+        if (isInvalidStreamStringField(streamFunction.name)) {
+          return { reason: "tool_call_function_name_invalid", callIndex, valueType: typeof streamFunction.name };
+        }
+        if (isInvalidStreamStringField(streamFunction.arguments)) {
+          return { reason: "tool_call_function_arguments_invalid", callIndex, valueType: typeof streamFunction.arguments };
+        }
+      }
+      if (isInvalidStreamStringField(rawToolCall.id)) {
+        return { reason: "tool_call_id_invalid", callIndex, valueType: typeof rawToolCall.id };
+      }
+      continue;
+    }
+    // Precedence must mirror the buffered validator below, or a payload with more than one
+    // problem is reported under the wrong reason and sends compatibility work after the wrong
+    // shape. That validator checks the `function` container first (`!isRecord(rawToolCall) ||
+    // !isRecord(rawToolCall.function)`), then id/name/arguments types together, and only then
+    // the blank name.
+    if (!isRecord(rawToolCall.function)) {
+      return {
+        reason: "tool_call_function_not_object",
+        callIndex,
+        valueType: rawToolCall.function === null ? "null" : Array.isArray(rawToolCall.function) ? "array" : typeof rawToolCall.function,
+      };
+    }
+    if (typeof rawToolCall.id !== "string") {
+      return { reason: "tool_call_id_invalid", callIndex, valueType: typeof rawToolCall.id };
+    }
+    if (typeof rawToolCall.function.name !== "string") {
+      return { reason: "tool_call_function_name_invalid", callIndex, valueType: typeof rawToolCall.function.name };
+    }
+    if (typeof rawToolCall.function.arguments !== "string") {
+      return { reason: "tool_call_function_arguments_invalid", callIndex, valueType: typeof rawToolCall.function.arguments };
+    }
+    // Last, matching the validator: #1531 also rejects a blank or whitespace-only name here,
+    // because such a call cannot select a dispatch target. Reporting it as `name_invalid`
+    // would claim a type problem for a correctly-typed value, so it gets its own code.
+    if (rawToolCall.function.name.trim().length === 0) {
+      return { reason: "tool_call_function_name_blank", callIndex, valueType: "string" };
+    }
+  }
+  return undefined;
+}
+
+function logInvalidToolCalls(
+  mode: "stream" | "response",
+  rawToolCalls: unknown,
+  diagnosticOverride?: InvalidToolCallDiagnostic,
+): void {
+  if (!isDebugEnabled()) return;
+  const diagnostic = diagnosticOverride ?? diagnoseInvalidToolCalls(rawToolCalls, mode);
+  if (!diagnostic) return;
+  const fieldShape = fingerprintInvalidField(invalidToolCallField(rawToolCalls, diagnostic));
+  debugProviderDiagnostic("openai-chat", "invalid-tool-calls", {
+    mode,
+    ...diagnostic,
+    ...(fieldShape ? { fieldShape } : {}),
+  });
+}
+
 function developerSystemText(message: OcxMessage): string | undefined {
   if (message.role !== "developer") return undefined;
   if (typeof message.content === "string") return message.content;
@@ -77,20 +569,49 @@ function developerSystemText(message: OcxMessage): string | undefined {
   return message.content.map(part => (part as OcxTextContent).text).join("");
 }
 
+function isNativeOpenAIChatTarget(provider: OcxProviderConfig): boolean {
+  try {
+    return new URL(provider.baseUrl).hostname === "api.openai.com";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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 toolResultTextForWire(content: string | OcxContentPart[]): string {
+  if (typeof content === "string") return content;
+  const text = content.filter((p) => p.type === "text").map((p) => (p as OcxTextContent).text).join("");
+  if (text) {
+    const untransportableImages = content.filter((p) => p.type === "image" && !p.imageUrl).length;
+    return `${text}${"[image]".repeat(untransportableImages)}`;
+  }
+  return contentPartsToText(content);
+}
+
+function toolResultImageChatParts(content: string | OcxContentPart[]): unknown[] {
+  if (typeof content === "string") return [];
+  const parts: unknown[] = [];
+  for (const p of content) {
+    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;
+  const replayCacheScope = parsed._reasoningReplayScope;
 
-  // 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>();
 
@@ -109,9 +630,18 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
     deferredBarrierMessages = [];
   };
 
-  // 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 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 = [];
+  };
+
   const flushPendingToolCalls = (): void => {
     if (pendingToolCalls.length === 0) return;
     for (const call of pendingToolCalls) {
@@ -122,32 +652,29 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
       });
     }
     pendingToolCalls = [];
+    flushToolResultImages();
     releaseDeferredBarriers();
   };
 
+  const nativeOpenAI = isNativeOpenAIChatTarget(provider);
   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 developerSystemParts = nativeOpenAI
+    ? []
+    : 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 sys = neutralizeIdentity(systemParts.join("\n\n"));
+    const wireModelId = provider.modelSuffixBracketStrip
+      ? stripBracketedModelSuffix(parsed.modelId)
+      : parsed.modelId;
+    const sys = identifyRoutedModel(systemParts.join("\n\n"), wireModelId);
     out.push({ role: "system", content: sys });
   }
 
@@ -157,24 +684,23 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
       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") {
+        if (msg.role === "developer" && !hasImages) {
+          if (!nativeOpenAI) break;
+          const text = typeof msg.content === "string"
+            ? msg.content
+            : parts!.map(p => (p as OcxTextContent).text).join("");
+          chatMsg = { role: "developer", content: text };
+        } else 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 {
-          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 };
-          }
+          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;
@@ -185,18 +711,38 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
         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("");
+        if (textParts.length > 0) chatMsg.content = textParts.map(p => p.text).join("");
+        let reasoningContent = thinkingParts.map(p => p.thinking).join("");
+        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");
+          } else if (modelInList(provider.requiresReasoningPlaceholderModels ?? provider.preserveReasoningContentModels, parsed.modelId)) {
+            // Fallback (extends #950, closes #1193): the replay cache is
+            // bounded (64 entries / 256 KiB / 1 h TTL) and always misses on
+            // long sessions, and some tool rounds carry no recorded reasoning
+            // at all. DeepSeek thinking mode rejects ANY tool_call assistant
+            // message missing reasoning_content with HTTP 400, so inject a
+            // minimal placeholder rather than emit a bare continuation the
+            // upstream will reject. Scoped to requiresReasoningPlaceholderModels
+            // (defaulting to the preserve list): preserve-listed providers with
+            // toggleable thinking (MiniMax low effort) opt out with `[]` so
+            // non-thinking histories are never given a fabricated placeholder.
+            reasoningContent = " ";
+          }
         }
-        const reasoningContent = thinkingParts.map(p => p.thinking).join("");
         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;
@@ -210,8 +756,6 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
             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) {
@@ -225,26 +769,44 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
         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),
+            content: toolResultTextForWire(msg.content),
           });
+          pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content));
           pendingToolCalls.splice(matchIdx, 1);
-          if (pendingToolCalls.length === 0) releaseDeferredBarriers();
+          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);
+          const cachedReasoning =
+            toolCallId && modelInList(provider.preserveReasoningContentModels, parsed.modelId)
+              ? peekReasoningForCall(toolCallId, replayCacheScope)
+              : undefined;
+          // Same fallback as the main-assistant path: never emit a bare orphan
+          // tool_call continuation on a thinking-mode provider — inject a
+          // placeholder when the replay cache missed (the bounded cache can
+          // always miss on long sessions), or DeepSeek thinking mode 400s.
+          // Gate on the preserve list too: reasoning_content is only ever
+          // serialized for preserve-listed models, so a requires-only custom
+          // entry must not fabricate it on this path (P2 on #1205).
+          // `||` (not `??`): the cache never stores empty strings, but treat a
+          // falsy hit as a miss so the placeholder still fires.
+          const orphanReasoning =
+            cachedReasoning
+            || (modelInList(provider.preserveReasoningContentModels, parsed.modelId)
+              && modelInList(provider.requiresReasoningPlaceholderModels ?? provider.preserveReasoningContentModels, parsed.modelId)
+              ? " "
+              : undefined);
           out.push({
             role: "assistant",
             content: emptyAssistantContent(provider),
+            ...(orphanReasoning ? { reasoning_content: orphanReasoning } : {}),
             tool_calls: [{
               id: toolCallId,
               type: "function",
@@ -255,16 +817,16 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
           out.push({
             role: "tool",
             tool_call_id: toolCallId,
-            content: contentPartsToText(msg.content),
+            content: toolResultTextForWire(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;
@@ -360,67 +922,36 @@ function shouldSanitizeZenToolParameters(provider: OcxProviderConfig): boolean {
     || 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;
-  }
-}
-
-function isKimiSchemaTarget(provider: OcxProviderConfig): boolean {
-  try {
-    return new URL(provider.baseUrl).hostname === "api.kimi.com";
+    // Public api.x.ai accepts native root object unions. Only the Grok CLI proxy
+    // 400s on a root oneOf/anyOf, so flattening/omitting is scoped to that host.
+    return new URL(provider.baseUrl).hostname === "cli-chat-proxy.grok.com";
   } 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 {
+function isVolcengineArkPaygChatTarget(provider: OcxProviderConfig): boolean {
   try {
-    return VOLCENGINE_ARK_HOSTNAMES.has(new URL(provider.baseUrl).hostname);
+    const url = new URL(provider.baseUrl);
+    const pathname = url.pathname.replace(/\/+$/, "") || "/";
+    return VOLCENGINE_ARK_HOSTNAMES.has(url.hostname) && pathname === "/api/v3";
   } 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: "" }] : "";
+  return isVolcengineArkPaygChatTarget(provider) ? [{ type: "text", text: "" }] : "";
 }
 
-/**
- * Kimi requires function.parameters.type to be exactly "object" at the root.
- * Codex tools with oneOf/anyOf schemas omit the root type, causing 400 errors.
- * Add type: "object" at the root while preserving oneOf, $defs, and other schema keys.
- */
-function ensureKimiRootObjectType(parameters: unknown): Record<string, unknown> {
+function ensureRootObjectType(parameters: unknown): Record<string, unknown> {
   if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
     return { type: "object", properties: {} };
   }
@@ -429,64 +960,288 @@ function ensureKimiRootObjectType(parameters: unknown): Record<string, unknown>
   return { ...obj, type: "object" };
 }
 
+function isXaiObjectSchema(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringRequiredFields(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+/** Variant keys the merger can keep. Anything else is refused, not silently dropped. */
+const XAI_VARIANT_MERGE_KEYS = new Set([
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "description",
+  "title",
+  "$comment",
+  "$defs",
+  "definitions",
+]);
+
+function decodeJsonPointerToken(token: string): string {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function lookupLocalJsonPointer(root: unknown, ref: string): unknown {
+  if (ref === "#" || ref === "#/") return root;
+  if (!ref.startsWith("#/")) return undefined;
+  let current: unknown = root;
+  for (const token of ref.slice(2).split("/").map(decodeJsonPointerToken)) {
+    if (!isXaiObjectSchema(current) || !Object.hasOwn(current, token)) return undefined;
+    current = current[token];
+  }
+  return current;
+}
+
+/** Resolve local `#/` `$ref`s. Unresolvable or cyclic refs return undefined. */
+function resolveXaiSchemaRefs(
+  schema: unknown,
+  root: Record<string, unknown>,
+  stack: Set<string> = new Set(),
+): unknown | undefined {
+  if (!isXaiObjectSchema(schema)) return schema;
+  if (typeof schema.$ref === "string") {
+    const ref = schema.$ref;
+    if (stack.has(ref)) return undefined;
+    const target = lookupLocalJsonPointer(root, ref);
+    if (target === undefined) return undefined;
+    stack.add(ref);
+    const resolvedTarget = resolveXaiSchemaRefs(target, root, stack);
+    stack.delete(ref);
+    if (resolvedTarget === undefined) return undefined;
+    const rest: Record<string, unknown> = { ...schema };
+    delete rest.$ref;
+    if (Object.keys(rest).length === 0) return resolvedTarget;
+    const resolvedRest = resolveXaiSchemaRefs(rest, root, stack);
+    if (resolvedRest === undefined || !isXaiObjectSchema(resolvedTarget) || !isXaiObjectSchema(resolvedRest)) {
+      return undefined;
+    }
+    return composeXaiObjectSchemas(resolvedTarget, resolvedRest);
+  }
+
+  const resolved: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if ((key === "oneOf" || key === "anyOf") && Array.isArray(value)) {
+      const items: unknown[] = [];
+      for (const item of value) {
+        const next = resolveXaiSchemaRefs(item, root, stack);
+        if (next === undefined) return undefined;
+        items.push(next);
+      }
+      resolved[key] = items;
+      continue;
+    }
+    if (key === "properties" && isXaiObjectSchema(value)) {
+      const properties: Record<string, unknown> = {};
+      for (const [name, property] of Object.entries(value)) {
+        const next = resolveXaiSchemaRefs(property, root, stack);
+        if (next === undefined) return undefined;
+        properties[name] = next;
+      }
+      resolved[key] = properties;
+      continue;
+    }
+    resolved[key] = value;
+  }
+  return resolved;
+}
+
+function xaiVariantIsConcreteObject(variant: Record<string, unknown>): boolean {
+  if (variant.type !== undefined && variant.type !== "object") return false;
+  return Object.keys(variant).every(key => XAI_VARIANT_MERGE_KEYS.has(key));
+}
+
+function variantProperties(variant: Record<string, unknown>): Record<string, unknown> {
+  return isXaiObjectSchema(variant.properties) ? variant.properties : {};
+}
+
+/**
+ * Independent per-property anyOf is lossless only when every property name exists
+ * on every variant (absence is meaningful under xAI's default additionalProperties:
+ * false, and promoting a branch-local key also tightens explicit-true variants)
+ * and at most one of those shared properties has a conflicting schema.
+ */
+function xaiPropertyMergeIsLossless(variants: Record<string, unknown>[]): boolean {
+  const names = new Set<string>();
+  const props = variants.map(variant => {
+    const properties = variantProperties(variant);
+    for (const name of Object.keys(properties)) names.add(name);
+    return properties;
+  });
+  let schemaConflicts = 0;
+  for (const name of names) {
+    const values = props.map(property => property[name]);
+    if (values.some(value => value === undefined)) return false;
+    if (values.some(value => JSON.stringify(value) !== JSON.stringify(values[0]))) schemaConflicts += 1;
+  }
+  return schemaConflicts <= 1;
+}
+
+function xaiRequiredSetsMatch(variants: Record<string, unknown>[]): boolean {
+  const serialized = variants.map(variant => [...stringRequiredFields(variant.required)].sort().join("\0"));
+  return serialized.every(value => value === serialized[0]);
+}
+
+function mergeXaiAdditionalProperties(
+  variants: Record<string, unknown>[],
+): { ok: true; value?: unknown } | { ok: false } {
+  const values = variants.map(variant => variant.additionalProperties);
+  const explicit = values.filter(value => value !== undefined);
+  if (explicit.length === 0) return { ok: true };
+  if (explicit.length !== values.length) return { ok: false };
+  const hasFalse = explicit.some(value => value === false);
+  const permissive = explicit.filter(value => value !== false);
+  if (hasFalse && permissive.length > 0) return { ok: false };
+  if (hasFalse) return { ok: true, value: false };
+  const unique: unknown[] = [];
+  const seen = new Set<string>();
+  for (const value of permissive) {
+    const key = JSON.stringify(value);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(value);
+  }
+  if (unique.length !== 1) return { ok: false };
+  return { ok: true, value: unique[0] };
+}
+
+/** Compose root siblings into a branch so properties/required are not overwritten. */
+function composeXaiObjectSchemas(
+  inherited: Record<string, unknown>,
+  branch: Record<string, unknown>,
+): Record<string, unknown> {
+  const composed: Record<string, unknown> = { ...inherited, ...branch };
+  const inheritedProps = isXaiObjectSchema(inherited.properties) ? inherited.properties : undefined;
+  const branchProps = isXaiObjectSchema(branch.properties) ? branch.properties : undefined;
+  if (inheritedProps || branchProps) {
+    const properties: Record<string, unknown> = { ...(inheritedProps ?? {}) };
+    for (const [name, value] of Object.entries(branchProps ?? {})) {
+      const inheritedValue = inheritedProps?.[name];
+      properties[name] = inheritedValue !== undefined && JSON.stringify(inheritedValue) !== JSON.stringify(value)
+        ? { allOf: [inheritedValue, value] }
+        : value;
+    }
+    composed.properties = properties;
+  }
+  const required = [...new Set([
+    ...stringRequiredFields(inherited.required),
+    ...stringRequiredFields(branch.required),
+  ])];
+  if (required.length > 0) composed.required = required;
+  else delete composed.required;
+  return composed;
+}
+
 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 (!isXaiObjectSchema(schema)) return undefined;
+  const compositionKey = ["oneOf", "anyOf"].find(key => Array.isArray(schema[key]));
   if (!compositionKey) {
-    if (obj.type !== undefined && obj.type !== "object") return undefined;
-    return [{ ...obj, type: "object" }];
+    if (schema.type !== undefined && schema.type !== "object") return undefined;
+    return [{ ...schema, type: "object" }];
   }
 
-  const siblings = Object.fromEntries(Object.entries(obj).filter(([key]) => key !== compositionKey));
-  const branches = obj[compositionKey];
+  const siblings = Object.fromEntries(Object.entries(schema).filter(([key]) => key !== compositionKey));
+  const branches = schema[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 });
+    for (const variant of variants) expanded.push(composeXaiObjectSchemas(siblings, variant));
   }
   return expanded.length > 0 ? expanded : undefined;
 }
 
+function mergeXaiPropertySchemas(values: unknown[]): unknown {
+  const unique: unknown[] = [];
+  const serialized = new Set<string>();
+  for (const value of values) {
+    const key = JSON.stringify(value);
+    if (serialized.has(key)) continue;
+    serialized.add(key);
+    unique.push(value);
+  }
+  return unique.length === 1 ? unique[0] : { anyOf: unique };
+}
+
+/**
+ * The Grok CLI proxy rejects a function parameter schema whose root remains oneOf/anyOf.
+ * Flatten only when the merge is lossless: local $refs resolve, every variant is a concrete
+ * object whose keys we can preserve, required sets match, additionalProperties does not change
+ * meaning, every property name exists on every variant, and at most one property schema
+ * differs. Otherwise omit the tool rather than emit a weaker schema.
+ */
 function normalizeXaiToolParameters(parameters: unknown): Record<string, unknown> | undefined {
-  const variants = expandXaiRootObjectSchemas(parameters);
+  if (!isXaiObjectSchema(parameters)) return undefined;
+  const resolved = resolveXaiSchemaRefs(parameters, parameters);
+  if (!isXaiObjectSchema(resolved)) return undefined;
+
+  const normalizedRoot = { ...resolved };
+  delete normalizedRoot.$schema;
+
+  const variants = expandXaiRootObjectSchemas(normalizedRoot);
   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 };
+  if (variants.length === 1) {
+    return xaiVariantIsConcreteObject(variants[0]) ? variants[0] : undefined;
+  }
+  if (!variants.every(xaiVariantIsConcreteObject) || !xaiRequiredSetsMatch(variants)) return undefined;
+  const additionalProperties = mergeXaiAdditionalProperties(variants);
+  if (!additionalProperties.ok) return undefined;
+  if (!xaiPropertyMergeIsLossless(variants)) return undefined;
+
+  const metadata = Object.fromEntries(Object.entries(normalizedRoot).filter(([key]) => key !== "oneOf" && key !== "anyOf" && key !== "type"));
+  delete metadata.properties;
+  delete metadata.required;
+  delete metadata.additionalProperties;
+
+  const propertyValues = new Map<string, unknown[]>();
+  for (const variant of variants) {
+    if (!variant.properties || typeof variant.properties !== "object" || Array.isArray(variant.properties)) continue;
+    for (const [name, value] of Object.entries(variant.properties as Record<string, unknown>)) {
+      const values = propertyValues.get(name) ?? [];
+      values.push(value);
+      propertyValues.set(name, values);
+    }
+  }
+
+  const properties = Object.fromEntries(
+    [...propertyValues].map(([name, values]) => [name, mergeXaiPropertySchemas(values)]),
+  );
+  const required = stringRequiredFields(variants[0]?.required);
+
+  return {
+    ...metadata,
+    type: "object",
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+    ...("value" in additionalProperties ? { additionalProperties: additionalProperties.value } : {}),
+  };
 }
 
 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;
+  const tools = parsed.context.tools.filter(toolChoiceToolPredicate(parsed.options.toolChoice, parsed.context.tools));
   if (tools.length === 0) return undefined;
   const xaiTarget = isXaiSchemaTarget(provider);
-  const kimiTarget = isKimiSchemaTarget(provider);
   const formatted = tools.flatMap(t => {
-    const parameters = xaiTarget
+    const parameters = stripResponsesOnlyEncryptedMarker(xaiTarget
       ? normalizeXaiToolParameters(t.parameters)
-      : kimiTarget
-        ? ensureKimiRootObjectType(t.parameters)
-        : 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 } : {}),
-    },
+      type: "function",
+      function: {
+        name: namespacedToolName(t.namespace, t.name),
+        ...(t.description ? { description: t.description } : {}),
+        parameters,
+        ...(t.strict !== undefined ? { strict: t.strict } : {}),
+      },
     }];
   });
   return formatted.length > 0 ? formatted : undefined;
@@ -509,9 +1264,18 @@ function toolsToChatFormatForProvider(parsed: OcxParsedRequest, provider: OcxPro
   });
 }
 
-function toolChoiceToChatFormat(tc: OcxParsedRequest["options"]["toolChoice"], tools: OcxParsedRequest["context"]["tools"]): unknown {
+function toolChoiceToChatFormat(
+  tc: OcxParsedRequest["options"]["toolChoice"],
+  tools: OcxParsedRequest["context"]["tools"],
+  provider: OcxProviderConfig,
+): unknown {
   if (!tc) return undefined;
-  if (isAllowedToolChoice(tc)) return tc.mode === "required" ? "required" : "auto";
+  if (isAllowedToolChoice(tc)) {
+    if (tc.mode === "required" && tc.allowedTools.length === 1 && isNativeOpenAIChatTarget(provider)) {
+      return { type: "function", function: { name: resolveToolChoiceWireName(tools, tc.allowedTools[0]) } };
+    }
+    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;
@@ -549,6 +1313,26 @@ function thinkingBudgetForEffort(parsed: OcxParsedRequest, reasoningEffort: stri
   return fraction === undefined ? undefined : Math.max(1, Math.floor(maxBudget * fraction));
 }
 
+function canSerializeOpenAIChatServiceTier(
+  provider: OcxProviderConfig,
+  modelId: string,
+  serviceTier: unknown,
+  tierDecision?: OcxParsedRequest["options"]["tierDecision"],
+): boolean {
+  if (serviceTier === undefined) return false;
+  if (tierDecision !== undefined) {
+    return tierDecision.kind === "set" || tierDecision.kind === "forward-caller";
+  }
+  // No decision from the router means this call did not go through the tier state machine, so
+  // ask that machine rather than re-deriving a looser answer beside it. The previous fallback
+  // returned true whenever foreign forwarding was allowed at all, which let a caller tier
+  // reach the wire in cases `decideTier` would have dropped — the two paths disagreeing is
+  // precisely the bug, so there is now only one authority.
+  const callerTier = typeof serviceTier === "string" ? serviceTier : undefined;
+  const decision = decideTier(fastPolicyForModel(provider, modelId, undefined, "chat"), undefined, callerTier);
+  return decision.kind === "set" || decision.kind === "forward-caller";
+}
+
 export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAdapter {
   return {
     name: "openai-chat",
@@ -556,20 +1340,30 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
     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 { url, headers, hasCredential } = openAIChatTransport(provider);
       const messages = messagesToChatFormat(parsed, provider);
       const tools = toolsToChatFormatForProvider(parsed, provider);
-      const toolChoice = toolChoiceToChatFormat(parsed.options.toolChoice, parsed.context.tools);
+      const toolChoice = toolChoiceToChatFormat(parsed.options.toolChoice, parsed.context.tools, provider);
 
       const body: Record<string, unknown> = {
         model: provider.modelSuffixBracketStrip ? stripBracketedModelSuffix(parsed.modelId) : parsed.modelId,
         messages,
         stream: parsed.stream,
       };
+      // A policy-produced canonical decision has already passed capability validation. Without
+      // that decision, a canonical caller value still requires an explicit true capability;
+      // unclassified Chat routes remain behind the caller-forwarding opt-in.
+      const serviceTier = parsed.options.serviceTier;
+      const tierDecision = parsed.options.tierDecision;
+      const canSerializeServiceTier = canSerializeOpenAIChatServiceTier(
+        provider,
+        parsed.modelId,
+        serviceTier,
+        tierDecision,
+      );
+      if (canSerializeServiceTier && serviceTier !== undefined) {
+        body.service_tier = serviceTier;
+      }
       if (modelInList(provider.reasoningSplitModels, parsed.modelId)) body.reasoning_split = true;
       const maxTokens = resolveMaxTokens(provider, parsed);
       const openRouterRouting = resolveOpenRouterRouting(provider, parsed.modelId);
@@ -588,10 +1382,44 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         body.top_p = parsed.options.topP;
       }
       if (parsed.options.stopSequences !== undefined) body.stop = parsed.options.stopSequences;
+      const reasoningDisabled = modelInList(provider.noReasoningModels, parsed.modelId);
       const reasoningEffort = mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning);
+      const nativeOpenAI = isNativeOpenAIChatTarget(provider);
       let reasoningLog: AdapterRequest["reasoningLog"];
-      if (reasoningEffort !== undefined) {
-        if (modelInList(provider.thinkingBudgetModels, parsed.modelId)) {
+      if (!reasoningDisabled && provider.reasoningWireFormat === "gateway-object" && parsed.options.reasoning === "none") {
+        if (nativeOpenAI) {
+          body.reasoning_effort = "none";
+          reasoningLog = {
+            effectiveEffort: "none",
+            wireField: "reasoning_effort",
+            wireValue: "none",
+          };
+        } else {
+          body.reasoning = { enabled: false };
+          reasoningLog = {
+            effectiveEffort: "none",
+            wireField: "reasoning.enabled",
+            wireValue: false,
+          };
+        }
+      } else if (reasoningEffort !== undefined) {
+        if (provider.reasoningWireFormat === "gateway-object") {
+          if (nativeOpenAI) {
+            body.reasoning_effort = reasoningEffort;
+            reasoningLog = {
+              effectiveEffort: reasoningEffort,
+              wireField: "reasoning_effort",
+              wireValue: reasoningEffort,
+            };
+          } else {
+            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;
@@ -602,9 +1430,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
             };
           }
         } 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 = {
@@ -628,37 +1453,55 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       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;
       }
+      // Structured-output support varies by the physical upstream model even when one
+      // gateway exposes a uniform OpenAI-compatible endpoint. Keep the #1137 translation
+      // as the default, but let an exact model opt out instead of forcing a provider-wide
+      // rollback that would silently return prose for siblings that support JSON Schema.
+      if (!provider.noStructuredOutputModels?.includes(parsed.modelId)) {
+        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 };
+        if (provider.parallelToolCalls === false) {
+          // NIM documents the Boolean defaulting to false and kimi rejects true; pin the
+          // wire bit so Codex cannot opt in via request.options. Other opted-out providers
+          // omit the field by default so strict OpenAI-compatible hosts never see an
+          // unsupported knob, but a self-hosted gateway that DOES honor the field and keeps
+          // emitting parallel calls without it can opt in via pinParallelToolCallsFalse.
+          if (provider.baseUrl === "https://integrate.api.nvidia.com/v1"
+              || provider.pinParallelToolCallsFalse === true) {
+            body.parallel_tool_calls = false;
+          }
+        } else if (provider.parallelToolCalls === true) {
+          body.parallel_tool_calls = parsed.options.parallelToolCalls !== false;
+        }
       }
-
-      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);
+      if (parsed.stream) body.stream_options = { include_usage: true };
 
       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).
+      const actualServiceTier = typeof body.service_tier === "string" ? body.service_tier : null;
+      const tierLog = createAdapterTierMetadata(
+        parsed.options.tierObservation,
+        parsed.options.tierDecision,
+        actualServiceTier === null ? null : "service-tier",
+        actualServiceTier,
+      );
       if (isDebugEnabled()) {
         let host = "upstream";
         try { host = new URL(url).host; } catch { /* keep fallback */ }
@@ -679,10 +1522,15 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         headers,
         body: bodyJson,
         ...(reasoningLog ? { reasoningLog } : {}),
+        ...(tierLog ? { tierLog } : {}),
       };
     },
 
-    async *parseStream(response: Response, budget: TranslatorBudget): AsyncGenerator<AdapterEvent> {
+    async *parseStream(
+      response: Response,
+      budget: TranslatorBudget,
+      tierMetadata?: AdapterTierMetadata,
+    ): AsyncGenerator<AdapterEvent> {
       if (!response.body) {
         yield { type: "error", message: "No response body" };
         return;
@@ -693,138 +1541,240 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       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 }
+      interface PendingToolCall {
+        key: string;
+        id: string;
+        name: string;
+        args: string;
+        argsBytes: number;
+        /**
+         * Whether this call has ever received `arguments` as an actual string, empty included.
+         * An empty string still counts: it proves the upstream sent the field with the right
+         * wire type, which is what a later malformed repeat of that field would be padding for.
+         * A canonical NAME is not evidence about the ARGUMENTS field and must not stand in.
+         */
+        sawArgumentsString: boolean;
+      }
       const pendingToolCalls: PendingToolCall[] = [];
       let toolCallSeq = 0;
-      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 pendingToolCalls) {
+      const closeToolCalls = (): PendingToolCall[] => {
+        const calls = [...pendingToolCalls];
+        for (const call of calls) budget.closeCall(call.key);
+        pendingToolCalls.length = 0;
+        return calls;
+      };
+      const pendingToolCallsAreCompleteJsonObjects = (): boolean =>
+        pendingToolCalls.length > 0 && pendingToolCalls.every(call => {
+          if (call.name.trim().length === 0 || !call.sawArgumentsString || call.args.length === 0) return false;
+          try {
+            const parsed = JSON.parse(call.args) as unknown;
+            return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed);
+          } catch {
+            return false;
+          }
+        });
+      // Returns "terminate" when a pending call cannot be dispatched, so every flush site
+      // stops the turn instead of emitting an unusable call. `closeToolCalls()` runs first,
+      // so budget reservations are released for every pending call even on the early return.
+      const flushToolCalls = function* (): Generator<AdapterEvent, "continue" | "terminate"> {
+        for (const call of closeToolCalls()) {
+          // Ingest already proved `name` is a string; the typeof guard keeps this branch
+          // total so a future ingest change cannot turn a malformed name into a throw.
+          if (typeof call.name !== "string" || call.name.trim().length === 0) {
+            debugProviderDiagnostic("openai-chat", "tool-call-unnamed", {
+              hadId: call.id.length > 0,
+              argsBytes: call.argsBytes,
+            });
+            yield unnamedToolCallEvent(pendingUsage);
+            return "terminate";
+          }
           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" };
-          budget.closeCall(call.key);
         }
-        pendingToolCalls.length = 0;
+        return "continue";
+      };
+      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"> {
-        if (!line.startsWith("data: ")) return "continue";
-        const payload = line.slice(6).trim();
+        const rawPayload = sseFieldValue(line, "data");
+        if (rawPayload === null) return "continue";
+        const payload = rawPayload.trim();
+        if (payload.length === 0) return "continue";
         if (payload === "[DONE]") {
-          yield* flushToolCalls();
-          const stopReason = finishReason === "length"
-            ? "max_tokens"
-            : finishReason === "content_filter"
-              ? "content_filter"
-              : undefined;
+          if ((yield* flushToolCalls()) === "terminate") return "terminate";
+          const stopReason = stopReasonFor(finishReason);
           yield { type: "done", usage: pendingUsage, ...(stopReason ? { stopReason } : {}) };
           return "terminate";
         }
 
-        let chunk: Record<string, unknown>;
+        let parsed: unknown;
         try {
-          chunk = JSON.parse(payload) as Record<string, unknown>;
+          parsed = JSON.parse(payload);
         } catch {
+          tierMetadata?.markResponseUnparseable();
           yield { type: "error", message: "malformed upstream SSE data frame" };
           return "terminate";
         }
-
-        // 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) {
-          const err = chunk.error as { message?: string; code?: string; type?: string; status?: number } | undefined;
-          const message = err?.message ?? "upstream error";
-          debugProviderDiagnostic("openai-chat", "stream-error", { message });
-          yield* flushToolCalls();
-          yield {
-            type: "error",
-            message,
-            ...(typeof err?.code === "string" ? { code: err.code } : {}),
-            ...(typeof err?.type === "string" ? { errorType: err.type } : {}),
-            ...(isCyberPolicyCode(err?.code)
-              ? { status: 400 }
-              : typeof err?.status === "number" && Number.isInteger(err.status)
-                ? { status: err.status }
-                : {}),
-          };
-          return "terminate";
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return "continue";
+        const chunk = parsed as Record<string, unknown>;
+        if (Object.hasOwn(chunk, "service_tier")) {
+          tierMetadata?.observeResponseServiceTier(chunk.service_tier);
         }
 
-        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>);
+        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);
         }
 
-        const choices = chunk.choices as { delta?: Record<string, unknown>; finish_reason?: string }[] | undefined;
-        if (!choices || choices.length === 0) return "continue";
-        // 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 choices[0].finish_reason === "string" && choices[0].finish_reason) {
-          finishReason = choices[0].finish_reason;
+        if (chunk.usage) 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 delta = choices[0].delta;
+        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);
+        }
+        if (typeof choice.finish_reason === "string" && choice.finish_reason) finishReason = choice.finish_reason;
+        const delta = choice.delta;
         if (delta) {
-          if (typeof delta.reasoning_content === "string" && delta.reasoning_content.length > 0) {
-            yield { type: "reasoning_raw_delta", text: delta.reasoning_content };
-          }
+          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;
+          const rawToolCalls = delta.tool_calls;
+          if (rawToolCalls !== undefined && rawToolCalls !== null) {
+            // A non-null claimed tool-call payload is not benign padding. Dropping it can leave the
+            // matching result permanently orphaned, so malformed nested shapes fail closed
+            // through the adapter error channel instead of escaping as TypeError (#1325). Null is
+            // tolerated as absent because OpenAI-compatible providers may emit it as stream padding.
+            if (!Array.isArray(rawToolCalls)) {
+              logInvalidToolCalls("stream", rawToolCalls);
+              return yield* terminateWithError(invalidToolCallsEvent(rawToolCalls, "stream", pendingUsage));
+            }
+            for (let callIndex = 0; callIndex < rawToolCalls.length; callIndex++) {
+              const rawToolCall: unknown = rawToolCalls[callIndex];
+              if (!isRecord(rawToolCall)) {
+                const diagnostic: InvalidToolCallDiagnostic = {
+                  reason: "tool_call_not_object",
+                  callIndex,
+                  valueType: rawToolCall === null ? "null" : Array.isArray(rawToolCall) ? "array" : typeof rawToolCall,
+                };
+                logInvalidToolCalls("stream", rawToolCalls, diagnostic);
+                return yield* terminateWithError(invalidToolCallsEvent(rawToolCalls, "stream", pendingUsage, diagnostic));
+              }
+              // This is upstream JSON, so every field is validated before it is stored: a
+              // malformed value must fail closed through the #1325 channel here rather than
+              // escaping later as a TypeError from string handling at flush time.
+              const rawFunction = rawToolCall.function;
+              if (rawFunction !== undefined && rawFunction !== null && !isRecord(rawFunction)) {
+                const diagnostic: InvalidToolCallDiagnostic = {
+                  reason: "tool_call_function_not_object",
+                  callIndex,
+                  valueType: Array.isArray(rawFunction) ? "array" : typeof rawFunction,
+                };
+                logInvalidToolCalls("stream", rawToolCalls, diagnostic);
+                return yield* terminateWithError(invalidToolCallsEvent(rawToolCalls, "stream", pendingUsage, diagnostic));
+              }
+              const fnRecord = isRecord(rawFunction) ? rawFunction : undefined;
+              const rawName = fnRecord?.name;
+              const rawArguments = fnRecord?.arguments;
+              const rawId = rawToolCall.id;
+              const idDelta = typeof rawId === "string" ? rawId : "";
+              const rawIndex = rawToolCall.index;
+
+              // Resolve the pending call BEFORE judging the fields. Some OpenAI-compatible
+              // streamers repeat an already-sent field as a non-string placeholder on a
+              // continuation delta; judging first meant the whole stream died with a 502 even
+              // though the value being repeated was already held in canonical form.
+              const key = typeof rawIndex === "number"
+                ? `i:${rawIndex}`
+                : idDelta
+                  ? `id:${idDelta}`
+                  : 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 && idDelta) call = pendingToolCalls.find(c => c.id === idDelta);
               if (!call) {
-                call = { key: key ?? `seq:${pendingToolCalls.length}`, id: "", name: "", args: "", argsBytes: 0 };
+                call = {
+                  key: key ?? `seq:${pendingToolCalls.length}`,
+                  id: "",
+                  name: "",
+                  args: "",
+                  argsBytes: 0,
+                  sawArgumentsString: false,
+                };
                 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) {
+
+              // Tolerance is per FIELD, keyed on that field's own provenance. A canonical name
+              // says nothing about whether `arguments` was ever sent as a string, so it cannot
+              // authorize a malformed arguments value — that would silently drop a real
+              // argument payload the model intended to send.
+              const rejection: InvalidToolCallDiagnostic | undefined =
+                isInvalidStreamStringField(rawName) && call.name.trim() === ""
+                  ? { reason: "tool_call_function_name_invalid", callIndex, valueType: typeof rawName }
+                  : isInvalidStreamStringField(rawArguments) && !call.sawArgumentsString
+                    ? { reason: "tool_call_function_arguments_invalid", callIndex, valueType: typeof rawArguments }
+                    : isInvalidStreamStringField(rawId) && call.id === ""
+                      ? { reason: "tool_call_id_invalid", callIndex, valueType: typeof rawId }
+                      : undefined;
+              if (rejection) {
+                logInvalidToolCalls("stream", rawToolCalls, rejection);
+                return yield* terminateWithError(invalidToolCallsEvent(rawToolCalls, "stream", pendingUsage, rejection));
+              }
+
+              if (idDelta && !call.id) call.id = idDelta;
+              if (typeof rawName === "string" && rawName && !call.name) call.name = rawName;
+              if (typeof rawArguments === "string") call.sawArgumentsString = true;
+              // Tool-call deltas are BUFFERED until a terminal signal, so this adapter can
+              // consume upstream frames for a long time while yielding nothing. The Responses
+              // bridge reads adapter activity, not socket activity, so a model that streams a
+              // large argument payload looks identical to a hung upstream and the stall
+              // watchdog can abort a turn that was progressing normally.
+              //
+              // Found while investigating #2156, but it is NOT that bug: a stall abort emits
+              // `response.incomplete` with `upstream_stall_timeout` from the bridge, whereas
+              // that report shows the adapter's own end-of-stream error after `reader.read()`
+              // returned EOF with tool calls still pending. Different path, different frame.
+              //
+              // A heartbeat is invisible downstream — the bridge consumes it to re-arm the
+              // watchdog and emits nothing — which is the same remedy the Cursor, Anthropic,
+              // Google, and Kiro adapters already use for their own silent phases.
+              yield { type: "heartbeat" };
+              if (typeof rawArguments === "string" && rawArguments) {
                 const previousBytes = call.argsBytes;
-                const nextBytes = previousBytes + budgetEncoder.encode(tc.function.arguments).byteLength;
+                const nextBytes = previousBytes + budgetEncoder.encode(rawArguments).byteLength;
                 const scope = { kind: "tool_args" as const, callId: call.key };
                 const reservation = budget.reserveTransient(nextBytes, scope);
                 try {
-                  call.args += tc.function.arguments;
+                  call.args += rawArguments;
                   reservation.commitRetained();
                   budget.releaseRetained(previousBytes, scope);
                   call.argsBytes = nextBytes;
@@ -837,10 +1787,8 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           }
         }
 
-        // 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 choices[0].finish_reason === "string" && choices[0].finish_reason) {
-          yield* flushToolCalls();
+        if (typeof choice.finish_reason === "string" && choice.finish_reason) {
+          if ((yield* flushToolCalls()) === "terminate") return "terminate";
         }
         return "continue";
       };
@@ -880,23 +1828,20 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           }
         }
 
-        // 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) {
+          // Some OpenAI-compatible gateways close immediately after a complete function-call
+          // delta and omit both terminal conventions. Keep the default fail-closed policy, and
+          // let an opted-in provider recover only calls whose assembled argument payload is a
+          // complete JSON object. A partial JSON prefix still takes the truncation path below.
+          if (provider.openaiChatEofTolerance === true && pendingToolCallsAreCompleteJsonObjects()) {
+            if ((yield* flushToolCalls()) === "terminate") return;
+            yield { type: "done", usage: pendingUsage };
+            return;
+          }
           debugProviderDiagnostic("openai-chat", "stream-truncated", {
             finishReason: null,
             hadUsage: pendingUsage !== undefined,
@@ -905,9 +1850,6 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           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,
@@ -916,13 +1858,8 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           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 = finishReason === "length"
-          ? "max_tokens"
-          : finishReason === "content_filter"
-            ? "content_filter"
-            : undefined;
+        if ((yield* flushToolCalls()) === "terminate") return;
+        const stopReason = stopReasonFor(finishReason);
         yield { type: "done", usage: pendingUsage, ...(stopReason ? { stopReason } : {}) };
       } catch (error) {
         if (isTranslatorBudgetExceededError(error)
@@ -940,63 +1877,101 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         throw error;
       } finally {
         budget.releaseRetained(bufferBytes, { kind: "live_transient" });
-        for (const call of pendingToolCalls) budget.closeCall(call.key);
+        closeToolCalls();
         reader.releaseLock();
       }
     },
 
-    async parseResponse(response: Response, budget: TranslatorBudget): Promise<AdapterEvent[]> {
-      const json = await response.json() as Record<string, unknown>;
+    async parseResponse(
+      response: Response,
+      budget: TranslatorBudget,
+      tierMetadata?: AdapterTierMetadata,
+    ): Promise<AdapterEvent[]> {
+      let parsed: unknown;
+      try {
+        parsed = await response.json();
+      } catch (error) {
+        tierMetadata?.markResponseUnparseable();
+        throw error;
+      }
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        tierMetadata?.markResponseUnparseable();
+        throw new Error("upstream response was not a JSON object");
+      }
+      const json = parsed as Record<string, unknown>;
+      if (Object.hasOwn(json, "service_tier")) {
+        tierMetadata?.observeResponseServiceTier(json.service_tier);
+      }
       const responseBytes = new TextEncoder().encode(JSON.stringify(json)).byteLength;
       budget.chargeRetained(responseBytes, { kind: "retained_collectors" });
       try {
-      if (json.error) {
-        const upstreamError = json.error as { message?: unknown; code?: unknown; type?: unknown; status?: unknown };
-        const message = typeof upstreamError.message === "string" ? upstreamError.message : "upstream error";
-        const code = typeof upstreamError.code === "string" ? upstreamError.code : undefined;
-        const errorType = typeof upstreamError.type === "string" ? upstreamError.type : undefined;
-        const status = isCyberPolicyCode(code)
-          ? 400
-          : typeof upstreamError.status === "number" && Number.isInteger(upstreamError.status)
-            ? upstreamError.status
-            : undefined;
-        return [{
-          type: "error",
-          message,
-          ...(code !== undefined ? { code } : {}),
-          ...(errorType !== undefined ? { errorType } : {}),
-          ...(status !== undefined ? { status } : {}),
-        }];
-      }
+        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 = json.choices as { message?: Record<string, unknown> }[] | undefined;
-      if (!Array.isArray(choices) || choices.length === 0 || !choices[0].message) {
-        return [{ type: "error", message: "upstream response contained no choices" }];
-      }
+        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 = choices[0].message;
-      if (typeof msg.reasoning_content === "string" && msg.reasoning_content.length > 0) {
-        events.push({ type: "reasoning_raw_delta", text: msg.reasoning_content });
-      }
-      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 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 rawToolCalls = msg.tool_calls;
+        if (rawToolCalls !== undefined && rawToolCalls !== null) {
+          if (!Array.isArray(rawToolCalls)) {
+            logInvalidToolCalls("response", rawToolCalls);
+            return [invalidToolCallsEvent(rawToolCalls, "response", usage)];
+          }
+          for (const rawToolCall of rawToolCalls) {
+            if (!isRecord(rawToolCall) || !isRecord(rawToolCall.function)) {
+              logInvalidToolCalls("response", rawToolCalls);
+              return [invalidToolCallsEvent(rawToolCalls, "response", usage)];
+            }
+            const id = rawToolCall.id;
+            const name = rawToolCall.function.name;
+            const args = rawToolCall.function.arguments;
+            // A blank name is as undispatchable as a missing one, so it fails closed here
+            // for the same reason the streamed path refuses it. Trimmed length, not `!name`:
+            // a whitespace-only function name is not a legitimate tool-call shape either.
+            if (typeof id !== "string" || typeof name !== "string" || typeof args !== "string"
+              || name.trim().length === 0) {
+              logInvalidToolCalls("response", rawToolCalls);
+              return [invalidToolCallsEvent(rawToolCalls, "response", usage)];
+            }
+            events.push({ type: "tool_call_start", id, name });
+            events.push({ type: "tool_call_delta", arguments: args });
+            events.push({ type: "tool_call_end" });
+          }
         }
-      }
-      const usage = json.usage as Record<string, unknown> | undefined;
-      events.push({
-        type: "done",
-        usage: usageFromOpenAIChat(usage),
-      });
-      retainTranslatedEventBatch(events, budget);
-      return events;
+        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" });
       }