@staticeng/opencode-litellm 0.1.9 → 0.2.0

package/README.md

@@ -15,7 +15,7 @@ npm install @staticeng/opencode-litellm
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
     [
-      "@staticeng/opencode-litellm@0.1.9",
+      "@staticeng/opencode-litellm",
       {
         "baseURL": "https://litellm.example.com/v1",
         "apiKeyEnv": "LITELLM_API_KEY"
@@ -33,7 +33,7 @@ export LITELLM_API_KEY="..."
 
 Do not put real API keys in `opencode.json`. If you pass `apiKey` directly, the plugin uses it only in memory and never logs it, but environment variables are recommended.
 
-Shared or synchronized OpenCode configuration must use the published, pinned npm package as shown above. Do not use a local path or `file://` plugin reference for shared configuration.
+Shared or synchronized OpenCode configuration should use the published package name as shown above. Do not use a local path or `file://` plugin reference for shared configuration.
 
 ## Options
 
@@ -56,11 +56,9 @@ The LiteLLM key must have permission to call `GET /model/info` and root `GET /mo
 
 ## Overrides
 
-LiteLLM metadata does not expose every OpenCode model field. Use `overrides` to add variants, thinking controls, cache costs, interleaved reasoning settings, limits, modalities, timeouts, or provider-specific options.
+LiteLLM metadata does not expose every OpenCode model field. Version 0.2.0 includes exact built-in contracts for the currently approved GPT-5.4, GPT-5.5, GPT-5.6, GPT-5.3 Codex Spark, DeepSeek V4 Flash, and Qwen3.8 aliases. Use `overrides` to customize those defaults or to add metadata for unknown models.
 
-When LiteLLM publishes `model_info.supported_reasoning_efforts`, the plugin maps
-that list to OpenCode variants automatically. It does not guess effort levels
-from model names; the LiteLLM catalog remains the source of truth.
+When LiteLLM publishes `model_info.supported_reasoning_efforts`, the plugin maps that list to OpenCode variants automatically for unknown models. Known contracts use exact alias membership and win over absent, incomplete, or conflicting discovery metadata. No substring, suffix, provider namespace, or base-model inference is used.
 
 ```json
 {
@@ -90,11 +88,22 @@ from model names; the LiteLLM catalog remains the source of truth.
 }
 ```
 
-Overrides win over generated values through a recursive deep merge. Arrays and scalar values are replaced rather than concatenated.
+Overrides win over built-in contracts and generated values through a recursive deep merge. Model overrides are applied first and provider overrides last. Arrays and scalar values are replaced rather than concatenated.
+
+The built-in mode matrix is:
+
+| Contract | Modes in order | Default |
+| --- | --- | --- |
+| GPT-5.4 / GPT-5.4 Mini | `none`, `low`, `medium`, `high`, `xhigh` | `none` |
+| GPT-5.5 | `none`, `low`, `medium`, `high`, `xhigh` | `medium` |
+| GPT-5.6 Luna / Sol / Terra | `none`, `low`, `medium`, `high`, `xhigh`, `max` | `medium` |
+| GPT-5.3 Codex Spark | `none`, `low`, `medium`, `high`, `xhigh` | `high` |
+| DeepSeek V4 Flash | `off`, `low`, `high`, `max` | `max` |
+| Qwen3.8 | `off`, `low`, `medium`, `xhigh` | `xhigh` |
 
-The exact model groups `deepseek-v4-flash-fp8-mtp` and `deepseek-v4-flash-fp8-mtp-norefusal` are an exception: the plugin exposes only `off`, `low`, `high`, and `max`. Semantic `off` emits canonical `none`; the other values pass through unchanged. At the OpenCode config boundary, disabled `medium` and `xhigh` tombstones remove generic generated variants, while the model-scoped `variantDefault: false` capability hides the UI's default sentinel on compatible OpenCode builds. The plugin strips that UI-only marker in `chat.params` only when both the LiteLLM provider and an exact target alias match. Target model and provider overrides cannot change these controls. No manual model entry in `opencode.json` is needed.
+DeepSeek `off` sends canonical `none`. Qwen `off` sends only `chat_template_kwargs.enable_thinking=false`, with no reasoning effort. `ultra` is not generated by a built-in contract. For requests without an explicit named variant, the plugin supplies the row's contract default through model options; an explicit variant is merged afterward and wins. Qwen's explicit `off` cleanup removes the default `xhigh` effort before serialization. The `variantDefault` compatibility marker is UI-only and is stripped before requests for exact built-in aliases.
 
-The exact model group `qwen3.8-27b-refusal-dial` similarly exposes only `off`, `low`, `medium`, and `xhigh`. Its semantic `off` sends `chat_template_kwargs.enable_thinking=false` without a `reasoning_effort`; the native effort modes pass through unchanged. Disabled `none`, `minimal`, `high`, and `max` tombstones suppress OpenCode's unsupported generated variants. Official OpenCode 1.18.23 still owns an intrinsic default selection (`Predeterminado`) outside model variants; plugin configuration cannot remove it, and leaving it selected omits reasoning controls and preserves the model's deployed default.
+Normal GPT-5.3 Codex aliases are retired and filtered even if stale discovery metadata still reports them. GPT-5.3 Codex Spark is a separate exact contract and remains available whenever discovered. Unlisted aliases such as `defend/gpt-5.5` do not inherit a contract.
 
 ## Runtime Behavior
 
@@ -103,7 +112,8 @@ The exact model group `qwen3.8-27b-refusal-dial` similarly exposes only `off`, `
 - Adds or replaces both legacy `cfg.provider[providerKey]` and V2 `cfg.providers[providerKey]` during the config hook.
 - Keeps namespaced deployment IDs and augments them with exact bare model-group IDs; exact collisions are enriched deterministically.
 - Skips malformed group rows without a nonblank `model_group` and exposes reasoning capability on legacy and V2 model metadata.
-- Generates exact DeepSeek V4 and Qwen3.8 reasoning variants for the supported aliases and sanitizes conflicting target overrides after merging.
+- Applies exact built-in model contracts as defaults, then applies explicit model and provider overrides last.
+- Filters retired normal GPT-5.3 Codex aliases without redirecting them; discovered Spark aliases remain independent.
 - Warns safely and keeps deployment models when group discovery fails in non-strict mode; strict mode mutates neither config surface on failure.
 - Does not write `opencode.json`, cache model metadata, or persist generated provider data.
 - Emits the required `limit.output` as `0` when LiteLLM reports a context/input limit but no output

package/dist/index.js

@@ -1,5 +1,5 @@
 import { fetchModelGroupInfo, fetchModelInfo } from "./litellm.js";
-import { addOpenCodeVariantTombstones, buildProvider, buildProviderV2, isContractReasoningModel, mergeModelInfo, } from "./mapping.js";
+import { buildProvider, buildProviderV2, isContractReasoningModel, isQwen38ReasoningModel, mergeModelInfo, } from "./mapping.js";
 import { resolveOptions } from "./options.js";
 async function log(ctx, level, message, extra = {}) {
     await ctx.client?.app?.log?.({ body: { service: "opencode-litellm", level, message, extra } });
@@ -25,7 +25,7 @@ const LiteLLMPlugin = async (ctx, options) => {
                         throw error;
                 }
                 const models = mergeModelInfo(deployments, groups);
-                const provider = addOpenCodeVariantTombstones(buildProvider(models, resolved));
+                const provider = buildProvider(models, resolved);
                 const config = cfg;
                 const providerV2 = buildProviderV2(models, resolved);
                 cfg.provider = {
@@ -60,6 +60,11 @@ const LiteLLMPlugin = async (ctx, options) => {
             if (!isContractReasoningModel(input.model.id))
                 return;
             delete output.options.variantDefault;
+            const selectedVariant = input.message?.model?.variant;
+            if (isQwen38ReasoningModel(input.model.id) && selectedVariant === "off") {
+                delete output.options.reasoningEffort;
+                delete output.options.reasoning_effort;
+            }
         }),
     };
 };

package/dist/mapping.d.ts

@@ -11,6 +11,7 @@ export declare function modelListResponseShape(value: unknown): ModelListRespons
 export declare function mergeModelInfo(deployments: LiteLLMModelInfo[], groups: LiteLLMModelInfo[]): LiteLLMModelInfo[];
 export declare function normalizeModelListResponse(response: unknown): LiteLLMModelInfo[];
 export declare function isDeepSeekV4ReasoningModel(name: string | undefined): boolean;
+export declare function isQwen38ReasoningModel(name: string | undefined): boolean;
 export declare function isContractReasoningModel(name: string | undefined): boolean;
 export declare function addOpenCodeVariantTombstones(provider: OpenCodeProvider): OpenCodeProvider;
 export declare function mapModels(response: unknown, options?: LiteLLMPluginOptions): {
@@ -18,6 +19,48 @@ export declare function mapModels(response: unknown, options?: LiteLLMPluginOpti
 };
 export declare function buildProvider(models: unknown, options?: LiteLLMPluginOptions): OpenCodeProvider;
 export declare function mapModelsV2(models: unknown, options?: LiteLLMPluginOptions): {
-    [k: string]: OpenCodeModelV2;
+    [k: string]: OpenCodeModelV2 | {
+        variants: {
+            id: string;
+            body: {
+                [x: string]: unknown;
+            };
+        }[];
+        family?: string;
+        name?: string;
+        api?: {
+            id?: string;
+            type: "aisdk";
+            package: string;
+            url?: string;
+            settings?: import("./types.js").JsonObject;
+        };
+        capabilities?: {
+            tools: boolean;
+            reasoning: boolean;
+            attachment: boolean;
+            input: string[];
+            output: string[];
+        };
+        request?: {
+            headers?: Record<string, string>;
+            body?: import("./types.js").JsonObject;
+            variant?: string;
+        };
+        cost?: {
+            input: number;
+            output: number;
+            cache?: {
+                read?: number;
+                write?: number;
+            };
+        };
+        disabled?: boolean;
+        limit?: {
+            context?: number;
+            input?: number;
+            output?: number;
+        };
+    };
 };
 export declare function buildProviderV2(models: unknown, options?: LiteLLMPluginOptions): OpenCodeProviderV2;

package/dist/mapping.js

@@ -1,38 +1,10 @@
 import { deepMerge } from "./merge.js";
+import { isRetiredModelAlias, modelContract } from "./model-contracts.js";
 const DEFAULT_MODES = new Set(["chat", "responses"]);
 const NON_CHAT_MODES = new Set(["embedding", "rerank"]);
 const TEXT_MODALITY = "text";
 const OPENCODE_MODALITIES = new Set(["text", "audio", "image", "video", "pdf"]);
 const TEXT_ONLY_MODELS = new Set(["minimax-m2.7", "minimax_m2.7"]);
-const DEEPSEEK_V4_REASONING_MODELS = new Set([
-    "deepseek-v4-flash-fp8-mtp",
-    "deepseek-v4-flash-fp8-mtp-norefusal",
-]);
-const QWEN_38_REASONING_MODELS = new Set(["qwen3.8-27b-refusal-dial"]);
-const DEEPSEEK_V4_VARIANTS = {
-    off: { reasoningEffort: "none" },
-    low: { reasoningEffort: "low" },
-    high: { reasoningEffort: "high" },
-    max: { reasoningEffort: "max" },
-};
-const DEEPSEEK_V4_VARIANTS_V2 = [
-    { id: "off", body: { reasoning_effort: "none" } },
-    { id: "low", body: { reasoning_effort: "low" } },
-    { id: "high", body: { reasoning_effort: "high" } },
-    { id: "max", body: { reasoning_effort: "max" } },
-];
-const QWEN_38_VARIANTS = {
-    off: { chat_template_kwargs: { enable_thinking: false } },
-    low: { reasoningEffort: "low" },
-    medium: { reasoningEffort: "medium" },
-    xhigh: { reasoningEffort: "xhigh" },
-};
-const QWEN_38_VARIANTS_V2 = [
-    { id: "off", body: { chat_template_kwargs: { enable_thinking: false } } },
-    { id: "low", body: { reasoning_effort: "low" } },
-    { id: "medium", body: { reasoning_effort: "medium" } },
-    { id: "xhigh", body: { reasoning_effort: "xhigh" } },
-];
 const REASONING_EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
 const REASONING_EFFORT_SET = new Set(REASONING_EFFORTS);
 const NUMERIC_MODEL_INFO_FIELDS = new Set([
@@ -195,6 +167,8 @@ function allowedByFilters(model, options) {
     const name = modelName(model);
     if (!name)
         return false;
+    if (isRetiredModelAlias(name))
+        return false;
     if (options.includeModels?.length && !options.includeModels.includes(name))
         return false;
     if (options.excludeModels?.includes(name))
@@ -280,29 +254,35 @@ function supportsReasoning(model) {
         model.model_info?.supported_params?.includes("thinking"));
 }
 export function isDeepSeekV4ReasoningModel(name) {
-    return name !== undefined && DEEPSEEK_V4_REASONING_MODELS.has(name);
+    return modelContract(name)?.family === "DeepSeek V4 Flash";
+}
+export function isQwen38ReasoningModel(name) {
+    return modelContract(name)?.family === "Qwen3.8";
 }
 export function isContractReasoningModel(name) {
-    return isDeepSeekV4ReasoningModel(name) || (name !== undefined && QWEN_38_REASONING_MODELS.has(name));
+    return modelContract(name) !== undefined;
 }
-function enforceReasoningVariants(model) {
-    const name = asString(model.id) ?? asString(model.name);
-    if (!isContractReasoningModel(name))
-        return model;
+function contractDefaults(name, tombstones = false) {
+    const entry = modelContract(name);
+    if (!entry)
+        return undefined;
+    const defaultMode = entry.modes.find((mode) => mode.id === entry.defaultMode);
+    if (!defaultMode)
+        throw new Error(`Model contract ${entry.family} has no default mode body`);
+    const variants = Object.fromEntries(entry.modes.map((mode) => [mode.id, { ...mode.legacy }]));
+    if (tombstones) {
+        const disabled = entry.family === "DeepSeek V4 Flash"
+            ? ["medium", "xhigh"]
+            : entry.family === "Qwen3.8"
+                ? ["none", "minimal", "high", "max"]
+                : [];
+        for (const effort of disabled)
+            variants[effort] = { disabled: true };
+    }
     return {
-        ...model,
         reasoning: true,
-        options: { ...(isRecord(model.options) ? model.options : {}), variantDefault: false },
-        variants: isDeepSeekV4ReasoningModel(name) ? DEEPSEEK_V4_VARIANTS : QWEN_38_VARIANTS,
-    };
-}
-function enforceReasoningProviderModels(provider) {
-    return {
-        ...provider,
-        models: Object.fromEntries(Object.entries(provider.models).map(([name, model]) => [
-            name,
-            isContractReasoningModel(name) ? enforceReasoningVariants({ ...model, id: name }) : model,
-        ])),
+        options: { ...defaultMode.legacy, variantDefault: entry.variantDefault },
+        variants,
     };
 }
 export function addOpenCodeVariantTombstones(provider) {
@@ -310,22 +290,7 @@ export function addOpenCodeVariantTombstones(provider) {
         ...provider,
         models: Object.fromEntries(Object.entries(provider.models).map(([name, model]) => [
             name,
-            isContractReasoningModel(name)
-                ? {
-                    ...model,
-                    variants: {
-                        ...(isDeepSeekV4ReasoningModel(name) ? DEEPSEEK_V4_VARIANTS : QWEN_38_VARIANTS),
-                        ...(isDeepSeekV4ReasoningModel(name)
-                            ? { medium: { disabled: true }, xhigh: { disabled: true } }
-                            : {
-                                none: { disabled: true },
-                                minimal: { disabled: true },
-                                high: { disabled: true },
-                                max: { disabled: true },
-                            }),
-                    },
-                }
-                : model,
+            isContractReasoningModel(name) ? deepMerge(contractDefaults(name, true) ?? {}, model) : model,
         ])),
     };
 }
@@ -338,12 +303,12 @@ function reasoningVariants(model) {
         return undefined;
     return Object.fromEntries(efforts.map((effort) => [effort, { reasoningEffort: effort }]));
 }
-function generatedModel(model) {
+function generatedModel(model, tombstones = false) {
     const name = modelName(model);
     if (!name)
         return undefined;
     const mappedModalities = modalities(model);
-    return {
+    const generated = {
         id: name,
         name,
         ...(asString(model.model_info?.base_model) ? { family: asString(model.model_info?.base_model) } : {}),
@@ -355,6 +320,7 @@ function generatedModel(model) {
         ...(supportsReasoning(model) && reasoningVariants(model) ? { variants: reasoningVariants(model) } : {}),
         ...(model.model_info?.supports_function_calling || model.model_info?.supports_tool_choice ? { tool_call: true } : {}),
     };
+    return deepMerge(generated, contractDefaults(name, tombstones));
 }
 function finalizedModel(model, override) {
     const input = supportedModalities(model.modalities?.input ?? [TEXT_MODALITY]);
@@ -366,19 +332,37 @@ function finalizedModel(model, override) {
         attachment: attachmentOverride ?? input.some((modality) => modality === "image" || modality === "pdf"),
     };
 }
+function v2VariantBody(value) {
+    const raw = isRecord(value) ? { ...value } : {};
+    const body = isRecord(raw.options) ? { ...raw.options } : raw;
+    if (body.reasoningEffort !== undefined && body.reasoning_effort === undefined) {
+        body.reasoning_effort = body.reasoningEffort;
+        delete body.reasoningEffort;
+    }
+    return body;
+}
 function v2Variants(model) {
     const variants = model.variants;
     if (!isRecord(variants))
         return undefined;
-    return Object.entries(variants).map(([id, value]) => {
-        const raw = isRecord(value) ? { ...value } : {};
-        const body = isRecord(raw.options) ? { ...raw.options } : raw;
-        if (body.reasoningEffort !== undefined && body.reasoning_effort === undefined) {
-            body.reasoning_effort = body.reasoningEffort;
-            delete body.reasoningEffort;
-        }
-        return { id, body };
-    });
+    return Object.entries(variants).map(([id, value]) => ({ id, body: v2VariantBody(value) }));
+}
+function contractV2Variants(name, override) {
+    const entry = modelContract(name);
+    if (!entry)
+        return undefined;
+    const variants = entry.modes.map((mode) => ({ id: mode.id, body: { ...mode.v2Body } }));
+    if (!isRecord(override?.variants))
+        return variants;
+    const byID = new Map(variants.map((variant) => [variant.id, variant]));
+    for (const [id, value] of Object.entries(override.variants)) {
+        const current = byID.get(id);
+        byID.set(id, {
+            id,
+            body: deepMerge(current?.body ?? {}, v2VariantBody(value)),
+        });
+    }
+    return Array.from(byID.values());
 }
 function v2Model(model, baseURL) {
     const id = asString(model.id) ?? asString(model.name);
@@ -407,24 +391,27 @@ function v2Model(model, baseURL) {
         ...(v2Variants(model) ? { variants: v2Variants(model) } : {}),
     };
 }
-export function mapModels(response, options = {}) {
+function mapModelsInternal(response, options, tombstones) {
     const models = normalizeModelListResponse(response);
     return Object.fromEntries(models
         .filter((model) => allowedByFilters(model, options))
         .map((model) => {
         const name = modelName(model);
-        const generated = generatedModel(model);
+        const generated = generatedModel(model, tombstones);
         return name && generated
             ? [
                 name,
-                enforceReasoningVariants(finalizedModel(deepMerge(generated, options.overrides?.[name]), options.overrides?.[name])),
+                finalizedModel(deepMerge(generated, options.overrides?.[name]), options.overrides?.[name]),
             ]
             : undefined;
     })
         .filter((entry) => Boolean(entry)));
 }
+export function mapModels(response, options = {}) {
+    return mapModelsInternal(response, options, false);
+}
 export function buildProvider(models, options = {}) {
-    return enforceReasoningProviderModels(deepMerge({
+    return deepMerge({
         id: options.providerKey ?? "LiteLLM",
         name: options.providerName ?? "LiteLLM",
         npm: "@ai-sdk/openai-compatible",
@@ -434,15 +421,19 @@ export function buildProvider(models, options = {}) {
             apiKey: options.apiKey,
             ...(options.apiKey ? { body: { apiKey: options.apiKey } } : {}),
         },
-        models: mapModels(models, options),
-    }, options.providerOverrides));
+        models: mapModelsInternal(models, options, true),
+    }, options.providerOverrides);
 }
 export function mapModelsV2(models, options = {}) {
     const legacy = mapModels(models, options);
-    return Object.fromEntries(Object.entries(legacy).map(([name, model]) => [name, v2Model(model, options.baseURL)]));
+    return Object.fromEntries(Object.entries(legacy).map(([name, model]) => {
+        const mapped = v2Model(model, options.baseURL);
+        const variants = contractV2Variants(name, options.overrides?.[name]);
+        return [name, variants ? { ...mapped, variants } : mapped];
+    }));
 }
 export function buildProviderV2(models, options = {}) {
-    const provider = deepMerge({
+    return deepMerge({
         name: options.providerName ?? "LiteLLM",
         api: {
             type: "aisdk",
@@ -457,24 +448,4 @@ export function buildProviderV2(models, options = {}) {
         },
         models: mapModelsV2(models, options),
     }, options.providerOverrides);
-    return {
-        ...provider,
-        models: Object.fromEntries(Object.entries(provider.models).map(([name, model]) => [
-            name,
-            isContractReasoningModel(name)
-                ? {
-                    ...model,
-                    capabilities: {
-                        tools: model.capabilities?.tools ?? false,
-                        reasoning: true,
-                        attachment: model.capabilities?.attachment ?? false,
-                        input: model.capabilities?.input ?? [TEXT_MODALITY],
-                        output: model.capabilities?.output ?? [TEXT_MODALITY],
-                    },
-                    options: { ...(isRecord(model.options) ? model.options : {}), variantDefault: false },
-                    variants: isDeepSeekV4ReasoningModel(name) ? DEEPSEEK_V4_VARIANTS_V2 : QWEN_38_VARIANTS_V2,
-                }
-                : model,
-        ])),
-    };
 }

package/dist/model-contracts.d.ts

@@ -0,0 +1,5 @@
+import type { ModelContract } from "./types.js";
+export declare const MODEL_CONTRACTS: readonly ModelContract[];
+export declare const RETIRED_MODEL_ALIASES: readonly string[];
+export declare function modelContract(name: string | undefined): ModelContract | undefined;
+export declare function isRetiredModelAlias(name: string | undefined): boolean;

package/dist/model-contracts.js

@@ -0,0 +1,82 @@
+function freezeJson(value) {
+    for (const nested of Object.values(value)) {
+        if (nested && typeof nested === "object" && !Object.isFrozen(nested))
+            Object.freeze(nested);
+    }
+    return Object.freeze(value);
+}
+function effortModes(ids) {
+    return Object.freeze(ids.map((id) => Object.freeze({
+        id,
+        legacy: freezeJson({ reasoningEffort: id }),
+        v2Body: freezeJson({ reasoning_effort: id }),
+    })));
+}
+function contract(family, aliases, modes, defaultMode) {
+    if (!modes.some((mode) => mode.id === defaultMode))
+        throw new Error(`Model contract ${family} has an invalid default`);
+    return Object.freeze({
+        family,
+        aliases: Object.freeze([...aliases]),
+        modes,
+        defaultMode,
+        reasoning: true,
+        variantDefault: false,
+    });
+}
+const GPT_STANDARD_MODES = effortModes(["none", "low", "medium", "high", "xhigh"]);
+const GPT_MAX_MODES = effortModes(["none", "low", "medium", "high", "xhigh", "max"]);
+const DEEPSEEK_MODES = Object.freeze([
+    Object.freeze({ id: "off", legacy: freezeJson({ reasoningEffort: "none" }), v2Body: freezeJson({ reasoning_effort: "none" }) }),
+    Object.freeze({ id: "low", legacy: freezeJson({ reasoningEffort: "low" }), v2Body: freezeJson({ reasoning_effort: "low" }) }),
+    Object.freeze({ id: "high", legacy: freezeJson({ reasoningEffort: "high" }), v2Body: freezeJson({ reasoning_effort: "high" }) }),
+    Object.freeze({ id: "max", legacy: freezeJson({ reasoningEffort: "max" }), v2Body: freezeJson({ reasoning_effort: "max" }) }),
+]);
+const qwenOff = Object.freeze({ enable_thinking: false });
+const QWEN_MODES = Object.freeze([
+    Object.freeze({
+        id: "off",
+        legacy: freezeJson({ chat_template_kwargs: qwenOff }),
+        v2Body: freezeJson({ chat_template_kwargs: qwenOff }),
+    }),
+    Object.freeze({ id: "low", legacy: freezeJson({ reasoningEffort: "low" }), v2Body: freezeJson({ reasoning_effort: "low" }) }),
+    Object.freeze({ id: "medium", legacy: freezeJson({ reasoningEffort: "medium" }), v2Body: freezeJson({ reasoning_effort: "medium" }) }),
+    Object.freeze({ id: "xhigh", legacy: freezeJson({ reasoningEffort: "xhigh" }), v2Body: freezeJson({ reasoning_effort: "xhigh" }) }),
+]);
+const chatGptAliases = (model) => Object.freeze([
+    model,
+    `chatgpt/${model}`,
+    `chatgpt-account2/${model}`,
+    `chatgpt-account3/${model}`,
+]);
+export const MODEL_CONTRACTS = Object.freeze([
+    contract("GPT-5.4", chatGptAliases("gpt-5.4"), GPT_STANDARD_MODES, "none"),
+    contract("GPT-5.4 Mini", chatGptAliases("gpt-5.4-mini"), GPT_STANDARD_MODES, "none"),
+    contract("GPT-5.5", chatGptAliases("gpt-5.5"), GPT_STANDARD_MODES, "medium"),
+    contract("GPT-5.6 Luna", chatGptAliases("gpt-5.6-luna"), GPT_MAX_MODES, "medium"),
+    contract("GPT-5.6 Sol", chatGptAliases("gpt-5.6-sol"), GPT_MAX_MODES, "medium"),
+    contract("GPT-5.6 Terra", chatGptAliases("gpt-5.6-terra"), GPT_MAX_MODES, "medium"),
+    contract("GPT-5.3 Codex Spark", chatGptAliases("gpt-5.3-codex-spark"), GPT_STANDARD_MODES, "high"),
+    contract("DeepSeek V4 Flash", ["deepseek-v4-flash-fp8-mtp", "deepseek-v4-flash-fp8-mtp-norefusal"], DEEPSEEK_MODES, "max"),
+    contract("Qwen3.8", ["qwen3.8-27b-refusal-dial"], QWEN_MODES, "xhigh"),
+]);
+export const RETIRED_MODEL_ALIASES = Object.freeze(chatGptAliases("gpt-5.3-codex"));
+const contractsByAlias = new Map();
+for (const entry of MODEL_CONTRACTS) {
+    for (const alias of entry.aliases) {
+        if (contractsByAlias.has(alias))
+            throw new Error(`Duplicate model contract alias: ${alias}`);
+        contractsByAlias.set(alias, entry);
+    }
+}
+const retiredAliases = new Set(RETIRED_MODEL_ALIASES);
+for (const alias of retiredAliases) {
+    if (contractsByAlias.has(alias))
+        throw new Error(`Active and retired model contract alias collision: ${alias}`);
+}
+export function modelContract(name) {
+    return name === undefined ? undefined : contractsByAlias.get(name);
+}
+export function isRetiredModelAlias(name) {
+    return name !== undefined && retiredAliases.has(name);
+}

package/dist/types.d.ts

@@ -1,4 +1,17 @@
 export type JsonObject = Record<string, unknown>;
+export type ModelContractMode = Readonly<{
+    id: string;
+    legacy: Readonly<JsonObject>;
+    v2Body: Readonly<JsonObject>;
+}>;
+export type ModelContract = Readonly<{
+    family: string;
+    aliases: readonly string[];
+    modes: readonly ModelContractMode[];
+    defaultMode: string;
+    reasoning: true;
+    variantDefault: false;
+}>;
 export type OpenCodeModel = JsonObject & {
     id?: string;
     name?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staticeng/opencode-litellm",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "OpenCode plugin that discovers LiteLLM models at runtime.",
   "type": "module",
   "license": "MIT",