Merge pull request #246 from pylon-code/upstream/2026-09-02-claude-manifest

feat(models): discover Claude models from a remote manifest

Author: rynfar

apps/server/src/provider/ClaudeModelCatalog.test.ts

@@ -0,0 +1,137 @@
+import { assert, describe, it } from "@effect/vitest";
+import { ProviderInstanceId } from "@t3tools/contracts";
+
+import { hasValidClaudeManifestAdapters } from "./ClaudeModelManifest.ts";
+import type { ModelManifestData } from "./ModelManifest.ts";
+import {
+  formatClaudeVersionUpgradeMessage,
+  normalizeClaudeCatalogEffort,
+  resolveClaudeCatalogApiModelId,
+  resolveClaudeModelCatalog,
+  resolveClaudeModelsForVersion,
+  resolveClaudeModelSlug,
+} from "./ClaudeModelCatalog.ts";
+
+/**
+ * Test policy: adding or changing a real Claude model in model-manifest.json
+ * must not add or update tests here. These synthetic fixtures cover resolver
+ * behavior once. Add a test only when Claude adapter semantics change, such
+ * as introducing a new compatibility rule or dispatch mapping type.
+ */
+
+const manifest = (): ModelManifestData => ({
+  version: 1,
+  currentModels: {},
+  providers: {
+    claudeAgent: {
+      profiles: {
+        synthetic: {
+          capabilities: {
+            optionDescriptors: [
+              {
+                id: "effort",
+                label: "Reasoning",
+                type: "select",
+                options: [{ id: "extreme", label: "Extreme", isDefault: true }],
+              },
+              {
+                id: "contextWindow",
+                label: "Context Window",
+                type: "select",
+                options: [{ id: "large", label: "Large", isDefault: true }],
+              },
+            ],
+          },
+          adapter: {
+            claudeCode: {
+              effortMap: { extreme: "high" },
+              modelSuffixes: { contextWindow: { large: "[large]" } },
+            },
+          },
+        },
+      },
+      models: [
+        {
+          slug: "claude-synthetic-next",
+          name: "Claude Synthetic Next",
+          aliases: ["synthetic"],
+          status: "current",
+          profile: "synthetic",
+          adapter: { claudeCode: { minVersion: "3.2.0" } },
+        },
+      ],
+    },
+  },
+});
+
+describe("Claude model catalog", () => {
+  it("filters models at runtime-version boundaries and derives the upgrade message", () => {
+    const catalog = resolveClaudeModelCatalog(manifest());
+    assert.deepStrictEqual(resolveClaudeModelsForVersion(catalog, "3.1.9"), []);
+    assert.deepStrictEqual(
+      resolveClaudeModelsForVersion(catalog, "3.2.0").map((model) => model.slug),
+      ["claude-synthetic-next"],
+    );
+    assert.strictEqual(
+      formatClaudeVersionUpgradeMessage(catalog, "3.1.9"),
+      "Claude Code v3.1.9 is too old for Claude Synthetic Next. Upgrade to v3.2.0 or newer to access it.",
+    );
+  });
+
+  it("resolves aliases and declarative adapter mappings", () => {
+    const base = manifest();
+    const input: ModelManifestData = {
+      ...base,
+      providers: {
+        ...base.providers,
+        claudeAgent: {
+          ...base.providers!.claudeAgent!,
+          models: [
+            {
+              slug: "claude-synthetic-collision",
+              name: "Claude Synthetic Collision",
+              aliases: ["claude-synthetic-next"],
+              status: "current",
+            },
+            ...base.providers!.claudeAgent!.models,
+          ],
+        },
+      },
+    };
+    const catalog = resolveClaudeModelCatalog(input);
+    assert.strictEqual(resolveClaudeModelSlug(catalog, "synthetic"), "claude-synthetic-next");
+    assert.strictEqual(
+      resolveClaudeModelSlug(catalog, "claude-synthetic-next"),
+      "claude-synthetic-next",
+    );
+    assert.strictEqual(normalizeClaudeCatalogEffort(catalog, "extreme", "synthetic"), "high");
+    assert.strictEqual(
+      resolveClaudeCatalogApiModelId(catalog, {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "synthetic",
+      }),
+      "claude-synthetic-next[large]",
+    );
+  });
+
+  it("rejects malformed adapter mappings", () => {
+    const base = manifest();
+    const malformed: ModelManifestData = {
+      ...base,
+      providers: {
+        ...base.providers,
+        claudeAgent: {
+          ...base.providers!.claudeAgent!,
+          profiles: {
+            ...base.providers!.claudeAgent!.profiles,
+            synthetic: {
+              ...base.providers!.claudeAgent!.profiles.synthetic!,
+              adapter: { claudeCode: { effortMap: { extreme: 123 } } },
+            },
+          },
+        },
+      },
+    };
+    assert.isFalse(hasValidClaudeManifestAdapters(malformed));
+  });
+});

