feat(catalog): per-provider selectedModels allowlist to trim oversized catalogs (#52)

A custom API proxy (or an aggregator like OpenRouter) exposing thousands of live
models bloats the Codex catalog (50MB+) and the Models page. Add an opt-in
per-provider `selectedModels` allowlist: when non-empty, only those ids ship to
the Codex catalog and /v1/models — live discovery still runs, this only narrows
what is emitted. Applied via a single choke point (filterCatalogVisibleModels)
at both catalog emission points; the admin /api/models list stays unfiltered so
the picker can show the full set. Adds /api/selected-models GET/PUT.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: lidge-jun

src/codex-catalog.ts

@@ -815,6 +815,30 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
   }
 }
 
+/**
+ * Narrow a raw routed-model list to what Codex's catalog / clients should see: drop the
+ * `disabledModels` blocklist AND, for any provider with a non-empty `selectedModels` allowlist, keep
+ * only those ids. This is the single choke point applied at every CATALOG emission point (on-disk
+ * sync + /v1/models); the admin `/api/models` list stays unfiltered so the picker can show the full
+ * set. Live discovery is unaffected — this only decides what ships. See issue_052.
+ */
+export function filterCatalogVisibleModels(
+  models: CatalogModel[],
+  config: Pick<OcxConfig, "disabledModels" | "providers">,
+): CatalogModel[] {
+  const disabled = new Set(config.disabledModels ?? []);
+  const allowByProvider = new Map<string, Set<string>>();
+  for (const [name, prov] of Object.entries(config.providers)) {
+    const sel = prov.selectedModels;
+    if (Array.isArray(sel) && sel.length > 0) allowByProvider.set(name, new Set(sel));
+  }
+  return models.filter(m => {
+    if (disabled.has(`${m.provider}/${m.id}`)) return false;
+    const allow = allowByProvider.get(m.provider);
+    return !allow || allow.has(m.id);
+  });
+}
+
 /**
  * Gather routed (non-forward) provider models across the config — the single source of truth for
  * the live model list, used by both the on-disk catalog sync and the proxy's /api/* + /v1/models
@@ -983,8 +1007,7 @@ export async function syncCatalogModels(config: OcxConfig): Promise<{ added: num
 
   // Hide disabled models from Codex, then feature the chosen subagent models (native OR routed)
   // by giving them the lowest priority — see buildCatalogEntries for why priority, not array order.
-  const disabled = new Set(config.disabledModels ?? []);
-  const enabledGo = goModels.filter(m => !disabled.has(`${m.provider}/${m.id}`));
+  const enabledGo = filterCatalogVisibleModels(goModels, config);
   const featured = config.subagentModels ?? [];
   const orderedGoModels = orderForSubagents(enabledGo, featured); // stable tie-break among equal priorities
   const goEntries = buildCatalogEntries(template ? JSON.parse(JSON.stringify(template)) : null, [], orderedGoModels, featured, websocketsEnabled(config));

src/server.ts

@@ -1981,6 +1981,38 @@ async function handleManagementAPI(req: Request, url: URL, config: OcxConfig): P
     return jsonResponse({ ok: true, applied: chosen });
   }
 
+  // Per-provider catalog allowlist (issue #52): when a provider has a non-empty selectedModels list,
+  // only those ids ship to Codex's catalog / /v1/models. GET returns the CURRENT selection plus the
+  // FULL available set per provider (unfiltered — the picker needs everything to choose from).
+  if (url.pathname === "/api/selected-models" && req.method === "GET") {
+    const models = await fetchAllModels(config);
+    const available: Record<string, string[]> = {};
+    for (const m of models) (available[m.provider] ??= []).push(m.id);
+    const selected: Record<string, string[]> = {};
+    for (const [name, prov] of Object.entries(config.providers)) {
+      if (Array.isArray(prov.selectedModels) && prov.selectedModels.length > 0) selected[name] = [...prov.selectedModels];
+    }
+    return jsonResponse({ selected, available });
+  }
+  if (url.pathname === "/api/selected-models" && req.method === "PUT") {
+    let body: { provider?: unknown; models?: unknown };
+    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    const provider = typeof body.provider === "string" ? body.provider : "";
+    if (!provider || !hasOwnProvider(config.providers, provider)) {
+      return jsonResponse({ error: "unknown provider" }, provider ? 404 : 400);
+    }
+    const models = Array.isArray(body.models)
+      ? [...new Set(body.models.filter((m): m is string => typeof m === "string"))]
+      : [];
+    // Empty list clears the allowlist (provider reverts to exposing all models).
+    if (models.length > 0) config.providers[provider].selectedModels = models;
+    else delete config.providers[provider].selectedModels;
+    const { saveConfig: save } = await import("./config");
+    save(config);
+    await refreshCodexCatalogBestEffort();
+    return jsonResponse({ ok: true, provider, selected: models });
+  }
+
   // OAuth login (xai now; anthropic/kimi in cycle 2). Starts the flow and returns the auth URL;
   // the provider's loopback callback server (inside this process) captures the redirect in the
   // background, then the credential is persisted. The GUI opens the URL and polls /api/oauth/status.
@@ -2141,10 +2173,9 @@ export function startServer(port?: number) {
           return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, config);
         }
         const goModels = await fetchAllModels(config);
-        const { buildCatalogEntries, loadCatalogTemplate, nativeOpenAiSlugs, orderForSubagents } = await import("./codex-catalog");
+        const { buildCatalogEntries, loadCatalogTemplate, nativeOpenAiSlugs, orderForSubagents, filterCatalogVisibleModels } = await import("./codex-catalog");
         const nativeSlugs = nativeOpenAiSlugs();
-        const disabledSet = new Set(config.disabledModels ?? []);
-        const goEnabled = goModels.filter(m => !disabledSet.has(`${m.provider}/${m.id}`));
+        const goEnabled = filterCatalogVisibleModels(goModels, config);
         const goOrdered = orderForSubagents(goEnabled, config.subagentModels);
         if (url.searchParams.has("client_version")) {
           // Codex client → Codex catalog shape: native gpt + namespaced routed models,

src/types.ts

@@ -339,6 +339,14 @@ export interface OcxProviderConfig {
    * or too flaky for startup/catalog sync.
    */
   liveModels?: boolean;
