@velum-labs/routekit-gateway 0.9.9 → 0.10.0

package/dist/adapters/anthropic.js

@@ -9,7 +9,7 @@
  */
 import { estimateTokens, randomId } from "@velum-labs/routekit-runtime";
 import { SseDecoder, SseParseError } from "../sse/parse.js";
-import { ANTHROPIC_MESSAGE_CONTENT, ANTHROPIC_REQUEST_METADATA, attachReasoningSelection, attachReasoningSelectionError, anthropicReasoningDetailsOf } from "./openai-chat-wire.js";
+import { attachAnthropicMessageContent, attachAnthropicRequestMetadata, attachReasoningSelection, attachReasoningSelectionError, anthropicReasoningDetailsOf } from "./openai-chat-wire.js";
 import { droppedField } from "./dropped.js";
 import { unwrapUpstreamError } from "./upstream-error.js";
 import { composeServerToolStream, runBufferedServerToolLoop, serverToolMarkerOf } from "./server-tool-loop.js";
@@ -122,12 +122,6 @@ function toolResultContent(result) {
     const text = blockText(result.content);
     return result.is_error === true ? `[tool_error]\n${text}` : text;
 }
-function attachAnthropicContent(message, content) {
-    Object.defineProperty(message, ANTHROPIC_MESSAGE_CONTENT, {
-        value: [...content],
-        enumerable: true
-    });
-}
 /**
  * Translate an Anthropic Messages request to an OpenAI Chat Completions body.
  * The upstream model is always the backend's own model (Claude Code sends a
@@ -266,7 +260,7 @@ export function anthropicToChat(body, backendModel, options = {}) {
                 if (toolCalls.length > 0)
                     assistant.tool_calls = toolCalls;
                 if (hasReplayableThinking)
-                    attachAnthropicContent(assistant, nativeContent);
+                    attachAnthropicMessageContent(assistant, nativeContent);
                 messages.push(assistant);
             }
             continue;
@@ -343,10 +337,7 @@ export function anthropicToChat(body, backendModel, options = {}) {
         ...(body.output_config !== undefined ? { output_config: body.output_config } : {})
     };
     if (Object.keys(metadata).length > 0) {
-        Object.defineProperty(chat, ANTHROPIC_REQUEST_METADATA, {
-            value: metadata,
-            enumerable: true
-        });
+        attachAnthropicRequestMetadata(chat, metadata);
     }
     if (Array.isArray(body.stop_sequences) && body.stop_sequences.length > 0) {
         chat.stop = body.stop_sequences;

package/dist/adapters/cursor.d.ts

@@ -14,6 +14,7 @@
  * never a reason to throw — unknown item and tool types are dropped so the
  * boundary stays defensive without 4xx-ing on new shapes.
  */
+import type { ModelReasoningCapabilities } from "@velum-labs/routekit-contracts";
 type JsonObject = Record<string, unknown>;
 /**
  * Whether a parsed request body is routable by the cursor route: a JSON
@@ -32,6 +33,25 @@ export declare function isCursorChatBody(body: unknown): body is JsonObject;
  * the OpenAI base-URL override. Deprecated: prefer `cursorModelName`.
  */
 export declare function cursorModelAliasId(id: string): string;
+export type CursorModelSelection = {
+    model: string;
+    reasoningEffort?: string;
+};
+/**
+ * Expand one served model into the opaque ids Cursor can put in its picker.
+ *
+ * Cursor's OpenAI-compatible BYOK path does not expose its reasoning picker,
+ * so each discovered effort is represented as a model-name variant instead.
+ */
+export declare function cursorModelVariants(id: string, reasoning: unknown): CursorModelSelection[];
+/**
+ * Resolve a Cursor-facing model variant back to its served model and effort.
+ *
+ * Exact served ids win before suffix parsing, so a provider model whose real
+ * id contains a colon remains addressable. Effort aliases are accepted but
+ * normalized to the provider's canonical id.
+ */
+export declare function resolveCursorModelSelection(model: unknown, servedIds: readonly string[], reasoningCapabilities?: (model: string) => ModelReasoningCapabilities | undefined): CursorModelSelection | undefined;
 /**
  * Resolve a Cursor-facing model name back to a served id.
  *

package/dist/adapters/cursor.js

@@ -14,9 +14,9 @@
  * never a reason to throw — unknown item and tool types are dropped so the
  * boundary stays defensive without 4xx-ing on new shapes.
  */
