Skip to content

Commit c080449

Browse files
Preserve custom model display names
1 parent 54e0bbf commit c080449

3 files changed

Lines changed: 168 additions & 1 deletion

File tree

‎docs-site/src/content/docs/guides/codex-integration.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,32 @@ Routed catalog entries also get their GPT-5 identity rewritten to the real upstr
127127
Reasoning controls come from provider/model metadata across Codex's `low | medium | high | xhigh |
128128
max | ultra` ladder; unsupported values are mapped or clamped before the upstream request.
129129

130+
### Custom model display names
131+
132+
A custom model can carry a human-readable **display name** that overrides the label Codex shows in
133+
its model picker, without changing anything about how the model is routed. The display name maps to
134+
the catalog entry's `display_name` field only — the routing slug (`<provider>/<model>`), alias
135+
collision order, provider, and native OpenAI marketing names are all left untouched.
136+
137+
Add a display name from the CLI (the proxy syncs the catalog right away when live):
138+
139+
```bash
140+
ocx models add deepseek deepseek-v4 --display-name "DeepSeek V4" --context-window 128000
141+
```
142+
143+
You can also set or edit it through the management API (`POST /api/custom-models`,
144+
`PUT /api/custom-models/<id>` with a `displayName` string) and the web dashboard. A `/` is rejected
145+
because it would collide with the routed-slug separator.
146+
147+
The display name is **display-only and stable across regeneration**. Every `ocx sync` and catalog
148+
refresh re-derives routed entries from `config.json` (including `customModels`), so the configured
149+
name is reapplied instead of drifting back to the routed slug. A managed service restart also attempts
150+
this sync shortly after the proxy binds. If that best-effort boot sync fails, for example during an
151+
offline login, the previously persisted catalog is retained and the next successful `ocx sync`
152+
reapplies the configured name. Genuine upstream native names (e.g. `gpt-5.6-sol` →
153+
"GPT-5.6-Sol") come from the pinned upstream snapshot and are never overridden by a custom display
154+
name.
155+
130156
## The subagent picker
131157

132158
Codex's `spawn_agent` advertises the first **5 picker-visible catalog models** after sorting by

‎src/codex/catalog.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -371,6 +371,14 @@ export interface CatalogModel {
371371
provider: string;
372372
/** Public Codex-facing slug override (used by combo aliases). */
373373
alias?: string;
374+
/**
375+
* Display-only Codex catalog `display_name` override. Relabels the picker row ONLY — it never
376+
* affects the routing slug, alias-collision order, native marketing-name precedence, or provider
377+
* behavior. When unset, the entry falls back to its Codex-facing slug (the historical behavior).
378+
* Native upstream entries (e.g. gpt-5.6-sol → "GPT-5.6-Sol") come from the pinned snapshot path
379+
* which carries no CatalogModel, so a configured displayName can never override a native name.
380+
*/
381+
displayName?: string;
374382
owned_by?: string;
375383
reasoningEfforts?: string[];
376384
defaultReasoningEffort?: string;
@@ -801,6 +809,14 @@ function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel): void
801809
// This marker survives strict catalog normalization and lets sync distinguish a stale
802810
// bare combo alias from a genuine native model row.
803811
if (model.provider === COMBO_NAMESPACE) entry.owned_by = model.owned_by ?? COMBO_NAMESPACE;
812+
// displayName is DISPLAY-ONLY: it relabels the picker row but never touches the routing
813+
// slug, alias, or provider. deriveEntry already stamped the slug as display_name; a
814+
// configured displayName overrides just the label. The `/` separator is rejected at every
815+
// input boundary (CLI `ocx models add`, management API), so the catalog trusts its source.
816+
// Combos carry no displayName, and natives never reach here (no CatalogModel), so genuine
817+
// upstream marketing names and combo alias labels are preserved untouched.
818+
const displayName = typeof model.displayName === "string" ? model.displayName.trim() : "";
819+
if (displayName) entry.display_name = displayName;
804820
if (typeof model.contextWindow === "number" && model.contextWindow > 0) {
805821
entry.context_window = model.contextWindow;
806822
entry.max_context_window = model.contextWindow;
@@ -1644,6 +1660,8 @@ export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogMode
16441660
const customModels = (config.customModels ?? []).map(cm => ({
16451661
id: cm.modelId,
16461662
provider: cm.provider,
1663+
// Display-only label: never feeds routing (customModels are keyed by routedSlug below).
1664+
...(cm.displayName ? { displayName: cm.displayName } : {}),
16471665
...(cm.contextWindow ? { contextWindow: cm.contextWindow } : {}),
16481666
...(cm.inputModalities ? { inputModalities: cm.inputModalities } : {}),
16491667
}));

‎tests/codex-catalog.test.ts‎

Lines changed: 124 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { afterEach, describe, expect, spyOn, test } from "bun:test";
22
import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import { join } from "node:path";
5-
import { augmentRoutedModelsWithJawcodeMetadata, augmentRoutedModelsWithRegistryOpenAiApiRows, buildCatalogEntries, clampCatalogModelsToCodexSupport, clampEntryToCodexSupportedEfforts, clampedDefaultEffort, deriveComboCatalogModel, exactComboCatalogSlugs, filterCatalogVisibleModels, filterSupportedNativeSlugs, gatherRoutedModels, isDatedVariantId, isMediaGenerationModelId, loadBundledCodexCatalog, materializeBundledCodexCatalog, mergeCatalogEntriesForSync, NATIVE_OPENAI_MODELS, normalizeRoutedCatalogEntry, resetCatalogRuntimeStateForTests, resetOpenAiApiCatalogWarningStateForTests } from "../src/codex/catalog";
5+
import { augmentRoutedModelsWithJawcodeMetadata, augmentRoutedModelsWithRegistryOpenAiApiRows, buildCatalogEntries, catalogModelSlug, clampCatalogModelsToCodexSupport, clampEntryToCodexSupportedEfforts, clampedDefaultEffort, deriveComboCatalogModel, exactComboCatalogSlugs, filterCatalogVisibleModels, filterSupportedNativeSlugs, gatherRoutedModels, isDatedVariantId, isMediaGenerationModelId, loadBundledCodexCatalog, materializeBundledCodexCatalog, mergeCatalogEntriesForSync, NATIVE_OPENAI_MODELS, normalizeRoutedCatalogEntry, resetCatalogRuntimeStateForTests, resetOpenAiApiCatalogWarningStateForTests } from "../src/codex/catalog";
66
import {
77
CURSOR_STATIC_MODELS,
88
filterCursorConfiguredModelsByLiveDiscovery,
@@ -521,6 +521,129 @@ describe("Google Gemini catalog metadata", () => {
521521
});
522522
});
523523

524+
describe("configured CatalogModel displayName -> catalog display_name", () => {
525+
test("a routed CatalogModel displayName becomes the catalog display_name", () => {
526+
const model = { provider: "deepseek", id: "deepseek-v4", displayName: "DeepSeek V4", owned_by: "deepseek" };
527+
const entries = buildCatalogEntries(nativeTemplate(), [], [model]);
528+
const row = entries.find(e => e.slug === "deepseek/deepseek-v4");
529+
530+
expect(row?.display_name).toBe("DeepSeek V4");
531+
// Routing slug is untouched — displayName is display-only.
532+
expect(row?.slug).toBe("deepseek/deepseek-v4");
533+
expect(catalogModelSlug(model)).toBe("deepseek/deepseek-v4");
534+
});
535+
536+
test("absent displayName leaves display_name as the slug (unchanged behavior)", () => {
537+
const entries = buildCatalogEntries(nativeTemplate(), [], [
538+
{ provider: "anthropic", id: "claude-sonnet-4-6", owned_by: "anthropic" },
539+
]);
540+
const row = entries.find(e => e.slug === "anthropic/claude-sonnet-4-6");
541+
542+
expect(row?.display_name).toBe("anthropic/claude-sonnet-4-6");
543+
expect(row?.slug).toBe("anthropic/claude-sonnet-4-6");
544+
});
545+
546+
test("empty/whitespace displayName is ignored and falls back to the slug", () => {
547+
const entries = buildCatalogEntries(nativeTemplate(), [], [
548+
{ provider: "deepseek", id: "deepseek-v4", displayName: " ", owned_by: "deepseek" },
549+
]);
550+
const row = entries.find(e => e.slug === "deepseek/deepseek-v4");
551+
expect(row?.display_name).toBe("deepseek/deepseek-v4");
552+
});
553+
554+
test("displayName never affects the routing slug, alias, or provider", () => {
555+
const withAlias = { provider: "combo", id: "x", alias: "fast-chat", displayName: "Fast Chat", owned_by: "combo" };
556+
const entries = buildCatalogEntries(nativeTemplate(), [], [withAlias], undefined, false, "default", new Set(["fast-chat"]));
557+
const row = entries.find(e => e.slug === "fast-chat")!;
558+
559+
// The public alias is still the slug; only the label changed.
560+
expect(row.slug).toBe("fast-chat");
561+
expect(catalogModelSlug(withAlias)).toBe("fast-chat");
562+
expect(row.display_name).toBe("Fast Chat");
563+
expect(row.owned_by).toBe("combo");
564+
});
565+
566+
test("displayName stays stable across repeated catalog sync (idempotent regeneration)", () => {
567+
const model = { provider: "deepseek", id: "deepseek-v4", displayName: "DeepSeek V4", owned_by: "deepseek" };
568+
const rebuild = () => buildCatalogEntries(nativeTemplate(), [], [model]);
569+
570+
// First sync: freshly built entries merged into an empty on-disk catalog.
571+
const firstSync = mergeCatalogEntriesForSync([], rebuild(), new Map(), [], false);
572+
const firstRow = firstSync.find(e => e.slug === "deepseek/deepseek-v4")!;
573+
expect(firstRow.display_name).toBe("DeepSeek V4");
574+
575+
// Second sync: re-derive from the SAME config and merge against the now-populated catalog.
576+
// Routed entries are rebuilt from gatherRoutedModels each sync, so display_name must be
577+
// re-derived deterministically and never drift back to the bare slug.
578+
const secondSync = mergeCatalogEntriesForSync(firstSync, rebuild(), new Map(), [], false);
579+
const secondRow = secondSync.find(e => e.slug === "deepseek/deepseek-v4")!;
580+
expect(secondRow.display_name).toBe("DeepSeek V4");
581+
expect(secondRow.slug).toBe("deepseek/deepseek-v4");
582+
});
583+
584+
test("configured displayName does not override genuine native upstream marketing names", () => {
585+
// Native gpt-5.6-* entries come from the pinned upstream snapshot with their real display
586+
// names; they carry no CatalogModel (isRouted=false), so a configured displayName can never
587+
// reach them — and the fallback-quality discriminator (display_name === slug) still works.
588+
const entries = buildCatalogEntries(nativeTemplate(), ["gpt-5.6-sol"], []);
589+
const sol = entries.find(e => e.slug === "gpt-5.6-sol");
590+
expect(sol?.display_name).toBe("GPT-5.6-Sol");
591+
592+
// A fallback-quality native (display_name stamped with the bare slug) is still upgraded to
593+
// the upstream entry by sync — displayName on routed models does not interfere with that path.
594+
const synthesizedLuna = {
595+
...nativeTemplate(),
596+
slug: "gpt-5.6-luna",
597+
display_name: "gpt-5.6-luna",
598+
priority: 9,
599+
};
600+
const merged = mergeCatalogEntriesForSync([synthesizedLuna], [], new Map(), [], false);
601+
expect(merged.find(e => e.slug === "gpt-5.6-luna")?.display_name).toBe("GPT-5.6-Luna");
602+
});
603+
604+
test("a configured customModel displayName propagates end-to-end through gatherRoutedModels", async () => {
605+
clearModelCache("custom-provider");
606+
const originalFetch = globalThis.fetch;
607+
let fetchCalls = 0;
608+
globalThis.fetch = (() => {
609+
fetchCalls += 1;
610+
throw new Error("fetch should not be called");
611+
}) as typeof fetch;
612+
try {
613+
const models = await gatherRoutedModels({
614+
port: 10100,
615+
defaultProvider: "custom-provider",
616+
providers: {
617+
"custom-provider": {
618+
baseUrl: "https://example.invalid/v1",
619+
adapter: "openai-chat",
620+
authMode: "key",
621+
liveModels: false,
622+
models: ["baseline-model"],
623+
},
624+
},
625+
customModels: [
626+
{ id: "cm-1", provider: "custom-provider", modelId: "renamed-model", displayName: "Renamed Model", addedAt: "2026-01-01T00:00:00.000Z" },
627+
],
628+
});
629+
630+
expect(fetchCalls).toBe(0);
631+
// The configured custom row is added alongside the provider's baseline model; displayName
632+
// rides only on the custom row.
633+
const custom = models.find(m => m.provider === "custom-provider" && m.id === "renamed-model");
634+
expect(custom?.displayName).toBe("Renamed Model");
635+
636+
const entries = buildCatalogEntries(nativeTemplate(), [], models);
637+
const row = entries.find(e => e.slug === "custom-provider/renamed-model");
638+
expect(row?.display_name).toBe("Renamed Model");
639+
expect(row?.slug).toBe("custom-provider/renamed-model");
640+
} finally {
641+
globalThis.fetch = originalFetch;
642+
clearModelCache("custom-provider");
643+
}
644+
});
645+
});
646+
524647
function openAiApiCatalogConfig(overrides: Record<string, unknown> = {}): OcxConfig {
525648
return {
526649
port: 10100,

0 commit comments

Comments
 (0)