feat: allow static provider model catalogs

lidge-jun · 0disoft · lidge-jun · commit 38bca18016db · 2026-06-23T13:27:58.000+09:00
Absorb PR #16 into dev while preserving live model discovery by default and keeping static allowlists out of the live model cache. Co-authored-by: 0disoft <rodisoft1@gmail.com>
diff --git a/devlog/_plan/260623_pr16_pr22_integration/00_plan.md b/devlog/_plan/260623_pr16_pr22_integration/00_plan.md
@@ -0,0 +1,125 @@
+# 2026-06-23 PR #16/#22 Dev Integration Plan
+
+## Objective
+
+Absorb the remaining open PRs into `dev` without routing them through the GitHub PR merge button:
+
+- PR #16: static provider model catalogs via `liveModels: false`.
+- PR #22: Anthropic Messages tool-result history repair.
+
+The final state must preserve existing live `/models` discovery by default, keep static allowlists opt-in only, fix invalid Anthropic `tool_result` history shapes, push `dev`, and close both superseded PRs with attribution.
+
+## Current State
+
+- Repository: `/Users/jun/Developer/new/700_projects/opencodex`
+- Branch: `dev`
+- Latest release baseline: `v2.1.7` / `241e327 release: v2.1.7`
+- Open PRs:
+  - `#16 [codex] Allow static provider model catalogs` by `0disoft`, mergeable, CI green.
+  - `#22 fix anthropic tool result history` by `jaekwonhong`, draft, mergeable, no reported checks.
+
+## Planned Changes
+
+### MODIFY `src/types.ts`
+
+Add optional provider config:
+
+```ts
+liveModels?: boolean;
+```
+
+Behavior:
+
+- `undefined` and `true` keep the current live `/models` behavior.
+- `false` means `models` is an intentional static Codex catalog allowlist.
+
+### MODIFY `src/codex-catalog.ts`
+
+Change `fetchProviderModels` order:
+
+1. Skip forward providers and unresolved OAuth providers as today.
+2. Build configured model hints first from `prov.models`.
+3. If `prov.liveModels === false`, return configured models immediately.
+4. Do not write static allowlists into the live model cache.
+5. Otherwise use fresh cache, live `/models`, stale cache, and configured fallback as today.
+
+This preserves the existing dashboard `/api/models`, Codex `/v1/models`, and catalog sync behavior because all three already route through `gatherRoutedModels(config)`.
+
+### MODIFY `tests/codex-catalog.test.ts`
+
+Add/absorb regression tests:
+
+- `liveModels:false` never calls `fetch`.
+- A fresh live cache cannot override a static allowlist.
+- Static allowlists do not poison the live cache after toggling back to live models.
+- Config catalog hints still apply to static configured models, specifically `modelContextWindows`
+  and `modelInputModalities` on a `liveModels:false` provider.
+
+### MODIFY docs
+
+Update configuration reference pages:
+
+- `/Users/jun/Developer/new/700_projects/opencodex/docs-site/src/content/docs/reference/configuration.md`
+- `/Users/jun/Developer/new/700_projects/opencodex/docs-site/src/content/docs/ko/reference/configuration.md`
+- `/Users/jun/Developer/new/700_projects/opencodex/docs-site/src/content/docs/zh-cn/reference/configuration.md`
+
+Document:
+
+- `models` remains seed/fallback by default.
+- `liveModels:false` makes `models` an exact allowlist.
+- Empty `models` with `liveModels:false` exposes no routed models.
+
+### MODIFY `src/adapters/anthropic.ts`
+
+Repair Anthropic tool-result history conversion:
+
+- Adjacent `toolResult` messages immediately following assistant `tool_use` blocks must be folded into one user message containing Anthropic `tool_result` blocks.
+- Missing tool results should be represented by synthetic `is_error: true` tool_result blocks so the request stays valid.
+- Duplicate or orphan tool results should be preserved as text instead of invalid standalone Anthropic `tool_result` blocks.
+- Image/tool content blocks should continue using existing `toAnthropicContentPart`.
+
+### MODIFY `tests/adapter-usage.test.ts`
+
+Add/absorb regression tests:
+
+- Multiple adjacent tool results are folded into one user message.
+- Missing tool result is synthesized with `is_error: true`.
+- Orphan tool result is preserved as text.
+- Duplicate tool results after one matching assistant `tool_use` are preserved as text, not a
+  second invalid Anthropic `tool_result` block.
+- Non-string tool-result content, including image content, still maps through Anthropic content
+  blocks.
+- Existing OpenAI Chat history repair tests remain green.
+
+## Integration Strategy
+
+1. Enter PABCD `A` and dispatch a read-only plan audit.
+2. Merge PR #16 into local `dev` using git, preserving contributor history where practical.
+3. Merge PR #22 into local `dev`, despite draft status, because the user explicitly authorized absorbing and closing it.
+4. Resolve conflicts manually if needed; add small follow-up patch if PR code regresses existing metadata caps or cache semantics.
+5. Run focused verification:
+   - `bun test tests/codex-catalog.test.ts`
+   - `bun test tests/adapter-usage.test.ts tests/umans-provider.test.ts`
+   - `bun run typecheck`
+6. Run full verification:
+   - `bun test tests`
+   - `cd docs-site && bun run build`
+   - `git diff --check`
+7. Commit or preserve merge commits atomically.
+8. Push `dev` to `origin/dev`.
+9. Comment on PR #16 and PR #22 with absorbed commit/evidence and close them.
+10. Record final goal evidence and pause the goal with an independent stop audit.
+
+## Risks
+
+- PR #16 could accidentally make static allowlists the default. Mitigation: tests assert the default live path still fetches.
+- PR #16 could pollute the live model cache with static allowlists. Mitigation: cache toggle test.
+- PR #22 could alter valid Anthropic history order. Mitigation: focused adapter tests plus existing usage tests.
+- PR #22 is draft. Mitigation: do not GitHub-merge the draft PR; absorb into `dev` with explicit user authorization and close as superseded.
+
+## Completion Evidence Required
+
+- Documentation: this devlog plan plus final devlog notes.
+- Implementation: changed source/tests/docs paths listed above.
+- Verification: focused tests, typecheck, full tests, docs build, diff check.
+- GitHub: `origin/dev` updated, PR #16 and #22 commented and closed.
diff --git a/docs-site/src/content/docs/ko/reference/configuration.md b/docs-site/src/content/docs/ko/reference/configuration.md
@@ -33,7 +33,8 @@ opencodex는 `~/.opencodex/config.json`으로 설정됩니다. 이 파일은 `oc
 | `baseUrl` | `string` | 업스트림 API 기본 URL. |
 | `apiKey?` | `string` | API 키, 또는 요청 시점에 해석되는 `${ENV_VAR}` / `$ENV_VAR` 참조. |
 | `defaultModel?` | `string` | 명시적인 모델 없이 이 프로바이더가 선택되었을 때 사용하는 모델. |
-| `models?` | `string[]` | 시드/폴백 모델 목록 (실시간 `/models`에 접근 가능하면 그쪽이 우선됨). |
+| `models?` | `string[]` | 시드/폴백 모델 목록. `liveModels`가 `false`이면 Codex 카탈로그에 노출할 정확한 allowlist가 됩니다. |
+| `liveModels?` | `boolean` | 시작/동기화 시 프로바이더의 실시간 `/models` 카탈로그를 가져옵니다(기본 `true`). `false`로 두면 설정된 `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. |
@@ -43,6 +44,28 @@ opencodex는 `~/.opencodex/config.json`으로 설정됩니다. 이 파일은 `oc
 | `noVisionModels?` | `string[]` | 텍스트 전용 모델 — [비전 사이드카](/opencodex/ko/guides/sidecars/)가 이들을 위해 이미지를 설명함. 매칭 시 Ollama의 `:size` 태그를 허용함. |
 | `escapeBuiltinToolNames?` | `boolean` | Umans 같은 Anthropic 호환 게이트웨이가 wire에서 도구명 escape를 요구할 때 사용합니다. opencodex는 Codex에 tool call을 돌려주기 전에 prefix를 제거합니다. |
 
+## 정적 모델 allowlist
+
+일부 프로바이더는 실시간 모델 카탈로그가 매우 크거나 느릴 수 있습니다. Codex에 `models`에
+고정한 모델만 노출하려면 `liveModels`를 `false`로 설정하세요.
+
+`liveModels`가 `false`인데 `models`가 비어 있거나 생략되면, opencodex는 해당 프로바이더의
+routed model을 노출하지 않습니다.
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "adapter": "openai-chat",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "apiKey": "${OPENROUTER_API_KEY}",
+      "liveModels": false,
+      "models": ["deepseek/deepseek-v4-flash", "qwen/qwen3-coder-plus"]
+    }
+  }
+}
+```
+
 ## 사이드카
 
 ### `webSearchSidecar` (`OcxWebSearchSidecarConfig`)
