Commit 03542836834d008a097450cf24d0d9c6f965b859 | the-knife

apps/server/src/provider/ClaudeModelCatalog.test.ts created+137

...	@@ -0,0 +1,137 @@
1	import { assert, describe, it } from "@effect/vitest";
2	import { ProviderInstanceId } from "@t3tools/contracts";
3
4	import { hasValidClaudeManifestAdapters } from "./ClaudeModelManifest.ts";
5	import type { ModelManifestData } from "./ModelManifest.ts";
6	import {
7	formatClaudeVersionUpgradeMessage,
8	normalizeClaudeCatalogEffort,
9	resolveClaudeCatalogApiModelId,
10	resolveClaudeModelCatalog,
11	resolveClaudeModelsForVersion,
12	resolveClaudeModelSlug,
13	} from "./ClaudeModelCatalog.ts";
14
15	/**
16	* Test policy: adding or changing a real Claude model in model-manifest.json
17	* must not add or update tests here. These synthetic fixtures cover resolver
18	* behavior once. Add a test only when Claude adapter semantics change, such
19	* as introducing a new compatibility rule or dispatch mapping type.
20	*/
21
22	const manifest = (): ModelManifestData => ({
23	version: 1,
24	currentModels: {},
25	providers: {
26	claudeAgent: {
27	profiles: {
28	synthetic: {
29	capabilities: {
30	optionDescriptors: [
31	{
32	id: "effort",
33	label: "Reasoning",
34	type: "select",
35	options: [{ id: "extreme", label: "Extreme", isDefault: true }],
36	},
37	{
38	id: "contextWindow",
39	label: "Context Window",
40	type: "select",
41	options: [{ id: "large", label: "Large", isDefault: true }],
42	},
43	],
44	},
45	adapter: {
46	claudeCode: {
47	effortMap: { extreme: "high" },
48	modelSuffixes: { contextWindow: { large: "[large]" } },
49	},
50	},
51	},
52	},
53	models: [
54	{
55	slug: "claude-synthetic-next",
56	name: "Claude Synthetic Next",
57	aliases: ["synthetic"],
58	status: "current",
59	profile: "synthetic",
60	adapter: { claudeCode: { minVersion: "3.2.0" } },
61	},
62	],
63	},
64	},
65	});
66
67	describe("Claude model catalog", () => {
68	it("filters models at runtime-version boundaries and derives the upgrade message", () => {
69	const catalog = resolveClaudeModelCatalog(manifest());
70	assert.deepStrictEqual(resolveClaudeModelsForVersion(catalog, "3.1.9"), []);
71	assert.deepStrictEqual(
72	resolveClaudeModelsForVersion(catalog, "3.2.0").map((model) => model.slug),
73	["claude-synthetic-next"],
74	);
75	assert.strictEqual(
76	formatClaudeVersionUpgradeMessage(catalog, "3.1.9"),
77	"Claude Code v3.1.9 is too old for Claude Synthetic Next. Upgrade to v3.2.0 or newer to access it.",
78	);
79	});
80
81	it("resolves aliases and declarative adapter mappings", () => {
82	const base = manifest();
83	const input: ModelManifestData = {
84	...base,
85	providers: {
86	...base.providers,
87	claudeAgent: {
88	...base.providers!.claudeAgent!,
89	models: [
90	{
91	slug: "claude-synthetic-collision",
92	name: "Claude Synthetic Collision",
93	aliases: ["claude-synthetic-next"],
94	status: "current",
95	},
96	...base.providers!.claudeAgent!.models,
97	],
98	},
99	},
100	};
101	const catalog = resolveClaudeModelCatalog(input);
102	assert.strictEqual(resolveClaudeModelSlug(catalog, "synthetic"), "claude-synthetic-next");
103	assert.strictEqual(
104	resolveClaudeModelSlug(catalog, "claude-synthetic-next"),
105	"claude-synthetic-next",
106	);
107	assert.strictEqual(normalizeClaudeCatalogEffort(catalog, "extreme", "synthetic"), "high");
108	assert.strictEqual(
109	resolveClaudeCatalogApiModelId(catalog, {
110	instanceId: ProviderInstanceId.make("claudeAgent"),
111	model: "synthetic",
112	}),
113	"claude-synthetic-next[large]",
114	);
115	});
116
117	it("rejects malformed adapter mappings", () => {
118	const base = manifest();
119	const malformed: ModelManifestData = {
120	...base,
121	providers: {
122	...base.providers,
123	claudeAgent: {
124	...base.providers!.claudeAgent!,
125	profiles: {
126	...base.providers!.claudeAgent!.profiles,
127	synthetic: {
128	...base.providers!.claudeAgent!.profiles.synthetic!,
129	adapter: { claudeCode: { effortMap: { extreme: 123 } } },
130	},
131	},
132	},
133	},
134	};
135	assert.isFalse(hasValidClaudeManifestAdapters(malformed));
136	});
137	});

apps/server/src/provider/ClaudeModelCatalog.testFixtures.ts created+83

...	@@ -0,0 +1,83 @@
1	import type { ClaudeModelCatalog } from "./ClaudeModelCatalog.ts";
2
3	// Transport tests must stay independent of bundled or remote manifest contents.
4	// Keep every model, alias, capability, and runtime mapping in this fixture synthetic.
5	export const SYNTHETIC_CLAUDE_CAPABLE_MODEL = "claude-synthetic-capable";
6	export const SYNTHETIC_CLAUDE_COLLIDING_ALIAS = "synthetic-collision";
7	export const SYNTHETIC_CLAUDE_STANDARD_MODEL = "claude-synthetic-standard";
8	export const SYNTHETIC_CLAUDE_THINKING_MODEL = "claude-synthetic-thinking";
9
10	const effort = {
11	id: "effort",
12	label: "Reasoning",
13	type: "select" as const,
14	options: [
15	{ id: "low", label: "Low" },
16	{ id: "high", label: "High", isDefault: true },
17	{ id: "max", label: "Max" },
18	{ id: "ultrathink", label: "Ultrathink" },
19	],
20	promptInjectedValues: ["ultrathink"],
21	};
22
23	const contextWindow = {
24	id: "contextWindow",
25	label: "Context Window",
26	type: "select" as const,
27	options: [
28	{ id: "standard", label: "Standard" },
29	{ id: "expanded", label: "Expanded", isDefault: true },
30	],
31	};
32
33	const runtime = {
34	effortMap: { ultrathink: null },
35	modelSuffixes: { contextWindow: { expanded: "[expanded]" } },
36	contextWindowTokens: { standard: 200_000, expanded: 1_000_000 },
37	};
38
39	export const SYNTHETIC_CLAUDE_MODEL_CATALOG: ClaudeModelCatalog = {
40	models: [
41	{
42	model: {
43	slug: SYNTHETIC_CLAUDE_CAPABLE_MODEL,
44	name: "Claude Synthetic Capable",
45	aliases: [SYNTHETIC_CLAUDE_COLLIDING_ALIAS],
46	isCustom: false,
47	capabilities: {
48	optionDescriptors: [
49	effort,
50	{ id: "fastMode", label: "Fast Mode", type: "boolean" },
51	contextWindow,
52	],
53	},
54	},
55	runtime,
56	compatibility: {},
57	},
58	{
59	model: {
60	slug: SYNTHETIC_CLAUDE_STANDARD_MODEL,
61	name: "Claude Synthetic Standard",
62	isCustom: false,
63	capabilities: {
64	optionDescriptors: [effort, contextWindow],
65	},
66	},
67	runtime,
68	compatibility: {},
69	},
70	{
71	model: {
72	slug: SYNTHETIC_CLAUDE_THINKING_MODEL,
73	name: "Claude Synthetic Thinking",
74	isCustom: false,
75	capabilities: {
76	optionDescriptors: [{ id: "thinking", label: "Thinking", type: "boolean" }],
77	},
78	},
79	runtime: {},
80	compatibility: {},
81	},
82	],
83	};

apps/server/src/provider/ClaudeModelCatalog.ts created+242

...	@@ -0,0 +1,242 @@
1	import {
2	type ModelCapabilities,
3	type ModelSelection,
4	ProviderDriverKind,
5	type ServerProviderModel,
6	} from "@t3tools/contracts";
7	import * as Option from "effect/Option";
8	import {
9	getModelSelectionStringOptionValue,
10	getProviderOptionCurrentValue,
11	getProviderOptionDescriptors,
12	normalizeCustomModelSlug,
13	} from "@t3tools/shared/model";
14	import { compareSemverVersions } from "@t3tools/shared/semver";
15
16	import {
17	type ClaudeCodeCompatibility,
18	type ClaudeCodeProfile,
19	decodeClaudeModelAdapter,
20	decodeClaudeProfileAdapter,
21	} from "./ClaudeModelManifest.ts";
22	import {
23	BUNDLED_MODEL_MANIFEST,
24	type ModelManifestData,
25	resolveProviderCatalog,
26	} from "./ModelManifest.ts";
27
28	const CLAUDE = ProviderDriverKind.make("claudeAgent");
29	const EMPTY_CAPABILITIES: ModelCapabilities = { optionDescriptors: [] };
30
31	export interface ClaudeCatalogModel {
32	readonly model: ServerProviderModel;
33	readonly runtime: ClaudeCodeProfile;
34	readonly compatibility: ClaudeCodeCompatibility;
35	}
36
37	export interface ClaudeModelCatalog {
38	readonly models: ReadonlyArray<ClaudeCatalogModel>;
39	}
40
41	function tryResolveClaudeModelCatalog(manifest: ModelManifestData): ClaudeModelCatalog \| null {
42	const resolved = resolveProviderCatalog(manifest, CLAUDE);
43	if (!resolved) return null;
44
45	const models: Array<ClaudeCatalogModel> = [];
46	for (const entry of resolved.models) {
47	const profile = decodeClaudeProfileAdapter(entry.profileAdapter ?? {});
48	const adapter = decodeClaudeModelAdapter(entry.adapter ?? {});
49	if (Option.isNone(profile) \|\| Option.isNone(adapter)) return null;
50	models.push({
51	model: entry.model,
52	runtime: profile.value.claudeCode ?? {},
53	compatibility: adapter.value.claudeCode ?? {},
54	});
55	}
56
57	return {
58	models,
59	};
60	}
61
62	export function resolveClaudeModelCatalog(manifest: ModelManifestData): ClaudeModelCatalog {
63	return (
64	tryResolveClaudeModelCatalog(manifest) ??
65	tryResolveClaudeModelCatalog(BUNDLED_MODEL_MANIFEST) ?? {
66	models: [],
67	}
68	);
69	}
70
71	export const BUNDLED_CLAUDE_MODEL_CATALOG = resolveClaudeModelCatalog(BUNDLED_MODEL_MANIFEST);
72
73	/** Keeps custom model aliases opaque while preserving canonical built-in models and capabilities. */
74	export function scopeClaudeModelCatalog(
75	catalog: ClaudeModelCatalog,
76	customModels: ReadonlyArray<string>,
77	): ClaudeModelCatalog {
78	const customAliases = new Set(
79	customModels.flatMap((model) => {
80	const slug = normalizeCustomModelSlug(model);
81	return slug ? [slug.toLowerCase()] : [];
82	}),
83	);
84	if (customAliases.size === 0) return catalog;
85
86	return {
87	models: catalog.models.map((entry) => {
88	if (!entry.model.aliases?.some((alias) => customAliases.has(alias.toLowerCase()))) {
89	return entry;
90	}
91	return {
92	...entry,
93	model: {
94	...entry.model,
95	aliases: entry.model.aliases.filter((alias) => !customAliases.has(alias.toLowerCase())),
96	},
97	};
98	}),
99	};
100	}
101
102	export function resolveClaudeCatalogModel(
103	catalog: ClaudeModelCatalog,
104	slugOrAlias: string \| null \| undefined,
105	): ClaudeCatalogModel \| undefined {
106	const value = slugOrAlias?.trim();
107	if (!value) return undefined;
108	return (
109	catalog.models.find((entry) => entry.model.slug === value) ??
110	catalog.models.find((entry) =>
111	entry.model.aliases?.some((alias) => alias.toLowerCase() === value.toLowerCase()),
112	)
113	);
114	}
115
116	export function resolveClaudeModelSlug(catalog: ClaudeModelCatalog, slugOrAlias: string): string {
117	return resolveClaudeCatalogModel(catalog, slugOrAlias)?.model.slug ?? slugOrAlias;
118	}
119
120	export function getClaudeCatalogModelCapabilities(
121	catalog: ClaudeModelCatalog,
122	slugOrAlias: string \| null \| undefined,
123	): ModelCapabilities {
124	return resolveClaudeCatalogModel(catalog, slugOrAlias)?.model.capabilities ?? EMPTY_CAPABILITIES;
125	}
126
127	function isVersionSupported(
128	compatibility: ClaudeCodeCompatibility,
129	version: string \| null \| undefined,
130	): boolean {
131	if (!compatibility.minVersion && !compatibility.maxVersionExclusive) return true;
132	if (!version) return false;
133	if (compatibility.minVersion && compareSemverVersions(version, compatibility.minVersion) < 0) {
134	return false;
135	}
136	return !(
137	compatibility.maxVersionExclusive &&
138	compareSemverVersions(version, compatibility.maxVersionExclusive) >= 0
139	);
140	}
141
142	export function resolveClaudeModelsForVersion(
143	catalog: ClaudeModelCatalog,
144	version: string \| null \| undefined,
145	): ReadonlyArray<ClaudeCatalogModel["model"]> {
146	return catalog.models
147	.filter((entry) => isVersionSupported(entry.compatibility, version))
148	.map((entry) => entry.model);
149	}
150
151	export function formatClaudeVersionUpgradeMessage(
152	catalog: ClaudeModelCatalog,
153	version: string \| null,
154	): string \| undefined {
155	const unavailable = catalog.models
156	.filter(
157	(entry) =>
158	entry.compatibility.minVersion &&
159	(!version \|\| compareSemverVersions(version, entry.compatibility.minVersion) < 0),
160	)
161	.toSorted((left, right) =>
162	compareSemverVersions(left.compatibility.minVersion!, right.compatibility.minVersion!),
163	)[0];
164	if (!unavailable?.compatibility.minVersion) return undefined;
165	const versionLabel = version ? `v${version}` : "the installed version";
166	return `Claude Code ${versionLabel} is too old for ${unavailable.model.name}. Upgrade to v${unavailable.compatibility.minVersion} or newer to access it.`;
167	}
168
169	export function resolveClaudeCatalogEffort(
170	catalog: ClaudeModelCatalog,
171	model: string \| null \| undefined,
172	raw: string \| null \| undefined,
173	): string \| undefined {
174	const caps = getClaudeCatalogModelCapabilities(catalog, model);
175	const descriptors = getProviderOptionDescriptors({
176	caps,
177	...(raw ? { selections: [{ id: "effort", value: raw }] } : {}),
178	});
179	const descriptor = descriptors.find((candidate) => candidate.id === "effort");
180	const value = getProviderOptionCurrentValue(descriptor);
181	return typeof value === "string" ? value : undefined;
182	}
183
184	export function normalizeClaudeCatalogEffort(
185	catalog: ClaudeModelCatalog,
186	effort: string \| null \| undefined,
187	model: string \| null \| undefined,
188	): string \| undefined {
189	if (!effort) return undefined;
190	const effortMap = resolveClaudeCatalogModel(catalog, model)?.runtime.effortMap;
191	if (!effortMap \|\| !Object.prototype.hasOwnProperty.call(effortMap, effort)) return effort;
192	return effortMap[effort] ?? undefined;
193	}
194
195	export function isClaudeCatalogUltracodeEffort(effort: string \| null \| undefined): boolean {
196	return effort === "ultracode";
197	}
198
199	export function resolveClaudeCatalogContextWindow(
200	catalog: ClaudeModelCatalog,
201	modelSelection: ModelSelection \| undefined,
202	): string \| undefined {
203	const caps = getClaudeCatalogModelCapabilities(catalog, modelSelection?.model);
204	const raw = getModelSelectionStringOptionValue(modelSelection, "contextWindow");
205	const descriptors = getProviderOptionDescriptors({
206	caps,
207	...(raw ? { selections: [{ id: "contextWindow", value: raw }] } : {}),
208	});
209	const descriptor = descriptors.find((candidate) => candidate.id === "contextWindow");
210	const value = getProviderOptionCurrentValue(descriptor);
211	return typeof value === "string" ? value : undefined;
212	}
213
214	export function resolveClaudeCatalogApiModelId(
215	catalog: ClaudeModelCatalog,
216	modelSelection: ModelSelection,
217	): string {
218	const entry = resolveClaudeCatalogModel(catalog, modelSelection.model);
219	const slug = entry?.model.slug ?? modelSelection.model;
220	const descriptors = getProviderOptionDescriptors({
221	caps: entry?.model.capabilities ?? EMPTY_CAPABILITIES,
222	selections: modelSelection.options,
223	});
224	for (const [optionId, suffixes] of Object.entries(entry?.runtime.modelSuffixes ?? {})) {
225	const value = getProviderOptionCurrentValue(
226	descriptors.find((descriptor) => descriptor.id === optionId),
227	);
228	if (typeof value === "string" && suffixes[value]) return `${slug}${suffixes[value]}`;
229	}
230	return slug;
231	}
232
233	export function resolveClaudeCatalogContextWindowTokens(
234	catalog: ClaudeModelCatalog,
235	modelSelection: ModelSelection \| undefined,
236	): number \| undefined {
237	const entry = resolveClaudeCatalogModel(catalog, modelSelection?.model);
238	if (!entry) return undefined;
239	if (entry.runtime.fixedContextWindowTokens) return entry.runtime.fixedContextWindowTokens;
240	const contextWindow = resolveClaudeCatalogContextWindow(catalog, modelSelection);
241	return contextWindow ? entry.runtime.contextWindowTokens?.[contextWindow] : undefined;
242	}

apps/server/src/provider/ClaudeModelManifest.ts created+82

...	@@ -0,0 +1,82 @@
1	import { TrimmedNonEmptyString } from "@t3tools/contracts";
2	import { compareSemverVersions, parseSemver } from "@t3tools/shared/semver";
3	import * as Option from "effect/Option";
4	import * as Schema from "effect/Schema";
5
6	export const ClaudeCodeProfileSchema = Schema.Struct({
7	effortMap: Schema.optional(
8	Schema.Record(TrimmedNonEmptyString, Schema.NullOr(TrimmedNonEmptyString)),
9	),
10	modelSuffixes: Schema.optional(
11	Schema.Record(
12	TrimmedNonEmptyString,
13	Schema.Record(TrimmedNonEmptyString, TrimmedNonEmptyString),
14	),
15	),
16	contextWindowTokens: Schema.optional(Schema.Record(TrimmedNonEmptyString, Schema.Number)),
17	fixedContextWindowTokens: Schema.optional(Schema.Number),
18	});
19
20	export const ClaudeProfileAdapterSchema = Schema.Struct({
21	claudeCode: Schema.optional(ClaudeCodeProfileSchema),
22	});
23
24	const ClaudeVersionSchema = TrimmedNonEmptyString.pipe(
25	Schema.check(
26	Schema.makeFilter((version) => parseSemver(version) !== null, {
27	expected: "a supported semantic version",
28	}),
29	),
30	);
31
32	const ClaudeCodeCompatibilitySchema = Schema.Struct({
33	minVersion: Schema.optional(ClaudeVersionSchema),
34	maxVersionExclusive: Schema.optional(ClaudeVersionSchema),
35	}).pipe(
36	Schema.check(
37	Schema.makeFilter(
38	({ minVersion, maxVersionExclusive }) =>
39	minVersion === undefined \|\|
40	maxVersionExclusive === undefined \|\|
41	compareSemverVersions(minVersion, maxVersionExclusive) < 0,
42	{ expected: "a minimum version below the exclusive maximum version" },
43	),
44	),
45	);
46
47	export const ClaudeModelAdapterSchema = Schema.Struct({
48	claudeCode: Schema.optional(ClaudeCodeCompatibilitySchema),
49	});
50
51	export type ClaudeCodeProfile = typeof ClaudeCodeProfileSchema.Type;
52	export type ClaudeCodeCompatibility = NonNullable<typeof ClaudeModelAdapterSchema.Type.claudeCode>;
53
54	export const decodeClaudeProfileAdapter = Schema.decodeUnknownOption(ClaudeProfileAdapterSchema);
55	export const decodeClaudeModelAdapter = Schema.decodeUnknownOption(ClaudeModelAdapterSchema);
56
57	interface ClaudeManifestAdapterInput {
58	readonly providers?:
59	\| Readonly<
60	Record<
61	string,
62	\| {
63	readonly profiles: Readonly<Record<string, { readonly adapter?: unknown }>>;
64	readonly models: ReadonlyArray<{ readonly adapter?: unknown }>;
65	}
66	\| undefined
67	>
68	>
69	\| undefined;
70	}
71
72	export function hasValidClaudeManifestAdapters(manifest: ClaudeManifestAdapterInput): boolean {
73	const catalog = manifest.providers?.claudeAgent;
74	if (!catalog) return true;
75
76	return (
77	Object.values(catalog.profiles).every((profile) =>
78	Option.isSome(decodeClaudeProfileAdapter(profile.adapter ?? {})),
79	) &&
80	catalog.models.every((model) => Option.isSome(decodeClaudeModelAdapter(model.adapter ?? {})))
81	);
82	}

