Prefer live CLIProxyAPI model metadata over models.dev

[moutansos]

Summary

• Read the optional context_length, max_completion_tokens, and display_name
  fields from /v1/models entries. Unknown or malformed fields are ignored
  without dropping the model.
• Merge each field independently. User configuration wins over live CLIProxyAPI
  metadata, which wins over the models.dev catalog, which wins over OpenCode's
  defaults. A live context wins even when it is smaller than the catalog value.
• Keep budgets coherent:
  • the output limit never exceeds the context;
  • with only a live context, an inherited output budget is capped at a quarter
    of it;
  • an inherited input limit is capped at context minus output.
• Live limits apply without a catalog match, with modelMetadataURL: false,
  and when enrichment fails. Each refresh rebuilds every model, so changed
  values apply and removed fields fall back.
• The README documents the wire contract, precedence, and the server-side
  enrichment prerequisite. Stock CLIProxyAPI does not send these fields.

There is no provider-specific client logic.

Closes #3

Test plan

• bun run check (typecheck, 35 tests, build).
• New tests cover the issue's acceptance criteria: live context and output
  override the catalog; context-only and output-only merges; no catalog
  match; enrichment disabled and failing; malformed values; explicit falsy
  catalog metadata; refresh with changed and removed fields; the output and
  input capping policy.
• Verified against a live CLIProxyAPI v8.0.11 server with an enrichment
  plugin, through a running OpenCode 2.0.22 (/api/model):
  • deployment models report 32768/8192, 65536/16384, and 196608/32000;
  • Claude and other providers are unchanged.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The change embeds a non-obvious budget-capping heuristic (the quarter-of-context divisor) in core model-limit computation with runtime/operational impact on context and compaction budgets, which warrants final human sign-off.

Review effort: Balanced
Findings: None

What changed in this PR

This PR makes the OpenCode CLIProxyAPI plugin prefer live, deployment-reported model metadata (from /v1/models entries) over the static models.dev catalog, so the harness receives accurate context/compaction budgets for resource-constrained deployments (e.g., Ollama, vLLM, gateways). It remains provider-agnostic: only the recognized optional wire fields (context_length, max_completion_tokens, display_name) are read, with malformed/unknown fields ignored without dropping the model. Merging is per-field with precedence user config > live metadata > models.dev catalog > OpenCode defaults, plus a coherence policy that keeps output/input budgets within the effective context.

Changes:

• Added a LiveMetadata type and parseLiveMetadata/tokenLimit helpers in catalog.ts to normalize optional enriched fields into CatalogModel.live.
• Introduced resolveLimit in index.ts to merge limits per field, cap an inherited output budget to a quarter of a live context, and keep input ≤ context − output; wired live name/limits into buildModel.
• Documented the wire contract, precedence, and server-side enrichment prerequisite in README.md/CHANGELOG.md, with comprehensive new parser, model-building, and refresh tests.

File	Description
src/​catalog.ts	Adds LiveMetadata type, parseLiveMetadata, and tokenLimit; retains recognized optional fields during catalog parsing.
src/​index.ts	Adds resolveLimit with per-field precedence and budget-coherence capping; uses live name/limits in buildModel.
src/​catalog.test.ts	Tests that recognized live metadata is kept and malformed values are ignored without dropping models.
src/​index.test.ts	Tests resolveLimit/buildModel precedence and capping, plus plugin behavior with enrichment disabled/failing and refresh with changed/removed fields.
README.md	Documents the wire contract, precedence, enrichment prerequisite, and budget-coherence policy.
CHANGELOG.md	Records the new live-metadata consumption feature under Unreleased.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.