fix(catalog): display effective model aliases in Codex picker

[terrytan95]

Summary

• Project existing effective provider/model aliases into the Codex catalog's display-only display_name path.
• Preserve explicit custom/combo display names first, effective aliases second, and the canonical slug as the existing fallback.
• Keep canonical catalog slugs, upstream model ids, persisted selectors, routing, usage, and pricing identities unchanged.
• Document the catalog presentation contract.

This is the missing catalog-display follow-up to #2463 / #2610. It reuses effectiveModelAliases() instead of adding another alias implementation. It also composes with #2715: an explicit display name remains higher priority than an alias-derived label.

Closes #2959

Verification

• Focused regression test covers gatherRoutedModels() → buildCatalogEntries() and asserts:
  • provider/model aliases become the picker display_name
  • the canonical routing slug remains unchanged
• bun test tests/codex-catalog.test.ts — 218 pass, 0 fail
• bun test tests/provider-model-aliases.test.ts — 7 pass, 0 fail
• bun run typecheck under Node 24.3.0 — pass
• cd docs-site && bun run build under Node 24.3.0 — 401 pages built
• Full bun run test main lane — 16,123 pass / 12 skip / 3 fail / 3 environment-sensitive errors; the four repository-documented environment-sensitive files then passed serially, 188/188. Kept as draft because the aggregate command did not exit cleanly.

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.

Review readiness checklist

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

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features

  • Model pickers now show qualified provider and model aliases when configured, making customized names easier to recognize.
  • Canonical provider/model identifiers remain unchanged for routing and compatibility.

• Documentation

  • Updated configuration and catalog reference documentation to explain the difference between displayed aliases and canonical routing identifiers.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7ceaa48c-95d6-4899-bbad-a24fb5107761

📥 Commits

Reviewing files that changed from the base of the PR and between dca1694 and 72adf72.

📒 Files selected for processing (4)

• docs-site/src/content/docs/reference/configuration.md
• src/codex/catalog/provider-fetch.ts
• structure/03_catalog-and-subagents.md
• tests/codex-catalog.test.ts

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

---

📝 Walkthrough

Walkthrough

The catalog now displays qualified provider and model aliases while preserving canonical provider/model routing slugs. A catalog test verifies this behavior, and configuration and catalog documentation describe the distinction.

Changes

Catalog alias display

Layer / File(s)	Summary
Derive and apply alias display names src/codex/catalog/provider-fetch.ts	gatherRoutedModelsUncached resolves effective model aliases and applies qualified display names when a catalog model has no explicit display name.
Validate and document catalog output tests/codex-catalog.test.ts, docs-site/src/content/docs/reference/configuration.md, structure/03_catalog-and-subagents.md	The test verifies ga/g3f as display_name and preserves google-antigravity/gemini-3.7-flash as the slug. Documentation describes the same display and routing values.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 72adf

The change only affects how existing aliases appear in the Codex picker while preserving canonical routing and persisted identities. No actionable merge-blocking risk remains; it is merge-ready after normal checks and review.

