feat(catalog): infer custom-provider context windows from model metadata

[lcxhh521]

Summary

Custom providers whose model list omits context metadata currently fall back to the 128k compatibility window, even when the bundled model metadata has a larger published window for that exact model ID. This adds a model-ID fallback for those missing windows.

• Keep observed/configured limits first (the smaller wins), then Azure metadata, then the bundled vendor estimate, then an enabled Context cap as the window, and finally 128k. Context caps still clamp the chosen value.
• Consult original-vendor API tables before OpenRouter/OpenCode Go. Preserve exact spellings. Case/dot/hyphen aliases must be unambiguous, and conflicting keys do not escape into a lower-priority table. Skip floating ~ aliases. In the current data, minimax-m3 and MiniMax-M3 actually have different windows, so a normalized first-match implementation would be unsafe.
• Exclude every built-in registry name, including providers without a metadata alias. OpenAI API lookup applies only to custom providers; existing native and built-in provider policies remain intact.
• Record the source provider, original model ID and published window as contextWindowInference. Client catalogs receive the budget, while routing capability provenance keeps the estimate separate from asserted serving-provider capacity. Preserve the marker through custom-row inheritance and recompute window estimates on re-hint.
• Cover custom-only models absent from the provider roster without replacing their explicit modalities, reasoning, or context overrides.
• Update the architecture contract and configuration, Codex, Claude Code and MiniMax documentation in all eight documentation locales.

A matching model ID does not establish a relay's actual capacity. Operators whose relay serves less should set modelContextWindows or Context cap. This does not enable a cap or send model probes automatically. The shared catalog also feeds Claude context selection and other client exports.

Maintainer decisions made explicit in this draft

1. Context authority uses a separate original-vendor allowlist rather than sharing the broader price-vendor list, which includes hosting/subscription sources.
2. Inference is source-labelled and omitted from asserted context_window routing provenance.
3. Existing cap defaults remain; the documentation explains relay-capacity risk.
4. Exact spelling wins within an authority tier; conflicting normalized or aggregator aliases return unknown.
5. Custom providers consult OpenAI API metadata rather than the Codex subscription table. Built-in names never enter this fallback.

The helper remains in catalog derivation because it projects client budgets without changing static provider or request-admission facts. Its placement can be adjusted if a different shared derivation owner is preferred.

Verification

Base: upstream dev at 6da2774369aa32552e318e333902499683d053bc.

• The supplied eight-case reproducer against source archived from that exact base: four missing-window cases fail, four existing precedence/fallback cases pass. Against this implementation: eight pass.
• Bun 1.4.3 focused validation: 261 pass, 0 fail, 14 files / 2,413 assertions. Covers the new lookup, generated catalog and routing-reader round trip, caps, configured/discovered/Azure precedence, actual and synthetic alias collisions, all built-in name exclusions, cached projection, custom-only/custom-inherited/combo paths, interrupted gather authority, Claude context accounting, client config exports, test-layout guards and file-size ratchet.
• Mac ARM64, Bun 1.4.0: vendor-context focused suite 15 pass, 0 fail; typecheck and structure checks passed. This is supplementary platform evidence, not the repository-pinned Bun 1.4.3 full suite.
• bun run typecheck, bun run structure:check, bun run privacy:scan, git diff --check: pass.
• Documentation: bun install --frozen-lockfile and bun run build; 569 pages / 79,417 internal links validated after the final documentation edits.
• bun run test:changed was stopped while queued, before running its suite, because broader fixture network isolation needs separate verification in this environment. No unrelated test-harness changes are included. Full import-connected/cross-platform coverage and exact-head hosted CI remain outstanding.
• All feature validation uses disposable configuration homes and fixtures. No real gateway/model request, Codex process, user account login, or live user-configuration change was used to establish the results. No claim of live 1M capacity is made.
• Independent final source review: no P0–P2 blockers. Independent focused run: 34 pass, 0 fail / 455 assertions.

Rebase validation (2026-10-13)

Rebased onto upstream dev at 20cd56169f501143f3efd53226c1a11528a748e3; the rebase head was 124fca57377703a39fc02e95c8a4036c5c2b0112. The single English provider-documentation conflict preserves both the context-inference wording and the new upstream Azure minMaxOutputTokens setting. Independent static review checked all ten automatically merged files and both test-layout maps. All six runtime feature files are byte-identical to the previously tested head. The new built-in Modelflare provider is covered by the registry-enumeration exclusion test.

Fresh verification on this exact source tree (Bun 1.4.3, disposable configuration homes):

• bun test --isolate over the same 14-file focused selection described above: 261 passed, 0 failed / 2,416 assertions.
• bun run typecheck, bun run structure:check, bun run privacy:scan, and git diff --check: passed.
• Documentation bun install --frozen-lockfile and bun run build: passed, 569 pages / 79,427 internal links.
• Full import-connected/cross-platform tests remain unrun locally for the documented fixture-isolation limitation. Earlier Mac results apply to the pre-rebase revision only. Exact-head hosted CI is pending maintainer approval/results; the PR remains a draft.

