feat(plugin): filter discovered models via includeModels/excludeModels

[zyc]

Summary

Adds per-provider includeModels/excludeModels options (glob patterns, * only) so a single LiteLLM proxy's catalog can be split across several OpenCode providers — e.g. one per naming prefix — without hand-maintaining a model list per provider. Also fixes a pre-existing idempotency-cache bug that already affects the litellm/litellm-responses pairing documented in the README.

Type of change

• 🐛 Bug fix (non-breaking)
• ✨ New feature (non-breaking)
• 💥 Breaking change
• 📝 Documentation only
• 🔧 Internal / refactor

(Also includes a small non-breaking bug fix as a drive-by — see below.)

Checklist

• npm run typecheck passes
• No new runtime dependencies
• README updated (new "Splitting one proxy into multiple providers" section + Features table row)
• CHANGELOG.md updated under ## [Unreleased]
• Commit messages follow Conventional Commits

Details

• includeModels is evaluated first (default: everything passes, so this is fully backward-compatible for anyone not setting either option); excludeModels is evaluated after and always wins. Implemented in src/utils/model-filter.ts with a minimal *-only glob-to-regex conversion (no new dependency).
• Applied in both the config hook (src/plugin/index.ts, the path OpenCode actually executes) and discoverBucket (src/plugin/discover.ts, the V2-schema path — it has no callers today, kept in sync for consistency with the rest of that file).
• Drive-by fix: injectedModelIds was keyed only by baseURL, so any two providers sharing a proxy clobber each other's idempotency tracking on every config-hook invocation, defeating the "repeat invocations are a no-op" guarantee. This already affects the existing litellm/litellm-responses pairing (README "Reasoning models") — includeModels/excludeModels just adds another way to hit it. Now keyed by providerId:baseURL.
• Warns (in the config hook only) when includeModels/excludeModels removes every discovered model for a provider, since a typo'd glob pattern is the likeliest misuse and would otherwise leave the provider silently empty.

How was this tested?

• npm run typecheck (only check this repo's CI runs — no test suite exists yet).
• Manually traced the glob-matching logic against edge cases: empty patterns, patterns containing regex metacharacters, and real model ids with literal dots (gpt-4.1, claude-3.5-sonnet) to confirm they're matched literally, not misinterpreted as regex.
• Running against my own LiteLLM proxy in daily use since before this PR, across two provider configs at once (one excludeModels-only, one combining includeModels+excludeModels) splitting the same proxy's catalog into two OpenCode providers — confirmed via the plugin's own discovery log line and opencode models --verbose.

Summary by CodeRabbit

• New Features

  • Added model filtering for LiteLLM providers using includeModels and excludeModels glob patterns.
  • Supports separate provider configurations for production, staging, canary, and other model sets.
  • Inclusion filters are applied first, with exclusions taking precedence.
  • Added clearer discovery reporting when models are filtered or no eligible models remain.

• Documentation

  • Documented model filtering options, behavior, and configuration examples.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b6896f22-a3aa-47b7-b9ae-029edee69308

📥 Commits

Reviewing files that changed from the base of the PR and between f7a20e0 and 246f09a.

📒 Files selected for processing (7)

• CHANGELOG.md
• README.md
• src/plugin/discover.ts
• src/plugin/index.ts
• src/types/index.ts
• src/utils/index.ts
• src/utils/model-filter.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The plugin adds includeModels and excludeModels provider options. It filters discovered model IDs with anchored * patterns, applies exclusions after inclusions, and scopes discovery caching by provider ID and base URL.

Changes

Model discovery filtering

Layer / File(s)	Summary
Filter contract and matcher src/types/index.ts, src/utils/model-filter.ts, src/utils/index.ts	Adds includeModels and excludeModels options and exports matching logic for literal characters and * wildcards.
Discovery integration and caching src/plugin/discover.ts, src/plugin/index.ts	Filters models before transport selection, tracks filtered counts, warns when all non-wildcard models are removed, and keys discovery state by provider ID and base URL.
Configuration documentation README.md, CHANGELOG.md	Documents multi-provider filtering, filter precedence, wildcard behavior, and the unreleased feature.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 246f0

This change adds configurable model filtering and an idempotency-key fix without any identified current-head merge-blocking risk; it is merge-ready after normal checks and review.

Possibly related PRs

• yuseferi/opencode-litellm#10: Both changes modify the model discovery pipeline in src/plugin/index.ts.

Suggested reviewers: yuseferi

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: filtering discovered plugin models with includeModels and excludeModels.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[yuseferi]

Hey @zyc there are some conflict, I appreciate if you resolve the conflicts.

Best

[yuseferi]

Thanks for this — the feature is well motivated (splitting one proxy's catalog across providers without hand-maintained lists), the minimal *-only glob keeps it dependency-free, and the README/tests discipline in the PR is appreciated.

Review notes before this can move forward:

1. The branch is stale and conflicts with main. src/plugin/index.ts has been significantly reworked on main (and further in #24), and the drive-by fix here (keying injectedModelIds by provider + baseURL) has already landed — #24 keys injectedModelIds, refreshContexts, and refreshInFlight by providerId@baseURL. So that part of the PR can be dropped entirely on rebase.

2. A real gap once the SWR cache is involved: since v0.10 the plugin serves models from an on-disk cache on the fast path and refreshes that cache in the background via discoverModels(). This PR applies passesModelFilter only in the cold discovery path, so:

• backgroundRefresh() writes an unfiltered result into the cache, and
• the next startup's cache-hit path merges it without filtering.

Net effect: filters work on first run, then silently stop applying after the first background refresh. On rebase, the filter needs to be applied inside discoverModels() (or at merge time in both the cold and cache-hit paths) so every path respects it. That also has a nice side effect: the filtered log counters can live in one place.

3. src/plugin/discover.ts (the V2-schema path) is dead code scheduled for removal in #24 — no need to keep it in sync; that hunk can be dropped.

Once #24 merges, a rebase onto main should be small: model-filter.ts + the config-hook application + types/README carry over almost as-is, and tests can now be written against the vitest suite that #24 adds. Happy to review the rebased version quickly.

[yuseferi]

@zyc — thank you again for this contribution! Since the rebase onto the post-#24/#26 codebase would have been substantial (the surrounding config hook was rewritten, discover.ts is gone, and the drive-by fix already landed), we took the liberty of carrying your work forward ourselves: #27.

It's your design and implementation — the model-filter.ts glob logic, the option semantics, and the README section all carry over, with a Co-authored-by credit. The one functional change from the review above: the filter is applied inside discoverModels() so the SWR cache and background refresh can't silently bypass it (your original only filtered the cold path).

You're very welcome to review #27 before it ships. Thanks for the feature and the patience!

[yuseferi]

Closing this in favor of #27, which carries this feature onto the current codebase — with a Co-authored-by credit for @zyc. Thanks again for the contribution! The one change from the original: filtering now happens inside discoverModels() so the SWR cache and background refresh can't bypass it. Review welcome over on #27 before it merges.