feat(catalog): durable display names for discovered models (#2201, carry of #2715)

[lidge-jun]

Summary

• Maintainer carry of feat: add durable display names for discovered models #2715 by @zigzag-007 (20 commits merged onto current dev, authorship preserved), the core slice of [Feature] configurable human-readable display names for discovered provider models #2201 that the reviewer asked for before any dashboard work: a validated per-provider modelDisplayNames map (exact upstream model id → label) with a fixed precedence chain — operator override → discovery metadata → routed slug fallback — carried through the management catalog, /api/providers, PUT /api/providers/:name/model-display-names, and the OpenCode export.
• Labels never become identity: routed slug, native id, wire model, pricing keys, disabled/selected/retain matches, aliases, combo targets, and row dedupe are unchanged (independent review at the merge head found no violation; configuredModelDisplayName and effectiveManagementDisplayName key strictly by native id). Validation (plain object, prototype guards, 2,000-entry cap, non-blank trimmed ≤128 chars, no / or control characters) applies at config load, POST, and PUT; null resets one id deterministically.
• Why a carry: the contributor branch was refreshed onto dev several times and an earlier head passed all 23 checks, but each refresh needed fork-workflow approval and never got one. Two conflicts with the recently landed retainModels feature (feat(catalog): per-provider retainModels opt-in (#1690, carries #2860) #3206) were resolved here (POST carry-over block; providers.md row), keeping both.
• Also fixes a privacy-scan regression from feat(providers): opt-in OS keychain storage for provider API keys (#1221) #3210: two key-store test fixtures looked like real API keys.
• GUI editor feat: add discovered model display name editor #2716 stays open as the separately reviewed follow-up.

Closes #2201

Verification

• bun x tsc --noEmit clean; bun run privacy:scan passed.
• Focused: bun test on model-display-names-management-api, provider-config-validation, config-load-degrade, config-user-edits, opencode-cli, codex-convergence-contract, management-client-config-route, codex-catalog, management-provider-validation, catalog-retain-models, core-lab-boundary, provider-key-store → 552 pass / 0 fail.
• Full suite runs in CI on this PR.

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.

Summary by CodeRabbit

• New Features

  • Added durable, provider-specific display names for discovered models.
  • Display names can be set, updated, or reset through the management API.
  • Custom labels persist across discovery refreshes and provider configuration changes.
  • Added validation for safe, trimmed labels and supported model identifiers.

• Documentation

  • Updated provider configuration references and architecture documentation across supported languages.
  • Documented display-name precedence and API usage.

• Bug Fixes

  • Improved handling of invalid configuration entries without discarding valid provider settings.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-01T20:16:30.266250Z	512d874	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 13245369-70ff-4dbf-ba46-5e78f62bbc86

📥 Commits

Reviewing files that changed from the base of the PR and between 5fc7d07 and 512d874.

📒 Files selected for processing (29)

• devlog/_plan/260902_nonbug_adoption_backlog/100_wp10_display_names_carry.md
• devlog/_plan/260902_nonbug_adoption_backlog/101_wp10_audit_r1_synthesis.md
• docs-site/src/content/docs/ja/reference/configuration/providers.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/reference/configuration/providers.md
• docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
• docs/superpowers/plans/2026-08-26-discovered-model-display-names-core.md
• docs/superpowers/specs/2026-08-26-discovered-model-display-names-design.md
• src/cli/opencode.ts
• src/codex/catalog/provider-fetch.ts
• src/config.ts
• src/config/provider-validation.ts
• src/server/management/model-routes.ts
• src/server/management/model-rows.ts
• src/server/management/provider-routes.ts
• src/types/provider.ts
• structure/02_config-and-codex-home.md
• structure/03_catalog-and-subagents.md
• tests/codex-catalog.test.ts
• tests/codex-convergence-contract.test.ts
• tests/config-load-degrade.test.ts
• tests/config-user-edits.test.ts
• tests/management-client-config-route.test.ts
• tests/management-provider-validation.test.ts
• tests/model-display-names-management-api.test.ts
• tests/opencode-cli.test.ts
• tests/provider-config-validation.test.ts
• tests/provider-key-store.test.ts

---

📝 Walkthrough

Walkthrough

Adds durable, provider-scoped display names for discovered models. Configuration validation, catalog precedence, management API mutations, persistence, refresh handling, documentation, and focused tests are included. Routing slugs, native model IDs, and upstream request models remain unchanged.

Changes

Discovered model display names

Layer / File(s)	Summary
Configuration contract and safe loading src/types/provider.ts, src/config.ts, src/config/provider-validation.ts, src/server/management/provider-routes.ts, tests/config-*, tests/provider-config-validation.test.ts	Adds validated modelDisplayNames maps with a 2,000-entry limit, safe load degradation, redacted errors, prototype-safe persistence, and overwrite preservation.
Catalog display precedence and identity src/codex/catalog/provider-fetch.ts, src/cli/opencode.ts, structure/03_catalog-and-subagents.md, tests/codex-catalog.test.ts, tests/opencode-cli.test.ts, tests/codex-convergence-contract.test.ts	Applies operator labels before provider metadata and fallback names. Catalog fingerprints include label changes. Fallback names are omitted from exported display metadata.
Management rows and mutation API src/server/management/model-rows.ts, src/server/management/model-routes.ts, tests/model-display-names-management-api.test.ts, tests/management-client-config-route.test.ts	Adds source-aware rows and PUT /api/providers/:provider/model-display-names with validation, persistence, reset, cache clearing, convergence, rollback, and refresh-failure handling.
Reference and architecture documentation docs-site/src/content/docs/*/reference/configuration/providers.md, structure/02_config-and-codex-home.md, devlog/_plan/*, docs/superpowers/*	Documents configuration syntax, precedence, API operations, identity guarantees, implementation checkpoints, and audit results.

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

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant ManagementAPI
  participant Config
  participant Catalog
  Operator->>ManagementAPI: Set or reset model display name
  ManagementAPI->>Config: Validate and persist override
  ManagementAPI->>Catalog: Clear cache and converge catalog
  Catalog-->>ManagementAPI: Return refresh result
  ManagementAPI-->>Operator: Return effective name and source

Loading

Possibly related PRs

• lidge-jun/opencodex#1554: Updates catalog-convergence route inventory expectations after route changes.

Suggested labels: review-ready

Suggested reviewers: ingwannu, wibias

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/carry-2715-display-names

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 512d874fc7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reapply labels after trusted OpenAI API augmentation

For the reserved openai-apikey provider, gatherRoutedModelsUncached invokes augmentRoutedModelsWithCapturedOpenAiApiRows after this hint pass; that helper replaces every provider row with a newly constructed trusted row that omits displayName, and no subsequent step reapplies applyProviderConfigHints. Consequently, modelDisplayNames appears correctly in /api/models because the management projection independently rereads the config, but the generated Codex catalog ignores the override for all official OpenAI API models. Apply the configured label while constructing the trusted rows or rerun the canonical hint derivation after augmentation, and cover this provider path with a regression test.

AGENTS.md reference: src/AGENTS.md:L18-L18

Useful? React with 👍 / 👎.

[lidge-jun]

리뷰 · 우선순위 70 / 80

이 PR은 이슈 #2201의 핵심 조각입니다. 지금 dev(HEAD d23eab43a, #3224 직후, package 2.40.0)에는 이미 머지되어 있습니다(머지 커밋 d975feaa4). 발견한 provider 모델이 xai/grok-4.6 같은 기계용 아이디만 보여 주면 피커·대시보드·OpenCode 내보내기가 읽기 어렵습니다. 예전에는 그 표시를 바꾸려면 커스텀 모델로 바꾸거나 임시 패치를 써야 했고, 카탈로그를 다시 받으면 사람이 붙인 이름이 사라질 수 있었습니다. 기여자 PR #2715(zigzag-007, 20커밋)가 그 계약을 만들었지만, 포크 CI 승인 때문에 헤드를 여러 번 올려도 관리자 머지가 막혔습니다. 그래서 메인터가 같은 내용을 codex/carry-2715-display-names로 다시 올려 #3212로 가져온 것입니다. GUI 편집기 #2716은 일부러 빼고, 코어만 먼저 넣었습니다.

넣는 값은 공급자마다 따로 두는 modelDisplayNames 맵입니다. 키는 그 공급자 안의 정확한 네이티브 모델 아이디이고, 값은 표시 전용 글자입니다. 우선순위는 운영자 맵 → 공급자 카탈로그 메타데이터 → 보통 provider/model 폴백입니다. 라우팅 슬러그, 와이어 모델, 가격 키, disabled/selected/retain 매칭, 별칭·콤보 대상, 행 중복 제거는 그대로 둡니다. src/types/provider.ts 172줄에 필드가 있고, 검증은 src/config/provider-validation.ts의 modelDisplayNamesConfigError(134–165줄)가 plain object·프로토타입 가드·발견 한도(2,000)·비어 있지 않은 trim≤128·슬래시/제어문자 금지를 봅니다. 로드 시 sanitizeModelDisplayNamesForLoad(src/config.ts)가 잘못된 칸만 빼고 나머지 provider 설정은 살립니다. 카탈로그 쪽은 configuredModelDisplayName(src/codex/catalog/provider-fetch.ts 634–640줄)가 네이티브 아이디로만 읽고, applyProviderConfigHints(683줄·719줄)가 displayName만 덮습니다. 관리 API는 PUT /api/providers/:name/model-display-names(src/server/management/model-routes.ts 359줄부터)로 한 칸을 넣거나 null로 지웁니다. 행 표시는 effectiveManagementDisplayName(src/server/management/model-rows.ts 49–63줄)가 source를 operator/provider/fallback로 나눕니다.

이미 dev에 같이 있는 retainModels(#3206)와 맞물립니다. POST로 provider를 다시 저장할 때 GUI가 modelDisplayNames를 안 보내면 기존 맵을 지우면 안 됩니다. src/server/management/provider-routes.ts 712줄에서 제출 여부를 먼저 샘플하고, 741–742줄에서 캐리오버합니다. 카탈로그 지문(providerCatalogFingerprint 577줄)에 displayNames를 넣어, 라벨만 바꿔도 재수집이 일어나게 했습니다. OpenCode 내보내기(src/cli/opencode.ts)는 displayNameSource === "fallback"이면 displayName을 비워, 슬러그를 이름처럼 굳히지 않습니다. 곁가지로 #3210 키체인 테스트 픽스처가 privacy:scan에 걸린 것도 고쳤습니다. types.ts/config.ts 분할 캠페인 때문에 닫을 대상이 아닙니다. 이미 분할된 src/types/provider.ts와 src/config.ts를 올바르게 건드렸고, #2201은 닫혔으며 #2715도 캐리 안내와 함께 닫혔습니다. GUI 후속 #2716은 아직 draft로 dev를 봅니다.

라인 172 (src/types/provider.ts · modelDisplayNames?) - 공급자 설정에 표시 전용 맵이 들어갑니다. 라우팅 아이디 필드가 아닙니다.
라인 134-165 (src/config/provider-validation.ts · modelDisplayNamesConfigError) - 맵·키·값 규칙을 한곳에서 검사합니다. 로드·POST·PUT이 같은 함수를 씁니다.
라인 634-640 (src/codex/catalog/provider-fetch.ts · configuredModelDisplayName) - Object.hasOwn으로 네이티브 아이디만 읽습니다. 슬러그나 별칭으로 키를 맞추지 않습니다.
라인 577 (providerCatalogFingerprint · displayNames) - 라벨 맵이 지문에 들어가서, 이름만 바꿔도 카탈로그 비행이 다시 뜹니다. 의도된 무효화입니다.
라인 49-63 (src/server/management/model-rows.ts · effectiveManagementDisplayName) - 운영자 → 공급자 메타 → 슬러그 폴백 순입니다. identity 필드를 바꾸지 않습니다.
라인 359-415 (src/server/management/model-routes.ts · PUT model-display-names) - null이면 그 아이디만 지웁니다. persist 실패 시 메모리 맵을 되돌리고, 카탈로그 갱신 실패면 저장은 됐다는 503을 줍니다.
라인 712, 741-742 (src/server/management/provider-routes.ts) - enrich 전에 제출 여부를 샘플하고, 폼이 맵을 안 보내면 기존 modelDisplayNames를 유지합니다. #3206 retainModels와 같은 패턴입니다.
심볼 sanitizeModelDisplayNamesForLoad (src/config.ts) - 손편집 실수는 잘못된 칸만 지우고 provider 전체를 기본값으로 밀어 버리지 않습니다.
심볼 OpenCode displayNameSource === "fallback" (src/cli/opencode.ts) - 폴백 슬러그를 내보내기 이름으로 굳히지 않습니다. 운영자/공급자 라벨만 넘깁니다.

메인테이너의 판단이 필요한 지점

• 이미 dev에 들어가 있으므로 추가 머지 판단은 없습니다. 이 댓글은 늦게 온 웨이크용 기록 리뷰입니다.
• GUI 후속 feat: add discovered model display name editor #2716(draft)을 지금 dev 기준으로 리베이스해 검토할지, 아니면 코어 사용 데이터를 더 보고 받을지.
• 원본 #2715에 landed-via-maintainer 라벨이 아직 없습니다. 닫힘·감사 댓글은 있으나 라벨만 비어 있습니다.
• 대소문자 구분 키(grok-4.6 vs Grok-4.6)를 문서·API 에러에서 더 세게 강조할지. 지금 검증은 정확한 아이디만 받습니다.
• types/config 분할과는 무관하니 되돌리거나 닫을 이유가 없습니다.

너의 추천
이미 머지된 캐리를 그대로 둡니다. #2201 닫힘과 #2715 닫힘을 유지하고, #2715에 landed-via-maintainer만 붙입니다. GUI #2716은 작성자가 dev(이 코어 위)로 리베이스한 뒤에만 리뷰합니다. 코어 계약(라벨≠아이덴티티, 검증 공용화, POST 캐리오버, PUT 단건 리셋)은 현재 HEAD에서 맞습니다. 새 버그로 되돌릴 이유는 없습니다.

이 댓글은 grok-bot이 작성했습니다