Proposal: opt-in /models discovery for custom OpenAI-compatible providers

[maxsonderby]

Proposal: opt-in /models discovery for custom OpenAI-compatible providers

Custom OpenAI-compatible providers currently require every model ID to be copied into ~/.prime/agent/models.json. That catalog becomes stale whenever a local server or proxy adds, removes, or renames a model.

I propose one opt-in provider field:

{
  "providers": {
    "local": {
      "baseUrl": "http://localhost:8000/v1",
      "api": "openai-completions",
      "apiKey": "local",
      "discoverModels": true
    }
  }
}

When enabled, existing async catalog refresh paths request GET <baseUrl>/models, parse the standard data[].id shape, and synthesize entries with the same defaults already used for minimal custom model definitions. Explicit models entries win. modelOverrides can add capability metadata for discovered IDs.

Compatibility boundary:

• Default is disabled. Existing configurations perform no new network requests.
• Only custom openai-completions providers are supported initially.
• No daemon protocol changes.
• Three-second timeout, five-minute in-memory success cache, ten-second failure backoff.
• Failure is non-fatal and preserves explicit models and the last matching cached catalog.
• --offline performs no discovery requests.
• CLI --provider/--model discovery targets only the requested provider.
• Config reload races discard responses from obsolete provider configurations.

The implementation is isolated to the coding-agent model registry/resolver, with mocked tests for absent-flag behavior, auth/headers, mapping/defaults, explicit override precedence, caching, failure/offline behavior, config-reload races, targeted refresh consistency, and CLI model selection.

Related: #1394 proposes live discovery for the bundled OpenRouter provider. This proposal is narrower and separate: it changes no built-in provider and only activates for user-defined providers that opt in.

Would maintainers accept this scope as a PR?