opencode-provider-litellm 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# opencode-provider-litellm
+
+OpenCode plugin that auto-discovers models from any [LiteLLM](https://github.com/BerriAI/litellm) proxy — complete with costs, context limits, capabilities, and auth. Zero config, zero hand-maintained model lists.
+
+## Quick start
+
+```bash
+# 1. Set your LiteLLM proxy URL and API key
+export LITELLM_URL="https://your-litellm-proxy.example.com"
+export LITELLM_KEY="sk-..."
+
+# 2. Install the plugin
+opencode plugin opencode-provider-litellm
+
+# 3. Restart OpenCode
+```
+
+All models from your LiteLLM proxy appear in OpenCode's model picker automatically.
+
+## Configuration
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `LITELLM_URL` | Your LiteLLM proxy base URL |
+| `LITELLM_KEY` | API key for the proxy |
+| `LITELLM_PROVIDER_ID` | Provider ID in OpenCode (defaults to `LiteLLM`) |
+
+### Inline config
+
+Alternatively, provide `url` and `apiKey` directly in your `opencode.json`:
+
+```jsonc
+{
+  "plugin": [
+    ["opencode-provider-litellm", {
+      "url": "https://your-litellm-proxy.example.com",
+      "apiKey": "sk-..."
+    }]
+  ]
+}
+```
+
+:::tip
+Environment variables take precedence over inline config. Use env vars to keep secrets out of checked-in files.
+:::
+
+### /connect flow
+
+You can also authenticate interactively via the OpenCode TUI:
+
+1. Run `/connect`
+2. Select **LiteLLM**
+3. Paste your API key
+
+The key is stored in OpenCode's auth store.
+
+## How it works
+
+The plugin uses two OpenCode hooks:
+
+| Hook | Purpose |
+|------|---------|
+| `config` | Queries `/health` + `/model/info` on startup, discovers models with rich metadata (costs, limits, capabilities), and injects them into OpenCode |
+| `auth` | Provides a `/connect` entry point for pasting an API key |
+
+Model metadata is fetched from LiteLLM's admin API:
+
+- `/health` — model list with internal UUIDs
+- `/model/info?litellm_model_id={uuid}` — rich metadata per model (costs, context limits, vision, tool calling, reasoning, etc.)
+
+Custom model_info updates via `/model/update` are respected — no hardcoded fallbacks.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "Plugin config error" | Set `LITELLM_URL` and `LITELLM_KEY`, or add `url`/`apiKey` to plugin options |
+| "Access denied" (403) | Verify the API key has access to the LiteLLM proxy |
+| "No models discovered" | Check that the proxy is reachable and the `/health` endpoint responds |
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run test
+npm run build
+```

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "opencode-provider-litellm",
+  "version": "0.1.0",
+  "description": "OpenCode plugin for any LiteLLM proxy — auto-discovers models, auth, and capabilities",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "build": "tsc --noEmit && esbuild src/index.ts --bundle --outfile=dist/litellm.js --platform=node --target=node20 --format=esm --external:node:* --packages=external"
+  },
+  "keywords": [
+    "opencode",
+    "llm",
+    "plugin",
+    "litellm"
+  ],
+  "license": "MIT",
+  "author": "Daniel Cherubini",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danielcherubini/opencode-provider-litellm.git"
+  },
+  "engines": {
+    "opencode": ">=1.14.0"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "latest"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "vitest": "^3.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "esbuild": "^0.27.0"
+  }
+}

package/src/discovery.test.ts

@@ -0,0 +1,291 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { PluginConfig, OpencodeModelConfig } from './types.js'
+import { discoverModels, injectModelsIntoConfig } from './discovery.js'
+
+interface TestConfig {
+  provider?: Record<string, {
+    npm?: string
+    name?: string
+    options?: Record<string, unknown>
+    models?: Record<string, OpencodeModelConfig>
+  }>
+}
+
+describe('discoverModels', () => {
+  const config: PluginConfig = {
+    url: 'https://litellm.example.com',
+    apiKey: 'test-api-key',
+  }
+  const getToken = vi.fn(() => Promise.resolve('test-token'))
+
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('returns mapped models from LiteLLM response', async () => {
+    const mockFetch = vi.fn()
+      // /health endpoint
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          healthy_endpoints: [
+            { model: 'gpt-4', model_id: 'uuid-1' },
+            { model: 'qwen3-32b', model_id: 'uuid-2' },
+          ],
+        }),
+      })
+      // /model/info for gpt-4
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: [{
+            model_name: 'gpt-4',
+            model_info: {
+              max_input_tokens: 8192,
+              max_output_tokens: 8192,
+              supports_function_calling: true,
+              supports_reasoning: false,
+              supports_vision: false,
+              input_cost_per_token: 0.0001,
+              output_cost_per_token: 0.0003,
+            },
+          }],
+        }),
+      })
+      // /model/info for qwen3-32b
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: [{
+            model_name: 'qwen3-32b',
+            model_info: {
+              max_input_tokens: 32768,
+              max_output_tokens: 32768,
+              supports_function_calling: true,
+              supports_reasoning: true,
+              supports_vision: false,
+              input_cost_per_token: 0.00005,
+              output_cost_per_token: 0.00015,
+            },
+          }],
+        }),
+      })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const result = await discoverModels(config, getToken)
+
+    expect(result).toEqual({
+      'gpt-4': {
+        name: 'gpt-4',
+        tool_call: true,
+        reasoning: false,
+        limit: { context: 8192, output: 8192 },
+        cost: { input: 0.0001, output: 0.0003 },
+        modalities: { input: ['text'], output: ['text'] },
+      },
+      'qwen3-32b': {
+        name: 'qwen3-32b',
+        tool_call: true,
+        reasoning: true,
+        limit: { context: 32768, output: 32768 },
+        cost: { input: 0.00005, output: 0.00015 },
+        modalities: { input: ['text'], output: ['text'] },
+      },
+    })
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://litellm.example.com/health',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer test-token',
+        }),
+        signal: expect.any(AbortSignal),
+      })
+    )
+    expect(getToken).toHaveBeenCalled()
+  })
+
+  it('returns empty object on timeout', async () => {
+    vi.useFakeTimers()
+
+    // Simulate a fetch that rejects when the abort signal fires
+    const mockFetch = vi.fn().mockImplementation((_url: string, init: RequestInit) => {
+      return new Promise<Response>((_resolve, reject) => {
+        const signal = init?.signal
+        if (signal) {
+          signal.addEventListener('abort', () => {
+            reject(new DOMException('The operation was aborted.', 'AbortError'))
+          })
+        }
+      })
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    // Run discoverModels
+    const promise = discoverModels(config, getToken)
+
+    // Advance timer past 15s timeout
+    await vi.advanceTimersByTimeAsync(15001)
+
+    const result = await promise
+
+    vi.useRealTimers()
+
+    expect(result).toEqual({})
+  })
+
+  it('throws descriptive error on 403', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 403,
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    await expect(discoverModels(config, getToken)).rejects.toThrow(
+      'Access denied. Contact your admin to grant access to the LLM proxy.'
+    )
+  })
+
+  it('returns empty object on 500', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const result = await discoverModels(config, getToken)
+    expect(result).toEqual({})
+  })
+
+  it('returns empty object on network error', async () => {
+    const mockFetch = vi.fn().mockRejectedValue(new Error('network error'))
+    vi.stubGlobal('fetch', mockFetch)
+
+    const result = await discoverModels(config, getToken)
+    expect(result).toEqual({})
+  })
+})
+
+describe('injectModelsIntoConfig', () => {
+  it('creates provider entry with correct structure', async () => {
+    const config: TestConfig = {}
+    const models: Record<string, OpencodeModelConfig> = {
+      'gpt-4': {
+        name: 'gpt-4',
+        tool_call: true,
+        reasoning: false,
+        limit: { context: 8192, output: 8192 },
+        modalities: { input: ['text' as const], output: ['text' as const] },
+      },
+    }
+
+    injectModelsIntoConfig(config, 'litellm', 'https://litellm.example.com', 'sk-test-key', models)
+
+    expect(config.provider).toEqual({
+      litellm: {
+        npm: '@ai-sdk/openai-compatible',
+        name: 'litellm',
+        options: { baseURL: 'https://litellm.example.com', apiKey: 'sk-test-key' },
+        models,
+      },
+    })
+  })
+
+  it('merges with existing provider config without overwriting options', async () => {
+    const config: TestConfig = {
+      provider: {
+        litellm: {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'litellm',
+          options: { baseURL: 'https://old.example.com', apiKey: 'old-key', extra: 'value' },
+          models: {
+            'existing-model': {
+              name: 'existing-model',
+              tool_call: true,
+              reasoning: false,
+              limit: { context: 4096, output: 4096 },
+              modalities: { input: ['text' as const], output: ['text' as const] },
+            },
+          },
+        },
+      },
+    }
+
+    const newModels: Record<string, OpencodeModelConfig> = {
+      'new-model': {
+        name: 'new-model',
+        tool_call: true,
+        reasoning: false,
+        limit: { context: 8192, output: 8192 },
+        modalities: { input: ['text' as const], output: ['text' as const] },
+      },
+    }
+
+    injectModelsIntoConfig(config, 'litellm', 'https://litellm.example.com', 'sk-test-key', newModels)
+
+    // Existing options should be preserved
+    expect(config.provider!.litellm.options).toEqual({
+      baseURL: 'https://old.example.com',
+      apiKey: 'old-key',
+      extra: 'value',
+    })
+
+    // Models should be merged
+    expect(config.provider!.litellm.models).toEqual({
+      'existing-model': {
+        name: 'existing-model',
+        tool_call: true,
+        reasoning: false,
+        limit: { context: 4096, output: 4096 },
+        modalities: { input: ['text' as const], output: ['text' as const] },
+      },
+      'new-model': {
+        name: 'new-model',
+        tool_call: true,
+        reasoning: false,
+        limit: { context: 8192, output: 8192 },
+        modalities: { input: ['text' as const], output: ['text' as const] },
+      },
+    })
+  })
+
+  it('preserves existing provider options when merging', async () => {
+    const config: TestConfig = {
+      provider: {
+        litellm: {
+          npm: '@ai-sdk/openai-compatible',
+          name: 'litellm',
+          options: {
+            baseURL: 'https://preserved.example.com',
+            apiKey: 'preserved-key',
+            customHeader: 'custom-value',
+          },
+          models: {},
+        },
+      },
+    }
+
+    const newModels: Record<string, OpencodeModelConfig> = {
+      'gpt-4': {
+        name: 'gpt-4',
+        tool_call: true,
+        reasoning: false,
+        limit: { context: 8192, output: 8192 },
+        modalities: { input: ['text' as const], output: ['text' as const] },
+      },
+    }
+
+    injectModelsIntoConfig(config, 'litellm', 'https://litellm.example.com', 'sk-test-key', newModels)
+
+    // All existing options should be preserved
+    const provider = config.provider!.litellm
+    expect(provider.options!.baseURL).toBe('https://preserved.example.com')
+    expect(provider.options!.apiKey).toBe('preserved-key')
+    expect(provider.options!.customHeader).toBe('custom-value')
+
+    // New models should be added
+    expect(Object.keys(provider.models!)).toContain('gpt-4')
+  })
+})

package/src/discovery.ts

@@ -0,0 +1,190 @@
+import type { PluginConfig, OpencodeModelConfig } from './types.js'
+import type { Config } from '@opencode-ai/plugin'
+
+interface LiteLLMHealthModel {
+  model: string
+  model_id: string
+}
+
+interface LiteLLMModelInfo {
+  model_name?: string
+  max_tokens?: number
+  max_input_tokens?: number
+  max_output_tokens?: number
+  supports_function_calling?: boolean
+  supports_reasoning?: boolean
+  supports_vision?: boolean
+  supports_audio_input?: boolean
+  supports_pdf_input?: boolean
+  input_cost_per_token?: number
+  output_cost_per_token?: number
+  cache_read_input_token_cost?: number
+  cache_creation_input_token_cost?: number
+}
+
+/**
+ * Fetches available models from the LiteLLM proxy's /health endpoint,
+ * then fetches rich metadata from /model/info for each model.
+ * Maps the metadata to OpenCode's model config format.
+ */
+export async function discoverModels(
+  config: PluginConfig,
+  getToken: () => Promise<string>,
+): Promise<Record<string, OpencodeModelConfig>> {
+  const token = await getToken()
+
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), 15_000)
+
+  try {
+    // Step 1: Get model list with internal UUIDs from /health
+    const healthResponse = await fetch(`${config.url}/health`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+      signal: controller.signal,
+    })
+
+    if (healthResponse.status === 403) {
+      throw new Error(
+        'Access denied. Contact your admin to grant access to the LLM proxy.',
+      )
+    }
+
+    if (!healthResponse.ok) {
+      return {}
+    }
+
+    const healthBody = await healthResponse.json()
+    const healthyEndpoints = healthBody.healthy_endpoints as LiteLLMHealthModel[] | undefined
+    if (!Array.isArray(healthyEndpoints)) return {}
+
+    // Step 2: Fetch rich metadata for each model in parallel
+    const modelInfos = await Promise.all(
+      healthyEndpoints.map(async (endpoint) => {
+        try {
+          const infoResponse = await fetch(
+            `${config.url}/model/info?litellm_model_id=${encodeURIComponent(endpoint.model_id)}`,
+            {
+              method: 'GET',
+              headers: {
+                Authorization: `Bearer ${token}`,
+              },
+              signal: controller.signal,
+            },
+          )
+
+          if (!infoResponse.ok) return null
+
+          const infoBody = await infoResponse.json()
+          const data = infoBody.data as Array<{ model_name?: string; model_info?: LiteLLMModelInfo }> | undefined
+          if (!Array.isArray(data) || !data[0]) return null
+
+          return { model_name: data[0].model_name, ...data[0].model_info }
+        } catch {
+          return null
+        }
+      }),
+    )
+
+    // Step 3: Map to OpenCode model config
+    const models: Record<string, OpencodeModelConfig> = {}
+
+    for (let i = 0; i < healthyEndpoints.length; i++) {
+      const info = modelInfos[i]
+      if (!info?.model_name) continue
+
+      const modelName = info.model_name
+
+      const inputModalities: Array<'text' | 'audio' | 'image' | 'video' | 'pdf'> = ['text']
+      if (info.supports_vision) inputModalities.push('image')
+      if (info.supports_audio_input) inputModalities.push('audio')
+      if (info.supports_pdf_input) inputModalities.push('pdf')
+
+      const modelConfig: OpencodeModelConfig = {
+        name: modelName,
+        tool_call: info.supports_function_calling ?? true,
+        reasoning: info.supports_reasoning ?? false,
+        limit: {
+          context: info.max_input_tokens ?? 32768,
+          output: info.max_output_tokens ?? info.max_tokens ?? 32768,
+        },
+        modalities: {
+          input: inputModalities,
+          output: ['text'],
+        },
+      }
+
+      // Add cost info if available
+      if (info.input_cost_per_token != null && info.output_cost_per_token != null) {
+        modelConfig.cost = {
+          input: info.input_cost_per_token,
+          output: info.output_cost_per_token,
+        }
+        if (info.cache_read_input_token_cost != null) {
+          modelConfig.cost.cache_read = info.cache_read_input_token_cost
+        }
+        if (info.cache_creation_input_token_cost != null) {
+          modelConfig.cost.cache_write = info.cache_creation_input_token_cost
+        }
+      }
+
+      models[modelName] = modelConfig
+    }
+
+    return models
+  } catch (error: unknown) {
+    // Timeout (AbortError) or network error → return empty object
+    if (error instanceof Error && error.name === 'AbortError') {
+      return {}
+    }
+    // Re-throw the 403 descriptive error
+    if (error instanceof Error && error.message.includes('Access denied')) {
+      throw error
+    }
+    // Network errors → return empty object
+    return {}
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+/**
+ * Injects discovered models into an OpenCode config under the given provider name.
+ * Merges with existing provider config without overwriting options.
+ */
+export function injectModelsIntoConfig(
+  config: Config,
+  providerName: string,
+  baseUrl: string,
+  apiKey: string,
+  models: Record<string, OpencodeModelConfig>,
+): void {
+  if (!config.provider) {
+    config.provider = {}
+  }
+
+  const existing = config.provider[providerName]
+
+  if (existing) {
+    // Preserve existing options, merge models
+    // Set defaults for incomplete provider entries
+    if (!existing.npm) existing.npm = '@ai-sdk/openai-compatible'
+    if (!existing.name) existing.name = providerName
+    if (!existing.options) {
+      existing.options = { baseURL: baseUrl, apiKey }
+    }
+    existing.models = { ...existing.models, ...models }
+  } else {
+    config.provider[providerName] = {
+      npm: '@ai-sdk/openai-compatible',
+      name: providerName,
+      options: {
+        baseURL: baseUrl,
+        apiKey,
+      },
+      models,
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { LiteLLMPlugin } from './plugin.js'

package/src/plugin.test.ts

@@ -0,0 +1,180 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest'
+import type { PluginInput } from '@opencode-ai/plugin'
+import type { OpencodeModelConfig } from './types.js'
+
+// Mock the discovery module
+vi.mock('./discovery.js', () => ({
+  discoverModels: vi.fn(),
+  injectModelsIntoConfig: vi.fn(),
+}))
+
+// Mock the utils module
+vi.mock('./utils.js', () => ({
+  resolvePluginConfig: vi.fn(),
+  getProviderId: vi.fn(() => 'litellm'),
+  mapLiteLLMModel: vi.fn(),
+}))
+
+import { LiteLLMPlugin } from './plugin.js'
+import { discoverModels, injectModelsIntoConfig } from './discovery.js'
+import { resolvePluginConfig } from './utils.js'
+
+function createMockInput(): PluginInput {
+  const logFn = vi.fn().mockResolvedValue(true)
+  return {
+    client: {
+      app: { log: logFn },
+    } as never,
+    $: vi.fn() as never,
+    project: {} as never,
+    directory: '/test',
+    worktree: '/test',
+    serverUrl: new URL('http://localhost'),
+    experimental_workspace: {
+      register: vi.fn(),
+    },
+  }
+}
+
+describe('LiteLLMPlugin', () => {
+  let mockInput: PluginInput
+  let logFn: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    vi.resetAllMocks()
+
+    mockInput = createMockInput()
+    logFn = mockInput.client.app.log as ReturnType<typeof vi.fn>
+
+    const models: Record<string, OpencodeModelConfig> = {
+      'gpt-4': {
+        name: 'gpt-4',
+        tool_call: true,
+        reasoning: false,
+        limit: { context: 8192, output: 8192 },
+        modalities: { input: ['text'], output: ['text'] },
+      },
+    }
+    vi.mocked(discoverModels).mockResolvedValue(models)
+    vi.mocked(injectModelsIntoConfig).mockImplementation(() => {})
+    vi.mocked(resolvePluginConfig).mockReturnValue({
+      url: 'https://litellm.example.com',
+      apiKey: 'test-api-key',
+    })
+  })
+
+  it('throws on missing config', async () => {
+    vi.mocked(resolvePluginConfig).mockReturnValue(null)
+
+    await expect(
+      LiteLLMPlugin(mockInput, {})
+    ).rejects.toThrow(
+      "Plugin config error: set 'url' and 'apiKey'",
+    )
+  })
+
+  it('config hook calls discoverModels and injects models into config', async () => {
+    const hooks = await LiteLLMPlugin(mockInput, {
+      url: 'https://litellm.example.com',
+      apiKey: 'test-api-key',
+    })
+
+    const testConfig = {} as never
+    await hooks.config?.(testConfig)
+
+    expect(discoverModels).toHaveBeenCalledWith(
+      { url: 'https://litellm.example.com', apiKey: 'test-api-key' },
+      expect.any(Function),
+    )
+    expect(injectModelsIntoConfig).toHaveBeenCalledWith(
+      testConfig,
+      'litellm',
+      'https://litellm.example.com',
+      'test-api-key',
+      expect.any(Object),
+    )
+    expect(logFn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: expect.objectContaining({
+          service: 'litellm',
+          level: 'info',
+          message: expect.stringContaining('Discovered'),
+        }),
+      }),
+    )
+  })
+
+  it('config hook catches errors and does not throw', async () => {
+    vi.mocked(discoverModels).mockRejectedValue(new Error('Network error'))
+
+    const hooks = await LiteLLMPlugin(mockInput, {
+      url: 'https://litellm.example.com',
+      apiKey: 'test-api-key',
+    })
+
+    await expect(hooks.config?.({} as never)).resolves.not.toThrow()
+
+    expect(logFn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: expect.objectContaining({
+          service: 'litellm',
+          level: 'warn',
+          message: expect.stringContaining('Model discovery failed'),
+        }),
+      }),
+    )
+  })
+
+  it('config hook logs warning and skips inject when no models discovered', async () => {
+    vi.mocked(discoverModels).mockResolvedValue({})
+
+    const hooks = await LiteLLMPlugin(mockInput, {
+      url: 'https://litellm.example.com',
+      apiKey: 'test-api-key',
+    })
+
+    await hooks.config?.({} as never)
+
+    expect(injectModelsIntoConfig).not.toHaveBeenCalled()
+    expect(logFn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: expect.objectContaining({
+          service: 'litellm',
+          level: 'warn',
+          message: 'No models discovered',
+        }),
+      }),
+    )
+  })
+
+  it('auth hook returns success when API key is provided', async () => {
+    const hooks = await LiteLLMPlugin(mockInput, {
+      url: 'https://litellm.example.com',
+      apiKey: 'test-api-key',
+    })
+
+    const result = await hooks.auth?.methods[0].authorize?.({ apiKey: 'user-pasted-key' })
+
+    expect(result).toEqual({ type: 'success', key: 'user-pasted-key' })
+  })
+
+  it('auth hook returns failed when API key is empty', async () => {
+    const hooks = await LiteLLMPlugin(mockInput, {
+      url: 'https://litellm.example.com',
+      apiKey: 'test-api-key',
+    })
+
+    const result = await hooks.auth?.methods[0].authorize?.({ apiKey: '' })
+    expect(result).toEqual({ type: 'failed' })
+  })
+
+  it('auth hook returns failed when no inputs provided', async () => {
+    const hooks = await LiteLLMPlugin(mockInput, {
+      url: 'https://litellm.example.com',
+      apiKey: 'test-api-key',
+    })
+
+    const result = await hooks.auth?.methods[0].authorize?.()
+    expect(result).toEqual({ type: 'failed' })
+  })
+})

package/src/plugin.ts

@@ -0,0 +1,104 @@
+import type { Plugin, PluginInput, PluginOptions } from '@opencode-ai/plugin'
+import { resolvePluginConfig, getProviderId } from './utils.js'
+import { discoverModels, injectModelsIntoConfig } from './discovery.js'
+
+/**
+ * Main plugin entry point for the LiteLLM provider.
+ *
+ * Wires together config (model discovery), auth (/connect API key flow),
+ * and chat.headers (per-request Bearer token injection).
+ *
+ * Auth: LITELLM_URL / LITELLM_KEY env vars take precedence,
+ * with fallback to values in opencode.json plugin options.
+ */
+export const LiteLLMPlugin: Plugin = async (
+  input: PluginInput,
+  options?: PluginOptions,
+) => {
+  const pluginConfig = resolvePluginConfig(options)
+  if (pluginConfig === null) {
+    throw new Error(
+      "Plugin config error: set 'url' and 'apiKey' in plugin options, " +
+      "or set LITELLM_URL and LITELLM_KEY environment variables.",
+    )
+  }
+
+  const providerId = getProviderId()
+
+  return {
+    /**
+     * Config hook — discovers models from the LiteLLM proxy and injects
+     * them into the OpenCode config under the provider.
+     */
+    config: async (config) => {
+      try {
+        const models = await discoverModels(
+          pluginConfig,
+          () => Promise.resolve(pluginConfig.apiKey),
+        )
+
+        if (Object.keys(models).length === 0) {
+          await input.client.app.log({
+            body: {
+              service: providerId,
+              level: 'warn',
+              message: 'No models discovered',
+            },
+          })
+          return
+        }
+
+        injectModelsIntoConfig(
+          config as Parameters<typeof injectModelsIntoConfig>[0],
+          providerId,
+          pluginConfig.url,
+          pluginConfig.apiKey,
+          models,
+        )
+        await input.client.app.log({
+          body: {
+            service: providerId,
+            level: 'info',
+            message: `Discovered ${Object.keys(models).length} models`,
+          },
+        })
+      } catch (error) {
+        await input.client.app.log({
+          body: {
+            service: providerId,
+            level: 'warn',
+            message: `Model discovery failed: ${error}`,
+          },
+        })
+      }
+    },
+
+    /**
+     * Auth hook — lets the user paste an API key via the /connect flow.
+     * The key is stored in OpenCode's auth store and used as the Bearer token.
+     */
+    auth: {
+      provider: providerId,
+      methods: [
+        {
+          type: 'api' as const,
+          label: 'LiteLLM API Key',
+          prompts: [
+            {
+              type: 'text' as const,
+              key: 'apiKey',
+              message: 'API key',
+              placeholder: 'sk-...',
+            },
+          ],
+          async authorize(inputs) {
+            if (!inputs?.apiKey || inputs.apiKey.length === 0) {
+              return { type: 'failed' as const }
+            }
+            return { type: 'success' as const, key: inputs.apiKey }
+          },
+        },
+      ],
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+export interface PluginConfig {
+  url: string
+  apiKey: string
+}
+
+export interface LiteLLMModel {
+  id: string
+  max_model_len?: number
+}
+
+export interface OpencodeModelConfig {
+  name: string
+  tool_call?: boolean
+  reasoning?: boolean
+  limit?: {
+    context: number
+    output: number
+  }
+  cost?: {
+    input: number
+    output: number
+    cache_read?: number
+    cache_write?: number
+    context_over_200k?: {
+      input: number
+      output: number
+    }
+  }
+  modalities?: {
+    input: Array<"text" | "audio" | "image" | "video" | "pdf">
+    output: Array<"text" | "audio" | "image" | "video" | "pdf">
+  }
+}

package/src/utils.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mapLiteLLMModel, resolvePluginConfig } from './utils.js'
+import type { LiteLLMModel } from './types.js'
+
+describe('mapLiteLLMModel', () => {
+  it('maps basic model correctly', () => {
+    const model: LiteLLMModel = { id: 'gpt-4o' }
+    const result = mapLiteLLMModel(model)
+
+    expect(result.name).toBe('gpt-4o')
+    expect(result.tool_call).toBe(true)
+    expect(result.reasoning).toBe(false)
+    expect(result.limit).toEqual({ context: 32768, output: 32768 })
+    expect(result.modalities).toEqual({ input: ['text'], output: ['text'] })
+  })
+
+  it('matches reasoning heuristic for qwen3 models', () => {
+    const model: LiteLLMModel = { id: 'qwen/qwen3.6-27b' }
+    expect(mapLiteLLMModel(model).reasoning).toBe(true)
+  })
+
+  it('matches reasoning heuristic for deepseek-r1', () => {
+    const model: LiteLLMModel = { id: 'deepseek-r1' }
+    expect(mapLiteLLMModel(model).reasoning).toBe(true)
+  })
+
+  it('matches reasoning heuristic for o3-mini', () => {
+    const model: LiteLLMModel = { id: 'o3-mini' }
+    expect(mapLiteLLMModel(model).reasoning).toBe(true)
+  })
+
+  it('does NOT match reasoning for gpt-4o', () => {
+    const model: LiteLLMModel = { id: 'gpt-4o' }
+    expect(mapLiteLLMModel(model).reasoning).toBe(false)
+  })
+
+  it('does NOT match reasoning for claude-sonnet-4', () => {
+    const model: LiteLLMModel = { id: 'claude-sonnet-4' }
+    expect(mapLiteLLMModel(model).reasoning).toBe(false)
+  })
+
+  it('uses custom max_model_len for limits', () => {
+    const model: LiteLLMModel = { id: 'gpt-4', max_model_len: 128000 }
+    const result = mapLiteLLMModel(model)
+
+    expect(result.limit).toEqual({ context: 128000, output: 128000 })
+  })
+})
+
+describe('resolvePluginConfig', () => {
+  const originalEnv = { ...process.env }
+
+  afterEach(() => {
+    process.env = { ...originalEnv }
+  })
+
+  describe('environment variable priority', () => {
+    it('returns config from env vars when both are set', () => {
+      process.env.LITELLM_URL = 'https://env.example.com'
+      process.env.LITELLM_KEY = 'env-key-123'
+
+      const config = resolvePluginConfig({ url: 'https://config.example.com', apiKey: 'config-key' })
+      expect(config).toEqual({ url: 'https://env.example.com', apiKey: 'env-key-123' })
+    })
+
+    it('ignores config options when env vars are set', () => {
+      process.env.LITELLM_URL = 'https://env.example.com'
+      process.env.LITELLM_KEY = 'env-key-123'
+
+      const config = resolvePluginConfig({ url: 'https://different.example.com', apiKey: 'different-key' })
+      expect(config).toEqual({ url: 'https://env.example.com', apiKey: 'env-key-123' })
+    })
+
+    it('falls back to config when only one env var is set', () => {
+      process.env.LITELLM_URL = 'https://env.example.com'
+      delete process.env.LITELLM_KEY
+
+      const config = resolvePluginConfig({ url: 'https://config.example.com', apiKey: 'config-key' })
+      expect(config).toEqual({ url: 'https://config.example.com', apiKey: 'config-key' })
+    })
+
+    it('falls back to config when env vars are empty strings', () => {
+      process.env.LITELLM_URL = ''
+      process.env.LITELLM_KEY = ''
+
+      const config = resolvePluginConfig({ url: 'https://config.example.com', apiKey: 'config-key' })
+      expect(config).toEqual({ url: 'https://config.example.com', apiKey: 'config-key' })
+    })
+  })
+
+  describe('config options fallback', () => {
+    beforeEach(() => {
+      delete process.env.LITELLM_URL
+      delete process.env.LITELLM_KEY
+    })
+
+    it('returns config for valid input', () => {
+      const config = resolvePluginConfig({ url: 'https://config.example.com', apiKey: 'my-api-key' })
+      expect(config).toEqual({ url: 'https://config.example.com', apiKey: 'my-api-key' })
+    })
+
+    it('returns null when url is missing', () => {
+      const config = resolvePluginConfig({ apiKey: 'my-api-key' })
+      expect(config).toBeNull()
+    })
+
+    it('returns null when apiKey is missing', () => {
+      const config = resolvePluginConfig({ url: 'https://config.example.com' })
+      expect(config).toBeNull()
+    })
+
+    it('returns null for null input', () => {
+      expect(resolvePluginConfig(null)).toBeNull()
+    })
+
+    it('returns null for undefined input', () => {
+      expect(resolvePluginConfig(undefined)).toBeNull()
+    })
+
+    it('returns null for non-object input', () => {
+      expect(resolvePluginConfig('string')).toBeNull()
+      expect(resolvePluginConfig(42)).toBeNull()
+      expect(resolvePluginConfig([])).toBeNull()
+    })
+
+    it('returns null for empty string url', () => {
+      expect(resolvePluginConfig({ url: '', apiKey: 'valid' })).toBeNull()
+    })
+
+    it('returns null for empty string apiKey', () => {
+      expect(resolvePluginConfig({ url: 'https://config.example.com', apiKey: '' })).toBeNull()
+    })
+
+    it('returns null when neither env vars nor config are available', () => {
+      delete process.env.LITELLM_URL
+      delete process.env.LITELLM_KEY
+      expect(resolvePluginConfig({})).toBeNull()
+    })
+  })
+})

package/src/utils.ts

@@ -0,0 +1,64 @@
+import type { LiteLLMModel, OpencodeModelConfig, PluginConfig } from './types.js'
+
+/**
+ * Maps a LiteLLM model to OpenCode model config format.
+ */
+export function mapLiteLLMModel(model: LiteLLMModel): OpencodeModelConfig {
+  const maxLen = model.max_model_len ?? 32768
+  const reasoning = /qwen3|deepseek-r1|o[134]/i.test(model.id)
+
+  return {
+    name: model.id,
+    tool_call: true,
+    reasoning,
+    limit: {
+      context: maxLen,
+      output: maxLen,
+    },
+    modalities: {
+      input: ['text'],
+      output: ['text'],
+    },
+  }
+}
+
+/**
+ * Resolves plugin configuration from environment variables or config options.
+ *
+ * Priority:
+ * 1. LITELLM_URL / LITELLM_KEY environment variables
+ * 2. Values from opencode.json plugin options
+ *
+ * Returns null if no source provides both url and apiKey.
+ */
+export function resolvePluginConfig(rawConfig: unknown): PluginConfig | null {
+  const envUrl = typeof process !== 'undefined' ? process.env.LITELLM_URL : undefined
+  const envKey = typeof process !== 'undefined' ? process.env.LITELLM_KEY : undefined
+
+  const hasEnvVars = envUrl !== undefined && envUrl.length > 0 &&
+                     envKey !== undefined && envKey.length > 0
+
+  if (hasEnvVars) {
+    return { url: envUrl, apiKey: envKey }
+  }
+
+  // Fall back to config options from opencode.json
+  if (rawConfig && typeof rawConfig === 'object' && !Array.isArray(rawConfig)) {
+    const obj = rawConfig as Record<string, unknown>
+    const configUrl = typeof obj.url === 'string' ? obj.url : ''
+    const configKey = typeof obj.apiKey === 'string' ? obj.apiKey : ''
+
+    if (configUrl.length > 0 && configKey.length > 0) {
+      return { url: configUrl, apiKey: configKey }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Gets the provider ID from environment variable or defaults to "LiteLLM".
+ */
+export function getProviderId(): string {
+  return (typeof process !== 'undefined' ? process.env.LITELLM_PROVIDER_ID : undefined) || 'LiteLLM'
+}