[feature]: Generic OpenAI-compatible gateway quota provider

[andrewshawcare]

Pre-flight checks

• I searched existing issues and did not find a duplicate request.
• I reviewed current behavior on the production released OpenCode version.

OpenCode version reviewed

1.15.12

Problem statement

Every provider hardcodes its vendor's balance/quota URL in src/lib/<vendor>.ts, and createProviderApiKeyResolver reads only an API key, not a base URL. So self-hosted / OpenAI-compatible gateways (LiteLLM proxies, in-house or university gateways, Vertex/Apigee fronts, OpenRouter-compatible endpoints) can't be supported, even though users already configure them as ordinary OpenAI-compatible providers for chat.

There's no standard remaining-quota endpoint, so each such gateway publishes its own small JSON but the plugin currently has no way to point at one.

Proposed change

A single, config-driven generic provider (openai-compatible) that polls a configurable quota endpoint and maps a small JSON shape into the normalized entries. One provider covers any number of gateways:

"experimental": {
  "quotaToast": {
    "openaiCompatibleGateways": [
      { "providerId": "my-gateway", "quotaPath": "/quota" }
      // baseURL inherited from provider.<id>.options.baseURL; apiKey via the existing resolver
    ]
  }
}

Key resolved via the existing createProviderApiKeyResolver (env / trusted global config / auth.json), keyed on providerId.

GET <baseURL><quotaPath> (Bearer) → a default vendor-neutral shape:

  {
    key,
    tokens: {
      limit,
      used,
      remaining,
      resets_at
    },
    cost: {
      currency,
      limit,
      used,
      remaining
    }
  }

with a built-in openrouter preset mapping (data:{usage,limit,limit_remaining}) so OpenRouter-style endpoints work too.

Token bucket → percent entry; cost → value entries. Bound to no product.

I'd start from contributing/provider-template/ and follow the existing resolver/result-helper patterns.

Alternatives considered

1. Hardcode OpenRouter (add an openrouter.ts): narrower (one product) and binds to a product API rather than the open OpenAI-compatible class.
2. Read a marker off provider.<id>.options instead of plugin config: avoids new plugin-config surface, but risks OpenCode rejecting unknown options keys and couples to the chat provider block.

Acceptance criteria

• openai-compatible provider registered; config-driven gateways list validated like other settings.
• Default neutral shape + openrouter preset mapping, both unit-tested (env/config/auth key sources covered).
• pnpm run typecheck && pnpm test && pnpm run build green; started from contributing/provider-template/.
• README documents setup; /quota_status reports the provider's key source.

[andrewshawcare]

1. Config location: is experimental.quotaToast.openaiCompatibleGateways the right home, or do you prefer reading markers off the OpenCode provider.* block?
2. matchesCurrentModel: its signature (model, context) can't see config; for a config-driven provider, is resolving matches via the configured providerIds (cached at fetch time) acceptable, or would you rather extend the signature/context?
3. enabledProviders: should it accept user-defined gateway ids, or stay limited to the canonical openai-compatible id?

[HerShin5]

This is a useful direction for cost control, especially because most OpenAI-compatible chat gateways will never converge on a single quota API.

A couple of implementation details I’d suggest for the generic provider:

• Allow quotaUrl to be absolute as well as baseURL + quotaPath. Some gateways put billing/usage APIs under a dashboard host rather than the chat /v1 host, and some deliberately do not expose quota from the inference origin.
• Treat quota as best-effort telemetry, not provider health. If the quota endpoint 404s/429s/times out, the plugin should show quota: unavailable and back off, not mark the model provider as broken.
• Keep model matching separate from provider matching: a gateway may expose aliases like claude-sonnet, deepseek-chat, or gpt-*, but the quota bucket is often per API key or account group rather than per requested model.
• Store both token and cost dimensions when available, with an explicit source field (upstream, gateway, estimated, unknown) so users don’t mistake an estimate for authoritative billing.
• Redact endpoint/key details in /quota_status, but include enough provider id / gateway id to debug “am I looking at the right key?” problems.

Disclosure: I’m associated with/evaluating KiroForge as an OpenAI-compatible gateway, so this pattern is directly relevant to gateway users trying to avoid surprise spend without hardcoding one vendor.

[andrewshawcare]

Sounds good, will get back shortly with changes.

[github-actions]

This issue has been inactive for 23 days. It will be closed in 7 days if there is no further activity.