@bitkyc08/opencodex 2.55.0 → 2.56.0

package/src/adapters/openai-chat.ts

@@ -1,1462 +1,50 @@
 import { hasShrinkableOpenAIChatImages, normalizeOpenAIChatImages } from "./openai-chat-images";
 import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "./base";
-import type { AdapterEvent, OcxAssistantMessage, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent, OcxThinkingContent, OcxToolCall, OcxUsage } from "../types";
-import { isAllowedToolChoice, modelInList, namespacedToolName, resolveToolChoiceWireName, toolChoiceToolPredicate } from "../types";
+import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig, OcxUsage } from "../types";
+import { modelInList } from "../types";
 import { mapReasoningEffort, modelRecordValue } from "../reasoning-effort";
-import { registryEntryForProviderDestination } from "../providers/registry";
 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 { EMPTY_TOOL_OUTPUT_ANNOTATION, isWhitespaceOnlyTextPartArray } from "./empty-tool-output-annotation";
-import { identifyRoutedModel } from "./identity";
-import { peekReasoningForCall } from "../responses/reasoning-replay-cache";
-import { buildNonOpenAIToolCatalogNudgeForTools, shouldInjectNonOpenAIToolCatalogNudge } from "./tool-catalog-nudge";
+import { frameAgentRouterMessages } from "./agentrouter";
 import { openRouterProviderPayload, resolveOpenRouterRouting } from "../providers/openrouter-routing";
 import { resolveVercelGatewayRouting, vercelGatewayProviderPayload } from "../providers/vercel-gateway-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, stripUnicodePropertyPatterns } from "./responses-tool-schema";
-import { agentRouterDefaultHeaders, frameAgentRouterMessages } from "./agentrouter";
-import {
-  isXaiSchemaTarget,
-  lookupLocalJsonPointer,
-  normalizeXaiToolParameters,
-} from "./xai-tool-schema";
+import { fastPolicyForModel } from "../providers/service-tier";
+import { createAdapterTierMetadata, decideTier, type AdapterTierMetadata } from "../providers/fastwire";
 import {
   isTranslatorBudgetExceededError,
   retainTranslatedEventBatch,
   TRANSLATOR_MAX_SSE_EVENT_BYTES,
   type TranslatorBudget,
 } from "../lib/translator-budget";
