@velum-labs/routekit-gateway 0.9.0

package/dist/adapters/chat.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OpenAI Chat Completions surface. This is the gateway's "core" dialect: it is
+ * what OpenAI-compatible providers speak, what opencode and the Cursor IDE
+ * consume directly, and what the Anthropic and Responses adapters translate
+ * down to. The handlers here are deliberately thin — the request is forwarded
+ * to the backend and the upstream response (including SSE streams) is piped
+ * straight back — so the only logic is filling in a default model.
+ */
+/** Fill in `model` from the backend default when the caller omitted it. */
+export declare function withDefaultModel(body: unknown, defaultModel: string | undefined): unknown;
+/** Whether a chat/completions request asked for a streamed response. */
+export declare function isStream(body: unknown): boolean;
+/** The model id a request will run as, after default injection. */
+export declare function effectiveModel(body: unknown, defaultModel: string | undefined): string | undefined;

package/dist/adapters/chat.js

@@ -0,0 +1,34 @@
+/**
+ * OpenAI Chat Completions surface. This is the gateway's "core" dialect: it is
+ * what OpenAI-compatible providers speak, what opencode and the Cursor IDE
+ * consume directly, and what the Anthropic and Responses adapters translate
+ * down to. The handlers here are deliberately thin — the request is forwarded
+ * to the backend and the upstream response (including SSE streams) is piped
+ * straight back — so the only logic is filling in a default model.
+ */
+function asObject(body) {
+    if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+        return body;
+    }
+    return undefined;
+}
+/** Fill in `model` from the backend default when the caller omitted it. */
+export function withDefaultModel(body, defaultModel) {
+    if (defaultModel === undefined)
+        return body;
+    const obj = asObject(body);
+    if (obj === undefined || obj.model !== undefined)
+        return body;
+    return { ...obj, model: defaultModel };
+}
+/** Whether a chat/completions request asked for a streamed response. */
+export function isStream(body) {
+    return asObject(body)?.stream === true;
+}
+/** The model id a request will run as, after default injection. */
+export function effectiveModel(body, defaultModel) {
+    const model = asObject(body)?.model;
+    if (typeof model === "string")
+        return model;
+    return defaultModel;
+}

package/dist/adapters/cursor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Translate Cursor's BYOK request hybrid into OpenAI Chat Completions.
+ *
+ * When Cursor's "Override OpenAI Base URL" feature is active, Cursor POSTs to
+ * `{base_url}/chat/completions` but — for agent mode and GPT-family routing —
+ * the JSON body is shaped like the OpenAI *Responses* API (`input` item list,
+ * flat tool definitions, `reasoning`/`text` objects), while the response it
+ * renders is standard Chat Completions SSE. This module is the pure
+ * translation layer behind the `/v1/cursor/*` routes. It maps the
+ * Responses-hybrid body onto
+ * the Chat Completions shape the rest of the gateway already handles.
+ *
+ * No I/O happens here. The translation is total: weird-but-parseable input is
+ * never a reason to throw — unknown item and tool types are dropped so the
+ * boundary stays defensive without 4xx-ing on new shapes.
+ */
+type JsonObject = Record<string, unknown>;
+/**
+ * Whether a parsed request body is routable by the cursor route: a JSON
+ * object carrying either `messages` (plain Chat Completions, e.g. Ask mode)
+ * or `input` (the Responses hybrid). Rejecting other shapes is the route's
+ * job; the translation itself stays total.
+ */
+export declare function isCursorChatBody(body: unknown): body is JsonObject;
+/**
+ * Map a Cursor BYOK request body onto a Chat Completions body.
+ *
+ * Dual-shape tolerance: Cursor only sends the Responses hybrid for some
+ * models/modes; Ask mode may send plain Chat Completions. A body that
+ * already carries `messages` is returned unchanged; a body with `input`
+ * is translated. A body with neither yields an empty `messages` list.
+ */
+export declare function translateCursorRequest(body: JsonObject): JsonObject;
+export {};

package/dist/adapters/cursor.js

