@rerouter/helper 0.0.0-stage → 0.1.0

package/src/lib/responses-bridge.js

@@ -0,0 +1,639 @@
+import crypto from "node:crypto";
+
+/**
+ * Pure translation between the OpenAI-compatible Responses API (used by Codex CLI)
+ * and the OpenAI-compatible Chat Completions API (used by the Rerouter gateway).
+ *
+ * This module has NO I/O — the local bridge server lives in bridge-server.js.
+ *
+ * Supported:
+ * - message (user/assistant/system/developer), input_text, input_image, output_text
+ * - function tools + function_call / function_call_output
+ * - custom tools (freeform input) — wrapped as a function `{input: string}`
+ * - reasoning.effort → reasoning_effort
+ * - stream: chat.completion.chunk → Responses events (response.created,
+ *   output_item.added, output_text.delta, function_call_arguments.delta, …, response.completed)
+ *
+ * Documented limitations:
+ * - `reasoning` items (encrypted) are dropped — cannot be forwarded to chat upstream.
+ * - `input_file`, item_reference, web_search/preview tools → 400 invalid_request.
+ * - store/include/background/service_tier/truncation → ignored.
+ */
+
+export class ResponsesBridgeError extends Error {
+  constructor(status, message, type = "invalid_request_error") {
+    super(message);
+    this.name = "ResponsesBridgeError";
+    this.status = status;
+    this.type = type;
+  }
+}
+
+const REASONING_EFFORTS = new Set(["low", "medium", "high"]);
+
+function newId(prefix) {
+  return `${prefix}_${crypto.randomUUID().replaceAll("-", "")}`;
+}
+
+function toText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => (typeof part?.text === "string" ? part.text : ""))
+    .filter(Boolean)
+    .join("");
+}
+
+function mapContentParts(content, role) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const out = [];
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    switch (part.type) {
+      case "input_text":
+      case "output_text":
+        out.push({ type: "text", text: part.text ?? "" });
+        break;
+      case "refusal":
+        out.push({ type: "text", text: part.refusal ?? "" });
+        break;
+      case "input_image": {
+        const url = part.image_url;
+        if (typeof url !== "string" || !url) {
+          throw new ResponsesBridgeError(400, "input_image without image_url is not supported.");
+        }
+        out.push({ type: "image_url", image_url: { url } });
+        break;
+      }
+      case "input_file":
+        throw new ResponsesBridgeError(400, "input_file is not yet supported by the bridge.");
+      default:
+        throw new ResponsesBridgeError(400, `Unknown content part: "${part.type}".`);
+    }
+  }
+  // Single text part → plain string (more compatible with strict upstreams).
+  if (role !== "user" && out.every((p) => p.type === "text")) {
+    return out.map((p) => p.text).join("");
+  }
+  if (out.length === 1 && out[0].type === "text") return out[0].text;
+  return out;
+}
+
+function mapToolChoice(choice) {
+  if (choice === undefined || choice === null) return undefined;
+  if (typeof choice === "string") {
+    if (choice === "auto" || choice === "required" || choice === "none") return choice;
+    return "auto";
+  }
+  if (typeof choice === "object" && typeof choice.name === "string") {
+    // {type:"function"|"custom"|"allowed_tools", name}
+    return { type: "function", function: { name: choice.name } };
+  }
+  return undefined;
+}
+
+/**
+ * Responses request → { request, customToolNames } ready to send to
+ * POST {baseUrl}/v1/chat/completions. Only fields known to the gateway
+ * are forwarded (whitelist).
+ */
+export function responsesToChatRequest(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw new ResponsesBridgeError(400, "Body must be a JSON object.");
+  }
+  const model = typeof body.model === "string" ? body.model.trim() : "";
+  if (!model) throw new ResponsesBridgeError(400, "Field `model` is required.");
+
+  const messages = [];
+  if (typeof body.instructions === "string" && body.instructions.trim()) {
+    messages.push({ role: "system", content: body.instructions });
+  }
+
+  const customToolNames = new Set();
+  let input = body.input;
+  if (typeof input === "string") {
+    input = [{ type: "message", role: "user", content: [{ type: "input_text", text: input }] }];
+  }
+  if (!Array.isArray(input)) {
+    throw new ResponsesBridgeError(400, "Field `input` must be a string or an array of items.");
+  }
+
+  for (const item of input) {
+    if (!item || typeof item !== "object") {
+      throw new ResponsesBridgeError(400, "`input` items must be objects.");
+    }
+    const type = item.type ?? (item.role ? "message" : undefined);
+    switch (type) {
+      case "message": {
+        const roleRaw = typeof item.role === "string" ? item.role : "user";
+        const role = roleRaw === "developer" ? "system" : roleRaw;
+        if (!["user", "assistant", "system", "tool"].includes(role)) {
+          throw new ResponsesBridgeError(400, `Unknown role: "${roleRaw}".`);
+        }
+        const content = mapContentParts(item.content, role);
+        messages.push({ role, content });
+        break;
+      }
+      case "function_call": {
+        if (typeof item.name !== "string" || !item.name) {
+          throw new ResponsesBridgeError(400, "function_call without `name`.");
+        }
+        const callId = typeof item.call_id === "string" && item.call_id ? item.call_id : newId("call");
+        messages.push({
+          role: "assistant",
+          content: "",
+          tool_calls: [
+            {
+              id: callId,
+              type: "function",
+              function: { name: item.name, arguments: typeof item.arguments === "string" ? item.arguments : "{}" },
+            },
+          ],
+        });
+        break;
+      }
+      case "custom_tool_call": {
+        if (typeof item.name !== "string" || !item.name) {
+          throw new ResponsesBridgeError(400, "custom_tool_call without `name`.");
+        }
+        customToolNames.add(item.name);
+        const callId = typeof item.call_id === "string" && item.call_id ? item.call_id : newId("call");
+        const inputText = typeof item.input === "string" ? item.input : "";
+        messages.push({
+          role: "assistant",
+          content: "",
+          tool_calls: [
+            {
+              id: callId,
+              type: "function",
+              function: { name: item.name, arguments: JSON.stringify({ input: inputText }) },
+            },
+          ],
+        });
+        break;
+      }
+      case "function_call_output": {
+        if (typeof item.call_id !== "string" || !item.call_id) {
+          throw new ResponsesBridgeError(400, "function_call_output without `call_id`.");
+        }
+        messages.push({
+          role: "tool",
+          tool_call_id: item.call_id,
+          content: typeof item.output === "string" ? item.output : JSON.stringify(item.output ?? ""),
+        });
+        break;
+      }
+      case "reasoning":
+        // Encrypted reasoning cannot be forwarded to chat upstream — drop.
+        break;
+      default:
+        throw new ResponsesBridgeError(400, `Unknown input item: "${String(type)}".`);
+    }
+  }
+  if (!messages.length || messages.every((m) => m.role === "system" && !m.content)) {
+    throw new ResponsesBridgeError(400, "No messages to send (empty input).");
+  }
+
+  const request = { model, messages };
+  if (body.stream === true) request.stream = true;
+
+  if (Array.isArray(body.tools) && body.tools.length) {
+    const tools = [];
+    for (const tool of body.tools) {
+      if (!tool || typeof tool !== "object") continue;
+      if (tool.type === "function") {
+        if (typeof tool.name !== "string" || !tool.name) {
+          throw new ResponsesBridgeError(400, "Function tool without `name`.");
+        }
+        const fn = {
+          name: tool.name,
+          ...(typeof tool.description === "string" ? { description: tool.description } : {}),
+          parameters:
+            tool.parameters && typeof tool.parameters === "object" ? tool.parameters : { type: "object", properties: {} },
+        };
+        if (tool.strict === true) fn.strict = true;
+        tools.push({ type: "function", function: fn });
+      } else if (tool.type === "custom") {
+        if (typeof tool.name !== "string" || !tool.name) {
+          throw new ResponsesBridgeError(400, "Custom tool without `name`.");
+        }
+        customToolNames.add(tool.name);
+        tools.push({
+          type: "function",
+          function: {
+            name: tool.name,
+            ...(typeof tool.description === "string" ? { description: tool.description } : {}),
+            parameters: {
+              type: "object",
+              properties: { input: { type: "string", description: "Freeform input for the tool." } },
+              required: ["input"],
+              additionalProperties: false,
+            },
+          },
+        });
+      }
+      // Other tool types (web_search etc.) cannot be honored upstream — skipped.
+    }
+    if (tools.length) request.tools = tools;
+  }
+
+  const toolChoice = mapToolChoice(body.tool_choice);
+  if (toolChoice !== undefined) request.tool_choice = toolChoice;
+  if (typeof body.max_output_tokens === "number" && Number.isFinite(body.max_output_tokens)) {
+    request.max_tokens = Math.max(1, Math.floor(body.max_output_tokens));
+  }
+  if (typeof body.temperature === "number") request.temperature = body.temperature;
+  if (typeof body.top_p === "number") request.top_p = body.top_p;
+  if (typeof body.parallel_tool_calls === "boolean") request.parallel_tool_calls = body.parallel_tool_calls;
+  if (body.reasoning && typeof body.reasoning === "object") {
+    const effort = body.reasoning.effort;
+    if (typeof effort === "string" && REASONING_EFFORTS.has(effort)) request.reasoning_effort = effort;
+  }
+
+  return { request, customToolNames };
+}
+
+function mapUsage(usage) {
+  if (!usage || typeof usage !== "object") return undefined;
+  const input = Number(usage.prompt_tokens ?? 0);
+  const output = Number(usage.completion_tokens ?? 0);
+  return {
+    input_tokens: input,
+    input_tokens_details: { cached_tokens: Number(usage.prompt_tokens_details?.cached_tokens ?? 0) },
+    output_tokens: output,
+    output_tokens_details: { reasoning_tokens: Number(usage.completion_tokens_details?.reasoning_tokens ?? 0) },
+    total_tokens: Number(usage.total_tokens ?? input + output),
+  };
+}
+
+function tryParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function toolCallToOutputItem(call, customToolNames) {
+  const name = call?.function?.name ?? "";
+  const callId = typeof call?.id === "string" && call.id ? call.id : newId("call");
+  const args = typeof call?.function?.arguments === "string" ? call.function.arguments : "";
+  if (customToolNames.has(name)) {
+    const parsed = tryParseJson(args);
+    const input = parsed && typeof parsed.input === "string" ? parsed.input : args;
+    return { type: "custom_tool_call", id: newId("ctc"), call_id: callId, name, input };
+  }
+  return {
+    type: "function_call",
+    id: newId("fc"),
+    call_id: callId,
+    name,
+    arguments: args,
+    status: "completed",
+  };
+}
+
+function baseResponse(id, createdAt, model) {
+  return {
+    id,
+    object: "response",
+    created_at: createdAt,
+    status: "in_progress",
+    background: false,
+    error: null,
+    incomplete_details: null,
+    instructions: null,
+    max_output_tokens: null,
+    model,
+    output: [],
+    parallel_tool_calls: true,
+    previous_response_id: null,
+    reasoning: { effort: null, summary: null },
+    store: false,
+    temperature: null,
+    text: { format: { type: "text" } },
+    tool_choice: "auto",
+    tools: [],
+    top_p: null,
+    truncation: "disabled",
+    usage: null,
+    metadata: {},
+  };
+}
+
+/** Chat completion JSON (non-stream) → Responses object. */
+export function chatJsonToResponse(chat, { requestedModel, customToolNames = new Set(), responseId, createdAt } = {}) {
+  const id = responseId ?? newId("resp");
+  const created = createdAt ?? (typeof chat?.created === "number" ? chat.created : Math.floor(Date.now() / 1000));
+  const response = baseResponse(id, created, requestedModel ?? chat?.model ?? "unknown");
+
+  const choice = Array.isArray(chat?.choices) ? chat.choices[0] : undefined;
+  const message = choice?.message ?? {};
+  const finish = choice?.finish_reason ?? "stop";
+
+  const text = toText(message.content);
+  if (text) {
+    response.output.push({
+      type: "message",
+      id: newId("msg"),
+      status: "completed",
+      role: "assistant",
+      content: [{ type: "output_text", text, annotations: [] }],
+    });
+  }
+  if (Array.isArray(message.tool_calls)) {
+    for (const call of message.tool_calls) {
+      response.output.push(toolCallToOutputItem(call, customToolNames));
+    }
+  }
+
+  response.status = finish === "length" ? "incomplete" : "completed";
+  if (finish === "length") response.incomplete_details = { reason: "max_output_tokens" };
+  response.usage = mapUsage(chat?.usage) ?? null;
+  return response;
+}
+
+// ------------------------------------------------------------------ streaming
+
+function encodeSse(event, data, seq) {
+  return `event: ${event}\ndata: ${JSON.stringify({ ...data, sequence_number: seq })}\n\n`;
+}
+
+/**
+ * Wrap a chat.completion.chunk stream (SSE byte ReadableStream from the gateway)
+ * into a Responses API event stream. `upstream` is a web ReadableStream
+ * (response.body from fetch).
+ */
+export function wrapResponsesStream(upstream, { requestedModel, customToolNames = new Set(), responseId, createdAt } = {}) {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const id = responseId ?? newId("resp");
+  const created = createdAt ?? Math.floor(Date.now() / 1000);
+  const model = requestedModel ?? "unknown";
+  const finalResponse = baseResponse(id, created, model);
+
+  return new ReadableStream({
+    async start(controller) {
+      let seq = 0;
+      const send = (event, data) => controller.enqueue(encoder.encode(encodeSse(event, data, ++seq)));
+
+      // Open item state
+      let textOpen = false;
+      let textItemId = null;
+      let textBuffer = "";
+      let textOutputIndex = -1;
+      const toolStates = new Map(); // upstream tool_call.index → state
+      let nextOutputIndex = 0;
+      let usageFinal;
+      let finishReason = null;
+
+      const openText = () => {
+        textOpen = true;
+        textItemId = newId("msg");
+        textOutputIndex = nextOutputIndex++;
+        send("response.output_item.added", {
+          type: "response.output_item.added",
+          output_index: textOutputIndex,
+          item: { type: "message", id: textItemId, status: "in_progress", role: "assistant", content: [] },
+        });
+        send("response.content_part.added", {
+          type: "response.content_part.added",
+          item_id: textItemId,
+          output_index: textOutputIndex,
+          content_index: 0,
+          part: { type: "output_text", text: "", annotations: [] },
+        });
+      };
+
+      const closeText = () => {
+        if (!textOpen) return;
+        send("response.output_text.done", {
+          type: "response.output_text.done",
+          item_id: textItemId,
+          output_index: textOutputIndex,
+          content_index: 0,
+          text: textBuffer,
+        });
+        const part = { type: "output_text", text: textBuffer, annotations: [] };
+        send("response.content_part.done", {
+          type: "response.content_part.done",
+          item_id: textItemId,
+          output_index: textOutputIndex,
+          content_index: 0,
+          part,
+        });
+        send("response.output_item.done", {
+          type: "response.output_item.done",
+          output_index: textOutputIndex,
+          item: { type: "message", id: textItemId, status: "completed", role: "assistant", content: [part] },
+        });
+        finalResponse.output.push({
+          type: "message",
+          id: textItemId,
+          status: "completed",
+          role: "assistant",
+          content: [part],
+        });
+        textOpen = false;
+      };
+
+      const openTool = (idx, callId, name) => {
+        const custom = customToolNames.has(name);
+        const state = {
+          outputIndex: nextOutputIndex++,
+          itemId: newId(custom ? "ctc" : "fc"),
+          callId: callId || newId("call"),
+          name,
+          custom,
+          args: "",
+          closed: false,
+        };
+        toolStates.set(idx, state);
+        const item = custom
+          ? { type: "custom_tool_call", id: state.itemId, call_id: state.callId, name, input: "" }
+          : { type: "function_call", id: state.itemId, call_id: state.callId, name, arguments: "", status: "in_progress" };
+        send("response.output_item.added", { type: "response.output_item.added", output_index: state.outputIndex, item });
+        return state;
+      };
+
+      const closeTool = (state) => {
+        if (state.closed) return;
+        state.closed = true;
+        if (state.custom) {
+          const parsed = tryParseJson(state.args);
+          const input = parsed && typeof parsed.input === "string" ? parsed.input : state.args;
+          send("response.custom_tool_call_input.done", {
+            type: "response.custom_tool_call_input.done",
+            item_id: state.itemId,
+            output_index: state.outputIndex,
+            input,
+          });
+          send("response.output_item.done", {
+            type: "response.output_item.done",
+            output_index: state.outputIndex,
+            item: { type: "custom_tool_call", id: state.itemId, call_id: state.callId, name: state.name, input },
+          });
+          finalResponse.output.push({
+            type: "custom_tool_call",
+            id: state.itemId,
+            call_id: state.callId,
+            name: state.name,
+            input,
+          });
+        } else {
+          send("response.function_call_arguments.done", {
+            type: "response.function_call_arguments.done",
+            item_id: state.itemId,
+            output_index: state.outputIndex,
+            arguments: state.args,
+          });
+          send("response.output_item.done", {
+            type: "response.output_item.done",
+            output_index: state.outputIndex,
+            item: {
+              type: "function_call",
+              id: state.itemId,
+              call_id: state.callId,
+              name: state.name,
+              arguments: state.args,
+              status: "completed",
+            },
+          });
+          finalResponse.output.push({
+            type: "function_call",
+            id: state.itemId,
+            call_id: state.callId,
+            name: state.name,
+            arguments: state.args,
+            status: "completed",
+          });
+        }
+      };
+
+      const finalize = () => {
+        closeText();
+        for (const state of toolStates.values()) closeTool(state);
+        finalResponse.status = finishReason === "length" ? "incomplete" : "completed";
+        if (finishReason === "length") finalResponse.incomplete_details = { reason: "max_output_tokens" };
+        const mapped = mapUsage(usageFinal);
+        if (mapped) finalResponse.usage = mapped;
+        send("response.completed", { type: "response.completed", response: finalResponse });
+      };
+
+      const handleChunk = (chunk) => {
+        if (!chunk || typeof chunk !== "object") return;
+        if (chunk.error) {
+          const message = typeof chunk.error === "string" ? chunk.error : (chunk.error.message ?? "upstream error");
+          send("response.failed", {
+            type: "response.failed",
+            response: { ...finalResponse, status: "failed", error: { code: "upstream_error", message } },
+          });
+          finishReason = "__failed__";
+          return;
+        }
+        if (chunk.usage) usageFinal = chunk.usage;
+        const choice = Array.isArray(chunk.choices) ? chunk.choices[0] : undefined;
+        if (!choice) return; // chunk usage-only
+        const delta = choice.delta ?? {};
+
+        if (typeof delta.content === "string" && delta.content) {
+          if (!textOpen) openText();
+          textBuffer += delta.content;
+          send("response.output_text.delta", {
+            type: "response.output_text.delta",
+            item_id: textItemId,
+            output_index: textOutputIndex,
+            content_index: 0,
+            delta: delta.content,
+          });
+        }
+        // reasoning_content is not translated (no valid signature).
+
+        if (Array.isArray(delta.tool_calls)) {
+          if (textOpen) closeText(); // tool call after text → separate item
+          for (const tc of delta.tool_calls) {
+            const idx = typeof tc.index === "number" ? tc.index : 0;
+            let state = toolStates.get(idx);
+            if (!state) state = openTool(idx, tc.id, tc.function?.name ?? "");
+            if (typeof tc.id === "string" && tc.id) state.callId = tc.id;
+            if (typeof tc.function?.name === "string" && tc.function.name) state.name = tc.function.name;
+            const argDelta = typeof tc.function?.arguments === "string" ? tc.function.arguments : "";
+            if (argDelta) {
+              state.args += argDelta;
+              send(state.custom ? "response.custom_tool_call_input.delta" : "response.function_call_arguments.delta", {
+                type: state.custom ? "response.custom_tool_call_input.delta" : "response.function_call_arguments.delta",
+                item_id: state.itemId,
+                output_index: state.outputIndex,
+                delta: argDelta,
+              });
+            }
+          }
+        }
+        if (typeof choice.finish_reason === "string" && choice.finish_reason) {
+          finishReason = choice.finish_reason;
+        }
+      };
+
+      // ---- send opening events
+      send("response.created", { type: "response.created", response: baseResponse(id, created, model) });
+      send("response.in_progress", { type: "response.in_progress", response: baseResponse(id, created, model) });
+
+      const reader = upstream.getReader();
+      let buffer = "";
+      let failed = false;
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          let sep;
+          while ((sep = buffer.indexOf("\n\n")) >= 0) {
+            const rawEvent = buffer.slice(0, sep);
+            buffer = buffer.slice(sep + 2);
+            const dataLines = [];
+            for (const line of rawEvent.split("\n")) {
+              if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+            }
+            if (!dataLines.length) continue;
+            const payload = dataLines.join("\n");
+            if (payload === "[DONE]") continue;
+            let chunk;
+            try {
+              chunk = JSON.parse(payload);
+            } catch {
+              continue; // ignore unknown frame
+            }
+            handleChunk(chunk);
+            if (finishReason === "__failed__") {
+              failed = true;
+              break;
+            }
+          }
+          if (failed) break;
+        }
+      } catch (err) {
+        send("response.failed", {
+          type: "response.failed",
+          response: {
+            ...finalResponse,
+            status: "failed",
+            error: { code: "stream_error", message: err?.message ?? "stream error" },
+          },
+        });
+        failed = true;
+      } finally {
+        try {
+          await reader.cancel();
+        } catch {
+          /* ignore */
+        }
+      }
+
+      if (!failed) {
+        finalize();
+      }
+      controller.close();
+    },
+  });
+}