+  /**
+   * Per-provider catalog allowlist. When non-empty, ONLY these model ids are emitted to Codex's
+   * catalog and `/v1/models` — live discovery still runs, this just narrows what ships (so a proxy
+   * exposing thousands of models, or an aggregator like OpenRouter, doesn't bloat the catalog).
+   * Empty/undefined = expose all. The admin `/api/models` list is unaffected (it always shows the
+   * full set so the user can pick). See devlog issue_052_provider-model-allowlist.
+   */
+  selectedModels?: string[];
   /** Provider-wide Codex-visible context-window cap for routed catalog entries. */
   contextWindow?: number;
   /** Model-specific Codex-visible context-window caps. Values cap live metadata, never raise it. */

tests/selected-models.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { filterCatalogVisibleModels, type CatalogModel } from "../src/codex-catalog";
+import type { OcxConfig, OcxProviderConfig } from "../src/types";
+
+function m(provider: string, id: string): CatalogModel {
+  return { provider, id, owned_by: provider };
+}
+
+function cfg(providers: Record<string, Partial<OcxProviderConfig>>, disabledModels?: string[]): Pick<OcxConfig, "disabledModels" | "providers"> {
+  const full: Record<string, OcxProviderConfig> = {};
+  for (const [name, p] of Object.entries(providers)) full[name] = { adapter: "openai-chat", baseUrl: "https://x", ...p };
+  return { providers: full, ...(disabledModels ? { disabledModels } : {}) };
+}
+
+describe("filterCatalogVisibleModels — per-provider allowlist", () => {
+  const models = [m("proxy", "a"), m("proxy", "b"), m("proxy", "c"), m("openai", "gpt-5.5")];
+
+  test("no selectedModels → all models pass", () => {
+    const out = filterCatalogVisibleModels(models, cfg({ proxy: {}, openai: {} }));
+    expect(out.map(x => x.id).sort()).toEqual(["a", "b", "c", "gpt-5.5"]);
+  });
+
+  test("empty selectedModels array → treated as all", () => {
+    const out = filterCatalogVisibleModels(models, cfg({ proxy: { selectedModels: [] }, openai: {} }));
+    expect(out.map(x => x.id).sort()).toEqual(["a", "b", "c", "gpt-5.5"]);
+  });
+
+  test("non-empty allowlist keeps only listed ids for that provider, others untouched", () => {
+    const out = filterCatalogVisibleModels(models, cfg({ proxy: { selectedModels: ["a", "c"] }, openai: {} }));
+    expect(out.map(x => `${x.provider}/${x.id}`).sort()).toEqual(["openai/gpt-5.5", "proxy/a", "proxy/c"]);
+  });
+
+  test("allowlist is per-provider — an id present under another provider is not leaked", () => {
+    const withDup = [...models, m("openai", "a")];
+    const out = filterCatalogVisibleModels(withDup, cfg({ proxy: { selectedModels: ["a"] }, openai: {} }));
+    expect(out.map(x => `${x.provider}/${x.id}`).sort()).toEqual(["openai/a", "openai/gpt-5.5", "proxy/a"]);
+  });
+
+  test("disabledModels blocklist still applies alongside the allowlist", () => {
+    const out = filterCatalogVisibleModels(models, cfg({ proxy: { selectedModels: ["a", "b"] }, openai: {} }, ["proxy/b"]));
+    expect(out.map(x => `${x.provider}/${x.id}`).sort()).toEqual(["openai/gpt-5.5", "proxy/a"]);
+  });
+
+  test("large list collapses to the few selected (the issue #52 shape)", () => {
+    const big = Array.from({ length: 2000 }, (_, i) => m("proxy", `model-${i}`));
+    const out = filterCatalogVisibleModels(big, cfg({ proxy: { selectedModels: ["model-7", "model-1999"] } }));
+    expect(out.map(x => x.id).sort()).toEqual(["model-1999", "model-7"]);
+  });
+});