-
-// Providers may opt into stripping one trailing "[...]" group from the wire model id.
-// Z.AI needs this because its OpenAI path rejects glm-5.2[1m] with 400 code 1211;
-// unflagged OpenAI-compatible providers and the Anthropic adapter keep ids verbatim.
-export function stripBracketedModelSuffix(modelId: string): string {
-  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",
-    ...agentRouterDefaultHeaders(provider.baseUrl, provider.headers),
-  };
-  if (hasCredential) headers.Authorization = `Bearer ${provider.apiKey}`;
-  if (provider.headers) Object.assign(headers, provider.headers);
-  // A configured relative path wins, mirroring how the Responses adapter honours
-  // `responsesPath`. An upstream can serve both wires under different prefixes, and a
-  // per-model wire override only swaps the adapter, so without this the opted-in Chat
-  // request would be sent to the Responses base with `/chat/completions` appended.
-  const url = provider.chatCompletionsPath === undefined
-    ? openaiChatCompletionsUrl(provider.baseUrl)
-    : `${provider.baseUrl.replace(/\/$/, "")}${provider.chatCompletionsPath}`;
-  return { url, headers, hasCredential };
-}
-
-/**
- * The translated Chat route has no video mapping: this adapter does not implement one,
- * and the marker records that fact so the payload is not dropped in silence.
- *
- * The wording is deliberately about opencodex's own translation, not the provider or
- * model. An earlier revision said "unsupported by this provider", which attributed an
- * opencodex mapping limit to upstream capability the proxy has not established. Native
- * Chat passthrough and Google inline video are unaffected by this route.
- */
-const VIDEO_UNSUPPORTED_MARKER = "[video omitted: the translated Chat route has no video mapping]";
-
-/**
- * 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: frameAgentRouterMessages(provider.baseUrl, rawBody.messages),
-    stream,
-  };
-  for (const field of CHAT_PASSTHROUGH_FIELDS) {
-    if (rawBody[field] !== undefined) body[field] = rawBody[field];
-  }
-  const rawEfforts = modelRecordValue(provider.modelReasoningEfforts, modelId) ?? provider.reasoningEfforts;
-  if (modelInList(provider.noReasoningModels, modelId) || rawEfforts?.length === 0) {
-    delete body.reasoning_effort;
-  }
-
-  const openRouterRouting = resolveOpenRouterRouting(provider, modelId);
-  if (openRouterRouting) body.provider = openRouterProviderPayload(openRouterRouting);
-  const vercelRouting = resolveVercelGatewayRouting(provider, modelId);
-  if (vercelRouting) body.provider = vercelGatewayProviderPayload(vercelRouting);
-
-  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;
-  // Narrower neighbour: the model takes `json_object` but rejects `json_schema`. Downgrade
-  // rather than drop, so a caller that asked for JSON still gets JSON. The type check also
-  // makes the kill switch above win without an else — after its `delete` there is no type
-  // left to match.
-  const passthroughFormat = body.response_format;
-  if (provider.noJsonSchemaModels?.includes(modelId)
-      && typeof passthroughFormat === "object" && passthroughFormat !== null
-      && (passthroughFormat as { type?: unknown }).type === "json_schema") {
-    body.response_format = { type: "json_object" };
-  }
-
-  // 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: Buffer.byteLength(bodyJson, "utf8"),
-    });
-  }
-
-  return { url, method: "POST", headers, body: bodyJson };
-}
-
-// 260715 (issue #126): surface upstream error detail through the web-search sidecar loop.
-// loop.ts only appends a suffix to "Provider error N" when the adapter exposes
-// formatErrorBody; without it, strict OpenAI-compatible backends (NVIDIA NIM pydantic
-// validation, "This model only supports single tool-calls at once!", etc.) were reduced
-// to a bare status code. JSON-only extraction: recognized string fields are returned,
-// HTML/non-JSON bodies yield "" so raw markup is never echoed to the client.
-export function formatOpenAIChatErrorBody(status: number, _headers: Headers, payloadText: string): string {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(payloadText);
-  } catch {
-    return "";
-  }
-  const detail = extractErrorDetail(parsed);
-  if (!detail) return "";
-  return redactSecretString(detail).slice(0, 400);
-}
-
-function extractErrorDetail(parsed: unknown): string | undefined {
-  if (typeof parsed === "string") return parsed.trim() || undefined;
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
-  const obj = parsed as Record<string, unknown>;
-  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();
-  }
-  const det = obj.detail;
-  if (typeof det === "string" && det.trim()) return det.trim();
-  if (Array.isArray(det)) {
-    const msgs = det
-      .map(item => (item !== null && typeof item === "object" && typeof (item as Record<string, unknown>).msg === "string"
-        ? ((item as Record<string, unknown>).msg as string).trim()
-        : ""))
-      .filter(m => m.length > 0);
-    if (msgs.length > 0) return msgs.join("; ");
-  }
-  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;
-}
-
-interface ReasoningDetailSegment {
-  key: string;
-  text: string;
-}
-
-/**
- * Structured `reasoning_details` array (MiniMax M-series with `reasoning_split`).
- * Each segment's key scopes cumulative-snapshot tracking: upstream repeats the
- * full text-so-far under a stable `id`/`index` instead of sending increments.
- */
-function reasoningDetailSegmentsFrom(record: Record<string, unknown>): ReasoningDetailSegment[] {
-  const raw = record.reasoning_details;
-  if (!Array.isArray(raw)) return [];
-  const segments: ReasoningDetailSegment[] = [];
-  for (let i = 0; i < raw.length; i++) {
-    const item: unknown = raw[i];
-    if (!isRecord(item)) continue;
-    if (typeof item.text !== "string" || item.text.length === 0) continue;
-    const key = typeof item.id === "string" && item.id.length > 0
-      ? `id:${item.id}`
-      : typeof item.index === "number"
-        ? `i:${item.index}`
-        : `n:${i}`;
-    segments.push({ key, text: item.text });
-  }
-  return segments;
-}
-
-/** Single-segment `reasoning_details` entry for replaying preserved reasoning (MiniMax wire shape). */
-function reasoningDetailSegmentForWire(text: string): Record<string, unknown> {
-  return { type: "reasoning.text", id: "reasoning-text-1", format: "MiniMax-response-v1", index: 0, text };
-}
-
-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;
-  if (message.content.some(part => part.type === "image")) return 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[], annotateEmpty = false): string {
-  // An empty content array is a present-but-empty result; `contentPartsToText` would
-  // otherwise fall back to the "[image]" marker and hide the emptiness from the model.
-  if (annotateEmpty && Array.isArray(content) && content.length === 0) return EMPTY_TOOL_OUTPUT_ANNOTATION;
-  if (typeof content === "string") {
-    if (annotateEmpty && content.trim() === "") return EMPTY_TOOL_OUTPUT_ANNOTATION;
-    return content;
-  }
-  const text = content.filter((p) => p.type === "text").map((p) => (p as OcxTextContent).text).join("");
-  // A whitespace-only text-part array is the array twin of a blank string; the
-  // shared emptiness contract (same module as the Responses adapter) annotates it
-  // instead of forwarding whitespace the model silently accepts. Image parts and
-  // any other non-text part keep the array non-empty.
-  if (annotateEmpty && isWhitespaceOnlyTextPartArray(content)) {
-    return EMPTY_TOOL_OUTPUT_ANNOTATION;
-  }
-  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;
-
-  interface PendingToolCall { id: string; name: string }
-  let pendingToolCalls: PendingToolCall[] = [];
-  let deferredBarrierMessages: unknown[] = [];
-  let pendingToolResultImageParts: unknown[] = [];
-  let mintedIdSeq = 0;
-  const seenWireCallIds = new Set<string>();
-
-  const mintCallId = (): string => {
-    let id = "";
-    do {
-      id = `call_ocx_minted_${++mintedIdSeq}`;
-    } while (seenWireCallIds.has(id));
-    seenWireCallIds.add(id);
-    return id;
-  };
-
-  const releaseDeferredBarriers = (): void => {
-    if (deferredBarrierMessages.length === 0) return;
-    out.push(...deferredBarrierMessages);
-    deferredBarrierMessages = [];
-  };
-
-  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) {
-      out.push({
-        role: "tool",
-        tool_call_id: call.id,
-        content: `[ocx] no tool result was recorded for "${call.name}"; execution status unknown — do not treat this as success, failure, or user-provided input.`,
-      });
-    }
-    pendingToolCalls = [];
-    flushToolResultImages();
-    releaseDeferredBarriers();
-  };
-
-  const nativeOpenAI = isNativeOpenAIChatTarget(provider);
-  // Hoisting a newly appended reminder rewrites the reusable prompt prefix.
-  // Keep this compatibility exception on the destination/model tested with OCG.
-  const chronologicalSystem = parsed.modelId === "deepseek-v4.1-flash"
-    && registryEntryForProviderDestination(provider)?.id === "opencode-go";
-  const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider)
-    ? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice)
-    : undefined;
-  const developerSystemParts = nativeOpenAI || chronologicalSystem
-    ? []
-    : 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) {
-    const wireModelId = provider.modelSuffixBracketStrip
-      ? stripBracketedModelSuffix(parsed.modelId)
-      : parsed.modelId;
-    const sys = identifyRoutedModel(systemParts.join("\n\n"), wireModelId);
-    out.push({ role: "system", content: sys });
-  }
-
-  for (const msg of context.messages) {
-    switch (msg.role) {
-      case "user":
-      case "developer": {
-        const parts = typeof msg.content === "string" ? undefined : msg.content as OcxContentPart[];
-        const hasImages = parts?.some(p => p.type === "image") ?? false;
-        let chatMsg: Record<string, unknown>;
-        if (msg.role === "developer" && !hasImages) {
-          if (!nativeOpenAI && !chronologicalSystem) break;
-          const text = typeof msg.content === "string"
-            ? msg.content
-            : parts!.map(p => (p as OcxTextContent).text).join("");
-          // A non-text timeline part (video, for example) serializes to nothing here.
-          // The generic path drops such a message; the chronological exception must not
-          // turn it into an empty system message that some upstreams reject.
-          if (!nativeOpenAI && text.length === 0) break;
-          chatMsg = { role: nativeOpenAI ? "developer" : "system", content: text };
-        } else if (typeof msg.content === "string") {
-          chatMsg = { role: "user", content: msg.content };
-        } else if (!hasImages) {
-          // A video part has no `text`, so joining it produced "" and the whole message
-          // was dropped: a video-only or text-plus-video turn vanished silently. OpenAI's
-          // Chat Completions wire has no video content part, so state the omission
-          // instead of losing it. Scoped to this adapter's wire, not a claim about video
-          // support in general — native Chat passthrough and Google inline video are
-          // unaffected.
-          chatMsg = {
-            role: "user",
-            content: parts!.map(p => (p.type === "video"
-              ? VIDEO_UNSUPPORTED_MARKER
-              : (p as OcxTextContent).text)).join(""),
-          };
-        } else {
-          const chatParts = parts!.map(p => {
-            if (p.type === "image") {
-              return { type: "image_url", image_url: { url: p.imageUrl, ...(p.detail ? { detail: p.detail } : {}) } };
-            }
-            // Previously this produced { type: "text", text: undefined } for a video
-            // part — a malformed part, worse than a drop because it can fail upstream
-            // schema validation.
-            if (p.type === "video") return { type: "text", text: VIDEO_UNSUPPORTED_MARKER };
-            return { type: "text", text: (p as OcxTextContent).text };
-          });
-          chatMsg = { role: "user", content: chatParts };
-        }
-        if (pendingToolCalls.length > 0) deferredBarrierMessages.push(chatMsg);
-        else out.push(chatMsg);
-        break;
-      }
-      case "assistant": {
-        const aMsg = msg as OcxAssistantMessage;
-        const textParts = aMsg.content.filter(p => p.type === "text") as OcxTextContent[];
-        const thinkingParts = aMsg.content.filter(p => p.type === "thinking") as OcxThinkingContent[];
-        const toolCalls = aMsg.content.filter(p => p.type === "toolCall") as OcxToolCall[];
-        const chatMsg: Record<string, unknown> = { role: "assistant" };
-        if (textParts.length > 0) chatMsg.content = textParts.map(p => p.text).join("");
-        let reasoningContent = thinkingParts.map(p => p.thinking).join("");
-        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 = " ";
-          }
-        }
-        if (reasoningContent.length > 0 && modelInList(provider.preserveReasoningContentModels, parsed.modelId)) {
-          // MiniMax's interleaved-thinking contract requires the structured
-          // reasoning_details array back on the next turn; a reasoning_content
-          // string is the native-format pass-back the docs mark unsupported.
-          if (modelInList(provider.reasoningDetailsModels, parsed.modelId)) {
-            chatMsg.reasoning_details = [reasoningDetailSegmentForWire(reasoningContent)];
-          } else {
-            chatMsg.reasoning_content = reasoningContent;
-          }
-        }
-        const hasReplayedReasoning = chatMsg.reasoning_content !== undefined || chatMsg.reasoning_details !== undefined;
-        if (chatMsg.content === undefined && toolCalls.length === 0 && !hasReplayedReasoning) break;
-        flushPendingToolCalls();
-        const wireToolCalls = toolCalls.map(tc => {
-          let id = tc.id;
-          if (!id) id = mintCallId();
-          else seenWireCallIds.add(id);
-          return { tc, id };
-        });
-        if (wireToolCalls.length > 0) {
-          chatMsg.tool_calls = wireToolCalls.map(({ tc, id }) => ({
-            id,
-            type: "function",
-            function: { name: namespacedToolName(tc.namespace, tc.name), arguments: JSON.stringify(tc.arguments) },
-          }));
-          if (!chatMsg.content) chatMsg.content = emptyAssistantContent(provider);
-        }
-        if (hasReplayedReasoning && chatMsg.content === undefined && chatMsg.tool_calls === undefined) {
-          chatMsg.content = emptyAssistantContent(provider);
-        }
-        out.push(chatMsg);
-        pendingToolCalls = wireToolCalls.map(({ tc, id }) => ({ id, name: namespacedToolName(tc.namespace, tc.name) }));
-        break;
-      }
-      case "toolResult": {
-        let toolCallId = msg.toolCallId;
-        const matchIdx = toolCallId ? pendingToolCalls.findIndex(c => c.id === toolCallId) : -1;
-        if (matchIdx >= 0 && toolCallId) {
-          out.push({
-            role: "tool",
-            tool_call_id: toolCallId,
-            content: toolResultTextForWire(msg.content, provider.annotateEmptyToolOutputs === true),
-          });
-          pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content));
-          pendingToolCalls.splice(matchIdx, 1);
-          if (pendingToolCalls.length === 0) {
-            flushToolResultImages();
-            releaseDeferredBarriers();
-          }
-        } else {
-          if (!toolCallId) toolCallId = `call_orphan_${out.length}`;
-          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);
-          const orphanReasoningFields: Record<string, unknown> = !orphanReasoning
-            ? {}
-            : modelInList(provider.reasoningDetailsModels, parsed.modelId)
-              ? { reasoning_details: [reasoningDetailSegmentForWire(orphanReasoning)] }
-              : { reasoning_content: orphanReasoning };
-          out.push({
-            role: "assistant",
-            content: emptyAssistantContent(provider),
-            ...orphanReasoningFields,
-            tool_calls: [{
-              id: toolCallId,
-              type: "function",
-              function: { name, arguments: "{}" },
-            }],
-          });
-          seenWireCallIds.add(toolCallId);
-          out.push({
-            role: "tool",
-            tool_call_id: toolCallId,
-            content: toolResultTextForWire(msg.content, provider.annotateEmptyToolOutputs === true),
-          });
-          pendingToolResultImageParts.push(...toolResultImageChatParts(msg.content));
-          flushToolResultImages();
-        }
-        break;
-      }
-    }
-  }
-
-  flushPendingToolCalls();
-  releaseDeferredBarriers();
-  return out;
-}
-
-function safeToolName(name: string | undefined): string {
-  const raw = name && name.trim().length > 0 ? name : "tool_result";
-  const sanitized = raw.replace(/[^A-Za-z0-9_-]/g, "_");
-  return sanitized;
-}
-
-const ZEN_SCHEMA_MAP_KEYS = new Set(["properties", "$defs", "definitions"]);
-const ZEN_DROPPED_SCHEMA_KEYS = new Set(["encrypted"]);
-
-function sanitizeZenSchemaMap(value: unknown): unknown {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return sanitizeZenToolParameters(value);
-  const out: Record<string, unknown> = {};
-  for (const [name, child] of Object.entries(value as Record<string, unknown>)) {
-    out[name] = sanitizeZenToolParameters(child);
-  }
-  return out;
-}
-
-function sanitizeZenToolParameters(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(sanitizeZenToolParameters);
-  if (!value || typeof value !== "object") return value;
-  const input = value as Record<string, unknown>;
-  const out: Record<string, unknown> = {};
-  for (const [key, child] of Object.entries(input)) {
-    if (ZEN_DROPPED_SCHEMA_KEYS.has(key)) continue;
-    if (key === "required" && Array.isArray(child) && child.length === 0) continue;
-    if (key === "type" && Array.isArray(child)) {
-      const nonNull = child.filter(entry => entry !== "null");
-      if (child.includes("null")) out.nullable = true;
-      if (nonNull.length > 0) out.type = nonNull[0];
-      continue;
-    }
-    out[key] = ZEN_SCHEMA_MAP_KEYS.has(key) ? sanitizeZenSchemaMap(child) : sanitizeZenToolParameters(child);
-  }
-  return out;
-}
-
-function ensureZenRootObjectSchema(schema: unknown): Record<string, unknown> {
-  const obj = schema && typeof schema === "object" && !Array.isArray(schema)
-    ? schema as Record<string, unknown>
-    : {};
-  const compositionKeys = ["oneOf", "anyOf", "allOf"] as const;
-  const hasComposition = compositionKeys.some(key => Array.isArray(obj[key]));
-  const rootType = obj.type;
-  const rootObjectType = rootType === "object" || (Array.isArray(rootType) && rootType.includes("object"));
-  if (!hasComposition) {
-    const base = sanitizeZenToolParameters(obj) as Record<string, unknown>;
-    return rootObjectType && base.type === "object" ? base : { ...base, type: "object" };
-  }
-
-  const props: Record<string, unknown> = {};
-  const required = new Set<string>();
-  if (obj.properties && typeof obj.properties === "object") {
-    Object.assign(props, sanitizeZenSchemaMap(obj.properties) as Record<string, unknown>);
-  }
-  if (Array.isArray(obj.required)) {
-    for (const entry of obj.required) if (typeof entry === "string") required.add(entry);
-  }
-  for (const key of compositionKeys) {
-    const variants = obj[key];
-    if (!Array.isArray(variants)) continue;
-    const mergeRequired = key === "allOf";
-    for (const variant of variants) {
-      if (!variant || typeof variant !== "object" || Array.isArray(variant)) continue;
-      const rec = variant as Record<string, unknown>;
-      if (rec.properties && typeof rec.properties === "object") {
-        Object.assign(props, sanitizeZenSchemaMap(rec.properties) as Record<string, unknown>);
-      }
-      if (mergeRequired && Array.isArray(rec.required)) {
-        for (const entry of rec.required) if (typeof entry === "string") required.add(entry);
-      }
-    }
-  }
-
-  const merged = sanitizeZenToolParameters(obj) as Record<string, unknown>;
-  delete merged.oneOf;
-  delete merged.anyOf;
-  delete merged.allOf;
-  merged.type = "object";
-  if (Object.keys(props).length > 0) merged.properties = props;
-  if (required.size > 0) merged.required = [...required];
-  return merged;
-}
-
-function shouldSanitizeZenToolParameters(provider: OcxProviderConfig): boolean {
-  const baseUrl = provider.baseUrl.replace(/\/+$/, "");
-  return baseUrl === "https://opencode.ai/zen/v1"
-    || baseUrl === "https://opencode.ai/zen/go/v1";
-}
-
-/** Azure Model Router (and Gemini-in-the-pool) 400s Codex MCP schemas whose root is a union. */
-const AZURE_CHAT_FORBIDDEN_ROOT_KEYS = ["oneOf", "anyOf", "allOf", "enum", "const", "not"] as const;
-
-function isAzureOpenAiChatTarget(provider: OcxProviderConfig): boolean {
-  try {
-    const host = new URL(provider.baseUrl).hostname.toLowerCase();
-    return host.endsWith(".openai.azure.com")
-      || host.endsWith(".cognitiveservices.azure.com")
-      || host.endsWith(".services.ai.azure.com")
-      || host.endsWith(".ai.azure.com");
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Azure Foundry Model Router validates every function schema against the strictest model in
- * the pool (Gemini-shaped): root must be {type:"object"} with no oneOf/anyOf/allOf/enum/
- * const/not. Codex App MCP tools such as mcp__codex_app__automation_update ship a root
- * union, which 400s the whole turn. Flatten like Zen, then strip leftover forbidden keys.
- */
-function sanitizeAzureChatToolParameters(parameters: unknown): Record<string, unknown> {
-  const root = ensureZenRootObjectSchema(parameters);
-  for (const key of AZURE_CHAT_FORBIDDEN_ROOT_KEYS) delete root[key];
-  root.type = "object";
-  if (!root.properties || typeof root.properties !== "object" || Array.isArray(root.properties)) {
-    root.properties = {};
-  }
-  return root;
-}
-
-// Moonshot validates function schemas against a draft-07 reading of `$ref`, where the
-// keyword stands alone and siblings are ignored. It rejects the whole request rather
-// than ignoring them: "not a valid moonshot flavored json schema ... when using $ref,
-// type should be defined in the referenced schema instead of the parent schema".
-const MOONSHOT_SCHEMA_HOSTNAMES = new Set([
-  "api.kimi.com",
-  "api.moonshot.ai",
-  "api.moonshot.cn",
-]);
-
-function isMoonshotSchemaTarget(provider: OcxProviderConfig): boolean {
-  try {
-    return MOONSHOT_SCHEMA_HOSTNAMES.has(new URL(provider.baseUrl).hostname);
-  } catch {
-    return false;
-  }
-}
-
-const VOLCENGINE_ARK_HOSTNAMES = new Set([
-  "ark.cn-beijing.volces.com",
-  "ark.ap-southeast.volces.com",
-]);
-
-function isVolcengineArkPaygChatTarget(provider: OcxProviderConfig): boolean {
-  try {
-    const url = new URL(provider.baseUrl);
-    const pathname = url.pathname.replace(/\/+$/, "") || "/";
-    return VOLCENGINE_ARK_HOSTNAMES.has(url.hostname) && pathname === "/api/v3";
-  } catch {
-    return false;
-  }
-}
-
-function emptyAssistantContent(provider: OcxProviderConfig): string | { type: "text"; text: string }[] {
-  return isVolcengineArkPaygChatTarget(provider) ? [{ type: "text", text: "" }] : "";
-}
-
-function ensureRootObjectType(parameters: unknown): Record<string, unknown> {
-  if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
-    return { type: "object", properties: {} };
-  }
-  const obj = parameters as Record<string, unknown>;
-  if (obj.type === "object") return obj;
-  return { ...obj, type: "object" };
-}
-
-function isXaiObjectSchema(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-/**
- * JSON Schema 2020-12 makes `$ref` an in-place applicator: siblings stay in force and are
- * combined with the referenced schema. Moonshot enforces the older draft-07 reading where
- * `$ref` must stand alone, and 400s the entire request when a node carries both. Codex's own
- * deferred tool catalog emits exactly that shape (zod-to-json-schema deduplicates into
- * `$defs.__schema*` nodes that keep `type`/`minLength`/`format` beside the `$ref`), so the
- * schema is not something a user can fix from configuration — see issue #2673.
- *
- * Inline the referenced schema underneath the node's own keywords, which is what 2020-12 says
- * the node means, then drop `$ref`. Constraints reach the model instead of being stripped.
- * The `$defs` bag is preserved: a bare `$ref` (no siblings) is already legal for Moonshot and
- * is left pointing at its definition rather than expanded, which keeps recursive schemas finite.
- */
-function moonshotRefTargetKeys(node: Record<string, unknown>): string[] {
-  return Object.keys(node).filter(key => key !== "$ref");
-}
-
-/**
- * Inlining duplicates the target, so a schema referencing one large definition from many
- * sibling-carrying nodes can multiply. Bound the total expansions and fall back to a bare
- * `$ref` once the budget is spent: still valid for Moonshot, just without the node's own
- * narrowing keywords. Mirrors the node budget in google-tool-schema.ts.
- */
-const MOONSHOT_MAX_REF_EXPANSIONS = 512;
-
-/**
- * Expansion count alone does not bound the walk: a deeply nested ref-free schema, or one
- * large definition repeated across many nodes, still recurses to exhaustion or amplifies the
- * emitted output. Depth and node budgets close both, and mirror google-tool-schema.ts.
- */
-const MOONSHOT_MAX_SCHEMA_DEPTH = 64;
-const MOONSHOT_MAX_SCHEMA_NODES = 4_096;
-
-/**
- * Assertion keywords whose meaning under a `$ref` is CONJUNCTION, not replacement. A node
- * carrying `required: ["b"]` beside a target requiring `["a"]` means both are required;
- * letting the sibling win emitted a schema that no longer described the tool.
- */
-function unionRequired(target: unknown, sibling: unknown): unknown {
-  if (!Array.isArray(target) || !Array.isArray(sibling)) return sibling;
-  const seen = new Set<unknown>();
-  const out: unknown[] = [];
-  for (const name of [...target, ...sibling]) {
-    if (seen.has(name)) continue;
-    seen.add(name);
-    out.push(name);
-  }
-  return out;
-}
-
-/**
- * Keywords whose values are DATA, not schemas.
- *
- * Recursing into them rewrote user data: an `enum` listing a literal object that happens
- * to carry a `"$ref"` string had that key stripped as if it were a schema reference, so a
- * value the tool declared as legal silently changed shape. These are copied through.
- */
-const MOONSHOT_DATA_VALUED_KEYWORDS = new Set(["enum", "const", "default", "examples"]);
-
-/**
- * Numeric assertions whose intersection is a bound, and which direction tightens.
- *
- * `$ref` under 2020-12 is an in-place applicator: the node and its target BOTH apply, so
- * the emitted schema must be their INTERSECTION. The previous code overwrote the target
- * with the node and called that "the narrower reading", which holds only when the node
- * happens to be narrower. A node declaring `minLength: 1` beside a target declaring
- * `minLength: 5` shipped `minLength: 1` - a contract weaker than either side asked for,
- * emitted silently, which is the same failure mode the `required` composition fixed for
- * set-valued keywords.
- *
- * "max" means the surviving value is the larger of the two (lower bounds), "min" the
- * smaller (upper bounds). A keyword absent from this table keeps the overwrite: for
- * `type`, `format`, `description` and friends there is no ordering to intersect along,
- * and the node is the more specific statement.
- */
-const MOONSHOT_BOUND_KEYWORDS: Record<string, "max" | "min"> = {
-  minLength: "max",
-  minItems: "max",
-  minProperties: "max",
-  minimum: "max",
-  exclusiveMinimum: "max",
-  maxLength: "min",
-  maxItems: "min",
-  maxProperties: "min",
-  maximum: "min",
-  exclusiveMaximum: "min",
-};
-
-/**
- * Intersect one numeric bound. Either side being absent or non-finite yields the other,
- * because an unstated bound constrains nothing - returning `undefined` there would drop
- * a constraint the remaining side genuinely made.
- */
-function intersectBound(target: unknown, sibling: unknown, direction: "max" | "min"): unknown {
-  const a = typeof target === "number" && Number.isFinite(target) ? target : null;
-  const b = typeof sibling === "number" && Number.isFinite(sibling) ? sibling : null;
-  if (a === null) return b === null ? sibling : sibling;
-  if (b === null) return target;
-  return direction === "max" ? Math.max(a, b) : Math.min(a, b);
-}
-
-/**
- * Compose two `properties` maps. A property named in BOTH the referenced target and the
- * node is the same conjunction problem `required` had: letting the sibling win discards
- * the target's constraints for that member. Merge the two member schemas so neither side
- * loses its keywords. Shared member bounds are the same conjunction one level down,
- * and nested object members recurse through this helper instead of replacing the target.
- */
-function composeProperties(
-  target: Record<string, unknown>,
-  sibling: Record<string, unknown>,
-): Record<string, unknown> {
-  const combined: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-  for (const [name, sub] of Object.entries(target)) combined[name] = sub;
-  for (const [name, sub] of Object.entries(sibling)) {
-    const existing = combined[name];
-    if (isXaiObjectSchema(existing) && isXaiObjectSchema(sub)) {
-      const member: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-      for (const [k, v] of Object.entries(existing)) member[k] = v;
-      for (const [k, v] of Object.entries(sub)) {
-        if (k === "required") {
-          member[k] = unionRequired(member[k], v);
-          continue;
-        }
-        if (k === "properties" && isXaiObjectSchema(member[k]) && isXaiObjectSchema(v)) {
-          member[k] = composeProperties(member[k] as Record<string, unknown>, v);
-          continue;
-        }
-        const boundDirection = MOONSHOT_BOUND_KEYWORDS[k];
-        if (boundDirection && k in member) {
-          member[k] = intersectBound(member[k], v, boundDirection);
-          continue;
-        }
-        member[k] = v;
-      }
-      combined[name] = member;
-      continue;
-    }
-    combined[name] = sub;
-  }
-  return combined;
-}
-
-interface MoonshotNormalizeState {
-  activeRefs: Set<string>;
-  remainingExpansions: number;
-  remainingNodes: number;
-}
-
-function normalizeMoonshotSchemaNode(
-  node: unknown,
-  root: Record<string, unknown>,
-  state: MoonshotNormalizeState,
-  depth = 0,
-): unknown {
-  if (Array.isArray(node)) {
-    if (depth >= MOONSHOT_MAX_SCHEMA_DEPTH) return [];
-    return node.map(item => normalizeMoonshotSchemaNode(item, root, state, depth + 1));
-  }
-  if (!isXaiObjectSchema(node)) return node;
-
-  // Fail closed for this node rather than emitting a partially weakened schema: an empty
-  // object is the one shape that asserts nothing it cannot back up.
-  if (depth >= MOONSHOT_MAX_SCHEMA_DEPTH || state.remainingNodes <= 0) return {};
-  state.remainingNodes -= 1;
-
-  const ref = node.$ref;
-  const hasSiblings = moonshotRefTargetKeys(node).length > 0;
-
-  if (typeof ref === "string" && hasSiblings) {
-    // A cycle cannot be inlined. Keeping the bare `$ref` is the lossy-but-valid fallback:
-    // Moonshot accepts it, and the alternative (dropping the ref) would erase the recursion.
-    if (state.activeRefs.has(ref) || state.remainingExpansions <= 0) return { $ref: ref };
-
-    const target = lookupLocalJsonPointer(root, ref);
-    if (isXaiObjectSchema(target)) {
-      state.remainingExpansions -= 1;
-      state.activeRefs.add(ref);
-      const resolvedTarget = normalizeMoonshotSchemaNode(target, root, state, depth + 1);
-      state.activeRefs.delete(ref);
-      const merged: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-      if (isXaiObjectSchema(resolvedTarget)) {
-        for (const [key, value] of Object.entries(resolvedTarget)) merged[key] = value;
-      }
-      // "Alongside the target" is conjunction, not replacement. For most keywords the node
-      // narrows the target and overwriting is the narrower reading, but `required` and
-      // `properties` are set-valued: letting the sibling win DROPPED the target's own
-      // members, so a tool requiring `a` beside a node requiring `b` shipped requiring only
-      // `b`. Those two compose; everything else keeps the narrowing overwrite.
-      for (const [key, value] of Object.entries(node)) {
-        if (key === "$ref") continue;
-        if (MOONSHOT_DATA_VALUED_KEYWORDS.has(key)) {
-          merged[key] = value;
-          continue;
-        }
-        const normalized = normalizeMoonshotSchemaNode(value, root, state, depth + 1);
-        if (key === "required") {
-          merged[key] = unionRequired(merged[key], normalized);
-          continue;
-        }
-        if (key === "properties" && isXaiObjectSchema(merged[key]) && isXaiObjectSchema(normalized)) {
-          merged[key] = composeProperties(merged[key] as Record<string, unknown>, normalized);
-          continue;
-        }
-        // Numeric bounds intersect rather than overwrite: both the node and its target
-        // apply, so the surviving bound is the stricter of the two in whichever direction
-        // that keyword tightens.
-        const boundDirection = MOONSHOT_BOUND_KEYWORDS[key];
-        if (boundDirection && key in merged) {
-          merged[key] = intersectBound(merged[key], normalized, boundDirection);
-          continue;
-        }
-        merged[key] = normalized;
-      }
-      return merged;
-    }
-
-    // Unresolvable pointer: a remote ref, a malformed path, or a non-object target. Dropping
-    // the ref and keeping the siblings silently discards whatever the reference constrained,
-    // which is the one outcome we cannot detect downstream. A bare `$ref` is lossy in the
-    // other direction - it loses the node's own keywords - but it preserves the identity of
-    // what was asked for, and Moonshot accepts it.
-    return { $ref: ref };
-  }
-
-  const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-  for (const [key, value] of Object.entries(node)) {
-    out[key] = key === "$ref" || MOONSHOT_DATA_VALUED_KEYWORDS.has(key)
-      ? value
-      : normalizeMoonshotSchemaNode(value, root, state, depth + 1);
-  }
-  return out;
-}
-
-function normalizeMoonshotToolParameters(parameters: unknown): Record<string, unknown> {
-  const rooted = ensureRootObjectType(parameters);
-  const normalized = normalizeMoonshotSchemaNode(rooted, rooted, {
-    activeRefs: new Set<string>(),
-    remainingExpansions: MOONSHOT_MAX_REF_EXPANSIONS,
-    remainingNodes: MOONSHOT_MAX_SCHEMA_NODES,
-  });
-  return isXaiObjectSchema(normalized) ? normalized : rooted;
-}
-
-function toolsToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] | undefined {
-  if (!parsed.context.tools || parsed.context.tools.length === 0) return undefined;
-  const tools = parsed.context.tools.filter(toolChoiceToolPredicate(parsed.options.toolChoice, parsed.context.tools));
-  if (tools.length === 0) return undefined;
-  const xaiTarget = isXaiSchemaTarget(provider);
-  const moonshotTarget = !xaiTarget && isMoonshotSchemaTarget(provider);
-  const formatted = tools.flatMap(t => {
-    const normalized = xaiTarget
-      ? normalizeXaiToolParameters(t.parameters)
-      : moonshotTarget
-        ? normalizeMoonshotToolParameters(t.parameters)
-        : ensureRootObjectType(t.parameters);
-    const parameters = stripUnicodePropertyPatterns(stripResponsesOnlyEncryptedMarker(normalized));
-
-    if (parameters === undefined) return [];
-    return [{
-      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;
-}
-
-function toolsToChatFormatForProvider(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] | undefined {
-  const base = toolsToChatFormat(parsed, provider);
-  const azureChat = isAzureOpenAiChatTarget(provider);
-  const zenChat = shouldSanitizeZenToolParameters(provider);
-  if (!base || (!zenChat && !azureChat)) return base;
-  return base.map(tool => {
-    if (!tool || typeof tool !== "object") return tool;
-    const functionDef = (tool as { function?: Record<string, unknown> }).function;
-    if (!functionDef || typeof functionDef !== "object") return tool;
-    const parameters = azureChat
-      ? sanitizeAzureChatToolParameters(functionDef.parameters ?? {})
-      : ensureZenRootObjectSchema(functionDef.parameters ?? {});
-    const nextFunction: Record<string, unknown> = { ...functionDef, parameters };
-    // strict: true plus a flattened schema is rejected by Gemini-in-the-pool routers.
-    if (azureChat) delete nextFunction.strict;
-    return {
-      ...tool,
-      function: nextFunction,
-    };
-  });
-}
-
-function toolChoiceToChatFormat(
-  tc: OcxParsedRequest["options"]["toolChoice"],
-  tools: OcxParsedRequest["context"]["tools"],
-  provider: OcxProviderConfig,
-): unknown {
-  if (!tc) return undefined;
-  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;
-}
-
-function usageFromOpenAIChat(usage: Record<string, unknown> | undefined): OcxUsage | undefined {
-  if (!usage) return undefined;
-  const promptDetails = usage.prompt_tokens_details as Record<string, number> | undefined;
-  const completionDetails = usage.completion_tokens_details as Record<string, number> | undefined;
-  return {
-    inputTokens: typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : 0,
-    outputTokens: typeof usage.completion_tokens === "number" ? usage.completion_tokens : 0,
-    ...(promptDetails?.cached_tokens !== undefined ? { cachedInputTokens: promptDetails.cached_tokens } : {}),
-    ...(completionDetails?.reasoning_tokens !== undefined ? { reasoningOutputTokens: completionDetails.reasoning_tokens } : {}),
-  };
-}
+import {
+  isInvalidStreamStringField,
+  isRecord,
+  logInvalidToolCalls,
+  type InvalidToolCallDiagnostic,
+} from "./openai-chat/tool-call-validation";
+import {
+  invalidChoicesEvent,
+  invalidToolCallsEvent,
+  reasoningDetailSegmentsFrom,
+  reasoningTextFrom,
+  stopReasonFor,
+  unnamedToolCallEvent,
+  usageFromOpenAIChat,
+} from "./openai-chat/response-events";
+import {
+  formatOpenAIChatErrorBody,
+  OpenAIChatError,
+  unwrapChatCompletionPayload,
+  upstreamErrorEvent,
+} from "./openai-chat/errors";
+import { messagesToChatFormat } from "./openai-chat/messages";
+import { isNativeOpenAIChatTarget, openAIChatTransport, stripBracketedModelSuffix } from "./openai-chat/wire";
+import { toolChoiceToChatFormat, toolsToChatFormatForProvider } from "./openai-chat/tool-schema";
+
+export { stripBracketedModelSuffix } from "./openai-chat/wire";
+export { buildOpenAIChatPassthroughRequest } from "./openai-chat/passthrough";
+export { formatOpenAIChatErrorBody } from "./openai-chat/errors";
 
 function resolveMaxTokens(provider: OcxProviderConfig, parsed: OcxParsedRequest): number | undefined {
   return parsed.options.maxOutputTokens