@staticeng/opencode-litellm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StaticDuo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# 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.
+
+## Install
+
+Install the package by npm name, then add it to OpenCode `plugin` config:
+
+```sh
+npm install @staticeng/opencode-litellm
+```
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "@staticeng/opencode-litellm",
+      {
+        "baseURL": "https://litellm.example.com/v1",
+        "apiKeyEnv": "LITELLM_API_KEY"
+      }
+    ]
+  ]
+}
+```
+
+Set the API key in your environment before starting OpenCode:
+
+```sh
+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.
+
+## Options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `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]`. |
+| `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. |
+| `strict` | `false` | Throw on fetch/mapping failures instead of warning. |
+
+The LiteLLM key must have permission to call `GET /model/info`.
+
+## 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.
+
+```json
+{
+  "plugin": [
+    [
+      "@staticeng/opencode-litellm",
+      {
+        "baseURL": "https://litellm.example.com/v1",
+        "apiKeyEnv": "LITELLM_API_KEY",
+        "overrides": {
+          "chatgpt/gpt-5.5": {
+            "limit": { "context": 262144, "output": 128000 },
+            "variants": {
+              "high": { "options": { "reasoning_effort": "high" } }
+            },
+            "interleaved": { "field": "reasoning_details" }
+          }
+        },
+        "providerOverrides": {
+          "options": {
+            "timeout": 600000
+          }
+        }
+      }
+    ]
+  ]
+}
+```
+
+Overrides win over generated values through a recursive deep merge. Arrays and scalar values are replaced rather than concatenated.
+
+## 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.
+- 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.
+
+## Publish Notes
+
+The package is ESM-only and publishes the compiled `dist/` directory.
+
+```sh
+npm install
+npm run build
+npm test
+npm pack --dry-run
+```
+
+Confirm package contents before publishing and keep secrets out of fixtures, docs, logs, and config examples.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { Config, PluginInput } from "@opencode-ai/plugin";
+import type { LiteLLMPluginOptions } from "./types.js";
+export declare const LiteLLMPlugin: (ctx: PluginInput, options?: LiteLLMPluginOptions) => Promise<{
+    config: (cfg: Config) => Promise<void>;
+}>;
+export default LiteLLMPlugin;
+export { buildProvider, mapModels } from "./mapping.js";
+export { fetchModelInfo } from "./litellm.js";
+export { deepMerge } from "./merge.js";
+export type { LiteLLMPluginOptions, LiteLLMModelInfo, OpenCodeProvider, OpenCodeModel } from "./types.js";

package/dist/index.js

@@ -0,0 +1,37 @@
+import { fetchModelInfo } from "./litellm.js";
+import { buildProvider } 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 } });
+}
+export const LiteLLMPlugin = async (ctx, options) => {
+    const resolved = resolveOptions(options);
+    return {
+        config: async (cfg) => {
+            try {
+                const models = await fetchModelInfo(resolved);
+                const provider = buildProvider(models, resolved);
+                cfg.provider = {
+                    ...(cfg.provider ?? {}),
+                    [resolved.providerKey]: provider,
+                };
+                await log(ctx, "info", "loaded LiteLLM provider metadata", {
+                    providerKey: resolved.providerKey,
+                    modelCount: Object.keys(provider.models ?? {}).length,
+                });
+            }
+            catch (error) {
+                await log(ctx, resolved.strict ? "error" : "warn", "failed to load LiteLLM provider metadata", {
+                    providerKey: resolved.providerKey,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                if (resolved.strict)
+                    throw error;
+            }
+        },
+    };
+};
+export default LiteLLMPlugin;
+export { buildProvider, mapModels } from "./mapping.js";
+export { fetchModelInfo } from "./litellm.js";
+export { deepMerge } from "./merge.js";

package/dist/litellm.d.ts

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

package/dist/litellm.js

@@ -0,0 +1,33 @@
+import { modelInfoURL } from "./options.js";
+function isModelInfoArray(value) {
+    return Array.isArray(value);
+}
+export async function fetchModelInfo(options, fetchImpl = fetch) {
+    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");
+    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");
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/mapping.d.ts

@@ -0,0 +1,5 @@
+import type { LiteLLMModelInfo, LiteLLMPluginOptions, OpenCodeModel, OpenCodeProvider } from "./types.js";
+export declare function mapModels(models: LiteLLMModelInfo[], options?: LiteLLMPluginOptions): {
+    [k: string]: OpenCodeModel;
+};
+export declare function buildProvider(models: LiteLLMModelInfo[], options?: LiteLLMPluginOptions): OpenCodeProvider;

package/dist/mapping.js

@@ -0,0 +1,120 @@
+import { deepMerge } from "./merge.js";
+const DEFAULT_MODES = new Set(["chat", "responses"]);
+const NON_CHAT_MODES = new Set(["embedding", "rerank"]);
+const TEXT_MODALITY = "text";
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function asNumber(value) {
+    const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+function perMillion(value) {
+    const parsed = asNumber(value);
+    return parsed === undefined ? undefined : Number((parsed * 1_000_000).toPrecision(12));
+}
+function unique(values) {
+    return Array.from(new Set(values));
+}
+function modelName(model) {
+    return asString(model.model_name) ?? asString(model.litellm_params?.model) ?? asString(model.model_info?.id);
+}
+function mode(model) {
+    return asString(model.model_info?.mode) ?? "chat";
+}
+function allowedByFilters(model, options) {
+    const name = modelName(model);
+    if (!name)
+        return false;
+    if (options.includeModels?.length && !options.includeModels.includes(name))
+        return false;
+    if (options.excludeModels?.includes(name))
+        return false;
+    const modelMode = mode(model);
+    if (options.includeModes?.length)
+        return options.includeModes.includes(modelMode);
+    return DEFAULT_MODES.has(modelMode) && !NON_CHAT_MODES.has(modelMode);
+}
+function cost(model) {
+    const input = perMillion(model.model_info?.input_cost_per_token);
+    const output = perMillion(model.model_info?.output_cost_per_token);
+    if (input === undefined || output === undefined)
+        return undefined;
+    return {
+        input,
+        output,
+        ...(perMillion(model.model_info?.cache_creation_input_token_cost) === undefined
+            ? {}
+            : { cache_write: perMillion(model.model_info?.cache_creation_input_token_cost) }),
+        ...(perMillion(model.model_info?.cache_read_input_token_cost) === undefined
+            ? {}
+            : { cache_read: perMillion(model.model_info?.cache_read_input_token_cost) }),
+    };
+}
+function limit(model) {
+    const context = asNumber(model.model_info?.max_input_tokens) ?? asNumber(model.model_info?.max_tokens);
+    const output = asNumber(model.model_info?.max_output_tokens) ?? asNumber(model.model_info?.max_tokens);
+    if (context === undefined || output === undefined)
+        return undefined;
+    return {
+        context,
+        ...(asNumber(model.model_info?.max_input_tokens) === undefined ? {} : { input: asNumber(model.model_info?.max_input_tokens) }),
+        output,
+    };
+}
+function modalities(model) {
+    return {
+        input: unique([
+            TEXT_MODALITY,
+            ...(model.model_info?.supported_modalities ?? []),
+            ...(model.model_info?.supports_vision ? ["image"] : []),
+            ...(model.model_info?.supports_pdf_input ? ["pdf"] : []),
+        ]),
+        output: unique([TEXT_MODALITY, ...(model.model_info?.output_modalities ?? [])]),
+    };
+}
+function supportsReasoning(model) {
+    return Boolean(model.model_info?.supports_reasoning ||
+        model.model_info?.supported_params?.includes("reasoning_effort") ||
+        model.model_info?.supported_params?.includes("thinking"));
+}
+function generatedModel(model) {
+    const name = modelName(model);
+    if (!name)
+        return undefined;
+    const mappedModalities = modalities(model);
+    return {
+        id: asString(model.model_info?.id) ?? name,
+        name,
+        ...(asString(model.model_info?.base_model) ? { family: asString(model.model_info?.base_model) } : {}),
+        ...(cost(model) ? { cost: cost(model) } : {}),
+        ...(limit(model) ? { limit: limit(model) } : {}),
+        modalities: mappedModalities,
+        ...(mappedModalities.input.includes("image") || mappedModalities.input.includes("pdf") ? { attachment: true } : {}),
+        ...(supportsReasoning(model) ? { reasoning: true } : {}),
+        ...(model.model_info?.supports_function_calling || model.model_info?.supports_tool_choice ? { tool_call: true } : {}),
+    };
+}
+export function mapModels(models, options = {}) {
+    return Object.fromEntries(models
+        .filter((model) => allowedByFilters(model, options))
+        .map((model) => {
+        const name = modelName(model);
+        const generated = generatedModel(model);
+        return name && generated ? [name, deepMerge(generated, options.overrides?.[name])] : undefined;
+    })
+        .filter((entry) => Boolean(entry)));
+}
+export function buildProvider(models, options = {}) {
+    return deepMerge({
+        id: options.providerKey ?? "LiteLLM",
+        name: options.providerName ?? "LiteLLM",
+        npm: "@ai-sdk/openai-compatible",
+        api: "openai-compatible",
+        options: {
+            baseURL: options.baseURL,
+            apiKey: options.apiKey,
+        },
+        models: mapModels(models, options),
+    }, options.providerOverrides);
+}

package/dist/merge.d.ts

@@ -0,0 +1 @@
+export declare function deepMerge<T extends Record<string, unknown>>(base: T, override?: Record<string, unknown>): T;

package/dist/merge.js

@@ -0,0 +1,11 @@
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function deepMerge(base, override) {
+    if (!override)
+        return { ...base };
+    return Object.entries(override).reduce((merged, [key, value]) => ({
+        ...merged,
+        [key]: isPlainObject(merged[key]) && isPlainObject(value) ? deepMerge(merged[key], value) : value,
+    }), { ...base });
+}

package/dist/options.d.ts

@@ -0,0 +1,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;

package/dist/options.js

@@ -0,0 +1,20 @@
+function readEnv(name) {
+    if (!name)
+        return undefined;
+    return typeof process === "undefined" ? undefined : process.env[name];
+}
+export function resolveOptions(options = {}) {
+    return {
+        ...options,
+        baseURL: options.baseURL ?? readEnv("LITELLM_BASE_URL"),
+        apiKey: options.apiKey ?? readEnv(options.apiKeyEnv ?? "LITELLM_API_KEY"),
+        apiKeyEnv: options.apiKeyEnv ?? "LITELLM_API_KEY",
+        providerKey: options.providerKey ?? "LiteLLM",
+        providerName: options.providerName ?? "LiteLLM",
+        timeoutMs: options.timeoutMs ?? 30_000,
+        strict: options.strict ?? false,
+    };
+}
+export function modelInfoURL(baseURL) {
+    return `${baseURL.replace(/\/+$/, "")}/model/info`;
+}

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+export type JsonObject = Record<string, unknown>;
+export type OpenCodeModel = JsonObject & {
+    id?: string;
+    name?: string;
+    cost?: {
+        input: number;
+        output: number;
+        cache_read?: number;
+        cache_write?: number;
+    };
+    limit?: {
+        context: number;
+        input?: number;
+        output: number;
+    };
+    modalities?: {
+        input: string[];
+        output: string[];
+    };
+    attachment?: boolean;
+    reasoning?: boolean;
+    tool_call?: boolean;
+};
+export type OpenCodeProvider = JsonObject & {
+    id?: string;
+    name?: string;
+    npm?: string;
+    api?: string;
+    options?: JsonObject;
+    models: Record<string, OpenCodeModel>;
+};
+export type LiteLLMPluginOptions = {
+    baseURL?: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    providerKey?: string;
+    providerName?: string;
+    overrides?: Record<string, JsonObject>;
+    providerOverrides?: JsonObject;
+    includeModes?: string[];
+    excludeModels?: string[];
+    includeModels?: string[];
+    timeoutMs?: number;
+    strict?: boolean;
+};
+export type LiteLLMModelInfo = JsonObject & {
+    model_name?: string;
+    litellm_params?: JsonObject & {
+        model?: string;
+    };
+    model_info?: JsonObject & {
+        id?: string;
+        base_model?: 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_params?: string[];
+    };
+};
+export type LiteLLMModelInfoResponse = {
+    data?: LiteLLMModelInfo[];
+};
+export type OpenCodeConfig = {
+    provider?: Record<string, OpenCodeProvider>;
+};
+export type PluginContext = {
+    client?: {
+        app?: {
+            log?: (input: {
+                body: {
+                    service: string;
+                    level: "info" | "warn" | "error" | "debug";
+                    message: string;
+                    extra?: JsonObject;
+                };
+            }) => Promise<unknown>;
+        };
+    };
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@staticeng/opencode-litellm",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that discovers LiteLLM models at runtime.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "litellm",
+    "models"
+  ]
+}