@staticeng/opencode-litellm 0.3.2 → 0.3.4

package/README.md

@@ -4,20 +4,23 @@ Runtime LiteLLM model autodiscovery for OpenCode. The plugin fetches LiteLLM dep
 
 ## Install
 
-For OpenCode V2, add the published package to `~/.config/opencode/opencode.json`.
-OpenCode downloads npm plugins automatically; no manual `npm install` is needed.
+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",
-  "plugins": [
-    {
-      "package": "@staticeng/opencode-litellm@0.3.0",
-      "options": {
+  "plugin": [
+    [
+      "@staticeng/opencode-litellm",
+      {
         "baseURL": "https://litellm.example.com/v1",
         "apiKeyEnv": "LITELLM_API_KEY"
       }
-    }
+    ]
   ]
 }
 ```
@@ -32,15 +35,27 @@ Do not put real API keys in `opencode.json`. If you pass `apiKey` directly, the
 
 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.
 
-Version 0.3.0 exposes native V2 `id`/`setup` and a V1 `server` entrypoint.
-V1 object entrypoints require OpenCode 1.18.29 or newer; use the V1 `plugin`
-package-and-options tuple on those releases. OpenCode V2 uses `plugins` and
-the object shown above. Versions through 0.2.7 only expose V1 hooks.
+### OpenCode V2
+
+OpenCode V2 loads plugins from `plugins` (plural). Use the package name as the entrypoint; its default export supports the V2 loader. The `./v2` export is also available for direct imports. The current API is tested against OpenCode V2 2.0.16 and `@opencode/plugin` 2.0.16; the transitional `@opencode-ai/plugin` catalog API remains supported. The dual V1/V2 default entrypoint supports V1 1.18.29 and newer; older V1 releases that require a default-exported function need an earlier package version.
+
+```json
+{
+  "plugins": [
+    {
+      "package": "@staticeng/opencode-litellm",
+      "options": {
+        "baseURL": "https://litellm.example.com/v1",
+        "apiKeyEnv": "LITELLM_API_KEY"
+      }
+    }
+  ]
+}
+```
+
+V2 adds the provider and models through in-memory transforms. It uses the same options and environment variables as V1.
 
-After changing the package version, reload configuration or start a new OpenCode
-process, then use `/models` to select a model under `LiteLLM`. For synchronized
-setups, edit the authoritative configuration once and wait for Syncthing to
-deliver it to each peer. Each host installs its own npm package cache.
+Current V2 uses the drivers bundled in the OpenCode executable: `@opencode/ai/providers/openai-compatible` for Chat Completions and `@opencode/ai/providers/openai/responses` for Responses. GPT names and LiteLLM `mode: responses` metadata select Responses, including opaque aliases. Models marked `use_responses_lite: true` receive `reasoning.context: all_turns`. Explicit model overrides still win. OpenCode 2.0.16 does not bundle the SDK's `openai-compatible/responses` entrypoint; the plugin normalizes that override to the bundled Responses driver as well.
 
 ## Options
 
@@ -49,7 +64,7 @@ deliver it to each peer. Each host installs its own npm package cache.
 | `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` | Provider ID registered in OpenCode. |
+| `providerKey` | `LiteLLM` | Provider ID in the V1 runtime config or V2 catalog. |
 | `providerName` | `LiteLLM` | Human provider name. |
 | `overrides` | `{}` | Per-model deep-merge overrides. |
 | `providerOverrides` | `{}` | Provider-level deep-merge overrides. |
@@ -58,40 +73,49 @@ deliver it to each peer. Each host installs its own npm package cache.
 | `includeBackends` | unset | Optional exact allowlist by `model_info.backend`, unioned with `includeModels` pins. |
 | `excludeModels` | none | Optional denylist by model name. |
 | `timeoutMs` | `30000` | Per-request discovery timeout. |
+| `startupRetryMs` | `120000` | Startup grace period for transient DNS/network, timeout and HTTP 408/429/5xx failures. Uses exponential backoff up to 10 seconds. Set `0` to make one attempt. |
+| `recoveryIntervalMs` | `30000` | Current V2 makes one background discovery attempt per interval after startup grace expires, then reloads the provider catalog when it recovers. Retries until success or plugin unload. Set `0` to disable. |
 | `strict` | `false` | Throw on fetch/mapping failures instead of warning. |
 
 The LiteLLM key must have permission to call `GET /model/info` and root `GET /model_group/info`.
 
+### Starting before the network is ready
+
+At boot, a user service can start before DNS or the LiteLLM endpoint is reachable,
+even with `After=network-online.target`. Transient failures now retry during the
+startup grace period. In current OpenCode V2, non-strict mode also recovers after
+that period without restarting OpenCode or OpenChamber: it registers the provider
+and reloads the live catalog once discovery succeeds. Recovery timers and in-flight
+requests stop when the plugin unloads. No generated model data is written to your
+configuration. Authentication errors and invalid metadata fail immediately.
+
+Strict mode throws if discovery still fails after startup grace. Legacy and
+transitional APIs use startup retries; recovery after that grace period requires
+the current V2 provider reload API.
+
 When `includeBackends` is present, models are candidates when `model_info.backend` exactly and case-sensitively matches an entry or their exact model name is pinned by `includeModels`. Backend values are not trimmed, normalized, or partially matched; missing and non-string values do not match. An empty `includeBackends` matches no backends, so without model pins it includes no models. `excludeModels` always wins over backend matches and pins, and candidates must still pass `includeModes` (or the default `chat` and `responses` modes). When `includeBackends` is omitted, `includeModels` retains its historical behavior: a non-empty array is a model-name allowlist, while an omitted or empty array imposes no model-name allowlist.
 
 ## Overrides
 
 LiteLLM metadata does not expose every OpenCode model field. The plugin includes exact built-in contracts for the currently approved GPT-5.4, GPT-5.5, GPT-5.6, GPT-6 Luna and Sol, 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. Known contracts contribute their approved defaults; discovered extra efforts remain available unless that exact contract explicitly closes discovery. Currently only `qwen3.8-flash-next` closes discovery so unverified efforts cannot become active. No substring, suffix, provider namespace, or base-model inference is used.
+When LiteLLM publishes `model_info.supported_reasoning_efforts`, the plugin maps that list to OpenCode variants automatically. Known contracts contribute their approved defaults; discovered extra efforts remain available unless that exact contract explicitly closes discovery. `qwen3.8-flash-next` and `gpt-6.1-sol` close discovery so unsupported efforts cannot become active. No substring, suffix, provider namespace, or base-model inference is used.
 
 ```json
 {
-  "plugins": [
-    {
-      "package": "@staticeng/opencode-litellm@0.3.0",
-      "options": {
+  "plugin": [
+    [
+      "@staticeng/opencode-litellm",
+      {
         "baseURL": "https://litellm.example.com/v1",
         "apiKeyEnv": "LITELLM_API_KEY",
         "overrides": {
           "chatgpt/gpt-5.5": {
-            "limit": {
-              "context": 262144,
-              "output": 128000
-            },
+            "limit": { "context": 262144, "output": 128000 },
             "variants": {
-              "high": {
-                "reasoningEffort": "high"
-              }
+              "high": { "reasoningEffort": "high" }
             },
-            "interleaved": {
-              "field": "reasoning_details"
-            }
+            "interleaved": { "field": "reasoning_details" }
           }
         },
         "providerOverrides": {
@@ -100,7 +124,7 @@ When LiteLLM publishes `model_info.supported_reasoning_efforts`, the plugin maps
           }
         }
       }
-    }
+    ]
   ]
 }
 ```
@@ -140,25 +164,28 @@ The built-in mode matrix is:
 | GPT-5.5 | `none`, `low`, `medium`, `high`, `xhigh` | `medium` |
 | GPT-5.6 Luna / Sol / Terra | `none`, `low`, `medium`, `high`, `xhigh`, `max` | `medium` |
 | DeepSeek V4 Flash | `off`, `low`, `high`, `max` | `max` |
+| DeepSeek V4.1 Flash 1017 | `off`, `low`, `high`, `max` | `high` |
 | Qwen3.8 27B refusal dial | `off`, `low`, `medium`, `xhigh` | `xhigh` |
 | Qwen3.8 Flash Next | `off`, `low`, `medium`, `xhigh` | `xhigh` |
 
-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. Flash Next activates exactly `off`, `low`, `medium`, and `xhigh`: discovered extras such as `ultra` are suppressed, V2 omits `minimal`, `high`, and `max`, and the legacy OpenCode surface disables unsupported generic choices. 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 model's default effort before serialization. The `variantDefault` compatibility marker is UI-only and is stripped before requests for exact built-in aliases.
+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. Flash Next activates exactly `off`, `low`, `medium`, and `xhigh`: discovered extras such as `ultra` are suppressed, V2 omits `minimal`, `high`, and `max`, and the legacy OpenCode surface disables unsupported generic choices. V1 supplies the contract default through model options and removes the default effort in its `chat.params` hook for Qwen `off`. Transitional V2 selects the default with `model.request.variant`. Current V2 applies the selected default variant's body and headers to outbound requests when no explicit variant is selected; an explicit `off` variant therefore has no inherited default effort. A request-level reasoning effort takes precedence. The `variantDefault` compatibility marker applies only to V1 and is stripped before requests for exact built-in aliases.
 
 The exact dynamically discovered alias `qwen3.8-flash-next` also receives verified static metadata that overrides incomplete or conflicting LiteLLM group metadata: text and image input, text output, attachment, reasoning, tool calling, and a 262144-token context. Its output limit remains unknown and is represented by the package's `0` sentinel; pricing and other modalities are not supplied. The contract is still discovery-gated and never creates the alias when LiteLLM omits it.
 
+The exact alias `deepseek-v4.1-flash-1017` receives verified static metadata from the official model card and deployed LiteLLM metadata: text and image input, text output, tool calling, a 1048576-token context, and a 262144-token output limit. Pricing remains discovery-owned. The V4.1 encoder documents `chat` and `thinking` modes with `low`, `high`, and `max` effort aliases; the plugin exposes `off` as the LiteLLM/vLLM `reasoning_effort=none` compatibility mode. Only `off`, `low`, `high`, and `max` are active, defaulting to `high`; extra discovery efforts are suppressed. The contract remains discovery-gated.
+
 Normal GPT-5.3 Codex and GPT-5.3 Codex Spark aliases are retired and filtered even if stale discovery metadata still reports them. Unlisted aliases such as `defend/gpt-5.5` do not inherit a contract.
 
 ## Runtime Behavior
 
 - 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.
-- Registers the provider and models with the native V2 provider transform API; V1 uses the config hook.
+- V1 updates `cfg.provider[providerKey]` and the migration-era `cfg.providers[providerKey]` in memory; transitional V2 registers a catalog transform, while current V2 registers a provider transform and scoped session hooks.
 - 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.
 - Applies exact built-in model contracts as defaults, then applies explicit model and provider overrides last.
 - Filters retired normal and Spark GPT-5.3 Codex aliases without redirecting them.
-- Warns safely and keeps deployment models when group discovery fails in non-strict mode; strict mode mutates neither config surface on failure.
+- Warns safely and keeps deployment models when group discovery fails in non-strict mode; strict mode skips registration or config mutation 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
   limit. The zero sentinel retains known metadata without inventing a positive output allowance.
@@ -176,9 +203,11 @@ npm test
 npm pack --dry-run
 ```
 
+With the OpenCode 2.0.16 executable installed, run `OPENCODE_V2_CLI_TEST=1 node --test test/v2-cli.test.mjs` after building. Set `OPENCODE_V2_CLI` to override the executable path. This isolated test uses mock HTTP endpoints and temporary configuration to check the binary's provider loading, Responses aliases, and Qwen reasoning modes without real credentials.
+
 Confirm package contents before publishing and keep secrets out of fixtures, docs, logs, and config examples.
 
-The GitHub release workflow supports npm trusted publishing from the `npm-production` environment. Provenance
+Publishing uses npm trusted publishing from the `npm-production` GitHub environment. Provenance
 requires this GitHub repository to remain public. Before a release, configure npm's trusted
 publisher for package `@staticeng/opencode-litellm` with this repository, workflow
 `publish.yml`, and environment `npm-production`; no npm token is used by the workflow.

package/dist/discovery.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedOptions } from "./options.js";
+export declare function isTransient(error: unknown): boolean;
+export declare function waitForRetry(ms: number, signal: AbortSignal): Promise<void>;
+/** Retry only transient failures; the grace deadline includes requests and backoff. */
+export declare function discoverWithRetry<T>(load: (options: ResolvedOptions, signal: AbortSignal) => Promise<T>, options: ResolvedOptions, signal?: AbortSignal): Promise<T>;

package/dist/discovery.js

@@ -0,0 +1,33 @@
+export function isTransient(error) {
+    return error instanceof Error && "retryable" in error && error.retryable === true;
+}
+export function waitForRetry(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(new Error("LiteLLM discovery cancelled"));
+        const abort = () => { clearTimeout(timer); reject(new Error("LiteLLM discovery cancelled")); };
+        const timer = setTimeout(() => { signal.removeEventListener("abort", abort); resolve(); }, ms);
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}
+/** Retry only transient failures; the grace deadline includes requests and backoff. */
+export async function discoverWithRetry(load, options, signal = new AbortController().signal) {
+    const grace = Number.isFinite(options.startupRetryMs) ? Math.max(0, options.startupRetryMs) : 120_000;
+    const deadline = Date.now() + grace;
+    let delay = 1000;
+    for (;;) {
+        if (signal.aborted)
+            throw new Error("LiteLLM discovery cancelled");
+        try {
+            const remaining = deadline - Date.now();
+            return await load({ ...options, timeoutMs: grace > 0 ? Math.max(1, Math.min(options.timeoutMs, remaining)) : options.timeoutMs }, signal);
+        }
+        catch (error) {
+            const remaining = deadline - Date.now();
+            if (!isTransient(error) || signal.aborted || remaining <= 0)
+                throw error;
+            await waitForRetry(Math.min(delay, remaining), signal);
+            delay = Math.min(delay * 2, 10_000);
+        }
+    }
+}

package/dist/index.d.ts

@@ -34,6 +34,6 @@ declare const _default: {
             options: Record<string, any>;
         }) => Promise<void>;
     }>;
