@velum-labs/routekit-gateway 0.9.6 → 0.9.8

package/dist/adapters/cursor.d.ts

@@ -23,21 +23,21 @@ type JsonObject = Record<string, unknown>;
  */
 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.
+ * Spell a namespaced model id with dashes. Kept for one-release back-compat
+ * with clients that still send the 0.9.6 `/v1/cursor` spelling
+ * (`claude-code/claude-fable-5` → `claude-code-claude-fable-5`). New
+ * advertising uses `cursorModelName` from `@velum-labs/routekit-contracts`
+ * (`routekit/<id>`) so no advertised name starts with `claude-` or
+ * `gemini-`, which Cursor routes to the Anthropic/Google keys instead of
+ * the OpenAI base-URL override. Deprecated: prefer `cursorModelName`.
  */
 export declare function cursorModelAliasId(id: string): string;
 /**
- * Resolve Cursor's dash-separated spelling back to a served namespaced id.
+ * Resolve a Cursor-facing model name back to a served 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.
+ * Order: served as spelled (no rewrite) → strip `routekit/` → legacy
+ * 0.9.6 dashed spelling. Returns `undefined` when the name is already a
+ * served id or cannot be resolved.
  */
 export declare function resolveCursorModelAlias(model: unknown, servedIds: readonly string[]): string | undefined;
 /**

package/dist/adapters/cursor.js

@@ -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 { stripCursorNamespace } from "@velum-labs/routekit-contracts";
 import { droppedField } from "./dropped.js";
 import { attachReasoningSelection, attachReasoningSelectionError } from "./openai-chat-wire.js";
 /** Fields copied through unchanged when present and non-null. */
