feat: preserve provider catalog metadata caps

Preserves context-window cap behavior from PR #12 and Umans catalog metadata propagation from PR #21 while keeping the verified Anthropic Messages runtime path.

Co-authored-by: 0disoft <rodisoft1@gmail.com>

Co-authored-by: Ingwannu <ingwannu@users.noreply.github.com>

Author: lidge-jun

README.md

@@ -217,6 +217,12 @@ Config lives at `~/.opencodex/config.json`. Here's a typical multi-provider setu
 }
 ```
 
+Provider entries can also annotate routed catalog metadata. Use `contextWindow` for a provider-wide
+Codex-visible context cap, `modelContextWindows` for model-specific caps, and
+`modelInputModalities` for model-specific catalog input hints such as `["text"]` or
+`["text", "image"]`. Context values cap live `/models` metadata; they never raise a smaller live
+context window. See the configuration reference for the full field list.
+
 Local models work too. Point opencodex at any OpenAI-compatible server running on your machine:
 
 ```json

devlog/250_provider-catalog-metadata/00_plan.md

@@ -0,0 +1,199 @@
+# Provider Catalog Metadata Plan
+
+## Goal
+
+Update `dev` with the remaining safe provider-catalog metadata work from PR #12 and PR #21 without
+regressing the verified Umans Anthropic Messages provider.
+
+## Source PRs
+
+- PR #12 by 0disoft / ZeroDi: configurable provider and model context-window caps.
+- PR #21 by Ingwannu / 이완우: native Umans provider metadata and registry-to-catalog propagation.
+
+## Decision
+
+Do not cherry-pick PR #21 wholesale. Current `dev` already has a verified Umans provider that uses:
+
+- `adapter: "anthropic"`
+- `baseUrl: "https://api.code.umans.ai"`
+- `POST /v1/messages`
+- `x-api-key`
+- `escapeBuiltinToolNames: true`
+
+PR #21 changes Umans to OpenAI Chat Completions shape. That would reopen the stream/tool-call class
+of issues documented in `devlog/230_umans-wire-protocol/`.
+
+Preserve these ideas instead:
+
+- From PR #12:
+  - `contextWindow?: number`
+  - `modelContextWindows?: Record<string, number>`
+  - configured context windows are caps, not blind overrides:
+    - cap live `/models` metadata with `Math.min(live, configured)`
+    - cap fresh/stale cached live metadata the same way
+    - use configured values for static configured-model fallback
+- From PR #21:
+  - `modelInputModalities?: Record<string, string[]>`
+  - registry metadata should flow through provider config seed, key-login maps, saved login payloads,
+    provider enrichment, and Codex catalog entries.
+
+## Implementation Plan
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/src/types.ts`
+
+Add optional provider catalog metadata fields to `OcxProviderConfig`:
+
+- `contextWindow?: number`
+- `modelContextWindows?: Record<string, number>`
+- `modelInputModalities?: Record<string, string[]>`
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/src/providers/registry.ts`
+
+Extend `ProviderRegistryEntry` and `ProviderConfigSeed` with the same metadata fields.
+
+Add Umans metadata to the existing Anthropic Messages entry only:
+
+- context windows:
+  - `umans-coder`: `262_144`
+  - `umans-kimi-k2.7`: `262_144`
+  - `umans-kimi-k2.6`: `262_144`
+  - `umans-flash`: `262_144`
+  - `umans-glm-5.2`: `405_504`
+  - `umans-glm-5.1`: `202_752`
+  - `umans-qwen3.6-35b-a3b`: `262_144`
+- input modalities:
+  - `umans-coder`: `["text", "image"]`
+  - `umans-kimi-k2.7`: `["text", "image"]`
+  - `umans-kimi-k2.6`: `["text", "image"]`
+  - `umans-flash`: `["text", "image"]`
+  - `umans-glm-5.2`: `["text"]`
+  - `umans-glm-5.1`: `["text"]`
+  - `umans-qwen3.6-35b-a3b`: `["text", "image"]`
+
+The GLM rows stay text-only to match the current `noVisionModels` behavior and OMP's treatment of
+GLM vision as a handoff, not native image input.
+
+Keep these fields unchanged:
+
+- `adapter: "anthropic"`
+- `baseUrl: "https://api.code.umans.ai"`
+- `authKind: "key"`
+- `defaultModel: "umans-coder"`
+- `escapeBuiltinToolNames: true`
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/src/providers/derive.ts`
+
+Copy the new metadata fields through:
+
+- `providerConfigSeed()`
+- `deriveKeyLoginMap()`
+- `DerivedKeyLoginProvider`
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/src/oauth/key-providers.ts`
+
+Copy the new metadata fields through:
+
+- `KeyLoginProvider`
+- `enrichProviderFromCatalog()`
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/src/oauth/login-cli.ts`
+
+Copy the new metadata fields into the saved key-login provider config.
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/src/oauth/index.ts`
+
+Include the new metadata fields in OAuth provider reconciliation so future OAuth registry metadata
+stays synced.
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/src/codex-catalog.ts`
+
+Extend `catalogHintsFromProviderConfig()` so provider config metadata reaches `CatalogModel`:
+
+- context cap selection must use existing per-model lookup semantics:
+  - use `modelRecordValue(prov.modelContextWindows, id) ?? prov.contextWindow`
+  - model-specific cap wins over provider-wide cap
+  - if no live/cached context exists, return configured cap for configured/static models
+- input modalities:
+  - use `modelRecordValue(prov.modelInputModalities, id)` when present
+
+`catalogHintsFromProviderConfig()` alone cannot cap live/cached values because it does not know the
+live value. Add a merge helper for live/cached models:
+
+```ts
+function applyProviderConfigHints(name: string, prov: OcxProviderConfig, model: CatalogModel): CatalogModel
+```
+
+The helper should:
+
+- compute the configured cap from `modelContextWindows` / `contextWindow`
+- set `contextWindow` to `Math.min(model.contextWindow, configuredCap)` when both values exist
+- set `contextWindow` to the configured cap when the model lacks live/cached context
+- copy `inputModalities` when `modelInputModalities` has a match
+- preserve current reasoning-effort behavior via `configuredReasoningEfforts()`
+
+Use that helper in all three catalog paths:
+
+- `applyConfigHintsToCachedModels()`
+- configured/static fallback models
+- live `/models` rows after `catalogHintsFromModelsApiItem()`
+
+This preserves PR #12's cap semantics: config can lower oversized live metadata but must not raise a
+smaller live context window.
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/tests/provider-registry-parity.test.ts`
+
+Assert registry-derived key-login and provider presets preserve Umans context/input metadata.
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/tests/umans-provider.test.ts`
+
+Strengthen Umans tests so the saved/enriched provider retains catalog metadata while preserving
+Anthropic Messages runtime behavior.
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/tests/codex-catalog.test.ts`
+
+Add catalog tests for:
+
+- static configured models receiving context/input metadata
+- live `/models` metadata being capped by provider-wide and model-specific config
+- configured caps not raising smaller live metadata
+- cached metadata being capped consistently
+
+### MODIFY `/Users/jun/Developer/new/700_projects/opencodex/README.md`
+
+Add a short configuration example or field summary for `contextWindow`, `modelContextWindows`, and
+`modelInputModalities`, then point detailed field definitions to the docs-site configuration
+reference.
+
+### MODIFY docs-site config reference pages
+
+Update English, Korean, and Chinese docs-site config/reference pages if the fields are documented
+there.
+
+## Verification Plan
+
+Run:
+
+- `bun test tests/codex-catalog.test.ts tests/provider-registry-parity.test.ts tests/umans-provider.test.ts tests/reasoning-effort.test.ts`
+- `bun run typecheck`
+- `bun test tests`
+- `cd docs-site && bun run build`
+- `git diff --check`
+
+## Contributor Credit
+
+Commit with trailers:
+
+```text
+Co-authored-by: 0disoft <rodisoft1@gmail.com>
+Co-authored-by: Ingwannu <ingwannu@users.noreply.github.com>
+```
+
+## GitHub Closeout
+
+After the dev commit is verified and pushed:
+
+- Comment on PR #12 that context-window cap behavior has landed on `dev` with credit, then close it
+  as superseded.
+- Comment on PR #21 that the metadata plumbing has landed on `dev` with credit, but the OpenAI Chat
+  Umans runtime shape was intentionally not merged because `dev` keeps the verified Anthropic
+  Messages provider, then close the draft PR as superseded.

