@velum-labs/routekit-gateway 0.9.0

package/dist/router.js

@@ -0,0 +1,474 @@
+import { z } from "zod";
+import { resolveReasoningEffort } from "@velum-labs/routekit-contracts";
+import { API_PROVIDER_IDS, ApiProviderSource, PROVIDER_IDS, SUBSCRIPTION_PROVIDER_IDS } from "./provider-source.js";
+import { attachReasoningSelection, reasoningSelectionErrorOf, reasoningSelectionOf } from "./adapters/openai-chat-wire.js";
+export class UnknownModelError extends Error {
+    model;
+    constructor(model) {
+        super(`unknown model: ${model}`);
+        this.model = model;
+        this.name = "UnknownModelError";
+    }
+}
+export class NoModelAvailableError extends Error {
+    constructor() {
+        super("no model is available; configure a provider");
+        this.name = "NoModelAvailableError";
+    }
+}
+const providerPolicySchema = z
+    .object({
+    strategy: z
+        .enum(["sticky", "round_robin", "capacity_weighted"])
+        .default("capacity_weighted"),
+    switchThreshold: z.number().min(0.01).max(1).default(0.9),
+    probeIntervalMs: z.number().int().nonnegative().optional(),
+    fallbackCooldownSeconds: z.number().nonnegative().optional()
+})
+    .strict();
+const reasoningCapabilityOverrideSchema = z
+    .object({
+    status: z.enum(["supported", "unsupported", "unknown"]).default("supported"),
+    efforts: z
+        .array(z
+        .object({
+        id: z.string().min(1),
+        label: z.string().min(1).optional(),
+        description: z.string().min(1).optional(),
+        aliases: z.array(z.string().min(1)).optional()
+    })
+        .strict())
+        .optional(),
+    defaultEffort: z.string().min(1).optional(),
+    budget: z
+        .object({
+        minTokens: z.number().int().nonnegative().optional(),
+        maxTokens: z.number().int().positive().optional(),
+        defaultTokens: z.number().int().nonnegative().optional()
+    })
+        .strict()
+        .optional(),
+    adaptive: z.boolean().optional(),
+    wireShape: z.string().min(1).optional()
+})
+    .strict()
+    .superRefine((capability, context) => {
+    const ids = new Set();
+    for (const [index, effort] of (capability.efforts ?? []).entries()) {
+        if (ids.has(effort.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["efforts", index, "id"],
+                message: `duplicate reasoning effort "${effort.id}"`
+            });
+        }
+        ids.add(effort.id);
+    }
+    if (capability.defaultEffort !== undefined &&
+        !ids.has(capability.defaultEffort)) {
+        context.addIssue({
+            code: "custom",
+            path: ["defaultEffort"],
+            message: "default reasoning effort must be listed in efforts"
+        });
+    }
+    if (capability.budget?.minTokens !== undefined &&
+        capability.budget.maxTokens !== undefined &&
+        capability.budget.minTokens > capability.budget.maxTokens) {
+        context.addIssue({
+            code: "custom",
+            path: ["budget"],
+            message: "minimum reasoning budget cannot exceed maximum"
+        });
+    }
+});
+export const routerConfigSchema = z
+    .object({
+    providers: z
+        .object({
+        openai: providerPolicySchema.optional(),
+        anthropic: providerPolicySchema.optional(),
+        google: providerPolicySchema.optional(),
+        openrouter: providerPolicySchema.optional(),
+        cliproxy: providerPolicySchema.optional(),
+        codex: providerPolicySchema.optional(),
+        "claude-code": providerPolicySchema.optional()
+    })
+        .strict(),
+    defaultModel: z.string().min(3).optional(),
+    reasoningCapabilities: z
+        .record(z.string().min(3), reasoningCapabilityOverrideSchema)
+        .optional()
+})
+    .strict();
+export function normalizeRouterConfigAliases(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return value;
+    const config = value;
+    const rawProviders = config.providers;
+    if (typeof rawProviders !== "object" ||
+        rawProviders === null ||
+        Array.isArray(rawProviders)) {
+        return value;
+    }
+    const providers = rawProviders;
+    const claudeKeys = ["claude-code", "claudeCode", "claude"].filter((key) => Object.hasOwn(providers, key));
+    if (claudeKeys.length > 1) {
+        throw new Error(`router config contains conflicting Claude provider keys: ${claudeKeys.join(", ")}`);
+    }
+    const normalizedProviders = { ...providers };
+    const claudeKey = claudeKeys[0];
+    if (claudeKey !== undefined && claudeKey !== "claude-code") {
+        normalizedProviders["claude-code"] = normalizedProviders[claudeKey];
+        delete normalizedProviders[claudeKey];
+    }
+    return { ...config, providers: normalizedProviders };
+}
+export function splitNamespacedModel(model) {
+    const separator = model.indexOf("/");
+    const source = separator < 0 ? "" : model.slice(0, separator);
+    const nativeModel = separator < 0 ? "" : model.slice(separator + 1);
+    if (!PROVIDER_IDS.includes(source) ||
+        nativeModel.length === 0 ||
+        nativeModel.startsWith("/")) {
+        throw new Error(`model "${model}" must use a supported provider/model namespace`);
+    }
+    return { provider: source, model: nativeModel };
+}
+export function parseRouterConfig(value) {
+    const config = routerConfigSchema.parse(normalizeRouterConfigAliases(value));
+    if (config.defaultModel !== undefined) {
+        const selected = splitNamespacedModel(config.defaultModel);
+        if (config.providers[selected.provider] === undefined) {
+            throw new Error(`default model provider "${selected.provider}" is not configured`);
+        }
+    }
+    return config;
+}
+function routeBilling(provider) {
+    switch (provider) {
+        case "openai":
+        case "anthropic":
+        case "google":
+        case "openrouter":
+            return { accountClass: "api-key", billingMode: "metered-api" };
+        case "codex":
+        case "claude-code":
+            return { accountClass: "subscription", billingMode: "subscription" };
+        case "cliproxy":
+            return { accountClass: "proxy", billingMode: "upstream-managed" };
+        default: {
+            const unreachable = provider;
+            throw new Error(`unsupported route provider: ${String(unreachable)}`);
+        }
+    }
+}
+function configuredProviderIds(config) {
+    return PROVIDER_IDS.filter((provider) => config.providers[provider] !== undefined);
+}
+function isApiProvider(provider) {
+    return API_PROVIDER_IDS.includes(provider);
+}
+function namespaced(provider, model) {
+    return `${provider}/${model}`;
+}
+export class CatalogBackend {
+    defaultModel;
+    #entries;
+    #sources;
+    constructor(defaultModel, entries, sources) {
+        this.defaultModel = defaultModel;
+        this.#entries = entries;
+        this.#sources = sources;
+    }
+    static async create(options) {
+        const config = parseRouterConfig(options.config);
+        const env = options.env ?? process.env;
+        const sources = [];
+        const entries = new Map();
+        try {
+            for (const provider of configuredProviderIds(config)) {
+                const injected = options.sources?.[provider];
+                let source;
+                if (injected !== undefined) {
+                    source = injected;
+                }
+                else if (isApiProvider(provider)) {
+                    source =
+                        options.createApiSource?.(provider, env) ??
+                            new ApiProviderSource({ provider, env });
+                }
+                else {
+                    throw new Error(`provider "${provider}" requires enrolled subscription accounts`);
+                }
+                if (source.sourceId !== provider) {
+                    throw new Error(`provider source mismatch: configured "${provider}", received "${source.sourceId}"`);
+                }
+                sources.push(source);
+                let discovered;
+                try {
+                    discovered = await source.discoverModels(options.signal);
+                }
+                catch (error) {
+                    throw new Error(`provider "${provider}" discovery failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+                }
+                if (discovered.length === 0) {
+                    throw new Error(`provider "${provider}" discovery returned no models`);
+                }
+                for (const model of discovered) {
+                    const publicId = namespaced(provider, model.id);
+                    if (entries.has(publicId))
+                        continue;
+                    const override = config.reasoningCapabilities?.[publicId];
+                    const reasoning = override !== undefined
+                        ? {
+                            ...override,
+                            provenance: "config"
+                        }
+                        : model.reasoning ?? source.reasoningCapabilities?.(model.id);
+                    entries.set(publicId, {
+                        publicId,
+                        nativeId: model.id,
+                        provider,
+                        source,
+                        capabilities: model.capabilities ?? source.capabilities?.(model.id) ?? {},
+                        ...(reasoning !== undefined ? { reasoning } : {})
+                    });
+                }
+            }
+            const first = entries.keys().next().value;
+            const defaultModel = config.defaultModel ?? first;
+            if (defaultModel === undefined) {
+                if (configuredProviderIds(config).length > 0) {
+                    throw new Error("configured providers discovered no models");
+                }
+            }
+            else if (!entries.has(defaultModel)) {
+                throw new UnknownModelError(defaultModel);
+            }
+            return new CatalogBackend(defaultModel, entries, sources);
+        }
+        catch (error) {
+            await Promise.allSettled(sources.map(async (source) => await source.close?.()));
+            throw error;
+        }
+    }
+    listModelIds() {
+        return [...this.#entries.keys()];
+    }
+    modelInfo(model) {
+        const entry = this.#entries.get(model);
+        if (entry === undefined)
+            return undefined;
+        return {
+            id: entry.publicId,
+            provider: entry.provider,
+            nativeModel: entry.nativeId,
+            ...routeBilling(entry.provider),
+            default: entry.publicId === this.defaultModel,
+            capabilities: entry.capabilities,
+            reasoning: entry.reasoning ?? null
+        };
+    }
+    async providerStatuses(signal) {
+        return await Promise.all(this.#sources.map(async (source) => {
+            try {
+                const models = await source.discoverModels(signal);
+                if (models.length === 0) {
+                    return {
+                        provider: source.sourceId,
+                        ok: false,
+                        models: [],
+                        error: "live discovery returned no models"
+                    };
+                }
+                return {
+                    provider: source.sourceId,
+                    ok: true,
+                    models: models.map((model) => namespaced(source.sourceId, model.id))
+                };
+            }
+            catch (error) {
+                return {
+                    provider: source.sourceId,
+                    ok: false,
+                    models: [],
+                    error: error instanceof Error ? error.message : String(error)
+                };
+            }
+        }));
+    }
+    servesModel(model) {
+        return this.#entries.has(model);
+    }
+    resolveModel(requested) {
+        if (requested === undefined)
+            return this.defaultModel;
+        return this.#entries.has(requested) ? requested : undefined;
+    }
+    resolveModelRoute(requested, nativeProvider) {
+        const publicId = requested ?? this.defaultModel;
+        if (publicId === undefined)
+            return undefined;
+        const exact = this.#entries.get(publicId);
+        if (exact !== undefined)
+            return this.#modelRoute(exact);
+        if (nativeProvider === undefined || requested === undefined)
+            return undefined;
+        for (const entry of this.#entries.values()) {
+            if (entry.provider === nativeProvider && entry.nativeId === requested) {
+                return this.#modelRoute(entry);
+            }
+        }
+        return undefined;
+    }
+    capabilities(model) {
+        return this.#entries.get(model)?.capabilities ?? {};
+    }
+    reasoningCapabilities(model) {
+        return this.#entries.get(model)?.reasoning;
+    }
+    chat(body, signal, options) {
+        const entry = this.#entry(this.#requestedModel(body));
+        const selectionError = reasoningSelectionErrorOf(body);
+        if (selectionError !== undefined) {
+            return Promise.resolve(Response.json({
+                error: {
+                    type: "invalid_request_error",
+                    code: "invalid_reasoning_control",
+                    message: selectionError
+                }
+            }, { status: 400 }));
+        }
+        const selection = this.#validatedReasoning(entry, reasoningSelectionOf(body));
+        if (typeof selection === "string") {
+            return Promise.resolve(Response.json({
+                error: {
+                    type: "invalid_request_error",
+                    code: "unsupported_reasoning_control",
+                    message: selection
+                }
+            }, { status: 400 }));
+        }
+        const nativeBody = this.#withNativeModel(body, entry.nativeId);
+        options?.onAttribution?.({
+            effective_model: entry.publicId,
+            native_model: entry.nativeId,
+            provider: entry.provider,
+            billing_mode: isSubscriptionProvider(entry.provider) || entry.provider === "cliproxy"
+                ? "subscription"
+                : "api_key"
+        });
+        if (nativeBody !== null &&
+            typeof nativeBody === "object" &&
+            !Array.isArray(nativeBody)) {
+            attachReasoningSelection(nativeBody, selection);
+            if (selection.mode === "effort") {
+                nativeBody.reasoning_effort =
+                    selection.effort;
+            }
+        }
+        return entry.source.chat(nativeBody, signal, {
+            ...options,
+            ...(entry.reasoning !== undefined
+                ? { reasoningCapabilities: entry.reasoning }
+                : {})
+        });
+    }
+    models() {
+        const data = [...this.#entries.values()].map((entry) => ({
+            id: entry.publicId,
+            object: "model",
+            owned_by: entry.provider,
+            capabilities: entry.capabilities,
+            ...(entry.reasoning !== undefined ? { reasoning: entry.reasoning } : {})
+        }));
+        return Promise.resolve(new Response(JSON.stringify({ object: "list", data }), {
+            headers: { "content-type": "application/json" }
+        }));
+    }
+    embeddings(body, signal, options) {
+        const entry = this.#entry(this.#requestedModel(body));
+        options?.onAttribution?.({
+            effective_model: entry.publicId,
+            native_model: entry.nativeId,
+            provider: entry.provider,
+            billing_mode: isSubscriptionProvider(entry.provider) || entry.provider === "cliproxy"
+                ? "subscription"
+                : "api_key"
+        });
+        return entry.source.embeddings(this.#withNativeModel(body, entry.nativeId), signal, options);
+    }
+    async close() {
+        await Promise.all(this.#sources.map(async (source) => await source.close?.()));
+    }
+    #requestedModel(body) {
+        return typeof body === "object" &&
+            body !== null &&
+            !Array.isArray(body) &&
+            typeof body.model === "string"
+            ? body.model
+            : undefined;
+    }
+    #entry(requested) {
+        const model = requested ?? this.defaultModel;
+        if (model === undefined)
+            throw new NoModelAvailableError();
+        const entry = this.#entries.get(model);
+        if (entry === undefined)
+            throw new UnknownModelError(model);
+        return entry;
+    }
+    #withNativeModel(body, nativeModel) {
+        return typeof body === "object" && body !== null && !Array.isArray(body)
+            ? { ...body, model: nativeModel }
+            : body;
+    }
+    #modelRoute(entry) {
+        return {
+            publicId: entry.publicId,
+            nativeId: entry.nativeId,
+            provider: entry.provider,
+            ...(entry.reasoning !== undefined ? { reasoning: entry.reasoning } : {})
+        };
+    }
+    #validatedReasoning(entry, selection) {
+        if (selection.mode === "auto" || selection.mode === "disabled") {
+            return selection;
+        }
+        const capability = entry.reasoning;
+        if (capability === undefined || capability.status === "unknown") {
+            return `model "${entry.publicId}" has no discovered reasoning controls`;
+        }
+        if (capability.status === "unsupported") {
+            return `model "${entry.publicId}" does not support reasoning controls`;
+        }
+        if (selection.mode === "effort") {
+            const effort = resolveReasoningEffort(capability, selection.effort);
+            return effort === undefined
+                ? `reasoning effort "${selection.effort}" is not supported by model "${entry.publicId}"`
+                : { mode: "effort", effort };
+        }
+        if (selection.mode === "adaptive") {
+            return capability.adaptive === true
+                ? selection
+                : `adaptive reasoning is not supported by model "${entry.publicId}"`;
+        }
+        const budget = capability.budget;
+        if (budget === undefined) {
+            return `reasoning token budgets are not supported by model "${entry.publicId}"`;
+        }
+        if (budget.minTokens !== undefined &&
+            selection.budgetTokens < budget.minTokens) {
+            return `reasoning budget must be at least ${budget.minTokens} tokens`;
+        }
+        if (budget.maxTokens !== undefined &&
+            selection.budgetTokens > budget.maxTokens) {
+            return `reasoning budget must be at most ${budget.maxTokens} tokens`;
+        }
+        return selection;
+    }
+}
+export function isSubscriptionProvider(provider) {
+    return SUBSCRIPTION_PROVIDER_IDS.includes(provider);
+}

package/dist/server.d.ts

@@ -0,0 +1,67 @@
+import type { IncomingMessage } from "node:http";
+import type { RequestAttribution } from "@velum-labs/routekit-contracts";
+import type { AnthropicRequest } from "./adapters/anthropic.js";
+import type { ResponsesRequest } from "./adapters/responses.js";
+import type { Backend, BackendRequestOptions } from "./backend.js";
+import type { ProvenanceSink } from "./provenance.js";
+/**
+ * The local-model gateway HTTP server. It fronts a single OpenAI Chat
+ * Completions backend (the owned mlx fork by default) and exposes the wire
+ * dialects each agent harness needs: OpenAI chat, Anthropic Messages, OpenAI
+ * Responses, and Cursor's Responses-hybrid BYOK shape.
+ */
+export type GatewayOptions = {
+    backend: Backend;
+    /** Bind host; defaults to loopback. */
+    host?: string;
+    /** Bind port; defaults to an ephemeral free port. */
+    port?: number;
+    /** When set, require this bearer token (or matching `x-api-key`). */
+    authToken?: string;
+    /** Optional observation sink for model calls. */
+    provenance?: ProvenanceSink;
+    /** Optional client-authenticated Responses relay. */
+    codexRelay?: ProviderRelay;
+    /** Provider-native relays sharing this HTTP boundary. */
+    providerRelays?: Partial<Record<ProviderRelayDialect, ProviderRelay>>;
+    /** Optional provider usage payload for `GET /usage`. */
+    usage?: () => unknown | Promise<unknown>;
+};
+export type ProviderRelayDialect = "anthropic" | "codex";
+export type ProviderRelay = {
+    readonly dialect: ProviderRelayDialect;
+    shouldRelay(headers: IncomingMessage["headers"], model: string | undefined, servesLocally: (model: string) => boolean): boolean;
+    relay(headers: IncomingMessage["headers"], body: AnthropicRequest | ResponsesRequest, signal?: AbortSignal, options?: Pick<BackendRequestOptions, "onAttribution">): Promise<Response>;
+    models?(headers: IncomingMessage["headers"], search: string, signal?: AbortSignal): Promise<Response>;
+    countTokens?(headers: IncomingMessage["headers"], body: AnthropicRequest, signal?: AbortSignal): Promise<Response>;
+    mergedCatalog?(headers: IncomingMessage["headers"], search: string): Promise<{
+        models: Array<Record<string, unknown>>;
+        etag?: string;
+    } | undefined>;
+    mergeDataIds?(data: Array<{
+        id: string;
+    } & Record<string, unknown>>, models: readonly Record<string, unknown>[]): Array<{
+        id: string;
+    } & Record<string, unknown>>;
+    close?(): Promise<void> | void;
+};
+export type Gateway = {
+    /** Base URL clients should target (without the `/v1` suffix). */
+    url(): string;
+    port(): number;
+    /**
+     * Graceful drain: flip `/health` to 503 and reject new model calls while
+     * letting in-flight requests (long-lived LLM streams) finish, bounded by
+     * `graceMs`; then close the listener and sever whatever remains. Does not
+     * release the backend — follow with {@link close}.
+     */
+    drain(graceMs?: number): Promise<void>;
+    /** Immediate close: equivalent to `drain(0)` plus backend/relay teardown. */
+    close(): Promise<void>;
+};
+export declare function initialAttribution(backend: Backend, requested: string | undefined, nativeProvider?: "claude-code" | "codex"): Partial<RequestAttribution>;
+export declare function startGateway(options: GatewayOptions): Promise<Gateway>;
+export declare function collectAttribution(seed: Partial<RequestAttribution> | undefined): {
+    report: NonNullable<BackendRequestOptions["onAttribution"]>;
+    snapshot(): RequestAttribution | undefined;
+};