Isolated compaction fixture follow-up (2026-10-13)

Current head: cb4f916330ab49daa580a5d7383864d5de47d501. A separate test-only commit addresses the two scenarios reported by Linux shard 3, independently of the context-default policy discussion:

• Move the HTTP replay and quota-handoff cases into tests/responses/responses-compaction-http-isolation.test.ts, preserving all original routing/account assertions and reducing the existing file below its size cap.
• Bind each synthetic executor through provider.fetch and explicitly select HTTP/SSE. Add a fixture-owned abort deadline, propagate the replay relay abort signal, and drain state before restoring fetch/configuration homes. A new regression verifies cancellation settles before restoration.
• Both original cases attempted an unmocked socket path in isolated tests on pristine base 20cd5616 and feature head 124fca57; an additional deny-all guard blocked those attempts. Supplying the fixture transport executor made both cases pass on both revisions. This establishes a fixture-isolation gap; it does not prove the precise cause of the hosted 20-second timeout or every subsequent failure.
• Final focused verification with Bun 1.4.3 and disposable homes: bun test tests/responses/responses-compaction-http-isolation.test.ts with an additional transport/process-blocking preload: 3 passed, 0 failed / 27 assertions, on both the base-plus-fix and feature-plus-fix trees; no blocked transport/process attempts on the fixed runs. The three layout/tooling/file-size regression files: 28 passed, 0 failed / 643 assertions. Typecheck, structure, privacy and whitespace checks passed; independent final source review found no remaining blocker in this fixture patch.

The two #1073 catalog expectations and the default-on inference policy are unchanged. The proposed default-off per-provider opt-in remains a discussion, not an implemented change. The prior full CI failed; full local tests were not rerun, and this new head requires its own hosted CI. This does not mark the PR ready for review.

Maintainer update (2026-10-14): opt-in, conservative default kept

Head 8dc12b84f makes the vendor estimate a per-provider opt-in. providers.<name>.inferContextWindow defaults to off. With it unset or false, an id-only custom row keeps the #1073 behavior: an enabled Context cap becomes the window, otherwise 128k. With true, the precedence described above applies. Built-in provider names stay excluded even when the flag is set. This resolves the two Linux test 2/4 failures in tests/codex-integration/codex-catalog.test.ts (an id-only model with no configured window keeps the conservative fallback (#1073) and an id-only model with an enabled context cap uses that cap as the window) without changing their expectations.

• canInferVendorContext(name, providerConfig) gates both call sites (applyProviderConfigHints and the custom-only gap fill in routed-gather).
• The flag is declared in OcxProviderConfig, the provider zod schema, the provider field-policy map (auth-cors.ts) and the model-rename field map.
• New regression in vendor-context.test.ts: an unset or false flag yields no inference, keeps the cap/128k fallback, and keeps custom-only gather rows uninferred. Existing inference cases now opt in.
• The providers reference in all eight locales documents the flag and its default. The Codex guide and structure/catalog-vendor-context.md / structure/catalog.md say it is opt-in.

Verification on this head: bun run typecheck, bun run structure:check, bun run privacy:scan, git diff --check pass. bun test tests/codex-integration/vendor-context.test.ts tests/codex-integration/codex-catalog.test.ts: 354 pass, 0 fail, including both #1073 cases. Local full-suite runs were not practical because several concurrent worktrees on this machine share the test-run lock. Exact-head hosted Cross-platform CI is the full-suite evidence.

Co-authored-by: lcxhh521 lcxhh521@users.noreply.github.com

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

This PR is intended to remain a draft pending maintainer decisions and exact-head hosted validation.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 03134ad7-f60c-4fb0-9040-7f4621b31cb3

📥 Commits

Reviewing files that changed from the base of the PR and between 20cd561 and 8dc12b8.

📒 Files selected for processing (51)

