@seqyuan/annodex 0.1.11 → 0.1.12

package/lib/codex-compat-proxy.ts

@@ -0,0 +1,1603 @@
+/**
+ * Codex Compat Proxy - Responses API <-> Chat Completions translation.
+ *
+ * Codex CLI speaks OpenAI Responses. Many third-party providers used by
+ * annodex, including DeepSeek-style and relay providers, expose Chat
+ * Completions. This in-process proxy keeps Codex on Responses while translating
+ * the upstream request/response shape.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from "http";
+import { request as httpRequest } from "http";
+import { request as httpsRequest } from "https";
+import { randomBytes } from "crypto";
+import { URL } from "url";
+import type { ReasoningConfig } from "./provider-api";
+
+interface ProxyOptions {
+  targetUrl: string;
+  apiKey: string;
+  defaultThinking?: string;
+  /** Provider-level thinking/reasoning parameter mapping override. */
+  reasoningConfig?: ReasoningConfig;
+  port?: number;
+}
+
+type JsonObject = Record<string, unknown>;
+
+interface ResponsesRequestBody extends JsonObject {
+  model?: string;
+  instructions?: unknown;
+  input?: unknown;
+  tools?: JsonObject[];
+  tool_choice?: unknown;
+  stream?: boolean;
+  reasoning?: { enabled?: boolean; effort?: string } | null;
+  temperature?: number;
+  top_p?: number;
+  max_output_tokens?: number;
+  max_tokens?: number;
+  max_completion_tokens?: number;
+  stop?: string | string[];
+  frequency_penalty?: number;
+  presence_penalty?: number;
+  parallel_tool_calls?: boolean;
+}
+
+interface ChatMessage extends JsonObject {
+  role: string;
+  content: unknown;
+  tool_calls?: ChatToolCall[];
+  tool_call_id?: string;
+  reasoning_content?: string;
+}
+
+interface ChatToolCall {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+interface ChatRequestBody extends JsonObject {
+  model: string;
+  messages: ChatMessage[];
+  stream?: boolean;
+  stream_options?: JsonObject;
+  tools?: ChatTool[];
+  tool_choice?: unknown;
+  thinking?: { type: string };
+  enable_thinking?: boolean;
+  reasoning_effort?: string;
+  temperature?: number;
+  top_p?: number;
+  max_tokens?: number;
+  max_completion_tokens?: number;
+  stop?: string | string[];
+  frequency_penalty?: number;
+  presence_penalty?: number;
+  parallel_tool_calls?: boolean;
+}
+
+interface ChatTool {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters: unknown;
+  };
+}
+
+type ToolKind = "function" | "custom";
+
+interface ToolSpec {
+  chatName: string;
+  originalName: string;
+  namespace?: string;
+  kind: ToolKind;
+}
+
+interface ToolContext {
+  specs: Map<string, ToolSpec>;
+}
+
+interface StreamToolCallState {
+  outputIndex: number;
+  itemId: string;
+  callId: string;
+  name: string;
+  arguments: string;
+  done: boolean;
+}
+
+type InlineThinkMode = "detecting" | "reasoning" | "text";
+
+interface SSEStreamState {
+  responseId: string;
+  messageId: string;
+  reasoningId: string;
+  createdAt: number;
+  model: string;
+  text: string;
+  textStarted: boolean;
+  contentStarted: boolean;
+  messageOutputIndex: number | null;
+  reasoningText: string;
+  reasoningStarted: boolean;
+  reasoningDone: boolean;
+  reasoningOutputIndex: number | null;
+  inlineThinkMode: InlineThinkMode;
+  inlineThinkBuffer: string;
+  nextOutputIndex: number;
+  toolCalls: Array<StreamToolCallState | undefined>;
+  outputItems: Array<{ outputIndex: number; item: JsonObject }>;
+  finalUsage: JsonObject | null;
+  finishReason: string | null;
+  toolContext: ToolContext;
+}
+
+type ThinkingEffort = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+interface ThinkingMapping {
+  supportsEffort: boolean;
+  effortMap: Record<ThinkingEffort, string | null>;
+  thinkingParam?: "thinking" | "enable_thinking";
+  effortParam?: "reasoning_effort" | "reasoning.effort";
+}
+
+const THINK_OPEN_TAG = "<think>";
+const THINK_CLOSE_TAG = "</think>";
+const ERROR_BODY_PREVIEW_LIMIT = 1024;
+
+const EXTRA_CHAT_PASSTHROUGH_FIELDS = [
+  "logit_bias",
+  "logprobs",
+  "metadata",
+  "n",
+  "response_format",
+  "seed",
+  "service_tier",
+  "top_logprobs",
+  "user",
+] as const;
+
+function buildThinkingMapping(config: ReasoningConfig): ThinkingMapping {
+  const mode = config.effortValueMode ?? "generic";
+  let effortMap: Record<ThinkingEffort, string | null>;
+  switch (mode) {
+    case "deepseek":
+      effortMap = { off: null, minimal: "high", low: "high", medium: "high", high: "high", xhigh: "max" };
+      break;
+    case "glm":
+      effortMap = { off: null, minimal: "low", low: "low", medium: "medium", high: "high", xhigh: "high" };
+      break;
+    case "openrouter":
+      effortMap = { off: null, minimal: "minimal", low: "low", medium: "medium", high: "high", xhigh: "xhigh" };
+      break;
+    default:
+      effortMap = { off: null, minimal: "enabled", low: "enabled", medium: "enabled", high: "enabled", xhigh: "enabled" };
+      break;
+  }
+  return {
+    supportsEffort: config.supportsEffort ?? (config.effortParam !== "none" && config.effortParam !== null),
+    thinkingParam: config.thinkingParam ?? undefined,
+    effortParam: config.effortParam === null || config.effortParam === "none" ? undefined : (config.effortParam ?? undefined),
+    effortMap,
+  };
+}
+
+const THINKING_MAPPINGS: Record<string, ThinkingMapping> = {
+  deepseek: {
+    supportsEffort: true,
+    thinkingParam: "thinking",
+    effortParam: "reasoning_effort",
+    effortMap: {
+      off: null,
+      minimal: "high",
+      low: "high",
+      medium: "high",
+      high: "high",
+      xhigh: "max",
+    },
+  },
+  kimi: {
+    supportsEffort: false,
+    thinkingParam: "thinking",
+    effortMap: {
+      off: null,
+      minimal: "enabled",
+      low: "enabled",
+      medium: "enabled",
+      high: "enabled",
+      xhigh: "enabled",
+    },
+  },
+  qwen: {
+    supportsEffort: false,
+    thinkingParam: "enable_thinking",
+    effortMap: {
+      off: null,
+      minimal: "enabled",
+      low: "enabled",
+      medium: "enabled",
+      high: "enabled",
+      xhigh: "enabled",
+    },
+  },
+  glm: {
+    supportsEffort: true,
+    thinkingParam: "thinking",
+    effortParam: "reasoning_effort",
+    effortMap: {
+      off: null,
+      minimal: "low",
+      low: "low",
+      medium: "medium",
+      high: "high",
+      xhigh: "high",
+    },
+  },
+  openrouter: {
+    supportsEffort: true,
+    effortParam: "reasoning.effort",
+    effortMap: {
+      off: null,
+      minimal: "minimal",
+      low: "low",
+      medium: "medium",
+      high: "high",
+      xhigh: "xhigh",
+    },
+  },
+  generic: {
+    supportsEffort: false,
+    thinkingParam: "thinking",
+    effortMap: {
+      off: null,
+      minimal: "enabled",
+      low: "enabled",
+      medium: "enabled",
+      high: "enabled",
+      xhigh: "enabled",
+    },
+  },
+};
+
+function isRecord(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function canonicalJsonString(value: unknown): string {
+  if (typeof value === "string") return canonicalizeJsonStringIfParseable(value);
+  try {
+    return JSON.stringify(value ?? "");
+  } catch {
+    return String(value ?? "");
+  }
+}
+
+function canonicalizeJsonStringIfParseable(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return value;
+  try {
+    return JSON.stringify(JSON.parse(trimmed));
+  } catch {
+    return value;
+  }
+}
+
+function appendText(existing: string | undefined, text: string | undefined): string | undefined {
+  const trimmed = text?.trim();
+  if (!trimmed) return existing;
+  if (!existing) return trimmed;
+  if (existing.includes(trimmed)) return existing;
+  return `${existing}\n\n${trimmed}`;
+}
+
+function instructionText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (isRecord(part)) return stringField(part.text);
+        return undefined;
+      })
+      .filter((part): part is string => Boolean(part))
+      .join("\n\n");
+  }
+  return "";
+}
+
+function contentToChatContent(content: unknown): unknown {
+  if (content === null || typeof content === "string") return content;
+  if (!Array.isArray(content)) return content;
+
+  const textParts: string[] = [];
+  const richParts: JsonObject[] = [];
+  let hasNonText = false;
+
+  for (const part of content) {
+    if (!isRecord(part)) continue;
+    const type = stringField(part.type) ?? "";
+    if (type === "input_text" || type === "output_text" || type === "text") {
+      const text = stringField(part.text);
+      if (text) {
+        textParts.push(text);
+        richParts.push({ type: "text", text });
+      }
+      continue;
+    }
+    if (type === "refusal") {
+      const text = stringField(part.refusal);
+      if (text) textParts.push(text);
+      continue;
+    }
+    if (type === "input_image" && part.image_url) {
+      hasNonText = true;
+      const imageUrl = isRecord(part.image_url) ? part.image_url : { url: String(part.image_url) };
+      richParts.push({ type: "image_url", image_url: imageUrl });
+    }
+  }
+
+  if (!hasNonText) return textParts.join("\n");
+  return richParts;
+}
+
+function normalizeRole(role: unknown): "system" | "user" | "assistant" | "tool" {
+  const normalized = typeof role === "string" ? role.trim().toLowerCase() : "user";
+  if (normalized === "system" || normalized === "developer") return "system";
+  if (normalized === "assistant") return "assistant";
+  if (normalized === "tool") return "tool";
+  return "user";
+}
+
+function normalizeParameters(value: unknown): unknown {
+  const schema: JsonObject = isRecord(value) ? { ...value } : {};
+  if (!schema.type) schema.type = "object";
+  if (schema.type === "object") {
+    if (!isRecord(schema.properties)) schema.properties = {};
+    if (!Array.isArray(schema.required)) schema.required = [];
+  }
+  return schema;
+}
+
+function customToolParameters(): JsonObject {
+  return {
+    type: "object",
+    properties: {
+      input: { type: "string" },
+    },
+    required: ["input"],
+    additionalProperties: false,
+  };
+}
+
+function flattenNamespaceToolName(namespace: string, name: string): string {
+  if (!namespace) return name;
+  if (!name) return namespace;
+  if (namespace.endsWith("__") || name.startsWith("__")) return `${namespace}${name}`;
+  return `${namespace}__${name}`;
+}
+
+function combineDescriptions(parent: string | undefined, child: string | undefined): string | undefined {
+  const a = parent?.trim() ?? "";
+  const b = child?.trim() ?? "";
+  if (!a && !b) return undefined;
+  if (!a) return b;
+  if (!b) return a;
+  return `${a}\n\n${b}`;
+}
+
+function buildToolContext(tools: unknown): ToolContext {
+  const context: ToolContext = { specs: new Map() };
+  if (!Array.isArray(tools)) return context;
+
+  const addSpec = (spec: ToolSpec) => {
+    if (!spec.chatName) return;
+    context.specs.set(spec.chatName, spec);
+  };
+
+  for (const tool of tools) {
+    if (!isRecord(tool)) continue;
+    const type = stringField(tool.type) ?? "function";
+    if (type === "namespace") {
+      const namespace = stringField(tool.name) ?? "";
+      const children = Array.isArray(tool.tools) ? tool.tools : [];
+      for (const child of children) {
+        if (!isRecord(child)) continue;
+        const fn = isRecord(child.function) ? child.function : undefined;
+        const name = stringField(child.name) ?? stringField(fn?.name);
+        if (!name) continue;
+        const chatName = flattenNamespaceToolName(namespace, name);
+        addSpec({ chatName, originalName: name, namespace, kind: "function" });
+      }
+      continue;
+    }
+
+    const fn = isRecord(tool.function) ? tool.function : undefined;
+    const name =
+      stringField(tool.name)
+      ?? stringField(fn?.name)
+      ?? (type !== "function" ? type : undefined);
+    if (!name) continue;
+    addSpec({
+      chatName: name,
+      originalName: name,
+      kind: type === "custom" ? "custom" : "function",
+    });
+  }
+
+  return context;
+}
+
+function responsesToolsToChatTools(tools: unknown, context: ToolContext): ChatTool[] {
+  if (!Array.isArray(tools)) return [];
+  const converted: ChatTool[] = [];
+  const seen = new Set<string>();
+
+  const addTool = (chatName: string, description: string | undefined, parameters: unknown) => {
+    if (!chatName || seen.has(chatName)) return;
+    seen.add(chatName);
+    converted.push({
+      type: "function",
+      function: {
+        name: chatName,
+        ...(description ? { description } : {}),
+        parameters,
+      },
+    });
+  };
+
+  for (const tool of tools) {
+    if (!isRecord(tool)) continue;
+    const type = stringField(tool.type) ?? "function";
+    if (type === "namespace") {
+      const namespace = stringField(tool.name) ?? "";
+      const namespaceDescription = stringField(tool.description);
+      const children = Array.isArray(tool.tools) ? tool.tools : [];
+      for (const child of children) {
+        if (!isRecord(child)) continue;
+        const fn = isRecord(child.function) ? child.function : undefined;
+        const name = stringField(child.name) ?? stringField(fn?.name);
+        if (!name) continue;
+        const chatName = flattenNamespaceToolName(namespace, name);
+        const description = combineDescriptions(namespaceDescription, stringField(child.description) ?? stringField(fn?.description));
+        const parameters = child.parameters ?? fn?.parameters ?? child.input_schema ?? child.schema;
+        addTool(chatName, description, normalizeParameters(parameters));
+      }
+      continue;
+    }
+
+    const fn = isRecord(tool.function) ? tool.function : undefined;
+    const name =
+      stringField(tool.name)
+      ?? stringField(fn?.name)
+      ?? (type !== "function" ? type : undefined);
+    if (!name) continue;
+
+    const spec = context.specs.get(name);
+    const description = stringField(tool.description) ?? stringField(fn?.description);
+    const parameters = spec?.kind === "custom"
+      ? customToolParameters()
+      : normalizeParameters(tool.parameters ?? fn?.parameters ?? tool.input_schema ?? tool.schema);
+    addTool(name, description, parameters);
+  }
+
+  return converted;
+}
+
+function responsesToolChoiceToChat(toolChoice: unknown, context: ToolContext): unknown {
+  if (typeof toolChoice === "string") return toolChoice;
+  if (!isRecord(toolChoice)) return toolChoice;
+
+  const type = stringField(toolChoice.type);
+  if (type === "auto" || type === "none" || type === "required") return type;
+
+  const fn = isRecord(toolChoice.function) ? toolChoice.function : undefined;
+  const namespace = stringField(toolChoice.namespace) ?? stringField(fn?.namespace) ?? "";
+  const name = stringField(toolChoice.name) ?? stringField(fn?.name);
+  if (!name) return undefined;
+  const chatName = namespace ? flattenNamespaceToolName(namespace, name) : name;
+  if (!context.specs.has(chatName) && !context.specs.has(name)) return undefined;
+  return { type: "function", function: { name: chatName } };
+}
+
+function mapToolNameForChat(item: JsonObject, context: ToolContext): string {
+  const name = stringField(item.name) ?? "unknown_tool";
+  const namespace = stringField(item.namespace) ?? "";
+  const chatName = namespace ? flattenNamespaceToolName(namespace, name) : name;
+  if (context.specs.has(chatName)) return chatName;
+  return name;
+}
+
+function extractReasoningText(value: unknown): string | undefined {
+  if (!isRecord(value)) return undefined;
+
+  const direct = stringField(value.reasoning_content)
+    ?? stringField(value.reasoning)
+    ?? stringField(value.text);
+  if (direct) return direct;
+
+  const summary = value.summary;
+  if (Array.isArray(summary)) {
+    const parts = summary
+      .map((part) => isRecord(part) ? stringField(part.text) ?? stringField(part.summary) : undefined)
+      .filter((part): part is string => Boolean(part));
+    if (parts.length) return parts.join("\n\n");
+  }
+
+  const details = value.reasoning_details;
+  if (Array.isArray(details)) {
+    const parts: string[] = [];
+    for (const detail of details) {
+      if (!isRecord(detail)) continue;
+      const summaryText = stringField(detail.summary) ?? stringField(detail.text);
+      if (summaryText) parts.push(summaryText);
+      if (Array.isArray(detail.parts)) {
+        for (const part of detail.parts) {
+          if (isRecord(part)) {
+            const text = stringField(part.text);
+            if (text) parts.push(text);
+          }
+        }
+      }
+    }
+    if (parts.length) return parts.join("\n\n");
+  }
+
+  return undefined;
+}
+
+function attachToolCallToAssistant(
+  messages: ChatMessage[],
+  call: ChatToolCall,
+  reasoning: string | undefined,
+  forceReasoningPlaceholder: boolean,
+) {
+  const last = messages[messages.length - 1];
+  const canAttach = last?.role === "assistant" && !last.tool_call_id;
+  const target = canAttach
+    ? last
+    : (() => {
+        const message: ChatMessage = { role: "assistant", content: null };
+        messages.push(message);
+        return message;
+      })();
+
+  target.tool_calls = [...(target.tool_calls ?? []), call];
+  if (!target.reasoning_content?.trim() && (reasoning?.trim() || forceReasoningPlaceholder)) {
+    target.reasoning_content = reasoning?.trim() || "tool call";
+  }
+}
+
+function functionCallFromResponsesItem(item: JsonObject, context: ToolContext): ChatToolCall | null {
+  const callId = stringField(item.call_id) ?? stringField(item.id);
+  if (!callId) return null;
+  const name = mapToolNameForChat(item, context);
+  const args = canonicalJsonString(item.arguments ?? {});
+  return { id: callId, type: "function", function: { name, arguments: args } };
+}
+
+function customToolCallFromResponsesItem(item: JsonObject, context: ToolContext): ChatToolCall | null {
+  const callId = stringField(item.call_id) ?? stringField(item.id);
+  if (!callId) return null;
+  const name = mapToolNameForChat(item, context);
+  const input = item.input ?? item.arguments ?? "";
+  const args = typeof input === "string"
+    ? JSON.stringify({ input })
+    : canonicalJsonString(input);
+  return { id: callId, type: "function", function: { name, arguments: args } };
+}
+
+function appendResponsesInput(
+  input: unknown,
+  messages: ChatMessage[],
+  context: ToolContext,
+  forceReasoningPlaceholder: boolean,
+) {
+  const items = typeof input === "string" ? [input] : Array.isArray(input) ? input : isRecord(input) ? [input] : [];
+  let pendingReasoning: string | undefined;
+  let lastReasoning: string | undefined;
+
+  for (const item of items) {
+    if (typeof item === "string") {
+      messages.push({ role: "user", content: item });
+      pendingReasoning = undefined;
+      continue;
+    }
+    if (!isRecord(item)) continue;
+
+    const type = stringField(item.type);
+    if (type === "reasoning") {
+      pendingReasoning = appendText(pendingReasoning, extractReasoningText(item));
+      lastReasoning = appendText(lastReasoning, extractReasoningText(item));
+      continue;
+    }
+
+    if (type === "function_call") {
+      const call = functionCallFromResponsesItem(item, context);
+      if (call) {
+        const reasoning = appendText(pendingReasoning, extractReasoningText(item)) ?? lastReasoning;
+        attachToolCallToAssistant(messages, call, reasoning, forceReasoningPlaceholder);
+        pendingReasoning = undefined;
+      }
+      continue;
+    }
+
+    if (type === "custom_tool_call" || type === "tool_search_call") {
+      const call = customToolCallFromResponsesItem(item, context);
+      if (call) {
+        const reasoning = appendText(pendingReasoning, extractReasoningText(item)) ?? lastReasoning;
+        attachToolCallToAssistant(messages, call, reasoning, forceReasoningPlaceholder);
+        pendingReasoning = undefined;
+      }
+      continue;
+    }
+
+    if (type === "function_call_output" || type === "custom_tool_call_output" || type === "tool_search_output") {
+      const callId = stringField(item.call_id);
+      if (!callId) continue;
+      const output = item.output ?? item.content ?? item;
+      messages.push({ role: "tool", tool_call_id: callId, content: typeof output === "string" ? output : canonicalJsonString(output) });
+      pendingReasoning = undefined;
+      continue;
+    }
+
+    if (type === "tool_call" && isRecord(item.tool_use)) {
+      const toolUse = item.tool_use;
+      const callId = stringField(toolUse.id);
+      const name = stringField(toolUse.name);
+      if (callId && name) {
+        attachToolCallToAssistant(messages, {
+          id: callId,
+          type: "function",
+          function: { name, arguments: canonicalJsonString(toolUse.input ?? {}) },
+        }, pendingReasoning ?? lastReasoning, forceReasoningPlaceholder);
+        pendingReasoning = undefined;
+      }
+      continue;
+    }
+
+    if (type === "tool_result" && isRecord(item.content)) {
+      const callId = stringField(item.content.tool_use_id);
+      if (callId) {
+        messages.push({ role: "tool", tool_call_id: callId, content: canonicalJsonString(item.content.content ?? "") });
+      }
+      pendingReasoning = undefined;
+      continue;
+    }
+
+    if (type === "message" || item.role !== undefined || item.content !== undefined) {
+      const role = normalizeRole(item.role);
+      const content = contentToChatContent(item.content);
+      const message: ChatMessage = {
+        role,
+        content: role === "assistant" && (content === null || (Array.isArray(content) && content.length === 0)) ? "" : content,
+      };
+      if (role === "assistant") {
+        const reasoning = appendText(pendingReasoning, extractReasoningText(item));
+        if (reasoning) {
+          message.reasoning_content = reasoning;
+          lastReasoning = appendText(lastReasoning, reasoning);
+        }
+      } else {
+        pendingReasoning = undefined;
+      }
+      messages.push(message);
+    }
+  }
+
+  for (const message of messages) {
+    if (forceReasoningPlaceholder && message.role === "assistant" && message.tool_calls?.length && !message.reasoning_content?.trim()) {
+      message.reasoning_content = "tool call";
+    }
+  }
+}
+
+function collapseSystemMessagesToHead(messages: ChatMessage[]): ChatMessage[] {
+  const system: string[] = [];
+  const rest: ChatMessage[] = [];
+  for (const message of messages) {
+    if (message.role === "system" && typeof message.content === "string" && message.content.trim()) {
+      system.push(message.content);
+    } else {
+      rest.push(message);
+    }
+  }
+  return system.length ? [{ role: "system", content: system.join("\n\n") }, ...rest] : rest;
+}
+
+function detectProvider(modelId?: string, providerHint?: string): keyof typeof THINKING_MAPPINGS {
+  const model = (modelId ?? "").toLowerCase();
+  const text = `${model} ${providerHint ?? ""}`.toLowerCase();
+  if (model.includes("openrouter") || model.includes("deeprouter")) return "openrouter";
+  if (text.includes("openrouter") || text.includes("deeprouter")) return "openrouter";
+  if (text.includes("deepseek")) return "deepseek";
+  if (text.includes("siliconflow")) return "deepseek";
+  if (text.includes("kimi") || text.includes("moonshot")) return "kimi";
+  if (text.includes("qwen")) return "qwen";
+  if (text.includes("glm") || text.includes("zhipu") || text.includes("chatglm")) return "glm";
+  return "generic";
+}
+
+function requiresAssistantToolReasoning(modelId: string | undefined, providerHint: string | undefined): boolean {
+  const text = `${modelId ?? ""} ${providerHint ?? ""}`.toLowerCase();
+  return /deepseek|kimi|moonshot|siliconflow/.test(text);
+}
+
+function normalizeEffort(value?: string | null): ThinkingEffort {
+  if (!value) return "off";
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "xhigh" || normalized === "max") return "xhigh";
+  if (normalized === "high") return "high";
+  if (normalized === "medium") return "medium";
+  if (normalized === "low") return "low";
+  if (normalized === "minimal") return "minimal";
+  if (normalized === "off" || normalized === "none" || normalized === "disabled" || normalized === "false") return "off";
+  return "medium";
+}
+
+function applyThinking(chat: ChatRequestBody, body: ResponsesRequestBody, defaultThinking: string, providerHint?: string, customMapping?: ThinkingMapping) {
+  const provider = detectProvider(body.model, providerHint);
+  const mapping = customMapping ?? (THINKING_MAPPINGS[provider] ?? THINKING_MAPPINGS.generic);
+
+  const explicitReasoning = body.reasoning !== undefined;
+  let requested = normalizeEffort(defaultThinking);
+  if (explicitReasoning) {
+    if (!body.reasoning || body.reasoning.enabled === false) requested = "off";
+    else requested = normalizeEffort(body.reasoning.effort);
+  }
+
+  const mapped = mapping.effortMap[requested];
+  if (mapped === null) {
+    if (explicitReasoning && mapping.effortParam === "reasoning.effort") {
+      chat.reasoning = { effort: "none" };
+    }
+    return;
+  }
+
+  if (mapping.thinkingParam === "enable_thinking") chat.enable_thinking = true;
+  else if (mapping.thinkingParam === "thinking") chat.thinking = { type: "enabled" };
+
+  if (mapping.supportsEffort && mapped !== "enabled") {
+    if (mapping.effortParam === "reasoning.effort") chat.reasoning = { effort: mapped };
+    else chat.reasoning_effort = mapped;
+  }
+}
+
+function responsesToChat(
+  body: ResponsesRequestBody,
+  defaultThinking: string,
+  context = buildToolContext(body.tools),
+  providerHint?: string,
+  customMapping?: ThinkingMapping,
+): ChatRequestBody {
+  const messages: ChatMessage[] = [];
+  const instructions = instructionText(body.instructions);
+  if (instructions) messages.push({ role: "system", content: instructions });
+  appendResponsesInput(body.input, messages, context, requiresAssistantToolReasoning(body.model, providerHint));
+
+  const model = body.model || "deepseek-chat";
+  const chat: ChatRequestBody = {
+    model,
+    messages: collapseSystemMessagesToHead(messages),
+  };
+
+  if (body.max_output_tokens !== undefined) chat.max_tokens = body.max_output_tokens;
+  if (body.max_tokens !== undefined) chat.max_tokens = body.max_tokens;
+  if (body.max_completion_tokens !== undefined) chat.max_completion_tokens = body.max_completion_tokens;
+  if (body.temperature !== undefined) chat.temperature = body.temperature;
+  if (body.top_p !== undefined) chat.top_p = body.top_p;
+  if (body.stream !== undefined) chat.stream = body.stream;
+  if (body.stop !== undefined) chat.stop = body.stop;
+  if (body.frequency_penalty !== undefined) chat.frequency_penalty = body.frequency_penalty;
+  if (body.presence_penalty !== undefined) chat.presence_penalty = body.presence_penalty;
+
+  applyThinking(chat, body, defaultThinking, providerHint, customMapping);
+
+  const tools = responsesToolsToChatTools(body.tools, context);
+  if (tools.length) {
+    chat.tools = tools;
+    if (body.parallel_tool_calls !== undefined) chat.parallel_tool_calls = body.parallel_tool_calls;
+    const toolChoice = responsesToolChoiceToChat(body.tool_choice, context);
+    if (toolChoice !== undefined) chat.tool_choice = toolChoice;
+  }
+
+  for (const key of EXTRA_CHAT_PASSTHROUGH_FIELDS) {
+    if (body[key] !== undefined) chat[key] = body[key];
+  }
+
+  if (chat.stream) {
+    chat.stream_options = {
+      ...(isRecord(body.stream_options) ? body.stream_options : {}),
+      include_usage: true,
+    };
+  }
+
+  return chat;
+}
+
+function responseStatus(finishReason?: string | null): string {
+  if (finishReason === "length") return "incomplete";
+  return "completed";
+}
+
+function defaultUsage(): JsonObject {
+  return { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+}
+
+function chatUsageToResponsesUsage(value: unknown): JsonObject {
+  if (!isRecord(value)) return defaultUsage();
+  const input = Number(value.prompt_tokens ?? value.input_tokens ?? 0);
+  const output = Number(value.completion_tokens ?? value.output_tokens ?? 0);
+  const total = Number(value.total_tokens ?? input + output);
+  const usage: JsonObject = {
+    input_tokens: input,
+    output_tokens: output,
+    total_tokens: total,
+  };
+  if (isRecord(value.prompt_tokens_details)) usage.input_tokens_details = value.prompt_tokens_details;
+  if (isRecord(value.completion_tokens_details)) usage.output_tokens_details = value.completion_tokens_details;
+  return usage;
+}
+
+function responseReasoningItem(responseId: string, text: string): JsonObject {
+  return {
+    id: `rs_${responseId}`,
+    type: "reasoning",
+    reasoning_content: text,
+    summary: [{ type: "summary_text", text }],
+  };
+}
+
+function customToolInputFromArguments(argumentsText: string): string {
+  try {
+    const parsed = JSON.parse(argumentsText) as unknown;
+    if (isRecord(parsed) && typeof parsed.input === "string") return parsed.input;
+  } catch {
+    // Keep raw text for non-JSON custom tool calls.
+  }
+  return argumentsText;
+}
+
+function responseToolCallItem(
+  callId: string,
+  chatName: string,
+  argumentsText: string,
+  status: "in_progress" | "completed",
+  context: ToolContext,
+): JsonObject {
+  const spec = context.specs.get(chatName);
+  if (spec?.kind === "custom") {
+    return {
+      id: `ctc_${callId}`,
+      type: "custom_tool_call",
+      status,
+      call_id: callId,
+      name: spec.originalName,
+      input: customToolInputFromArguments(argumentsText),
+    };
+  }
+
+  const item: JsonObject = {
+    id: `fc_${callId}`,
+    type: "function_call",
+    status,
+    call_id: callId,
+    name: spec?.originalName ?? chatName,
+    arguments: argumentsText,
+  };
+  if (spec?.namespace) item.namespace = spec.namespace;
+  return item;
+}
+
+function chatToResponses(chatResp: JsonObject, fallbackModel: string, context: ToolContext): JsonObject {
+  const responseId = `resp_${randomBytes(12).toString("hex")}`;
+  const choices = Array.isArray(chatResp.choices) ? chatResp.choices : [];
+  const choice = isRecord(choices[0]) ? choices[0] : {};
+  const message = isRecord(choice.message) ? choice.message : {};
+  const output: JsonObject[] = [];
+
+  const reasoning = extractReasoningText(message);
+  if (reasoning) output.push(responseReasoningItem(responseId, reasoning));
+
+  const content = typeof message.content === "string" ? message.content : "";
+  if (content) {
+    output.push({
+      id: `msg_${randomBytes(12).toString("hex")}`,
+      type: "message",
+      status: "completed",
+      role: "assistant",
+      content: [{ type: "output_text", text: content, annotations: [] }],
+    });
+  }
+
+  const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+  for (const toolCall of toolCalls) {
+    if (!isRecord(toolCall)) continue;
+    const fn = isRecord(toolCall.function) ? toolCall.function : {};
+    const callId = stringField(toolCall.id) ?? `call_${output.length}`;
+    const name = stringField(fn.name) ?? "unknown_tool";
+    const args = canonicalizeJsonStringIfParseable(typeof fn.arguments === "string" ? fn.arguments : "{}");
+    output.push(responseToolCallItem(callId, name, args, "completed", context));
+  }
+
+  const status = responseStatus(stringField(choice.finish_reason));
+  const response: JsonObject = {
+    id: responseId,
+    object: "response",
+    created_at: typeof chatResp.created === "number" ? chatResp.created : Math.floor(Date.now() / 1000),
+    status,
+    model: stringField(chatResp.model) ?? fallbackModel,
+    output,
+    usage: chatUsageToResponsesUsage(chatResp.usage),
+  };
+  if (status === "incomplete") response.incomplete_details = { reason: "max_output_tokens" };
+  return response;
+}
+
+function formatSSE(event: string, payload: unknown): string {
+  return `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;
+}
+
+function createStreamState(model: string, context: ToolContext): SSEStreamState {
+  const responseId = `resp_${randomBytes(12).toString("hex")}`;
+  return {
+    responseId,
+    messageId: `msg_${randomBytes(12).toString("hex")}`,
+    reasoningId: `rs_${responseId}`,
+    createdAt: Math.floor(Date.now() / 1000),
+    model: model || "deepseek-chat",
+    text: "",
+    textStarted: false,
+    contentStarted: false,
+    messageOutputIndex: null,
+    reasoningText: "",
+    reasoningStarted: false,
+    reasoningDone: false,
+    reasoningOutputIndex: null,
+    inlineThinkMode: "detecting",
+    inlineThinkBuffer: "",
+    nextOutputIndex: 0,
+    toolCalls: [],
+    outputItems: [],
+    finalUsage: null,
+    finishReason: null,
+    toolContext: context,
+  };
+}
+
+function baseResponse(state: SSEStreamState, status: string, output: JsonObject[] = []): JsonObject {
+  return {
+    id: state.responseId,
+    object: "response",
+    created_at: state.createdAt,
+    status,
+    model: state.model,
+    output,
+    usage: state.finalUsage ?? defaultUsage(),
+  };
+}
+
+function startedStreamEvents(state: SSEStreamState): string {
+  const response = baseResponse(state, "in_progress");
+  return formatSSE("response.created", { type: "response.created", response })
+    + formatSSE("response.in_progress", { type: "response.in_progress", response });
+}
+
+function nextOutputIndex(state: SSEStreamState): number {
+  return state.nextOutputIndex++;
+}
+
+function pushReasoningDelta(state: SSEStreamState, delta: string): string[] {
+  if (!delta) return [];
+  const events: string[] = [];
+  if (!state.reasoningStarted) {
+    state.reasoningStarted = true;
+    state.reasoningOutputIndex = nextOutputIndex(state);
+    events.push(formatSSE("response.output_item.added", {
+      type: "response.output_item.added",
+      output_index: state.reasoningOutputIndex,
+      item: {
+        id: state.reasoningId,
+        type: "reasoning",
+        status: "in_progress",
+        reasoning_content: "",
+        summary: [],
+      },
+    }));
+    events.push(formatSSE("response.reasoning_summary_part.added", {
+      type: "response.reasoning_summary_part.added",
+      item_id: state.reasoningId,
+      output_index: state.reasoningOutputIndex,
+      summary_index: 0,
+      part: { type: "summary_text", text: "" },
+    }));
+  }
+
+  state.reasoningText += delta;
+  events.push(formatSSE("response.reasoning_summary_text.delta", {
+    type: "response.reasoning_summary_text.delta",
+    item_id: state.reasoningId,
+    output_index: state.reasoningOutputIndex ?? 0,
+    summary_index: 0,
+    delta,
+  }));
+  return events;
+}
+
+function finalizeReasoning(state: SSEStreamState): string[] {
+  if (!state.reasoningStarted || state.reasoningDone) return [];
+  const outputIndex = state.reasoningOutputIndex ?? 0;
+  const item = responseReasoningItem(state.responseId, state.reasoningText);
+  state.outputItems.push({ outputIndex, item });
+  state.reasoningDone = true;
+  return [
+    formatSSE("response.reasoning_summary_text.done", {
+      type: "response.reasoning_summary_text.done",
+      item_id: state.reasoningId,
+      output_index: outputIndex,
+      summary_index: 0,
+      text: state.reasoningText,
+    }),
+    formatSSE("response.reasoning_summary_part.done", {
+      type: "response.reasoning_summary_part.done",
+      item_id: state.reasoningId,
+      output_index: outputIndex,
+      summary_index: 0,
+      part: { type: "summary_text", text: state.reasoningText },
+    }),
+    formatSSE("response.output_item.done", {
+      type: "response.output_item.done",
+      output_index: outputIndex,
+      item,
+    }),
+  ];
+}
+
+function pushTextDelta(state: SSEStreamState, delta: string): string[] {
+  if (!delta) return [];
+  const events: string[] = [];
+  if (!state.textStarted) {
+    state.textStarted = true;
+    state.messageOutputIndex = nextOutputIndex(state);
+    events.push(formatSSE("response.output_item.added", {
+      type: "response.output_item.added",
+      output_index: state.messageOutputIndex,
+      item: {
+        id: state.messageId,
+        type: "message",
+        status: "in_progress",
+        role: "assistant",
+        content: [],
+      },
+    }));
+  }
+  if (!state.contentStarted) {
+    state.contentStarted = true;
+    events.push(formatSSE("response.content_part.added", {
+      type: "response.content_part.added",
+      item_id: state.messageId,
+      output_index: state.messageOutputIndex ?? 0,
+      content_index: 0,
+      part: { type: "output_text", text: "", annotations: [] },
+    }));
+  }
+
+  state.text += delta;
+  events.push(formatSSE("response.output_text.delta", {
+    type: "response.output_text.delta",
+    item_id: state.messageId,
+    output_index: state.messageOutputIndex ?? 0,
+    content_index: 0,
+    delta,
+  }));
+  return events;
+}
+
+function finalizeText(state: SSEStreamState): string[] {
+  if (!state.textStarted) return [];
+  const outputIndex = state.messageOutputIndex ?? 0;
+  const item: JsonObject = {
+    id: state.messageId,
+    type: "message",
+    status: "completed",
+    role: "assistant",
+    content: [{ type: "output_text", text: state.text, annotations: [] }],
+  };
+  state.outputItems.push({ outputIndex, item });
+  return [
+    formatSSE("response.output_text.done", {
+      type: "response.output_text.done",
+      item_id: state.messageId,
+      output_index: outputIndex,
+      content_index: 0,
+      text: state.text,
+    }),
+    formatSSE("response.content_part.done", {
+      type: "response.content_part.done",
+      item_id: state.messageId,
+      output_index: outputIndex,
+      content_index: 0,
+      part: { type: "output_text", text: state.text, annotations: [] },
+    }),
+    formatSSE("response.output_item.done", {
+      type: "response.output_item.done",
+      output_index: outputIndex,
+      item,
+    }),
+  ];
+}
+
+function handleContentDelta(state: SSEStreamState, delta: string): string[] {
+  if (!delta) return [];
+  const events: string[] = [];
+
+  if (state.inlineThinkMode === "text") {
+    events.push(...finalizeReasoning(state));
+    events.push(...pushTextDelta(state, delta));
+    return events;
+  }
+
+  state.inlineThinkBuffer += delta;
+  if (state.inlineThinkMode === "detecting") {
+    const trimmed = state.inlineThinkBuffer.trimStart();
+    if (!trimmed) return events;
+    if (trimmed.startsWith(THINK_OPEN_TAG)) {
+      state.inlineThinkMode = "reasoning";
+      state.inlineThinkBuffer = trimmed.slice(THINK_OPEN_TAG.length);
+    } else if (THINK_OPEN_TAG.startsWith(trimmed)) {
+      return events;
+    } else {
+      state.inlineThinkMode = "text";
+      const text = state.inlineThinkBuffer;
+      state.inlineThinkBuffer = "";
+      events.push(...finalizeReasoning(state));
+      events.push(...pushTextDelta(state, text));
+      return events;
+    }
+  }
+
+  if (state.inlineThinkMode === "reasoning") {
+    const closeIndex = state.inlineThinkBuffer.indexOf(THINK_CLOSE_TAG);
+    if (closeIndex === -1) return events;
+    const reasoning = state.inlineThinkBuffer.slice(0, closeIndex);
+    const answer = state.inlineThinkBuffer.slice(closeIndex + THINK_CLOSE_TAG.length);
+    state.inlineThinkBuffer = "";
+    state.inlineThinkMode = "text";
+    events.push(...pushReasoningDelta(state, reasoning));
+    events.push(...finalizeReasoning(state));
+    events.push(...pushTextDelta(state, answer));
+  }
+
+  return events;
+}
+
+function flushInlineThink(state: SSEStreamState): string[] {
+  const events: string[] = [];
+  if (!state.inlineThinkBuffer) return events;
+  if (state.inlineThinkMode === "reasoning") {
+    const closeIndex = state.inlineThinkBuffer.indexOf(THINK_CLOSE_TAG);
+    const reasoning = closeIndex === -1
+      ? state.inlineThinkBuffer
+      : state.inlineThinkBuffer.slice(0, closeIndex);
+    const answer = closeIndex === -1
+      ? ""
+      : state.inlineThinkBuffer.slice(closeIndex + THINK_CLOSE_TAG.length);
+    events.push(...pushReasoningDelta(state, reasoning));
+    events.push(...finalizeReasoning(state));
+    events.push(...pushTextDelta(state, answer));
+  } else {
+    events.push(...finalizeReasoning(state));
+    events.push(...pushTextDelta(state, state.inlineThinkBuffer));
+  }
+  state.inlineThinkBuffer = "";
+  state.inlineThinkMode = "text";
+  return events;
+}
+
+function toolCallItemId(callId: string, chatName: string, context: ToolContext): string {
+  const spec = context.specs.get(chatName);
+  return `${spec?.kind === "custom" ? "ctc" : "fc"}_${callId}`;
+}
+
+function pushToolCallDelta(state: SSEStreamState, toolCall: JsonObject): string[] {
+  const events: string[] = [];
+  const index = typeof toolCall.index === "number" ? toolCall.index : state.toolCalls.length;
+  const fn = isRecord(toolCall.function) ? toolCall.function : {};
+  let current = state.toolCalls[index];
+  const id = stringField(toolCall.id);
+  const name = stringField(fn.name);
+  const argsDelta = typeof fn.arguments === "string" ? fn.arguments : "";
+
+  if (!current) {
+    const callId = id ?? `call_${index}`;
+    const chatName = name ?? "unknown_tool";
+    current = {
+      outputIndex: nextOutputIndex(state),
+      itemId: toolCallItemId(callId, chatName, state.toolContext),
+      callId,
+      name: chatName,
+      arguments: "",
+      done: false,
+    };
+    state.toolCalls[index] = current;
+    events.push(formatSSE("response.output_item.added", {
+      type: "response.output_item.added",
+      output_index: current.outputIndex,
+      item: responseToolCallItem(current.callId, current.name, "", "in_progress", state.toolContext),
+    }));
+  }
+
+  if (id) current.callId = id;
+  if (name && current.name === "unknown_tool") {
+    current.name = name;
+    current.itemId = toolCallItemId(current.callId, current.name, state.toolContext);
+  }
+
+  if (argsDelta) {
+    current.arguments += argsDelta;
+    const spec = state.toolContext.specs.get(current.name);
+    if (spec?.kind !== "custom") {
+      events.push(formatSSE("response.function_call_arguments.delta", {
+        type: "response.function_call_arguments.delta",
+        item_id: current.itemId,
+        output_index: current.outputIndex,
+        delta: argsDelta,
+      }));
+    }
+  }
+
+  return events;
+}
+
+function finalizeTools(state: SSEStreamState): string[] {
+  const events: string[] = [];
+  for (const toolCall of state.toolCalls) {
+    if (!toolCall || toolCall.done) continue;
+    toolCall.done = true;
+    const args = canonicalizeJsonStringIfParseable(toolCall.arguments);
+    const spec = state.toolContext.specs.get(toolCall.name);
+    if (spec?.kind === "custom") {
+      const input = customToolInputFromArguments(args);
+      if (input) {
+        events.push(formatSSE("response.custom_tool_call_input.delta", {
+          type: "response.custom_tool_call_input.delta",
+          item_id: toolCall.itemId,
+          output_index: toolCall.outputIndex,
+          delta: input,
+        }));
+      }
+      events.push(formatSSE("response.custom_tool_call_input.done", {
+        type: "response.custom_tool_call_input.done",
+        item_id: toolCall.itemId,
+        output_index: toolCall.outputIndex,
+        input,
+      }));
+    } else {
+      events.push(formatSSE("response.function_call_arguments.done", {
+        type: "response.function_call_arguments.done",
+        item_id: toolCall.itemId,
+        output_index: toolCall.outputIndex,
+        arguments: args,
+      }));
+    }
+
+    const item = responseToolCallItem(toolCall.callId, toolCall.name, args, "completed", state.toolContext);
+    state.outputItems.push({ outputIndex: toolCall.outputIndex, item });
+    events.push(formatSSE("response.output_item.done", {
+      type: "response.output_item.done",
+      output_index: toolCall.outputIndex,
+      item,
+    }));
+  }
+  return events;
+}
+
+function translateChatSSEToResponsesEvents(chunk: JsonObject, state: SSEStreamState): string[] {
+  const events: string[] = [];
+  const model = stringField(chunk.model);
+  if (model) state.model = model;
+  if (isRecord(chunk.usage)) state.finalUsage = chatUsageToResponsesUsage(chunk.usage);
+
+  const choices = Array.isArray(chunk.choices) ? chunk.choices : [];
+  const choice = isRecord(choices[0]) ? choices[0] : undefined;
+  if (!choice) return events;
+
+  if (typeof choice.finish_reason === "string") state.finishReason = choice.finish_reason;
+  const delta = isRecord(choice.delta) ? choice.delta : {};
+
+  const reasoningDelta = stringField(delta.reasoning_content) ?? stringField(delta.reasoning);
+  if (reasoningDelta) {
+    events.push(...pushReasoningDelta(state, reasoningDelta));
+  }
+
+  const contentDelta = typeof delta.content === "string" ? delta.content : "";
+  if (contentDelta) {
+    events.push(...handleContentDelta(state, contentDelta));
+  }
+
+  if (Array.isArray(delta.tool_calls)) {
+    events.push(...flushInlineThink(state));
+    events.push(...finalizeReasoning(state));
+    for (const toolCall of delta.tool_calls) {
+      if (isRecord(toolCall)) events.push(...pushToolCallDelta(state, toolCall));
+    }
+  }
+
+  return events;
+}
+
+function sseStreamFinalize(state: SSEStreamState): string[] {
+  const events: string[] = [];
+  events.push(...flushInlineThink(state));
+  events.push(...finalizeReasoning(state));
+  events.push(...finalizeText(state));
+  events.push(...finalizeTools(state));
+
+  const sorted = [...state.outputItems].sort((a, b) => a.outputIndex - b.outputIndex).map((entry) => entry.item);
+  const status = responseStatus(state.finishReason);
+  const response = baseResponse(state, status, sorted);
+  if (status === "incomplete") response.incomplete_details = { reason: "max_output_tokens" };
+  events.push(formatSSE("response.completed", {
+    type: "response.completed",
+    response,
+  }));
+  events.push("data: [DONE]\n\n");
+  return events;
+}
+
+function responsesErrorFromUpstream(statusCode: number, contentType: string | undefined, body: Buffer): JsonObject {
+  let message = body.toString("utf8").slice(0, ERROR_BODY_PREVIEW_LIMIT);
+  let type = "upstream_error";
+  let code: string | number = statusCode;
+  let param: unknown;
+
+  if (contentType?.toLowerCase().includes("json")) {
+    try {
+      const parsed = JSON.parse(body.toString("utf8")) as unknown;
+      const error = isRecord(parsed) && isRecord(parsed.error) ? parsed.error : parsed;
+      if (isRecord(error)) {
+        message = stringField(error.message) ?? stringField(error.detail) ?? message;
+        type = stringField(error.type) ?? stringField(error.error_type) ?? type;
+        code = error.code as string | number ?? code;
+        param = error.param;
+      }
+    } catch {
+      // Keep plain text preview.
+    }
+  }
+
+  const error: JsonObject = { message: message || `Upstream returned HTTP ${statusCode}`, type, code };
+  if (param !== undefined) error.param = param;
+  return { error };
+}
+
+function appendStreamChunk(buffer: { value: string }, chunk: Buffer, state: SSEStreamState, res: ServerResponse) {
+  buffer.value += chunk.toString("utf8");
+  while (buffer.value.includes("\n")) {
+    const newlineIndex = buffer.value.indexOf("\n");
+    const line = buffer.value.slice(0, newlineIndex).trim();
+    buffer.value = buffer.value.slice(newlineIndex + 1);
+    if (!line || line.startsWith(":")) continue;
+    if (line === "data: [DONE]") continue;
+    if (!line.startsWith("data: ")) continue;
+    try {
+      const payload = JSON.parse(line.slice(6)) as unknown;
+      if (isRecord(payload)) {
+        for (const event of translateChatSSEToResponsesEvents(payload, state)) res.write(event);
+      }
+    } catch {
+      // Ignore malformed upstream chunks.
+    }
+  }
+}
+
+function hasVersionSuffix(baseUrl: string): boolean {
+  const segment = baseUrl.split("/").pop() ?? "";
+  return /^v\d+/i.test(segment);
+}
+
+export function chatCompletionsUrl(baseUrl: string): string {
+  const base = baseUrl.trim().replace(/#+$/, "").replace(/\/+$/, "");
+  if (!base) return base;
+  if (/\/chat\/completions$/i.test(base)) return base;
+  const rest = base.split("://")[1] ?? base;
+  const originOnly = !rest.includes("/");
+  let url = originOnly && !hasVersionSuffix(base)
+    ? `${base}/v1/chat/completions`
+    : `${base}/chat/completions`;
+  while (url.includes("/v1/v1/")) url = url.replace("/v1/v1/", "/v1/");
+  return url;
+}
+
+export class CompatProxy {
+  private server: ReturnType<typeof createServer> | null = null;
+  private port = 0;
+  public readonly targetUrl: string;
+  public readonly apiKey: string;
+  public readonly defaultThinking: string;
+  public readonly reasoningConfig?: ReasoningConfig;
+
+  constructor(opts: ProxyOptions) {
+    this.targetUrl = chatCompletionsUrl(opts.targetUrl);
+    this.apiKey = opts.apiKey;
+    this.defaultThinking = opts.defaultThinking ?? "disabled";
+    this.reasoningConfig = opts.reasoningConfig;
+    if (opts.port) this.port = opts.port;
+  }
+
+  async start(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      this.server = createServer((req, res) => this.handleRequest(req, res));
+      this.server.on("error", reject);
+      this.server.listen(this.port, "127.0.0.1", () => {
+        const addr = this.server?.address();
+        if (addr && typeof addr === "object") {
+          this.port = addr.port;
+          resolve(this.port);
+        } else {
+          reject(new Error("Failed to get server address"));
+        }
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (!this.server) {
+        resolve();
+        return;
+      }
+      this.server.close(() => resolve());
+      this.server = null;
+    });
+  }
+
+  getPort(): number {
+    return this.port;
+  }
+
+  getBaseUrl(): string {
+    return `http://127.0.0.1:${this.port}/v1`;
+  }
+
+  private handleRequest(req: IncomingMessage, res: ServerResponse): void {
+    if (req.url === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", target: this.targetUrl }));
+      return;
+    }
+    if (req.method !== "POST" || !req.url?.startsWith("/v1/responses")) {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => {
+      try {
+        const body = JSON.parse(Buffer.concat(chunks).toString()) as ResponsesRequestBody;
+        this.proxyRequest(body, res);
+      } catch {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: { message: "Invalid JSON", type: "invalid_request_error" } }));
+      }
+    });
+  }
+
+  private proxyRequest(body: ResponsesRequestBody, res: ServerResponse): void {
+    const context = buildToolContext(body.tools);
+    const customMapping = this.reasoningConfig ? buildThinkingMapping(this.reasoningConfig) : undefined;
+    const chatBody = responsesToChat(body, this.defaultThinking, context, this.targetUrl, customMapping);
+    const targetUrl = new URL(this.targetUrl);
+    const isHttps = targetUrl.protocol === "https:";
+    const requestFn = isHttps ? httpsRequest : httpRequest;
+
+    const upstreamReq = requestFn({
+      hostname: targetUrl.hostname,
+      port: targetUrl.port || (isHttps ? 443 : 80),
+      path: targetUrl.pathname + targetUrl.search,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+    }, (upstreamRes) => {
+      const statusCode = upstreamRes.statusCode ?? 502;
+      const contentType = String(upstreamRes.headers["content-type"] ?? "");
+      const upstreamIsStream = chatBody.stream === true || contentType.includes("text/event-stream");
+
+      if (statusCode < 200 || statusCode >= 300) {
+        const errorChunks: Buffer[] = [];
+        upstreamRes.on("data", (chunk: Buffer) => errorChunks.push(chunk));
+        upstreamRes.on("end", () => {
+          const error = responsesErrorFromUpstream(statusCode, contentType, Buffer.concat(errorChunks));
+          res.writeHead(statusCode, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(error));
+        });
+        return;
+      }
+
+      if (upstreamIsStream) {
+        const state = createStreamState(chatBody.model, context);
+        res.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        });
+        res.write(startedStreamEvents(state));
+        const buffer = { value: "" };
+        upstreamRes.on("data", (chunk: Buffer) => appendStreamChunk(buffer, chunk, state, res));
+        upstreamRes.on("end", () => {
+          for (const event of sseStreamFinalize(state)) res.write(event);
+          res.end();
+        });
+        upstreamRes.on("error", () => res.end());
+        return;
+      }
+
+      const responseChunks: Buffer[] = [];
+      upstreamRes.on("data", (chunk: Buffer) => responseChunks.push(chunk));
+      upstreamRes.on("end", () => {
+        try {
+          const chatResp = JSON.parse(Buffer.concat(responseChunks).toString()) as JsonObject;
+          const response = chatToResponses(chatResp, chatBody.model, context);
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(response));
+        } catch {
+          res.writeHead(502, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: { message: "Invalid upstream JSON", type: "upstream_error" } }));
+        }
+      });
+    });
+
+    upstreamReq.on("error", (error) => {
+      res.writeHead(502, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: { message: `Upstream error: ${error.message}`, type: "upstream_error" } }));
+    });
+    upstreamReq.write(JSON.stringify(chatBody));
+    upstreamReq.end();
+  }
+}
+
+const NON_OPENAI_BASE_URL_PATTERNS = [
+  /deepseek/i,
+  /moonshot/i,
+  /zhipu|bigmodel/i,
+  /qwen/i,
+  /kimi/i,
+  /minimax/i,
+  /siliconflow/i,
+  /together/i,
+  /groq/i,
+  /dashscope/i,
+  /lingyiwanwu|yi-api/i,
+  /stepfun|step-api/i,
+  /baichuan/i,
+  /\/chat\/completions(?:$|[?#])/i,
+];
+
+export function needsCompatProxy(baseUrl: string): boolean {
+  if (!baseUrl) return false;
+  const normalized = baseUrl.toLowerCase();
+  if (normalized.includes("api.openai.com")) return false;
+  return NON_OPENAI_BASE_URL_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+export const __compatProxyTest = {
+  responsesToChat,
+  chatToResponses,
+  buildToolContext,
+  translateChatSSEToResponsesEvents,
+  sseStreamFinalize,
+  createStreamState,
+};