The best way to control Claude Code, Codex and more from any computer or phone

main
ts 572 lines 20.7 KB
Raw
1 import {
2 type CustomModelSetting,
3 type ModelCapabilities,
4 type ModelSelection,
5 ProviderDriverKind,
6 type ServerProviderModel,
7 type ServerProviderUpdateRequiredModel,
8 } from "@t3tools/contracts";
9 import type { ModelInfo as ClaudeModelInfo } from "@anthropic-ai/claude-agent-sdk";
10 import * as Option from "effect/Option";
11 import {
12 getModelSelectionStringOptionValue,
13 getProviderOptionCurrentValue,
14 getProviderOptionDescriptors,
15 readCustomModelEntries,
16 } from "@t3tools/shared/model";
17 import { compareSemverVersions } from "@t3tools/shared/semver";
18
19 import {
20 type ClaudeCodeCompatibility,
21 type ClaudeCodeProfile,
22 decodeClaudeModelAdapter,
23 decodeClaudeProfileAdapter,
24 } from "./ClaudeModelManifest.ts";
25 import * as ModelCatalog from "@t3tools/provider-core/server/ModelCatalog";
26 import { BUNDLED_MODEL_MANIFEST, resolveProviderCatalog } 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 /** What to send Claude Code instead of the slug, from its own model list. */
36 readonly apiModel?: string;
37 }
38
39 export interface ClaudeModelCatalog {
40 readonly models: ReadonlyArray<ClaudeCatalogModel>;
41 }
42
43 function tryResolveClaudeModelCatalog(
44 resolved: ModelCatalog.ProviderCatalog | undefined,
45 ): ClaudeModelCatalog | null {
46 if (!resolved) return null;
47
48 const models: Array<ClaudeCatalogModel> = [];
49 for (const entry of resolved.models) {
50 const profile = decodeClaudeProfileAdapter(entry.profileAdapter ?? {});
51 const adapter = decodeClaudeModelAdapter(entry.adapter ?? {});
52 if (Option.isNone(profile) || Option.isNone(adapter)) return null;
53 const model = ModelCatalog.catalogServerModel(resolved, entry);
54 models.push({
55 model: { ...model, capabilities: withUltracodeToggle(model.capabilities) },
56 runtime: profile.value.claudeCode ?? {},
57 compatibility: adapter.value.claudeCode ?? {},
58 });
59 }
60
61 return {
62 models,
63 };
64 }
65
66 // The manifest keeps Ultracode as an effort level because released servers read it from main.
67 export function withUltracodeToggle(
68 capabilities: ModelCapabilities | null,
69 ): ModelCapabilities | null {
70 const descriptors = capabilities?.optionDescriptors ?? [];
71 const effortIndex = descriptors.findIndex(
72 (descriptor) =>
73 descriptor.id === "effort" &&
74 descriptor.type === "select" &&
75 descriptor.options.some((option) => option.id === "ultracode"),
76 );
77 const effort = descriptors[effortIndex];
78 if (effort?.type !== "select") return capabilities;
79 const ultracodeByDefault =
80 (effort.currentValue ?? effort.options.find((option) => option.isDefault)?.id) === "ultracode";
81 const hasXhigh = effort.options.some((option) => option.id === "xhigh");
82 // Ultracode ran at xhigh, so a model that offered it keeps xhigh, and its default moves there.
83 const options = effort.options.flatMap(({ isDefault, ...option }) => {
84 if (option.id === "ultracode") {
85 return hasXhigh
86 ? []
87 : [{ id: "xhigh", label: "Extra High", ...(isDefault ? { isDefault } : {}) }];
88 }
89 if (ultracodeByDefault && option.id === "xhigh") return [{ ...option, isDefault: true }];
90 return [isDefault && !ultracodeByDefault ? { ...option, isDefault } : option];
91 });
92 return {
93 optionDescriptors: descriptors.toSpliced(
94 effortIndex,
95 1,
96 {
97 ...effort,
98 ...(effort.currentValue === "ultracode" ? { currentValue: "xhigh" } : {}),
99 options,
100 },
101 {
102 id: "ultracode",
103 label: "Ultracode",
104 type: "boolean",
105 ...(ultracodeByDefault ? { currentValue: true } : {}),
106 },
107 ),
108 };
109 }
110
111 /** Resolve the fallback on each read so its new-model badges can expire. */
112 export function resolveClaudeModelCatalog(
113 catalog: ModelCatalog.ProviderCatalog | undefined,
114 ): ClaudeModelCatalog {
115 return (
116 tryResolveClaudeModelCatalog(catalog) ??
117 tryResolveClaudeModelCatalog(
118 resolveProviderCatalog(BUNDLED_MODEL_MANIFEST, CLAUDE) ?? undefined,
119 ) ?? {
120 models: [],
121 }
122 );
123 }
124
125 export const BUNDLED_CLAUDE_MODEL_CATALOG = resolveClaudeModelCatalog(undefined);
126
127 export function scopeClaudeModelCatalog(
128 catalog: ClaudeModelCatalog,
129 customModels: ReadonlyArray<CustomModelSetting>,
130 ): ClaudeModelCatalog {
131 const customEntries = readCustomModelEntries(customModels);
132 if (customEntries.length === 0) return catalog;
133 const customAliases = new Set(customEntries.map((entry) => entry.slug.toLowerCase()));
134
135 const builtInModels = catalog.models.map((entry) => {
136 if (!entry.model.aliases?.some((alias) => customAliases.has(alias.toLowerCase()))) {
137 return entry;
138 }
139 return {
140 ...entry,
141 model: {
142 ...entry.model,
143 aliases: entry.model.aliases.filter((alias) => !customAliases.has(alias.toLowerCase())),
144 },
145 };
146 });
147 const builtInSlugs = new Set(builtInModels.map((entry) => entry.model.slug));
148 const customCatalogModels: Array<ClaudeCatalogModel> = [];
149 for (const entry of customEntries) {
150 if (!entry.capabilities || builtInSlugs.has(entry.slug)) continue;
151 customCatalogModels.push({
152 model: {
153 slug: entry.slug,
154 name: entry.name,
155 isCustom: true,
156 capabilities: withUltracodeToggle(entry.capabilities),
157 },
158 runtime: {},
159 compatibility: {},
160 });
161 }
162
163 return { models: [...builtInModels, ...customCatalogModels] };
164 }
165
166 const CLAUDE_EFFORT_LABELS: Readonly<Record<string, string>> = {
167 low: "Low",
168 medium: "Medium",
169 high: "High",
170 xhigh: "Extra High",
171 max: "Max",
172 };
173
174 function stripClaudeContextWindowSuffix(value: string): string {
175 return value.replace(/\[[^\]]*\]$/, "").trim();
176 }
177
178 export function claudeReportedModels(
179 catalog: ClaudeModelCatalog,
180 customModels: ReadonlyArray<CustomModelSetting>,
181 reported: ReadonlyArray<ClaudeModelInfo> | undefined,
182 ): ReadonlyArray<ServerProviderModel> {
183 if (!reported?.length) return [];
184 const known = new Set(
185 [
186 ...catalog.models.flatMap(({ model }) => [model.slug, ...(model.aliases ?? [])]),
187 ...readCustomModelEntries(customModels).map((entry) => entry.slug),
188 ].map((id) => stripClaudeContextWindowSuffix(id).toLowerCase()),
189 );
190 const models: Array<ServerProviderModel> = [];
191 for (const info of reported) {
192 const slug = info.value.trim();
193 // `default` is Claude Code's pointer at its own default model, not a model.
194 if (!slug || slug === "default") continue;
195 const ids = [slug, info.resolvedModel ?? ""]
196 .map((id) => stripClaudeContextWindowSuffix(id).toLowerCase())
197 .filter((id) => id.length > 0);
198 if (ids.some((id) => known.has(id))) continue;
199 for (const id of ids) known.add(id);
200 const efforts = info.supportsEffort ? (info.supportedEffortLevels ?? []) : [];
201 models.push({
202 slug,
203 name: info.displayName.trim() || slug,
204 isCustom: false,
205 capabilities: {
206 optionDescriptors: efforts.length
207 ? [
208 {
209 id: "effort",
210 label: "Reasoning",
211 type: "select",
212 // `default` is not an effort, so choosing it sends none and Claude Code picks.
213 options: [
214 { id: "default", label: "Default", isDefault: true },
215 ...efforts.map((id) => ({ id, label: CLAUDE_EFFORT_LABELS[id] ?? id })),
216 ],
217 },
218 ]
219 : [],
220 },
221 });
222 }
223 return models;
224 }
225
226 export function resolveClaudeCatalogModel(
227 catalog: ClaudeModelCatalog,
228 slugOrAlias: string | null | undefined,
229 ): ClaudeCatalogModel | undefined {
230 const value = slugOrAlias?.trim();
231 if (!value) return undefined;
232 return (
233 catalog.models.find((entry) => entry.model.slug === value) ??
234 catalog.models.find((entry) =>
235 entry.model.aliases?.some((alias) => alias.toLowerCase() === value.toLowerCase()),
236 )
237 );
238 }
239
240 // Cloud backends decorate first-party ids: Bedrock adds a region prefix and a
241 // version ("us.anthropic.claude-opus-4-6-v1"), Vertex adds "@<date>".
242 function stripClaudeBackendDecoration(wireModel: string): string {
243 return wireModel
244 .replace(/^(?:[a-z-]+\.)?anthropic\./, "")
245 .replace(/-v\d+(?::\d+)?$/, "")
246 .replace(/@[^@]*$/, "");
247 }
248
249 /**
250 * On Bedrock, Vertex and similar backends Claude Code does not accept the first-party slug: it
251 * either sends it verbatim or, when `availableModels` excludes it, silently runs the default
252 * model instead. Its model list names the id that does work, often a family alias that
253 * `ANTHROPIC_DEFAULT_*_MODEL` points at a backend id.
254 */
255 export function withClaudeCodeModelRoutes(
256 catalog: ClaudeModelCatalog,
257 reportedModels: ReadonlyArray<Pick<ClaudeModelInfo, "value" | "resolvedModel">>,
258 ): ClaudeModelCatalog {
259 const apiModels = new Map<string, string>();
260 for (const reported of reportedModels) {
261 if (reported.value === "default") continue;
262 const wireModel = stripClaudeContextWindowSuffix(reported.resolvedModel ?? reported.value);
263 const firstPartyModel = stripClaudeBackendDecoration(wireModel);
264 if (firstPartyModel === wireModel) continue;
265 const entry = resolveClaudeCatalogModel(catalog, firstPartyModel);
266 if (!entry || apiModels.has(entry.model.slug)) continue;
267 apiModels.set(entry.model.slug, stripClaudeContextWindowSuffix(reported.value));
268 }
269 if (apiModels.size === 0) return catalog;
270 return {
271 models: catalog.models.map((entry) => {
272 const apiModel = apiModels.get(entry.model.slug);
273 return apiModel ? { ...entry, apiModel } : entry;
274 }),
275 };
276 }
277
278 export function resolveClaudeModelSlug(catalog: ClaudeModelCatalog, slugOrAlias: string): string {
279 return resolveClaudeCatalogModel(catalog, slugOrAlias)?.model.slug ?? slugOrAlias;
280 }
281
282 /** Claude reports dated IDs, such as `claude-opus-4-5-20251101`, that the catalog may not list. */
283 export function resolveClaudeReportedModelSlug(
284 catalog: ClaudeModelCatalog,
285 reported: string,
286 ): string {
287 return (
288 (
289 resolveClaudeCatalogModel(catalog, reported) ??
290 resolveClaudeCatalogModel(catalog, reported.replace(/-\d{8}$/, ""))
291 )?.model.slug ?? reported
292 );
293 }
294
295 export function getClaudeCatalogModelCapabilities(
296 catalog: ClaudeModelCatalog,
297 slugOrAlias: string | null | undefined,
298 ): ModelCapabilities {
299 return resolveClaudeCatalogModel(catalog, slugOrAlias)?.model.capabilities ?? EMPTY_CAPABILITIES;
300 }
301
302 function isVersionSupported(
303 compatibility: ClaudeCodeCompatibility,
304 version: string | null | undefined,
305 ): boolean {
306 if (!compatibility.minVersion && !compatibility.maxVersionExclusive) return true;
307 if (!version) return false;
308 if (compatibility.minVersion && compareSemverVersions(version, compatibility.minVersion) < 0) {
309 return false;
310 }
311 return !(
312 compatibility.maxVersionExclusive &&
313 compareSemverVersions(version, compatibility.maxVersionExclusive) >= 0
314 );
315 }
316
317 export function resolveClaudeModelsForVersion(
318 catalog: ClaudeModelCatalog,
319 version: string | null | undefined,
320 ): ReadonlyArray<ClaudeCatalogModel["model"]> {
321 return catalog.models
322 .filter((entry) => isVersionSupported(entry.compatibility, version))
323 .map((entry) => entry.model);
324 }
325
326 export function resolveClaudeUpdateRequiredModels(
327 catalog: ClaudeModelCatalog,
328 version: string | null | undefined,
329 ): ReadonlyArray<ServerProviderUpdateRequiredModel> {
330 if (!version) return [];
331 return catalog.models.flatMap(({ model, compatibility }) => {
332 const minVersion = compatibility.minVersion;
333 if (model.isLegacy || !minVersion || compareSemverVersions(version, minVersion) >= 0) {
334 return [];
335 }
336 return [
337 {
338 slug: model.slug,
339 name: model.name,
340 ...(model.badge ? { badge: model.badge } : {}),
341 minVersion,
342 },
343 ];
344 });
345 }
346
347 export function formatClaudeVersionUpgradeMessage(
348 catalog: ClaudeModelCatalog,
349 version: string | null,
350 ): string | undefined {
351 const unavailable = catalog.models
352 .filter(
353 (entry) =>
354 entry.compatibility.minVersion &&
355 (!version || compareSemverVersions(version, entry.compatibility.minVersion) < 0),
356 )
357 .toSorted((left, right) =>
358 compareSemverVersions(left.compatibility.minVersion!, right.compatibility.minVersion!),
359 )[0];
360 if (!unavailable?.compatibility.minVersion) return undefined;
361 const versionLabel = version ? `v${version}` : "the installed version";
362 return `Claude Code ${versionLabel} is too old for ${unavailable.model.name}. Upgrade to v${unavailable.compatibility.minVersion} or newer to access it.`;
363 }
364
365 /** Claude Code's effort levels, lowest first. */
366 export const CLAUDE_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
367 export type ClaudeEffortLevel = (typeof CLAUDE_EFFORT_LEVELS)[number];
368
369 function claudeEffortRank(level: string | undefined): number {
370 return CLAUDE_EFFORT_LEVELS.indexOf(level as ClaudeEffortLevel);
371 }
372
373 /** One settings source's effort caps, with `modelSettings` keys as the user wrote them. */
374 export interface ClaudeEffortCapSource {
375 readonly maxEffortLevel?: ClaudeEffortLevel;
376 readonly modelMaxEffortLevels?: ReadonlyMap<string, ClaudeEffortLevel>;
377 }
378
379 const CLAUDE_1M_SUFFIX = "[1m]";
380 const CLAUDE_CODE_FAMILY_ALIASES: ReadonlySet<string> = new Set([
381 "opus",
382 "sonnet",
383 "haiku",
384 "fable",
385 ]);
386
387 /**
388 * Names the model a `modelSettings` key caps the way Claude Code does, which is narrower than the
389 * catalog's aliases: only a family alias (optionally `[1m]`) resolves as an alias, and any other key
390 * names the most specific model id it contains, so `claude-opus-5-5-20260101` and Bedrock ids match
391 * while `claude-opus-5.5` matches nothing.
392 */
393 function resolveClaudeModelSettingsKey(
394 catalog: ClaudeModelCatalog,
395 key: string,
396 ): string | undefined {
397 const lowered = key.trim().toLowerCase();
398 const unsuffixed = lowered.endsWith(CLAUDE_1M_SUFFIX)
399 ? lowered.slice(0, -CLAUDE_1M_SUFFIX.length)
400 : lowered;
401 if (CLAUDE_CODE_FAMILY_ALIASES.has(unsuffixed)) {
402 return catalog.models.find(
403 (entry) => !entry.model.isCustom && entry.model.aliases?.includes(unsuffixed),
404 )?.model.slug;
405 }
406 let match: string | undefined;
407 for (const { model } of catalog.models) {
408 if (!model.isCustom && lowered.includes(model.slug) && model.slug.length > (match?.length ?? 0))
409 match = model.slug;
410 }
411 return match;
412 }
413
414 /** Keys `modelSettings` caps by canonical slug, keeping the lowest cap when several keys name one model. */
415 function resolveClaudeModelMaxEffortLevels(
416 catalog: ClaudeModelCatalog,
417 levels: ReadonlyMap<string, ClaudeEffortLevel> | undefined,
418 ): ReadonlyMap<string, ClaudeEffortLevel> {
419 const resolved = new Map<string, ClaudeEffortLevel>();
420 for (const [key, level] of levels ?? []) {
421 const slug = resolveClaudeModelSettingsKey(catalog, key);
422 if (!slug) continue;
423 const current = resolved.get(slug);
424 if (!current || claudeEffortRank(level) < claudeEffortRank(current)) resolved.set(slug, level);
425 }
426 return resolved;
427 }
428
429 /**
430 * Claude Code clamps efforts above `maxEffortLevel` to the model's highest level under it, so
431 * such options are relabelled, not removed, keeping stored selections valid. Per-model caps
432 * replace their own source's top-level cap and `max` means none; across sources the lowest wins.
433 */
434 export function capClaudeCatalogEffort(
435 catalog: ClaudeModelCatalog,
436 models: ReadonlyArray<ServerProviderModel>,
437 sources: ReadonlyArray<ClaudeEffortCapSource>,
438 ): ReadonlyArray<ServerProviderModel> {
439 if (sources.length === 0) return models;
440 const resolvedSources = sources.map((source) => ({
441 maxEffortLevel: source.maxEffortLevel,
442 modelMaxEffortLevels: resolveClaudeModelMaxEffortLevels(catalog, source.modelMaxEffortLevels),
443 }));
444 return models.map((model) => {
445 // Custom model labels are user-authored, so they are left alone.
446 if (model.isCustom || !model.capabilities?.optionDescriptors) return model;
447 const modelMaxEffortLevel = resolvedSources.reduce<ClaudeEffortLevel | undefined>(
448 (lowest, source) => {
449 const level = source.modelMaxEffortLevels.get(model.slug) ?? source.maxEffortLevel;
450 return level &&
451 level !== "max" &&
452 (!lowest || claudeEffortRank(level) < claudeEffortRank(lowest))
453 ? level
454 : lowest;
455 },
456 undefined,
457 );
458 if (!modelMaxEffortLevel) return model;
459 const capRank = claudeEffortRank(modelMaxEffortLevel);
460 return {
461 ...model,
462 capabilities: {
463 ...model.capabilities,
464 optionDescriptors: model.capabilities.optionDescriptors.map((descriptor) => {
465 if (descriptor.id !== "effort" || descriptor.type !== "select") return descriptor;
466 const cap = descriptor.options.reduce<{ rank: number; label: string } | undefined>(
467 (best, option) => {
468 const rank = claudeEffortRank(option.id);
469 return rank >= 0 && rank <= capRank && rank > (best?.rank ?? -1)
470 ? { rank, label: option.label }
471 : best;
472 },
473 undefined,
474 );
475 if (!cap) return descriptor;
476 return {
477 ...descriptor,
478 options: descriptor.options.map((option) => {
479 const idRank = claudeEffortRank(option.id);
480 const sentRank = claudeEffortRank(
481 normalizeClaudeCatalogEffort(catalog, option.id, model.slug),
482 );
483 const displayedRank = idRank >= 0 ? idRank : sentRank;
484 const runsRank = sentRank >= 0 ? sentRank : idRank;
485 return displayedRank > cap.rank && runsRank > cap.rank
486 ? { ...option, label: `${option.label} (capped to ${cap.label})` }
487 : option;
488 }),
489 };
490 }),
491 },
492 };
493 });
494 }
495
496 export function resolveClaudeCatalogEffort(
497 catalog: ClaudeModelCatalog,
498 model: string | null | undefined,
499 raw: string | null | undefined,
500 ): string | undefined {
501 if (!resolveClaudeCatalogModel(catalog, model)) {
502 const effort = raw?.trim();
503 return effort && (CLAUDE_EFFORT_LEVELS as ReadonlyArray<string>).includes(effort)
504 ? effort
505 : undefined;
506 }
507
508 const caps = getClaudeCatalogModelCapabilities(catalog, model);
509 const descriptors = getProviderOptionDescriptors({
510 caps,
511 ...(raw ? { selections: [{ id: "effort", value: raw }] } : {}),
512 });
513 const descriptor = descriptors.find((candidate) => candidate.id === "effort");
514 const value = getProviderOptionCurrentValue(descriptor);
515 return typeof value === "string" ? value : undefined;
516 }
517
518 export function normalizeClaudeCatalogEffort(
519 catalog: ClaudeModelCatalog,
520 effort: string | null | undefined,
521 model: string | null | undefined,
522 ): string | undefined {
523 if (!effort) return undefined;
524 const effortMap = resolveClaudeCatalogModel(catalog, model)?.runtime.effortMap;
525 if (!effortMap || !Object.prototype.hasOwnProperty.call(effortMap, effort)) return effort;
526 return effortMap[effort] ?? undefined;
527 }
528
529 function resolveClaudeCatalogContextWindow(
530 catalog: ClaudeModelCatalog,
531 modelSelection: ModelSelection | undefined,
532 ): string | undefined {
533 const caps = getClaudeCatalogModelCapabilities(catalog, modelSelection?.model);
534 const raw = getModelSelectionStringOptionValue(modelSelection, "contextWindow");
535 const descriptors = getProviderOptionDescriptors({
536 caps,
537 ...(raw ? { selections: [{ id: "contextWindow", value: raw }] } : {}),
538 });
539 const descriptor = descriptors.find((candidate) => candidate.id === "contextWindow");
540 const value = getProviderOptionCurrentValue(descriptor);
541 return typeof value === "string" ? value : undefined;
542 }
543
544 export function resolveClaudeCatalogApiModelId(
545 catalog: ClaudeModelCatalog,
546 modelSelection: ModelSelection,
547 ): string {
548 const entry = resolveClaudeCatalogModel(catalog, modelSelection.model);
549 const slug = entry?.apiModel ?? entry?.model.slug ?? modelSelection.model;
550 const descriptors = getProviderOptionDescriptors({
551 caps: entry?.model.capabilities ?? EMPTY_CAPABILITIES,
552 selections: modelSelection.options,
553 });
554 for (const [optionId, suffixes] of Object.entries(entry?.runtime.modelSuffixes ?? {})) {
555 const value = getProviderOptionCurrentValue(
556 descriptors.find((descriptor) => descriptor.id === optionId),
557 );
558 if (typeof value === "string" && suffixes[value]) return `${slug}${suffixes[value]}`;
559 }
560 return slug;
561 }
562
563 export function resolveClaudeCatalogContextWindowTokens(
564 catalog: ClaudeModelCatalog,
565 modelSelection: ModelSelection | undefined,
566 ): number | undefined {
567 const entry = resolveClaudeCatalogModel(catalog, modelSelection?.model);
568 if (!entry) return undefined;
569 if (entry.runtime.fixedContextWindowTokens) return entry.runtime.fixedContextWindowTokens;
570 const contextWindow = resolveClaudeCatalogContextWindow(catalog, modelSelection);
571 return contextWindow ? entry.runtime.contextWindowTokens?.[contextWindow] : undefined;
572 }