feat: support custom model info overrides

packages/types/src/__tests__/custom-model-info.test.ts

@@ -0,0 +1,135 @@
+import { applyCustomModelInfo, customModelInfoSchema, toCustomModelInfo, type ModelInfo } from "../model.js"
+import { providerIdentifiers, providerSettingsSchemaDiscriminated } from "../index.js"
+
+describe("custom model info", () => {
+	const catalogModel: ModelInfo = {
+		maxTokens: 4096,
+		contextWindow: 8192,
+		supportsImages: false,
+		supportsPromptCache: false,
+		inputPrice: 0.1,
+		outputPrice: 0.2,
+		cacheWritesPrice: 0.3,
+		cacheReadsPrice: 0.4,
+		description: "Provider metadata",
+	}
+
+	it("replaces discovered metadata with the configured snapshot", () => {
+		const resolved = applyCustomModelInfo(catalogModel, {
+			customModelInfo: {
+				contextWindow: 128_000,
+				maxTokens: 16_384,
+				supportsImages: true,
+				supportsPromptCache: true,
+			},
+		})
+
+		expect(resolved).toMatchObject({
+			contextWindow: 128_000,
+			maxTokens: 16_384,
+			supportsImages: true,
+			supportsPromptCache: true,
+		})
+		// The snapshot wins wholesale: catalog metadata it does not carry is dropped
+		// rather than merged, so the resolved value matches what the user configured.
+		expect(resolved?.description).toBeUndefined()
+	})
+
+	it("keeps provider-owned pricing from the catalog entry", () => {
+		const resolved = applyCustomModelInfo(catalogModel, {
+			customModelInfo: { contextWindow: 128_000, supportsPromptCache: false },
+		})
+
+		expect(resolved).toMatchObject({
+			inputPrice: 0.1,
+			outputPrice: 0.2,
+			cacheWritesPrice: 0.3,
+			cacheReadsPrice: 0.4,
+		})
+	})
+
+	it("resolves an unlisted model without any catalog entry", () => {
+		const resolved = applyCustomModelInfo(undefined, {
+			customModelInfo: { contextWindow: 64_000, maxTokens: 8_192, supportsPromptCache: false },
+		})
+
+		expect(resolved).toMatchObject({ contextWindow: 64_000, maxTokens: 8_192 })
+	})
+
+	it("does not invent pricing when the catalog has none", () => {
+		const resolved = applyCustomModelInfo(undefined, {
+			customModelInfo: { contextWindow: 64_000, supportsPromptCache: false },
+		})
+
+		expect(resolved && "inputPrice" in resolved).toBe(false)
+		expect(resolved && "tiers" in resolved).toBe(false)
+	})
+
+	it("passes discovered metadata through untouched when nothing is configured", () => {
+		expect(applyCustomModelInfo(catalogModel, {})).toEqual(catalogModel)
+		expect(applyCustomModelInfo(catalogModel, { customModelInfo: null })).toEqual(catalogModel)
+		expect(applyCustomModelInfo(undefined, {})).toBeUndefined()
+	})
+
+	it("strips pricing when seeding the editor from a catalog entry", () => {
+		const seeded = toCustomModelInfo(catalogModel)
+
+		expect(seeded).toMatchObject({ contextWindow: 8192, maxTokens: 4096, description: "Provider metadata" })
+		expect("inputPrice" in seeded).toBe(false)
+		expect("cacheReadsPrice" in seeded).toBe(false)
+	})
+
+	it("rejects pricing fields in the persisted override schema", () => {
+		expect(
+			customModelInfoSchema.safeParse({ contextWindow: 64_000, supportsPromptCache: false, inputPrice: 1 })
+				.success,
+		).toBe(false)
+		expect(
+			providerSettingsSchemaDiscriminated.safeParse({
+				apiProvider: providerIdentifiers.openrouter,
+				customModelInfo: { contextWindow: 64_000, supportsPromptCache: false, outputPrice: 1 },
+			}).success,
+		).toBe(false)
+	})
+
+	it("requires a context window in the persisted override schema", () => {
+		expect(customModelInfoSchema.safeParse({ supportsPromptCache: false }).success).toBe(false)
+		expect(customModelInfoSchema.safeParse({ contextWindow: 64_000, supportsPromptCache: false }).success).toBe(
+			true,
+		)
+	})
+
+	// `modelInfoSchema` accepts any number because a provider catalog is not ours
+	// to police. User input is, and these two values drive token accounting and the
+	// outgoing max_completion_tokens.
+	it.each([
+		{ label: "zero", contextWindow: 0 },
+		{ label: "negative", contextWindow: -1 },
+		{ label: "fractional", contextWindow: 1.5 },
+		{ label: "non-finite", contextWindow: Number.POSITIVE_INFINITY },
+		{ label: "beyond safe integer range", contextWindow: Number.MAX_SAFE_INTEGER + 2 },
+	])("rejects a $label context window override", ({ contextWindow }) => {
+		expect(customModelInfoSchema.safeParse({ contextWindow, supportsPromptCache: false }).success).toBe(false)
+	})
+
+	it.each([
+		{ label: "zero", maxTokens: 0 },
+		{ label: "negative", maxTokens: -1 },
+		{ label: "fractional", maxTokens: 1.5 },
+		{ label: "non-finite", maxTokens: Number.POSITIVE_INFINITY },
+	])("rejects a $label max output tokens override", ({ maxTokens }) => {
+		expect(
+			customModelInfoSchema.safeParse({ contextWindow: 64_000, maxTokens, supportsPromptCache: false }).success,
+		).toBe(false)
+	})
+
+	it("accepts an absent max output tokens as provider-decided", () => {
+		expect(customModelInfoSchema.safeParse({ contextWindow: 64_000, supportsPromptCache: false }).success).toBe(
+			true,
+		)
+		expect(
+			customModelInfoSchema.safeParse({ contextWindow: 64_000, maxTokens: null, supportsPromptCache: false })
+				.success,
+		).toBe(true)
+	})
+})

