refactor(provider-core): expose model metadata through a ModelCatalog port

[juliusmarminge]

Antigravity, Claude, and Codex read the server's ModelManifest service directly, so they can't move into packages. This adds a ModelCatalog port in provider-core. Providers see only their own catalog entry through it, and the manifest (bundle, remote refresh, disk cache, compatibility policies) stays with the server.

Port (@t3tools/provider-core/server/ModelCatalog)

• current(driverKind) and bundled(driverKind) return the driver's catalog from the in-memory manifest or the bundle. They never fetch.
• refreshInBackground starts the TTL-gated remote refresh that drivers kick off from provider checks.
• Pure helpers: classifyCatalogModels, applyCatalogDefault, applyModelCatalog, and catalogServerModel. A driver can pass an optional CatalogMatching to map its slugs to catalog families.

Server

• ModelManifest.layerModelCatalog provides the port from the existing manifest service. layerTest provides both, so existing tests keep working.
• resolveProviderCatalog now returns the port's ProviderCatalog, and the manifest-wide apply* and classify* helpers are removed.
• Provider-specific branches leave the generic code. Codex's family matching and update-required models move to codexModelCatalog.ts. Claude's catalog resolves from its ProviderCatalog entry. Antigravity uses applyModelCatalog.

Tests

• The generic classify and default tests move to provider-core.
• The Codex update-required tests move next to codexModelCatalog.
• The Claude catalog tests go through the port the way the driver does.
• I ran 239 tests across the manifest, catalog, drivers, provider registry, compatibility, maintenance runner, Codex installation, and Claude provider, and all passed. Typecheck, lint, and knip pass.

Done by Claude Opus 5.5 in Claude Code.

🤖 Generated with Claude Code

---

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces and wires a new shared ModelCatalog abstraction across three production provider drivers, affecting model metadata, classification, fallback, and default-selection paths. The manifest values remain unchanged, but the cross-component refactor and changed default plumbing warrant human review.

No code changes detected at 3637b65. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	5.0 KiB	4.9 KiB	−23 B (−0.5%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	−23 B (−1.9%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.9 KiB	20.8 KiB	−41 B (−0.2%)	29.3 KiB	✅
Codex	Live turn messages	2	1	−1 (−50.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	+24 B (+0.5%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	+24 B (+2.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	+41 B (+0.2%)	29.3 KiB	✅
Claude	Live turn messages	1	2	+1 (+100.0%)	8	✅

Baseline: a669827 · PR result: 3637b65 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: 0074f7b7-7c43-407a-bb95-064b4d6eb75f

---

📥 Commits

Reviewing files that changed from the base of the PR and between 3c9e832 and 3637b65.

---

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: d87f081a-6941-4dc1-8cab-212251d2fe91

---

📥 Commits

Reviewing files that changed from the base of the PR and between 43f8a8d and 3c9e832.

---

📒 Files selected for processing (14)

• apps/server/src/provider/ClaudeModelCatalog.test.ts
• apps/server/src/provider/ClaudeModelCatalog.ts
• apps/server/src/provider/Drivers/AntigravityDriver.ts
• apps/server/src/provider/Drivers/ClaudeDriver.ts
• apps/server/src/provider/Drivers/CodexDriver.ts
• apps/server/src/provider/ModelManifest.test.ts
• apps/server/src/provider/ModelManifest.ts
• apps/server/src/provider/codexModelCatalog.test.ts
• apps/server/src/provider/codexModelCatalog.ts
• apps/server/src/server.ts
• docs/internals/model-manifest.md
• packages/provider-core/package.json
• packages/provider-core/src/server/ModelCatalog.test.ts
• packages/provider-core/src/server/ModelCatalog.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The server now exposes provider model data through a shared ModelCatalog service. Provider drivers use resolved catalogs for model classification and defaults. Claude uses a catalog adapter with a bundled fallback, and Codex applies catalog-based update eligibility.

Changes

Provider model catalog

Layer / File(s)	Summary
Shared catalog contract and model application packages/provider-core/src/server/ModelCatalog.ts, packages/provider-core/src/server/ModelCatalog.test.ts, packages/provider-core/package.json	Adds catalog types and a service for current and bundled catalogs. Catalog helpers convert entries to server models, classify models, and apply defaults. Tests cover classification, matching, and default behavior.
Manifest-backed catalog resolution apps/server/src/provider/ModelManifest.ts, apps/server/src/provider/ModelManifest.test.ts, apps/server/src/server.ts, docs/internals/model-manifest.md	resolveProviderCatalog now returns provider-core catalog data. The manifest layer provides current and bundled catalogs and background refresh. Runtime wiring and documentation use the catalog service.
Claude and Antigravity catalog integration apps/server/src/provider/Drivers/AntigravityDriver.ts, apps/server/src/provider/Drivers/ClaudeDriver.ts, apps/server/src/provider/ClaudeModelCatalog.ts, apps/server/src/provider/ClaudeModelCatalog.test.ts	Both drivers read and refresh the catalog service. Claude resolves its catalog from provider catalog data, uses catalog-based server models, and falls back to its bundled catalog.
Codex catalog policy and driver integration apps/server/src/provider/codexModelCatalog.ts, apps/server/src/provider/codexModelCatalog.test.ts, apps/server/src/provider/Drivers/CodexDriver.ts	Adds Codex family classification and update-required model selection based on installed version and discovered models. The Codex driver applies this catalog to checks and initial snapshots.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Refactor

Sequence Diagram(s)

sequenceDiagram
  participant ModelManifest
  participant ModelCatalog
  participant CodexDriver
  participant CodexModelCatalog
  ModelManifest->>ModelCatalog: Resolve manifest data into provider catalogs
  CodexDriver->>ModelCatalog: Read current catalog
  CodexDriver->>CodexModelCatalog: Apply catalog to provider draft
  CodexModelCatalog->>CodexDriver: Return classified draft and eligible update-required models

Loading

Suggested reviewers: t3dotgg

---

Merge Risk: ⚪ Minimal · up to 3c9e8

No identified catalog regression remains to fix before merging. Normal checks can proceed.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check		The title is concise, specific, and accurately describes the main change: exposing model metadata through a ModelCatalog port.
Description check		The description clearly explains the problem, implementation, affected components, tests, validation results, and agent details. It does not include an explicit issue or maintainer-approval link for t…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

---

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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