jeopi-catalog 16.2.13

package/src/identity/dialect.ts

@@ -0,0 +1,42 @@
+import { modelFamilyToken } from "./family";
+
+export type Dialect =
+	| "glm"
+	| "hermes"
+	| "kimi"
+	| "xml"
+	| "anthropic"
+	| "deepseek"
+	| "harmony"
+	| "qwen3"
+	| "gemini"
+	| "gemma"
+	| "minimax";
+
+export const FALLBACK_DIALECT: Dialect = "xml";
+
+export function preferredDialect(modelId: string): Dialect {
+	switch (modelFamilyToken(modelId)) {
+		case "anthropic":
+			return "anthropic";
+		case "glm":
+			return "glm";
+		case "gemini":
+			return "gemini";
+		case "gemma":
+			return "gemma";
+		case "kimi":
+			return "kimi";
+		case "qwen":
+			return "qwen3";
+		case "deepseek":
+			return "deepseek";
+		case "minimax":
+			return "minimax";
+		case "openai":
+		case "gpt-oss":
+			return "harmony";
+		default:
+			return FALLBACK_DIALECT;
+	}
+}

package/src/identity/family.ts

@@ -0,0 +1,296 @@
+/**
+ * Model-family id predicates: the shared vocabulary for "is this id a member
+ * of family X" checks that gate wire-level behavior across hosts (a Kimi or
+ * DeepSeek model keeps its quirks no matter which OpenAI-compatible proxy
+ * serves it). Looser per-feature heuristics (e.g. stream-markup healing)
+ * deliberately keep their own patterns — only provably-shared matchers live
+ * here.
+ */
+
+import {
+	bareModelId,
+	isAnthropicAdaptiveGenAtLeast,
+	isFableOrMythos,
+	parseAnthropicModel,
+	parseGlmModel,
+	parseKnownModel,
+	parseOpenAIModel,
+	semverGte,
+} from "./classify";
+
+/** Bounded process-lifetime cache memo helper. */
+function memo<T>(fn: (modelId: string) => T): (modelId: string) => T {
+	const cache = new Map<string, T>();
+	return (modelId: string) => {
+		if (cache.has(modelId)) {
+			return cache.get(modelId) as T;
+		}
+		const result = fn(modelId);
+		cache.set(modelId, result);
+		return result;
+	};
+}
+
+/** Kimi family ids in any namespace form (`moonshotai/kimi-*`, `kimi-k2.6`, `vendor/kimi.x`). */
+export const isKimiModelId = memo((modelId: string): boolean => {
+	return modelId.includes("moonshotai/kimi") || /(^|\/)kimi[-.]/i.test(modelId);
+});
+
+/** Kimi K2.6 specifically, including router ids that spell the version `k2p6`. */
+export const isKimiK26ModelId = memo((modelId: string): boolean => {
+	return /(^|\/)kimi-k2(?:\.6|p6)(?:[-:]|$)/i.test(modelId);
+});
+
+/** Claude ids in any namespace form (`claude-*`, `vendor/claude.x`). */
+export const isClaudeModelId = memo((modelId: string): boolean => {
+	return /(^|\/)claude[-.]/i.test(modelId);
+});
+
+/** `anthropic/`-namespaced ids (aggregator catalogs like OpenRouter). */
+export const isAnthropicNamespacedModelId = memo((modelId: string): boolean => {
+	return /(^|\/)anthropic\//i.test(modelId);
+});
+
+/** Qwen family ids (substring match — Qwen SKUs have no stable prefix shape). */
+export const isQwenModelId = memo((modelId: string): boolean => {
+	return modelId.toLowerCase().includes("qwen");
+});
+
+/** Gemma open-weights family (`gemma-3-27b-it`, `google/gemma-4-E2B-it`, `gemma2-9b`). */
+export const isGemmaModelId = memo((modelId: string): boolean => {
+	return /(^|\/)gemma[-.]?\d/i.test(modelId);
+});
+
+/** DeepSeek family by id or display name (proxies often rename the id but keep the name). */
+export const isDeepseekModelIdOrName = memo((value: string): boolean => {
+	return value.toLowerCase().includes("deepseek");
+});
+
+/** Xiaomi MiMo family by id or display name. */
+export const isMimoModelIdOrName = memo((value: string): boolean => {
+	return value.toLowerCase().includes("mimo");
+});
+
+const GROK_EFFORT_CAPABLE_PREFIXES = ["grok-3-mini", "grok-4.20-multi-agent", "grok-4.3"] as const;
+
+/**
+ * Grok SKUs that expose the wire `reasoning.effort` dial. Other Grok reasoners
+ * (e.g. `grok-build`, `grok-4.20-0309-reasoning`) think natively but reject the
+ * param, so callers must omit reasoning effort for them.
+ */
+export const isGrokReasoningEffortCapable = memo((modelId: string): boolean => {
+	const bare = bareModelId(modelId).trim().toLowerCase();
+	if (!bare) return false;
+	return GROK_EFFORT_CAPABLE_PREFIXES.some(prefix => bare.startsWith(prefix));
+});
+
+/**
+ * MiniMax M2-generation family (M2, M2.1, M2.5, M2.7, including `-highspeed`/
+ * `-lightning`/`-her`/`-turbo` variants, dotless aliases like `minimax-m21`,
+ * and short `minimax/m2-…` ids on aggregator hosts). Underlying model accepts
+ * only `low|medium|high` for `reasoning_effort` and 400s on `minimal`,
+ * `xhigh`, or `none` — so hosts whose default effort map otherwise lowers
+ * `minimal` to `none` (Fireworks) or expects the full 5-tier scale must
+ * clamp instead. Excludes M1, M3, MiniMax-Text-01, music, hailuo, voice ids.
+ */
+export const isMinimaxM2FamilyModelId = memo((modelId: string): boolean => {
+	const lower = modelId.toLowerCase();
+	if (!lower.includes("minimax")) return false;
+	// Boundary-delimited `m2` token followed by zero or more digits (dotless
+	// variants like `m21`/`m25`/`m27`) and an optional dotted minor version.
+	return /(?:^|[/.-])m2\d*(?:[.-]\d+)?(?:[-.:_]|$)/i.test(lower);
+});
+
+/** MiniMax M3 family ids in bundled/default and aggregator namespace forms. */
+export const isMinimaxM3FamilyModelId = memo((modelId: string): boolean => {
+	const lower = modelId.toLowerCase();
+	if (!lower.includes("minimax")) return false;
+	return /(?:^|[/._-])(?:minimax[/._-])?m3(?:[-.:_]|$)/i.test(lower);
+});
+
+/**
+ * OpenAI gpt-oss family (`gpt-oss-20b`, `gpt-oss-120b`, `gpt-oss:120b`,
+ * `vendor/gpt-oss-…`). The Harmony reasoning format only accepts
+ * `low|medium|high` for `reasoning_effort` and rejects `minimal`, `xhigh`,
+ * and `none`.
+ */
+export const isOpenAIGptOssModelId = memo((modelId: string): boolean => {
+	return /(^|\/)gpt-oss[-:]/i.test(modelId);
+});
+
+/** OpenAI model ids (gpt-*, o1-*, o3-*, o4-*, or prefixed with openai/). */
+export const isOpenAIModelId = memo((modelId: string): boolean => {
+	return /(^|\/)(gpt|o1|o3|o4)[-.]/i.test(modelId) || modelId.toLowerCase().includes("openai/");
+});
+
+/** OpenAI models at or above the gpt-5.4 wire generation, keyed off the parsed version. */
+const isOpenAIWireGen54Plus = memo((modelId: string): boolean => {
+	const parsed = parseOpenAIModel(bareModelId(modelId));
+	if (!parsed) return false;
+	return semverGte(parsed.version, "5.4");
+});
+
+/**
+ * OpenAI Codex models that honor `reasoning.context: "all_turns"` (full
+ * cross-turn reasoning replay). The `reasoning.context` field itself exists for
+ * the whole gpt-5/o-series family, but the `all_turns` value is only accepted
+ * from gpt-5.4 onward; earlier ids (`gpt-5.1-codex`, `gpt-5.3-codex`, and
+ * `gpt-5.3-codex-spark`) reject it with
+ * `Unsupported value: 'all_turns' is not supported with this model`. Version
+ * floor (not an allowlist) so 5.6/6.x inherit support automatically. Callers
+ * fall back to omitting `context`, letting the server default to `current_turn`.
+ */
+export const supportsAllTurnsReasoningContext = isOpenAIWireGen54Plus;
+
+/**
+ * OpenAI Codex models that accept `reasoning.summary`. Shares the gpt-5.4 wire
+ * floor with {@link supportsAllTurnsReasoningContext}: earlier Codex ids
+ * (`gpt-5.1-codex`, `gpt-5.3-codex`, `gpt-5.3-codex-spark`) reject the field
+ * with `Unsupported parameter: 'reasoning.summary' is not supported with this
+ * model`. Callers omit `summary` for unsupported ids, letting the server skip
+ * the human-readable summary stream.
+ */
+export const supportsCodexReasoningSummary = isOpenAIWireGen54Plus;
+
+/**
+ * Reasoning-capable GLM coding SKUs: glm-4.5 and up on the base / `-air` /
+ * `-turbo` lines. Excludes the vision (`…v`) shape, the non-reasoning
+ * `-flash`/`-flashx`/`-preview` variants, and pre-4.5 ids. Matching the family
+ * keeps newly-bumped integers (`glm-5.3`, `glm-6`, …) covered without a per-id
+ * allowlist.
+ */
+export const isReasoningGlmModelId = memo((modelId: string): boolean => {
+	const glm = parseGlmModel(bareModelId(modelId));
+	if (!glm || glm.vision) {
+		return false;
+	}
+	if (glm.variant !== "base" && glm.variant !== "air" && glm.variant !== "turbo") {
+		return false;
+	}
+	return semverGte(glm.version, "4.5");
+});
+
+/** GLM-5.2+ coding SKUs accept `reasoning_effort` in addition to binary thinking. */
+export const isGlm52ReasoningEffortModelId = memo((modelId: string): boolean => {
+	const glm = parseGlmModel(bareModelId(modelId));
+	if (!glm || glm.vision) {
+		return false;
+	}
+	if (glm.variant !== "base" && glm.variant !== "air" && glm.variant !== "turbo") {
+		return false;
+	}
+	return semverGte(glm.version, "5.2");
+});
+
+/** GLM vision SKUs — the `v` that attaches to the version (`glm-4v`, `glm-4.5v`). */
+export const isGlmVisionModelId = memo((modelId: string): boolean => {
+	return parseGlmModel(bareModelId(modelId))?.vision === true;
+});
+
+/**
+ * Coarse vendor-lineage token for "are two models the same family?" checks
+ * (e.g. picking a cross-family reviewer). All Claude point releases share a token,
+ * Claude and GPT differ; namespace prefixes and aggregator mirrors fold onto the
+ * lineage via {@link parseKnownModel}'s `bareModelId` normalization. Opaque and
+ * comparison-only — not a stable key to persist, since the vocabulary tracks new
+ * releases. Returns `""` for ids it cannot classify; callers fall back to the provider.
+ *
+ * Vendor-only by design: a model's kind/variant (opus vs sonnet, codex vs base) is
+ * collapsed onto the single vendor token; use {@link parseKnownModel} for finer breakdowns.
+ */
+export const modelFamilyToken = memo((modelId: string): string => {
+	const parsed = parseKnownModel(modelId);
+	if (parsed.family !== "unknown") return parsed.family;
+	if (isClaudeModelId(modelId) || isAnthropicNamespacedModelId(modelId)) return "anthropic";
+	if (isOpenAIModelId(modelId)) return "openai";
+	if (isKimiModelId(modelId)) return "kimi";
+	if (isQwenModelId(modelId)) return "qwen";
+	if (isMinimaxM2FamilyModelId(modelId) || isMinimaxM3FamilyModelId(modelId)) return "minimax";
+	if (isOpenAIGptOssModelId(modelId)) return "gpt-oss";
+	if (isDeepseekModelIdOrName(modelId)) return "deepseek";
+	if (isMimoModelIdOrName(modelId)) return "mimo";
+	if (isGemmaModelId(modelId)) return "gemma";
+	if (parseGlmModel(bareModelId(modelId))) return "glm";
+	return "";
+});
+
+/**
+ * Adaptive thinking `display` is supported starting with Claude Opus 4.7+,
+ * Sonnet 5+, and the Claude Fable/Mythos 5 generation. Older adaptive-thinking
+ * models (Opus 4.6, Sonnet 4.6) reject the field. Classifier-based, so dotted
+ * and dashed version forms both match while bare dated ids
+ * (`claude-opus-4-20250514` = Opus 4.0) stay excluded.
+ */
+export const supportsAdaptiveThinkingDisplay = memo((modelId: string): boolean => {
+	const parsed = parseAnthropicModel(bareModelId(modelId));
+	return parsed !== null && isAnthropicAdaptiveGenAtLeast(parsed, "4.7");
+});
+
+/**
+ * Returns true for Anthropic models with Opus 4.7+, Sonnet 5+, and Fable/Mythos 5+
+ * API restrictions:
+ * - Sampling parameters (temperature/top_p/top_k) return 400 error
+ * - Thinking content is omitted by default (needs display: "summarized")
+ */
+export const hasOpus47ApiRestrictions = memo((modelId: string): boolean => {
+	const parsed = parseAnthropicModel(bareModelId(modelId));
+	return parsed !== null && isAnthropicAdaptiveGenAtLeast(parsed, "4.7");
+});
+
+/**
+ * Mid-conversation `role: "system"` messages (system instructions appended at
+ * non-first positions in the `messages` array) are supported starting with
+ * Claude Opus 4.8+, Sonnet 5+, and the Claude Fable/Mythos 5 generation.
+ * Earlier Claude models reject the role.
+ * @see https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages
+ */
+export const supportsMidConversationSystemMessages = memo((modelId: string): boolean => {
+	const parsed = parseAnthropicModel(bareModelId(modelId));
+	return parsed !== null && isAnthropicAdaptiveGenAtLeast(parsed, "4.8");
+});
+
+export const isAnthropicFableOrMythosModel = memo((modelId: string): boolean => {
+	const parsed = parseAnthropicModel(bareModelId(modelId));
+	return parsed !== null && isFableOrMythos(parsed.kind);
+});
+
+/** Thinking-variant token location inside a model id. */
+export interface ThinkingVariantToken {
+	index: number;
+	length: number;
+}
+
+const THINKING_VARIANT_TOKEN_RE = /-(?:thinking|reasoner|reasoning)(?=$|[^a-z0-9])/gi;
+
+/**
+ * Locates the first thinking-variant token (`-thinking`, `-reasoner`,
+ * `-reasoning`; trailing or infix) in a model id. The token ends at the id
+ * end or any non-alphanumeric boundary, and negated forms (`non-thinking`,
+ * `no-thinking`) never match — those name the NON-thinking SKU.
+ */
+export function findThinkingVariantToken(modelId: string): ThinkingVariantToken | undefined {
+	THINKING_VARIANT_TOKEN_RE.lastIndex = 0;
+	let match = THINKING_VARIANT_TOKEN_RE.exec(modelId);
+	while (match !== null) {
+		const preceding = /([a-z0-9]+)$/i.exec(modelId.slice(0, match.index))?.[1]?.toLowerCase();
+		if (preceding !== "non" && preceding !== "no") {
+			return { index: match.index, length: match[0].length };
+		}
+		match = THINKING_VARIANT_TOKEN_RE.exec(modelId);
+	}
+	return undefined;
+}
+
+/**
+ * Removes the located thinking-variant token: `kimi-k2-thinking` → `kimi-k2`,
+ * `mimo-v2-flash-thinking-original` → `mimo-v2-flash-original`,
+ * `grok-4.1-fast-reasoning` → `grok-4.1-fast`. Returns `undefined` when no
+ * token exists or nothing would remain. Callers MUST verify the result names
+ * a live model.
+ */
+export const stripThinkingVariantToken = memo((modelId: string): string | undefined => {
+	const token = findThinkingVariantToken(modelId);
+	if (!token) return undefined;
+	const stripped = modelId.slice(0, token.index) + modelId.slice(token.index + token.length);
+	return stripped.length > 0 ? stripped : undefined;
+});

