|
| 1 | +# wp4 — #1690 retainModels allowlist (two rival PRs) |
| 2 | + |
| 3 | +Issue #1690 (score 58, labels enhancement/catalog). Two open drafts implement it: |
| 4 | + |
| 5 | +| | PR #2860 (rrmlima) | PR #2122 (chilung-cgu) | |
| 6 | +| --- | --- | --- | |
| 7 | +| size | +132/-2, 3 files | +726/-25, 15 files | |
| 8 | +| CI at head | fully green (test 1-4, macos, ci) | only hygiene/label/target ran | |
| 9 | +| base | e546c160b, 310 behind dev; cherry-picks cleanly onto `fcf0da257` | same base | |
| 10 | +| retention | `shouldRetainConfiguredProviderModel(name, id, prov)` + `modelInList` | new `providerRetainModels` set inside the merge loop | |
| 11 | +| ids must also be in `models`? | yes (purely retentive) | no (`retainModels` folded into `configuredIds`) | |
| 12 | +| config validation | none (relies on `.passthrough()`) | zod `retainModels` + `nonBlankStringArrayConfigError` | |
| 13 | +| management API / DTO | none | none (neither exposes it via PATCH) | |
| 14 | +| rename migration | none | adds `retainModels` to `MODEL_ID_LISTS` | |
| 15 | +| 404 diagnostic | none | new module state + `warnRetainedModel404Once` wired into 4 request handlers, `CatalogModel.retainedWithoutDiscovery` | |
| 16 | +| docs | none | 5 locales, one table row each | |
| 17 | + |
| 18 | +## Decision |
| 19 | + |
| 20 | +Adopt **#2860 as the base commit** (cherry-picked as `2be9d505d` on |
| 21 | +`codex/retain-models-1690`), then add the pieces that make the opt-in |
| 22 | +discoverable and safe to hand-edit. #2122 is closed as superseded with credit for |
| 23 | +the config/migration design. |
| 24 | + |
| 25 | +Why #2860 over #2122: the retention decision belongs in the one predicate the |
| 26 | +merge loop already consults; #2122 adds a second set beside it. #2122's 404 |
| 27 | +diagnostic requires module-level maps keyed by provider, a new `CatalogModel` |
| 28 | +field, and edits to `core.ts`, `chat-completions.ts`, `chat-native.ts`, |
| 29 | +`claude-messages.ts` — four hot request paths — to print one warning that the |
| 30 | +upstream error body already carries (`model_not_found`). That is the wrong |
| 31 | +trade for this cycle; the existing `warnDroppedConfiguredIdsOnce` stays as the |
| 32 | +diagnostic for ids that are *not* retained. |
| 33 | + |
| 34 | +## What this cycle adds on top of #2860 |
| 35 | + |
| 36 | +1. **`retainModels` alone is enough.** `configuredIds` in |
| 37 | + `fetchProviderModelsWithAuth` becomes the ordered union of the Vertex seed, |
| 38 | + `prov.models`, and `prov.retainModels`. An operator who writes |
| 39 | + `"retainModels": ["gemini-3.7-flash"]` should not have to repeat the id in |
| 40 | + `models`; requiring both is the footgun #2122 correctly avoided. #2860's |
| 41 | + "does not invent ids" test flips to assert the union. |
| 42 | +2. **Schema + load normalization** (`src/config.ts`): `retainModels: |
| 43 | + z.array(z.string().min(1)).transform(normalizeNonBlankStringArray).optional()` |
| 44 | + next to `noStructuredOutputModels`, plus the same `superRefine` entry so a |
| 45 | + hand-edited `"retainModels": "x"` fails with a path instead of being silently |
| 46 | + passed through. |
| 47 | +3. **Management PATCH + DTO** (`src/server/management/provider-routes.ts`): |
| 48 | + `retainModels` accepted like `noStructuredOutputModels` (`null` clears, |
| 49 | + empty array clears, validated with `nonBlankStringArrayConfigError`), and |
| 50 | + returned in the safe provider DTO so the dashboard/API round-trips it. |
| 51 | +4. **CLI opt-in** (`src/cli/provider-runtime.ts`): |
| 52 | + `ocx provider edit <name> --retain-models <id,id|->`. This is the easy |
| 53 | + switch: one flag, no JSON editing, `-` clears. Usage string and |
| 54 | + `skills/ocx` surface are regenerated if the capability registry changes |
| 55 | + (it does not — `provider edit` already exists; only the flag list grows). |
| 56 | +5. **Rename migration** (`src/providers/model-rename-migration.ts`): |
| 57 | + `"retainModels"` added to `MODEL_ID_LISTS` so a retired id is renamed |
| 58 | + rather than resurrected as a ghost row. |
| 59 | +6. **Docs** (`docs-site/.../reference/configuration/providers.md`): one table |
| 60 | + row after `selectedModels`, and a short paragraph in "Static model |
| 61 | + allowlists" contrasting `selectedModels` (narrows) with `retainModels` |
| 62 | + (preserves). English only this cycle; locales already lag on |
| 63 | + `noStructuredOutputModels` and a missing row does not contradict. |
| 64 | + |
| 65 | +## Explicitly not in this cycle |
| 66 | + |
| 67 | +- Seeding `CALLABLE_CONFIGURED_COMPATIBILITY_MODELS` with antigravity |
| 68 | + `gemini-3.7-flash` (issue step 4). That is a product default, and #1683 is a |
| 69 | + separate issue; with the config key available it no longer needs a release. |
| 70 | +- GUI field. The dashboard provider editor is untouched; the PATCH contract is |
| 71 | + ready for it, and a later PR can add the input with its screenshot. |
| 72 | +- 404-time warning. See "Decision". |
| 73 | + |
| 74 | +## Acceptance criteria |
| 75 | + |
| 76 | +- `retainModels` absent/empty → catalog identical to today (existing |
| 77 | + `tests/codex-catalog.test.ts` retention tests untouched and green). |
| 78 | +- `retainModels: ["x"]`, live omits `x`, `x` not in `models` → `x` present |
| 79 | + with provider hints applied; `droppedConfiguredIds` excludes it. |
| 80 | +- `retainModels: ["x"]`, live returns `x` → single row, no duplicate. |
| 81 | +- `liveModels: false` → `retainModels` ids are part of the static list. |
| 82 | +- Config load rejects `retainModels: "x"` / `[""]` with a |
| 83 | + `providers.<name>.retainModels` path; trims and dedupes valid input. |
| 84 | +- Management PATCH sets/clears; DTO echoes; CLI flag round-trips through PATCH. |
| 85 | +- A test through `fetchProviderModels` (not only `mergeConfiguredModelsIntoLiveCatalog`) proves a retain-only id survives both live discovery and `liveModels: false` (audit r1 blocker 2). |
| 86 | +- CLI treats `-` before `csv` so `--retain-models -` clears (audit r1 blocker 3). |
| 87 | +- `providerCatalogFingerprint` includes `retainModels`. |
| 88 | +- Migration renames a retired id inside `retainModels`. |
| 89 | +- `bun x tsc --noEmit` clean, `bun run privacy:scan` clean, focused files: |
| 90 | + `tests/catalog-retain-models.test.ts`, `tests/codex-catalog.test.ts`, |
| 91 | + `tests/management-provider-validation.test.ts`, |
| 92 | + `tests/model-rename-migration.test.ts` (if present), provider-runtime CLI test. |
| 93 | + |
| 94 | +## Files |
| 95 | + |
| 96 | +- `src/codex/catalog/provider-fetch.ts` — configuredIds union (on top of #2860). |
| 97 | +- `src/config.ts` — schema + superRefine. |
| 98 | +- `src/server/management/provider-routes.ts` — PATCH + DTO. |
| 99 | +- `src/server/auth-cors.ts` — `providerManagementConfigError` validation + safe-config DTO key list (audit r1 blocker 1). |
| 100 | +- `src/cli/provider-runtime.ts` — `--retain-models`. |
| 101 | +- `src/providers/model-rename-migration.ts` — list entry. |
| 102 | +- `src/types/provider.ts` — already added by #2860 (doc comment adjusted for union). |
| 103 | +- `docs-site/src/content/docs/reference/configuration/providers.md`. |
| 104 | +- `tests/catalog-retain-models.test.ts` (extend), `tests/management-provider-validation.test.ts` (extend). |
| 105 | + |
| 106 | +## Closure |
| 107 | + |
| 108 | +PR targets `dev`, `Closes #1690`, description names #2860 as the carried |
| 109 | +source commit (`12e69c200`) and #2122 as design input. After landing: close |
| 110 | +#1690 with the landing SHA, close #2860 as landed-via-carry (author credited in |
| 111 | +the squash trailer), close #2122 as superseded with the reasoning above. |
0 commit comments