opencode-models-discovery 0.7.0 → 0.8.0

package/README.md

@@ -8,19 +8,18 @@
 
 > A universal OpenCode plugin for dynamic model discovery across **any OpenAI-compatible provider**.
 
-Originally inspired by [opencode-lmstudio](https://github.com/nicktasios/opencode-lmstudio), this project has been fully refactored into a general-purpose model discovery plugin with richer configuration controls for providers, models, naming, caching, and discovery behavior.
+Originally inspired by [opencode-lmstudio](https://github.com/nicktasios/opencode-lmstudio), this project has been fully refactored into a general-purpose model discovery plugin with richer configuration controls for providers, models, naming, and discovery behavior.
 
 ## Features
 
 - **Universal Provider Support**: Works with any OpenAI-compatible provider (LM Studio, Ollama, LocalAI, gateways, and more)
-- **Dynamic Model Discovery**: Queries each provider's `/v1/models` endpoint to discover available models
+- **Dynamic Model Discovery**: Queries each provider's configured models endpoint to discover available models
 - **Auto-Injection**: Automatically adds unconfigured models into OpenCode provider config
 - **Provider Filtering**: Include or exclude specific providers from discovery
 - **Model Filtering**: Use regex rules to precisely control which discovered models are injected
-- **Configurable Discovery**: Control discovery behavior with enable/disable switches and TTL-based caching
+- **Configurable Discovery**: Control discovery behavior with global and provider-level enable/disable switches
 - **Smart Model Formatting**: Optional human-friendly display names for discovered models
 - **Organization Owner Extraction**: Extracts and sets `organizationOwner` from model IDs when available
-- **Health Check Monitoring**: Verifies providers are accessible before attempting discovery
 - **Model Merging**: Intelligently merges discovered models with existing configuration
 - **Error Handling**: Smart error categorization with actionable suggestions
 
@@ -43,11 +42,16 @@ Add the plugin to your `opencode.json`:
     "opencode-models-discovery@latest"
   ],
   "provider": {
-    "ollama": {
+    "deepseek": {
       "npm": "@ai-sdk/openai-compatible",
-      "name": "Ollama (local)",
+      "name": "DeepSeek",
       "options": {
-        "baseURL": "http://127.0.0.1:11434/v1"
+        "baseURL": "https://api.deepseek.com",
+        "apiKey": "YOUR_DEEPSEEK_API_KEY",
+        "modelsDiscovery": {
+          "enabled": true,
+          "endpoint": "/models"
+        }
       }
     },
     "lmstudio": {
@@ -63,6 +67,8 @@ Add the plugin to your `opencode.json`:
 
 ### Configuration
 
+The plugin still supports global configuration in the `plugin` array, but for new setups it is recommended to prefer `provider.<name>.options.modelsDiscovery` for provider-specific behavior. This keeps discovery rules close to the provider they affect and avoids older global rules unintentionally changing newer providers.
+
 The plugin configuration is placed in the `plugin` array using tuple format `["plugin-name", { config }]`:
 
 ```json
@@ -95,10 +101,19 @@ Each provider can override discovery behavior through `provider.<name>.options.m
 | Option | Type | Description |
 |--------|------|-------------|
 | `provider.<name>.options.modelsDiscovery.enabled` | `boolean` | Override global discovery and provider filters for a single provider |
+| `provider.<name>.options.modelsDiscovery.endpoint` | `string` | Provider-specific models endpoint path. Defaults to `/v1/models` |
 | `provider.<name>.options.modelsDiscovery.models.includeRegex` | `string[]` | Provider-specific model include filter |
 | `provider.<name>.options.modelsDiscovery.models.excludeRegex` | `string[]` | Provider-specific model exclude filter |
 | `provider.<name>.options.modelsDiscovery.smartModelName` | `boolean` | Override global `smartModelName` for a single provider |
 
+Recommended approach for new configurations:
+
+1. Keep global plugin config minimal, or use it only as a broad default
+2. Put endpoint, enablement, and model filtering rules on each provider
+3. Use provider-level overrides whenever a provider does not follow the usual `/v1/models` convention
+
+If `provider.<name>.options.modelsDiscovery.endpoint` is omitted, the plugin uses `/v1/models`.
+
 Priority rules:
 
 1. `provider.<name>.options.modelsDiscovery.enabled` overrides global `discovery.enabled` and `providers.include/exclude`
@@ -110,16 +125,9 @@ Priority rules:
 {
   "plugin": [
     ["opencode-models-discovery", {
-      "providers": {
-        "include": ["ollama"]
-      },
-      "models": {
-        "includeRegex": ["^qwen/"]
-      },
       "discovery": {
         "enabled": false
-      },
-      "smartModelName": false
+      }
     }]
   ],
   "provider": {
@@ -130,6 +138,7 @@ Priority rules:
         "baseURL": "http://127.0.0.1:1234/v1",
         "modelsDiscovery": {
           "enabled": true,
+          "endpoint": "/v1/models",
           "models": {
             "includeRegex": ["^gpt-"]
           },
@@ -137,6 +146,70 @@ Priority rules:
         }
       },
       "models": {}
+    },
+    "deepseek": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "DeepSeek",
+      "options": {
+        "baseURL": "https://api.deepseek.com",
+        "apiKey": "sk-example-deepseek-key",
+        "modelsDiscovery": {
+          "enabled": true,
+          "endpoint": "/models",
+          "smartModelName": true
+        }
+      },
+      "models": {}
+    }
+  }
+}
+```
+
+In this example:
+
+1. `lmstudio` explicitly enables discovery and uses the default `/v1/models` endpoint
+2. `lmstudio` limits discovery to models matching `^gpt-`
+3. `deepseek` explicitly enables discovery but uses `"/models"` instead of `/v1/models`
+4. The API key uses an example placeholder and should be replaced in real configs
+
+#### Provider-First Example
+
+This is the recommended style for newer configs, especially when different providers need different discovery paths:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["opencode-models-discovery", {
+      "smartModelName": false
+    }]
+  ],
+  "provider": {
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Ollama",
+      "options": {
+        "baseURL": "http://127.0.0.1:11434/v1",
+        "modelsDiscovery": {
+          "enabled": true,
+          "models": {
+            "includeRegex": ["^qwen/"]
+          }
+        }
+      }
+    },
+    "deepseek": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "DeepSeek",
+      "options": {
+        "baseURL": "https://api.deepseek.com",
+        "apiKey": "YOUR_DEEPSEEK_API_KEY",
+        "modelsDiscovery": {
+          "enabled": true,
+          "endpoint": "/models",
+          "smartModelName": true
+        }
+      }
     }
   }
 }
@@ -144,10 +217,10 @@ Priority rules:
 
 In this example:
 
-1. Global discovery is disabled
-2. `lmstudio` is still discovered because `modelsDiscovery.enabled` is `true`
-3. `lmstudio` uses `^gpt-` instead of the global `^qwen/` filter
-4. `lmstudio` uses smart model names even though the global setting is `false`
+1. The global plugin config only keeps a shared default
+2. `ollama` uses the default discovery path derived from its `/v1` baseURL
+3. `deepseek` does not rely on `/v1/models` and explicitly uses `"/models"`
+4. Each provider can evolve independently without changing global include or endpoint rules
 
 #### Provider Filtering
 
@@ -199,8 +272,8 @@ Regex filtering only applies to auto-discovered models. Models already explicitl
 
 1. On OpenCode startup, the plugin's `config` hook is called
 2. The plugin iterates through all configured providers
-3. For each provider, it checks if the baseURL contains `/v1/` (supports any npm package)
-4. For each accessible provider, it queries the `/v1/models` endpoint
+3. For each provider, it checks whether it is OpenAI-compatible by npm, by a `/v1` baseURL, by an explicit discovery endpoint override, or by a forced provider-level discovery override
+4. For each accessible provider, it queries the configured models endpoint, defaulting to `/v1/models`
 5. Discovered models are automatically merged into the provider's configuration
 6. The enhanced configuration is used for the current session
 
@@ -217,6 +290,7 @@ The plugin supports any OpenAI-compatible provider. Here are the most common one
 | **Text Generation WebUI** | 5000 | OpenAI-compatible extension | `@ai-sdk/openai-compatible` |
 | **FastChat (Vicuna)** | 8001 | Multi-model serving | `@ai-sdk/openai-compatible` |
 | **vLLM** | 8000 | High-performance inference | `@ai-sdk/openai-compatible` |
+| **DeepSeek** | Cloud | OpenAI-compatible API with `/models` discovery endpoint | `@ai-sdk/openai-compatible` |
 | **CLIProxyAPI** | 8317 | A LLM proxy server  | `@ai-sdk/anthropic` (with `/v1` backend) & `@ai-sdk/openai-compatible` |
 
 #### Anthropic API with Custom Backend
@@ -248,17 +322,21 @@ Cloud services with OpenAI-compatible APIs are also supported:
 
 ### Provider Detection
 
-The plugin identifies OpenAI-compatible providers using **two detection methods**:
+The plugin identifies OpenAI-compatible providers using these detection signals:
 
 1. **Strict Detection**: `npm === "@ai-sdk/openai-compatible"`
 2. **URL-based Detection**: `baseURL` contains `/v1/` pattern
+3. **Endpoint Override Detection**: `options.modelsDiscovery.endpoint` is configured
+
+In addition, `options.modelsDiscovery.enabled === true` can force discovery even when the provider does not match the detection rules above.
 
-A provider is considered discoverable if **either** condition matches.
+A provider is considered discoverable if it matches any detection signal above, or if discovery is explicitly forced on.
 
 #### Examples of Supported Configurations
 
 ```json
 {
+  "plugin": ["opencode-models-discovery"],
   "provider": {
     "ollama": {
       "npm": "@ai-sdk/openai-compatible",
@@ -271,6 +349,7 @@ A provider is considered discoverable if **either** condition matches.
 
 ```json
 {
+  "plugin": ["opencode-models-discovery"],
   "provider": {
     "ollama-anthropic": {
       "npm": "@ai-sdk/anthropic",
@@ -283,23 +362,51 @@ A provider is considered discoverable if **either** condition matches.
 
 ```json
 {
+  "plugin": [
+    ["opencode-models-discovery", {
+      "smartModelName": false
+    }]
+  ],
   "provider": {
     "lmstudio": {
       "npm": "@ai-sdk/openai-compatible",
       "name": "LM Studio",
-      "options": { "baseURL": "http://127.0.0.1:1234/v1" }
+      "options": {
+        "baseURL": "http://127.0.0.1:1234/v1",
+        "modelsDiscovery": {
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+```json
+{
+  "plugin": ["opencode-models-discovery"],
+  "provider": {
+    "deepseek": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "DeepSeek",
+      "options": {
+        "baseURL": "https://api.deepseek.com",
+        "modelsDiscovery": {
+          "endpoint": "/models"
+        }
+      }
     }
   }
 }
 ```
 
-This means providers using `@ai-sdk/anthropic` with OpenAI-compatible backends (like Ollama's Anthropic compatibility mode) are also supported, as long as the `baseURL` contains `/v1/`.
+This means providers using `@ai-sdk/anthropic` with OpenAI-compatible backends are also supported when the `baseURL` contains `/v1/`, when a provider-specific discovery endpoint is configured, or when provider-level discovery is explicitly forced on. It also means providers like DeepSeek can be discovered from a non-`/v1` baseURL as long as the models endpoint is configured explicitly.
 
 ## Requirements
 
 - OpenCode with plugin support
 - At least one OpenAI-compatible provider running locally or remotely
-- Provider server API accessible (e.g., `http://127.0.0.1:11434/v1`)
+- Provider server API accessible, using either a `/v1`-style base URL or an explicitly configured models endpoint such as `/models`
 
 ## Logging
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-models-discovery",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "OpenCode plugin for auto-discovery of OpenAI-compatible models with dynamic provider configuration",
   "type": "module",
   "main": "./src/index.ts",

package/src/plugin/enhance-config.ts

@@ -1,6 +1,6 @@
 import { ToastNotifier } from '../ui/toast-notifier'
 import { categorizeModel, formatModelName, extractModelOwner } from '../utils'
-import { normalizeBaseURL, checkProviderHealth, discoverModelsFromProvider, autoDetectOpenAICompatibleProvider, canDiscoverModels } from '../utils/openai-compatible-api'
+import { normalizeBaseURL, discoverModelsFromProvider, autoDetectOpenAICompatibleProvider, canDiscoverModels } from '../utils/openai-compatible-api'
 import { getProviderFilter, getDiscoveryConfig, getModelRegexFilter, getProviderModelRegexFilter, shouldDiscoverModel, shouldDiscoverProviderWithOverride } from '../types/plugin-config'
 import type { PluginLogger } from './logger'
 import type { PluginInput } from '@opencode-ai/plugin'
@@ -31,8 +31,10 @@ export async function enhanceConfig(
     for (const [providerName, providerConfig] of Object.entries(providers)) {
       const p = providerConfig as any
       const providerDiscoveryConfig = p.options?.modelsDiscovery ?? {}
+      const modelsEndpoint = providerDiscoveryConfig.endpoint ?? '/v1/models'
+      const forceDiscoveryEnabled = providerDiscoveryConfig.enabled === true
 
-      if (!canDiscoverModels(p)) {
+      if (!forceDiscoveryEnabled && !canDiscoverModels(p)) {
         continue
       }
 
@@ -52,24 +54,19 @@ export async function enhanceConfig(
 
       const apiKey = p.options?.apiKey
 
-      const isHealthy = await checkProviderHealth(baseURL, apiKey)
-      if (!isHealthy) {
-        // Provider offline - silent, this is normal for health checks
-        continue
-      }
-
       let models: OpenAIModel[]
-      try {
-        models = await discoverModelsFromProvider(baseURL, apiKey)
-      } catch (error) {
+      const discovery = await discoverModelsFromProvider(baseURL, apiKey, modelsEndpoint)
+      if (!discovery.ok) {
         logger.warn('Provider model discovery failed', {
           provider: providerName,
           baseURL,
-          error: error instanceof Error ? error.message : String(error),
+          endpoint: modelsEndpoint,
         })
         continue
       }
 
+      models = discovery.models
+
       if (models.length === 0) {
         continue
       }

package/src/types/plugin-config.ts

@@ -15,6 +15,7 @@ export interface PluginConfig {
 
 export interface ProviderDiscoveryConfig {
   enabled?: boolean
+  endpoint?: string
   models?: {
     includeRegex?: string[]
     excludeRegex?: string[]

package/src/utils/openai-compatible-api.ts

@@ -2,6 +2,11 @@ import type { OpenAIModel, OpenAIModelsResponse } from '../types'
 
 const OPENAI_COMPATIBLE_MODELS_ENDPOINT = "/v1/models"
 
+export interface ModelsDiscoveryResult {
+  ok: boolean
+  models: OpenAIModel[]
+}
+
 export function normalizeBaseURL(baseURL: string): string {
   let normalized = baseURL.replace(/\/+$/, '')
   if (normalized.endsWith('/v1')) {
@@ -15,27 +20,13 @@ export function buildAPIURL(baseURL: string, endpoint: string = OPENAI_COMPATIBL
   return `${normalized}${endpoint}`
 }
 
-export async function checkProviderHealth(baseURL: string, apiKey?: string): Promise<boolean> {
-  try {
-    const url = buildAPIURL(baseURL)
-    const headers: Record<string, string> = {}
-    if (apiKey) {
-      headers["Authorization"] = `Bearer ${apiKey}`
-    }
-    const response = await fetch(url, {
-      method: "GET",
-      headers: Object.keys(headers).length > 0 ? headers : undefined,
-      signal: AbortSignal.timeout(3000),
-    })
-    return response.ok
-  } catch {
-    return false
-  }
-}
-
-export async function discoverModelsFromProvider(baseURL: string, apiKey?: string): Promise<OpenAIModel[]> {
+export async function discoverModelsFromProvider(
+  baseURL: string,
+  apiKey?: string,
+  endpoint: string = OPENAI_COMPATIBLE_MODELS_ENDPOINT
+): Promise<ModelsDiscoveryResult> {
   try {
-    const url = buildAPIURL(baseURL)
+    const url = buildAPIURL(baseURL, endpoint)
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
     }
@@ -49,19 +40,22 @@ export async function discoverModelsFromProvider(baseURL: string, apiKey?: strin
     })
 
     if (!response.ok) {
-      return []
+      return { ok: false, models: [] }
     }
 
     const data = (await response.json()) as OpenAIModelsResponse
-    return data.data ?? []
-  } catch (error) {
-    throw new Error(`Failed to discover models: ${error instanceof Error ? error.message : String(error)}`)
+    return {
+      ok: true,
+      models: data.data ?? [],
+    }
+  } catch {
+    return { ok: false, models: [] }
   }
 }
 
-export async function fetchModelsDirect(baseURL: string): Promise<string[]> {
+export async function fetchModelsDirect(baseURL: string, endpoint: string = OPENAI_COMPATIBLE_MODELS_ENDPOINT): Promise<string[]> {
   try {
-    const url = buildAPIURL(baseURL)
+    const url = buildAPIURL(baseURL, endpoint)
     const response = await fetch(url, {
       method: "GET",
       signal: AbortSignal.timeout(3000),
@@ -87,8 +81,8 @@ export async function autoDetectOpenAICompatibleProvider(): Promise<{ name: stri
   for (const candidate of candidates) {
     for (const port of candidate.ports) {
       const baseURL = `http://127.0.0.1:${port}`
-      const isHealthy = await checkProviderHealth(baseURL)
-      if (isHealthy) {
+      const discovery = await discoverModelsFromProvider(baseURL)
+      if (discovery.ok) {
         return { name: candidate.name, baseURL }
       }
     }
@@ -108,8 +102,14 @@ export function hasOpenAICompatibleURL(provider: any): boolean {
   return /\/v1(\/|$)/.test(baseURL)
 }
 
+export function hasModelsDiscoveryEndpoint(provider: any): boolean {
+  if (!provider || typeof provider !== 'object') return false
+  const endpoint = provider.options?.modelsDiscovery?.endpoint
+  return typeof endpoint === 'string' && endpoint.length > 0
+}
+
 export function canDiscoverModels(provider: any): boolean {
-  return isOpenAICompatibleProvider(provider) || hasOpenAICompatibleURL(provider)
+  return isOpenAICompatibleProvider(provider) || hasOpenAICompatibleURL(provider) || hasModelsDiscoveryEndpoint(provider)
 }
 
 export function isValidModel(model: any): model is { id: string; [key: string]: any } {
@@ -117,4 +117,4 @@ export function isValidModel(model: any): model is { id: string; [key: string]:
          typeof model === 'object' &&
          typeof model.id === 'string' &&
          model.id.length > 0
-}
+}

package/src/utils/validation/validate-config.ts

@@ -13,8 +13,9 @@ export function validateConfig(config: any): ValidationResult {
   if (config.provider && typeof config.provider === 'object') {
     for (const [providerName, providerConfig] of Object.entries(config.provider)) {
       const p = providerConfig as any
+      const forceDiscoveryEnabled = p.options?.modelsDiscovery?.enabled === true
 
-      if (canDiscoverModels(p)) {
+      if (forceDiscoveryEnabled || canDiscoverModels(p)) {
         if (!p.options?.baseURL) {
           warnings.push(`Provider '${providerName}' missing baseURL`)
         }
@@ -30,4 +31,4 @@ export function validateConfig(config: any): ValidationResult {
     errors,
     warnings
   }
-}
+}