packages/types/src/model.ts

@@ -185,6 +185,95 @@ export const modelInfoSchema = z.object({
 
 export type ModelInfo = z.infer<typeof modelInfoSchema>
 
+/**
+ * User-supplied model metadata for a model whose discovered metadata is
+ * incomplete or unavailable.
+ *
+ * This mirrors the long-standing `openAiCustomModelInfo` contract: the stored
+ * value is a complete snapshot that the settings UI prefills from the
+ * discovered catalog entry. Resolution therefore stays a single expression at
+ * every call site and a configured override can never resolve to `undefined`.
+ *
+ * Pricing is deliberately excluded. Router catalogs own prices and refresh
+ * them, so a user-held price snapshot would go stale and silently corrupt cost
+ * reporting.
+ */
+export const customModelInfoSchema = modelInfoSchema
+	.omit({
+		inputPrice: true,
+		outputPrice: true,
+		cacheWritesPrice: true,
+		cacheReadsPrice: true,
+		longContextPricing: true,
+		tiers: true,
+	})
+	.extend({
+		// `modelInfoSchema` accepts any number because a provider catalog is not
+		// ours to validate. User input is, and these two values drive token
+		// accounting and the outgoing max_completion_tokens, so reject the values
+		// that would produce NaN percentages or a request the gateway rejects.
+		contextWindow: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+		maxTokens: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullish(),
+	})
+	// `strict()` is what actually rejects a pricing field: omitting a key only
+	// drops it from the shape, it does not make the value invalid.
+	.strict()
+
+export type CustomModelInfo = z.infer<typeof customModelInfoSchema>
+
+export type CustomModelInfoSettings = {
+	customModelInfo?: CustomModelInfo | null
+}
+
+/**
+ * Strips provider-owned pricing so the settings UI can prefill the editor from
+ * a discovered catalog entry.
+ */
+export const toCustomModelInfo = (info: ModelInfo): CustomModelInfo => {
+	const {
+		inputPrice: _inputPrice,
+		outputPrice: _outputPrice,
+		cacheWritesPrice: _cacheWritesPrice,
+		cacheReadsPrice: _cacheReadsPrice,
+		longContextPricing: _longContextPricing,
+		tiers: _tiers,
+		...rest
+	} = info
+
+	return rest
+}
+
+/**
+ * Resolves the effective model metadata for providers that expose the custom
+ * model info editor.
+ *
+ * A configured override replaces the discovered metadata wholesale; pricing is
+ * always read back from the catalog entry. Without an override the discovered
+ * metadata passes through untouched.
+ */
+export const applyCustomModelInfo = (
+	info: ModelInfo | undefined,
+	settings: CustomModelInfoSettings | undefined,
+): ModelInfo | undefined => {
+	const override = settings?.customModelInfo
+
+	if (!override) {
+		return info
+	}
+
+	// Copy only the price keys the catalog actually carries, so the result never
+	// gains explicit `undefined` pricing fields.
+	return {
+		...override,
+		...(info?.inputPrice !== undefined && { inputPrice: info.inputPrice }),
+		...(info?.outputPrice !== undefined && { outputPrice: info.outputPrice }),
+		...(info?.cacheWritesPrice !== undefined && { cacheWritesPrice: info.cacheWritesPrice }),
+		...(info?.cacheReadsPrice !== undefined && { cacheReadsPrice: info.cacheReadsPrice }),
+		...(info?.longContextPricing !== undefined && { longContextPricing: info.longContextPricing }),
+		...(info?.tiers !== undefined && { tiers: info.tiers }),
+	}
+}
+
 export type ModelRecord = Record<string, ModelInfo>
 
 export type RouterModels = Record<DynamicProvider | LocalProvider, ModelRecord>

packages/types/src/provider-settings.ts

@@ -81,6 +81,28 @@ export type DynamicProvider = (typeof dynamicProviders)[number]
 export const isDynamicProvider = (key: string): key is DynamicProvider =>
 	dynamicProviders.includes(key as DynamicProvider)
 
+/**
+ * Providers that accept user-supplied `customModelInfo` overrides in the
+ * settings UI. This is a strict subset of `dynamicProviders` — only providers
+ * whose model metadata can be manually adjusted by the user.
+ *
+ * NOTE: Of these, only vercel-ai-gateway and zoo-gateway apply the overlay
+ * inside `RouterProvider.resolveModelInfo()`. The others (openrouter, requesty,
+ * unbound) apply it in their own overridden `getModel()` methods.
+ */
+export const customModelInfoProviders = [
+	providerIdentifiers.openrouter,
+	providerIdentifiers.requesty,
+	providerIdentifiers.unbound,
+	providerIdentifiers.vercelAiGateway,
+	providerIdentifiers.zooGateway,
+] as const
+
+export type CustomModelInfoProvider = (typeof customModelInfoProviders)[number]
+
+export const isCustomModelInfoProvider = (key: string): key is CustomModelInfoProvider =>
+	customModelInfoProviders.includes(key as CustomModelInfoProvider)
+
 /**
  * LocalProvider
  *

packages/types/src/provider-settings/common.ts

@@ -1,6 +1,6 @@
 import { z } from "zod"
 
-import { reasoningEffortSettingSchema, verbosityLevelsSchema } from "../model.js"
+import { customModelInfoSchema, reasoningEffortSettingSchema, verbosityLevelsSchema } from "../model.js"
 import type { ProviderIdentifier } from "../provider-identifiers.js"
 
 export const API_PROVIDER_FIELD = "apiProvider"
@@ -18,6 +18,7 @@ export const baseProviderSettingsShape = {
 	modelMaxTokens: z.number().optional(),
 	modelMaxThinkingTokens: z.number().optional(),
 	verbosity: verbosityLevelsSchema.optional(),
+	customModelInfo: customModelInfoSchema.nullish(),
 }
 
 export const apiModelIdProviderModelShape = {

src/api/providers/__tests__/kenari.spec.ts

@@ -81,6 +81,17 @@ describe("KenariHandler", () => {
 			expect(result.info.supportsPromptCache).toBe(false)
 		})
 
+		it("does not apply gateway-only custom metadata overrides", async () => {
+			const handler = new KenariHandler({
+				...mockOptions,
+				customModelInfo: { contextWindow: 100_000, maxTokens: 10_000, supportsPromptCache: false },
+			})
+			const result = await handler.fetchModel()
+
+			expect(result.info.contextWindow).toBe(1_048_576)
+			expect(result.info.maxTokens).toBe(32_768)
+		})
+
 		it("falls back to the default model id when none is configured", async () => {
 			const handler = new KenariHandler({ kenariApiKey: "test-key" })
 			const result = await handler.fetchModel()