apps/server/src/provider/Drivers/ClaudeDriver.ts+25-19

 @@ -35,6 +35,7 @@ import {
   probeClaudeCapabilities,
 } from "../Layers/ClaudeProvider.ts";
 import { ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
+import { resolveClaudeModelCatalog } from "../ClaudeModelCatalog.ts";
 import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
 import * as ModelManifest from "../ModelManifest.ts";
 import {
 @@ -128,6 +129,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
       const serverSettings = yield* ServerSettingsService;
       const eventLoggers = yield* ProviderEventLoggers;
       const modelManifest = yield* ModelManifest.ModelManifest;
+      const modelCatalog = modelManifest.current.pipe(Effect.map(resolveClaudeModelCatalog));
       const processEnv = mergeProviderInstanceEnvironment(environment);
       const fallbackContinuationIdentity = defaultProviderContinuationIdentity({
         driverKind: DRIVER_KIND,
 @@ -149,10 +151,15 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
       const adapterOptions = {
         instanceId,
         environment: processEnv,
+        modelCatalog,
         ...(eventLoggers.native ? { nativeEventLogger: eventLoggers.native } : {}),
       };
       const adapter = yield* makeClaudeAdapter(effectiveConfig, adapterOptions);
-      const textGeneration = yield* makeClaudeTextGeneration(effectiveConfig, processEnv);
+      const textGeneration = yield* makeClaudeTextGeneration(
+        effectiveConfig,
+        processEnv,
+        modelCatalog,
+      );
       // Per-instance capabilities cache: keyed on binary + resolved HOME so
       // account-specific probes never share auth metadata across instances.
 @@ -166,22 +173,21 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
       });
       const capabilitiesCacheKey = yield* makeClaudeCapabilitiesCacheKey(effectiveConfig, cwd);
-      // Kick the TTL-gated manifest refresh in the background and classify
+      // Start the TTL-gated refresh without delaying provider readiness. The
-      // with the in-memory manifest, so a slow or hung fetch never delays the
+      // next check observes a remote manifest after the background fetch lands.
-      // provider check. A refresh that lands mid-probe applies on the next one.
       const checkProvider = modelManifest.refreshInBackground.pipe(
         Effect.andThen(
-          Effect.zipWith(
+          modelManifest.current.pipe(
-            checkClaudeProviderStatus(
+            Effect.flatMap((manifest) =>
-              effectiveConfig,
+              checkClaudeProviderStatus(
-              () => Cache.get(capabilitiesProbeCache, capabilitiesCacheKey),
+                effectiveConfig,
-              processEnv,
+                () => Cache.get(capabilitiesProbeCache, capabilitiesCacheKey),
-              cwd,
+                processEnv,
+                cwd,
+                resolveClaudeModelCatalog(manifest),
+              ),
             ),
-            modelManifest.current,
+            Effect.map(stampIdentity),
-            (draft, manifest) =>
-              stampIdentity(ModelManifest.applyModelManifest(draft, manifest, DRIVER_KIND)),
-            { concurrent: true },
           ),
         ),
         Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
 @@ -196,11 +202,11 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
         streamSettings: snapshotSettings.streamSettings,
         haveSettingsChanged: haveProviderSnapshotSettingsChanged,
         initialSnapshot: (settings) =>
-          Effect.zipWith(
+          modelManifest.current.pipe(
-            makePendingClaudeProvider(settings.provider),
+            Effect.flatMap((manifest) =>
-            modelManifest.current,
+              makePendingClaudeProvider(settings.provider, resolveClaudeModelCatalog(manifest)),
-            (draft, manifest) =>
+            ),
-              stampIdentity(ModelManifest.applyModelManifest(draft, manifest, DRIVER_KIND)),
+            Effect.map(stampIdentity),
           ),
         checkProvider,
         enrichSnapshot: ({ settings, snapshot, publishSnapshot }) =>

apps/server/src/provider/Layers/ClaudeAdapter.test.ts+141-196

 @@ -35,6 +35,13 @@ import * as TestClock from "effect/testing/TestClock";
 import { attachmentRelativePath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
+import {
+  SYNTHETIC_CLAUDE_CAPABLE_MODEL,
+  SYNTHETIC_CLAUDE_COLLIDING_ALIAS,
+  SYNTHETIC_CLAUDE_MODEL_CATALOG,
+  SYNTHETIC_CLAUDE_STANDARD_MODEL,
+  SYNTHETIC_CLAUDE_THINKING_MODEL,
+} from "../ClaudeModelCatalog.testFixtures.ts";
 import { ProviderAdapterProcessError, ProviderAdapterValidationError } from "../Errors.ts";
 import type { ClaudeAdapterShape } from "../Services/ClaudeAdapter.ts";
 import { makeClaudeAdapter, type ClaudeAdapterLiveOptions } from "./ClaudeAdapter.ts";
 @@ -166,6 +173,7 @@ function makeHarness(config?: {
   const adapterOptions: ClaudeAdapterLiveOptions = {
     ...(config?.instanceId ? { instanceId: config.instanceId } : {}),
+    modelCatalog: Effect.succeed(SYNTHETIC_CLAUDE_MODEL_CATALOG),
     createQuery: (input) => {
       createInput = input;
       return query;
 @@ -265,6 +273,7 @@ async function readFirstPromptMessage(
 const THREAD_ID = ThreadId.make("thread-claude-1");
 const RESUME_THREAD_ID = ThreadId.make("thread-claude-resume");
+const SYNTHETIC_SUBAGENT_MODEL = "claude-synthetic-subagent[expanded]";
 describe("ClaudeAdapterLive", () => {
   it.effect("returns validation error for non-claude provider on startSession", () => {
 @@ -441,7 +450,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-opus-4-6",
+          SYNTHETIC_CLAUDE_CAPABLE_MODEL,
           [{ id: "effort", value: "max" }],
         ),
         runtimeMode: "full-access",
 @@ -464,7 +473,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-opus-4-6",
+          SYNTHETIC_CLAUDE_CAPABLE_MODEL,
         ),
         runtimeMode: "full-access",
       });
 @@ -480,167 +489,7 @@ describe("ClaudeAdapterLive", () => {
     );
   });
-  it.effect("maps the Claude Opus 4.7 default effort to the SDK-supported max value", () => {
+  it.effect("forwards Claude thinking toggle for models that support it", () => {
-    const harness = makeHarness();
-    return Effect.gen(function* () {
-      const adapter = yield* ClaudeAdapter;
-      yield* adapter.startSession({
-        threadId: THREAD_ID,
-        provider: ProviderDriverKind.make("claudeAgent"),
-        modelSelection: {
-          instanceId: ProviderInstanceId.make("claudeAgent"),
-          model: "claude-opus-4-7",
-        },
-        runtimeMode: "full-access",
-      });
-      const createInput = harness.getLastCreateQueryInput();
-      assert.equal(createInput?.options.effort, "max");
-    }).pipe(
-      Effect.provideService(Random.Random, makeDeterministicRandomService()),
-      Effect.provide(harness.layer),
-    );
-  });
-  it.effect("maps xhigh effort for Claude Opus 4.7 to the SDK-supported max value", () => {
-    const harness = makeHarness();
-    return Effect.gen(function* () {
-      const adapter = yield* ClaudeAdapter;
-      yield* adapter.startSession({
-        threadId: THREAD_ID,
-        provider: ProviderDriverKind.make("claudeAgent"),
-        modelSelection: createModelSelection(
-          ProviderInstanceId.make("claudeAgent"),
-          "claude-opus-4-7",
-          [{ id: "effort", value: "xhigh" }],
-        ),
-        runtimeMode: "full-access",
-      });
-      const createInput = harness.getLastCreateQueryInput();
-      assert.equal(createInput?.options.effort, "max");
-    }).pipe(
-      Effect.provideService(Random.Random, makeDeterministicRandomService()),
-      Effect.provide(harness.layer),
-    );
-  });
-  it.effect("preserves xhigh effort for Claude Fable 5.1", () => {
-    const harness = makeHarness();
-    return Effect.gen(function* () {
-      const adapter = yield* ClaudeAdapter;
-      yield* adapter.startSession({
-        threadId: THREAD_ID,
-        provider: ProviderDriverKind.make("claudeAgent"),
-        modelSelection: createModelSelection(
-          ProviderInstanceId.make("claudeAgent"),
-          "claude-fable-5-1",
-          [{ id: "effort", value: "xhigh" }],
-        ),
-        runtimeMode: "full-access",
-      });
-      const createInput = harness.getLastCreateQueryInput();
-      assert.equal(createInput?.options.effort, "xhigh");
-    }).pipe(
-      Effect.provideService(Random.Random, makeDeterministicRandomService()),
-      Effect.provide(harness.layer),
-    );
-  });
-  it.effect("preserves xhigh effort for Claude Fable 5", () => {
-    const harness = makeHarness();
-    return Effect.gen(function* () {
-      const adapter = yield* ClaudeAdapter;
-      yield* adapter.startSession({
-        threadId: THREAD_ID,
-        provider: ProviderDriverKind.make("claudeAgent"),
-        modelSelection: createModelSelection(
-          ProviderInstanceId.make("claudeAgent"),
-          "claude-fable-5",
-          [{ id: "effort", value: "xhigh" }],
-        ),
-        runtimeMode: "full-access",
-      });
-      const createInput = harness.getLastCreateQueryInput();
-      assert.equal(createInput?.options.effort, "xhigh");
-    }).pipe(
-      Effect.provideService(Random.Random, makeDeterministicRandomService()),
-      Effect.provide(harness.layer),
-    );
-  });
-  it.effect("preserves xhigh effort for Claude Opus 5", () => {
-    const harness = makeHarness();
-    return Effect.gen(function* () {
-      const adapter = yield* ClaudeAdapter;
-      yield* adapter.startSession({
-        threadId: THREAD_ID,
-        provider: ProviderDriverKind.make("claudeAgent"),
-        modelSelection: createModelSelection(
-          ProviderInstanceId.make("claudeAgent"),
-          "claude-opus-5",
-          [{ id: "effort", value: "xhigh" }],
-        ),
-        runtimeMode: "full-access",
-      });
-      const createInput = harness.getLastCreateQueryInput();
-      assert.equal(createInput?.options.effort, "xhigh");
-    }).pipe(
-      Effect.provideService(Random.Random, makeDeterministicRandomService()),
-      Effect.provide(harness.layer),
-    );
-  });
-  it.effect("falls back to default effort when unsupported max is requested for Sonnet 4.6", () => {
-    const harness = makeHarness();
-    return Effect.gen(function* () {
-      const adapter = yield* ClaudeAdapter;
-      yield* adapter.startSession({
-        threadId: THREAD_ID,
-        provider: ProviderDriverKind.make("claudeAgent"),
-        modelSelection: createModelSelection(
-          ProviderInstanceId.make("claudeAgent"),
-          "claude-sonnet-4-6",
-          [{ id: "effort", value: "max" }],
-        ),
-        runtimeMode: "full-access",
-      });
-      const createInput = harness.getLastCreateQueryInput();
-      assert.equal(createInput?.options.effort, "high");
-    }).pipe(
-      Effect.provideService(Random.Random, makeDeterministicRandomService()),
-      Effect.provide(harness.layer),
-    );
-  });
-  it.effect("ignores adaptive effort for Haiku 4.5", () => {
-    const harness = makeHarness();
-    return Effect.gen(function* () {
-      const adapter = yield* ClaudeAdapter;
-      yield* adapter.startSession({
-        threadId: THREAD_ID,
-        provider: ProviderDriverKind.make("claudeAgent"),
-        modelSelection: createModelSelection(
-          ProviderInstanceId.make("claudeAgent"),
-          "claude-haiku-4-5",
-          [{ id: "effort", value: "high" }],
-        ),
-        runtimeMode: "full-access",
-      });
-      const createInput = harness.getLastCreateQueryInput();
-      assert.equal(createInput?.options.effort, undefined);
-    }).pipe(
-      Effect.provideService(Random.Random, makeDeterministicRandomService()),
-      Effect.provide(harness.layer),
-    );
-  });
-  it.effect("forwards Claude thinking toggle into SDK settings for Haiku 4.5", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
 @@ -649,7 +498,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-haiku-4-5",
+          SYNTHETIC_CLAUDE_THINKING_MODEL,
           [{ id: "thinking", value: false }],
         ),
         runtimeMode: "full-access",
 @@ -665,7 +514,7 @@ describe("ClaudeAdapterLive", () => {
     );
   });
-  it.effect("ignores Claude thinking toggle for non-Haiku models", () => {
+  it.effect("ignores Claude thinking toggle for models without it", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
 @@ -674,7 +523,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-sonnet-4-6",
+          SYNTHETIC_CLAUDE_STANDARD_MODEL,
           [{ id: "thinking", value: false }],
         ),
         runtimeMode: "full-access",
 @@ -697,7 +546,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-opus-4-6",
+          SYNTHETIC_CLAUDE_CAPABLE_MODEL,
           [{ id: "fastMode", value: true }],
         ),
         runtimeMode: "full-access",
 @@ -713,7 +562,7 @@ describe("ClaudeAdapterLive", () => {
     );
   });
-  it.effect("ignores claude fast mode for non-opus models", () => {
+  it.effect("ignores claude fast mode for models without it", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
 @@ -722,7 +571,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-sonnet-4-6",
+          SYNTHETIC_CLAUDE_STANDARD_MODEL,
           [{ id: "fastMode", value: true }],
         ),
         runtimeMode: "full-access",
 @@ -736,6 +585,97 @@ describe("ClaudeAdapterLive", () => {
     );
   });
+  it.effect(
+    "keeps a configured custom alias opaque without disabling the canonical built-in",
+    () => {
+      const claudeConfig = { customModels: [SYNTHETIC_CLAUDE_COLLIDING_ALIAS] };
+      const customHarness = makeHarness({ claudeConfig });
+      const builtInHarness = makeHarness({ claudeConfig });
+      const start = (harness: ReturnType<typeof makeHarness>, model: string) =>
+        Effect.gen(function* () {
+          const adapter = yield* ClaudeAdapter;
+          yield* adapter.startSession({
+            threadId: THREAD_ID,
+            provider: ProviderDriverKind.make("claudeAgent"),
+            modelSelection: createModelSelection(ProviderInstanceId.make("claudeAgent"), model, [
+              { id: "effort", value: "max" },
+              { id: "fastMode", value: true },
+              { id: "contextWindow", value: "expanded" },
+            ]),
+            runtimeMode: "full-access",
+          });
+          return harness.getLastCreateQueryInput()!.options;
+        }).pipe(
+          Effect.provideService(Random.Random, makeDeterministicRandomService()),
+          Effect.provide(harness.layer),
+        );
+      const runCustomFlow = Effect.gen(function* () {
+        const adapter = yield* ClaudeAdapter;
+        yield* adapter.startSession({
+          threadId: THREAD_ID,
+          provider: ProviderDriverKind.make("claudeAgent"),
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("claudeAgent"),
+            SYNTHETIC_CLAUDE_COLLIDING_ALIAS,
+            [
+              { id: "effort", value: "max" },
+              { id: "fastMode", value: true },
+              { id: "contextWindow", value: "expanded" },
+            ],
+          ),
+          runtimeMode: "full-access",
+        });
+        const options = customHarness.getLastCreateQueryInput()!.options;
+        yield* adapter.sendTurn({
+          threadId: THREAD_ID,
+          input: "use the built-in model",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("claudeAgent"),
+            SYNTHETIC_CLAUDE_CAPABLE_MODEL,
+            [{ id: "contextWindow", value: "expanded" }],
+          ),
+          attachments: [],
+        });
+        yield* Effect.promise(() => readFirstPromptText(customHarness.getLastCreateQueryInput()));
+        yield* adapter.sendTurn({
+          threadId: THREAD_ID,
+          input: "keep this prompt literal",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("claudeAgent"),
+            SYNTHETIC_CLAUDE_COLLIDING_ALIAS,
+            [{ id: "effort", value: "ultrathink" }],
+          ),
+          attachments: [],
+        });
+        const prompt = yield* Effect.promise(() =>
+          readFirstPromptText(customHarness.getLastCreateQueryInput()),
+        );
+        return { options, prompt };
+      }).pipe(
+        Effect.provideService(Random.Random, makeDeterministicRandomService()),
+        Effect.provide(customHarness.layer),
+      );
+      return Effect.gen(function* () {
+        const { options: customOptions, prompt: customPrompt } = yield* runCustomFlow;
+        assert.equal(customOptions.model, SYNTHETIC_CLAUDE_COLLIDING_ALIAS);
+        assert.equal(customOptions.effort, undefined);
+        assert.equal(customOptions.settings, undefined);
+        assert.deepEqual(customHarness.query.setModelCalls, [
+          `${SYNTHETIC_CLAUDE_CAPABLE_MODEL}[expanded]`,
+          SYNTHETIC_CLAUDE_COLLIDING_ALIAS,
+        ]);
+        assert.equal(customPrompt, "keep this prompt literal");
+        const builtInOptions = yield* start(builtInHarness, SYNTHETIC_CLAUDE_CAPABLE_MODEL);
+        assert.equal(builtInOptions.model, `${SYNTHETIC_CLAUDE_CAPABLE_MODEL}[expanded]`);
+        assert.equal(builtInOptions.effort, "max");
+        assert.deepEqual(builtInOptions.settings, { fastMode: true });
+      });
+    },
+  );
   it.effect("treats ultrathink as a prompt keyword instead of a session effort", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
 @@ -745,7 +685,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-sonnet-4-6",
+          SYNTHETIC_CLAUDE_STANDARD_MODEL,
           [{ id: "effort", value: "ultrathink" }],
         ),
         runtimeMode: "full-access",
 @@ -757,7 +697,7 @@ describe("ClaudeAdapterLive", () => {
         attachments: [],
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-sonnet-4-6",
+          SYNTHETIC_CLAUDE_STANDARD_MODEL,
           [{ id: "effort", value: "ultrathink" }],
         ),
       });
 @@ -778,7 +718,7 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       const modelSelection = createModelSelection(
         ProviderInstanceId.make("claudeAgent"),
-        "claude-sonnet-4-6",
+        SYNTHETIC_CLAUDE_STANDARD_MODEL,
         [{ id: "effort", value: "ultrathink" }],
       );
       const session = yield* adapter.startSession({
 @@ -885,7 +825,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: {
           instanceId: ProviderInstanceId.make("claudeAgent"),
-          model: "claude-sonnet-4-5",
+          model: SYNTHETIC_CLAUDE_STANDARD_MODEL,
         },
         runtimeMode: "full-access",
       });
 @@ -1900,7 +1840,7 @@ describe("ClaudeAdapterLive", () => {
           output_tokens: 50,
         },
         modelUsage: {
-          "claude-opus-4-6": {
+          [SYNTHETIC_CLAUDE_CAPABLE_MODEL]: {
             contextWindow: 200000,
             maxOutputTokens: 64000,
           },
 @@ -1990,7 +1930,7 @@ describe("ClaudeAdapterLive", () => {
           output_tokens: 50,
         },
         modelUsage: {
-          "claude-opus-4-6": {
+          [SYNTHETIC_CLAUDE_CAPABLE_MODEL]: {
             contextWindow: 200000,
             maxOutputTokens: 64000,
           },
 @@ -2125,7 +2065,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-opus-4-6",
+          SYNTHETIC_CLAUDE_CAPABLE_MODEL,
           [{ id: "effort", value: "max" }],
         ),
         runtimeMode: "full-access",
 @@ -2154,7 +2094,7 @@ describe("ClaudeAdapterLive", () => {
         type: "assistant",
         parent_tool_use_id: "toolu_agent_m",
         message: {
-          model: "claude-sonnet-5[1m]",
+          model: SYNTHETIC_SUBAGENT_MODEL,
           content: [],
         },
         uuid: "subagent-snapshot-uuid",
 @@ -2174,13 +2114,13 @@ describe("ClaudeAdapterLive", () => {
       const started = taskEvents[0];
       assert.equal(started?.type, "task.started");
       if (started?.type === "task.started") {
-        assert.equal(started.payload.model, "claude-opus-4-6");
+        assert.equal(started.payload.model, SYNTHETIC_CLAUDE_CAPABLE_MODEL);
         assert.equal(started.payload.effort, "max");
       }
       const progress = taskEvents[1];
       assert.equal(progress?.type, "task.progress");
       if (progress?.type === "task.progress") {
-        assert.equal(progress.payload.model, "claude-sonnet-5[1m]");
+        assert.equal(progress.payload.model, SYNTHETIC_SUBAGENT_MODEL);
         assert.equal(progress.payload.effort, "max");
       }
     }).pipe(
 @@ -2206,7 +2146,7 @@ describe("ClaudeAdapterLive", () => {
         provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-opus-4-6",
+          SYNTHETIC_CLAUDE_CAPABLE_MODEL,
           [{ id: "effort", value: "max" }],
         ),
         runtimeMode: "full-access",
 @@ -2223,7 +2163,7 @@ describe("ClaudeAdapterLive", () => {
         type: "assistant",
         parent_tool_use_id: "toolu_agent_early",
         message: {
-          model: "claude-sonnet-5[1m]",
+          model: SYNTHETIC_SUBAGENT_MODEL,
           content: [],
         },
         uuid: "early-snapshot-uuid",
 @@ -2253,13 +2193,13 @@ describe("ClaudeAdapterLive", () => {
       const started = taskEvents[0];
       assert.equal(started?.type, "task.started");
       if (started?.type === "task.started") {
-        assert.equal(started.payload.model, "claude-sonnet-5[1m]");
+        assert.equal(started.payload.model, SYNTHETIC_SUBAGENT_MODEL);
         assert.equal(started.payload.effort, "max");
       }
       const progress = taskEvents[1];
       assert.equal(progress?.type, "task.progress");
       if (progress?.type === "task.progress") {
-        assert.equal(progress.payload.model, "claude-sonnet-5[1m]");
+        assert.equal(progress.payload.model, SYNTHETIC_SUBAGENT_MODEL);
       }
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
 @@ -2884,7 +2824,7 @@ describe("ClaudeAdapterLive", () => {
           output_tokens: 679,
         },
         modelUsage: {
-          "claude-opus-4-6": {
+          [SYNTHETIC_CLAUDE_CAPABLE_MODEL]: {
             contextWindow: 200000,
             maxOutputTokens: 64000,
           },
 @@ -2948,7 +2888,7 @@ describe("ClaudeAdapterLive", () => {
           total_tokens: 535000,
         },
         modelUsage: {
-          "claude-opus-4-6": {
+          [SYNTHETIC_CLAUDE_CAPABLE_MODEL]: {
             contextWindow: 200000,
             maxOutputTokens: 64000,
           },
 @@ -3025,7 +2965,7 @@ describe("ClaudeAdapterLive", () => {
             total_tokens: 535000,
           },
           modelUsage: {
-            "claude-opus-4-6": {
+            [SYNTHETIC_CLAUDE_CAPABLE_MODEL]: {
               contextWindow: 200000,
               maxOutputTokens: 64000,
             },
 @@ -4069,7 +4009,7 @@ describe("ClaudeAdapterLive", () => {
         cwd: "/tmp/claude-adapter-test",
         tools: [],
         mcp_servers: [],
-        model: "claude-sonnet-4-5",
+        model: SYNTHETIC_CLAUDE_STANDARD_MODEL,
         permissionMode: "bypassPermissions",
         slash_commands: [],
         output_style: "default",
 @@ -4232,12 +4172,14 @@ describe("ClaudeAdapterLive", () => {
         input: "hello",
         modelSelection: {
           instanceId: ProviderInstanceId.make("claudeAgent"),
-          model: "claude-opus-4-6",
+          model: SYNTHETIC_CLAUDE_CAPABLE_MODEL,
         },
         attachments: [],
       });
-      assert.deepEqual(harness.query.setModelCalls, ["claude-opus-4-6[1m]"]);
+      assert.deepEqual(harness.query.setModelCalls, [
+        `${SYNTHETIC_CLAUDE_CAPABLE_MODEL}[expanded]`,
+      ]);
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
       Effect.provide(harness.layer),
 @@ -4280,7 +4222,7 @@ describe("ClaudeAdapterLive", () => {
         const adapter = yield* ClaudeAdapter;
         const modelSelection = {
           instanceId: ProviderInstanceId.make("claudeAgent"),
-          model: "claude-opus-4-6",
+          model: SYNTHETIC_CLAUDE_CAPABLE_MODEL,
         };
         const session = yield* adapter.startSession({
 @@ -4327,8 +4269,8 @@ describe("ClaudeAdapterLive", () => {
         input: "hello",
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-opus-4-6",
+          SYNTHETIC_CLAUDE_CAPABLE_MODEL,
-          [{ id: "contextWindow", value: "1m" }],
+          [{ id: "contextWindow", value: "expanded" }],
         ),
         attachments: [],
       });
 @@ -4337,13 +4279,16 @@ describe("ClaudeAdapterLive", () => {
         input: "hello again",
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
-          "claude-opus-4-6",
+          SYNTHETIC_CLAUDE_CAPABLE_MODEL,
-          [{ id: "contextWindow", value: "200k" }],
+          [{ id: "contextWindow", value: "standard" }],
         ),
         attachments: [],
       });
-      assert.deepEqual(harness.query.setModelCalls, ["claude-opus-4-6[1m]", "claude-opus-4-6"]);
+      assert.deepEqual(harness.query.setModelCalls, [
+        `${SYNTHETIC_CLAUDE_CAPABLE_MODEL}[expanded]`,
+        SYNTHETIC_CLAUDE_CAPABLE_MODEL,
+      ]);
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
       Effect.provide(harness.layer),
 @@ -4553,7 +4498,7 @@ describe("ClaudeAdapterLive", () => {
         uuid: "assistant-exit-plan",
         parent_tool_use_id: null,
         message: {
-          model: "claude-opus-4-6",
+          model: SYNTHETIC_CLAUDE_CAPABLE_MODEL,
           id: "msg-exit-plan",
           type: "message",
           role: "assistant",

apps/server/src/provider/Layers/ClaudeAdapter.ts+56-38

 @@ -80,13 +80,17 @@ import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
 import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 import {
-  getClaudeModelCapabilities,
+  BUNDLED_CLAUDE_MODEL_CATALOG,
-  isClaudeUltracodeEffort,
+  type ClaudeModelCatalog,
-  normalizeClaudeCliEffort,
+  getClaudeCatalogModelCapabilities,
-  resolveClaudeApiModelId,
+  isClaudeCatalogUltracodeEffort,
-  resolveClaudeContextWindow,
+  normalizeClaudeCatalogEffort,
-  resolveClaudeEffort,
+  resolveClaudeCatalogApiModelId,
-} from "./ClaudeProvider.ts";
+  resolveClaudeCatalogContextWindowTokens,
+  resolveClaudeCatalogEffort,
+  resolveClaudeModelSlug,
+  scopeClaudeModelCatalog,
+} from "../ClaudeModelCatalog.ts";
 import {
   ProviderAdapterProcessError,
   ProviderAdapterRequestError,
 @@ -333,6 +337,7 @@ export interface ClaudeAdapterLiveOptions {
   }) => ClaudeQueryRuntime;
   readonly nativeEventLogPath?: string;
   readonly nativeEventLogger?: EventNdjsonLogger;
+  readonly modelCatalog?: Effect.Effect<ClaudeModelCatalog>;
 }
 function isUuid(value: string): boolean {
 @@ -381,10 +386,11 @@ function normalizeClaudeStreamMessages(
 }
 function getEffectiveClaudeAgentEffort(
+  catalog: ClaudeModelCatalog,
   effort: string | null | undefined,
   model: string | null | undefined,
 ): ClaudeSdkEffort | null {
-  const normalized = normalizeClaudeCliEffort(effort, model);
+  const normalized = normalizeClaudeCatalogEffort(catalog, effort, model);
   return normalized ? (normalized as ClaudeSdkEffort) : null;
 }
 @@ -470,23 +476,10 @@ function maxClaudeContextWindowFromModelUsage(
 }
 function selectedClaudeContextWindow(
+  catalog: ClaudeModelCatalog,
   modelSelection: ModelSelection | undefined,
 ): number | undefined {
-  switch (modelSelection?.model) {
+  return resolveClaudeCatalogContextWindowTokens(catalog, modelSelection);
-    case "claude-opus-4-8":
-    case "claude-opus-4-7":
-      // Always 1M at the API; these models expose no contextWindow option.
-      return 1_000_000;
-  }
-  switch (resolveClaudeContextWindow(modelSelection)) {
-    case "1m":
-      return 1_000_000;
-    case "200k":
-      return 200_000;
-    default:
-      return undefined;
-  }
 }
 function finiteNonNegativeInteger(value: unknown): number | undefined {
 @@ -1234,6 +1227,7 @@ const CLAUDE_SETTING_SOURCES = [
 function buildPromptText(
   input: ProviderSendTurnInput,
   boundInstanceId: ProviderInstanceId,
+  catalog: ClaudeModelCatalog,
 ): string {
   const rawEffort =
     input.modelSelection?.instanceId === boundInstanceId
 @@ -1241,7 +1235,7 @@ function buildPromptText(
       : null;
   const claudeModel =
     input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection.model : undefined;
-  const caps = getClaudeModelCapabilities(claudeModel);
+  const caps = getClaudeCatalogModelCapabilities(catalog, claudeModel);
   const promptEffort = resolvePromptInjectedEffort(caps, rawEffort);
   return applyClaudePromptEffortPrefix(input.input?.trim() ?? "", promptEffort);
 @@ -1281,9 +1275,10 @@ const buildUserMessageEffect = Effect.fn("buildUserMessageEffect")(function* (
     readonly fileSystem: FileSystem.FileSystem;
     readonly attachmentsDir: string;
     readonly boundInstanceId: ProviderInstanceId;
+    readonly modelCatalog: ClaudeModelCatalog;
   },
 ) {
-  const text = buildPromptText(input, dependencies.boundInstanceId);
+  const text = buildPromptText(input, dependencies.boundInstanceId, dependencies.modelCatalog);
   const sdkContent: Array<Record<string, unknown>> = [];
   if (text.length > 0) {
 @@ -1682,6 +1677,9 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
   options?: ClaudeAdapterLiveOptions,
 ) {
   const boundInstanceId = options?.instanceId ?? ProviderInstanceId.make("claudeAgent");
+  const modelCatalogEffect = (
+    options?.modelCatalog ?? Effect.succeed(BUNDLED_CLAUDE_MODEL_CATALOG)
+  ).pipe(Effect.map((catalog) => scopeClaudeModelCatalog(catalog, claudeSettings.customModels)));
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const serverConfig = yield* ServerConfig;
 @@ -3805,6 +3803,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
   const startSession: ClaudeAdapterShape["startSession"] = Effect.fn("startSession")(
     function* (input) {
+      const modelCatalog = yield* modelCatalogEffect;
       if (input.provider !== undefined && input.provider !== PROVIDER) {
         return yield* new ProviderAdapterValidationError({
           provider: PROVIDER,
 @@ -4243,14 +4242,23 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       const claudeBinaryPath = claudeSdkExecutablePath;
       const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
-      const modelSelection =
+      const selectedModel =
         input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;
-      const caps = getClaudeModelCapabilities(modelSelection?.model);
+      const modelSelection = selectedModel
+        ? {
+            ...selectedModel,
+            model: resolveClaudeModelSlug(modelCatalog, selectedModel.model),
+          }
+        : undefined;
+      const caps = getClaudeCatalogModelCapabilities(modelCatalog, modelSelection?.model);
       const descriptors = getProviderOptionDescriptors({ caps });
-      const apiModelId = modelSelection ? resolveClaudeApiModelId(modelSelection) : undefined;
+      const apiModelId = modelSelection
-      const initialContextWindow = selectedClaudeContextWindow(modelSelection);
+        ? resolveClaudeCatalogApiModelId(modelCatalog, modelSelection)
+        : undefined;
+      const initialContextWindow = selectedClaudeContextWindow(modelCatalog, modelSelection);
       const rawEffort = getModelSelectionStringOptionValue(modelSelection, "effort");
-      const effort = resolveClaudeEffort(caps, rawEffort) ?? null;
+      const effort =
+        resolveClaudeCatalogEffort(modelCatalog, modelSelection?.model, rawEffort) ?? null;
       const fastModeSupported = descriptors.some(
         (descriptor) => descriptor.type === "boolean" && descriptor.id === "fastMode",
       );
 @@ -4263,8 +4271,12 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       const thinking = thinkingSupported
         ? getModelSelectionBooleanOptionValue(modelSelection, "thinking")
         : undefined;
-      const ultracode = isClaudeUltracodeEffort(effort);
+      const ultracode = isClaudeCatalogUltracodeEffort(effort);
-      const effectiveEffort = getEffectiveClaudeAgentEffort(effort, modelSelection?.model);
+      const effectiveEffort = getEffectiveClaudeAgentEffort(
+        modelCatalog,
+        effort,
+        modelSelection?.model,
+      );
       const runtimeModeToPermission: Record<string, PermissionMode> = {
         "auto-accept-edits": "acceptEdits",
         auto: "auto",
 @@ -4495,10 +4507,14 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
   const sendTurn: ClaudeAdapterShape["sendTurn"] = Effect.fn("sendTurn")(function* (input) {
     const context = yield* requireSession(input.threadId);
-    const modelSelection =
+    const modelCatalog = yield* modelCatalogEffect;
+    const selectedModel =
       input.modelSelection !== undefined && input.modelSelection.instanceId === boundInstanceId
         ? input.modelSelection
         : undefined;
+    const modelSelection = selectedModel
+      ? { ...selectedModel, model: resolveClaudeModelSlug(modelCatalog, selectedModel.model) }
+      : undefined;
     // A sendTurn while a real turn is running is a steer: the message is
     // queued into the live SDK agent loop and the work continues as the same
 @@ -4512,7 +4528,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     }
     if (modelSelection?.model) {
-      const apiModelId = resolveClaudeApiModelId(modelSelection);
+      const apiModelId = resolveClaudeCatalogApiModelId(modelCatalog, modelSelection);
       if (context.currentApiModelId !== apiModelId) {
         yield* Effect.tryPromise({
           try: () => context.query.setModel(apiModelId),
 @@ -4524,13 +4540,14 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         ...context.session,
         model: modelSelection.model,
       };
-      const turnCaps = getClaudeModelCapabilities(modelSelection.model);
+      const turnEffort = resolveClaudeCatalogEffort(
-      const turnEffort = resolveClaudeEffort(
+        modelCatalog,
-        turnCaps,
+        modelSelection.model,
         getModelSelectionStringOptionValue(modelSelection, "effort"),
       );
       context.currentEffort =
-        getEffectiveClaudeAgentEffort(turnEffort ?? null, modelSelection.model) ?? undefined;
+        getEffectiveClaudeAgentEffort(modelCatalog, turnEffort ?? null, modelSelection.model) ??
+        undefined;
     }
     // Apply interaction mode by switching the SDK's permission mode.
 @@ -4589,6 +4606,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       fileSystem,
       attachmentsDir: serverConfig.attachmentsDir,
       boundInstanceId,
+      modelCatalog,
     });
     yield* Queue.offer(context.promptQueue, {

apps/server/src/provider/Layers/ClaudeProvider.ts+13-487

...	@@ -1,8 +1,6 @@	...	@@ -1,8 +1,6 @@
1	import {	1	import {
2	type ClaudeSettings,	2	type ClaudeSettings,
3	type ModelCapabilities,	3	type ModelCapabilities,
4	type ModelSelection,
5	type ServerProviderModel,
6	type ServerProviderSlashCommand,	4	type ServerProviderSlashCommand,
7	} from "@t3tools/contracts";	5	} from "@t3tools/contracts";
8	import * as DateTime from "effect/DateTime";	6	import * as DateTime from "effect/DateTime";
...	@@ -12,14 +10,8 @@ import * as Option from "effect/Option";	...	@@ -12,14 +10,8 @@ import * as Option from "effect/Option";
12	import * as Path from "effect/Path";	10	import * as Path from "effect/Path";
13	import * as Result from "effect/Result";	11	import * as Result from "effect/Result";
14	import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";	12	import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
15	import {	13	import { createModelCapabilities } from "@t3tools/shared/model";
16	createModelCapabilities,
17	getModelSelectionStringOptionValue,
18	getProviderOptionCurrentValue,
19	getProviderOptionDescriptors,
20	} from "@t3tools/shared/model";
21	import { resolveSpawnCommand } from "@t3tools/shared/shell";	14	import { resolveSpawnCommand } from "@t3tools/shared/shell";
22	import { compareSemverVersions } from "@t3tools/shared/semver";
23	import {	15	import {
24	query as claudeQuery,	16	query as claudeQuery,
25	type Options as ClaudeQueryOptions,	17	type Options as ClaudeQueryOptions,
...	@@ -29,8 +21,6 @@ import {	...	@@ -29,8 +21,6 @@ import {
29	} from "@anthropic-ai/claude-agent-sdk";	21	} from "@anthropic-ai/claude-agent-sdk";
30		22
31	import {	23	import {
32	buildBooleanOptionDescriptor,
33	buildSelectOptionDescriptor,
34	buildServerProvider,	24	buildServerProvider,
35	DEFAULT_TIMEOUT_MS,	25	DEFAULT_TIMEOUT_MS,
36	isCommandMissingCause,	26	isCommandMissingCause,
...	@@ -42,6 +32,12 @@ import {	...	@@ -42,6 +32,12 @@ import {
42	import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";	32	import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
43	import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";	33	import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
44	import { discoverClaudeSkills } from "../Drivers/ClaudeSkills.ts";	34	import { discoverClaudeSkills } from "../Drivers/ClaudeSkills.ts";
		35	import {
		36	BUNDLED_CLAUDE_MODEL_CATALOG,
		37	type ClaudeModelCatalog,
		38	formatClaudeVersionUpgradeMessage,
		39	resolveClaudeModelsForVersion,
		40	} from "../ClaudeModelCatalog.ts";
45		41
46	const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({	42	const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
47	optionDescriptors: [],	43	optionDescriptors: [],
...	@@ -51,468 +47,6 @@ const CLAUDE_PRESENTATION = {	...	@@ -51,468 +47,6 @@ const CLAUDE_PRESENTATION = {
51	displayName: "Claude",	47	displayName: "Claude",
52	showInteractionModeToggle: true,	48	showInteractionModeToggle: true,
53	} as const;	49	} as const;
54	const MINIMUM_CLAUDE_FABLE_5_1_VERSION = "2.1.257";
55	const MINIMUM_CLAUDE_OPUS_5_VERSION = "2.1.219";
56	const MINIMUM_CLAUDE_FABLE_5_VERSION = "2.1.169";
57	const MINIMUM_CLAUDE_OPUS_4_8_VERSION = "2.1.154";
58	const MINIMUM_CLAUDE_OPUS_4_7_VERSION = "2.1.111";
59
60	const CLAUDE_MODEL_CATALOG: ReadonlyArray<ServerProviderModel> = [
61	{
62	slug: "claude-fable-5-1",
63	name: "Claude Fable 5.1",
64	isCustom: false,
65	capabilities: createModelCapabilities({
66	optionDescriptors: [
67	buildSelectOptionDescriptor({
68	id: "effort",
69	label: "Reasoning",
70	options: [
71	{ value: "low", label: "Low" },
72	{ value: "medium", label: "Medium" },
73	{ value: "high", label: "High", isDefault: true },
74	{ value: "xhigh", label: "Extra High" },
75	{ value: "max", label: "Max" },
76	{
77	value: "ultracode",
78	label: "Ultracode",
79	description: "xhigh effort plus multi-agent workflow orchestration",
80	},
81	{ value: "ultrathink", label: "Ultrathink" },
82	],
83	promptInjectedValues: ["ultrathink"],
84	}),
85	buildSelectOptionDescriptor({
86	id: "contextWindow",
87	label: "Context Window",
88	options: [
89	{ value: "200k", label: "200k" },
90	{ value: "1m", label: "1M", isDefault: true },
91	],
92	}),
93	],
94	}),
95	},
96	{
97	slug: "claude-fable-5",
98	name: "Claude Fable 5",
99	isCustom: false,
100	capabilities: createModelCapabilities({
101	optionDescriptors: [
102	buildSelectOptionDescriptor({
103	id: "effort",
104	label: "Reasoning",
105	options: [
106	{ value: "low", label: "Low" },
107	{ value: "medium", label: "Medium" },
108	{ value: "high", label: "High", isDefault: true },
109	{ value: "xhigh", label: "Extra High" },
110	{ value: "max", label: "Max" },
111	{
112	value: "ultracode",
113	label: "Ultracode",
114	description: "xhigh effort plus multi-agent workflow orchestration",
115	},
116	{ value: "ultrathink", label: "Ultrathink" },
117	],
118	promptInjectedValues: ["ultrathink"],
119	}),
120	buildSelectOptionDescriptor({
121	id: "contextWindow",
122	label: "Context Window",
123	options: [
124	{ value: "200k", label: "200k" },
125	{ value: "1m", label: "1M", isDefault: true },
126	],
127	}),
128	],
129	}),
130	},
131	{
132	slug: "claude-opus-5",
133	name: "Claude Opus 5",
134	isCustom: false,
135	capabilities: createModelCapabilities({
136	optionDescriptors: [
137	buildSelectOptionDescriptor({
138	id: "effort",
139	label: "Reasoning",
140	options: [
141	{ value: "low", label: "Low" },
142	{ value: "medium", label: "Medium" },
143	{ value: "high", label: "High", isDefault: true },
144	{ value: "xhigh", label: "Extra High" },
145	{ value: "max", label: "Max" },
146	{
147	value: "ultracode",
148	label: "Ultracode",
149	description: "xhigh effort plus multi-agent workflow orchestration",
150	},
151	{ value: "ultrathink", label: "Ultrathink" },
152	],
153	promptInjectedValues: ["ultrathink"],
154	}),
155	buildBooleanOptionDescriptor({
156	id: "fastMode",
157	label: "Fast Mode",
158	}),
159	buildSelectOptionDescriptor({
160	id: "contextWindow",
161	label: "Context Window",
162	// Claude Code selects the 1M variant explicitly (`claude-opus-5[1m]`).
163	options: [
164	{ value: "200k", label: "200k" },
165	{ value: "1m", label: "1M", isDefault: true },
166	],
167	}),
168	],
169	}),
170	},
171	{
172	slug: "claude-opus-4-8",
173	name: "Claude Opus 4.8",
174	isCustom: false,
175	capabilities: createModelCapabilities({
176	optionDescriptors: [
177	buildSelectOptionDescriptor({
178	id: "effort",
179	label: "Reasoning",
180	options: [
181	{ value: "low", label: "Low" },
182	{ value: "medium", label: "Medium" },
183	{ value: "high", label: "High", isDefault: true },
184	{ value: "xhigh", label: "Extra High" },
185	{ value: "max", label: "Max" },
186	{
187	value: "ultracode",
188	label: "Ultracode",
189	description: "xhigh effort plus multi-agent workflow orchestration",
190	},
191	{ value: "ultrathink", label: "Ultrathink" },
192	],
193	promptInjectedValues: ["ultrathink"],
194	}),
195	buildBooleanOptionDescriptor({
196	id: "fastMode",
197	label: "Fast Mode",
198	}),
199	],
200	}),
201	},
202	{
203	slug: "claude-opus-4-7",
204	name: "Claude Opus 4.7",
205	isCustom: false,
206	capabilities: createModelCapabilities({
207	optionDescriptors: [
208	buildSelectOptionDescriptor({
209	id: "effort",
210	label: "Reasoning",
211	options: [
212	{ value: "low", label: "Low" },
213	{ value: "medium", label: "Medium" },
214	{ value: "high", label: "High" },
215	{ value: "xhigh", label: "Extra High", isDefault: true },
216	{ value: "max", label: "Max" },
217	{ value: "ultrathink", label: "Ultrathink" },
218	],
219	promptInjectedValues: ["ultrathink"],
220	}),
221	buildBooleanOptionDescriptor({
222	id: "fastMode",
223	label: "Fast Mode",
224	}),
225	],
226	}),
227	},
228	{
229	slug: "claude-opus-4-6",
230	name: "Claude Opus 4.6",
231	isCustom: false,
232	capabilities: createModelCapabilities({
233	optionDescriptors: [
234	buildSelectOptionDescriptor({
235	id: "effort",
236	label: "Reasoning",
237	options: [
238	{ value: "low", label: "Low" },
239	{ value: "medium", label: "Medium" },
240	{ value: "high", label: "High", isDefault: true },
241	{ value: "max", label: "Max" },
242	{ value: "ultrathink", label: "Ultrathink" },
243	],
244	promptInjectedValues: ["ultrathink"],
245	}),
246	buildBooleanOptionDescriptor({
247	id: "fastMode",
248	label: "Fast Mode",
249	}),
250	buildSelectOptionDescriptor({
251	id: "contextWindow",
252	label: "Context Window",
253	options: [
254	{ value: "200k", label: "200k" },
255	{ value: "1m", label: "1M", isDefault: true },
256	],
257	}),
258	],
259	}),
260	},
261	{
262	slug: "claude-opus-4-5",
263	name: "Claude Opus 4.5",
264	isCustom: false,
265	capabilities: createModelCapabilities({
266	optionDescriptors: [
267	buildSelectOptionDescriptor({
268	id: "effort",
269	label: "Reasoning",
270	options: [
271	{ value: "low", label: "Low" },
272	{ value: "medium", label: "Medium" },
273	{ value: "high", label: "High", isDefault: true },
274	{ value: "max", label: "Max" },
275	],
276	}),
277	buildBooleanOptionDescriptor({
278	id: "fastMode",
279	label: "Fast Mode",
280	}),
281	],
282	}),
283	},
284	{
285	slug: "claude-sonnet-5",
286	name: "Claude Sonnet 5",
287	isCustom: false,
288	capabilities: createModelCapabilities({
289	optionDescriptors: [
290	buildSelectOptionDescriptor({
291	id: "effort",
292	label: "Reasoning",
293	options: [
294	{ value: "low", label: "Low" },
295	{ value: "medium", label: "Medium" },
296	{ value: "high", label: "High", isDefault: true },
297	{ value: "xhigh", label: "Extra High" },
298	{ value: "max", label: "Max" },
299	{ value: "ultrathink", label: "Ultrathink" },
300	],
301	promptInjectedValues: ["ultrathink"],
302	}),
303	buildSelectOptionDescriptor({
304	id: "contextWindow",
305	label: "Context Window",
306	// Sonnet is 200k-default in Claude Code (1M is opt-in there too).
307	options: [
308	{ value: "200k", label: "200k", isDefault: true },
309	{ value: "1m", label: "1M" },
310	],
311	}),
312	],
313	}),
314	},
315	{
316	slug: "claude-sonnet-4-6",
317	name: "Claude Sonnet 4.6",
318	isCustom: false,
319	capabilities: createModelCapabilities({
320	optionDescriptors: [
321	buildSelectOptionDescriptor({
322	id: "effort",
323	label: "Reasoning",
324	options: [
325	{ value: "low", label: "Low" },
326	{ value: "medium", label: "Medium" },
327	{ value: "high", label: "High", isDefault: true },
328	{ value: "max", label: "Max" },
329	{ value: "ultrathink", label: "Ultrathink" },
330	],
331	promptInjectedValues: ["ultrathink"],
332	}),
333	buildSelectOptionDescriptor({
334	id: "contextWindow",
335	label: "Context Window",
336	// Sonnet is 200k-default in Claude Code (1M is opt-in there too).
337	options: [
338	{ value: "200k", label: "200k", isDefault: true },
339	{ value: "1m", label: "1M" },
340	],
341	}),
342	],
343	}),
344	},
345	{
346	slug: "claude-haiku-4-5",
347	name: "Claude Haiku 4.5",
348	isCustom: false,
349	capabilities: createModelCapabilities({
350	optionDescriptors: [
351	buildBooleanOptionDescriptor({
352	id: "thinking",
353	label: "Thinking",
354	}),
355	],
356	}),
357	},
358	];
359
360	// Legacy classification happens at the driver boundary via `applyModelManifest`,
361	// so the catalog itself carries no `isLegacy` flags.
362	const BUILT_IN_MODELS: ReadonlyArray<ServerProviderModel> = CLAUDE_MODEL_CATALOG;
363
364	function supportsClaudeFable51(version: string \| null \| undefined): boolean {
365	return version ? compareSemverVersions(version, MINIMUM_CLAUDE_FABLE_5_1_VERSION) >= 0 : false;
366	}
367
368	function supportsClaudeOpus5(version: string \| null \| undefined): boolean {
369	return version ? compareSemverVersions(version, MINIMUM_CLAUDE_OPUS_5_VERSION) >= 0 : false;
370	}
371
372	function supportsClaudeFable5(version: string \| null \| undefined): boolean {
373	return version ? compareSemverVersions(version, MINIMUM_CLAUDE_FABLE_5_VERSION) >= 0 : false;
374	}
375
376	function supportsClaudeOpus48(version: string \| null \| undefined): boolean {
377	return version ? compareSemverVersions(version, MINIMUM_CLAUDE_OPUS_4_8_VERSION) >= 0 : false;
378	}
379
380	function supportsClaudeOpus47(version: string \| null \| undefined): boolean {
381	return version ? compareSemverVersions(version, MINIMUM_CLAUDE_OPUS_4_7_VERSION) >= 0 : false;
382	}
383
384	function getBuiltInClaudeModelsForVersion(
385	version: string \| null \| undefined,
386	): ReadonlyArray<ServerProviderModel> {
387	return BUILT_IN_MODELS.filter((model) => {
388	if (model.slug === "claude-fable-5-1") {
389	return supportsClaudeFable51(version);
390	}
391	if (model.slug === "claude-opus-5") {
392	return supportsClaudeOpus5(version);
393	}
394	if (model.slug === "claude-fable-5") {
395	return supportsClaudeFable5(version);
396	}
397	if (model.slug === "claude-opus-4-8") {
398	return supportsClaudeOpus48(version);
399	}
400	if (model.slug === "claude-opus-4-7") {
401	return supportsClaudeOpus47(version);
402	}
403	return true;
404	});
405	}
406
407	function formatClaudeFable51UpgradeMessage(version: string \| null): string {
408	const versionLabel = version ? `v${version}` : "the installed version";
409	return `Claude Code ${versionLabel} is too old for Claude Fable 5.1. Upgrade to v${MINIMUM_CLAUDE_FABLE_5_1_VERSION} or newer to access it.`;
410	}
411
412	function formatClaudeOpus5UpgradeMessage(version: string \| null): string {
413	const versionLabel = version ? `v${version}` : "the installed version";
414	return `Claude Code ${versionLabel} is too old for Claude Opus 5. Upgrade to v${MINIMUM_CLAUDE_OPUS_5_VERSION} or newer to access it.`;
415	}
416
417	function formatClaudeFable5UpgradeMessage(version: string \| null): string {
418	const versionLabel = version ? `v${version}` : "the installed version";
419	return `Claude Code ${versionLabel} is too old for Claude Fable 5. Upgrade to v${MINIMUM_CLAUDE_FABLE_5_VERSION} or newer to access it.`;
420	}
421
422	function formatClaudeOpus48UpgradeMessage(version: string \| null): string {
423	const versionLabel = version ? `v${version}` : "the installed version";
424	return `Claude Code ${versionLabel} is too old for Claude Opus 4.8. Upgrade to v${MINIMUM_CLAUDE_OPUS_4_8_VERSION} or newer to access it.`;
425	}
426
427	function formatClaudeOpus47UpgradeMessage(version: string \| null): string {
428	const versionLabel = version ? `v${version}` : "the installed version";
429	return `Claude Code ${versionLabel} is too old for Claude Opus 4.7. Upgrade to v${MINIMUM_CLAUDE_OPUS_4_7_VERSION} or newer to access it.`;
430	}
431
432	export function getClaudeModelCapabilities(model: string \| null \| undefined): ModelCapabilities {
433	const slug = model?.trim();
434	return (
435	BUILT_IN_MODELS.find((candidate) => candidate.slug === slug)?.capabilities ??
436	DEFAULT_CLAUDE_MODEL_CAPABILITIES
437	);
438	}
439
440	export function resolveClaudeEffort(
441	caps: ModelCapabilities,
442	raw: string \| null \| undefined,
443	): string \| undefined {
444	const descriptors = getProviderOptionDescriptors({
445	caps,
446	...(raw ? { selections: [{ id: "effort", value: raw }] } : {}),
447	});
448	const effortDescriptor = descriptors.find((descriptor) => descriptor.id === "effort");
449	const value = getProviderOptionCurrentValue(effortDescriptor);
450	return typeof value === "string" ? value : undefined;
451	}
452
453	/**
454	* Normalize a resolved Claude effort value into one suitable for the Claude
455	* CLI's `--effort` flag.
456	*
457	* Mirrors the mapping used when invoking the Claude Agent SDK
458	* ({@link getEffectiveClaudeAgentEffort} in ClaudeAdapter): `ultracode` is a
459	* Claude Code setting that pairs with `xhigh`, `ultrathink` is filtered out
460	* because it is a prompt-prefix mode, and older model compatibility mappings
461	* are preserved for current Claude Code behavior.
462	*/
463	export function normalizeClaudeCliEffort(
464	effort: string \| null \| undefined,
465	model: string \| null \| undefined,
466	): string \| undefined {
467	if (!effort \|\| effort === "ultrathink") {
468	return undefined;
469	}
470	if (effort === "ultracode") {
471	return "xhigh";
472	}
473	if (
474	effort === "xhigh" &&
475	model !== "claude-fable-5-1" &&
476	model !== "claude-fable-5" &&
477	model !== "claude-opus-5" &&
478	model !== "claude-opus-4-8" &&
479	model !== "claude-sonnet-5"
480	) {
481	return "max";
482	}
483	if (effort === "max" && model === "claude-sonnet-4-6") {
484	return "high";
485	}
486	return effort;
487	}
488
489	export function isClaudeUltracodeEffort(effort: string \| null \| undefined): boolean {
490	return effort === "ultracode";
491	}
492
493	export function resolveClaudeContextWindow(
494	modelSelection: ModelSelection \| undefined,
495	): string \| undefined {
496	const caps = getClaudeModelCapabilities(modelSelection?.model);
497	const raw = getModelSelectionStringOptionValue(modelSelection, "contextWindow");
498	const descriptors = getProviderOptionDescriptors({
499	caps,
500	...(raw ? { selections: [{ id: "contextWindow", value: raw }] } : {}),
501	});
502	const descriptor = descriptors.find((candidate) => candidate.id === "contextWindow");
503	const value = getProviderOptionCurrentValue(descriptor);
504	return typeof value === "string" ? value : undefined;
505	}
506
507	export function resolveClaudeApiModelId(modelSelection: ModelSelection): string {
508	switch (resolveClaudeContextWindow(modelSelection)) {
509	case "1m":
510	return `${modelSelection.model}[1m]`;
511	default:
512	return modelSelection.model;
513	}
514	}
515
516	function toTitleCaseWords(value: string): string {	50	function toTitleCaseWords(value: string): string {
517	const parts: Array<string> = [];	51	const parts: Array<string> = [];
518	for (const part of value.split(/[\s_-]+/g)) {	52	for (const part of value.split(/[\s_-]+/g)) {
...	@@ -860,6 +394,7 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(	...	@@ -860,6 +394,7 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
860	) => Effect.Effect<ClaudeCapabilitiesProbe \| undefined>,	394	) => Effect.Effect<ClaudeCapabilitiesProbe \| undefined>,
861	environment?: NodeJS.ProcessEnv,	395	environment?: NodeJS.ProcessEnv,
862	cwd?: string,	396	cwd?: string,
		397	modelCatalog: ClaudeModelCatalog = BUNDLED_CLAUDE_MODEL_CATALOG,
863	): Effect.fn.Return<	398	): Effect.fn.Return<
864	ServerProviderDraft,	399	ServerProviderDraft,
865	never,	400	never,
...	@@ -868,7 +403,7 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(	...	@@ -868,7 +403,7 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
868	const resolvedEnvironment = environment ?? process.env;	403	const resolvedEnvironment = environment ?? process.env;
869	const checkedAt = DateTime.formatIso(yield* DateTime.now);	404	const checkedAt = DateTime.formatIso(yield* DateTime.now);
870	const allModels = providerModelsFromSettings(	405	const allModels = providerModelsFromSettings(
871	BUILT_IN_MODELS,	406	modelCatalog.models.map((entry) => entry.model),
872	claudeSettings.customModels,	407	claudeSettings.customModels,
873	DEFAULT_CLAUDE_MODEL_CAPABILITIES,	408	DEFAULT_CLAUDE_MODEL_CAPABILITIES,
874	);	409	);
...	@@ -958,21 +493,11 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(	...	@@ -958,21 +493,11 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
958	}	493	}
959		494
960	const models = providerModelsFromSettings(	495	const models = providerModelsFromSettings(
961	getBuiltInClaudeModelsForVersion(parsedVersion),	496	resolveClaudeModelsForVersion(modelCatalog, parsedVersion),
962	claudeSettings.customModels,	497	claudeSettings.customModels,
963	DEFAULT_CLAUDE_MODEL_CAPABILITIES,	498	DEFAULT_CLAUDE_MODEL_CAPABILITIES,
964	);	499	);
965	const versionUpgradeMessage = supportsClaudeFable51(parsedVersion)	500	const versionUpgradeMessage = formatClaudeVersionUpgradeMessage(modelCatalog, parsedVersion);
966	? undefined
967	: supportsClaudeOpus5(parsedVersion)
968	? formatClaudeFable51UpgradeMessage(parsedVersion)
969	: supportsClaudeFable5(parsedVersion)
970	? formatClaudeOpus5UpgradeMessage(parsedVersion)
971	: supportsClaudeOpus48(parsedVersion)
972	? formatClaudeFable5UpgradeMessage(parsedVersion)
973	: supportsClaudeOpus47(parsedVersion)
974	? formatClaudeOpus48UpgradeMessage(parsedVersion)
975	: formatClaudeOpus47UpgradeMessage(parsedVersion);
976		501
977	const capabilities = resolveCapabilities	502	const capabilities = resolveCapabilities
978	? yield* resolveCapabilities(claudeSettings).pipe(Effect.orElseSucceed(() => undefined))	503	? yield* resolveCapabilities(claudeSettings).pipe(Effect.orElseSucceed(() => undefined))
...	@@ -1035,11 +560,12 @@ const nowIso = Effect.map(DateTime.now, DateTime.formatIso);	...	@@ -1035,11 +560,12 @@ const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
1035		560
1036	export const makePendingClaudeProvider = (	561	export const makePendingClaudeProvider = (
1037	claudeSettings: ClaudeSettings,	562	claudeSettings: ClaudeSettings,
		563	modelCatalog: ClaudeModelCatalog = BUNDLED_CLAUDE_MODEL_CATALOG,
1038	): Effect.Effect<ServerProviderDraft> =>	564	): Effect.Effect<ServerProviderDraft> =>
1039	Effect.gen(function* () {	565	Effect.gen(function* () {
1040	const checkedAt = yield* nowIso;	566	const checkedAt = yield* nowIso;
1041	const models = providerModelsFromSettings(	567	const models = providerModelsFromSettings(
1042	BUILT_IN_MODELS,	568	modelCatalog.models.map((entry) => entry.model),
1043	claudeSettings.customModels,	569	claudeSettings.customModels,
1044	DEFAULT_CLAUDE_MODEL_CAPABILITIES,	570	DEFAULT_CLAUDE_MODEL_CAPABILITIES,
1045	);	571	);

apps/server/src/provider/Layers/ProviderRegistry.test.ts-242

...	@@ -2051,248 +2051,6 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te	...	@@ -2051,248 +2051,6 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
2051	),	2051	),
2052	);	2052	);
2053		2053
2054	it.effect("includes Claude Opus 5 on supported Claude Code versions", () =>
2055	Effect.gen(function* () {
2056	const status = yield* checkClaudeProviderStatus(
2057	defaultClaudeSettings,
2058	claudeCapabilities(),
2059	);
2060	const opus5 = status.models.find((model) => model.slug === "claude-opus-5");
2061	assert.strictEqual(opus5?.name, "Claude Opus 5");
2062	}).pipe(
2063	Effect.provide(
2064	mockSpawnerLayer((args) => {
2065	const joined = args.join(" ");
2066	if (joined === "--version") return { stdout: "2.1.219\n", stderr: "", code: 0 };
2067	if (joined === "auth status")
2068	return {
2069	stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
2070	stderr: "",
2071	code: 0,
2072	};
2073	throw new Error(`Unexpected args: ${joined}`);
2074	}),
2075	),
2076	),
2077	);
2078
2079	it.effect("hides Claude Opus 5 on older Claude Code versions", () =>
2080	Effect.gen(function* () {
2081	const status = yield* checkClaudeProviderStatus(
2082	defaultClaudeSettings,
2083	claudeCapabilities(),
2084	);
2085	assert.strictEqual(
2086	status.models.some((model) => model.slug === "claude-opus-5"),
2087	false,
2088	);
2089	assert.strictEqual(
2090	status.message,
2091	"Claude Code v2.1.218 is too old for Claude Opus 5. Upgrade to v2.1.219 or newer to access it.",
2092	);
2093	}).pipe(
2094	Effect.provide(
2095	mockSpawnerLayer((args) => {
2096	const joined = args.join(" ");
2097	if (joined === "--version") return { stdout: "2.1.218\n", stderr: "", code: 0 };
2098	if (joined === "auth status")
2099	return {
2100	stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
2101	stderr: "",
2102	code: 0,
2103	};
2104	throw new Error(`Unexpected args: ${joined}`);
2105	}),
2106	),
2107	),
2108	);
2109
2110	it.effect("includes Claude Fable 5 on supported Claude Code versions", () =>
2111	Effect.gen(function* () {
2112	const status = yield* checkClaudeProviderStatus(
2113	defaultClaudeSettings,
2114	claudeCapabilities(),
2115	);
2116	const fable5 = status.models.find((model) => model.slug === "claude-fable-5");
2117	assert.strictEqual(fable5?.name, "Claude Fable 5");
2118	}).pipe(
2119	Effect.provide(
2120	mockSpawnerLayer((args) => {
2121	const joined = args.join(" ");
2122	if (joined === "--version") return { stdout: "2.1.169\n", stderr: "", code: 0 };
2123	if (joined === "auth status")
2124	return {
2125	stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
2126	stderr: "",
2127	code: 0,
2128	};
2129	throw new Error(`Unexpected args: ${joined}`);
2130	}),
2131	),
2132	),
2133	);
2134
2135	it.effect("includes Claude Fable 5.1 on supported Claude Code versions", () =>
2136	Effect.gen(function* () {
2137	const status = yield* checkClaudeProviderStatus(
2138	defaultClaudeSettings,
2139	claudeCapabilities(),
2140	);
2141	const fable51 = status.models.find((model) => model.slug === "claude-fable-5-1");
2142	assert.strictEqual(fable51?.name, "Claude Fable 5.1");
2143	}).pipe(
2144	Effect.provide(
2145	mockSpawnerLayer((args) => {
2146	const joined = args.join(" ");
2147	if (joined === "--version") return { stdout: "2.1.257\n", stderr: "", code: 0 };
2148	if (joined === "auth status")
2149	return {
2150	stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
2151	stderr: "",
2152	code: 0,
2153	};
2154	throw new Error(`Unexpected args: ${joined}`);
2155	}),
2156	),
2157	),
2158	);
2159
2160	it.effect("hides Claude Fable 5.1 on older Claude Code versions", () =>
2161	Effect.gen(function* () {
2162	const status = yield* checkClaudeProviderStatus(
2163	defaultClaudeSettings,
2164	claudeCapabilities(),
2165	);
2166	assert.strictEqual(
2167	status.models.some((model) => model.slug === "claude-fable-5-1"),
2168	false,
2169	);
2170	assert.strictEqual(
2171	status.message,
2172	"Claude Code v2.1.256 is too old for Claude Fable 5.1. Upgrade to v2.1.257 or newer to access it.",
2173	);
2174	}).pipe(
2175	Effect.provide(
2176	mockSpawnerLayer((args) => {
2177	const joined = args.join(" ");
2178	if (joined === "--version") return { stdout: "2.1.256\n", stderr: "", code: 0 };
2179	if (joined === "auth status")
2180	return {
2181	stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
2182	stderr: "",
2183	code: 0,
2184	};
2185	throw new Error(`Unexpected args: ${joined}`);
2186	}),
2187	),
2188	),
2189	);
2190
2191	it.effect("hides Claude Fable 5 on older Claude Code versions", () =>
2192	Effect.gen(function* () {
2193	const status = yield* checkClaudeProviderStatus(
2194	defaultClaudeSettings,
2195	claudeCapabilities(),
2196	);
2197	assert.strictEqual(
2198	status.models.some((model) => model.slug === "claude-fable-5"),
2199	false,
2200	);
2201	assert.strictEqual(
2202	status.message,
2203	"Claude Code v2.1.168 is too old for Claude Fable 5. Upgrade to v2.1.169 or newer to access it.",
2204	);
2205	}).pipe(
2206	Effect.provide(
2207	mockSpawnerLayer((args) => {
2208	const joined = args.join(" ");
2209	if (joined === "--version") return { stdout: "2.1.168\n", stderr: "", code: 0 };
2210	if (joined === "auth status")
2211	return {
2212	stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
2213	stderr: "",
2214	code: 0,
2215	};
2216	throw new Error(`Unexpected args: ${joined}`);
2217	}),
2218	),
2219	),
2220	);
2221
2222	it.effect(
2223	"includes Claude Opus 4.7 with xhigh as the default effort on supported versions",
2224	() =>
2225	Effect.gen(function* () {
2226	const status = yield* checkClaudeProviderStatus(
2227	defaultClaudeSettings,
2228	claudeCapabilities(),
2229	);
2230	const opus47 = status.models.find((model) => model.slug === "claude-opus-4-7");
2231	if (!opus47) {
2232	assert.fail("Expected Claude Opus 4.7 to be present for Claude Code v2.1.111.");
2233	}
2234	if (!opus47.capabilities) {
2235	assert.fail(
2236	"Expected Claude Opus 4.7 capabilities to be present for Claude Code v2.1.111.",
2237	);
2238	}
2239	const effortDescriptor = opus47.capabilities.optionDescriptors?.find(
2240	(descriptor) => descriptor.type === "select" && descriptor.id === "effort",
2241	);
2242	assert.deepStrictEqual(
2243	effortDescriptor?.type === "select"
2244	? effortDescriptor.options.find((option) => option.isDefault)
2245	: undefined,
2246	{ id: "xhigh", label: "Extra High", isDefault: true },
2247	);
2248	}).pipe(
2249	Effect.provide(
2250	mockSpawnerLayer((args) => {
2251	const joined = args.join(" ");
2252	if (joined === "--version") return { stdout: "2.1.111\n", stderr: "", code: 0 };
2253	if (joined === "auth status")
2254	return {
2255	stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
2256	stderr: "",
2257	code: 0,
2258	};
2259	throw new Error(`Unexpected args: ${joined}`);
2260	}),
2261	),
2262	),
2263	);
2264
2265	it.effect("hides Claude Opus 4.7 on older Claude Code versions", () =>
2266	Effect.gen(function* () {
2267	const status = yield* checkClaudeProviderStatus(
2268	defaultClaudeSettings,
2269	claudeCapabilities(),
2270	);
2271	assert.strictEqual(
2272	status.models.some((model) => model.slug === "claude-opus-4-7"),
2273	false,
2274	);
2275	assert.strictEqual(
2276	status.message,
2277	"Claude Code v2.1.110 is too old for Claude Opus 4.7. Upgrade to v2.1.111 or newer to access it.",
2278	);
2279	}).pipe(
2280	Effect.provide(
2281	mockSpawnerLayer((args) => {
2282	const joined = args.join(" ");
2283	if (joined === "--version") return { stdout: "2.1.110\n", stderr: "", code: 0 };
2284	if (joined === "auth status")
2285	return {
2286	stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
2287	stderr: "",
2288	code: 0,
2289	};
2290	throw new Error(`Unexpected args: ${joined}`);
2291	}),
2292	),
2293	),
2294	);
2295
2296	it.effect("returns a display label for claude subscription types", () =>	2054	it.effect("returns a display label for claude subscription types", () =>
2297	Effect.gen(function* () {	2055	Effect.gen(function* () {
2298	const status = yield* checkClaudeProviderStatus(	2056	const status = yield* checkClaudeProviderStatus(

apps/server/src/provider/ModelManifest.test.ts+239-64

...	@@ -3,6 +3,7 @@ import * as NodeServices from "@effect/platform-node/NodeServices";	...	@@ -3,6 +3,7 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
3	import { ProviderDriverKind, type ServerProviderModel } from "@t3tools/contracts";	3	import { ProviderDriverKind, type ServerProviderModel } from "@t3tools/contracts";
4	import * as Effect from "effect/Effect";	4	import * as Effect from "effect/Effect";
5	import * as Layer from "effect/Layer";	5	import * as Layer from "effect/Layer";
		6	import * as TestClock from "effect/testing/TestClock";
6	import { HttpClient, HttpClientResponse } from "effect/unstable/http";	7	import { HttpClient, HttpClientResponse } from "effect/unstable/http";
7		8
8	import * as ServerConfig from "../config.ts";	9	import * as ServerConfig from "../config.ts";
...	@@ -10,61 +11,20 @@ import * as ServerSettings from "../serverSettings.ts";	...	@@ -10,61 +11,20 @@ import * as ServerSettings from "../serverSettings.ts";
10	import {	11	import {
11	BUNDLED_MODEL_MANIFEST,	12	BUNDLED_MODEL_MANIFEST,
12	classifyModels,	13	classifyModels,
13	isLegacyModel,
14	make,	14	make,
		15	resolveProviderCatalog,
15	type ModelManifestData,	16	type ModelManifestData,
16	} from "./ModelManifest.ts";	17	} from "./ModelManifest.ts";
17		18
18	const CODEX = ProviderDriverKind.make("codex");	19	/**
19	const CLAUDE = ProviderDriverKind.make("claudeAgent");	20	* Test policy: this file covers manifest machinery, not manifest contents.
20	const CURSOR = ProviderDriverKind.make("cursor");	21	* Do not add assertions for real model slugs, names, status, aliases, or
21		22	* profiles when editing model-manifest.json. Add tests only when fetch/cache
22	describe("isLegacyModel (bundled manifest)", () => {	23	* behavior or the provider-neutral resolver semantics change, and use
23	it("keeps current Codex models out of legacy models", () => {	24	* synthetic models for resolver coverage.
24	assert.deepStrictEqual(	25	*/
25	[
26	"gpt-5.6-luna",
27	"gpt-5.6-terra",
28	"gpt-5.6-sol",
29	"gpt-daybreak-blue-latest",
30	"gpt-daybreak-red-latest",
31	"gpt-5.4",
32	].map((model) => [model, isLegacyModel(BUNDLED_MODEL_MANIFEST, CODEX, model)]),
33	[
34	["gpt-5.6-luna", false],
35	["gpt-5.6-terra", false],
36	["gpt-5.6-sol", false],
37	["gpt-daybreak-blue-latest", false],
38	["gpt-daybreak-red-latest", false],
39	["gpt-5.4", true],
40	],
41	);
42	});
43
44	it("keeps only the Claude 5 family out of legacy models", () => {
45	assert.deepStrictEqual(
46	[
47	"claude-fable-5-1",
48	"claude-fable-5",
49	"claude-opus-5",
50	"claude-sonnet-5",
51	"claude-opus-4-8",
52	].map((model) => [model, isLegacyModel(BUNDLED_MODEL_MANIFEST, CLAUDE, model)]),
53	[
54	["claude-fable-5-1", false],
55	["claude-fable-5", true],
56	["claude-opus-5", false],
57	["claude-sonnet-5", false],
58	["claude-opus-4-8", true],
59	],
60	);
61	});
62
63	it("leaves driver kinds without a manifest entry unflagged", () => {
64	assert.isFalse(isLegacyModel(BUNDLED_MODEL_MANIFEST, CURSOR, "composer-1.5"));
65	});
66	});
67		26
		27	const CODEX = ProviderDriverKind.make("codex");
68	const model = (overrides: Partial<ServerProviderModel>): ServerProviderModel => ({	28	const model = (overrides: Partial<ServerProviderModel>): ServerProviderModel => ({
69	slug: "gpt-test",	29	slug: "gpt-test",
70	name: "GPT Test",	30	name: "GPT Test",
...	@@ -75,37 +35,227 @@ const model = (overrides: Partial<ServerProviderModel>): ServerProviderModel =>	...	@@ -75,37 +35,227 @@ const model = (overrides: Partial<ServerProviderModel>): ServerProviderModel =>
75		35
76	describe("classifyModels", () => {	36	describe("classifyModels", () => {
77	it("flags non-current models, clears stale flags, and skips custom models", () => {	37	it("flags non-current models, clears stale flags, and skips custom models", () => {
		38	const manifest: ModelManifestData = {
		39	version: 1,
		40	currentModels: { codex: ["current-a", "current-b"] },
		41	};
78	const models = [	42	const models = [
79	model({ slug: "gpt-5.6-sol" }),	43	model({ slug: "current-a" }),
80	// Stale flag from a previous classification pass must be cleared.	44	// Stale flag from a previous classification pass must be cleared.
81	model({ slug: "gpt-5.6-luna", isLegacy: true }),	45	model({ slug: "current-b", isLegacy: true }),
82	model({ slug: "gpt-5.4" }),	46	model({ slug: "old-model" }),
83	// Custom models are user-defined and never reclassified.	47	// Custom models are user-defined and never reclassified.
84	model({ slug: "my-own-model", isCustom: true }),	48	model({ slug: "my-own-model", isCustom: true }),
85	];	49	];
86	assert.deepStrictEqual(	50	assert.deepStrictEqual(
87	classifyModels(models, BUNDLED_MODEL_MANIFEST, CODEX).map((entry) => [	51	classifyModels(models, manifest, CODEX).map((entry) => [entry.slug, entry.isLegacy ?? false]),
88	entry.slug,
89	entry.isLegacy ?? false,
90	]),
91	[	52	[
92	["gpt-5.6-sol", false],	53	["current-a", false],
93	["gpt-5.6-luna", false],	54	["current-b", false],
94	["gpt-5.4", true],	55	["old-model", true],
95	["my-own-model", false],	56	["my-own-model", false],
96	],	57	],
97	);	58	);
98	});	59	});
99	});	60	});
100		61
		62	describe("resolveProviderCatalog", () => {
		63	it("resolves generic model presentation through a reusable profile", () => {
		64	const manifest: ModelManifestData = {
		65	version: 1,
		66	currentModels: {},
		67	providers: {
		68	synthetic: {
		69	defaults: { chat: "model-next" },
		70	profiles: {
		71	standard: {
		72	capabilities: {
		73	optionDescriptors: [
		74	{
		75	id: "mode",
		76	label: "Mode",
		77	type: "select",
		78	options: [{ id: "fast", label: "Fast", isDefault: true }],
		79	},
		80	],
		81	},
		82	adapter: { opaque: true },
		83	},
		84	},
		85	models: [
		86	{
		87	slug: "model-next",
		88	name: "Model Next",
		89	aliases: ["next"],
		90	status: "current",
		91	badge: "new",
		92	profile: "standard",
		93	},
		94	],
		95	},
		96	},
		97	};
		98
		99	const catalog = resolveProviderCatalog(manifest, ProviderDriverKind.make("synthetic"));
		100	assert.deepStrictEqual(catalog?.models[0], {
		101	model: {
		102	slug: "model-next",
		103	name: "Model Next",
		104	aliases: ["next"],
		105	badge: "new",
		106	isCustom: false,
		107	isDefault: true,
		108	capabilities: manifest.providers!.synthetic!.profiles.standard!.capabilities!,
		109	},
		110	adapter: undefined,
		111	profileAdapter: { opaque: true },
		112	});
		113	});
		114
		115	it("rejects invalid catalog references", () => {
		116	const invalidCatalog = (input: {
		117	readonly models: NonNullable<ModelManifestData["providers"]>[string]["models"];
		118	readonly defaultChat?: string;
		119	}): ModelManifestData => ({
		120	version: 1,
		121	currentModels: {},
		122	providers: {
		123	synthetic: {
		124	...(input.defaultChat ? { defaults: { chat: input.defaultChat } } : {}),
		125	profiles: {},
		126	models: input.models,
		127	},
		128	},
		129	});
		130
		131	for (const invalid of [
		132	invalidCatalog({
		133	models: [
		134	{ slug: "duplicate", name: "First", status: "current" },
		135	{ slug: "duplicate", name: "Second", status: "current" },
		136	],
		137	}),
		138	invalidCatalog({
		139	models: [
		140	{
		141	slug: "missing-profile",
		142	name: "Missing Profile",
		143	status: "current",
		144	profile: "missing",
		145	},
		146	],
		147	}),
		148	invalidCatalog({
		149	models: [{ slug: "present", name: "Present", status: "current" }],
		150	defaultChat: "absent",
		151	}),
		152	]) {
		153	assert.isNull(resolveProviderCatalog(invalid, ProviderDriverKind.make("synthetic")));
		154	}
		155	});
		156	});
		157
101	const REMOTE_MANIFEST: ModelManifestData = {	158	const REMOTE_MANIFEST: ModelManifestData = {
102	version: 1,	159	version: 1,
103	currentModels: {	160	currentModels: {
104	codex: ["gpt-5.4"],	161	codex: ["remote-model"],
105	claudeAgent: ["claude-fable-5"],	162	claudeAgent: ["remote-agent-model"],
106	},	163	},
107	};	164	};
108		165
		166	const REMOTE_CLAUDE_MANIFEST: ModelManifestData = {
		167	version: 1,
		168	currentModels: {},
		169	providers: {
		170	claudeAgent: {
		171	profiles: {
		172	synthetic: {
		173	adapter: { claudeCode: { effortMap: { extreme: "high" } } },
		174	},
		175	},
		176	models: [
		177	{
		178	slug: "remote-only-model",
		179	name: "Remote Only Model",
		180	status: "current",
		181	profile: "synthetic",
		182	},
		183	],
		184	},
		185	},
		186	};
		187
		188	const remoteClaudeManifestWithCompatibility = (compatibility: unknown): ModelManifestData => ({
		189	...REMOTE_CLAUDE_MANIFEST,
		190	providers: {
		191	claudeAgent: {
		192	profiles: REMOTE_CLAUDE_MANIFEST.providers!.claudeAgent!.profiles,
		193	models: REMOTE_CLAUDE_MANIFEST.providers!.claudeAgent!.models.map((model) => ({
		194	...model,
		195	adapter: { claudeCode: compatibility },
		196	})),
		197	},
		198	},
		199	});
		200
		201	const INVALID_REMOTE_MANIFESTS: ReadonlyArray<ModelManifestData> = [
		202	{
		203	...REMOTE_CLAUDE_MANIFEST,
		204	providers: {
		205	claudeAgent: {
		206	profiles: {
		207	synthetic: {
		208	adapter: { claudeCode: { effortMap: { extreme: 123 } } },
		209	},
		210	},
		211	models: REMOTE_CLAUDE_MANIFEST.providers!.claudeAgent!.models,
		212	},
		213	},
		214	},
		215	{
		216	...REMOTE_CLAUDE_MANIFEST,
		217	providers: {
		218	claudeAgent: {
		219	profiles: {},
		220	models: REMOTE_CLAUDE_MANIFEST.providers!.claudeAgent!.models,
		221	},
		222	},
		223	},
		224	{
		225	...REMOTE_CLAUDE_MANIFEST,
		226	providers: {
		227	claudeAgent: {
		228	profiles: REMOTE_CLAUDE_MANIFEST.providers!.claudeAgent!.profiles,
		229	models: [
		230	...REMOTE_CLAUDE_MANIFEST.providers!.claudeAgent!.models,
		231	{
		232	slug: "remote-only-model",
		233	name: "Duplicate Remote Model",
		234	status: "current",
		235	profile: "synthetic",
		236	},
		237	],
		238	},
		239	},
		240	},
		241	{
		242	...REMOTE_CLAUDE_MANIFEST,
		243	providers: {
		244	claudeAgent: {
		245	defaults: { chat: "absent-model" },
		246	profiles: REMOTE_CLAUDE_MANIFEST.providers!.claudeAgent!.profiles,
		247	models: REMOTE_CLAUDE_MANIFEST.providers!.claudeAgent!.models,
		248	},
		249	},
		250	},
		251	remoteClaudeManifestWithCompatibility({ minVersion: "2.x" }),
		252	remoteClaudeManifestWithCompatibility({ maxVersionExclusive: "2.x" }),
		253	remoteClaudeManifestWithCompatibility({
		254	minVersion: "2.2",
		255	maxVersionExclusive: "2.1",
		256	}),
		257	];
		258
109	const httpClientLayer = (handler: () => Response) =>	259	const httpClientLayer = (handler: () => Response) =>
110	Layer.succeed(	260	Layer.succeed(
111	HttpClient.HttpClient,	261	HttpClient.HttpClient,
...	@@ -129,8 +279,6 @@ describe("ModelManifest service", () => {	...	@@ -129,8 +279,6 @@ describe("ModelManifest service", () => {
129	const service = yield* make;	279	const service = yield* make;
130	const refreshed = yield* service.refresh;	280	const refreshed = yield* service.refresh;
131	assert.deepStrictEqual(refreshed, REMOTE_MANIFEST);	281	assert.deepStrictEqual(refreshed, REMOTE_MANIFEST);
132	assert.isTrue(isLegacyModel(refreshed, CODEX, "gpt-5.6-sol"));
133	assert.isFalse(isLegacyModel(refreshed, CODEX, "gpt-5.4"));
134		282
135	// A fresh service instance sees the disk cache without another fetch:	283	// A fresh service instance sees the disk cache without another fetch:
136	// its HTTP layer is still stubbed, but `current` never fetches at all.	284	// its HTTP layer is still stubbed, but `current` never fetches at all.
...	@@ -162,6 +310,33 @@ describe("ModelManifest service", () => {	...	@@ -162,6 +310,33 @@ describe("ModelManifest service", () => {
162	),	310	),
163	);	311	);
164		312
		313	it.effect("preserves the last-good remote cache when later payloads are invalid", () => {
		314	let responseIndex = 0;
		315	const responses = [REMOTE_CLAUDE_MANIFEST, ...INVALID_REMOTE_MANIFESTS];
		316
		317	return Effect.gen(function* () {
		318	const service = yield* make;
		319	assert.deepStrictEqual(yield* service.refresh, REMOTE_CLAUDE_MANIFEST);
		320
		321	for (const _invalid of INVALID_REMOTE_MANIFESTS) {
		322	yield* TestClock.adjust("1 hour");
		323	responseIndex += 1;
		324	assert.deepStrictEqual(yield* service.refresh, REMOTE_CLAUDE_MANIFEST);
		325	}
		326
		327	const rebooted = yield* make;
		328	assert.deepStrictEqual(yield* rebooted.current, REMOTE_CLAUDE_MANIFEST);
		329	}).pipe(
		330	Effect.scoped,
		331	Effect.provide(
		332	serviceLayers({
		333	prefix: "model-manifest-last-good-test",
		334	response: () => Response.json(responses[responseIndex]),
		335	}),
		336	),
		337	);
		338	});
		339
165	it.live("does not fetch when provider update checks are disabled", () =>	340	it.live("does not fetch when provider update checks are disabled", () =>
166	Effect.gen(function* () {	341	Effect.gen(function* () {
167	let fetchCount = 0;	342	let fetchCount = 0;

apps/server/src/provider/ModelManifest.ts+139-18

...	@@ -1,20 +1,24 @@	...	@@ -1,20 +1,24 @@
1	/**	1	/**
2	* ModelManifest — decides which provider models are current and which belong	2	* ModelManifest — remote provider-model metadata with a bundled offline
3	* in the model picker's legacy section.	3	* fallback.
4	*	4	*
5	* The classification data (current slugs per driver kind) lives in	5	* Provider catalogs and legacy classification live in `model-manifest.json`.
6	* `model-manifest.json` next to this file. The bundled copy ships with every	6	* The bundled copy ships with every release; at runtime the service refreshes
7	* release. At runtime the service refreshes it from the same file on `main`	7	* it from the same file on `main`. Preference order is remote, then the last
8	* via raw.githubusercontent.com, so a new model can leave the legacy section	8	* successful on-disk copy, then the bundle. A failed fetch never fails a
9	* with a commit to `main` instead of a release. Preference order is remote,	9	* provider check.
10	* then the on-disk copy of the last successful fetch, then the bundle. A
11	* failed fetch never fails a provider check.
12	*	10	*
13	* Drivers apply the manifest to snapshot drafts with `applyModelManifest`	11	* Providers with authoritative discovery can use only the classification
14	* before publishing, so every path that produces models (pending, probe,	12	* overlay. Providers with static catalogs can resolve presentation and
15	* error fallbacks) is classified the same way.	13	* capabilities from `providers`, then decode their own allowlisted adapter
		14	* payload separately.
16	*/	15	*/
17	import type { ProviderDriverKind, ServerProviderModel } from "@t3tools/contracts";	16	import {
		17	ModelCapabilities,
		18	TrimmedNonEmptyString,
		19	type ProviderDriverKind,
		20	type ServerProviderModel,
		21	} from "@t3tools/contracts";
18	import * as Clock from "effect/Clock";	22	import * as Clock from "effect/Clock";
19	import * as Context from "effect/Context";	23	import * as Context from "effect/Context";
20	import * as Effect from "effect/Effect";	24	import * as Effect from "effect/Effect";
...	@@ -27,6 +31,7 @@ import { HttpClient, HttpClientResponse } from "effect/unstable/http";	...	@@ -27,6 +31,7 @@ import { HttpClient, HttpClientResponse } from "effect/unstable/http";
27		31
28	import { ServerConfig } from "../config.ts";	32	import { ServerConfig } from "../config.ts";
29	import * as ServerSettings from "../serverSettings.ts";	33	import * as ServerSettings from "../serverSettings.ts";
		34	import { hasValidClaudeManifestAdapters } from "./ClaudeModelManifest.ts";
30	import bundledManifestJson from "./model-manifest.json" with { type: "json" };	35	import bundledManifestJson from "./model-manifest.json" with { type: "json" };
31	import type { ServerProviderDraft } from "./providerSnapshot.ts";	36	import type { ServerProviderDraft } from "./providerSnapshot.ts";
32		37
...	@@ -42,23 +47,135 @@ const MANIFEST_RETRY_MS = 5 * 60 * 1000;	...	@@ -42,23 +47,135 @@ const MANIFEST_RETRY_MS = 5 * 60 * 1000;
42		47
43	const FETCH_TIMEOUT_MS = 10_000;	48	const FETCH_TIMEOUT_MS = 10_000;
44		49
		50	const ManifestModelStatus = Schema.Literals(["current", "legacy"]);
		51
		52	const ManifestModelProfile = Schema.Struct({
		53	capabilities: Schema.optional(ModelCapabilities),
		54	adapter: Schema.optional(Schema.Unknown),
		55	});
		56
		57	const ManifestProviderModel = Schema.Struct({
		58	slug: TrimmedNonEmptyString,
		59	name: TrimmedNonEmptyString,
		60	shortName: Schema.optional(TrimmedNonEmptyString),
		61	subProvider: Schema.optional(TrimmedNonEmptyString),
		62	aliases: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
		63	status: ManifestModelStatus,
		64	badge: Schema.optional(Schema.Literal("new")),
		65	profile: Schema.optional(TrimmedNonEmptyString),
		66	adapter: Schema.optional(Schema.Unknown),
		67	});
		68
		69	const ManifestProviderCatalog = Schema.Struct({
		70	defaults: Schema.optional(
		71	Schema.Struct({
		72	chat: Schema.optional(TrimmedNonEmptyString),
		73	}),
		74	),
		75	profiles: Schema.Record(Schema.String, ManifestModelProfile),
		76	models: Schema.Array(ManifestProviderModel),
		77	});
		78
45	/**	79	/**
46	* `version` gates breaking schema changes: a build only accepts remote	80	* `version` gates breaking schema changes. Provider catalogs are additive so
47	* manifests whose version it understands, and keeps its bundled copy	81	* clients that only understand `currentModels` keep accepting this v1 file.
48	* otherwise. `currentModels` is keyed by driver kind; kinds absent from the
49	* map have no legacy concept and their models are left unflagged.
50	*/	82	*/
51	const ModelManifestSchema = Schema.Struct({	83	const ModelManifestEnvelopeSchema = Schema.Struct({
52	version: Schema.Literal(1),	84	version: Schema.Literal(1),
53	currentModels: Schema.Record(Schema.String, Schema.Array(Schema.String)),	85	currentModels: Schema.Record(Schema.String, Schema.Array(Schema.String)),
		86	providers: Schema.optional(Schema.Record(Schema.String, ManifestProviderCatalog)),
54	});	87	});
		88
		89	const hasValidProviderCatalogReferences = (
		90	manifest: typeof ModelManifestEnvelopeSchema.Type,
		91	): boolean =>
		92	Object.values(manifest.providers ?? {}).every((catalog) => {
		93	const slugs = new Set<string>();
		94	const modelsAreValid = catalog.models.every((model) => {
		95	if (slugs.has(model.slug)) return false;
		96	slugs.add(model.slug);
		97	return model.profile === undefined \|\| catalog.profiles[model.profile] !== undefined;
		98	});
		99	return (
		100	modelsAreValid && (catalog.defaults?.chat === undefined \|\| slugs.has(catalog.defaults.chat))
		101	);
		102	});
		103
		104	const ModelManifestSchema = ModelManifestEnvelopeSchema.pipe(
		105	Schema.check(
		106	Schema.makeFilter(hasValidProviderCatalogReferences, {
		107	expected: "unique model slugs and existing model and profile references",
		108	}),
		109	Schema.makeFilter(hasValidClaudeManifestAdapters, {
		110	expected: "valid Claude adapter metadata",
		111	}),
		112	),
		113	);
55	export type ModelManifestData = typeof ModelManifestSchema.Type;	114	export type ModelManifestData = typeof ModelManifestSchema.Type;
56		115
		116	export interface ResolvedManifestModel {
		117	readonly model: ServerProviderModel;
		118	readonly adapter: unknown;
		119	readonly profileAdapter: unknown;
		120	}
		121
		122	export interface ResolvedProviderCatalog {
		123	readonly models: ReadonlyArray<ResolvedManifestModel>;
		124	readonly defaults: {
		125	readonly chat: string \| undefined;
		126	};
		127	}
		128
57	const decodeManifest = Schema.decodeUnknownEffect(ModelManifestSchema);	129	const decodeManifest = Schema.decodeUnknownEffect(ModelManifestSchema);
58		130
59	export const BUNDLED_MODEL_MANIFEST: ModelManifestData =	131	export const BUNDLED_MODEL_MANIFEST: ModelManifestData =
60	Schema.decodeUnknownSync(ModelManifestSchema)(bundledManifestJson);	132	Schema.decodeUnknownSync(ModelManifestSchema)(bundledManifestJson);
61		133
		134	/** Resolve provider-neutral model presentation and capability data. */
		135	export function resolveProviderCatalog(
		136	manifest: ModelManifestData,
		137	driverKind: ProviderDriverKind,
		138	): ResolvedProviderCatalog \| null {
		139	const catalog = manifest.providers?.[driverKind];
		140	if (!catalog) return null;
		141
		142	const seen = new Set<string>();
		143	const models: Array<ResolvedManifestModel> = [];
		144	for (const entry of catalog.models) {
		145	if (seen.has(entry.slug)) return null;
		146	seen.add(entry.slug);
		147
		148	const profile = entry.profile ? catalog.profiles[entry.profile] : undefined;
		149	if (entry.profile && !profile) return null;
		150
		151	models.push({
		152	model: {
		153	slug: entry.slug,
		154	name: entry.name,
		155	...(entry.shortName ? { shortName: entry.shortName } : {}),
		156	...(entry.subProvider ? { subProvider: entry.subProvider } : {}),
		157	...(entry.aliases ? { aliases: entry.aliases } : {}),
		158	...(entry.badge ? { badge: entry.badge } : {}),
		159	isCustom: false,
		160	...(catalog.defaults?.chat === entry.slug ? { isDefault: true } : {}),
		161	...(entry.status === "legacy" ? { isLegacy: true } : {}),
		162	capabilities: profile?.capabilities ?? null,
		163	},
		164	adapter: entry.adapter,
		165	profileAdapter: profile?.adapter,
		166	});
		167	}
		168
		169	if (catalog.defaults?.chat !== undefined && !seen.has(catalog.defaults.chat)) return null;
		170
		171	return {
		172	models,
		173	defaults: {
		174	chat: catalog.defaults?.chat,
		175	},
		176	};
		177	}
		178
62	/** On-disk shape of the last successfully fetched manifest. */	179	/** On-disk shape of the last successfully fetched manifest. */
63	const ManifestCacheFile = Schema.Struct({	180	const ManifestCacheFile = Schema.Struct({
64	fetchedAtMs: Schema.Number,	181	fetchedAtMs: Schema.Number,
...	@@ -81,6 +198,10 @@ export function isLegacyModel(	...	@@ -81,6 +198,10 @@ export function isLegacyModel(
81	driverKind: ProviderDriverKind,	198	driverKind: ProviderDriverKind,
82	slug: string,	199	slug: string,
83	): boolean {	200	): boolean {
		201	const catalogModel = manifest.providers?.[driverKind]?.models.find(
		202	(model) => model.slug === slug,
		203	);
		204	if (catalogModel) return catalogModel.status === "legacy";
84	const currentModels = manifest.currentModels[driverKind];	205	const currentModels = manifest.currentModels[driverKind];
85	if (!currentModels) return false;	206	if (!currentModels) return false;
86	return !currentModels.includes(slug);	207	return !currentModels.includes(slug);

apps/server/src/provider/model-manifest.json+359

...	@@ -9,5 +9,364 @@	...	@@ -9,5 +9,364 @@
9	"gpt-daybreak-red-latest"	9	"gpt-daybreak-red-latest"
10	],	10	],
11	"claudeAgent": ["claude-fable-5-1", "claude-opus-5", "claude-sonnet-5"]	11	"claudeAgent": ["claude-fable-5-1", "claude-opus-5", "claude-sonnet-5"]
		12	},
		13	"providers": {
		14	"claudeAgent": {
		15	"defaults": {
		16	"chat": "claude-sonnet-5"
		17	},
		18	"profiles": {
		19	"fable-5": {
		20	"capabilities": {
		21	"optionDescriptors": [
		22	{
		23	"id": "effort",
		24	"label": "Reasoning",
		25	"type": "select",
		26	"options": [
		27	{ "id": "low", "label": "Low" },
		28	{ "id": "medium", "label": "Medium" },
		29	{ "id": "high", "label": "High", "isDefault": true },
		30	{ "id": "xhigh", "label": "Extra High" },
		31	{ "id": "max", "label": "Max" },
		32	{
		33	"id": "ultracode",
		34	"label": "Ultracode",
		35	"description": "xhigh effort plus multi-agent workflow orchestration"
		36	},
		37	{ "id": "ultrathink", "label": "Ultrathink" }
		38	],
		39	"promptInjectedValues": ["ultrathink"]
		40	},
		41	{
		42	"id": "contextWindow",
		43	"label": "Context Window",
		44	"type": "select",
		45	"options": [
		46	{ "id": "200k", "label": "200k" },
		47	{ "id": "1m", "label": "1M", "isDefault": true }
		48	]
		49	}
		50	]
		51	},
		52	"adapter": {
		53	"claudeCode": {
		54	"effortMap": { "ultracode": "xhigh", "ultrathink": null },
		55	"modelSuffixes": { "contextWindow": { "1m": "[1m]" } },
		56	"contextWindowTokens": { "200k": 200000, "1m": 1000000 }
		57	}
		58	}
		59	},
		60	"opus-5": {
		61	"capabilities": {
		62	"optionDescriptors": [
		63	{
		64	"id": "effort",
		65	"label": "Reasoning",
		66	"type": "select",
		67	"options": [
		68	{ "id": "low", "label": "Low" },
		69	{ "id": "medium", "label": "Medium" },
		70	{ "id": "high", "label": "High", "isDefault": true },
		71	{ "id": "xhigh", "label": "Extra High" },
		72	{ "id": "max", "label": "Max" },
		73	{
		74	"id": "ultracode",
		75	"label": "Ultracode",
		76	"description": "xhigh effort plus multi-agent workflow orchestration"
		77	},
		78	{ "id": "ultrathink", "label": "Ultrathink" }
		79	],
		80	"promptInjectedValues": ["ultrathink"]
		81	},
		82	{ "id": "fastMode", "label": "Fast Mode", "type": "boolean" },
		83	{
		84	"id": "contextWindow",
		85	"label": "Context Window",
		86	"type": "select",
		87	"options": [
		88	{ "id": "200k", "label": "200k" },
		89	{ "id": "1m", "label": "1M", "isDefault": true }
		90	]
		91	}
		92	]
		93	},
		94	"adapter": {
		95	"claudeCode": {
		96	"effortMap": { "ultracode": "xhigh", "ultrathink": null },
		97	"modelSuffixes": { "contextWindow": { "1m": "[1m]" } },
		98	"contextWindowTokens": { "200k": 200000, "1m": 1000000 }
		99	}
		100	}
		101	},
		102	"opus-4-8": {
		103	"capabilities": {
		104	"optionDescriptors": [
		105	{
		106	"id": "effort",
		107	"label": "Reasoning",
		108	"type": "select",
		109	"options": [
		110	{ "id": "low", "label": "Low" },
		111	{ "id": "medium", "label": "Medium" },
		112	{ "id": "high", "label": "High", "isDefault": true },
		113	{ "id": "xhigh", "label": "Extra High" },
		114	{ "id": "max", "label": "Max" },
		115	{
		116	"id": "ultracode",
		117	"label": "Ultracode",
		118	"description": "xhigh effort plus multi-agent workflow orchestration"
		119	},
		120	{ "id": "ultrathink", "label": "Ultrathink" }
		121	],
		122	"promptInjectedValues": ["ultrathink"]
		123	},
		124	{ "id": "fastMode", "label": "Fast Mode", "type": "boolean" }
		125	]
		126	},
		127	"adapter": {
		128	"claudeCode": {
		129	"effortMap": { "ultracode": "xhigh", "ultrathink": null },
		130	"fixedContextWindowTokens": 1000000
		131	}
		132	}
		133	},
		134	"opus-4-7": {
		135	"capabilities": {
		136	"optionDescriptors": [
		137	{
		138	"id": "effort",
		139	"label": "Reasoning",
		140	"type": "select",
		141	"options": [
		142	{ "id": "low", "label": "Low" },
		143	{ "id": "medium", "label": "Medium" },
		144	{ "id": "high", "label": "High" },
		145	{ "id": "xhigh", "label": "Extra High", "isDefault": true },
		146	{ "id": "max", "label": "Max" },
		147	{ "id": "ultrathink", "label": "Ultrathink" }
		148	],
		149	"promptInjectedValues": ["ultrathink"]
		150	},
		151	{ "id": "fastMode", "label": "Fast Mode", "type": "boolean" }
		152	]
		153	},
		154	"adapter": {
		155	"claudeCode": {
		156	"effortMap": { "xhigh": "max", "ultrathink": null },
		157	"fixedContextWindowTokens": 1000000
		158	}
		159	}
		160	},
		161	"opus-4-6": {
		162	"capabilities": {
		163	"optionDescriptors": [
		164	{
		165	"id": "effort",
		166	"label": "Reasoning",
		167	"type": "select",
		168	"options": [
		169	{ "id": "low", "label": "Low" },
		170	{ "id": "medium", "label": "Medium" },
		171	{ "id": "high", "label": "High", "isDefault": true },
		172	{ "id": "max", "label": "Max" },
		173	{ "id": "ultrathink", "label": "Ultrathink" }
		174	],
		175	"promptInjectedValues": ["ultrathink"]
		176	},
		177	{ "id": "fastMode", "label": "Fast Mode", "type": "boolean" },
		178	{
		179	"id": "contextWindow",
		180	"label": "Context Window",
		181	"type": "select",
		182	"options": [
		183	{ "id": "200k", "label": "200k" },
		184	{ "id": "1m", "label": "1M", "isDefault": true }
		185	]
		186	}
		187	]
		188	},
		189	"adapter": {
		190	"claudeCode": {
		191	"effortMap": { "ultrathink": null },
		192	"modelSuffixes": { "contextWindow": { "1m": "[1m]" } },
		193	"contextWindowTokens": { "200k": 200000, "1m": 1000000 }
		194	}
		195	}
		196	},
		197	"opus-4-5": {
		198	"capabilities": {
		199	"optionDescriptors": [
		200	{
		201	"id": "effort",
		202	"label": "Reasoning",
		203	"type": "select",
		204	"options": [
		205	{ "id": "low", "label": "Low" },
		206	{ "id": "medium", "label": "Medium" },
		207	{ "id": "high", "label": "High", "isDefault": true },
		208	{ "id": "max", "label": "Max" }
		209	]
		210	},
		211	{ "id": "fastMode", "label": "Fast Mode", "type": "boolean" }
		212	]
		213	},
		214	"adapter": { "claudeCode": {} }
		215	},
		216	"sonnet-5": {
		217	"capabilities": {
		218	"optionDescriptors": [
		219	{
		220	"id": "effort",
		221	"label": "Reasoning",
		222	"type": "select",
		223	"options": [
		224	{ "id": "low", "label": "Low" },
		225	{ "id": "medium", "label": "Medium" },
		226	{ "id": "high", "label": "High", "isDefault": true },
		227	{ "id": "xhigh", "label": "Extra High" },
		228	{ "id": "max", "label": "Max" },
		229	{ "id": "ultrathink", "label": "Ultrathink" }
		230	],
		231	"promptInjectedValues": ["ultrathink"]
		232	},
		233	{
		234	"id": "contextWindow",
		235	"label": "Context Window",
		236	"type": "select",
		237	"options": [
		238	{ "id": "200k", "label": "200k", "isDefault": true },
		239	{ "id": "1m", "label": "1M" }
		240	]
		241	}
		242	]
		243	},
		244	"adapter": {
		245	"claudeCode": {
		246	"effortMap": { "ultrathink": null },
		247	"modelSuffixes": { "contextWindow": { "1m": "[1m]" } },
		248	"contextWindowTokens": { "200k": 200000, "1m": 1000000 }
		249	}
		250	}
		251	},
		252	"sonnet-4-6": {
		253	"capabilities": {
		254	"optionDescriptors": [
		255	{
		256	"id": "effort",
		257	"label": "Reasoning",
		258	"type": "select",
		259	"options": [
		260	{ "id": "low", "label": "Low" },
		261	{ "id": "medium", "label": "Medium" },
		262	{ "id": "high", "label": "High", "isDefault": true },
		263	{ "id": "max", "label": "Max" },
		264	{ "id": "ultrathink", "label": "Ultrathink" }
		265	],
		266	"promptInjectedValues": ["ultrathink"]
		267	},
		268	{
		269	"id": "contextWindow",
		270	"label": "Context Window",
		271	"type": "select",
		272	"options": [
		273	{ "id": "200k", "label": "200k", "isDefault": true },
		274	{ "id": "1m", "label": "1M" }
		275	]
		276	}
		277	]
		278	},
		279	"adapter": {
		280	"claudeCode": {
		281	"effortMap": { "max": "high", "ultrathink": null },
		282	"modelSuffixes": { "contextWindow": { "1m": "[1m]" } },
		283	"contextWindowTokens": { "200k": 200000, "1m": 1000000 }
		284	}
		285	}
		286	},
		287	"haiku-4-5": {
		288	"capabilities": {
		289	"optionDescriptors": [{ "id": "thinking", "label": "Thinking", "type": "boolean" }]
		290	},
		291	"adapter": { "claudeCode": {} }
		292	}
		293	},
		294	"models": [
		295	{
		296	"slug": "claude-fable-5-1",
		297	"name": "Claude Fable 5.1",
		298	"aliases": ["fable", "fable-5.1", "claude-fable-5.1"],
		299	"status": "current",
		300	"badge": "new",
		301	"profile": "fable-5",
		302	"adapter": { "claudeCode": { "minVersion": "2.1.257" } }
		303	},
		304	{
		305	"slug": "claude-fable-5",
		306	"name": "Claude Fable 5",
		307	"status": "legacy",
		308	"profile": "fable-5",
		309	"adapter": { "claudeCode": { "minVersion": "2.1.169" } }
		310	},
		311	{
		312	"slug": "claude-opus-5",
		313	"name": "Claude Opus 5",
		314	"aliases": ["opus", "opus-5", "claude-opus-5.0", "claude-opus-5-0"],
		315	"status": "current",
		316	"profile": "opus-5",
		317	"adapter": { "claudeCode": { "minVersion": "2.1.219" } }
		318	},
		319	{
		320	"slug": "claude-opus-4-8",
		321	"name": "Claude Opus 4.8",
		322	"aliases": ["opus-4.8", "claude-opus-4.8"],
		323	"status": "legacy",
		324	"profile": "opus-4-8",
		325	"adapter": { "claudeCode": { "minVersion": "2.1.154" } }
		326	},
		327	{
		328	"slug": "claude-opus-4-7",
		329	"name": "Claude Opus 4.7",
		330	"aliases": ["opus-4.7", "claude-opus-4.7"],
		331	"status": "legacy",
		332	"profile": "opus-4-7",
		333	"adapter": { "claudeCode": { "minVersion": "2.1.111" } }
		334	},
		335	{
		336	"slug": "claude-opus-4-6",
		337	"name": "Claude Opus 4.6",
		338	"aliases": ["opus-4.6", "claude-opus-4.6", "claude-opus-4-6-20251117"],
		339	"status": "legacy",
		340	"profile": "opus-4-6"
		341	},
		342	{
		343	"slug": "claude-opus-4-5",
		344	"name": "Claude Opus 4.5",
		345	"status": "legacy",
		346	"profile": "opus-4-5"
		347	},
		348	{
		349	"slug": "claude-sonnet-5",
		350	"name": "Claude Sonnet 5",
		351	"aliases": ["sonnet", "sonnet-5", "claude-sonnet-5.0", "claude-sonnet-5-0"],
		352	"status": "current",
		353	"profile": "sonnet-5"
		354	},
		355	{
		356	"slug": "claude-sonnet-4-6",
		357	"name": "Claude Sonnet 4.6",
		358	"aliases": ["sonnet-4.6", "claude-sonnet-4.6", "claude-sonnet-4-6-20251117"],
		359	"status": "legacy",
		360	"profile": "sonnet-4-6"
		361	},
		362	{
		363	"slug": "claude-haiku-4-5",
		364	"name": "Claude Haiku 4.5",
		365	"aliases": ["haiku", "haiku-4.5", "claude-haiku-4.5", "claude-haiku-4-5-20251001"],
		366	"status": "legacy",
		367	"profile": "haiku-4-5"
		368	}
		369	]
		370	}
12	}	371	}
13	}	372	}

apps/server/src/textGeneration/ClaudeTextGeneration.test.ts+79-20

 @@ -11,6 +11,13 @@ import * as Schema from "effect/Schema";
 import { expect } from "vite-plus/test";
 import * as ServerConfig from "../config.ts";
+import {
+  SYNTHETIC_CLAUDE_CAPABLE_MODEL,
+  SYNTHETIC_CLAUDE_COLLIDING_ALIAS,
+  SYNTHETIC_CLAUDE_MODEL_CATALOG,
+  SYNTHETIC_CLAUDE_STANDARD_MODEL,
+  SYNTHETIC_CLAUDE_THINKING_MODEL,
+} from "../provider/ClaudeModelCatalog.testFixtures.ts";
 import * as TextGeneration from "./TextGeneration.ts";
 import { sanitizeThreadTitle } from "./TextGenerationUtils.ts";
 import { makeClaudeTextGeneration } from "./ClaudeTextGeneration.ts";
 @@ -219,13 +226,17 @@ function withFakeClaudeEnv<A, E, R>(
     );
     const config = decodeClaudeSettings(input.claudeConfig ?? {});
-    const textGeneration = yield* makeClaudeTextGeneration(config);
+    const textGeneration = yield* makeClaudeTextGeneration(
+      config,
+      undefined,
+      Effect.succeed(SYNTHETIC_CLAUDE_MODEL_CATALOG),
+    );
     return yield* effectFn(textGeneration);
   }).pipe(Effect.scoped);
 }
 it.layer(ClaudeTextGenerationTestLayer)("ClaudeTextGeneration", (it) => {
-  it.effect("forwards Claude thinking settings for Haiku without passing effort", () =>
+  it.effect("forwards Claude thinking settings without passing unsupported effort", () =>
     withFakeClaudeEnv(
       {
         output: JSON.stringify({
 @@ -245,10 +256,14 @@ it.layer(ClaudeTextGenerationTestLayer)("ClaudeTextGeneration", (it) => {
             stagedSummary: "M README.md",
             stagedPatch: "diff --git a/README.md b/README.md",
             modelSelection: {
-              ...createModelSelection(ProviderInstanceId.make("claudeAgent"), "claude-haiku-4-5", [
+              ...createModelSelection(
-                { id: "thinking", value: false },
+                ProviderInstanceId.make("claudeAgent"),
-                { id: "effort", value: "high" },
+                SYNTHETIC_CLAUDE_THINKING_MODEL,
-              ]),
+                [
+                  { id: "thinking", value: false },
+                  { id: "effort", value: "high" },
+                ],
+              ),
             },
           });
 @@ -257,39 +272,83 @@ it.layer(ClaudeTextGenerationTestLayer)("ClaudeTextGeneration", (it) => {
     ),
   );
-  it.effect("forwards Claude fast mode and supported effort", () =>
+  it.effect("keeps a configured custom alias opaque to the Claude CLI", () =>
     withFakeClaudeEnv(
       {
         output: JSON.stringify({
           structured_output: {
-            title: "Improve orchestration flow",
+            title: "Keep custom model",
-            body: "Body",
+            body: "",
           },
         }),
-        argsMustContain: '--effort max --settings {"fastMode":true}',
+        argsMustContain: `--model ${SYNTHETIC_CLAUDE_COLLIDING_ALIAS} --dangerously-skip-permissions`,
+        claudeConfig: { customModels: [SYNTHETIC_CLAUDE_COLLIDING_ALIAS] },
       },
       (textGeneration) =>
         Effect.gen(function* () {
           const generated = yield* textGeneration.generatePrContent({
             cwd: process.cwd(),
             baseBranch: "main",
-            headBranch: "feature/claude-effect",
+            headBranch: "feature/custom-model",
-            commitSummary: "Improve orchestration",
+            commitSummary: "Keep custom model",
             diffSummary: "1 file changed",
             diffPatch: "diff --git a/README.md b/README.md",
-            modelSelection: {
+            modelSelection: createModelSelection(
-              ...createModelSelection(ProviderInstanceId.make("claudeAgent"), "claude-opus-4-6", [
+              ProviderInstanceId.make("claudeAgent"),
+              SYNTHETIC_CLAUDE_COLLIDING_ALIAS,
+              [
                 { id: "effort", value: "max" },
                 { id: "fastMode", value: true },
-              ]),
+                { id: "contextWindow", value: "expanded" },
-            },
+              ],
+            ),
           });
-          expect(generated.title).toBe("Improve orchestration flow");
+          expect(generated.title).toBe("Keep custom model");
         }),
     ),
   );
+  it.effect(
+    "keeps canonical built-in capabilities when a custom model collides with its alias",
+    () =>
+      withFakeClaudeEnv(
+        {
+          output: JSON.stringify({
+            structured_output: {
+              title: "Improve orchestration flow",
+              body: "Body",
+            },
+          }),
+          argsMustContain: `--model ${SYNTHETIC_CLAUDE_CAPABLE_MODEL}[expanded] --effort max --settings {"fastMode":true} --dangerously-skip-permissions`,
+          claudeConfig: { customModels: [SYNTHETIC_CLAUDE_COLLIDING_ALIAS] },
+        },
+        (textGeneration) =>
+          Effect.gen(function* () {
+            const generated = yield* textGeneration.generatePrContent({
+              cwd: process.cwd(),
+              baseBranch: "main",
+              headBranch: "feature/claude-effect",
+              commitSummary: "Improve orchestration",
+              diffSummary: "1 file changed",
+              diffPatch: "diff --git a/README.md b/README.md",
+              modelSelection: {
+                ...createModelSelection(
+                  ProviderInstanceId.make("claudeAgent"),
+                  SYNTHETIC_CLAUDE_CAPABLE_MODEL,
+                  [
+                    { id: "effort", value: "max" },
+                    { id: "fastMode", value: true },
+                  ],
+                ),
+              },
+            });
+            expect(generated.title).toBe("Improve orchestration flow");
+          }),
+      ),
+  );
   it.effect("generates thread titles through the Claude provider", () =>
     withFakeClaudeEnv(
       {
 @@ -308,7 +367,7 @@ it.layer(ClaudeTextGenerationTestLayer)("ClaudeTextGeneration", (it) => {
             message: "Please investigate reconnect failures after restarting the session.",
             modelSelection: {
               instanceId: ProviderInstanceId.make("claudeAgent"),
-              model: "claude-sonnet-4-6",
+              model: SYNTHETIC_CLAUDE_STANDARD_MODEL,
             },
           });
 @@ -343,7 +402,7 @@ it.layer(ClaudeTextGenerationTestLayer)("ClaudeTextGeneration", (it) => {
               message: "thread title",
               modelSelection: {
                 instanceId: ProviderInstanceId.make("claudeAgent"),
-                model: "claude-sonnet-4-6",
+                model: SYNTHETIC_CLAUDE_STANDARD_MODEL,
               },
             });
 @@ -369,7 +428,7 @@ it.layer(ClaudeTextGenerationTestLayer)("ClaudeTextGeneration", (it) => {
             message: "Name this thread.",
             modelSelection: {
               instanceId: ProviderInstanceId.make("claudeAgent"),
-              model: "claude-sonnet-4-6",
+              model: SYNTHETIC_CLAUDE_STANDARD_MODEL,
             },
           });

apps/server/src/textGeneration/ClaudeTextGeneration.ts+34-13

 @@ -37,12 +37,16 @@ import {
   getProviderOptionDescriptors,
 } from "@t3tools/shared/model";
 import {
-  getClaudeModelCapabilities,
+  BUNDLED_CLAUDE_MODEL_CATALOG,
-  isClaudeUltracodeEffort,
+  type ClaudeModelCatalog,
-  normalizeClaudeCliEffort,
+  getClaudeCatalogModelCapabilities,
-  resolveClaudeApiModelId,
+  isClaudeCatalogUltracodeEffort,
-  resolveClaudeEffort,
+  normalizeClaudeCatalogEffort,
-} from "../provider/Layers/ClaudeProvider.ts";
+  resolveClaudeCatalogApiModelId,
+  resolveClaudeCatalogEffort,
+  resolveClaudeModelSlug,
+  scopeClaudeModelCatalog,
+} from "../provider/ClaudeModelCatalog.ts";
 import { makeClaudeEnvironment } from "../provider/Drivers/ClaudeHome.ts";
 const CLAUDE_TIMEOUT_MS = 180_000;
 @@ -61,9 +65,13 @@ const decodeClaudeOutputEnvelope = Schema.decodeEffect(Schema.fromJsonString(Cla
 export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(function* (
   claudeSettings: ClaudeSettings,
   environment?: NodeJS.ProcessEnv,
+  modelCatalog: Effect.Effect<ClaudeModelCatalog> = Effect.succeed(BUNDLED_CLAUDE_MODEL_CATALOG),
 ) {
   const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+  const scopedModelCatalog = modelCatalog.pipe(
+    Effect.map((catalog) => scopeClaudeModelCatalog(catalog, claudeSettings.customModels)),
+  );
   const readStreamAsString = <E>(
     operation: string,
 @@ -121,21 +129,34 @@ export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(fu
     outputSchemaJson: S;
     modelSelection: ModelSelection;
   }): Effect.fn.Return<S["Type"], TextGenerationError, S["DecodingServices"]> {
+    const catalog = yield* scopedModelCatalog;
+    const resolvedModelSelection = {
+      ...modelSelection,
+      model: resolveClaudeModelSlug(catalog, modelSelection.model),
+    };
     const jsonSchemaStr = yield* encodeJsonForOperation(
       operation,
       toJsonSchemaObject(outputSchemaJson),
       "Failed to encode structured output schema.",
     );
-    const caps = getClaudeModelCapabilities(modelSelection.model);
+    const caps = getClaudeCatalogModelCapabilities(catalog, resolvedModelSelection.model);
     const descriptors = getProviderOptionDescriptors({
       caps,
-      selections: modelSelection.options,
+      selections: resolvedModelSelection.options,
     });
     const findDescriptor = (id: string) => descriptors.find((descriptor) => descriptor.id === id);
-    const rawEffortSelection = getModelSelectionStringOptionValue(modelSelection, "effort");
+    const rawEffortSelection = getModelSelectionStringOptionValue(resolvedModelSelection, "effort");
-    const resolvedEffort = resolveClaudeEffort(caps, rawEffortSelection);
+    const resolvedEffort = resolveClaudeCatalogEffort(
-    const cliEffort = normalizeClaudeCliEffort(resolvedEffort, modelSelection.model);
+      catalog,
-    const ultracode = isClaudeUltracodeEffort(resolvedEffort);
+      resolvedModelSelection.model,
+      rawEffortSelection,
+    );
+    const cliEffort = normalizeClaudeCatalogEffort(
+      catalog,
+      resolvedEffort,
+      resolvedModelSelection.model,
+    );
+    const ultracode = isClaudeCatalogUltracodeEffort(resolvedEffort);
     const thinkingDescriptor = findDescriptor("thinking");
     const fastModeDescriptor = findDescriptor("fastMode");
     const thinking =
 @@ -166,7 +187,7 @@ export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(fu
           "--json-schema",
           jsonSchemaStr,
           "--model",
-          resolveClaudeApiModelId(modelSelection),
+          resolveClaudeCatalogApiModelId(catalog, resolvedModelSelection),
           ...(cliEffort ? ["--effort", cliEffort] : []),
           ...(settingsJson ? ["--settings", settingsJson] : []),
           "--dangerously-skip-permissions",

apps/web/src/components/chat/ModelPickerContent.tsx+3-2

...	@@ -15,7 +15,6 @@ import {	...	@@ -15,7 +15,6 @@ import {
15	parseModelPickerLegacySectionKey,	15	parseModelPickerLegacySectionKey,
16	parseModelPickerModelKey,	16	parseModelPickerModelKey,
17	} from "./modelPickerKeys";	17	} from "./modelPickerKeys";
18	import { isModelPickerNewModel } from "./modelPickerModelHighlights";
19	import { buildModelPickerSearchText, scoreModelPickerSearch } from "./modelPickerSearch";	18	import { buildModelPickerSearchText, scoreModelPickerSearch } from "./modelPickerSearch";
20	import {	19	import {
21	Combobox,	20	Combobox,
...	@@ -47,6 +46,7 @@ type ModelPickerItem = {	...	@@ -47,6 +46,7 @@ type ModelPickerItem = {
47	name: string;	46	name: string;
48	shortName?: string;	47	shortName?: string;
49	subProvider?: string;	48	subProvider?: string;
		49	badge?: "new";
50	instanceId: ProviderInstanceId;	50	instanceId: ProviderInstanceId;
51	driverKind: ProviderDriverKind;	51	driverKind: ProviderDriverKind;
52	instanceDisplayName: string;	52	instanceDisplayName: string;
...	@@ -256,6 +256,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {	...	@@ -256,6 +256,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
256	name: model.name,	256	name: model.name,
257	...(model.shortName ? { shortName: model.shortName } : {}),	257	...(model.shortName ? { shortName: model.shortName } : {}),
258	...(model.subProvider ? { subProvider: model.subProvider } : {}),	258	...(model.subProvider ? { subProvider: model.subProvider } : {}),
		259	...(model.badge ? { badge: model.badge } : {}),
259	...(model.isLegacy ? { isLegacy: true } : {}),	260	...(model.isLegacy ? { isLegacy: true } : {}),
260	...(model.isUnavailable ? { isUnavailable: true } : {}),	261	...(model.isUnavailable ? { isUnavailable: true } : {}),
261	instanceId,	262	instanceId,
...	@@ -804,7 +805,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {	...	@@ -804,7 +805,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
804	showProvider	805	showProvider
805	preferShortName={!isLocked}	806	preferShortName={!isLocked}
806	useTriggerLabel={false}	807	useTriggerLabel={false}
807	showNewBadge={isModelPickerNewModel(model.driverKind, model.slug)}	808	showNewBadge={model.badge === "new"}
808	unavailable={model.isUnavailable === true}	809	unavailable={model.isUnavailable === true}
809	jumpLabel={modelJumpLabelByKey.get(modelKey) ?? null}	810	jumpLabel={modelJumpLabelByKey.get(modelKey) ?? null}
810	disabledReason={disabledReason}	811	disabledReason={disabledReason}

apps/web/src/components/chat/composerProviderState.test.tsx+4-3

 @@ -291,11 +291,12 @@ describe("getComposerProviderState", () => {
   it("validates options for a known model selected through a legacy alias", () => {
     const state = getComposerProviderState({
       provider: ProviderDriverKind.make("claudeAgent"),
-      model: "opus",
+      model: "legacy-test-model",
       models: [
         {
-          slug: "claude-opus-5",
+          slug: "test-model",
-          name: "Claude Opus 5",
+          name: "Test Model",
+          aliases: ["legacy-test-model"],
           isCustom: false,
           capabilities: {
             optionDescriptors: [

apps/web/src/components/chat/modelPickerModelHighlights.ts deleted-13

...	@@ -1,13 +0,0 @@
1	import type { ProviderDriverKind } from "@t3tools/contracts";
2
3	/**
4	* Model slugs that show a gold "NEW" chip in the model picker list.
5	* Add entries as `provider:slug` when you want to highlight freshly shipped models.
6	*/
7	const NEW_MODEL_KEYS = new Set<string>([
8	// Example: "claudeAgent:claude-opus-4-7",
9	]);
10
11	export function isModelPickerNewModel(provider: ProviderDriverKind, slug: string): boolean {
12	return NEW_MODEL_KEYS.has(`${provider}:${slug}`);
13	}

apps/web/src/components/chat/providerIconUtils.ts+1

...	@@ -26,6 +26,7 @@ export type ModelEsque = {	...	@@ -26,6 +26,7 @@ export type ModelEsque = {
26	name: string;	26	name: string;
27	shortName?: string \| undefined;	27	shortName?: string \| undefined;
28	subProvider?: string \| undefined;	28	subProvider?: string \| undefined;
		29	badge?: "new" \| undefined;
29	isLegacy?: boolean \| undefined;	30	isLegacy?: boolean \| undefined;
30	isUnavailable?: boolean \| undefined;	31	isUnavailable?: boolean \| undefined;
31	};	32	};

apps/web/src/modelSelection.ts+4

...	@@ -75,6 +75,8 @@ export interface AppModelOption {	...	@@ -75,6 +75,8 @@ export interface AppModelOption {
75	name: string;	75	name: string;
76	shortName?: string;	76	shortName?: string;
77	subProvider?: string;	77	subProvider?: string;
		78	aliases?: ReadonlyArray<string>;
		79	badge?: "new";
78	isCustom: boolean;	80	isCustom: boolean;
79	isDefault?: boolean;	81	isDefault?: boolean;
80	isLegacy?: boolean;	82	isLegacy?: boolean;
...	@@ -109,6 +111,8 @@ function toAppModelOption(model: ServerProvider["models"][number]): AppModelOpti	...	@@ -109,6 +111,8 @@ function toAppModelOption(model: ServerProvider["models"][number]): AppModelOpti
109	};	111	};
110	if (model.shortName) option.shortName = model.shortName;	112	if (model.shortName) option.shortName = model.shortName;
111	if (model.subProvider) option.subProvider = model.subProvider;	113	if (model.subProvider) option.subProvider = model.subProvider;
		114	if (model.aliases) option.aliases = model.aliases;
		115	if (model.badge) option.badge = model.badge;
112	if (model.isDefault) option.isDefault = true;	116	if (model.isDefault) option.isDefault = true;
113	if (model.isLegacy) option.isLegacy = true;	117	if (model.isLegacy) option.isLegacy = true;
114	return option;	118	return option;

apps/web/src/providerModels.test.ts created+77

...	@@ -0,0 +1,77 @@
1	import {
2	ProviderDriverKind,
3	type ModelCapabilities,
4	type ServerProviderModel,
5	} from "@t3tools/contracts";
6	import { describe, expect, it } from "vite-plus/test";
7
8	import { getProviderModelCapabilities } from "./providerModels";
9
10	const PROVIDER = ProviderDriverKind.make("claudeAgent");
11
12	function capabilities(id: string): ModelCapabilities {
13	return {
14	optionDescriptors: [{ id, label: id, type: "boolean" }],
15	};
16	}
17
18	function model(input: {
19	slug: string;
20	capabilities: ModelCapabilities;
21	aliases?: ReadonlyArray<string>;
22	isCustom?: boolean;
23	}): ServerProviderModel {
24	return {
25	slug: input.slug,
26	name: input.slug,
27	...(input.aliases ? { aliases: [...input.aliases] } : {}),
28	isCustom: input.isCustom ?? false,
29	capabilities: input.capabilities,
30	};
31	}
32
33	describe("getProviderModelCapabilities", () => {
34	it("resolves model-declared aliases", () => {
35	const aliasCapabilities = capabilities("aliased-option");
36	const models = [
37	model({
38	slug: "synthetic-model",
39	aliases: ["Legacy-Synthetic-Model"],
40	capabilities: aliasCapabilities,
41	}),
42	];
43
44	expect(getProviderModelCapabilities(models, "legacy-synthetic-model", PROVIDER)).toEqual(
45	aliasCapabilities,
46	);
47	});
48
49	it("prefers an exact custom slug over a built-in model alias", () => {
50	const customCapabilities = capabilities("custom-option");
51	const models = [
52	model({
53	slug: "synthetic-model",
54	aliases: ["custom-model"],
55	capabilities: capabilities("built-in-option"),
56	}),
57	model({ slug: "custom-model", capabilities: customCapabilities, isCustom: true }),
58	];
59
60	expect(getProviderModelCapabilities(models, " custom-model ", PROVIDER)).toEqual(
61	customCapabilities,
62	);
63	});
64
65	it("returns empty capabilities for an unknown slug", () => {
66	const models = [
67	model({
68	slug: "default-model",
69	capabilities: capabilities("default-option"),
70	}),
71	];
72
73	expect(getProviderModelCapabilities(models, "unknown-model", PROVIDER)).toEqual({
74	optionDescriptors: [],
75	});
76	});
77	});

apps/web/src/providerModels.ts+4-4

...	@@ -8,7 +8,7 @@ import {	...	@@ -8,7 +8,7 @@ import {
8	type ServerProvider,	8	type ServerProvider,
9	type ServerProviderModel,	9	type ServerProviderModel,
10	} from "@t3tools/contracts";	10	} from "@t3tools/contracts";
11	import { createModelCapabilities, normalizeModelSlug } from "@t3tools/shared/model";	11	import { createModelCapabilities, resolveSelectableModel } from "@t3tools/shared/model";
12		12
13	const EMPTY_CAPABILITIES: ModelCapabilities = createModelCapabilities({	13	const EMPTY_CAPABILITIES: ModelCapabilities = createModelCapabilities({
14	optionDescriptors: [],	14	optionDescriptors: [],
...	@@ -83,9 +83,9 @@ export function getProviderModelCapabilities(	...	@@ -83,9 +83,9 @@ export function getProviderModelCapabilities(
83	provider: ProviderDriverKind,	83	provider: ProviderDriverKind,
84	planModeEnabled = true,	84	planModeEnabled = true,
85	): ModelCapabilities {	85	): ModelCapabilities {
86	const slug = normalizeModelSlug(model, provider);	86	const slug = resolveSelectableModel(provider, model, models);
87	const caps =	87	const selectedModel = models.find((candidate) => candidate.slug === slug);
88	models.find((candidate) => candidate.slug === slug)?.capabilities ?? EMPTY_CAPABILITIES;	88	const caps = selectedModel?.capabilities ?? EMPTY_CAPABILITIES;
89	if (planModeEnabled) {	89	if (planModeEnabled) {
90	return caps;	90	return caps;
91	}	91	}

docs/internals/model-manifest.md created+40

...	@@ -0,0 +1,40 @@
1	# Model manifest
2
3	`apps/server/src/provider/model-manifest.json` is bundled for offline startup and fetched from
4	`main` at runtime. A remote fetch replaces the in-memory and on-disk cache only after generic
5	catalog references and provider-owned adapter data validate. A failed or invalid fetch keeps the
6	last successful remote manifest. The bundle is used only when no valid remote cache exists.
7
8	The top-level provider catalog is generic: models contain presentation metadata, aliases, status,
9	an optional badge, and a reusable capability profile. The profile and model `adapter` fields are
10	opaque until the owning provider validates them with its own allowlisted schema.
11
12	Claude Code uses the manifest as its complete built-in model catalog. To add a Claude model that
13	uses an existing profile, add one object to `providers.claudeAgent.models`. Do not add a test or
14	change application code. Add or change a profile in the same JSON file only when the model exposes
15	a capability combination that does not already exist.
16
17	`currentModels.claudeAgent` is retained as a frozen compatibility field for releases that predate
18	catalog discovery. New Claude models do not need to be added there. Codex still discovers models
19	from its app server and uses `currentModels.codex` only as a legacy-classification overlay.
20
21	Claude model entries support:
22
23	- `aliases`, `status`, `badge`, and `profile` for client presentation and selection.
24	- `adapter.claudeCode.minVersion` and `maxVersionExclusive` for installed-runtime compatibility.
25	- Profile-level effort mappings, model suffixes, and context-window metadata for dispatch.
26
27	## Test policy
28
29	Changing model data does not require tests. Do not add or update tests for a model slug, display
30	name, alias, legacy status, version boundary, badge, or profile assignment. The bundled manifest is
31	configuration and is validated by its schema when imported.
32
33	Add tests only when implementation behavior changes:
34
35	- Fetching, caching, fallback, or schema-version handling changes in the manifest service.
36	- Provider-neutral profile resolution gains new semantics.
37	- A provider adapter gains a new compatibility or dispatch mapping type.
38
39	Resolver tests must use synthetic providers and model names so normal JSON edits never create test
40	churn.

packages/contracts/src/model.ts+1-27

...	@@ -176,33 +176,7 @@ export const MODEL_SLUG_ALIASES_BY_PROVIDER: Partial<	...	@@ -176,33 +176,7 @@ export const MODEL_SLUG_ALIASES_BY_PROVIDER: Partial<
176	"5.3-spark": "gpt-5.3-codex-spark",	176	"5.3-spark": "gpt-5.3-codex-spark",
177	"gpt-5.3-spark": "gpt-5.3-codex-spark",	177	"gpt-5.3-spark": "gpt-5.3-codex-spark",
178	},	178	},
179	[CLAUDE_DRIVER_KIND]: {	179	[CLAUDE_DRIVER_KIND]: {},
180	fable: "claude-fable-5-1",
181	"fable-5.1": "claude-fable-5-1",
182	"claude-fable-5.1": "claude-fable-5-1",
183	opus: "claude-opus-5",
184	"opus-5": "claude-opus-5",
185	"claude-opus-5.0": "claude-opus-5",
186	"claude-opus-5-0": "claude-opus-5",
187	"opus-4.8": "claude-opus-4-8",
188	"claude-opus-4.8": "claude-opus-4-8",
189	"opus-4.7": "claude-opus-4-7",
190	"claude-opus-4.7": "claude-opus-4-7",
191	"opus-4.6": "claude-opus-4-6",
192	"claude-opus-4.6": "claude-opus-4-6",
193	"claude-opus-4-6-20251117": "claude-opus-4-6",
194	sonnet: "claude-sonnet-5",
195	"sonnet-5": "claude-sonnet-5",
196	"claude-sonnet-5.0": "claude-sonnet-5",
197	"claude-sonnet-5-0": "claude-sonnet-5",
198	"sonnet-4.6": "claude-sonnet-4-6",
199	"claude-sonnet-4.6": "claude-sonnet-4-6",
200	"claude-sonnet-4-6-20251117": "claude-sonnet-4-6",
201	haiku: "claude-haiku-4-5",
202	"haiku-4.5": "claude-haiku-4-5",
203	"claude-haiku-4.5": "claude-haiku-4-5",
204	"claude-haiku-4-5-20251001": "claude-haiku-4-5",
205	},
206	[CURSOR_DRIVER_KIND]: {	180	[CURSOR_DRIVER_KIND]: {
207	composer: "composer-2",	181	composer: "composer-2",
208	"composer-1.5": "composer-1.5",	182	"composer-1.5": "composer-1.5",

packages/contracts/src/server.ts+2

...	@@ -66,6 +66,8 @@ export const ServerProviderModel = Schema.Struct({	...	@@ -66,6 +66,8 @@ export const ServerProviderModel = Schema.Struct({
66	name: TrimmedNonEmptyString,	66	name: TrimmedNonEmptyString,
67	shortName: Schema.optional(TrimmedNonEmptyString),	67	shortName: Schema.optional(TrimmedNonEmptyString),
68	subProvider: Schema.optional(TrimmedNonEmptyString),	68	subProvider: Schema.optional(TrimmedNonEmptyString),
		69	aliases: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
		70	badge: Schema.optional(Schema.Literal("new")),
69	isCustom: Schema.Boolean,	71	isCustom: Schema.Boolean,
70	isDefault: Schema.optional(Schema.Boolean),	72	isDefault: Schema.optional(Schema.Boolean),
71	isLegacy: Schema.optional(Schema.Boolean),	73	isLegacy: Schema.optional(Schema.Boolean),

packages/shared/src/model.test.ts+1-13

 @@ -1,5 +1,5 @@
 import { describe, expect, it } from "vite-plus/test";
-import { ProviderDriverKind, ProviderInstanceId, type ModelCapabilities } from "@t3tools/contracts";
+import { ProviderInstanceId, type ModelCapabilities } from "@t3tools/contracts";
 import {
   applyClaudePromptEffortPrefix,
 @@ -11,8 +11,6 @@ import {
   getProviderOptionDescriptors,
   getProviderOptionBooleanSelectionValue,
   getProviderOptionStringSelectionValue,
-  normalizeCustomModelSlug,
-  normalizeModelSlug,
 } from "./model.ts";
 const codexCaps: ModelCapabilities = createModelCapabilities({
 @@ -148,16 +146,6 @@ describe("descriptor helpers", () => {
   });
 });
-describe("model slug normalization", () => {
-  it("preserves exact custom slugs instead of expanding provider aliases", () => {
-    const claude = ProviderDriverKind.make("claudeAgent");
-    expect(normalizeModelSlug("fable", claude)).toBe("claude-fable-5-1");
-    expect(normalizeModelSlug("opus", claude)).toBe("claude-opus-5");
-    expect(normalizeCustomModelSlug(" opus ")).toBe("opus");
-  });
-});
 describe("applyClaudePromptEffortPrefix", () => {
   it("keeps slash commands intact when ultrathink is selected", () => {
     expect(applyClaudePromptEffortPrefix("/compact", "ultrathink")).toBe("/compact");

packages/shared/src/model.ts+8

 @@ -15,6 +15,7 @@ const DEFAULT_PROVIDER_DRIVER_KIND = ProviderDriverKind.make("codex");
 export interface SelectableModelOption {
   slug: string;
   name: string;
+  aliases?: ReadonlyArray<string> | undefined;
 }
 export function createModelCapabilities(input: {
 @@ -281,6 +282,13 @@ export function resolveSelectableModel(
     return byName.slug;
   }
+  const byAlias = options.find((option) =>
+    option.aliases?.some((alias) => alias.toLowerCase() === trimmed.toLowerCase()),
+  );
+  if (byAlias) {
+    return byAlias.slug;
+  }
   const normalized = normalizeModelSlug(trimmed, provider);
   if (!normalized) {
     return null;

author	Julius Marminge <julius0216@outlook.com> 2026-09-01 13:53:46-07:00
committer	GitHub <noreply@github.com> 2026-09-01 13:53:46-07:00
log	03542836834d008a097450cf24d0d9c6f965b859
tree	8866e08382183be2698ffaa92549ef719428d5a0
parent	a924fbe08e681ef56d8cfb8b99e1e803d52aa463
signature	Signed by PGP key B5690EEEBB952194

feat(models): discover Claude models from remote manifest (#9084)