-import { stripCursorNamespace } from "@velum-labs/routekit-contracts";
+import { cursorModelName, resolveReasoningEffort, stripCursorNamespace } from "@velum-labs/routekit-contracts";
 import { droppedField } from "./dropped.js";
-import { attachReasoningSelection, attachReasoningSelectionError } from "./openai-chat-wire.js";
+import { attachReasoningSelection, attachReasoningSelectionError, hasExplicitReasoningSelection, reasoningSelectionErrorOf, reasoningSelectionOf } 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"];
 /**
@@ -53,6 +53,56 @@ export function isCursorChatBody(body) {
 export function cursorModelAliasId(id) {
     return id.replaceAll("/", "-");
 }
+/**
+ * Expand one served model into the opaque ids Cursor can put in its picker.
+ *
+ * Cursor's OpenAI-compatible BYOK path does not expose its reasoning picker,
+ * so each discovered effort is represented as a model-name variant instead.
+ */
+export function cursorModelVariants(id, reasoning) {
+    const variants = [{ model: cursorModelName(id) }];
+    if (!isObject(reasoning) || reasoning.status !== "supported")
+        return variants;
+    if (!Array.isArray(reasoning.efforts))
+        return variants;
+    const seen = new Set();
+    for (const option of reasoning.efforts) {
+        if (!isObject(option) || typeof option.id !== "string" || option.id.length === 0) {
+            continue;
+        }
+        if (seen.has(option.id))
+            continue;
+        seen.add(option.id);
+        variants.push({
+            model: cursorModelName(`${id}:${option.id}`),
+            reasoningEffort: option.id
+        });
+    }
+    return variants;
+}
+/**
+ * Resolve a Cursor-facing model variant back to its served model and effort.
+ *
+ * Exact served ids win before suffix parsing, so a provider model whose real
+ * id contains a colon remains addressable. Effort aliases are accepted but
+ * normalized to the provider's canonical id.
+ */
+export function resolveCursorModelSelection(model, servedIds, reasoningCapabilities) {
+    if (typeof model !== "string" || model.length === 0 || servedIds.includes(model)) {
+        return undefined;
+    }
+    const stripped = stripCursorNamespace(model);
+    const candidate = stripped ?? model;
+    if (servedIds.includes(candidate))
+        return { model: candidate };
+    const suffixed = resolveCursorReasoningSuffix(candidate, servedIds, reasoningCapabilities);
+    if (suffixed !== undefined)
+        return suffixed;
+    const legacy = servedIds.find((id) => id.includes("/") && cursorModelAliasId(id) === candidate);
+    if (legacy !== undefined)
+        return { model: legacy };
+    return resolveLegacyCursorReasoningSuffix(candidate, servedIds, reasoningCapabilities);
+}
 /**
  * Resolve a Cursor-facing model name back to a served id.
  *
@@ -61,14 +111,45 @@ export function cursorModelAliasId(id) {
  * served id or cannot be resolved.
  */
 export function resolveCursorModelAlias(model, servedIds) {
-    if (typeof model !== "string" || model.length === 0 || servedIds.includes(model)) {
+    return resolveCursorModelSelection(model, servedIds)?.model;
+}
+function resolveCursorReasoningSuffix(candidate, servedIds, reasoningCapabilities) {
+    if (reasoningCapabilities === undefined)
         return undefined;
+    for (const id of [...servedIds].sort((left, right) => right.length - left.length)) {
+        const prefix = `${id}:`;
+        if (!candidate.startsWith(prefix))
+            continue;
+        const requested = candidate.slice(prefix.length);
+        if (requested.length === 0)
+            continue;
+        const capabilities = reasoningCapabilities(id);
+        if (capabilities === undefined || capabilities.status !== "supported")
+            continue;
+        const effort = resolveReasoningEffort(capabilities, requested);
+        if (effort !== undefined)
+            return { model: id, reasoningEffort: effort };
     }
-    const stripped = stripCursorNamespace(model);
-    if (stripped !== undefined && servedIds.includes(stripped)) {
-        return stripped;
+    return undefined;
+}
+function resolveLegacyCursorReasoningSuffix(candidate, servedIds, reasoningCapabilities) {
+    if (reasoningCapabilities === undefined)
+        return undefined;
+    for (const id of servedIds) {
+        if (!id.includes("/"))
+            continue;
+        const prefix = `${cursorModelAliasId(id)}:`;
+        if (!candidate.startsWith(prefix))
+            continue;
+        const requested = candidate.slice(prefix.length);
+        const capabilities = reasoningCapabilities(id);
+        if (capabilities === undefined || capabilities.status !== "supported")
+            continue;
+        const effort = resolveReasoningEffort(capabilities, requested);
+        if (effort !== undefined)
+            return { model: id, reasoningEffort: effort };
     }
-    return servedIds.find((id) => id.includes("/") && cursorModelAliasId(id) === model);
+    return undefined;
 }
 /**
  * Map a Cursor BYOK request body onto a Chat Completions body.
@@ -93,11 +174,18 @@ export function translateCursorRequest(body) {
         }
     }
     translated.messages = inputItemsToMessages(body.input);
+    if (body.x_routekit !== undefined)
+        translated.x_routekit = body.x_routekit;
+    const originalSelectionError = reasoningSelectionErrorOf(body);
+    if (originalSelectionError !== undefined) {
+        attachReasoningSelectionError(translated, originalSelectionError);
+    }
     const tools = translateTools(body.tools);
     if (tools !== undefined)
         translated.tools = tools;
     translateSampling(body, translated);
-    translateReasoning(body, translated);
+    if (originalSelectionError === undefined)
+        translateReasoning(body, translated);
     translateTextFormat(body, translated);
     if (translated.stream === true) {
         translated.stream_options = { include_usage: true };
@@ -275,6 +363,10 @@ function translateSampling(body, translated) {
     }
 }
 function translateReasoning(body, translated) {
+    const hasCanonicalSelection = hasExplicitReasoningSelection(body);
+    if (hasCanonicalSelection) {
+        attachReasoningSelection(translated, reasoningSelectionOf(body));
+    }
     const reasoning = body.reasoning;
     if (reasoning === undefined || reasoning === null)
         return;
@@ -284,8 +376,10 @@ function translateReasoning(body, translated) {
     }
     const effort = reasoning.effort;
     if (typeof effort === "string" && effort.length > 0) {
-        translated.reasoning_effort = effort;
-        attachReasoningSelection(translated, { mode: "effort", effort });
+        if (!hasCanonicalSelection) {
+            translated.reasoning_effort = effort;
+            attachReasoningSelection(translated, { mode: "effort", effort });
+        }
         return;
     }
     attachReasoningSelectionError(translated, "reasoning.effort must be a non-empty string");

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

@@ -12,6 +12,13 @@ export type OpenAiToolCall = {
  * `reasoning` string. Native Anthropic streams need block lifecycle and opaque
  * signatures to survive a round trip; other dialects can ignore this field.
  */
+export type GoogleThoughtDetail = {
+    type: "google_thought";
+    index: number;
+    thought?: string;
+    thoughtSignature: string;
+};
+export declare function googleThoughtDetailsOf(value: unknown): GoogleThoughtDetail[];
 export type AnthropicReasoningDetail = {
     type: "thinking";
     index: number;
@@ -51,8 +58,76 @@ 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;
+/**
+ * Opaque OpenAI Responses reasoning state carried only inside the gateway.
+ * The symbol key survives in-process object spreads but is omitted by JSON,
+ * while the value itself is plain serializable data for deterministic replay
+ * by a Responses-capable provider backend.
+ */
+export declare const RESPONSES_REASONING_METADATA: unique symbol;
+export declare const GOOGLE_TOOL_CALL_INDEXES: unique symbol;
+export type ResponsesReasoningItem = {
+    type: "reasoning";
+    id?: string;
+    summary?: unknown;
+    content?: unknown;
+    encrypted_content: string;
+};
+export type ResponsesReasoningMetadata = {
+    items: ResponsesReasoningItem[];
+    includeEncryptedContent: boolean;
+};
+export declare function attachResponsesReasoningMetadata(target: Record<PropertyKey, unknown>, metadata: ResponsesReasoningMetadata): void;
+export declare function responsesReasoningMetadataErrorOf(value: unknown): string | undefined;
+export declare function responsesReasoningMetadataOf(value: unknown): ResponsesReasoningMetadata | undefined;
+/**
+ * Explicitly namespaced, JSON-safe fidelity metadata. Chat providers must strip
+ * this extension before egress; compound/proxy layers may serialize it while
+ * reconstructing a request for another RouteKit gateway.
+ */
+export type RouteKitReasoningEnvelope = {
+    version: 1;
+    selection?: ReasoningSelection;
+    anthropic?: {
+        request?: AnthropicRequestMetadata;
+    };
+    responses?: ResponsesReasoningMetadata;
+};
+export type RouteKitMessageEnvelope = {
+    version: 1;
+    anthropic?: {
+        content?: AnthropicNativeContentBlock[];
+    };
+    responses?: ResponsesReasoningMetadata;
+    google?: {
+        toolCallIndexes?: Record<string, number>;
+    };
+};
+export declare const ROUTEKIT_EXTENSION_KEY: "x_routekit";
+export declare function attachAnthropicRequestMetadata(target: Record<PropertyKey, unknown>, metadata: AnthropicRequestMetadata): void;
+export declare function anthropicRequestMetadataOf(value: unknown): AnthropicRequestMetadata | undefined;
+export declare function hasExplicitReasoningSelection(value: unknown): boolean;
+export declare function attachAnthropicMessageContent(target: Record<PropertyKey, unknown>, content: readonly AnthropicNativeContentBlock[]): void;
+export declare function anthropicMessageContentOf(value: unknown): AnthropicNativeContentBlock[] | undefined;
+export declare function attachGoogleToolCallIndexes(target: Record<PropertyKey, unknown>, indexes: Readonly<Record<string, number>>): void;
+export declare function googleToolCallIndexesOf(value: unknown): Readonly<Record<string, number>>;
+/** Remove the private namespaced extension at a final non-RouteKit provider boundary. */
+export declare function withoutRouteKitExtensions(value: unknown): unknown;
 export declare function attachReasoningSelection(target: Record<PropertyKey, unknown>, selection: ReasoningSelection): void;
 export declare function attachReasoningSelectionError(target: Record<PropertyKey, unknown>, message: string): void;
+/**
+ * Replace all request-local reasoning state with one authoritative selection.
+ *
+ * The clone is intentional: attached symbol metadata is non-configurable on
+ * its source object, while object spread creates replaceable own properties.
+ */
+export declare function withReasoningSelection(target: Record<string, unknown>, selection: ReasoningSelection): Record<string, unknown>;
+export type RouteKitRequestValidationError = {
+    code: "invalid_reasoning_control" | "invalid_reasoning_metadata";
+    path: string;
+    message: string;
+};
+export declare function routeKitRequestValidationErrorOf(value: unknown): RouteKitRequestValidationError | undefined;
 export declare function reasoningSelectionErrorOf(value: unknown): string | undefined;
 export declare function reasoningSelectionOf(value: unknown): ReasoningSelection;
 export type AnthropicNativeContentBlock = {
@@ -71,11 +146,12 @@ export type AnthropicNativeContentBlock = {
     name: string;
     input: unknown;
 };
+export type CanonicalReasoningDetail = AnthropicReasoningDetail | GoogleThoughtDetail;
 export type OpenAiDelta = {
     content?: string | null;
     reasoning?: string | null;
     reasoning_content?: string | null;
-    reasoning_details?: AnthropicReasoningDetail[];
+    reasoning_details?: CanonicalReasoningDetail[];
     tool_calls?: OpenAiToolCall[];
 };
 export type OpenAiChoice = {
@@ -84,7 +160,7 @@ export type OpenAiChoice = {
         content?: string | null;
         reasoning?: string | null;
         reasoning_content?: string | null;
-        reasoning_details?: AnthropicReasoningDetail[];
+        reasoning_details?: CanonicalReasoningDetail[];
         tool_calls?: OpenAiToolCall[];
     };
     finish_reason?: string | null;