@staticeng/opencode-litellm 0.1.5 → 0.1.7

package/README.md

@@ -1,6 +1,6 @@
 # opencode-litellm
 
-Runtime LiteLLM model autodiscovery for OpenCode. The plugin fetches LiteLLM `/model/info` at OpenCode startup and adds an in-memory provider named `LiteLLM` by default.
+Runtime LiteLLM model autodiscovery for OpenCode. The plugin fetches LiteLLM deployment and model-group metadata at startup and adds an in-memory provider named `LiteLLM` by default.
 
 ## Install
 
@@ -40,17 +40,17 @@ Do not put real API keys in `opencode.json`. If you pass `apiKey` directly, the
 | `baseURL` | `LITELLM_BASE_URL` | LiteLLM proxy base URL. `/v1` URLs are supported. |
 | `apiKey` | env value | Bearer token for LiteLLM. |
 | `apiKeyEnv` | `LITELLM_API_KEY` | Environment variable used when `apiKey` is not set. |
-| `providerKey` | `LiteLLM` | Key written to `cfg.provider[providerKey]`. |
+| `providerKey` | `LiteLLM` | Key written to legacy `cfg.provider` and V2 `cfg.providers`. |
 | `providerName` | `LiteLLM` | Human provider name. |
 | `overrides` | `{}` | Per-model deep-merge overrides. |
 | `providerOverrides` | `{}` | Provider-level deep-merge overrides. |
 | `includeModes` | `chat`, `responses` | LiteLLM modes to include. |
 | `includeModels` | all included modes | Optional allowlist by model name. |
 | `excludeModels` | none | Optional denylist by model name. |
-| `timeoutMs` | `30000` | `/model/info` request timeout. |
+| `timeoutMs` | `30000` | Per-request discovery timeout. |
 | `strict` | `false` | Throw on fetch/mapping failures instead of warning. |
 
-The LiteLLM key must have permission to call `GET /model/info`.
+The LiteLLM key must have permission to call `GET /model/info` and root `GET /model_group/info`.
 
 ## Overrides
 
@@ -88,9 +88,12 @@ Overrides win over generated values through a recursive deep merge. Arrays and s
 
 ## Runtime Behavior
 
-- Fetches `${baseURL}/model/info` with `Authorization: Bearer <token>`.
-- Handles base URLs with or without a trailing slash, including `/v1`.
-- Adds or replaces `cfg.provider[providerKey]` during OpenCode's plugin config hook.
+- Fetches `${baseURL}/model/info`, then root `/model_group/info`, with separate authenticated and timed requests.
+- Preserves `/v1` for model-info discovery but resolves model-group discovery from the LiteLLM origin.
+- 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.
+- 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.
 - Includes `chat` and `responses` modes by default; non-chat modes such as `embedding` and `rerank` are excluded unless explicitly included.
 - No HuggingFace fallback is included in v1.

package/dist/helpers.d.ts

@@ -1,4 +1,5 @@
-export { buildProvider, buildProviderV2, mapModels, mapModelsV2 } from "./mapping.js";
-export { fetchModelInfo } from "./litellm.js";
+export { buildProvider, buildProviderV2, mapModels, mapModelsV2, mergeModelInfo, normalizeModelListResponse, modelListResponseShape, } from "./mapping.js";
+export { fetchModelGroupInfo, fetchModelInfo, normalizeModelGroupResponse } from "./litellm.js";
+export { modelGroupInfoURL, modelInfoURL } from "./options.js";
 export { deepMerge } from "./merge.js";
-export type { LiteLLMModelInfo, LiteLLMPluginOptions, OpenCodeModel, OpenCodeModelV2, OpenCodeProvider, OpenCodeProviderV2, } from "./types.js";
+export type { LiteLLMPluginOptions, LiteLLMModelGroup, LiteLLMModelInfo, OpenCodeProvider, OpenCodeProviderV2, OpenCodeModel, OpenCodeModelV2, } from "./types.js";

package/dist/helpers.js

@@ -1,3 +1,4 @@
-export { buildProvider, buildProviderV2, mapModels, mapModelsV2 } from "./mapping.js";
-export { fetchModelInfo } from "./litellm.js";
+export { buildProvider, buildProviderV2, mapModels, mapModelsV2, mergeModelInfo, normalizeModelListResponse, modelListResponseShape, } from "./mapping.js";
+export { fetchModelGroupInfo, fetchModelInfo, normalizeModelGroupResponse } from "./litellm.js";
+export { modelGroupInfoURL, modelInfoURL } from "./options.js";
 export { deepMerge } from "./merge.js";