diff --git a/docs-site/src/content/docs/reference/configuration.md b/docs-site/src/content/docs/reference/configuration.md
@@ -33,7 +33,8 @@ also force the same native-provider recovery with `ocx recover-history --legacy-
 | `baseUrl` | `string` | Upstream API base URL. |
 | `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). |
+| `models?` | `string[]` | Seed/fallback model list. Also becomes the exact catalog allowlist when `liveModels` is `false`. |
+| `liveModels?` | `boolean` | Fetch the provider's live `/models` catalog on start/sync (default `true`). Set `false` to use only configured `models`. |
 | `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"]`. |
@@ -43,6 +44,28 @@ also force the same native-provider recovery with `ocx recover-history --legacy-
 | `noVisionModels?` | `string[]` | Text-only models — the [vision sidecar](/opencodex/guides/sidecars/) describes images for them. Matching tolerates an Ollama `:size` tag. |
 | `escapeBuiltinToolNames?` | `boolean` | Anthropic-compatible gateways such as Umans can require tool-name escaping on the wire; opencodex strips the prefix before returning tool calls to Codex. |
 
+## Static model allowlists
+
+Some providers expose very large or slow live model catalogs. Set `liveModels` to `false` when you
+want Codex to see only the models pinned in `models`:
+
+When `liveModels` is `false` and `models` is empty or omitted, opencodex exposes no routed models
+for that provider.
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "adapter": "openai-chat",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "apiKey": "${OPENROUTER_API_KEY}",
+      "liveModels": false,
+      "models": ["deepseek/deepseek-v4-flash", "qwen/qwen3-coder-plus"]
+    }
+  }
+}
+```
+
 ## Sidecars
 
 ### `webSearchSidecar` (`OcxWebSearchSidecarConfig`)