@@ -41,28 +42,32 @@ 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.
+ * Spell a namespaced model id with dashes. Kept for one-release back-compat
+ * with clients that still send the 0.9.6 `/v1/cursor` spelling
+ * (`claude-code/claude-fable-5` → `claude-code-claude-fable-5`). New
+ * advertising uses `cursorModelName` from `@velum-labs/routekit-contracts`
+ * (`routekit/<id>`) so no advertised name starts with `claude-` or
+ * `gemini-`, which Cursor routes to the Anthropic/Google keys instead of
+ * the OpenAI base-URL override. Deprecated: prefer `cursorModelName`.
  */
 export function cursorModelAliasId(id) {
-    return id.replace("/", "-");
+    return id.replaceAll("/", "-");
 }
 /**
- * Resolve Cursor's dash-separated spelling back to a served namespaced id.
+ * Resolve a Cursor-facing model name back to a served 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.
+ * Order: served as spelled (no rewrite) → strip `routekit/` → legacy
+ * 0.9.6 dashed spelling. Returns `undefined` when the name is already a
+ * served id or cannot be resolved.
  */
 export function resolveCursorModelAlias(model, servedIds) {
     if (typeof model !== "string" || model.length === 0 || servedIds.includes(model)) {
         return undefined;
     }
+    const stripped = stripCursorNamespace(model);
+    if (stripped !== undefined && servedIds.includes(stripped)) {
+        return stripped;
+    }
     return servedIds.find((id) => id.includes("/") && cursorModelAliasId(id) === model);
 }
 /**

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 "/"; alias keys must stay distinct from namespaced model ids`);
+        }
+        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

@@ -1,10 +1,10 @@
 import { once } from "node:events";
 import { createServer } from "node:http";
-import { ProviderFailureError } from "@velum-labs/routekit-contracts";
+import { ProviderFailureError, cursorModelName } 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 { cursorModelAliasId, isCursorChatBody, resolveCursorModelAlias, translateCursorRequest } from "./adapters/cursor.js";
+import { 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,10 @@ export async function startGateway(options) {
             return;
         }
         // Cursor may probe the models list relative to its BYOK base URL
-        // (`.../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.
+        // (`.../v1/cursor`); mirror /v1/models there. Every id is namespaced under
+        // `routekit/` so no advertised name starts with `claude-` or `gemini-`,
+        // which Cursor routes to the Anthropic/Google keys instead of the OpenAI
+        // base-URL override. The chat route below strips the namespace back.
         if (method === "GET" && path === "/v1/cursor/models") {
             const upstream = await backend.models();
             if (!upstream.ok) {
@@ -286,7 +287,7 @@ export async function startGateway(options) {
             writeJson(res, 200, {
                 ...payload,
                 data: (payload.data ?? []).map((entry) => typeof entry.id === "string"
-                    ? { ...entry, id: cursorModelAliasId(entry.id) }
+                    ? { ...entry, id: cursorModelName(entry.id) }
                     : entry)
             });
             return;

package/dist/test/cursor.test.js

@@ -47,16 +47,21 @@ 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", () => {
+test("Cursor model names namespace under routekit/ and resolve back", () => {
     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", "legacy dashed spelling still respells every slash");
     const served = ["claude-code/claude-fable-5", "openai/gpt-4o", "route-primary"];
+    // Namespaced Cursor-facing spelling.
+    assert.equal(resolveCursorModelAlias("routekit/claude-code/claude-fable-5", served), "claude-code/claude-fable-5");
+    assert.equal(resolveCursorModelAlias("routekit/openai/gpt-4o", served), "openai/gpt-4o");
+    assert.equal(resolveCursorModelAlias("routekit/route-primary", served), "route-primary");
+    // Legacy 0.9.6 dashed spelling still resolves.
     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("routekit/", served), undefined);
     assert.equal(resolveCursorModelAlias(undefined, served), undefined);
 });
 test("Cursor hybrid detection rejects unrelated bodies", () => {
@@ -104,13 +109,13 @@ test("RouteKit serves the Cursor hybrid through its neutral HTTP boundary", asyn
         });
         const models = await fetch(`${gateway.url()}/v1/cursor/models`);
         assert.equal(models.status, 200);
-        assert.deepEqual((await models.json()).data.map((model) => model.id), ["route-primary"]);
+        assert.deepEqual((await models.json()).data.map((model) => model.id), ["routekit/route-primary"]);
     }
     finally {
         await gateway.close();
     }
 });
-test("Cursor route resolves dashed model aliases to namespaced ids", async () => {
+test("Cursor route namespaces advertised ids and resolves them on ingress", async () => {
     let received;
     const backend = {
         defaultModel: "claude-code/claude-fable-5",
@@ -133,15 +138,31 @@ test("Cursor route resolves dashed model aliases to namespaced ids", async () =>
             object: "list",
             data: [
                 { id: "claude-code/claude-fable-5", object: "model" },
-                { id: "openai/gpt-4o", object: "model" }
+                { id: "openai/gpt-4o", object: "model" },
+                { id: "gemini-proxy/gemini-zzz-9", object: "model" }
             ]
         })),
-        listModelIds: () => ["claude-code/claude-fable-5", "openai/gpt-4o"],
+        listModelIds: () => [
+            "claude-code/claude-fable-5",
+            "openai/gpt-4o",
+            "gemini-proxy/gemini-zzz-9"
+        ],
         embeddings: () => Promise.resolve(new Response(null, { status: 501 }))
     };
     const gateway = await startGateway({ backend });
     try {
-        const response = await fetch(`${gateway.url()}/v1/cursor/chat/completions`, {
+        const namespaced = await fetch(`${gateway.url()}/v1/cursor/chat/completions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                model: "routekit/claude-code/claude-fable-5",
+                messages: [{ role: "user", content: "hi" }]
+            })
+        });
+        assert.equal(namespaced.status, 200);
+        assert.equal(received?.model, "claude-code/claude-fable-5");
+        // Legacy dashed spelling still resolves for one-release back-compat.
+        const legacy = await fetch(`${gateway.url()}/v1/cursor/chat/completions`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({
@@ -149,12 +170,22 @@ test("Cursor route resolves dashed model aliases to namespaced ids", async () =>
                 messages: [{ role: "user", content: "hi" }]
             })
         });
-        assert.equal(response.status, 200);
+        assert.equal(legacy.status, 200);
         assert.equal(received?.model, "claude-code/claude-fable-5");
-        // The models mirror advertises the dashed spelling Cursor accepts.
+        // The models mirror advertises routekit/-namespaced ids that never start
+        // with claude- or gemini- (Cursor's BYOK provider-selection prefixes).
         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"]);
+        const ids = (await models.json()).data.map((model) => model.id);
+        assert.deepEqual(ids, [
+            "routekit/claude-code/claude-fable-5",
+            "routekit/openai/gpt-4o",
+            "routekit/gemini-proxy/gemini-zzz-9"
+        ]);
+        for (const id of ids) {
+            assert.equal(id.startsWith("claude-"), false, id);
+            assert.equal(id.startsWith("gemini-"), false, id);
+        }
     }
     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.6",
+  "version": "0.9.8",
   "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.6",
-    "@velum-labs/routekit-registry": "0.9.6",
-    "@velum-labs/routekit-runtime": "0.9.6",
-    "@velum-labs/routekit-tracing": "0.9.6"
+    "@velum-labs/routekit-registry": "0.9.8",
+    "@velum-labs/routekit-tracing": "0.9.8",
+    "@velum-labs/routekit-runtime": "0.9.8",
+    "@velum-labs/routekit-contracts": "0.9.8"
   },
   "keywords": [
     "routekit",