@@ -0,0 +1,305 @@
+/**
+ * Translate Cursor's BYOK request hybrid into OpenAI Chat Completions.
+ *
+ * When Cursor's "Override OpenAI Base URL" feature is active, Cursor POSTs to
+ * `{base_url}/chat/completions` but — for agent mode and GPT-family routing —
+ * the JSON body is shaped like the OpenAI *Responses* API (`input` item list,
+ * flat tool definitions, `reasoning`/`text` objects), while the response it
+ * renders is standard Chat Completions SSE. This module is the pure
+ * translation layer behind the `/v1/cursor/*` routes. It maps the
+ * Responses-hybrid body onto
+ * the Chat Completions shape the rest of the gateway already handles.
+ *
+ * No I/O happens here. The translation is total: weird-but-parseable input is
+ * never a reason to throw — unknown item and tool types are dropped so the
+ * boundary stays defensive without 4xx-ing on new shapes.
+ */
+import { droppedField } from "./dropped.js";
+import { attachReasoningSelection, attachReasoningSelectionError } from "./openai-chat-wire.js";
+/** Fields copied through unchanged when present and non-null. */
+const PASSTHROUGH_FIELDS = ["model", "temperature", "top_p", "top_k", "tool_choice", "stream", "parallel_tool_calls"];
+/**
+ * Permissive schema built for grammar-based ("custom") tools that
+ * declare no JSON schema of their own; the model's call output flows back as
+ * a normal function tool call with the raw text under `input`.
+ */
+const CUSTOM_TOOL_PARAMETERS = {
+    type: "object",
+    properties: { input: { type: "string" } },
+    required: ["input"]
+};
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether a parsed request body is routable by the cursor route: a JSON
+ * object carrying either `messages` (plain Chat Completions, e.g. Ask mode)
+ * or `input` (the Responses hybrid). Rejecting other shapes is the route's
+ * job; the translation itself stays total.
+ */
+export function isCursorChatBody(body) {
+    return isObject(body) && ("messages" in body || "input" in body);
+}
+/**
+ * Map a Cursor BYOK request body onto a Chat Completions body.
+ *
+ * Dual-shape tolerance: Cursor only sends the Responses hybrid for some
+ * models/modes; Ask mode may send plain Chat Completions. A body that
+ * already carries `messages` is returned unchanged; a body with `input`
+ * is translated. A body with neither yields an empty `messages` list.
+ */
+export function translateCursorRequest(body) {
+    if ("messages" in body) {
+        const passthrough = { ...body };
+        if (passthrough.stream === true) {
+            passthrough.stream_options = { include_usage: true };
+        }
+        return passthrough;
+    }
+    const translated = {};
+    for (const key of PASSTHROUGH_FIELDS) {
+        if (key in body && body[key] !== null && body[key] !== undefined) {
+            translated[key] = body[key];
+        }
+    }
+    translated.messages = inputItemsToMessages(body.input);
+    const tools = translateTools(body.tools);
+    if (tools !== undefined)
+        translated.tools = tools;
+    translateSampling(body, translated);
+    translateReasoning(body, translated);
+    translateTextFormat(body, translated);
+    if (translated.stream === true) {
+        translated.stream_options = { include_usage: true };
+    }
+    return translated;
+}
+/**
+ * Flatten a Responses-API `input` item list into chat messages.
+ *
+ * Handles message items (typed or bare role/content objects),
+ * `function_call` items (folded into assistant `tool_calls`, merging
+ * consecutive calls of the same assistant turn), `function_call_output`
+ * items (`tool` messages), and drops `reasoning` and unknown items.
+ */
+function inputItemsToMessages(items) {
+    if (typeof items === "string") {
+        // The Responses API also accepts a plain string as the whole input.
+        return [{ role: "user", content: items }];
+    }
+    if (!Array.isArray(items))
+        return [];
+    const messages = [];
+    for (const item of items) {
+        if (!isObject(item))
+            continue;
+        const kind = item.type;
+        if (kind === undefined || kind === null || kind === "message") {
+            messages.push(messageFromItem(item));
+        }
+        else if (kind === "function_call") {
+            appendFunctionCall(messages, item);
+        }
+        else if (kind === "function_call_output") {
+            messages.push({
+                role: "tool",
+                tool_call_id: asStr(item.call_id),
+                content: stringify(item.output)
+            });
+        }
+        else if (kind === "reasoning") {
+            droppedField("cursor", "reasoning", "input");
+        }
+        else if (kind !== undefined && kind !== null) {
+            droppedField("cursor", asStr(kind), "input");
+        }
+    }
+    return messages;
+}
+function messageFromItem(item) {
+    let role = item.role;
+    if (role === "developer")
+        role = "system";
+    if (role !== "system" && role !== "user" && role !== "assistant" && role !== "tool") {
+        role = "user";
+    }
+    return { role, content: contentText(item.content) };
+}
+/**
+ * Concatenate the text parts of a Responses content value.
+ *
+ * Accepts a plain string or a parts list (`input_text` / `output_text` /
+ * anything else carrying a string `text`); non-text parts such as
+ * `input_image` are ignored rather than rejected.
+ */
+function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const part of content) {
+            if (typeof part === "string")
+                parts.push(part);
+            else if (isObject(part)) {
+                if (part.type === "input_file") {
+                    droppedField("cursor", "input_file");
+                    continue;
+                }
+                if (part.type === "refusal" && typeof part.text === "string") {
+                    parts.push(part.text);
+                    continue;
+                }
+                if (typeof part.text === "string")
+                    parts.push(part.text);
+            }
+        }
+        return parts.join("");
+    }
+    return "";
+}
+/**
+ * Fold a `function_call` item into the current assistant turn.
+ *
+ * Consecutive function calls after the same assistant message extend that
+ * message's `tool_calls` list; otherwise a new assistant message opens.
+ */
+function appendFunctionCall(messages, item) {
+    const call = {
+        id: asStr(item.call_id) || asStr(item.id),
+        type: "function",
+        function: {
+            name: asStr(item.name),
+            arguments: stringify(item.arguments) || "{}"
+        }
+    };
+    const last = messages.length > 0 ? messages[messages.length - 1] : undefined;
+    if (last !== undefined && last.role === "assistant") {
+        if (!Array.isArray(last.tool_calls))
+            last.tool_calls = [];
+        last.tool_calls.push(call);
+        return;
+    }
+    messages.push({ role: "assistant", content: "", tool_calls: [call] });
+}
+/**
+ * Map Responses tool definitions onto Chat Completions nested tools.
+ *
+ * Cursor sends flat function tools (`{type: "function", name, ...}`) and
+ * grammar-based custom tools (`{type: "custom", name, format}`). Flat tools
+ * are nested under `function`; custom tools become plain function tools with
+ * their declared schema or a permissive generated one. Already-nested
+ * tools pass through unchanged; other typed entries are forwarded as-is for
+ * the gateway's downstream tool normalization.
+ */
+function translateTools(tools) {
+    if (!Array.isArray(tools) || tools.length === 0)
+        return undefined;
+    const translated = [];
+    for (const entry of tools) {
+        if (!isObject(entry))
+            continue;
+        if (isObject(entry.function)) {
+            translated.push(entry);
+            continue;
+        }
+        const kind = entry.type;
+        if (kind === "function") {
+            translated.push(nestedFunctionTool(entry, defaultParameters(entry)));
+        }
+        else if (kind === "custom") {
+            translated.push(nestedFunctionTool(entry, customParameters(entry)));
+        }
+        else {
+            // Typed nameless tools (e.g. web_search) and future shapes flow
+            // through; the downstream tool normalization decides their fate.
+            translated.push(entry);
+        }
+    }
+    return translated.length > 0 ? translated : undefined;
+}
+function nestedFunctionTool(entry, parameters) {
+    return {
+        type: "function",
+        function: {
+            name: asStr(entry.name),
+            description: asStr(entry.description),
+            parameters
+        }
+    };
+}
+function defaultParameters(entry) {
+    if (isObject(entry.parameters))
+        return entry.parameters;
+    return { type: "object", properties: {} };
+}
+function customParameters(entry) {
+    if (isObject(entry.parameters))
+        return entry.parameters;
+    return { ...CUSTOM_TOOL_PARAMETERS };
+}
+/** Fold Responses sampling names into Chat Completions ones in place. */
+function translateSampling(body, translated) {
+    const maxTokens = body.max_output_tokens ?? body.max_tokens;
+    if (typeof maxTokens === "number" && Number.isInteger(maxTokens)) {
+        translated.max_completion_tokens = maxTokens;
+    }
+}
+function translateReasoning(body, translated) {
+    const reasoning = body.reasoning;
+    if (reasoning === undefined || reasoning === null)
+        return;
+    if (!isObject(reasoning)) {
+        attachReasoningSelectionError(translated, "reasoning must contain a non-empty effort string");
+        return;
+    }
+    const effort = reasoning.effort;
+    if (typeof effort === "string" && effort.length > 0) {
+        translated.reasoning_effort = effort;
+        attachReasoningSelection(translated, { mode: "effort", effort });
+        return;
+    }
+    attachReasoningSelectionError(translated, "reasoning.effort must be a non-empty string");
+}
+function translateTextFormat(body, translated) {
+    const text = body.text;
+    if (!isObject(text))
+        return;
+    const format = text.format;
+    if (!isObject(format) || typeof format.type !== "string")
+        return;
+    switch (format.type) {
+        case "json_schema":
+            translated.response_format = {
+                type: "json_schema",
+                json_schema: {
+                    ...(typeof format.name === "string" ? { name: format.name } : {}),
+                    ...(format.schema !== undefined ? { schema: format.schema } : {}),
+                    ...(typeof format.strict === "boolean" ? { strict: format.strict } : {})
+                }
+            };
+            break;
+        case "json_object":
+            translated.response_format = { type: "json_object" };
+            break;
+        default:
+            droppedField("cursor", "text");
+            break;
+    }
+}
+function asStr(value) {
+    return typeof value === "string" ? value : "";
+}
+/** Stringify a non-string tool output/arguments value losslessly. */
+function stringify(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === null || value === undefined)
+        return "";
+    try {
+        const encoded = JSON.stringify(value);
+        return encoded === undefined ? String(value) : encoded;
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/adapters/dropped.d.ts

@@ -0,0 +1,10 @@
+export type DialectName = "anthropic" | "responses" | "cursor";
+export declare const DIALECT_DROPPED_ATTRIBUTE = "routekit.dialect.dropped";
+export type DroppedFieldSpan = {
+    span: {
+        setAttribute(name: string, value: string[]): unknown;
+    };
+};
+export declare function withDroppedFieldSpan<T>(span: DroppedFieldSpan, fn: () => T): T;
+export declare function droppedField(dialect: DialectName, field: string, context?: string): void;
+export declare function resetDroppedFieldWarnings(): void;

package/dist/adapters/dropped.js

@@ -0,0 +1,24 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const DIALECT_DROPPED_ATTRIBUTE = "routekit.dialect.dropped";
+const ambientSpan = new AsyncLocalStorage();
+const spanEntries = new WeakMap();
+const warned = new Set();
+export function withDroppedFieldSpan(span, fn) {
+    return ambientSpan.run(span, fn);
+}
+export function droppedField(dialect, field, context) {
+    const entry = context !== undefined ? `${dialect}.${context}.${field}` : `${dialect}.${field}`;
+    const target = ambientSpan.getStore()?.span;
+    if (target !== undefined) {
+        const entries = [...(spanEntries.get(target) ?? []), entry];
+        spanEntries.set(target, entries);
+        target.setAttribute(DIALECT_DROPPED_ATTRIBUTE, entries);
+    }
+    if (warned.has(entry))
+        return;
+    warned.add(entry);
+    process.stderr.write(`routekit gateway: ${dialect} field "${context !== undefined ? `${context}.` : ""}${field}" is not translated and was dropped\n`);
+}
+export function resetDroppedFieldWarnings() {
+    warned.clear();
+}

package/dist/adapters/openai-chat-wire.d.ts

@@ -0,0 +1,93 @@
+import type { ReasoningSelection } from "@velum-labs/routekit-contracts";
+export type OpenAiToolCall = {
+    id?: string;
+    index?: number;
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+};
+/**
+ * Lossless Anthropic reasoning metadata carried beside the portable
+ * `reasoning` string. Native Anthropic streams need block lifecycle and opaque
+ * signatures to survive a round trip; other dialects can ignore this field.
+ */
+export type AnthropicReasoningDetail = {
+    type: "thinking";
+    index: number;
+    phase?: "start" | "delta" | "signature" | "stop";
+    thinking?: string;
+    signature?: string;
+} | {
+    type: "redacted_thinking";
+    index: number;
+    phase?: "block";
+    data: string;
+};
+export declare function anthropicReasoningDetailsOf(value: unknown, mode: "message" | "stream"): AnthropicReasoningDetail[];
+export type AnthropicThinkingConfig = {
+    type: "enabled";
+    budget_tokens: number;
+    display?: "summarized" | "omitted" | null;
+} | {
+    type: "adaptive";
+    display?: "summarized" | "omitted" | null;
+} | {
+    type: "disabled";
+};
+export type AnthropicRequestMetadata = {
+    thinking?: AnthropicThinkingConfig;
+    output_config?: {
+        effort?: string | null;
+        [key: string]: unknown;
+    } | null;
+};
+/**
+ * Symbol-keyed metadata stays in-process through object spreads while
+ * JSON.stringify omits it. This lets an Anthropic backend receive exact native
+ * controls/history without leaking Anthropic-only fields to OpenAI providers.
+ */
+export declare const ANTHROPIC_REQUEST_METADATA: unique symbol;
+export declare const ANTHROPIC_MESSAGE_CONTENT: unique symbol;
+export declare const REASONING_SELECTION: unique symbol;
+export declare const REASONING_SELECTION_ERROR: unique symbol;
+export declare function attachReasoningSelection(target: Record<PropertyKey, unknown>, selection: ReasoningSelection): void;
+export declare function attachReasoningSelectionError(target: Record<PropertyKey, unknown>, message: string): void;
+export declare function reasoningSelectionErrorOf(value: unknown): string | undefined;
+export declare function reasoningSelectionOf(value: unknown): ReasoningSelection;
+export type AnthropicNativeContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    thinking: string;
+    signature: string;
+} | {
+    type: "redacted_thinking";
+    data: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+};
+export type OpenAiDelta = {
+    content?: string | null;
+    reasoning?: string | null;
+    reasoning_content?: string | null;
+    reasoning_details?: AnthropicReasoningDetail[];
+    tool_calls?: OpenAiToolCall[];
+};
+export type OpenAiChoice = {
+    delta?: OpenAiDelta;
+    message?: {
+        content?: string | null;
+        reasoning?: string | null;
+        reasoning_content?: string | null;
+        reasoning_details?: AnthropicReasoningDetail[];
+        tool_calls?: OpenAiToolCall[];
+    };
+    finish_reason?: string | null;
+    anthropic_stop_reason?: string | null;
+    anthropic_stop_sequence?: string | null;
+};