diff --git a/docs-site/src/content/docs/zh-cn/reference/configuration.md b/docs-site/src/content/docs/zh-cn/reference/configuration.md
@@ -31,7 +31,8 @@ opencodex 通过 `~/.opencodex/config.json` 进行配置。它由 `ocx init` 和
 | `baseUrl` | `string` | 上游 API 的基础 URL。 |
 | `apiKey?` | `string` | API key,或在请求时解析的 `${ENV_VAR}` / `$ENV_VAR` 引用。 |
 | `defaultModel?` | `string` | 当选中该 provider 但未指定明确模型时使用的模型。 |
-| `models?` | `string[]` | 种子/回退模型列表(当实时 `/models` 可达时优先使用它)。 |
+| `models?` | `string[]` | 种子/回退模型列表。当 `liveModels` 为 `false` 时,它也是 Codex 目录中精确暴露的 allowlist。 |
+| `liveModels?` | `boolean` | 启动/同步时获取 provider 的实时 `/models` 目录(默认 `true`)。设为 `false` 时只使用配置的 `models`。 |
 | `contextWindow?` | `number` | 路由 catalog 条目的 provider 级上下文窗口上限。实时 metadata 小于该值时会保留实时值。 |
 | `modelContextWindows?` | `Record<string,number>` | 模型级上下文窗口上限。匹配模型时优先于 `contextWindow`,且不会抬高更小的实时 metadata。 |
 | `modelInputModalities?` | `Record<string,string[]>` | 模型级 catalog 输入提示,例如 `["text"]` 或 `["text", "image"]`。 |