apps/server/src/provider/ClaudeModelCatalog.testFixtures.ts

@@ -0,0 +1,83 @@
+import type { ClaudeModelCatalog } from "./ClaudeModelCatalog.ts";
+
+// Transport tests must stay independent of bundled or remote manifest contents.
+// Keep every model, alias, capability, and runtime mapping in this fixture synthetic.
+export const SYNTHETIC_CLAUDE_CAPABLE_MODEL = "claude-synthetic-capable";
+export const SYNTHETIC_CLAUDE_COLLIDING_ALIAS = "synthetic-collision";
+export const SYNTHETIC_CLAUDE_STANDARD_MODEL = "claude-synthetic-standard";
+export const SYNTHETIC_CLAUDE_THINKING_MODEL = "claude-synthetic-thinking";
+
+const effort = {
+  id: "effort",
+  label: "Reasoning",
+  type: "select" as const,
+  options: [
+    { id: "low", label: "Low" },
+    { id: "high", label: "High", isDefault: true },
+    { id: "max", label: "Max" },
+    { id: "ultrathink", label: "Ultrathink" },
+  ],
+  promptInjectedValues: ["ultrathink"],
+};
+
+const contextWindow = {
+  id: "contextWindow",
+  label: "Context Window",
+  type: "select" as const,
+  options: [
+    { id: "standard", label: "Standard" },
+    { id: "expanded", label: "Expanded", isDefault: true },
+  ],
+};
+
+const runtime = {
+  effortMap: { ultrathink: null },
+  modelSuffixes: { contextWindow: { expanded: "[expanded]" } },
+  contextWindowTokens: { standard: 200_000, expanded: 1_000_000 },
+};
+
+export const SYNTHETIC_CLAUDE_MODEL_CATALOG: ClaudeModelCatalog = {
+  models: [
+    {
+      model: {
+        slug: SYNTHETIC_CLAUDE_CAPABLE_MODEL,
+        name: "Claude Synthetic Capable",
+        aliases: [SYNTHETIC_CLAUDE_COLLIDING_ALIAS],
+        isCustom: false,
+        capabilities: {
+          optionDescriptors: [
+            effort,
+            { id: "fastMode", label: "Fast Mode", type: "boolean" },
+            contextWindow,
+          ],
+        },
+      },
+      runtime,
+      compatibility: {},
+    },
+    {
+      model: {
+        slug: SYNTHETIC_CLAUDE_STANDARD_MODEL,
+        name: "Claude Synthetic Standard",
+        isCustom: false,
+        capabilities: {
+          optionDescriptors: [effort, contextWindow],
+        },
+      },
+      runtime,
+      compatibility: {},
+    },
+    {
+      model: {
+        slug: SYNTHETIC_CLAUDE_THINKING_MODEL,
+        name: "Claude Synthetic Thinking",
+        isCustom: false,
+        capabilities: {
+          optionDescriptors: [{ id: "thinking", label: "Thinking", type: "boolean" }],
+        },
+      },
+      runtime: {},
+      compatibility: {},
+    },
+  ],
+};