fix(opencode-go): hide unavailable hy3 from catalogs (#82)

Author: lidge-jun

src/codex/catalog.ts

@@ -303,6 +303,20 @@ type RawEntry = Record<string, unknown>;
 type RawCatalog = { models?: RawEntry[]; [k: string]: unknown };
 const JAWCODE_CATALOG_AUGMENT_PROVIDERS = new Set(["opencode-go"]);
 
+/**
+ * Exact provider/model pairs whose discovery endpoint advertises them but whose inference backend
+ * rejects them. Apply this after live/static/metadata sources converge so no source can resurrect
+ * an uncallable picker row. Remove an entry once authenticated inference proves it usable again.
+ */
+const ROUTED_MODEL_COMPATIBILITY_EXCLUSIONS = new Set([
+  // Issue #82: Zen Go /models advertises HY3, but Console Go rejects it as outside the lite list.
+  "opencode-go/hy3-preview",
+]);
+
+function isRoutedModelCompatibilityExcluded(slug: string): boolean {
+  return ROUTED_MODEL_COMPATIBILITY_EXCLUSIONS.has(slug);
+}
+
 /**
  * Image/video GENERATION model families. opencodex routes chat/coding models into Codex; media-
  * generation models (Grok image/video, DALL·E, Imagen, Sora, Veo, …) are useless to a coding agent
@@ -328,6 +342,7 @@ export function isMediaGenerationModelId(id: string): boolean {
 }
 
 function shouldExposeRoutedModel(model: CatalogModel): boolean {
+  if (isRoutedModelCompatibilityExcluded(`${model.provider}/${model.id}`)) return false;
   if (model.provider === "cursor" && model.id === "gemini-3-pro-image-preview") return true;
   return !isMediaGenerationModelId(model.id);
 }
@@ -1329,9 +1344,10 @@ export function mergeCatalogEntriesForSync(
   }
 
   let finalRoutedEntries = routedEntries;
-  if (routedEntries.length === 0 && catalogModels.some(m => typeof m.slug === "string" && (m.slug as string).includes("/"))) {
+  const preservingExistingRouted = routedEntries.length === 0
+    && catalogModels.some(m => typeof m.slug === "string" && (m.slug as string).includes("/"));
+  if (preservingExistingRouted) {
     finalRoutedEntries = catalogModels.filter(m => typeof m.slug === "string" && (m.slug as string).includes("/"));
-    console.warn(`[opencodex] catalog sync: routed model fetch returned empty; preserving ${finalRoutedEntries.length} existing routed entr${finalRoutedEntries.length === 1 ? "y" : "ies"} on disk.`);
   } else {
     const freshSlugs = new Set(routedEntries.flatMap(entry => typeof entry.slug === "string" ? [entry.slug] : []));
     const preservedForeignRouted = catalogModels.filter(m => {
@@ -1341,6 +1357,14 @@ export function mergeCatalogEntriesForSync(
     });
     finalRoutedEntries = [...routedEntries, ...preservedForeignRouted];
   }
+  // Reapply final catalog policy to rows preserved from disk. Those rows bypass
+  // gatherRoutedModels, so filtering only the freshly gathered list can resurrect an excluded id.
+  finalRoutedEntries = finalRoutedEntries.filter(entry =>
+    typeof entry.slug !== "string" || !isRoutedModelCompatibilityExcluded(entry.slug)
+  );
+  if (preservingExistingRouted) {
+    console.warn(`[opencodex] catalog sync: routed model fetch returned empty; preserving ${finalRoutedEntries.length} existing routed entr${finalRoutedEntries.length === 1 ? "y" : "ies"} on disk.`);
+  }
 
   const mergedEntries = [...native, ...finalRoutedEntries].map(m => {
     const normalized = normalizeServiceTiers(m);

structure/03_catalog-and-subagents.md

@@ -11,6 +11,8 @@
 - forces strict Codex catalog fields required by the current parser;
 - hides `disabledModels` (routed namespaced ids are excluded; BARE native slugs flip the
   catalog entry to `visibility: "hide"` and drop from the bare `/v1/models` list);
+- applies exact provider/model compatibility exclusions after live discovery and metadata
+  augmentation, so upstream-advertised but uncallable rows never enter dashboard or Codex pickers;
 - strips native-only service tier and WebSocket metadata unless explicitly enabled;
 - backs up the pristine catalog once to `~/.opencodex/catalog-backup.json`;
 - invalidates `$CODEX_HOME/models_cache.json` when model visibility changes.

tests/codex-catalog-sync-hardening.test.ts

@@ -118,6 +118,31 @@ describe("Codex catalog sync hardening", () => {
     expect(slugs).toContain("gpt-5.5");
   });
 
+  test("empty routed refresh drops compatibility-excluded rows while preserving other routed entries", () => {
+    const catalogPath = join(codexHome, "catalog.json");
+    writeFileSync(join(codexHome, "config.toml"), 'model_catalog_json = "catalog.json"\n', "utf8");
+    writeFileSync(catalogPath, JSON.stringify({
+      models: [
+        nativeEntry("gpt-5.5", 0),
+        routedEntry("kiro/claude-opus-4.8", 5),
+        routedEntry("opencode-go/glm-5.2", 6),
+        routedEntry("opencode-go/hy3-preview", 7),
+      ],
+    }, null, 2) + "\n");
+
+    const r = runScript(codexHome, opencodexHome, `
+      const { syncCatalogModels } = require("./src/codex/catalog");
+      syncCatalogModels({ providers: {} }).then(res => console.log(JSON.stringify(res)));
+    `);
+    expect(r.status).toBe(0);
+    expect(r.stderr).toContain("routed model fetch returned empty; preserving 2 existing routed entries");
+
+    const slugs = (JSON.parse(readFileSync(catalogPath, "utf8")).models as Array<{ slug: string }>).map(m => m.slug);
+    expect(slugs).toContain("kiro/claude-opus-4.8");
+    expect(slugs).toContain("opencode-go/glm-5.2");
+    expect(slugs).not.toContain("opencode-go/hy3-preview");
+  });
+
   test("preserves existing routed entries for providers absent from the current sync config", () => {
     const catalogPath = join(codexHome, "catalog.json");
     writeFileSync(join(codexHome, "config.toml"), 'model_catalog_json = "catalog.json"\n', "utf8");

tests/provider-live-models.test.ts

@@ -8,6 +8,8 @@ import type { OcxConfig } from "../src/types";
 // authority/fallback contract of fetchProviderModels through the public gatherRoutedModels seam.
 
 const PROVIDER = "xai-live-test";
+const HY3_PROVIDER = "opencode-go";
+const HY3_CONTROL_PROVIDER = "hy3-control-live-test";
 
 function config(): OcxConfig {
   return {
@@ -29,6 +31,8 @@ const originalFetch = globalThis.fetch;
 afterEach(() => {
   globalThis.fetch = originalFetch;
   clearModelCache(PROVIDER);
+  clearModelCache(HY3_PROVIDER);
+  clearModelCache(HY3_CONTROL_PROVIDER);
 });
 
 describe("live provider model discovery (authority + fallback)", () => {
@@ -67,6 +71,45 @@ describe("live provider model discovery (authority + fallback)", () => {
     }
   });
 
+  test("HY3 compatibility guard hides only opencode-go/hy3-preview from live discovery", async () => {
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      const isOpenCodeGo = String(url).startsWith("https://opencode-go.test/");
+      return new Response(JSON.stringify({
+        data: isOpenCodeGo
+          ? [
+              { id: "glm-5.2" },
+              { id: "hy3-preview" },
+              { id: "future-live-model" },
+            ]
+          : [{ id: "hy3-preview" }],
+      }), { status: 200, headers: { "content-type": "application/json" } });
+    }) as typeof fetch;
+
+    const models = await gatherRoutedModels({
+      providers: {
+        [HY3_PROVIDER]: {
+          baseUrl: "https://opencode-go.test/v1",
+          adapter: "openai-chat",
+          authMode: "key",
+          apiKey: "sk-test",
+          models: ["glm-5.2"],
+        },
+        [HY3_CONTROL_PROVIDER]: {
+          baseUrl: "https://hy3-control.test/v1",
+          adapter: "openai-chat",
+          authMode: "key",
+          apiKey: "sk-test",
+        },
+      },
+    } as unknown as OcxConfig);
+    const slugs = models.map(model => `${model.provider}/${model.id}`);
+
+    expect(slugs).not.toContain("opencode-go/hy3-preview");
+    expect(slugs).toContain("opencode-go/glm-5.2");
+    expect(slugs).toContain("opencode-go/future-live-model");
+    expect(slugs).toContain("hy3-control-live-test/hy3-preview");
+  });
+
   test("fetch failure falls back to the configured static list", async () => {
     globalThis.fetch = (async () => {
       throw new Error("network down");