• docs-site/src/content/docs/fr/guides/claude-code.md
• docs-site/src/content/docs/fr/guides/codex-integration.md
• docs-site/src/content/docs/fr/guides/minimax.md
• docs-site/src/content/docs/fr/reference/configuration/providers.md
• docs-site/src/content/docs/guides/claude-code.md
• docs-site/src/content/docs/guides/codex-integration.md
• docs-site/src/content/docs/guides/minimax.md
• docs-site/src/content/docs/ja/guides/claude-code.md
• docs-site/src/content/docs/ja/guides/codex-integration.md
• docs-site/src/content/docs/ja/guides/minimax.md
• docs-site/src/content/docs/ja/reference/configuration/providers.md
• docs-site/src/content/docs/ko/guides/claude-code.md
• docs-site/src/content/docs/ko/guides/codex-integration.md
• docs-site/src/content/docs/ko/guides/minimax.md
• docs-site/src/content/docs/ko/reference/configuration/providers.md
• docs-site/src/content/docs/reference/configuration/providers.md
• docs-site/src/content/docs/ru/guides/claude-code.md
• docs-site/src/content/docs/ru/guides/codex-integration.md
• docs-site/src/content/docs/ru/guides/minimax.md
• docs-site/src/content/docs/ru/reference/configuration/providers.md
• docs-site/src/content/docs/tr/guides/claude-code.md
• docs-site/src/content/docs/tr/guides/codex-integration.md
• docs-site/src/content/docs/tr/guides/minimax.md
• docs-site/src/content/docs/tr/reference/configuration/providers.md
• docs-site/src/content/docs/zh-cn/guides/claude-code.md
• docs-site/src/content/docs/zh-cn/guides/codex-integration.md
• docs-site/src/content/docs/zh-cn/guides/minimax.md
• docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
• docs-site/src/content/docs/zh-tw/guides/claude-code.md
• docs-site/src/content/docs/zh-tw/guides/codex-integration.md
• docs-site/src/content/docs/zh-tw/guides/minimax.md
• docs-site/src/content/docs/zh-tw/reference/configuration/providers.md
• scripts/test-layout/layout.json
• src/clients/config-export/model-metadata.ts
• src/codex/catalog/effort.ts
• src/codex/catalog/model-hints.ts
• src/codex/catalog/parsing.ts
• src/codex/catalog/routed-gather.ts
• src/codex/catalog/vendor-context.ts
• src/config/schema/leaf-validators.ts
• src/providers/model-rename-fields.ts
• src/server/auth-cors.ts
• src/types/provider.ts
• structure/INDEX.md
• structure/catalog-vendor-context.md
• structure/catalog.md
• structure/manifest.json
• tests/codex-integration/vendor-context.test.ts
• tests/fixtures/test-layout-expected.json
• tests/responses/responses-compaction-http-isolation.test.ts
• tests/responses/responses-compaction-routing.test.ts

 _____________________________________________________________________
< You added a feature flag. Great-now we can ship bugs *selectively*. >
 ---------------------------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

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

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.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ Required local validation passed; commands, results, and any full-suite exception are documented.
• ⬜ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

Automatic draft conversion failed. Please convert this pull request to a draft manually until every box above is ticked.

[lidge-jun]

Maintainer bundle review (clients/config/tests/catalog): holding this PR; not merged.

Exact-head Cross-platform CI on 124fca57 fails Linux test 2/4 (job) with two existing #1073 contract tests in tests/codex-integration/codex-catalog.test.ts:

• an id-only model with no configured window keeps the conservative fallback (#1073) (line 6467): sub2api/gpt-5.6-luna now advertises context_window 1,050,000 instead of 128,000, because the vendor lookup fills the window before the 128k fallback.
• an id-only model with an enabled context cap uses that cap as the window (line 6493): the enabled 350k cap now clamps a 1.05M estimate, so the row reports contextCapped: true and carries contextWindowInference instead of using the cap as the window.

These are not flaky. They are the behavior change this PR proposes, colliding with the earlier #1073 decision that id-only custom rows stay at the conservative window. Resolving them means either updating those expectations as an explicit reversal of #1073 (note that codex-catalog.test.ts sits at its file-size cap, so changed cases need to move to a sibling file), or narrowing inference so sub2api-style relays keep 128k. That choice, together with the five decisions listed in the description, needs a maintainer call. The 14-file focused selection did not include codex-catalog.test.ts, which is why local runs were green.

The source review found nothing else blocking: the exact/normalized tiering, fail-closed conflicts, built-in name exclusion and provenance separation read correctly, and the PR merges cleanly with current dev alongside #7036/#7038/#7039.

[lcxhh521]

@lidge-jun The original problem was frequent compaction in my setup: a custom provider omitted context metadata, so the catalog used 128k even though the bundled vendor table had a larger window for the model. That metadata is an estimate, not verification of the relay's capacity.

I understand that #1073 deliberately keeps id-only custom providers conservative. Would you accept a per-provider opt-in for vendor context inference, disabled by default?

With it unset or disabled, the existing fallback and enabled-cap behavior would remain unchanged. When explicitly enabled for a custom provider, reported/configured windows would still take precedence, context caps would still clamp the result, and inferred windows would keep their source provenance separate from verified capacity. Built-in providers would remain excluded.

This would preserve the existing #1073 expectations while making the metadata fallback available to users who choose it. Is this direction acceptable, and are there any changes you want to the five decisions in the PR description before implementation?

[lidge-jun]

Maintainer integration into dev (MAINTAINERS.md dev-only exception), at exact head 8dc12b84f.

This resolves the earlier hold: the maintainer decision is to keep the #1073 conservative fallback as the default. Vendor context inference is now a per-provider opt-in (inferContextWindow: true, default off). Both #1073 contract tests in codex-catalog.test.ts pass with unchanged expectations. The five decisions listed in the description are otherwise accepted as written.

Exact-head hosted evidence: Cross-platform CI test 1/4 through 4/4, structure gate, docs site build, docker smoke, storage policy, api usage, npm-global and keyring all passed; Catalog async contracts and React Doctor passed. The src/server/auth-cors.ts change is one field-policy entry classifying the new boolean as editor, the same classification as contextWindow. I reviewed it and applied maintainer-sponsored. Author credit: @lcxhh521 (PR author; Co-authored-by trailer on the maintainer commit).