docs-site/src/content/docs/ko/reference/configuration.md

@@ -34,6 +34,9 @@ opencodex는 `~/.opencodex/config.json`으로 설정됩니다. 이 파일은 `oc
 | `apiKey?` | `string` | API 키, 또는 요청 시점에 해석되는 `${ENV_VAR}` / `$ENV_VAR` 참조. |
 | `defaultModel?` | `string` | 명시적인 모델 없이 이 프로바이더가 선택되었을 때 사용하는 모델. |
 | `models?` | `string[]` | 시드/폴백 모델 목록 (실시간 `/models`에 접근 가능하면 그쪽이 우선됨). |
+| `contextWindow?` | `number` | routed catalog entry에 표시할 프로바이더 전체 context-window cap. 실시간 metadata가 이보다 작으면 그대로 둡니다. |
+| `modelContextWindows?` | `Record<string,number>` | 모델별 context-window cap. 매칭되는 모델에서는 `contextWindow`보다 우선하며, 더 작은 실시간 metadata를 올리지 않습니다. |
+| `modelInputModalities?` | `Record<string,string[]>` | `["text"]` 또는 `["text", "image"]` 같은 모델별 catalog input hint. |
 | `headers?` | `Record<string,string>` | 업스트림으로 전송되는 추가 HTTP 헤더. |
 | `authMode?` | `"key" \| "forward" \| "oauth"` | 인증 방식 (기본 `key`). [프로바이더](/opencodex/ko/guides/providers/#auth-modes) 참조. |
 | `noReasoningModels?` | `string[]` | reasoning/thinking 파라미터를 거부하는 모델 — 어댑터가 이들에 대해 `reasoning_effort`를 제거함. |

docs-site/src/content/docs/reference/configuration.md

@@ -34,6 +34,9 @@ also force the same native-provider recovery with `ocx recover-history --legacy-
 | `apiKey?` | `string` | API key, or an `${ENV_VAR}` / `$ENV_VAR` reference resolved at request time. |
 | `defaultModel?` | `string` | Model used when this provider is selected without an explicit model. |
 | `models?` | `string[]` | Seed/fallback model list (live `/models` is preferred when reachable). |