package/dist/adapters/openai-chat-wire.js

@@ -0,0 +1,143 @@
+export function anthropicReasoningDetailsOf(value, mode) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((candidate) => {
+        if (candidate === null ||
+            typeof candidate !== "object" ||
+            Array.isArray(candidate)) {
+            return [];
+        }
+        const detail = candidate;
+        if (!Number.isInteger(detail.index) ||
+            detail.index < 0) {
+            return [];
+        }
+        const index = detail.index;
+        if (detail.type === "redacted_thinking") {
+            if (typeof detail.data !== "string" ||
+                (mode === "stream" && detail.phase !== "block") ||
+                (mode === "message" && detail.phase !== undefined)) {
+                return [];
+            }
+            return [
+                {
+                    type: "redacted_thinking",
+                    index,
+                    ...(mode === "stream" ? { phase: "block" } : {}),
+                    data: detail.data
+                }
+            ];
+        }
+        if (detail.type !== "thinking")
+            return [];
+        if (mode === "message") {
+            if (detail.phase !== undefined ||
+                typeof detail.thinking !== "string" ||
+                typeof detail.signature !== "string") {
+                return [];
+            }
+            return [
+                {
+                    type: "thinking",
+                    index,
+                    thinking: detail.thinking,
+                    signature: detail.signature
+                }
+            ];
+        }
+        if (detail.phase === "start") {
+            if (detail.signature !== undefined &&
+                typeof detail.signature !== "string") {
+                return [];
+            }
+            return [
+                {
+                    type: "thinking",
+                    index,
+                    phase: "start",
+                    ...(typeof detail.signature === "string"
+                        ? { signature: detail.signature }
+                        : {})
+                }
+            ];
+        }
+        if (detail.phase === "delta" && typeof detail.thinking === "string") {
+            return [
+                {
+                    type: "thinking",
+                    index,
+                    phase: "delta",
+                    thinking: detail.thinking
+                }
+            ];
+        }
+        if (detail.phase === "signature" &&
+            typeof detail.signature === "string") {
+            return [
+                {
+                    type: "thinking",
+                    index,
+                    phase: "signature",
+                    signature: detail.signature
+                }
+            ];
+        }
+        if (detail.phase === "stop") {
+            return [{ type: "thinking", index, phase: "stop" }];
+        }
+        return [];
+    });
+}
+/**
+ * Symbol-keyed metadata stays in-process through object spreads while
+ * JSON.stringify omits it. This lets an Anthropic backend receive exact native
+ * controls/history without leaking Anthropic-only fields to OpenAI providers.
+ */
+export const ANTHROPIC_REQUEST_METADATA = Symbol.for("@velum-labs/routekit-gateway/anthropic-request-metadata");
+export const ANTHROPIC_MESSAGE_CONTENT = Symbol.for("@velum-labs/routekit-gateway/anthropic-message-content");
+export const REASONING_SELECTION = Symbol.for("@velum-labs/routekit-gateway/reasoning-selection");
+export const REASONING_SELECTION_ERROR = Symbol.for("@velum-labs/routekit-gateway/reasoning-selection-error");
+export function attachReasoningSelection(target, selection) {
+    Object.defineProperty(target, REASONING_SELECTION, {
+        value: selection,
+        enumerable: true
+    });
+}
+export function attachReasoningSelectionError(target, message) {
+    Object.defineProperty(target, REASONING_SELECTION_ERROR, {
+        value: message,
+        enumerable: true
+    });
+}
+export function reasoningSelectionErrorOf(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    const attachedError = record[REASONING_SELECTION_ERROR];
+    if (typeof attachedError === "string")
+        return attachedError;
+    if (Object.hasOwn(record, "reasoning_effort") &&
+        (typeof record.reasoning_effort !== "string" ||
+            record.reasoning_effort.length === 0)) {
+        return "reasoning_effort must be a non-empty string";
+    }
+    return undefined;
+}
+export function reasoningSelectionOf(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const record = value;
+        const attached = record[REASONING_SELECTION];
+        if (attached !== null &&
+            typeof attached === "object" &&
+            !Array.isArray(attached) &&
+            typeof attached.mode === "string") {
+            return attached;
+        }
+        if (typeof record.reasoning_effort === "string" &&
+            record.reasoning_effort.length > 0) {
+            return { mode: "effort", effort: record.reasoning_effort };
+        }
+    }
+    return { mode: "auto" };
+}

package/dist/adapters/responses-stream.d.ts

@@ -0,0 +1,7 @@
+type ResponsesToolKind = "function" | "custom" | "typed" | "server";
+type ResponsesToolRegistry = ReadonlyMap<string, {
+    kind: ResponsesToolKind;
+    namespace?: string;
+}>;
+export declare function openAiSseToResponses(upstream: ReadableStream<Uint8Array>, model: string, toolRegistry?: ResponsesToolRegistry): ReadableStream<Uint8Array>;
+export {};