Skip to content

Commit 438b9cc

Browse files
authored
devlog: model/provider UX design unit — aliases, new-models-off, default preset (#2463 #2464 #2465) (#2466)
* devlog: model/provider UX design unit — aliases, new-models-off, default preset Design-only unit 260824_model_ux_aliases_and_defaults: 000 research, 010 provider+model aliases, 020 new-models-arrive-off baseline, 030 latest-only default preset. Basis for three feature issues. * devlog: link filed issues #2463 #2464 #2465
1 parent 35a8990 commit 438b9cc

4 files changed

Lines changed: 468 additions & 0 deletions

File tree

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# 000 — model_ux_aliases_and_defaults: Plan & Research
2+
3+
## Objective
4+
5+
Design — to issue-ready, near-implementation precision — three model/provider UX
6+
improvements, file them as three templated GitHub issues on
7+
`lidge-jun/opencodex`, and land this design unit on `dev` via a docs-only PR.
8+
No implementation code in this unit.
9+
10+
Trigger: X feedback on the model picker
11+
([@terryaidev](https://x.com/terryaidev/status/2091696002550083870)):
12+
"Probably add customized model name, since some of the model names can be very
13+
long and not good for user experience." Plus two operator-observed defaults
14+
problems: live-catalog providers (OpenRouter) expose 400+ models all-on, and
15+
catalog refresh introduces new models already enabled.
16+
17+
## Deliverables
18+
19+
| Doc | Design | Issue |
20+
|-----|--------|-------|
21+
| 010 | Provider & model aliases (pencil edit, defaults set, CLI space) | [#2463](https://github.com/lidge-jun/opencodex/issues/2463) |
22+
| 020 | Newly discovered models arrive OFF by default | [#2464](https://github.com/lidge-jun/opencodex/issues/2464) |
23+
| 030 | Latest-only default preset per provider | [#2465](https://github.com/lidge-jun/opencodex/issues/2465) |
24+
25+
## Current behavior (evidence base)
26+
27+
- Visibility is a two-filter system (`src/server/management/model-routes.ts`):
28+
- Per-provider allowlist `providers.<name>.selectedModels` — absent/empty
29+
means "expose everything" (`/api/selected-models` GET/PUT, line ~531).
30+
- Global blocklist `config.disabledModels` (`/api/disabled-models`, ~272).
31+
- `/api/model-visibility` (PUT, ~285) updates both atomically; scope
32+
`models` or `provider`; native rows use only the blocklist.
33+
- GUI: `gui/src/model-visibility.ts` — `modelIncluded()` returns true when
34+
the allowlist is absent OR empty; `gui/src/pages/Models.tsx` renders per-
35+
provider toggle lists ("모두 켜기 / 모두 끄기", custom window).
36+
- CLI: `ocx models` subcommands `live/edit/enable/disable/provider/selected/
37+
context/shadow` (`src/cli/models.ts:415`, `src/cli/models-runtime.ts`).
38+
- `ModelConfig.displayName` already exists (`src/types/config.ts:190,626`)
39+
but only for custom models; there is no provider alias and no resolvable
40+
model alias.
41+
- Live catalogs: `liveModels?: boolean` (`src/types/provider.ts:260`);
42+
`getProviderLiveModelCount` feeds the GUI. New live models are visible the
43+
moment they are discovered (allowlist absent = all-on).
44+
45+
## Loop-spec
46+
47+
- Loop archetype: verifier-defined (issues exist + PR merged = done).
48+
- Write scope: `devlog/_plan/260824_model_ux_aliases_and_defaults/**` only.
49+
Out of scope: any `src/`, `gui/`, `docs-site/` change; implementation.
50+
- External writes: 3 issues on lidge-jun/opencodex; 1 PR to `dev` + merge
51+
(explicitly user-authorized in the request).
52+
- Budget: single PABCD work-phase; sol-medium subagent drafts, main verifies.
53+
54+
## Work-phase map (one phase = one full PABCD cycle)
55+
56+
| WP | Doc | Slice | Depends on |
57+
|----|-----|-------|------------|
58+
| wp1 | 000/010/020/030 | Research + three designs + 3 issues + docs PR merged to dev | — |
59+
60+
Implementation work-phases are intentionally NOT scheduled here; each issue
61+
becomes its own future unit when picked up.
62+
63+
## Accept criteria
64+
65+
- c1: three issues created on lidge-jun/opencodex using the exact
66+
`feature_request.yml` form headings (survives enforce-issue-quality).
67+
- c2: this unit contains 000/010/020/030 at design precision.
68+
- c3: docs-only PR targeting `dev` merged; merge SHA recorded in 090.
Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# 010 — Provider & Model Aliases
2+
3+
Status: design proposal (no code). Scope: config schema, request-time resolution, catalog exposure, management API, CLI, GUI.
4+
5+
## Motivation
6+
7+
X feedback: "add customized model name, since some model names can be very long." Real routed slugs today are things like `google-antigravity/gemini-3-pro-preview-11-2025` or `openrouter/anthropic-claude-opus-4.6`. Users type these into Codex's model picker, `/model`, CLI flags, and combo targets. A short, user-chosen alias (`agy/opus`) removes friction on every one of those surfaces. Combos already prove the concept: `OcxComboConfig.alias` (src/types/config.ts:626 area, src/combos/types.ts:43) gives a combo a public short id that resolves at request time. This design generalizes that to providers and individual models.
8+
9+
## Current behavior (verified)
10+
11+
- `OcxCustomModel.displayName` exists (src/types/config.ts:190) and combo `displayName` (src/types/config.ts:626). Both are display-only: src/codex/catalog/effort.ts:118-124 sets `entry.display_name` and explicitly never touches routing.
12+
- Combo aliases are the only *resolvable* aliases today: `comboPublicModelId` (src/combos/types.ts:76), uniqueness + reserved-namespace validation (src/combos/types.ts:123-165), resolved in `routeModelInternal` before provider namespaces (src/router.ts:627-636).
13+
- Request routing order in `routeModelInternal` (src/router.ts:558-706): policy namespace → Codex account namespace → combo alias → explicit `<provider>/<model>` for a *configured* provider name → bare native OpenAI family → provider `defaultModel` match → known-model-pattern → provider `models` list → `defaultProvider` fallback.
14+
- Codex-facing slugs are `routedSlug(provider, id)` with inner slashes encoded to `-` and an exact bijective decode against known ids (src/providers/slug-codec.ts:28-82).
15+
- Live-catalog providers (`liveModels: true`, src/providers/registry.ts:165; e.g. openrouter with 400+ models) have model ids that never appear in static config — any per-model alias store must key by model id on the provider, not by config model rows.
16+
- Provider names are validated by `isValidProviderName` (src/config/provider-name.ts:15) with `RESERVED_PROVIDER_NAMES` (prototype-pollution guards + system namespaces).
17+
18+
## Design
19+
20+
### Config schema
21+
22+
```jsonc
23+
{
24+
"providers": {
25+
"google-antigravity": {
26+
"alias": "agy", // NEW: provider alias (id-shaped, no "/")
27+
"modelAliases": { // NEW: per-model aliases keyed by NATIVE model id
28+
"gemini-3-pro-preview-11-2025": "g3p"
29+
},
30+
"defaultAliases": true // NEW: opt into built-in alias set for this provider
31+
}
32+
},
33+
"defaultModelAliases": true // NEW: global opt-in, applied across ALL providers
34+
}
35+
```
36+
37+
Field semantics:
38+
39+
- `providers.<name>.alias?: string` — one alias per provider. Must pass `isValidProviderName` (same pattern, same reserved set) and must not equal any configured provider name, any other provider's alias, `policy`, `combo`, or a Codex account namespace. Validated at config load and at the write API.
40+
- `providers.<name>.modelAliases?: Record<string, string>` — native model id → alias. Keys are native ids (may contain "/", e.g. openrouter's `anthropic/claude-opus-4.6`), matching the `modelContextWindows` / `modelCosts` convention (src/types/provider.ts:272-296). This is why it lives on the provider and not on model rows: live-catalog models have no config row, but a Record keyed by id survives catalog refresh untouched.
41+
- `providers.<name>.defaultAliases?: boolean` and top-level `defaultModelAliases?: boolean` — enable the built-in alias set per provider or globally. Per-provider value wins over global when both are set. Default: off (aliases are additive surface area; opt-in keeps zero behavior change).
42+
- Alias value pattern for models: `^[A-Za-z0-9][A-Za-z0-9._-]*$`, no "/". A model alias is always used as the segment after the provider segment (or bare, see resolution), so it must be slash-free — same constraint custom-model `displayName` already enforces (model-routes.ts:407).
43+
44+
### Built-in default alias set
45+
46+
Shipped in code as a new module `src/providers/default-aliases.ts`:
47+
48+
```ts
49+
/** Native-model-id pattern -> alias. First match wins; ordered most-specific first. */
50+
export const DEFAULT_MODEL_ALIASES: ReadonlyArray<{ match: RegExp; alias: string }> = [
51+
{ match: /^claude-opus-5/, alias: "opus" },
52+
{ match: /^claude-sonnet-5/, alias: "sonnet" },
53+
{ match: /^claude-haiku/, alias: "haiku" },
54+
{ match: /^gemini-3(\.\d+)?-pro/, alias: "g3p" },
55+
{ match: /^gemini-3(\.\d+)?-flash/, alias: "g3f" },
56+
{ match: /^deepseek-v4/, alias: "ds4" },
57+
{ match: /^grok-4/, alias: "grok" },
58+
// ...curated, extended over releases; also matches after stripping a vendor prefix
59+
// ("anthropic/claude-opus-5" on openrouter matches the opus rule).
60+
];
61+
```
62+
63+
Vendor-prefixed ids (aggregators) are matched against both the full id and the segment after the last "/". Built-ins are patterns, not exact ids, so snapshot suffixes (`-20260115`) keep their alias across provider refreshes. Precedence: user `modelAliases` entry > built-in rule. Within built-ins, when two models on the SAME provider both match one rule (e.g. two opus snapshots), the built-in alias binds to none of them — ambiguity disables the built-in for that provider and the models list shows a hint; the user resolves it with an explicit `modelAliases` entry. Deterministic and safe over "latest wins" guessing.
64+
65+
### Request-time resolution
66+
67+
Two hook points in `routeModelInternal` (src/router.ts), not one — the qualified and bare forms live at different depths of the existing resolution ladder:
68+
69+
- **Qualified (`head/tail`) aliases** extend the explicit provider-namespace step (src/router.ts:640-665): when the head matches no configured provider name, try provider aliases before falling through; within a resolved provider, when the tail matches no known id/encoded slug, try model aliases. This stays below combo aliases (src/router.ts:627-636), so any name a combo already claims keeps its current meaning.
70+
- **Bare model aliases** are a LATE step: after every existing bare-resolution step (native OpenAI family, provider defaultModel, known-model pattern, provider models list — src/router.ts:672-698) and immediately BEFORE the `defaultProvider` fallback (src/router.ts:699-703).
71+
72+
One deliberate, documented behavior change follows from the bare-alias slot: a bare id that today reaches the `defaultProvider` fallback resolves via alias instead when it matches an enabled one. This only triggers for alias values the user defined (or a built-in set the user explicitly turned on), which is exactly the intent of defining the alias; the design accepts this as opt-in shadowing of the fallback, and the collision rules below keep aliases from shadowing anything that resolves earlier in the ladder.
73+
74+
Rules for an incoming model id `X`:
75+
76+
1. If `X` contains "/": split at the first "/". Resolve the head as a provider: exact configured-provider name first, else a provider whose `alias` matches. Resolve the tail within that provider: exact known model id / encoded slug first, else a `modelAliases` value match, else an enabled built-in alias match. `agy/opus` → provider `google-antigravity`, model `claude-opus-5-...` — resolved in one pass, both segments may be aliases independently. Note the current slash-path already has partial-match fallbacks (src/router.ts:659-665), so "exact first" describes ordering within the extended step, not a claim that the whole step is untouched.
77+
2. If `X` is bare (no "/"): existing steps run first (native OpenAI family, provider defaultModel, pattern, models list). If ALL miss, a bare model alias resolves — ahead of the `defaultProvider` fallback (src/router.ts:699-703) — iff exactly one enabled (provider, model) pair carries that alias; two providers sharing alias `opus` make the bare form an error listing both candidates ("model alias 'opus' is ambiguous: agy/opus, claude/opus"), while the qualified forms keep working. A bare provider alias alone never routes.
78+
3. Aliases resolve for main requests, combo target strings, and subagent model fields — anywhere `routeModel` runs. Resolution happens once, before adapters; upstream always receives the native id. Usage logs and request logs record the native slug plus a `requestedAlias` field so log rows stay joinable.
79+
80+
Collision rules (validated at write time, enforced again defensively at load):
81+
82+
- Provider alias vs real provider name: rejected (409 from API, config-load warning + alias ignored for hand-edited config).
83+
- Provider alias vs another provider alias: rejected.
84+
- Model alias vs a real model id on the same provider: rejected for user-set; built-in rule silently skipped (catalog drift must not break startup).
85+
- Two models on one provider with the same user alias: rejected at write time (last write loses, 409 "alias already used by <id>").
86+
- Case sensitivity: aliases are stored as typed but matched case-insensitively. Rationale: aliases are typed by hand (the whole point is typing less), so `Opus`/`opus` diverging silently would be a trap; the reserved-name guard already normalizes with `name.toLowerCase()` (src/config/provider-name.ts), and matching follows that convention. Two aliases differing only by case collide.
87+
88+
### Catalog exposure (/v1/models and Codex catalog)
89+
90+
Two options considered:
91+
92+
- (a) Alias replaces the id: shortest picker entries, but breaks log/usage continuity, breaks any client that persisted the old slug, and makes disabledModels/selectedModels matching ambiguous.
93+
- (b) Alias as an additional resolvable id; display uses alias: canonical slug `provider/model` stays the row id everywhere; the catalog row gains `display_name` = `alias` (provider-alias-qualified: `agy/opus`) via the existing display_name path (src/codex/catalog/effort.ts:118-124); /v1/models additionally lists the alias id as its own entry marked `"alias_of": "google-antigravity/claude-opus-5"` so scripted clients can request it directly.
94+
95+
Recommendation: (b). Persistence (selectedModels, disabledModels, combos, usage) keeps canonical slugs only; aliases are a resolution/display layer that can be renamed or removed without touching stored state. `slugEquals` and the visibility filters (src/codex/catalog/provider-fetch.ts:1555-1577) are unchanged.
96+
97+
### Management API
98+
99+
- `PUT /api/providers/:name/alias` body `{"alias": "agy"}` → `{"ok":true,"provider":"google-antigravity","alias":"agy"}`; `{"alias": null}` clears. 409 on collision with `{"error":"alias conflicts with provider 'x'"}`.
100+
- `PUT /api/providers/:name/model-aliases` body `{"set": {"gemini-3-pro-preview-11-2025": "g3p"}, "remove": ["old-id"]}` → `{"ok":true,"aliases":{...}}`. Partial-update semantics like other model-keyed Records; 409 per-entry collisions reported as `{"error":"...","conflicts":[{"alias":"g3p","heldBy":"..."}]}`.
101+
- `PUT /api/default-aliases` body `{"enabled": true, "provider": "openrouter"}` (provider omitted = global) → `{"ok":true}`.
102+
- `GET /api/aliases` → effective view: `{"providers":{"google-antigravity":"agy"},"models":{"google-antigravity":{"gemini-3-pro-preview-11-2025":{"alias":"g3p","source":"user"}}},"defaults":{"global":false,"providers":{"openrouter":true}},"ambiguousBuiltins":{"claude":["opus"]}}`. The GUI and CLI both read this one endpoint.
103+
- All writes go through `saveConfigPreservingClaudeCode` and end with `convergeCodexCatalog()` like the existing model routes (model-routes.ts:172, 277-279), so display_name changes reach Codex on the next turn.
104+
105+
### CLI
106+
107+
Namespace: `ocx alias` (top-level; aliases span providers and models, and `ocx models` is already eight subcommands deep — src/cli/models.ts:415).
108+
109+
```
110+
ocx alias list [--json] # effective table: kind, target, alias, source (user|builtin)
111+
ocx alias set <provider> <alias> # provider alias: ocx alias set google-antigravity agy
112+
ocx alias set <provider>/<modelId> <alias> # model alias: ocx alias set openrouter/anthropic/claude-opus-4.6 opus
113+
ocx alias rm <provider>[/<modelId>] # clear
114+
ocx alias defaults on|off [--provider <name>] # built-in set, global or per provider
115+
```
116+
117+
`<provider>/<modelId>` splits at the FIRST "/" (provider names cannot contain "/"); the remainder is the native id, slashes included. Implemented in `src/cli/alias.ts` following the models-runtime.ts pattern (runtimeRequest against the management API, offline config fallback like `ocx models add`).
118+
119+
### GUI
120+
121+
- Models window (gui/src/pages/Models.tsx): pencil icon after the provider group header sets the provider alias; pencil on each model row sets/clears the model alias (inline edit, Enter saves, shows 409 conflicts inline). Rows show `alias · canonical-id` with alias emphasized.
122+
- Provider header overflow menu gains "Use default aliases" toggle (per provider); a global toggle sits in the Models window toolbar next to the existing visibility controls. Built-in-derived aliases render with a subtle "auto" badge; clicking one pre-fills the edit field to promote it to a user alias.
123+
- Bulk view: toolbar "Aliases" button opens a filterable table (provider, model, alias, source) with inline editing — the GET /api/aliases payload verbatim.
124+
125+
## Resolution & edge cases
126+
127+
- Catalog refresh: `modelAliases` keys pointing at ids no longer discovered are kept (snapshot churn is temporary); `GET /api/aliases` marks them `"stale": true` and the GUI dims them. Nothing auto-deletes user intent.
128+
- Export/import: aliases live inside config.json, so existing config export/import carries them. Client config export (`/api/client-config`, ocx export) emits canonical ids; a follow-up may add `--use-aliases`.
129+
- Combos: combo target strings may use aliases (resolved through routeModel); the combo `alias` field itself is unchanged and keeps winning at its earlier resolution slot. Collision checks are bidirectional: a provider/model alias colliding with an existing combo alias is rejected at write time, and combo alias validation (src/combos/types.ts:123-165) gains the mirror check against existing provider/model aliases.
130+
- Native OpenAI models: bare native family ids (src/router.ts:672) resolve before alias lookup, so a built-in alias can never shadow `gpt-5.6-sol`; a user alias equal to a native family id is rejected (same guard combos apply via nativeAlias, src/combos/types.ts:146-152).
131+
- Codex account namespaces resolve before aliases (src/router.ts:598); an alias equal to a configured account namespace is rejected.
132+
- Renaming a provider (config key change) orphans its alias with it — aliases are stored inside the provider object, so they move or die with the provider entry atomically.
133+
134+
## Migration & compatibility
135+
136+
- No migration: all fields optional, absent = today's behavior exactly. Old binaries reading a new config ignore unknown keys (config parse is tolerant; `safeConfigDTO` should include the new fields for the GUI).
137+
- Requests by canonical slug are untouched at every step — alias resolution only runs where today's resolution would already have missed or after exact matches fail. The one intentional exception is the bare-alias-over-defaultProvider shadowing documented in Request-time resolution above.
138+
139+
## Out of scope
140+
141+
- Aliases for combos (exists), policies, or Codex accounts.
142+
- Alias-based filtering in usage/cost summaries (logs store canonical + requestedAlias; summary UX later).
143+
- Per-client alias sets (different aliases for Claude Code vs Codex).
144+
145+
## Open questions
146+
147+
1. Should /v1/models list alias entries as separate rows or only annotate? Proposed: separate row with `alias_of`, gated behind a query param `?aliases=1` initially to avoid confusing existing clients. Default recommendation: annotate-only in v1, separate rows once a client asks.
148+
2. Bare model alias (`opus` with no provider) — allow when globally unique? Proposed: yes (rule 2 above); it is the highest-value typing shortcut and the ambiguity error is deterministic.
149+
3. Built-in alias list curation cadence — proposed: update alongside the provider registry in normal releases; no runtime fetch.

0 commit comments

Comments
 (0)