package/src/identity/id.ts

@@ -0,0 +1,81 @@
+const LEADING_BRACKETED_AFFIX_PATTERN = /^(?:\s*(?:\[|【)[^\]】]+(?:\]|】)\s*)+/u;
+const TRAILING_BRACKETED_AFFIX_PATTERN = /(?:\s*(?:\[|【)[^\]】]+(?:\]|】)\s*)+$/u;
+const MODEL_ID_SEGMENT_PATTERN = /[a-z0-9.:-]+/g;
+const MODEL_FAMILY_PREFIX_PATTERN =
+	/^(claude|gemini|gpt|grok|glm|qwen|deepseek|kimi|mimo|doubao|ernie|gpt-oss|gemma|minimax|step|command|jamba|llama|o[1345])/i;
+
+function normalizeModelIdWhitespace(value: string): string {
+	return value.trim().replace(/\s+/g, " ");
+}
+
+/** Ordering for model-like segments: longest first, ties broken lexicographically. */
+function compareSegmentPreference(left: string, right: string): number {
+	return left.length !== right.length ? right.length - left.length : left.localeCompare(right);
+}
+
+export function getModelLikeIdSegments(modelId: string): string[] {
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return [];
+	const segments = new Set<string>();
+	for (const segment of matches) {
+		if (MODEL_FAMILY_PREFIX_PATTERN.test(segment) && /\d/.test(segment)) segments.add(segment);
+	}
+	return [...segments].sort(compareSegmentPreference);
+}
+
+export function getLongestModelLikeIdSegment(modelId: string): string | undefined {
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return undefined;
+	let best: string | undefined;
+	for (const segment of matches) {
+		if (
+			MODEL_FAMILY_PREFIX_PATTERN.test(segment) &&
+			/\d/.test(segment) &&
+			(best === undefined || compareSegmentPreference(segment, best) < 0)
+		) {
+			best = segment;
+		}
+	}
+	return best;
+}
+
+function hasBracketAffixMarker(value: string): boolean {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code === 91 || code === 93 || code === 0x3010 || code === 0x3011) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Strip reseller / wrapper tags that are injected as bracketed affixes around an
+ * upstream model id, e.g.
+ *   "[Kiro] claude-opus-4-8"                -> "claude-opus-4-8"
+ *   "[gcli转] gemini-3.1-pro-preview [假流]" -> "gemini-3.1-pro-preview"
+ *
+ * Candidates are returned most-stripped first: both ends, then leading-only, then trailing-only.
+ */
+export function getBracketStrippedModelIdCandidates(modelId: string): string[] {
+	if (!hasBracketAffixMarker(modelId)) return [];
+	const normalized = normalizeModelIdWhitespace(modelId);
+	if (!normalized) return [];
+
+	const strippedLeading = normalized.replace(LEADING_BRACKETED_AFFIX_PATTERN, "");
+	const withoutLeading = normalizeModelIdWhitespace(strippedLeading);
+	const withoutTrailing = normalizeModelIdWhitespace(normalized.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
+	const withoutBoth = normalizeModelIdWhitespace(strippedLeading.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
+
+	const candidates = new Set<string>();
+	for (const candidate of [withoutBoth, withoutLeading, withoutTrailing]) {
+		if (candidate && candidate !== normalized) {
+			candidates.add(candidate);
+		}
+	}
+	return [...candidates];
+}
+
+export function stripBracketedModelIdAffixes(modelId: string): string | undefined {
+	return getBracketStrippedModelIdCandidates(modelId)[0];
+}

package/src/identity/index.ts

@@ -0,0 +1,8 @@
+export * from "./bundled";
+export * from "./classify";
+export * from "./dialect";
+export * from "./family";
+export * from "./id";
+export * from "./markers";
+export * from "./priority";
+export * from "./reference";

package/src/identity/markers.ts

@@ -0,0 +1,49 @@
+/**
+ * Trailing-marker vocabulary shared by canonical-id resolution and
+ * proxy-reference lookup. A "marker" is a routing/quantization/effort suffix
+ * a reseller or aggregator appends to an upstream model id
+ * (`-thinking`, `:nitro`, `-fp8`, …) that does not change model identity.
+ */
+const TRAILING_MARKERS = [
+	"thinking",
+	"customtools",
+	"high",
+	"low",
+	"medium",
+	"minimal",
+	"xhigh",
+	"free",
+	"cloud",
+	"exacto",
+	"nitro",
+	"original",
+	"optimized",
+	"nvfp4",
+	"fp8",
+	"fp4",
+	"bf16",
+	"int8",
+	"int4",
+] as const;
+
+/**
+ * Markers treated as identity-preserving ONLY when recovering bundled metadata
+ * for a proxied model id, never during canonical-id coalescing: Perplexity's
+ * `sonar-pro-search` is a distinct model from `sonar-pro`, so canonical
+ * resolution must not strip `search`, while a proxy id like
+ * `claude-opus-4-6-search` should still inherit the upstream pricing/limits.
+ */
+const REFERENCE_ONLY_TRAILING_MARKERS = ["search"] as const;
+
+function buildTrailingMarkerPattern(markers: readonly string[]): RegExp {
+	return new RegExp(`[-:](?:${markers.join("|")})$`, "i");
+}
+
+/** Marker pattern used by canonical-id resolution (`search` excluded). */
+export const CANONICAL_TRAILING_MARKER_PATTERN = buildTrailingMarkerPattern(TRAILING_MARKERS);
+
+/** Marker pattern used by proxy-reference lookup (`search` included). */
+export const REFERENCE_TRAILING_MARKER_PATTERN = buildTrailingMarkerPattern([
+	...TRAILING_MARKERS,
+	...REFERENCE_ONLY_TRAILING_MARKERS,
+]);

package/src/identity/priority.ts

@@ -0,0 +1,57 @@
+const DEFAULT_MODEL_PROVIDER_ORDER = [
+	// First-party / native account providers. Prefer these over relays when the
+	// same upstream model is available in more than one place.
+	"openai-codex",
+	"anthropic",
+	"openai",
+	"google-gemini-cli",
+	"google",
+	"google-vertex",
+	"kimi-code",
+	"moonshot",
+	"qwen-portal",
+	"zai",
+	"xai-oauth",
+	"xai",
+	"mistral",
+	"deepseek",
+	"groq",
+
+	// High-quality aggregators / hosted inference providers.
+	"fireworks",
+	"cerebras",
+	"openrouter",
+	"aimlapi",
+	"together",
+
+	// Generic gateways and editor/proxy providers. These are useful when picked
+	// explicitly, but should not win ambiguous automatic role selection.
+	"alibaba-coding-plan",
+	"umans",
+	"google-antigravity",
+	"opencode-zen",
+	"gitlab-duo",
+	"opencode-go",
+	"kilo",
+	"vercel-ai-gateway",
+	"cloudflare-ai-gateway",
+	"nanogpt",
+	"github-copilot",
+] as const;
+
+function addProviderRank(rank: Map<string, number>, provider: string): void {
+	const normalized = provider.trim().toLowerCase();
+	if (!normalized || rank.has(normalized)) return;
+	rank.set(normalized, rank.size);
+}
+
+export function buildModelProviderPriorityRank(configuredProviderOrder?: readonly string[]): Map<string, number> {
+	const rank = new Map<string, number>();
+	for (const provider of configuredProviderOrder ?? []) {
+		addProviderRank(rank, provider);
+	}
+	for (const provider of DEFAULT_MODEL_PROVIDER_ORDER) {
+		addProviderRank(rank, provider);
+	}
+	return rank;
+}

package/src/identity/reference.ts

@@ -0,0 +1,148 @@
+/**
+ * Proxy/reseller reference lookup: given a custom model id served through a
+ * proxy (`[Kiro] claude-opus-4-8`, `gpt-5.4:cloud`, `vendor/claude-sonnet-4-6-thinking`),
+ * find the bundled upstream model so missing pricing/capability metadata can be
+ * inherited while keeping the custom transport.
+ *
+ * Kept separate from canonical-id resolution (`./equivalence`): this lookup
+ * may strip `search`-style markers and prefers cache-pricing-complete
+ * references, both of which would be wrong for canonical coalescing.
+ */
+import type { Api, Model } from "../types";
+import { getBracketStrippedModelIdCandidates, getLongestModelLikeIdSegment, getModelLikeIdSegments } from "./id";
+import { REFERENCE_TRAILING_MARKER_PATTERN } from "./markers";
+
+export interface ModelReferenceIndex {
+	exact: Map<string, Model<Api>>;
+	suffixAlias: Map<string, Model<Api>>;
+}
+
+// xai-oauth subscription entries carry zero public pricing and inflated maxTokens;
+// keep them provider-local so they cannot outrank paid/public Grok references.
+export function isZeroCostXaiOAuthReference(candidate: Model<Api>): boolean {
+	return (
+		candidate.provider === "xai-oauth" &&
+		candidate.cost.input === 0 &&
+		candidate.cost.output === 0 &&
+		candidate.cost.cacheRead === 0 &&
+		candidate.cost.cacheWrite === 0
+	);
+}
+
+// Prefer the reference with the largest limits and complete cache pricing, then
+// first-party OpenAI entries.
+function shouldReplaceReference(existing: Model<Api> | undefined, candidate: Model<Api>): boolean {
+	if (!existing) return true;
+	if (candidate.contextWindow !== existing.contextWindow) {
+		return (candidate.contextWindow ?? 0) > (existing.contextWindow ?? 0);
+	}
+	if (candidate.maxTokens !== existing.maxTokens) {
+		return (candidate.maxTokens ?? 0) > (existing.maxTokens ?? 0);
+	}
+	const existingHasCachePricing = existing.cost.cacheRead > 0 || existing.cost.cacheWrite > 0;
+	const candidateHasCachePricing = candidate.cost.cacheRead > 0 || candidate.cost.cacheWrite > 0;
+	if (candidateHasCachePricing !== existingHasCachePricing) {
+		return candidateHasCachePricing;
+	}
+	return existing.provider !== "openai" && candidate.provider === "openai";
+}
+
+function normalizeReferenceKey(value: string): string {
+	return value.trim().toLowerCase();
+}
+
+/**
+ * Build a reference index from a model catalog (typically the bundled models).
+ * Pure: callers are responsible for memoizing the result.
+ */
+export function buildModelReferenceIndex(models: Iterable<Model<Api>>): ModelReferenceIndex {
+	const exact = new Map<string, Model<Api>>();
+	for (const candidate of models) {
+		if (isZeroCostXaiOAuthReference(candidate)) {
+			continue;
+		}
+		const key = normalizeReferenceKey(candidate.id);
+		if (shouldReplaceReference(exact.get(key), candidate)) {
+			exact.set(key, candidate);
+		}
+	}
+	return { exact, suffixAlias: buildSuffixAliasMap(exact) };
+}
+
+function buildSuffixAliasMap(exactReferences: ReadonlyMap<string, Model<Api>>): Map<string, Model<Api>> {
+	const aliases = new Map<string, Model<Api>>();
+	for (const reference of exactReferences.values()) {
+		const slashIndex = reference.id.lastIndexOf("/");
+		if (slashIndex === -1) {
+			continue;
+		}
+		const suffix = reference.id.slice(slashIndex + 1);
+		const alias = getLongestModelLikeIdSegment(suffix);
+		if (!alias) {
+			continue;
+		}
+		if (shouldReplaceReference(aliases.get(alias), reference)) {
+			aliases.set(alias, reference);
+		}
+	}
+	return aliases;
+}
+
+function stripReferenceTrailingMarker(candidate: string): string | undefined {
+	const match = REFERENCE_TRAILING_MARKER_PATTERN.exec(candidate);
+	return match ? candidate.slice(0, match.index) : undefined;
+}
+
+function getReferenceCandidateIds(modelId: string): string[] {
+	const candidates = new Set<string>();
+	const queue = [modelId];
+	for (let index = 0; index < queue.length; index += 1) {
+		const candidate = queue[index]?.trim();
+		if (!candidate || candidates.has(candidate)) continue;
+		candidates.add(candidate);
+
+		for (const stripped of getBracketStrippedModelIdCandidates(candidate)) {
+			queue.push(stripped);
+		}
+		for (const segment of getModelLikeIdSegments(candidate)) {
+			queue.push(segment);
+		}
+
+		for (const suffix of [":cloud", "-cloud"] as const) {
+			if (candidate.toLowerCase().endsWith(suffix)) {
+				queue.push(candidate.slice(0, -suffix.length));
+			}
+		}
+
+		const slashIndex = candidate.lastIndexOf("/");
+		if (slashIndex !== -1) {
+			queue.push(candidate.slice(slashIndex + 1));
+		}
+
+		const colonToDash = candidate.replace(/:/g, "-");
+		if (colonToDash !== candidate) {
+			queue.push(colonToDash);
+		}
+
+		const lowercased = candidate.toLowerCase();
+		if (lowercased !== candidate) {
+			queue.push(lowercased);
+		}
+
+		const strippedMarker = stripReferenceTrailingMarker(candidate);
+		if (strippedMarker) {
+			queue.push(strippedMarker);
+		}
+	}
+	return [...candidates];
+}
+
+/** Resolve a (possibly proxied/affixed) model id to its bundled upstream reference. */
+export function resolveModelReference(modelId: string, index: ModelReferenceIndex): Model<Api> | undefined {
+	for (const candidate of getReferenceCandidateIds(modelId)) {
+		const key = normalizeReferenceKey(candidate);
+		const reference = index.exact.get(key) ?? index.suffixAlias.get(key);
+		if (reference) return reference;
+	}
+	return undefined;
+}