@velum-labs/routekit-gateway 0.9.5 → 0.9.7

package/dist/adapters/cursor.d.ts

@@ -22,6 +22,24 @@ type JsonObject = Record<string, unknown>;
  * job; the translation itself stays total.
  */
 export declare function isCursorChatBody(body: unknown): body is JsonObject;
+/**
+ * Spell a namespaced model id the way Cursor's custom-model settings accept
+ * it. Cursor rejects ids containing "/" ("Model name is not valid"), so the
+ * cursor route advertises and answers to a dash-separated spelling
+ * (`claude-code/claude-fable-5` -> `claude-code-claude-fable-5`). Dashes are
+ * preferred over dots because dotted names can collide with Cursor's managed
+ * model catalog.
+ */
+export declare function cursorModelAliasId(id: string): string;
+/**
+ * Resolve Cursor's dash-separated spelling back to a served namespaced id.
+ *
+ * Resolution is an exact lookup over the gateway's served ids rather than a
+ * separator split, because namespaces themselves contain dashes. A rewrite
+ * only happens when the model is not served as spelled; if two served ids
+ * produce the same alias, the first one listed wins.
+ */
+export declare function resolveCursorModelAlias(model: unknown, servedIds: readonly string[]): string | undefined;
 /**
  * Map a Cursor BYOK request body onto a Chat Completions body.
  *

package/dist/adapters/cursor.js

@@ -40,6 +40,31 @@ function isObject(value) {
 export function isCursorChatBody(body) {
     return isObject(body) && ("messages" in body || "input" in body);
 }
+/**
+ * Spell a namespaced model id the way Cursor's custom-model settings accept
+ * it. Cursor rejects ids containing "/" ("Model name is not valid"), so the
+ * cursor route advertises and answers to a dash-separated spelling
+ * (`claude-code/claude-fable-5` -> `claude-code-claude-fable-5`). Dashes are
+ * preferred over dots because dotted names can collide with Cursor's managed
+ * model catalog.
+ */
+export function cursorModelAliasId(id) {
+    return id.replaceAll("/", "-");
+}
+/**
+ * Resolve Cursor's dash-separated spelling back to a served namespaced id.
+ *
+ * Resolution is an exact lookup over the gateway's served ids rather than a
+ * separator split, because namespaces themselves contain dashes. A rewrite
+ * only happens when the model is not served as spelled; if two served ids
+ * produce the same alias, the first one listed wins.
+ */
+export function resolveCursorModelAlias(model, servedIds) {
+    if (typeof model !== "string" || model.length === 0 || servedIds.includes(model)) {
+        return undefined;
+    }
+    return servedIds.find((id) => id.includes("/") && cursorModelAliasId(id) === model);
+}
 /**
  * Map a Cursor BYOK request body onto a Chat Completions body.
  *

package/dist/router.d.ts

@@ -94,6 +94,7 @@ export declare const routerConfigSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>;
     defaultModel: z.ZodOptional<z.ZodString>;
+    modelAliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     reasoningCapabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         status: z.ZodDefault<z.ZodEnum<{
             unknown: "unknown";

package/dist/router.js

@@ -96,6 +96,7 @@ export const routerConfigSchema = z
     })
         .strict(),
     defaultModel: z.string().min(3).optional(),
+    modelAliases: z.record(z.string().min(1), z.string().min(3)).optional(),
     reasoningCapabilities: z
         .record(z.string().min(3), reasoningCapabilityOverrideSchema)
         .optional()
@@ -143,6 +144,15 @@ export function parseRouterConfig(value) {
             throw new Error(`default model provider "${selected.provider}" is not configured`);
         }
     }
+    for (const [alias, target] of Object.entries(config.modelAliases ?? {})) {
+        if (alias.includes("/")) {
+            throw new Error(`model alias "${alias}" must not contain "/"; aliases exist to give namespaced models slash-free names`);
+        }
+        const selected = splitNamespacedModel(target);
+        if (config.providers[selected.provider] === undefined) {
+            throw new Error(`model alias "${alias}" targets "${target}" but provider "${selected.provider}" is not configured`);
+        }
+    }
     return config;
 }
 function routeBilling(provider) {
@@ -236,6 +246,16 @@ export class CatalogBackend {
                     });
                 }
             }
+            for (const [alias, target] of Object.entries(config.modelAliases ?? {})) {
+                const entry = entries.get(target);
+                if (entry === undefined) {
+                    throw new Error(`model alias "${alias}" targets "${target}", which no configured provider serves`);
+                }
+                if (entries.has(alias)) {
+                    throw new Error(`model alias "${alias}" collides with a served model id`);
+                }
+                entries.set(alias, { ...entry, publicId: alias });
+            }
             const first = entries.keys().next().value;
             const defaultModel = config.defaultModel ?? first;
             if (defaultModel === undefined) {

package/dist/server.js

@@ -4,7 +4,7 @@ import { ProviderFailureError } from "@velum-labs/routekit-contracts";
 import { anthropicModelsResponse, handleAnthropicMessages, handleCountTokens, resolveClaudeModelAlias } from "./adapters/anthropic.js";
 import { effectiveModel, isStream, withDefaultModel } from "./adapters/chat.js";
 import { authorizedRequest } from "./auth.js";
-import { isCursorChatBody, translateCursorRequest } from "./adapters/cursor.js";
+import { cursorModelAliasId, isCursorChatBody, resolveCursorModelAlias, translateCursorRequest } from "./adapters/cursor.js";
 import { handleResponses } from "./adapters/responses.js";
 import { validateAnthropicRequest, validateChatRequest, validateCountTokensRequest, validateResponsesRequest } from "./adapters/validate.js";
 import { buildModelCallRecord, MODEL_CALL_ID_HEADER, modelCallId } from "./provenance.js";
@@ -273,9 +273,22 @@ export async function startGateway(options) {
             return;
         }
         // Cursor may probe the models list relative to its BYOK base URL
-        // (`.../v1/cursor`); mirror /v1/models there.
+        // (`.../v1/cursor`); mirror /v1/models there. Namespaced ids are respelled
+        // with dashes because Cursor's custom-model settings reject "/" in names;
+        // the chat route below resolves the dashed spelling back.
         if (method === "GET" && path === "/v1/cursor/models") {
-            await pipeUpstream(res, await backend.models());
+            const upstream = await backend.models();
+            if (!upstream.ok) {
+                await pipeUpstream(res, upstream);
+                return;
+            }
+            const payload = (await upstream.json());
+            writeJson(res, 200, {
+                ...payload,
+                data: (payload.data ?? []).map((entry) => typeof entry.id === "string"
+                    ? { ...entry, id: cursorModelAliasId(entry.id) }
+                    : entry)
+            });
             return;
         }
         // Anthropic single-model retrieve (`GET /v1/models/{id}`): Claude Code probes
@@ -349,6 +362,9 @@ export async function startGateway(options) {
             const translated = translateCursorRequest(raw);
             if (rejectInvalid(res, validateChatRequest(translated)))
                 return;
+            const aliased = resolveCursorModelAlias(translated.model, backend.listModelIds?.() ?? []);
+            if (aliased !== undefined)
+                translated.model = aliased;
             const body = withDefaultModel(translated, backend.defaultModel);
             await handleModelCall(res, provenance, {
                 dialect: "openai-chat",

package/dist/test/cursor.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { isCursorChatBody, translateCursorRequest } from "../adapters/cursor.js";
+import { cursorModelAliasId, isCursorChatBody, resolveCursorModelAlias, translateCursorRequest } from "../adapters/cursor.js";
 import { startGateway } from "../server.js";
 const cursorBody = {
     model: "route-primary",
@@ -47,6 +47,23 @@ test("Cursor hybrid requests translate to chat messages and tools", () => {
     ]);
     assert.equal(translated.tools[0]?.function.name, "read_file");
 });
+test("Cursor model aliases respell namespaced ids with dashes", () => {
+    assert.equal(cursorModelAliasId("claude-code/claude-fable-5"), "claude-code-claude-fable-5");
+    assert.equal(cursorModelAliasId("openai/gpt-4o"), "openai-gpt-4o");
+    assert.equal(cursorModelAliasId("route-primary"), "route-primary");
+    assert.equal(cursorModelAliasId("openrouter/moonshotai/kimi-k2-thinking"), "openrouter-moonshotai-kimi-k2-thinking", "every slash is respelled, not just the namespace separator");
+    const served = ["claude-code/claude-fable-5", "openai/gpt-4o", "route-primary"];
+    assert.equal(resolveCursorModelAlias("openrouter-moonshotai-kimi-k2-thinking", [
+        ...served,
+        "openrouter/moonshotai/kimi-k2-thinking"
+    ]), "openrouter/moonshotai/kimi-k2-thinking");
+    assert.equal(resolveCursorModelAlias("claude-code-claude-fable-5", served), "claude-code/claude-fable-5");
+    assert.equal(resolveCursorModelAlias("openai-gpt-4o", served), "openai/gpt-4o");
+    // Served-as-spelled ids and unknown names never rewrite.
+    assert.equal(resolveCursorModelAlias("route-primary", served), undefined);
+    assert.equal(resolveCursorModelAlias("claude-fable-5", served), undefined);
+    assert.equal(resolveCursorModelAlias(undefined, served), undefined);
+});
 test("Cursor hybrid detection rejects unrelated bodies", () => {
     assert.equal(isCursorChatBody({ input: "hello" }), true);
     assert.equal(isCursorChatBody({ messages: [] }), true);
@@ -98,3 +115,53 @@ test("RouteKit serves the Cursor hybrid through its neutral HTTP boundary", asyn
         await gateway.close();
     }
 });
+test("Cursor route resolves dashed model aliases to namespaced ids", async () => {
+    let received;
+    const backend = {
+        defaultModel: "claude-code/claude-fable-5",
+        chat(body) {
+            received = body;
+            return Promise.resolve(Response.json({
+                id: "chatcmpl_2",
+                object: "chat.completion",
+                model: "claude-code/claude-fable-5",
+                choices: [
+                    {
+                        index: 0,
+                        message: { role: "assistant", content: "done" },
+                        finish_reason: "stop"
+                    }
+                ]
+            }));
+        },
+        models: () => Promise.resolve(Response.json({
+            object: "list",
+            data: [
+                { id: "claude-code/claude-fable-5", object: "model" },
+                { id: "openai/gpt-4o", object: "model" }
+            ]
+        })),
+        listModelIds: () => ["claude-code/claude-fable-5", "openai/gpt-4o"],
+        embeddings: () => Promise.resolve(new Response(null, { status: 501 }))
+    };
+    const gateway = await startGateway({ backend });
+    try {
+        const response = await fetch(`${gateway.url()}/v1/cursor/chat/completions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                model: "claude-code-claude-fable-5",
+                messages: [{ role: "user", content: "hi" }]
+            })
+        });
+        assert.equal(response.status, 200);
+        assert.equal(received?.model, "claude-code/claude-fable-5");
+        // The models mirror advertises the dashed spelling Cursor accepts.
+        const models = await fetch(`${gateway.url()}/v1/cursor/models`);
+        assert.equal(models.status, 200);
+        assert.deepEqual((await models.json()).data.map((model) => model.id), ["claude-code-claude-fable-5", "openai-gpt-4o"]);
+    }
+    finally {
+        await gateway.close();
+    }
+});

package/dist/test/router.test.js

@@ -156,6 +156,58 @@ test("catalog namespaces live models and strips the source before dispatch", asy
     });
     assert.equal(backend.modelInfo("openai/not-real"), undefined);
 });
+test("configured model aliases serve namespaced models under slash-free names", async () => {
+    const calls = [];
+    const backend = await CatalogBackend.create({
+        config: {
+            providers: { "claude-code": {} },
+            modelAliases: { "velum-fable-5": "claude-code/claude-fable-5" }
+        },
+        sources: {
+            "claude-code": fakeSource("claude-code", [{ id: "claude-fable-5" }], calls)
+        }
+    });
+    assert.deepEqual(backend.listModelIds(), [
+        "claude-code/claude-fable-5",
+        "velum-fable-5"
+    ]);
+    assert.equal(backend.servesModel("velum-fable-5"), true);
+    assert.deepEqual(backend.resolveModelRoute("velum-fable-5"), {
+        publicId: "velum-fable-5",
+        nativeId: "claude-fable-5",
+        provider: "claude-code"
+    });
+    assert.equal(backend.modelInfo("velum-fable-5")?.id, "velum-fable-5");
+    assert.equal(backend.modelInfo("velum-fable-5")?.nativeModel, "claude-fable-5");
+    await backend.chat({ model: "velum-fable-5", messages: [] });
+    assert.deepEqual(calls, [
+        { source: "claude-code", model: "claude-fable-5" }
+    ]);
+});
+test("model aliases reject bad shapes and unknown targets", async () => {
+    assert.throws(() => parseRouterConfig({
+        providers: { openai: {} },
+        modelAliases: { "bad/alias": "openai/gpt-5.5" }
+    }), /must not contain "\/"/);
+    assert.throws(() => parseRouterConfig({
+        providers: { openai: {} },
+        modelAliases: { "velum-fable-5": "claude-code/claude-fable-5" }
+    }), /provider "claude-code" is not configured/);
+    await assert.rejects(CatalogBackend.create({
+        config: {
+            providers: { openai: {} },
+            modelAliases: { "velum-gpt": "openai/not-discovered" }
+        },
+        sources: { openai: fakeSource("openai", [{ id: "gpt-5.5" }]) }
+    }), /targets "openai\/not-discovered", which no configured provider serves/);
+    await assert.rejects(CatalogBackend.create({
+        config: {
+            providers: { openai: {} },
+            modelAliases: { "openai/gpt-5.5": "openai/gpt-5.5" }
+        },
+        sources: { openai: fakeSource("openai", [{ id: "gpt-5.5" }]) }
+    }), /must not contain "\/"/);
+});
 test("model info exhaustively classifies subscription and proxy billing", async () => {
     const backend = await CatalogBackend.create({
         config: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-gateway",
   "private": false,
-  "version": "0.9.5",
+  "version": "0.9.7",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/handoffkit.git",
@@ -27,10 +27,10 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@velum-labs/routekit-contracts": "0.9.5",
-    "@velum-labs/routekit-tracing": "0.9.5",
-    "@velum-labs/routekit-runtime": "0.9.5",
-    "@velum-labs/routekit-registry": "0.9.5"
+    "@velum-labs/routekit-contracts": "0.9.7",
+    "@velum-labs/routekit-tracing": "0.9.7",
+    "@velum-labs/routekit-runtime": "0.9.7",
+    "@velum-labs/routekit-registry": "0.9.7"
   },
   "keywords": [
     "routekit",