Suggested reviewers: ingwannu

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (2 skipped: 2 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the primary change: displaying effective model aliases in the Codex picker catalog.
Linked Issues check	✅ Passed	The changes satisfy issue #2959. src/codex/catalog/provider-fetch.ts applies effectiveModelAliases() to routed models and sets display-only aliases while preserving canonical routing slugs. `tests…
Out of Scope Changes check	✅ Passed	All changes are in scope for issue #2959. The implementation fixes catalog display metadata, the test covers the regression, and the documentation updates explain alias display behavior. No unrelated …

Full details: Linked Issues check

Explanation

The changes satisfy issue #2959. src/codex/catalog/provider-fetch.ts applies effectiveModelAliases() to routed models and sets display-only aliases while preserving canonical routing slugs. tests/codex-catalog.test.ts verifies the alias display name and unchanged provider/model slug. The documentation updates describe the same catalog presentation contract.

Full details: Out of Scope Changes check

Explanation

All changes are in scope for issue #2959. The implementation fixes catalog display metadata, the test covers the regression, and the documentation updates explain alias display behavior. No unrelated code or behavior changes are identified.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 hygiene checks failed.

• missing_regression_test — Behavior changed under src/ or gui/src/ without a test change. Add focused coverage or obtain test-exception-approved.

[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

• ⬜ All CI tests are green on my local testing.
• ⬜ I pushed my PR to the latest dev commit.
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

This PR stays in draft until every box above is ticked.

[lidge-jun]

리뷰 · 우선순위 62 / 80

설명

이 PR은 이슈 #2959를 고칩니다. 프로바이더/모델 별칭은 요청을 올바른 정식 아이디로 보내 주는데, Codex 피커 글자는 그대로 긴 provider/model이었습니다. 고치는 곳은 src/codex/catalog/provider-fetch.ts의 gatherRoutedModelsUncached입니다. 이미 있는 effectiveModelAliases(src/providers/default-aliases.ts)를 한 번 더 써서, 별칭이 있으면 CatalogModel.displayName에 프로바이더별칭/모델별칭을 넣습니다. 커스텀/콤보가 이미 준 표시 이름이 있으면 그걸 이깁니다. 정식 슬러그, 업스트림 아이디, 라우팅, 사용량, 가격 정체성은 안 바꿉니다. 문서(docs-site 설정 페이지, structure/03_catalog-and-subagents.md)도 그 계약을 적습니다.

지금 dev HEAD는 b95dc5d42(#2962, 테스트 락을 사용자 런타임으로 좁힘)입니다. 카탈로그 표시 코드는 HEAD와 이 PR 기반 dca16949b가 같습니다. HEAD의 applyCatalogModelMetadata(src/codex/catalog/effort.ts)는 displayName이 있을 때만 display_name을 덮습니다. 네이티브 행은 CatalogModel이 없어서 마케팅 이름이 그대로입니다. /v1/models의 alias_of(src/server/index.ts)는 열린 호환 목록용이라 피커를 고치지 못합니다. 그래서 별칭을 gatherRoutedModels에서 displayName으로 넣는 자리 선택이 맞습니다. 새 별칭 구현을 또 만들지 않고 #2463 / #2610 맵을 재사용합니다. types.ts/config.ts 대분할과 안 겹칩니다.

테스트는 tests/codex-catalog.test.ts에 하나 있습니다. google-antigravity에 alias: ga, modelAliases: gemini-3.7-flash → g3f를 주고 gatherRoutedModels → buildCatalogEntries를 탑니다. display_name은 ga/g3f, slug는 google-antigravity/gemini-3.7-flash로 잠급니다. 본문은 codex-catalog 218통과, provider-model-aliases 7통과, typecheck와 docs-site 빌드를 적었습니다. 전체 bun run test는 16,123통과에 실패 3·환경 민감 3이 있어 드래프트로 남겼습니다. 리뷰 준비 체크리스트 네 칸은 아직 비어 있습니다.

이슈 재현 설정은 프로바이더 alias가 없고 gemini-3.7-flash → gemini-3.7입니다. 그때 기대 글자는 google-antigravity/gemini-3.7입니다. 지금 테스트는 프로바이더 별칭 ga와 짧은 g3f라, 이슈 화면과 한 글자도 같지는 않습니다. 메커니즘은 같고, 이슈 JSON을 그대로 잠그지는 않았습니다. defaultModelAliases만 켠 내장 별칭(이슈가 말한 cursor/grok)도 새 테스트가 없습니다. #2715처럼 커스텀 displayName이 별칭보다 이긴다는 주장도 코드의 !model.displayName으로 보이지만, 그 우선순위를 깨는 테스트는 없습니다.

표시 이름에 /가 들어가는 것은 의도입니다. 피커에 자격 있는(qualified) 별칭을 보여 주려는 계약입니다. applyCatalogModelMetadata는 커스텀 입력에서 /를 거절하는 경로와 다릅니다. 여기서는 display_name만 덮습니다. 라우팅 슬러그는 그대로라 선택자가 깨지지 않습니다.

src/codex/catalog/provider-fetch.ts aliasDisplayNames - 프로바이더마다 models.filter를 돌아 목록 크기가 커지면 비용이 커집니다. 주석도 그 점을 알고 있습니다. 지금 카탈로그 크기에서는 막힐 정도는 아닙니다.

src/codex/catalog/provider-fetch.ts 표시 맵 키 - 요청 별칭 해석(resolveModelAlias)은 대소문자를 접습니다. 표시 맵은 modelAliases 키와 model.id를 글자 그대로 맞춥니다. 설정 키만 대소문자가 다르면 요청은 되고 피커는 긴 아이디로 남을 수 있습니다.

tests/codex-catalog.test.ts 새 테스트 - ga/g3f만 잠급니다. 이슈 재현(google-antigravity/gemini-3.7), 내장 기본 별칭, 커스텀 displayName이 별칭을 이긴다는 #2715 핀이 없습니다.

PR 상태 - 드래프트이고 체크리스트가 비어 있습니다. 작성자가 전체 테스트가 한 번에 안 끝났다고 적어 두었습니다. 지금 병합하면 안 됩니다.

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

• 드래프트가 준비될 때까지 기다릴지, 테스트만 닫히면 메인테이너가 캐리할지.
• 내장 기본 별칭도 피커에 넣을지(이슈는 넣기를 기대함. 이 PR의 effectiveModelAliases는 넣습니다).
• 표시 맵도 요청 경로처럼 대소문자를 접을지.

너의 추천

지금은 병합하지 마세요. 방향은 맞고 #2959의 올바른 고침입니다. 이슈와 같은 설정으로 display_name을 잠그는 테스트 하나, 그리고 커스텀 표시 이름이 별칭보다 이긴다는 테스트 하나를 더한 뒤, 드래프트를 벗기고 CI가 초록이면 dev에 넣으세요. 랜딩 후 #2959를 닫으면 됩니다. 대형 config 분할을 기다릴 이유는 없습니다.

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