diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index a6a62e36cc2a..e0c92a810763 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -2631,6 +2631,7 @@ export type ConfigEntry = console_watches?: boolean mcp_events?: boolean full_codemode?: boolean + openai_compatible_discovery?: boolean schedules?: boolean part_rows?: boolean image_generate?: boolean | { model?: string | { providerID: string; model: string; variant?: string } } diff --git a/packages/core/src/plugin/internal.ts b/packages/core/src/plugin/internal.ts index 988343b8189b..cdcca82abf5a 100644 --- a/packages/core/src/plugin/internal.ts +++ b/packages/core/src/plugin/internal.ts @@ -110,6 +110,7 @@ import { McpCodeModeDefaultsPlugin } from "./mcp-codemode-defaults.js" import { ProviderPlugins } from "./provider.js" import { DynamicProviderPlugin } from "./provider/dynamic.js" import { OpencodePlugin } from "./provider/opencode.js" +import { OpenAICompatiblePlugin } from "./provider/openai-compatible.js" import { WebSearchPlugins } from "./websearch/index.js" import { SkillPlugin } from "./skill.js" import { VcsHgPlugin } from "./vcs/hg.js" @@ -305,6 +306,8 @@ const post = [ ConfigProviderPlugin.Plugin, // Run the dynamic npm SDK loader after SDK, instance, and external plugins register their `sdk` hooks. DynamicProviderPlugin, + // Fills configured providers with discovered models, so it must see their config applied first. + OpenAICompatiblePlugin, ConfigWebSearchPlugin.Plugin, ConfigPolicyPlugin.Plugin, ] as const satisfies readonly InternalPlugin[] diff --git a/packages/core/src/plugin/provider/openai-compatible.ts b/packages/core/src/plugin/provider/openai-compatible.ts new file mode 100644 index 000000000000..addf77701cdc --- /dev/null +++ b/packages/core/src/plugin/provider/openai-compatible.ts @@ -0,0 +1,178 @@ +import { define } from "@opencode/plugin/effect/plugin" +import type { Document, Entry } from "@opencode/schema/config" +import { type Duration, Effect, Schedule, Schema, Semaphore, Stream } from "effect" +import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http" +import { Bus } from "../../bus.js" +import { Config } from "../../config.js" +import { Credential } from "../../credential.js" +import { Flag } from "../../flag.js" +import { Model } from "../../model.js" +import { Provider } from "../../provider.js" +import type { PluginInternal } from "../internal.js" +import { foldSettings } from "./configured.js" + +const Strings = Schema.NullOr(Schema.Array(Schema.String)).pipe(Schema.optional) + +const RemoteModel = Schema.Struct({ + id: Schema.String, + mode: Schema.NullOr(Schema.String).pipe(Schema.optional), + // Gateways report modalities at the top level or under `architecture`, as OpenRouter does. + input_modalities: Strings, + output_modalities: Strings, + architecture: Schema.NullOr(Schema.Struct({ input_modalities: Strings, output_modalities: Strings })).pipe( + Schema.optional, + ), + supported_parameters: Strings, +}) + +const Models = Schema.Struct({ data: Schema.Array(RemoteModel) }) + +// Gateways such as LiteLLM also list embedding, image, and audio models. +const chat = new Set(["chat", "responses"]) + +const packages = new Set(["@ai-sdk/openai-compatible", "@opencode/ai/providers/openai-compatible"]) + +// These providers have dedicated discovery plugins that own their whole model list. +const dedicated = new Set(["ollama", "lmstudio", "vllm"]) + +type Target = ReturnType[number] + +export function make(interval: Duration.Input = "5 minutes") { + return define({ + id: "opencode.provider.openai-compatible", + effect: Effect.fn(function* (ctx) { + const http = HttpClient.filterStatusOk(yield* HttpClient.HttpClient) + const bus = yield* Bus.Service + const config = yield* Config.Service + const flags = yield* Flag.Service + const loading = Semaphore.makeUnsafe(1) + const loaded = { + inventory: new Map< + Provider.ID, + { source: string; models: readonly { id: string; capabilities: Model.Capabilities }[] } + >(), + hash: "[]", + } + + yield* ctx.provider.transform((providers) => { + for (const [providerID, item] of loaded.inventory) { + const provider = providers.get(providerID) + if (!provider) continue + for (const model of item.models) { + // Configured models keep their own capabilities. + if (provider.models.has(Model.ID.make(model.id))) continue + providers.models.update(providerID, model.id, (draft) => { + draft.capabilities = { + tools: model.capabilities.tools, + input: [...model.capabilities.input], + output: [...model.capabilities.output], + } + }) + } + } + }) + + const inventory = Effect.fnUntraced(function* (target: Target) { + const connection = yield* ctx.integration.connection.active(target.providerID) + const credential = connection + ? yield* ctx.integration.connection.resolve(connection).pipe(Effect.orElseSucceed(() => undefined)) + : undefined + // Same precedence as requests: a stored key replaces the configured one. + const apiKey = credential?.type === "key" ? credential.key : target.apiKey + const source = JSON.stringify([target.baseURL, apiKey, target.headers]) + const previous = loaded.inventory.get(target.providerID) + const request = HttpClientRequest.get(`${target.baseURL}/models`).pipe( + HttpClientRequest.acceptJson, + HttpClientRequest.setHeaders(target.headers ?? {}), + ) + const models = yield* http.execute(apiKey ? request.pipe(HttpClientRequest.bearerToken(apiKey)) : request).pipe( + Effect.flatMap(HttpClientResponse.schemaBodyJson(Models)), + Effect.timeout("5 seconds"), + Effect.map((response) => + response.data + .filter((model) => model.id.length > 0 && (!model.mode || chat.has(model.mode))) + .map((model) => ({ id: model.id, capabilities: capabilities(model) })) + .toSorted((a, b) => a.id.localeCompare(b.id)), + ), + // Log the message only: the request in the cause carries configured headers, which may hold secrets. + Effect.tapError((error) => + Effect.logDebug("openai-compatible model discovery failed", { + providerID: target.providerID, + message: error.message, + }), + ), + // Keep the last successful inventory through transient outages while the endpoint and key are unchanged. + Effect.orElseSucceed(() => (previous?.source === source ? previous.models : undefined)), + ) + return models === undefined ? [] : [[target.providerID, { source, models }] as const] + }) + + const load = Effect.fn("OpenAICompatiblePlugin.load")(function* () { + const entries = yield* config.entries() + // Internal plugins are not re-run on config changes, so read the flag on every refresh; turning it off drops + // the discovered models. + const results = flags.resolve(entries).openai_compatible_discovery.enabled + ? yield* Effect.forEach(targets(entries), inventory, { concurrency: 4 }) + : [] + const next = new Map(results.flat()) + const hash = JSON.stringify([...next]) + if (hash === loaded.hash) return + loaded.inventory = next + loaded.hash = hash + yield* ctx.provider.reload() + }) + const refresh = () => loading.withPermit(load()) + + yield* ctx.event.subscribe().pipe( + Stream.filter((event) => event.type === "config.updated"), + Stream.runForEach(refresh), + Effect.forkScoped({ startImmediately: true }), + ) + yield* bus.subscribe(Credential.Event.Switched).pipe( + Stream.runForEach(refresh), + Effect.forkScoped({ startImmediately: true }), + ) + yield* refresh().pipe(Effect.ignore, Effect.repeat(Schedule.spaced(interval)), Effect.forkScoped) + }), + } satisfies PluginInternal.InternalPlugin) +} + +export const OpenAICompatiblePlugin = make() + +function targets(entries: readonly Entry[]) { + const documents = entries.filter((entry): entry is Document => entry.type === "document") + const ids = new Set(documents.flatMap((file) => Object.keys(file.info.providers ?? {}))) + return [...ids].flatMap((id) => { + if (dedicated.has(id)) return [] + const configured = documents.flatMap((file) => file.info.providers?.[id] ?? []) + const pkg = configured.findLast((item) => item.package !== undefined)?.package + // Migrated V1 configs store the package as `aisdk:@ai-sdk/openai-compatible`. + if (pkg === undefined || !packages.has(Provider.packageName(pkg))) return [] + const settings = foldSettings(entries, id, undefined) + const baseURL = typeof settings?.baseURL === "string" ? settings.baseURL.replace(/\/+$/, "") : "" + if (!URL.canParse(baseURL) || !["http:", "https:"].includes(new URL(baseURL).protocol)) return [] + return [ + { + providerID: Provider.ID.make(id), + baseURL, + apiKey: typeof settings?.apiKey === "string" && settings.apiKey !== "" ? settings.apiKey : undefined, + headers: configured.reduce( + (headers: Record | undefined, item) => Provider.mergeHeaders(headers, item.headers), + undefined, + ), + }, + ] + }) +} + +// Without metadata, assume text-only input: an image sent to a text-only model fails every later request in the +// session, while a missing image capability only blocks attachments. +function capabilities(model: typeof RemoteModel.Type): Model.Capabilities { + const input = model.input_modalities ?? model.architecture?.input_modalities ?? ["text"] + return { + tools: model.supported_parameters?.includes("tools") ?? true, + // OpenRouter calls PDF input `file`. + input: input.map((modality) => (modality === "file" ? "pdf" : modality)), + output: model.output_modalities ?? model.architecture?.output_modalities ?? ["text"], + } +} diff --git a/packages/core/test/plugin/provider-openai-compatible.test.ts b/packages/core/test/plugin/provider-openai-compatible.test.ts new file mode 100644 index 000000000000..a7f6a3028bdf --- /dev/null +++ b/packages/core/test/plugin/provider-openai-compatible.test.ts @@ -0,0 +1,353 @@ +import { Bus } from "@opencode/core/bus" +import { Config } from "@opencode/core/config" +import { ConfigNormalize } from "@opencode/core/config/normalize" +import { ConfigProviderPlugin } from "@opencode/core/config/plugin/provider" +import { Credential } from "@opencode/core/credential" +import { Integration } from "@opencode/core/integration" +import { Model } from "@opencode/core/model" +import { Plugin } from "@opencode/core/plugin" +import { PluginHost } from "@opencode/core/plugin/host" +import { make } from "@opencode/core/plugin/provider/openai-compatible" +import { Provider } from "@opencode/core/provider" +import { Document, Event, Info } from "@opencode/schema/config" +import { describe, expect } from "bun:test" +import { Effect, Layer, Schema } from "effect" +import { withEnv } from "../fixture/env" +import { testEffect } from "../lib/effect" +import { PluginTestLayer } from "./fixture" + +const it = testEffect(Layer.merge(PluginTestLayer, Config.testLayer())) +const decode = Schema.decodeUnknownSync(Info) + +// Registers the config plugin first, matching production order, so discovery sees configured providers. +const addPlugins = Effect.fn(function* () { + const plugin = yield* Plugin.Service + const config = yield* PluginHost.make(plugin, ConfigProviderPlugin.Plugin.id) + yield* ConfigProviderPlugin.Plugin.effect(config) + const discovery = make("1 hour") + const host = yield* PluginHost.make(plugin, discovery.id) + yield* discovery.effect(host) +}) + +// Bounded by elapsed time rather than attempts, so a slow plugin start on a busy machine still fits. +function eventually( + effect: Effect.Effect, + predicate: (value: A) => boolean, + deadline = Date.now() + 10_000, +): Effect.Effect { + return Effect.gen(function* () { + const value = yield* effect + if (predicate(value)) return value + if (Date.now() > deadline) return yield* Effect.fail(new Error("Timed out waiting for value")) + yield* Effect.promise(() => Bun.sleep(1)) + return yield* eventually(effect, predicate, deadline) + }) +} + +// Shaped like LiteLLM, which only sometimes reports a mode. +const litellm = [ + { id: "configured-model", object: "model" }, + { id: "discovered-model", object: "model", mode: "chat" }, + { id: "untyped-model", object: "model", mode: null }, + { id: "embedding-model", object: "model", mode: "embedding" }, +] + +function serve(data: readonly Record[] = litellm) { + const state = { failing: false } + const requests: Array<{ path: string; authorization: string | null; team: string | null }> = [] + const server = Bun.serve({ + port: 0, + fetch: (request) => { + requests.push({ + path: new URL(request.url).pathname, + authorization: request.headers.get("authorization"), + team: request.headers.get("x-team"), + }) + if (state.failing) return new Response(null, { status: 503 }) + return Response.json({ object: "list", data }) + }, + }) + return { state, requests, server } +} + +// Flags are off in the test channel, so discovery is switched on explicitly. +function configuration(providers: Record, enabled = true) { + return new Document({ + type: "document", + info: decode({ providers, experimental: { openai_compatible_discovery: enabled } }), + }) +} + +describe("OpenAICompatiblePlugin", () => { + it.live("adds discovered models to configured OpenAI-compatible providers without replacing configured ones", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("litellm") + yield* config.setEntries([ + configuration({ + litellm: { + package: "@ai-sdk/openai-compatible", + settings: { baseURL: `${server.url.origin}/litellm/v1/`, apiKey: "secret" }, + headers: { "x-team": "core" }, + models: { "configured-model": { name: "Configured" } }, + }, + mistral: { package: "@ai-sdk/mistral", settings: { baseURL: `${server.url.origin}/mistral` } }, + ollama: { package: "@ai-sdk/openai-compatible", settings: { baseURL: `${server.url.origin}/ollama/v1` } }, + }), + ]) + yield* addPlugins() + + const discovered = yield* eventually( + models.get(providerID, Model.ID.make("discovered-model")), + (model) => model !== undefined, + ) + expect(discovered).toMatchObject({ + modelID: "discovered-model", + name: "discovered-model", + capabilities: { tools: true, input: ["text"], output: ["text"] }, + }) + expect(yield* models.get(providerID, Model.ID.make("untyped-model"))).toBeDefined() + expect(yield* models.get(providerID, Model.ID.make("embedding-model"))).toBeUndefined() + expect(yield* models.get(providerID, Model.ID.make("configured-model"))).toMatchObject({ + name: "Configured", + capabilities: Model.Capabilities.default(), + }) + expect(requests).toEqual([{ path: "/litellm/v1/models", authorization: "Bearer secret", team: "core" }]) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("reads advertised modalities and tool support", () => + Effect.acquireUseRelease( + Effect.sync(() => + serve([ + { + id: "vision-model", + architecture: { input_modalities: ["text", "image", "file"], output_modalities: ["text"] }, + supported_parameters: ["tools", "temperature"], + }, + { id: "text-model", input_modalities: ["text"], supported_parameters: ["temperature"] }, + ]), + ), + ({ server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("gateway") + yield* config.setEntries([ + configuration({ + gateway: { package: "@ai-sdk/openai-compatible", settings: { baseURL: `${server.url.origin}/v1` } }, + }), + ]) + yield* addPlugins() + + const vision = yield* eventually( + models.get(providerID, Model.ID.make("vision-model")), + (model) => model !== undefined, + ) + expect(vision).toMatchObject({ capabilities: { tools: true, input: ["text", "image", "pdf"], output: ["text"] } }) + expect(yield* models.get(providerID, Model.ID.make("text-model"))).toMatchObject({ + capabilities: { tools: false, input: ["text"], output: ["text"] }, + }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("lets config disable a discovered model that reports no mode", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("litellm") + yield* config.setEntries([ + configuration({ + litellm: { + package: "@ai-sdk/openai-compatible", + settings: { baseURL: `${server.url.origin}/v1` }, + models: { "untyped-model": { disabled: true } }, + }, + }), + ]) + yield* addPlugins() + + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model !== undefined) + expect(yield* models.get(providerID, Model.ID.make("untyped-model"))).toMatchObject({ enabled: false }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("discovers keyless providers and prefers a stored key over the configured one", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const credentials = yield* Credential.Service + const models = yield* Model.Service + yield* config.setEntries([ + configuration({ + local: { package: "@ai-sdk/openai-compatible", settings: { baseURL: `${server.url.origin}/local/v1` } }, + gateway: { + package: "@opencode/ai/providers/openai-compatible", + settings: { baseURL: `${server.url.origin}/gateway/v1`, apiKey: "configured" }, + }, + }), + ]) + yield* credentials.create({ + integrationID: Integration.ID.make("gateway"), + value: Credential.Key.make({ type: "key", key: "stored" }), + }) + yield* addPlugins() + + yield* eventually( + models.get(Provider.ID.make("gateway"), Model.ID.make("discovered-model")), + (model) => model !== undefined, + ) + expect(yield* models.get(Provider.ID.make("local"), Model.ID.make("discovered-model"))).toBeDefined() + expect(requests).toContainEqual({ path: "/local/v1/models", authorization: null, team: null }) + expect(requests).toContainEqual({ path: "/gateway/v1/models", authorization: "Bearer stored", team: null }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("uses the key from the provider's configured environment variable", () => + withEnv({ DISCOVERY_ACME_KEY: "from-env" }, () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + yield* config.setEntries([ + configuration({ + acme: { + env: ["DISCOVERY_ACME_KEY"], + package: "@opencode/ai/providers/openai-compatible", + settings: { baseURL: `${server.url.origin}/v1` }, + }, + }), + ]) + yield* addPlugins() + + yield* eventually( + models.get(Provider.ID.make("acme"), Model.ID.make("discovered-model")), + (model) => model !== undefined, + ) + expect(requests).toContainEqual({ path: "/v1/models", authorization: "Bearer from-env", team: null }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ), + ) + + it.live("discovers models for providers migrated from a V1 config", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + const normalized = ConfigNormalize.normalize({ + provider: { + litellm: { + npm: "@ai-sdk/openai-compatible", + options: { baseURL: `${server.url.origin}/v1`, apiKey: "secret" }, + }, + }, + experimental: { openai_compatible_discovery: true }, + }) + if (normalized.type !== "normalized") return yield* Effect.fail(new Error("V1 config was rejected")) + const info = decode(normalized.encoded) + expect(info.providers?.litellm?.package).toBe("aisdk:@ai-sdk/openai-compatible") + yield* config.setEntries([new Document({ type: "document", info })]) + yield* addPlugins() + + yield* eventually( + models.get(Provider.ID.make("litellm"), Model.ID.make("discovered-model")), + (model) => model !== undefined, + ) + expect(requests).toContainEqual({ path: "/v1/models", authorization: "Bearer secret", team: null }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("stops discovery and drops its models when the flag is turned off", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const bus = yield* Bus.Service + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("litellm") + const entries = (enabled: boolean) => [ + configuration( + { litellm: { package: "@ai-sdk/openai-compatible", settings: { baseURL: `${server.url.origin}/v1` } } }, + enabled, + ), + ] + yield* config.setEntries(entries(true)) + yield* addPlugins() + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model !== undefined) + + const before = requests.length + yield* config.setEntries(entries(false)) + yield* bus.publish(Event.Updated, {}) + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model === undefined) + expect(requests.length).toBe(before) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("keeps the last inventory through outages and drops it when the endpoint changes", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ state, requests, server }) => + Effect.gen(function* () { + const bus = yield* Bus.Service + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("litellm") + const entries = (path: string) => [ + configuration({ + litellm: { + package: "@ai-sdk/openai-compatible", + settings: { baseURL: `${server.url.origin}${path}` }, + }, + }), + ] + yield* config.setEntries(entries("/first/v1")) + yield* addPlugins() + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model !== undefined) + + // Config events refresh one at a time, so the second failed request proves the first refresh finished. + state.failing = true + const before = requests.length + yield* bus.publish(Event.Updated, {}) + yield* bus.publish(Event.Updated, {}) + yield* eventually( + Effect.sync(() => requests.length), + (count) => count >= before + 2, + ) + expect(yield* models.get(providerID, Model.ID.make("discovered-model"))).toBeDefined() + + yield* config.setEntries(entries("/second/v1")) + yield* bus.publish(Event.Updated, {}) + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model === undefined) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) +}) diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index 1e241a9bfa20..a7d51d523125 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -17349,6 +17349,9 @@ "full_codemode": { "type": "boolean" }, + "openai_compatible_discovery": { + "type": "boolean" + }, "schedules": { "type": "boolean" }, diff --git a/packages/schema/src/config/flag.ts b/packages/schema/src/config/flag.ts index 4a2064879c2d..b086019e597e 100644 --- a/packages/schema/src/config/flag.ts +++ b/packages/schema/src/config/flag.ts @@ -20,6 +20,8 @@ export const registry = { "Enable experimental MCP Events, a draft MCP extension: declare support to MCP servers and read the events of servers that offer them.", full_codemode: "Enable the full Code Mode work in progress. Off by default in every build, including local and dev; opt in with OPENCODE_FLAGS=full_codemode or experimental.full_codemode: true.", + openai_compatible_discovery: + "Add the models that OpenAI-compatible providers in config list at `GET {baseURL}/models`, so they do not have to be listed by hand.", } as const satisfies Record export type Key = keyof typeof registry diff --git a/services/site/src/docs/content/config.mdx b/services/site/src/docs/content/config.mdx index 3a6cf47e5475..b6de3191c620 100644 --- a/services/site/src/docs/content/config.mdx +++ b/services/site/src/docs/content/config.mdx @@ -644,6 +644,20 @@ Set `todo` to `true` to give agents a `todowrite` tool for tracking multi-step w `subagent_depth` sets how deeply subagents can start their own subagents. Defaults to `1`, so a subagent cannot start another subagent. +### OpenAI-compatible model discovery + +Set `openai_compatible_discovery` to `true` to add the models that OpenAI-compatible providers list at +`GET {baseURL}/models`, so they don't have to be listed under `models`. Defaults to `false`. See +[Discovered models](/providers#discovered-models) for how it works. + +```jsonc +{ + "experimental": { + "openai_compatible_discovery": true, + }, +} +``` + ### Image generation `image_generate` sets the default model for the [`experimental_image_generate`](/tools#image-generate) tool, as diff --git a/services/site/src/docs/content/providers.mdx b/services/site/src/docs/content/providers.mdx index 0d93bcb15b15..e0d96ebf06a7 100644 --- a/services/site/src/docs/content/providers.mdx +++ b/services/site/src/docs/content/providers.mdx @@ -96,6 +96,57 @@ The `providers` object is keyed by the provider ID used in model references, suc | `body` | JSON fields merged into request bodies. | | `models` | Models to add or override, keyed by the OpenCode model ID. | +### Discovered models + +With the [experimental](/config#experimental) `openai_compatible_discovery` flag, OpenCode reads `GET {baseURL}/models` +from OpenAI-compatible providers, so `models` can be omitted. This covers gateways such as LiteLLM: + +```jsonc title="opencode.jsonc" +{ + "experimental": { + "openai_compatible_discovery": true, + }, + "providers": { + "litellm": { + "name": "LiteLLM", + "package": "@opencode/ai/providers/openai-compatible", + "settings": { + "baseURL": "http://127.0.0.1:4000/v1", + }, + }, + }, +} +``` + +- Discovery authenticates with the saved key, an `env` variable, or `settings.apiKey`, and sends the provider `headers`. +- Discovery only adds missing models. Models listed under `models` keep their configuration. +- Models that report a non-chat `mode`, such as embedding models, are skipped. Entries without a `mode` are treated as + chat models; hide one by listing it under `models` with `"disabled": true`. +- The list refreshes every five minutes and after config or credential changes, and survives temporary outages. +- Ollama, LM Studio, and vLLM keep their own [discovery](/models#local). +- Turning the flag off removes the discovered models. + +#### Capabilities + +Discovered models accept text and can call tools. An endpoint can report more per model, at the top level or under +`architecture` as OpenRouter does: + +```json title="GET {baseURL}/models" +{ + "data": [ + { + "id": "qwen3-vl", + "input_modalities": ["text", "image"], + "supported_parameters": ["tools", "temperature"] + } + ] +} +``` + +- `input_modalities` and `output_modalities` replace the text-only default. `file` means PDF input. +- `supported_parameters` without `tools` turns tool calls off. +- Override any of these under `models`. + ## Endpoint Override `settings.baseURL` to send a catalog provider through a proxy or compatible endpoint. Its existing package,