+| `contextWindow?` | `number` | Provider-wide Codex-visible context-window cap for routed catalog entries. Live metadata below this value is kept. |
+| `modelContextWindows?` | `Record<string,number>` | Model-specific context-window caps. These override `contextWindow` for matching model ids and never raise smaller live metadata. |
+| `modelInputModalities?` | `Record<string,string[]>` | Model-specific catalog input hints such as `["text"]` or `["text", "image"]`. |
 | `headers?` | `Record<string,string>` | Extra HTTP headers sent upstream. |
 | `authMode?` | `"key" \| "forward" \| "oauth"` | How to authenticate (default `key`). See [Providers](/opencodex/guides/providers/#auth-modes). |
 | `noReasoningModels?` | `string[]` | Models that reject a reasoning/thinking param — the adapter drops `reasoning_effort` for them. |

docs-site/src/content/docs/zh-cn/reference/configuration.md

@@ -32,6 +32,9 @@ opencodex 通过 `~/.opencodex/config.json` 进行配置。它由 `ocx init` 和
 | `apiKey?` | `string` | API key,或在请求时解析的 `${ENV_VAR}` / `$ENV_VAR` 引用。 |
 | `defaultModel?` | `string` | 当选中该 provider 但未指定明确模型时使用的模型。 |
 | `models?` | `string[]` | 种子/回退模型列表(当实时 `/models` 可达时优先使用它)。 |
+| `contextWindow?` | `number` | 路由 catalog 条目的 provider 级上下文窗口上限。实时 metadata 小于该值时会保留实时值。 |
+| `modelContextWindows?` | `Record<string,number>` | 模型级上下文窗口上限。匹配模型时优先于 `contextWindow`,且不会抬高更小的实时 metadata。 |
+| `modelInputModalities?` | `Record<string,string[]>` | 模型级 catalog 输入提示,例如 `["text"]` 或 `["text", "image"]`。 |
 | `headers?` | `Record<string,string>` | 发送到上游的额外 HTTP 头。 |
 | `authMode?` | `"key" \| "forward" \| "oauth"` | 认证方式(默认 `key`)。见 [Providers](/opencodex/zh-cn/guides/providers/#auth-modes)。 |
 | `noReasoningModels?` | `string[]` | 会拒绝 reasoning/thinking 参数的模型 —— adapter 会为它们丢弃 `reasoning_effort`。 |

src/codex-catalog.ts

@@ -6,7 +6,7 @@ import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, readR
 import { DEFAULT_MODEL_CACHE_TTL_MS, getFreshCached, getStaleCached, setCached } from "./model-cache";
 import { buildModelsRequest, resolveModelsAuthToken } from "./oauth/index";
 import type { OcxConfig, OcxProviderConfig } from "./types";
-import { CODEX_REASONING_LEVELS, configuredReasoningEfforts, sanitizeCodexReasoningEfforts } from "./reasoning-effort";
+import { CODEX_REASONING_LEVELS, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "./reasoning-effort";
 import { getJawcodeModelMetadata, getJawcodeModelMetadataCaseInsensitive, listJawcodeModelMetadata, resolveJawcodeProvider } from "./generated/jawcode-model-metadata";
 import { shouldCaseFoldMetadataModelId } from "./providers/derive";
 
@@ -341,19 +341,43 @@ type ProviderModelsApiItem = {
   };
 };
 
-function catalogHintsFromProviderConfig(name: string, prov: OcxProviderConfig, id: string): Partial<CatalogModel> {
+function configuredContextWindow(prov: OcxProviderConfig, id: string): number | undefined {
+  const configured = modelRecordValue(prov.modelContextWindows, id) ?? prov.contextWindow;
+  return typeof configured === "number" && configured > 0 ? configured : undefined;
+}
+
+function configuredInputModalities(prov: OcxProviderConfig, id: string): string[] | undefined {
+  const modalities = modelRecordValue(prov.modelInputModalities, id);
+  return Array.isArray(modalities) && modalities.length > 0 ? [...modalities] : undefined;
+}
+
+function applyProviderConfigHints(name: string, prov: OcxProviderConfig, model: CatalogModel): CatalogModel {
   void name;
-  const reasoningEfforts = configuredReasoningEfforts(prov, id);
+  const contextCap = configuredContextWindow(prov, model.id);
+  const inputModalities = configuredInputModalities(prov, model.id);
+  const reasoningEfforts = configuredReasoningEfforts(prov, model.id);
   return {
+    ...model,
+    ...(contextCap !== undefined
+      ? {
+        contextWindow: typeof model.contextWindow === "number" && model.contextWindow > 0
+          ? Math.min(model.contextWindow, contextCap)
+          : contextCap,
+      }
+      : {}),
+    ...(inputModalities ? { inputModalities } : {}),
     ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
   };
 }
 
+function catalogHintsFromProviderConfig(name: string, prov: OcxProviderConfig, id: string): Partial<CatalogModel> {
+  const hinted = applyProviderConfigHints(name, prov, { id, provider: name });
+  const { provider: _provider, id: _id, ...hints } = hinted;
+  return hints;
+}
+
 function applyConfigHintsToCachedModels(name: string, prov: OcxProviderConfig, models: CatalogModel[]): CatalogModel[] {
-  return models.map(model => ({
-    ...catalogHintsFromProviderConfig(name, prov, model.id),
-    ...model,
-  }));
+  return models.map(model => applyProviderConfigHints(name, prov, model));
 }
 
 function isGlm52ModelId(id: string): boolean {
@@ -410,11 +434,10 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
       return stale ? applyConfigHintsToCachedModels(name, prov, stale) : configured;
     }
     const json = await res.json() as { data?: ProviderModelsApiItem[] };
-    const live = (json.data ?? []).map(m => ({
+    const live = (json.data ?? []).map(m => applyProviderConfigHints(name, prov, {
       id: m.id,
       provider: name,
       owned_by: m.owned_by,
-      ...catalogHintsFromProviderConfig(name, prov, m.id),
       ...catalogHintsFromModelsApiItem(name, m),
     }));
     const liveIds = new Set(live.map(m => m.id));

src/oauth/index.ts

@@ -129,6 +129,9 @@ function cloneProviderField(value: unknown): unknown {
 
 const OAUTH_RECONCILE_FIELDS: (keyof OcxProviderConfig)[] = [
   "models",
+  "contextWindow",
+  "modelContextWindows",
+  "modelInputModalities",
   "noReasoningModels",
   "noVisionModels",
   "reasoningEfforts",

src/oauth/key-providers.ts

@@ -15,6 +15,9 @@ export interface KeyLoginProvider {
   dashboardUrl: string;
   models?: string[];
   defaultModel?: string;
+  contextWindow?: number;
+  modelContextWindows?: Record<string, number>;
+  modelInputModalities?: Record<string, string[]>;
   /**
    * Model ids that do NOT accept image input (the vision sidecar describes images for them) / do NOT
    * accept a reasoning param. Copied into the created provider config by `enrichProviderFromCatalog`,
@@ -47,6 +50,9 @@ export function enrichProviderFromCatalog(name: string, prov: OcxProviderConfig)
   if (!e) return;
   if (!prov.models && e.models) prov.models = [...e.models];
   if (!prov.defaultModel && e.defaultModel) prov.defaultModel = e.defaultModel;
+  if (prov.contextWindow === undefined && e.contextWindow !== undefined) prov.contextWindow = e.contextWindow;
+  if (!prov.modelContextWindows && e.modelContextWindows) prov.modelContextWindows = { ...e.modelContextWindows };
+  if (!prov.modelInputModalities && e.modelInputModalities) prov.modelInputModalities = cloneRecordOfArrays(e.modelInputModalities);
   if (!prov.reasoningEfforts && e.reasoningEfforts) prov.reasoningEfforts = [...e.reasoningEfforts];
   if (!prov.modelReasoningEfforts && e.modelReasoningEfforts) prov.modelReasoningEfforts = cloneRecordOfArrays(e.modelReasoningEfforts);
   if (!prov.reasoningEffortMap && e.reasoningEffortMap) prov.reasoningEffortMap = { ...e.reasoningEffortMap };

src/oauth/login-cli.ts

@@ -59,6 +59,9 @@ export function providerConfigFromKeyLoginProvider(def: KeyLoginProvider, key: s
     apiKey: key,
     ...(def.defaultModel ? { defaultModel: def.defaultModel } : {}),
     ...(def.models ? { models: [...def.models] } : {}),
+    ...(def.contextWindow !== undefined ? { contextWindow: def.contextWindow } : {}),
+    ...(def.modelContextWindows ? { modelContextWindows: { ...def.modelContextWindows } } : {}),
+    ...(def.modelInputModalities ? { modelInputModalities: cloneRecordOfArrays(def.modelInputModalities) } : {}),
     ...(def.reasoningEfforts ? { reasoningEfforts: [...def.reasoningEfforts] } : {}),
     ...(def.modelReasoningEfforts ? { modelReasoningEfforts: cloneRecordOfArrays(def.modelReasoningEfforts) } : {}),
     ...(def.reasoningEffortMap ? { reasoningEffortMap: { ...def.reasoningEffortMap } } : {}),

src/providers/derive.ts

@@ -8,6 +8,9 @@ export interface DerivedKeyLoginProvider {
   dashboardUrl: string;
   models?: string[];
   defaultModel?: string;
+  contextWindow?: number;
+  modelContextWindows?: Record<string, number>;
+  modelInputModalities?: Record<string, string[]>;
   reasoningEfforts?: string[];
   modelReasoningEfforts?: Record<string, string[]>;
   reasoningEffortMap?: Record<string, string>;
@@ -63,6 +66,9 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     authMode: entry.authKind === "local" ? undefined : entry.authKind,
     ...(entry.defaultModel ? { defaultModel: entry.defaultModel } : {}),
     ...(entry.models ? { models: [...entry.models] } : {}),
+    ...(entry.contextWindow !== undefined ? { contextWindow: entry.contextWindow } : {}),
+    ...(entry.modelContextWindows ? { modelContextWindows: { ...entry.modelContextWindows } } : {}),
+    ...(entry.modelInputModalities ? { modelInputModalities: cloneRecordOfArrays(entry.modelInputModalities) } : {}),
     ...(entry.reasoningEfforts ? { reasoningEfforts: [...entry.reasoningEfforts] } : {}),
     ...(entry.modelReasoningEfforts ? { modelReasoningEfforts: cloneRecordOfArrays(entry.modelReasoningEfforts) } : {}),
     ...(entry.reasoningEffortMap ? { reasoningEffortMap: { ...entry.reasoningEffortMap } } : {}),
@@ -90,6 +96,9 @@ export function deriveKeyLoginMap(): Record<string, DerivedKeyLoginProvider> {
       dashboardUrl: entry.dashboardUrl,
       ...(entry.models ? { models: [...entry.models] } : {}),
       ...(entry.defaultModel ? { defaultModel: entry.defaultModel } : {}),
+      ...(entry.contextWindow !== undefined ? { contextWindow: entry.contextWindow } : {}),
+      ...(entry.modelContextWindows ? { modelContextWindows: { ...entry.modelContextWindows } } : {}),
+      ...(entry.modelInputModalities ? { modelInputModalities: cloneRecordOfArrays(entry.modelInputModalities) } : {}),
       ...(entry.reasoningEfforts ? { reasoningEfforts: [...entry.reasoningEfforts] } : {}),
       ...(entry.modelReasoningEfforts ? { modelReasoningEfforts: cloneRecordOfArrays(entry.modelReasoningEfforts) } : {}),
       ...(entry.reasoningEffortMap ? { reasoningEffortMap: { ...entry.reasoningEffortMap } } : {}),