@@ -41,6 +42,27 @@ opencodex 通过 `~/.opencodex/config.json` 进行配置。它由 `ocx init` 和
 | `noVisionModels?` | `string[]` | 纯文本模型 —— [视觉 sidecar](/opencodex/zh-cn/guides/sidecars/) 会为它们描述图像。匹配时可容忍 Ollama 的 `:size` 标签。 |
 | `escapeBuiltinToolNames?` | `boolean` | Umans 等 Anthropic 兼容网关可能要求在 wire 上转义工具名；opencodex 会在把 tool call 返回给 Codex 前移除前缀。 |
 
+## 静态模型 allowlist
+
+有些 provider 的实时模型目录非常大或响应较慢。如果只希望 Codex 看到 `models` 中固定的模型,
+可以将 `liveModels` 设为 `false`。
+
+当 `liveModels` 为 `false` 且 `models` 为空或省略时,opencodex 不会为该 provider 暴露 routed model。
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "adapter": "openai-chat",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "apiKey": "${OPENROUTER_API_KEY}",
+      "liveModels": false,
+      "models": ["deepseek/deepseek-v4-flash", "qwen/qwen3-coder-plus"]
+    }
+  }
+}
+```
+
 ## Sidecars
 
 ### `webSearchSidecar`(`OcxWebSearchSidecarConfig`)
diff --git a/src/codex-catalog.ts b/src/codex-catalog.ts
@@ -419,13 +419,16 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
   if (prov.authMode === "forward") return []; // ChatGPT backend has no /models
   const apiKey = await resolveModelsAuthToken(name, prov);
   if (prov.authMode === "oauth" && !apiKey) return []; // not logged in → skip
-  const fresh = getFreshCached(name, ttlMs);
-  if (fresh) return applyConfigHintsToCachedModels(name, prov, fresh); // dedups Codex's frequent /v1/models polling within the TTL
   const configured: CatalogModel[] = (prov.models ?? []).map(id => ({
     id,
     provider: name,
     ...catalogHintsFromProviderConfig(name, prov, id),
   }));
+  if (prov.liveModels === false) {
+    return configured;
+  }
+  const fresh = getFreshCached(name, ttlMs);
+  if (fresh) return applyConfigHintsToCachedModels(name, prov, fresh); // dedups Codex's frequent /v1/models polling within the TTL
   const { url, headers } = buildModelsRequest(prov, apiKey);
   try {
     const res = await fetch(url, { headers, signal: AbortSignal.timeout(8000) });
diff --git a/src/types.ts b/src/types.ts
@@ -230,6 +230,12 @@ export interface OcxProviderConfig {
   apiKey?: string;
   defaultModel?: string;
   models?: string[];
+  /**
+   * Fetch the provider's live `/models` endpoint. Defaults to true.
+   * Set false when `models` is an intentional allowlist or a provider's live catalog is too large
+   * or too flaky for startup/catalog sync.
+   */
+  liveModels?: boolean;
   /** Provider-wide Codex-visible context-window cap for routed catalog entries. */
   contextWindow?: number;
   /** Model-specific Codex-visible context-window caps. Values cap live metadata, never raise it. */
diff --git a/tests/codex-catalog.test.ts b/tests/codex-catalog.test.ts