-    setup: (ctx: import("@opencode/plugin/promise/plugin").Context) => Promise<void>;
+    setup: (ctx: import("@opencode/plugin/promise/plugin").Context) => Promise<() => void>;
 };
 export default _default;

package/dist/index.js

@@ -2,6 +2,7 @@ import { fetchModelGroupInfo, fetchModelInfo } from "./litellm.js";
 import { buildProvider, buildProviderV2, isContractReasoningModel, isQwen38ReasoningModel, mergeModelInfo, } from "./mapping.js";
 import { resolveOptions } from "./options.js";
 import V2Plugin from "./v2.js";
+import { discoverWithRetry } from "./discovery.js";
 async function log(ctx, level, message, extra = {}) {
     await ctx.client?.app?.log?.({ body: { service: "opencode-litellm", level, message, extra } });
 }
@@ -10,7 +11,7 @@ export const LiteLLMPlugin = async (ctx, options) => {
     return {
         config: async (cfg) => {
             try {
-                const deployments = await fetchModelInfo(resolved);
+                const deployments = await discoverWithRetry((attempt, signal) => fetchModelInfo(attempt, fetch, signal), resolved);
                 let groups = [];
                 try {
                     groups = await fetchModelGroupInfo(resolved);

package/dist/litellm.d.ts

@@ -1,5 +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 fetchModelInfo(options: ResolvedOptions, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<LiteLLMModelInfo[]>;
 export declare function normalizeModelGroupResponse(response: unknown): LiteLLMModelInfo[];
-export declare function fetchModelGroupInfo(options: ResolvedOptions, fetchImpl?: typeof fetch): Promise<LiteLLMModelInfo[]>;
+export declare function fetchModelGroupInfo(options: ResolvedOptions, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<LiteLLMModelInfo[]>;

package/dist/litellm.js

@@ -6,8 +6,12 @@ function requireCredentials(options) {
     if (!options.apiKey)
         throw new Error("opencode-litellm requires options.apiKey or the configured apiKeyEnv");
 }
-async function fetchJSON(options, endpoint, url, fetchImpl) {
+async function fetchJSON(options, endpoint, url, fetchImpl, signal) {
     const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (signal?.aborted)
+        abort();
+    signal?.addEventListener("abort", abort, { once: true });
     const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
     try {
         try {
@@ -20,24 +24,30 @@ async function fetchJSON(options, endpoint, url, fetchImpl) {
                 signal: controller.signal,
             });
             if (!response.ok)
-                throw new Error(`LiteLLM ${endpoint} returned HTTP ${response.status}`);
+                throw Object.assign(new Error(`LiteLLM ${endpoint} returned HTTP ${response.status}`), {
+                    retryable: response.status === 408 || response.status === 429 || response.status >= 500,
+                });
             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)}`);
+                throw Object.assign(new Error(`LiteLLM ${endpoint} timed out after ${options.timeoutMs}ms`), { retryable: !signal?.aborted });
+            throw Object.assign(new Error(`LiteLLM ${endpoint} request failed: ${error instanceof Error ? error.message : String(error)}`), {
+                // A JSON/parser failure is a catalog error, not a network outage.
+                retryable: !(error instanceof SyntaxError),
+            });
         }
     }
     finally {
         clearTimeout(timeout);
+        signal?.removeEventListener("abort", abort);
     }
 }
-export async function fetchModelInfo(options, fetchImpl = fetch) {
+export async function fetchModelInfo(options, fetchImpl = fetch, signal) {
     requireCredentials(options);
-    return normalizeModelListResponse(await fetchJSON(options, "/model/info", modelInfoURL(options.baseURL), fetchImpl));
+    return normalizeModelListResponse(await fetchJSON(options, "/model/info", modelInfoURL(options.baseURL), fetchImpl, signal));
 }
 export function normalizeModelGroupResponse(response) {
     const data = typeof response === "object" && response !== null && !Array.isArray(response)
@@ -63,7 +73,7 @@ export function normalizeModelGroupResponse(response) {
         },
     }));
 }
-export async function fetchModelGroupInfo(options, fetchImpl = fetch) {
+export async function fetchModelGroupInfo(options, fetchImpl = fetch, signal) {
     requireCredentials(options);
-    return normalizeModelGroupResponse(await fetchJSON(options, "/model_group/info", modelGroupInfoURL(options.baseURL), fetchImpl));
+    return normalizeModelGroupResponse(await fetchJSON(options, "/model_group/info", modelGroupInfoURL(options.baseURL), fetchImpl, signal));
 }

package/dist/mapping.d.ts

@@ -18,7 +18,7 @@ export declare function mapModels(response: unknown, options?: LiteLLMPluginOpti
     [k: string]: OpenCodeModel;
 };
 export declare function buildProvider(models: unknown, options?: LiteLLMPluginOptions): OpenCodeProvider;
-export declare function mapModelsV2(models: unknown, options?: LiteLLMPluginOptions): {
+export declare function mapModelsV2(models: unknown, options?: LiteLLMPluginOptions, nativeImages?: boolean): {
     [k: string]: OpenCodeModelV2 | {
         variants: {
             id: string;
@@ -26,6 +26,7 @@ export declare function mapModelsV2(models: unknown, options?: LiteLLMPluginOpti
                 [x: string]: unknown;
             };
         }[];
+        type?: "image";
         family?: string;
         name?: string;
         api?: {
@@ -63,4 +64,4 @@ export declare function mapModelsV2(models: unknown, options?: LiteLLMPluginOpti
         };
     };
 };
-export declare function buildProviderV2(models: unknown, options?: LiteLLMPluginOptions): OpenCodeProviderV2;
+export declare function buildProviderV2(models: unknown, options?: LiteLLMPluginOptions, nativeImages?: boolean): OpenCodeProviderV2;

package/dist/mapping.js

@@ -167,7 +167,7 @@ export function normalizeModelListResponse(response) {
 function mode(model) {
     return asString(model.model_info?.mode) ?? "chat";
 }
-function allowedByFilters(model, options) {
+function allowedByFilters(model, options, nativeImages = false) {
     const name = modelName(model);
     if (!name)
         return false;
@@ -186,8 +186,13 @@ function allowedByFilters(model, options) {
     if (options.excludeModels?.includes(name))
         return false;
     const modelMode = mode(model);
+    // Images require the typed catalog and media resolver introduced in current V2.
+    if (modelMode === "image_generation" && !nativeImages)
+        return false;
     if (options.includeModes?.length)
         return options.includeModes.includes(modelMode);
+    if (modelMode === "image_generation")
+        return nativeImages;
     return DEFAULT_MODES.has(modelMode) && !NON_CHAT_MODES.has(modelMode);
 }
 function cost(model) {
@@ -283,11 +288,13 @@ function contractDefaults(name, tombstones = false) {
         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", "low", "medium", "high", "xhigh", "max", ...(entry.metadata ? ["ultra"] : [])].filter((effort) => !entry.modes.some((mode) => mode.id === effort))
-                : [];
+        const disabled = entry.family === "DeepSeek V4.1 Flash"
+            ? REASONING_EFFORTS.filter((effort) => !entry.modes.some((mode) => mode.id === effort))
+            : entry.family === "DeepSeek V4 Flash"
+                ? ["medium", "xhigh"]
+                : entry.family === "Qwen3.8"
+                    ? ["none", "minimal", "low", "medium", "high", "xhigh", "max", ...(entry.metadata ? ["ultra"] : [])].filter((effort) => !entry.modes.some((mode) => mode.id === effort))
+                    : [];
         for (const effort of disabled)
             variants[effort] = { disabled: true };
     }
@@ -330,6 +337,15 @@ function generatedModel(model, tombstones = false) {
     const name = modelName(model);
     if (!name)
         return undefined;
+    if (mode(model) === "image_generation")
+        return {
+            id: name,
+            name,
+            type: "image",
+            provider: { npm: "@opencode/ai/providers/openai-compatible/images" },
+            modalities: { input: supportedModalities(["text", ...(model.model_info?.supported_modalities ?? [])]), output: ["image"] },
+            tool_call: false,
+        };
     const mappedModalities = modalities(model);
     const discoveredVariants = supportsReasoning(model) ? reasoningVariants(model) : undefined;
     const suppressDiscoveredVariants = modelContract(name)?.suppressDiscoveredVariants === true;
@@ -403,6 +419,7 @@ function v2Model(model, baseURL) {
     const name = asString(model.name);
     const family = asString(model.family);
     return {
+        ...(model.type === "image" ? { type: "image" } : {}),
         ...(family ? { family } : {}),
         ...(name ? { name } : {}),
         api: {
@@ -425,10 +442,10 @@ function v2Model(model, baseURL) {
         ...(v2Variants(model) ? { variants: v2Variants(model) } : {}),
     };
 }
-function mapModelsInternal(response, options, tombstones) {
+function mapModelsInternal(response, options, tombstones, nativeImages = false) {
     const models = normalizeModelListResponse(response);
     return Object.fromEntries(models
-        .filter((model) => allowedByFilters(model, options))
+        .filter((model) => allowedByFilters(model, options, nativeImages))
         .map((model) => {
         const name = modelName(model);
         const generated = generatedModel(model, tombstones);
@@ -458,8 +475,8 @@ export function buildProvider(models, options = {}) {
         models: mapModelsInternal(models, options, true),
     }, options.providerOverrides);
 }
-export function mapModelsV2(models, options = {}) {
-    const legacy = mapModels(models, options);
+export function mapModelsV2(models, options = {}, nativeImages = false) {
+    const legacy = mapModelsInternal(models, options, false, nativeImages);
     return Object.fromEntries(Object.entries(legacy).map(([name, model]) => {
         const mapped = v2Model(model, options.baseURL);
         const variants = contractV2Variants(name, model, options.overrides?.[name]);
@@ -471,7 +488,7 @@ export function mapModelsV2(models, options = {}) {
         const overridesEffort = isRecord(overriddenOptions) && ("reasoningEffort" in overriddenOptions ||
             "reasoning_effort" in overriddenOptions ||
             "chat_template_kwargs" in overriddenOptions);
-        // V2 applies the selected variant after request.body, so Qwen off must not inherit its default effort.
+        // V2 applies the selected variant after request.body, so the Qwen off mode cannot inherit a default effort.
         if (contract && mapped.api?.package !== "@ai-sdk/openai" && !overridesEffort) {
             delete defaultBody.reasoning_effort;
             delete defaultBody.reasoningEffort;
@@ -504,7 +521,7 @@ function responsesBody(options) {
     }
     return body;
 }
-export function buildProviderV2(models, options = {}) {
+export function buildProviderV2(models, options = {}, nativeImages = false) {
     return deepMerge({
         name: options.providerName ?? "LiteLLM",
         api: {
@@ -518,6 +535,6 @@ export function buildProviderV2(models, options = {}) {
                 ...(options.apiKey ? { apiKey: options.apiKey } : {}),
             },
         },
-        models: mapModelsV2(models, options),
+        models: mapModelsV2(models, options, nativeImages),
     }, options.providerOverrides);
 }

package/dist/model-contracts.js

@@ -28,12 +28,24 @@ function contract(family, aliases, modes, defaultMode, metadata, suppressDiscove
 }
 const GPT_STANDARD_MODES = effortModes(["none", "low", "medium", "high", "xhigh"]);
 const GPT_MAX_MODES = effortModes(["none", "low", "medium", "high", "xhigh", "max"]);
+const GPT_61_SOL_MODES = effortModes(["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" }) }),
 ]);
+// V4.1's official encoder accepts chat mode plus low/high/max effort aliases;
+// the plugin keeps the existing off -> none wire contract for LiteLLM/vLLM.
+const DEEPSEEK_V41_METADATA = Object.freeze({
+    modalities: Object.freeze({
+        input: Object.freeze(["text", "image"]),
+        output: Object.freeze(["text"]),
+    }),
+    attachment: true,
+    tool_call: true,
+    limit: Object.freeze({ context: 1048576, output: 262144 }),
+});
 const qwenOff = Object.freeze({ enable_thinking: false });
 const QWEN_MODES = Object.freeze([
     Object.freeze({
@@ -78,8 +90,9 @@ export const MODEL_CONTRACTS = Object.freeze([
     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-6 Luna", chatGptAliases("gpt-6-luna"), GPT_MAX_MODES, "medium"),
-    contract("GPT-6 Sol", chatGptAliases("gpt-6-sol"), GPT_MAX_MODES, "medium"),
+    contract("GPT-6.1 Sol", chatGptAliases("gpt-6.1-sol"), GPT_61_SOL_MODES, "medium", undefined, true),
     contract("DeepSeek V4 Flash", ["deepseek-v4-flash-fp8-mtp", "deepseek-v4-flash-fp8-mtp-norefusal"], DEEPSEEK_MODES, "max"),
+    contract("DeepSeek V4.1 Flash", ["deepseek-v4.1-flash-1017"], DEEPSEEK_MODES, "high", DEEPSEEK_V41_METADATA, true),
     contract("Qwen3.8", ["qwen3.8-27b-refusal-dial"], QWEN_MODES, "xhigh"),
     contract("Qwen3.8", ["qwen3.8-flash-next"], QWEN_MODES, "xhigh", QWEN_FLASH_NEXT_METADATA, true),
     contract("Qwen3.8 Strata", ["5090-local-model", "5090-local-model-codex"], STRATA_QWEN_MODES, "xhigh", STRATA_QWEN_METADATA, true),

package/dist/options.d.ts

@@ -1,5 +1,5 @@
 import type { LiteLLMPluginOptions } from "./types.js";
-export type ResolvedOptions = Required<Pick<LiteLLMPluginOptions, "providerKey" | "providerName" | "timeoutMs" | "strict">> & Omit<LiteLLMPluginOptions, "providerKey" | "providerName" | "timeoutMs" | "strict">;
+export type ResolvedOptions = Required<Pick<LiteLLMPluginOptions, "providerKey" | "providerName" | "timeoutMs" | "strict" | "startupRetryMs" | "recoveryIntervalMs">> & Omit<LiteLLMPluginOptions, "providerKey" | "providerName" | "timeoutMs" | "strict" | "startupRetryMs" | "recoveryIntervalMs">;
 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

@@ -12,6 +12,8 @@ export function resolveOptions(options = {}) {
         providerKey: options.providerKey ?? "LiteLLM",
         providerName: options.providerName ?? "LiteLLM",
         timeoutMs: options.timeoutMs ?? 30_000,
+        startupRetryMs: options.startupRetryMs ?? 120_000,
+        recoveryIntervalMs: options.recoveryIntervalMs ?? 30_000,
         strict: options.strict ?? false,
     };
 }

package/dist/types.d.ts

@@ -27,6 +27,7 @@ export type ModelContract = Readonly<{
     metadata?: ModelContractMetadata;
 }>;
 export type OpenCodeModel = JsonObject & {
+    type?: "image";
     provider?: {
         npm?: string;
         api?: string;
@@ -54,6 +55,7 @@ export type OpenCodeModel = JsonObject & {
     variants?: Record<string, JsonObject>;
 };
 export type OpenCodeModelV2 = JsonObject & {
+    type?: "image";
     family?: string;
     name?: string;
     api?: {
@@ -131,6 +133,10 @@ export type LiteLLMPluginOptions = {
     /** Exact model_info.backend matches, unioned with includeModels pins. */
     includeBackends?: string[];
     timeoutMs?: number;
+    /** Total startup grace period for transient discovery failures. Zero disables retries. */
+    startupRetryMs?: number;
+    /** V2 recovery interval after startup grace expires. Zero disables background recovery. */
+    recoveryIntervalMs?: number;
     strict?: boolean;
 };
 export type LiteLLMModelInfo = JsonObject & {

package/dist/v2.d.ts

@@ -2,6 +2,6 @@ import type { Plugin as CurrentPlugin } from "@opencode/plugin";
 type CurrentContext = Parameters<CurrentPlugin.Plugin["setup"]>[0];
 declare const LiteLLMPluginV2: {
     id: string;
-    setup: (ctx: CurrentContext) => Promise<void>;
+    setup: (ctx: CurrentContext) => Promise<() => void>;
 };
 export default LiteLLMPluginV2;

package/dist/v2.js

@@ -2,9 +2,17 @@ import { fetchModelGroupInfo, fetchModelInfo } from "./litellm.js";
 import { buildProviderV2, mergeModelInfo } from "./mapping.js";
 import { deepMerge } from "./merge.js";
 import { resolveOptions } from "./options.js";
+import { discoverWithRetry, isTransient } from "./discovery.js";
 const CHAT_PACKAGE = "@opencode/ai/providers/openai-compatible";
 // The 2.0.16 binary bundles this driver, but not openai-compatible/responses.
 const RESPONSES_PACKAGE = "@opencode/ai/providers/openai/responses";
+/** Image catalog types and their resolver are available in OpenCode 2.2+. */
+function supportsNativeImages(ctx) {
+    const version = ctx.app?.version?.match(/^v?(\d+)\.(\d+)\.(\d+)(?:$|[-+])/);
+    if (!version)
+        return false;
+    return Number(version[1]) > 2 || (Number(version[1]) === 2 && Number(version[2]) >= 2);
+}
 function packageName(name) {
     if (name === "@ai-sdk/openai" || name === "@opencode/ai/providers/openai-compatible/responses")
         return RESPONSES_PACKAGE;
@@ -49,6 +57,7 @@ function currentModel(providerID, id, config, providerPackage) {
     }
     return {
         id,
+        ...(config.type === "image" ? { type: "image" } : {}),
         modelID: config.api?.id ?? id,
         providerID,
         name: config.name ?? id,
@@ -226,62 +235,85 @@ const LiteLLMPluginV2 = {
     id: "opencode-litellm",
     setup: async (ctx) => {
         const options = resolveOptions(ctx.options);
-        let provider;
-        try {
-            const deployments = await fetchModelInfo(options);
-            let groups = [];
+        const controller = new AbortController();
+        let timer;
+        let recovered = false;
+        const cleanup = () => { controller.abort(); if (timer)
+            clearTimeout(timer); };
+        const load = async () => {
+            let provider;
             try {
-                groups = await fetchModelGroupInfo(options);
+                const deployments = await discoverWithRetry((attempt, signal) => fetchModelInfo(attempt, fetch, signal), recovered ? { ...options, startupRetryMs: 0 } : options, controller.signal);
+                let groups = [];
+                try {
+                    groups = await fetchModelGroupInfo(options, fetch, controller.signal);
+                }
+                catch (error) {
+                    if (options.strict)
+                        throw error;
+                    console.warn("opencode-litellm: failed to load LiteLLM model group metadata", error instanceof Error ? error.message : String(error));
+                }
+                const models = mergeModelInfo(deployments, groups);
+                if (ctx.provider?.transform) {
+                    const overrides = { ...options.overrides };
+                    for (const model of models) {
+                        if (model.model_info?.mode !== "responses")
+                            continue;
+                        const id = model.model_name ?? model.litellm_params?.model ?? model.model_info?.id;
+                        if (!id)
+                            continue;
+                        // Opaque Responses aliases need the same transport as GPT-named models.
+                        overrides[id] = deepMerge({ provider: { npm: "@ai-sdk/openai" } }, overrides[id]);
+                    }
+                    provider = buildProviderV2(models, { ...options, overrides }, supportsNativeImages(ctx));
+                    for (const model of models) {
+                        if (model.model_info?.use_responses_lite !== true)
+                            continue;
+                        const id = model.model_name ?? model.litellm_params?.model ?? model.model_info?.id;
+                        const mapped = id ? provider.models[id] : undefined;
+                        if (!mapped || currentModelPackage(mapped, currentProviderPackage(provider)) !== RESPONSES_PACKAGE)
+                            continue;
+                        mapped.request ??= {};
+                        mapped.request.body = deepMerge({ reasoning: { context: "all_turns" } }, mapped.request.body);
+                    }
+                }
+                else {
+                    provider = buildProviderV2(models, options);
+                }
             }
             catch (error) {
+                if (controller.signal.aborted)
+                    return;
                 if (options.strict)
                     throw error;
-                console.warn("opencode-litellm: failed to load LiteLLM model group metadata", error instanceof Error ? error.message : String(error));
+                console.warn("opencode-litellm: failed to load LiteLLM provider metadata", error instanceof Error ? error.message : String(error));
+                const interval = options.recoveryIntervalMs;
+                if (isTransient(error) && Number.isFinite(interval) && interval > 0 && ctx.provider?.reload) {
+                    timer = setTimeout(() => {
+                        recovered = true;
+                        void load().catch((failure) => console.warn("opencode-litellm: catalog recovery failed", failure instanceof Error ? failure.message : String(failure)));
+                    }, interval);
+                    timer.unref?.();
+                }
+                return;
             }
-            const models = mergeModelInfo(deployments, groups);
+            if (controller.signal.aborted)
+                return;
             if (ctx.provider?.transform) {
-                const overrides = { ...options.overrides };
-                for (const model of models) {
-                    if (model.model_info?.mode !== "responses")
-                        continue;
-                    const id = model.model_name ?? model.litellm_params?.model ?? model.model_info?.id;
-                    if (!id)
-                        continue;
-                    // Opaque Responses aliases need the same transport as GPT-named models.
-                    overrides[id] = deepMerge({ provider: { npm: "@ai-sdk/openai" } }, overrides[id]);
-                }
-                provider = buildProviderV2(models, { ...options, overrides });
-                for (const model of models) {
-                    if (model.model_info?.use_responses_lite !== true)
-                        continue;
-                    const id = model.model_name ?? model.litellm_params?.model ?? model.model_info?.id;
-                    const mapped = id ? provider.models[id] : undefined;
-                    if (!mapped || currentModelPackage(mapped, currentProviderPackage(provider)) !== RESPONSES_PACKAGE)
-                        continue;
-                    mapped.request ??= {};
-                    mapped.request.body = deepMerge({ reasoning: { context: "all_turns" } }, mapped.request.body);
-                }
+                await registerCurrent(ctx, options.providerKey, provider);
+                if (recovered)
+                    await ctx.provider.reload();
+                return;
             }
-            else {
-                provider = buildProviderV2(models, options);
+            const transitional = ctx;
+            if (transitional.catalog?.transform) {
+                await transitional.catalog.transform((catalog) => applyTransitional(catalog, options.providerKey, provider));
+                return;
             }
-        }
-        catch (error) {
-            if (options.strict)
-                throw error;
-            console.warn("opencode-litellm: failed to load LiteLLM provider metadata", error instanceof Error ? error.message : String(error));
-            return;
-        }
-        if (ctx.provider?.transform) {
-            await registerCurrent(ctx, options.providerKey, provider);
-            return;
-        }
-        const transitional = ctx;
-        if (transitional.catalog?.transform) {
-            await transitional.catalog.transform((catalog) => applyTransitional(catalog, options.providerKey, provider));
-            return;
-        }
-        throw new Error("opencode-litellm requires an OpenCode V2 provider or catalog transform API");
+            throw new Error("opencode-litellm requires an OpenCode V2 provider or catalog transform API");
+        };
+        await load();
+        return cleanup;
     },
 };
 export default LiteLLMPluginV2;

package/package.json

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