package/dist/index.js

@@ -1,5 +1,5 @@
-import { fetchModelInfo } from "./litellm.js";
-import { buildProvider, buildProviderV2 } from "./mapping.js";
+import { fetchModelGroupInfo, fetchModelInfo } from "./litellm.js";
+import { buildProvider, buildProviderV2, 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 } });
@@ -9,7 +9,22 @@ const LiteLLMPlugin = async (ctx, options) => {
     return {
         config: async (cfg) => {
             try {
-                const models = await fetchModelInfo(resolved);
+                const deployments = await fetchModelInfo(resolved);
+                let groups = [];
+                try {
+                    groups = await fetchModelGroupInfo(resolved);
+                }
+                catch (error) {
+                    const errorShape = error instanceof Error && "responseShape" in error ? error.responseShape : undefined;
+                    await log(ctx, resolved.strict ? "error" : "warn", "failed to load LiteLLM model group metadata", {
+                        providerKey: resolved.providerKey,
+                        error: error instanceof Error ? error.message : String(error),
+                        ...(errorShape ? { responseShape: errorShape } : {}),
+                    });
+                    if (resolved.strict)
+                        throw error;
+                }
+                const models = mergeModelInfo(deployments, groups);
                 const provider = buildProvider(models, resolved);
                 const config = cfg;
                 const providerV2 = buildProviderV2(models, resolved);
@@ -28,9 +43,11 @@ const LiteLLMPlugin = async (ctx, options) => {
                 });
             }
             catch (error) {
+                const errorShape = error instanceof Error && "responseShape" in error ? error.responseShape : undefined;
                 await log(ctx, resolved.strict ? "error" : "warn", "failed to load LiteLLM provider metadata", {
                     providerKey: resolved.providerKey,
                     error: error instanceof Error ? error.message : String(error),
+                    ...(errorShape ? { responseShape: errorShape } : {}),
                 });
                 if (resolved.strict)
                     throw error;

package/dist/litellm.d.ts

@@ -1,3 +1,5 @@
 import { type ResolvedOptions } from "./options.js";
 import type { LiteLLMModelInfo } from "./types.js";
 export declare function fetchModelInfo(options: ResolvedOptions, fetchImpl?: typeof fetch): Promise<LiteLLMModelInfo[]>;
+export declare function normalizeModelGroupResponse(response: unknown): LiteLLMModelInfo[];
+export declare function fetchModelGroupInfo(options: ResolvedOptions, fetchImpl?: typeof fetch): Promise<LiteLLMModelInfo[]>;

package/dist/litellm.js

@@ -1,33 +1,69 @@
-import { modelInfoURL } from "./options.js";
-function isModelInfoArray(value) {
-    return Array.isArray(value);
-}
-export async function fetchModelInfo(options, fetchImpl = fetch) {
+import { modelListResponseShape, normalizeModelListResponse } from "./mapping.js";
+import { modelGroupInfoURL, modelInfoURL } from "./options.js";
+function requireCredentials(options) {
     if (!options.baseURL)
         throw new Error("opencode-litellm requires options.baseURL or LITELLM_BASE_URL");
     if (!options.apiKey)
         throw new Error("opencode-litellm requires options.apiKey or the configured apiKeyEnv");
+}
+async function fetchJSON(options, endpoint, url, fetchImpl) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
     try {
-        const response = await fetchImpl(modelInfoURL(options.baseURL), {
-            method: "GET",
-            headers: {
-                Authorization: `Bearer ${options.apiKey}`,
-                Accept: "application/json",
-            },
-            signal: controller.signal,
-        });
-        if (!response.ok)
-            throw new Error(`LiteLLM /model/info returned HTTP ${response.status}`);
-        const body = (await response.json());
-        if (isModelInfoArray(body))
-            return body;
-        if (isModelInfoArray(body.data))
-            return body.data;
-        throw new Error("LiteLLM /model/info response did not contain a data array");
+        try {
+            const response = await fetchImpl(url, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${options.apiKey}`,
+                    Accept: "application/json",
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                throw new Error(`LiteLLM ${endpoint} returned HTTP ${response.status}`);
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith(`LiteLLM ${endpoint}`))
+                throw error;
+            if (controller.signal.aborted)
+                throw new Error(`LiteLLM ${endpoint} timed out after ${options.timeoutMs}ms`);
+            throw new Error(`LiteLLM ${endpoint} request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     finally {
         clearTimeout(timeout);
     }
 }
+export async function fetchModelInfo(options, fetchImpl = fetch) {
+    requireCredentials(options);
+    return normalizeModelListResponse(await fetchJSON(options, "/model/info", modelInfoURL(options.baseURL), fetchImpl));
+}
+export function normalizeModelGroupResponse(response) {
+    const data = typeof response === "object" && response !== null && !Array.isArray(response)
+        ? response.data
+        : undefined;
+    if (!Array.isArray(data)) {
+        throw Object.assign(new Error("LiteLLM /model_group/info response did not contain a data array"), {
+            name: "LiteLLMModelGroupResponseError",
+            responseShape: modelListResponseShape(response),
+        });
+    }
+    return data
+        .filter((group) => typeof group === "object" &&
+        group !== null &&
+        !Array.isArray(group) &&
+        typeof group.model_group === "string" &&
+        Boolean(group.model_group?.trim()))
+        .map(({ model_group, supported_openai_params, ...metadata }) => ({
+        model_name: model_group,
+        model_info: {
+            ...metadata,
+            ...(supported_openai_params === undefined ? {} : { supported_params: supported_openai_params }),
+        },
+    }));
+}
+export async function fetchModelGroupInfo(options, fetchImpl = fetch) {
+    requireCredentials(options);
+    return normalizeModelGroupResponse(await fetchJSON(options, "/model_group/info", modelGroupInfoURL(options.baseURL), fetchImpl));
+}

package/dist/mapping.d.ts

@@ -1,9 +1,20 @@
 import type { LiteLLMModelInfo, LiteLLMPluginOptions, OpenCodeModel, OpenCodeModelV2, OpenCodeProvider, OpenCodeProviderV2 } from "./types.js";
-export declare function mapModels(models: LiteLLMModelInfo[], options?: LiteLLMPluginOptions): {
+export type ModelListResponseShape = {
+    type: string;
+    length?: number;
+    keyCount?: number;
+    arrayFields?: string[];
+    objectValueCount?: number;
+    scalarValueCount?: number;
+};
+export declare function modelListResponseShape(value: unknown): ModelListResponseShape;
+export declare function mergeModelInfo(deployments: LiteLLMModelInfo[], groups: LiteLLMModelInfo[]): LiteLLMModelInfo[];
+export declare function normalizeModelListResponse(response: unknown): LiteLLMModelInfo[];
+export declare function mapModels(response: unknown, options?: LiteLLMPluginOptions): {
     [k: string]: OpenCodeModel;
 };
-export declare function buildProvider(models: LiteLLMModelInfo[], options?: LiteLLMPluginOptions): OpenCodeProvider;
-export declare function mapModelsV2(models: LiteLLMModelInfo[], options?: LiteLLMPluginOptions): {
+export declare function buildProvider(models: unknown, options?: LiteLLMPluginOptions): OpenCodeProvider;
+export declare function mapModelsV2(models: unknown, options?: LiteLLMPluginOptions): {
     [k: string]: OpenCodeModelV2;
 };
-export declare function buildProviderV2(models: LiteLLMModelInfo[], options?: LiteLLMPluginOptions): OpenCodeProviderV2;
+export declare function buildProviderV2(models: unknown, options?: LiteLLMPluginOptions): OpenCodeProviderV2;

package/dist/mapping.js

@@ -3,6 +3,60 @@ const DEFAULT_MODES = new Set(["chat", "responses"]);
 const NON_CHAT_MODES = new Set(["embedding", "rerank"]);
 const TEXT_MODALITY = "text";
 const TEXT_ONLY_MODELS = new Set(["minimax-m2.7", "minimax_m2.7"]);
+const NUMERIC_MODEL_INFO_FIELDS = new Set([
+    "input_cost_per_token",
+    "output_cost_per_token",
+    "cache_creation_input_token_cost",
+    "cache_read_input_token_cost",
+    "max_tokens",
+    "max_input_tokens",
+    "max_output_tokens",
+]);
+const MODEL_LIST_RESPONSE_ERROR_MESSAGE = "LiteLLM model list response did not contain a model array";
+const MODEL_ARRAY_FIELDS = ["data", "models", "model_info"];
+const MODEL_INFO_FIELDS = new Set([
+    "id",
+    "base_model",
+    "mode",
+    "input_cost_per_token",
+    "output_cost_per_token",
+    "max_tokens",
+    "max_input_tokens",
+    "max_output_tokens",
+    "supports_function_calling",
+    "supports_tool_choice",
+    "supports_vision",
+    "supports_pdf_input",
+    "supports_reasoning",
+    "supported_modalities",
+    "output_modalities",
+    "supported_params",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function modelListResponseShape(value) {
+    if (Array.isArray(value))
+        return { type: "array", length: value.length };
+    if (value === null)
+        return { type: "null" };
+    if (!isRecord(value))
+        return { type: typeof value };
+    const values = Object.values(value);
+    return {
+        type: "object",
+        keyCount: Object.keys(value).length,
+        arrayFields: MODEL_ARRAY_FIELDS.filter((field) => Array.isArray(value[field])),
+        objectValueCount: values.filter(isRecord).length,
+        scalarValueCount: values.filter((entry) => !isRecord(entry) && !Array.isArray(entry)).length,
+    };
+}
+function modelListResponseError(response) {
+    return Object.assign(new Error(MODEL_LIST_RESPONSE_ERROR_MESSAGE), {
+        name: "LiteLLMModelListResponseError",
+        responseShape: modelListResponseShape(response),
+    });
+}
 function asString(value) {
     return typeof value === "string" && value.trim() ? value : undefined;
 }
@@ -17,9 +71,85 @@ function perMillion(value) {
 function unique(values) {
     return Array.from(new Set(values));
 }
+function isValidMetadata(value, key) {
+    if (value === undefined || value === null || value === "")
+        return false;
+    if (key && NUMERIC_MODEL_INFO_FIELDS.has(key))
+        return asNumber(value) !== undefined;
+    if (typeof value === "number")
+        return Number.isFinite(value) && value > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+function enrichMetadata(existing, incoming, key) {
+    if (Array.isArray(existing) && Array.isArray(incoming))
+        return unique([...existing, ...incoming].filter(asString));
+    if (isRecord(existing) && isRecord(incoming)) {
+        const merged = { ...existing };
+        for (const [nestedKey, value] of Object.entries(incoming)) {
+            merged[nestedKey] = enrichMetadata(merged[nestedKey], value, nestedKey);
+        }
+        return merged;
+    }
+    if (typeof existing === "boolean" && typeof incoming === "boolean")
+        return existing || incoming;
+    if (isValidMetadata(existing, key))
+        return existing;
+    return isValidMetadata(incoming, key) ? incoming : existing;
+}
 function modelName(model) {
     return asString(model.model_name) ?? asString(model.litellm_params?.model) ?? asString(model.model_info?.id);
 }
+export function mergeModelInfo(deployments, groups) {
+    const byName = new Map();
+    for (const model of [...deployments, ...groups]) {
+        const name = modelName(model);
+        if (!name)
+            continue;
+        const existing = byName.get(name);
+        byName.set(name, existing ? enrichMetadata(existing, model) : model);
+    }
+    return Array.from(byName.values());
+}
+function hasModelInfoFields(value) {
+    return Object.keys(value).some((key) => MODEL_INFO_FIELDS.has(key));
+}
+function isPlausibleMappedModel(value) {
+    if (isRecord(value.model_info) && hasModelInfoFields(value.model_info))
+        return true;
+    if (isRecord(value.litellm_params) && typeof value.litellm_params.model === "string")
+        return true;
+    return hasModelInfoFields(value);
+}
+function normalizeMappedModel(name, value) {
+    if (!isRecord(value))
+        return undefined;
+    const model = value;
+    if (modelName(model))
+        return model;
+    if (!isPlausibleMappedModel(value))
+        return undefined;
+    return { ...model, model_name: name };
+}
+export function normalizeModelListResponse(response) {
+    if (Array.isArray(response))
+        return response;
+    if (isRecord(response)) {
+        for (const field of MODEL_ARRAY_FIELDS) {
+            if (Array.isArray(response[field]))
+                return response[field];
+        }
+        if (MODEL_ARRAY_FIELDS.some((field) => field in response))
+            throw modelListResponseError(response);
+        const mappedModels = Object.entries(response)
+            .map(([name, value]) => normalizeMappedModel(name, value))
+            .filter((model) => Boolean(model));
+        if (mappedModels.length > 0)
+            return mappedModels;
+    }
+    throw modelListResponseError(response);
+}
 function mode(model) {
     return asString(model.model_info?.mode) ?? "chat";
 }
@@ -129,13 +259,15 @@ function generatedModel(model) {
 }
 function v2Variants(model) {
     const variants = model.variants;
-    if (!variants || typeof variants !== "object" || Array.isArray(variants))
+    if (!isRecord(variants))
         return undefined;
     return Object.entries(variants).map(([id, value]) => {
-        const raw = value && typeof value === "object" && !Array.isArray(value) ? value : {};
-        const body = raw.options && typeof raw.options === "object" && !Array.isArray(raw.options)
-            ? raw.options
-            : raw;
+        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 };
     });
 }
@@ -155,6 +287,7 @@ function v2Model(model, baseURL) {
         },
         capabilities: {
             tools: model.tool_call ?? false,
+            reasoning: model.reasoning ?? false,
             input: model.modalities?.input ?? [TEXT_MODALITY],
             output: model.modalities?.output ?? [TEXT_MODALITY],
         },
@@ -163,7 +296,8 @@ function v2Model(model, baseURL) {
         ...(v2Variants(model) ? { variants: v2Variants(model) } : {}),
     };
 }
-export function mapModels(models, options = {}) {
+export function mapModels(response, options = {}) {
+    const models = normalizeModelListResponse(response);
     return Object.fromEntries(models
         .filter((model) => allowedByFilters(model, options))
         .map((model) => {
@@ -178,10 +312,11 @@ export function buildProvider(models, options = {}) {
         id: options.providerKey ?? "LiteLLM",
         name: options.providerName ?? "LiteLLM",
         npm: "@ai-sdk/openai-compatible",
-        api: "openai-compatible",
+        api: options.baseURL,
         options: {
             baseURL: options.baseURL,
             apiKey: options.apiKey,
+            ...(options.apiKey ? { body: { apiKey: options.apiKey } } : {}),
         },
         models: mapModels(models, options),
     }, options.providerOverrides);
@@ -191,7 +326,7 @@ export function mapModelsV2(models, options = {}) {
     return Object.fromEntries(Object.entries(legacy).map(([name, model]) => [name, v2Model(model, options.baseURL)]));
 }
 export function buildProviderV2(models, options = {}) {
-    return {
+    return deepMerge({
         name: options.providerName ?? "LiteLLM",
         api: {
             type: "aisdk",
@@ -205,5 +340,5 @@ export function buildProviderV2(models, options = {}) {
             },
         },
         models: mapModelsV2(models, options),
-    };
+    }, options.providerOverrides);
 }

package/dist/options.d.ts

@@ -2,3 +2,4 @@ import type { LiteLLMPluginOptions } from "./types.js";
 export type ResolvedOptions = Required<Pick<LiteLLMPluginOptions, "providerKey" | "providerName" | "timeoutMs" | "strict">> & Omit<LiteLLMPluginOptions, "providerKey" | "providerName" | "timeoutMs" | "strict">;
 export declare function resolveOptions(options?: LiteLLMPluginOptions): ResolvedOptions;
 export declare function modelInfoURL(baseURL: string): string;
+export declare function modelGroupInfoURL(baseURL: string): string;

package/dist/options.js

@@ -18,3 +18,6 @@ export function resolveOptions(options = {}) {
 export function modelInfoURL(baseURL) {
     return `${baseURL.replace(/\/+$/, "")}/model/info`;
 }
+export function modelGroupInfoURL(baseURL) {
+    return new URL("/model_group/info", baseURL).toString();
+}

package/dist/types.d.ts

@@ -33,6 +33,7 @@ export type OpenCodeModelV2 = JsonObject & {
     };
     capabilities?: {
         tools: boolean;
+        reasoning: boolean;
         input: string[];
         output: string[];
     };
@@ -123,8 +124,29 @@ export type LiteLLMModelInfo = JsonObject & {
         supported_params?: string[];
     };
 };
-export type LiteLLMModelInfoResponse = {
+export type LiteLLMModelInfoResponse = LiteLLMModelInfo[] | {
     data?: LiteLLMModelInfo[];
+    models?: LiteLLMModelInfo[];
+    model_info?: LiteLLMModelInfo[];
+};
+export type LiteLLMModelGroup = JsonObject & {
+    model_group?: string;
+    mode?: string;
+    input_cost_per_token?: number | string;
+    output_cost_per_token?: number | string;
+    cache_creation_input_token_cost?: number | string;
+    cache_read_input_token_cost?: number | string;
+    max_tokens?: number | string;
+    max_input_tokens?: number | string;
+    max_output_tokens?: number | string;
+    supports_function_calling?: boolean;
+    supports_tool_choice?: boolean;
+    supports_vision?: boolean;
+    supports_pdf_input?: boolean;
+    supports_reasoning?: boolean;
+    supported_modalities?: string[];
+    output_modalities?: string[];
+    supported_openai_params?: string[];
 };
 export type OpenCodeConfig = {
     provider?: Record<string, OpenCodeProvider>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staticeng/opencode-litellm",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "OpenCode plugin that discovers LiteLLM models at runtime.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "node --test test/*.test.mjs",
+    "test": "node --test --test-concurrency=1 test/*.test.mjs",
     "prepack": "npm run build"
   },
   "peerDependencies": {