Plan: Known Model autocomplete and frontend-only defaults for Chat Model Admin

Goal

Improve the admin Add Model onboarding flow by replacing the blank Model Identifier experience with provider-scoped Known Model discovery suggestions for native OpenAI and Anthropic providers. Selecting a Known Model, or typing an exact canonical Known Model identifier and blurring the field, should prefill safe objective model metadata in the existing form without changing backend APIs, database schema, or runtime behavior.

The primary UX goal is discovery for admins who do not know exact provider model identifiers or metadata. Typing convenience is a secondary benefit.

Evidence and current code facts

• The current Model Identifier field is a plain free-text Input in site/src/pages/AgentsPage/components/ChatModelAdminPanel/ModelForm.tsx. It submits as model and is only validated as a non-empty string.
• The provider selector is disabled in edit and duplicate modes. In add mode, ModelsSection.tsx keys the form by provider, so provider changes remount ModelForm.
• The shared site/src/components/Autocomplete/Autocomplete.tsx primitive already supports free-text input with suggestions and is the right UI primitive for this feature.
• modelConfigFormLogic.ts owns form initialization via buildInitialModelFormValues(...), and modelConfigFormLogic.test.ts already covers this pure logic area.
• No frontend or backend Known Model catalog exists today.
• The database has a non-unique (provider, model) index, not a uniqueness constraint. Multiple Model Configs can share the same Provider and Model Identifier, so suggestions must not hide already-configured models.
• models.dev/api.json has provider-keyed model metadata with canonical IDs, names, limits, pricing, release dates, and last_updated values. The Phase 1 catalog should copy a curated subset into TypeScript records, not fetch at runtime.

Domain language

Use these terms consistently in code, tests, docs, and review discussion:

• Provider: configured external AI service such as native openai or anthropic.
• Model Config: persisted admin-defined config row used by Coder chat runtime.
• Model Identifier: exact provider API string submitted as model, such as gpt-5.5.
• Known Model: curated frontend catalog entry with advisory metadata for one canonical Model Identifier.
• Model Catalog: checked-in frontend-only list of Known Models.
• Off-catalog Model Identifier: user-entered Model Identifier that does not match any Known Model and remains valid.
• Default application: copying advisory Known Model metadata into a draft add-mode Model Config form.

Resolved design decisions

UX scope

• Implement this on the Add Model page/form only.
• Do not add provider success popups, provider-side calls to action, or new deep-link behavior in this pass.
• Use Autocomplete only when all are true:
  • form mode is add;
  • selected Provider is native openai or native anthropic;
  • that Provider has Known Models.
• Edit mode, duplicate mode, and unsupported providers keep the existing free-text input behavior.

Suggestion behavior

• Suggestions open on focus only when the Model Identifier field is empty.
• Once the field has text, suggestions open while typing or interacting with the autocomplete.
• Empty unsupported-provider catalogs degrade silently to the existing plain input behavior.
• When a supported provider has zero matches for a non-empty query, show a non-blocking empty state such as: No matching known models. You can still use this identifier.
• Suggestion rows show:
  • display name;
  • canonical Model Identifier;
  • context-window badge, for example 1.05M context.
• Format context badges with a deterministic helper covered by tests, for example 200K context, 400K context, and 1.05M context.
• Do not show pricing, recommendations, capability tags, or large-context caveats in suggestion rows.
• Keep catalog display order as product ordering. Do not show a visible Recommended badge.

Canonical IDs and aliases

• Selecting a Known Model always writes its canonical Model Identifier into the form.
• Use non-date latest aliases as canonical onboarding IDs when the provider exposes them, such as gpt-5.5 or claude-sonnet-4-6.
• Date-pinned IDs may be aliases for search, but selecting a Known Model writes the non-date canonical ID.
• Typing aliases filters suggestions but does not rewrite the field and does not apply defaults by itself.
• Search over canonical ID, display name, and explicit aliases.
• Search is case-insensitive and normalizes spaces, hyphens, underscores, and dots before substring matching.
• Aliases are objective name or identifier variants only. Do not include editorial intent tags such as best, cheap, fast, coding, or reasoning.
• Do not implement typo-tolerant fuzzy search in Phase 1.

Default application rules

• Default application only runs in add mode.
• Explicit Known Model selection applies defaults immediately.
• Exact typed or pasted canonical Model Identifier applies defaults on blur, not on every keystroke. This avoids prematurely applying gpt-5.5 while the admin is typing gpt-5.5-pro.
• Defaults fill only target fields whose current values still equal this form session's initial values.
• Do not use Formik touched state as the source of truth for safety.
• Do not implement field-level provenance tracking in Phase 1.
• Capture an immutable initialValuesRef at ModelForm mount/remount and compare against that snapshot for safe default application. Do not compare against a live Formik reference that can drift.
• Do not reapply repeatedly for the same provider/model pair in a single form session.
• The defaulting helper must return both the next values and the list of applied form paths:

interface ApplyKnownModelDefaultsResult {
  values: ModelFormValues;
  appliedFields: readonly string[];
}

• Treat Model Identifier canonicalization separately from metadata default application. appliedFields tracks populated metadata/form paths only, not the model field change caused by selecting a Known Model.
• Show an inline note near Model Identifier only when appliedFields.length > 0, such as: Defaults applied from GPT-5.5. Review and adjust before saving.
• Do not show a note for off-catalog identifiers, no-op Known Model selections, or selections that only canonicalize the Model Identifier.

Initial Model Catalog

Use curated TypeScript records with source metadata copied from models.dev. Do not check in the full models.dev/api.json snapshot and do not add a generator in Phase 1. Add a file-level comment that array order controls suggestion order so future cleanup does not accidentally change onboarding UX.

Initial native OpenAI entries, in display order:

1. gpt-5.5
2. gpt-5.5-pro
3. gpt-5.4
4. gpt-5.4-mini
5. gpt-5.4-nano
6. gpt-5.3-codex

Initial native Anthropic entries, in display order:

1. claude-opus-4-7
2. claude-opus-4-6
3. claude-sonnet-4-6
4. claude-haiku-4-5
5. claude-sonnet-4-5

Do not include GPT-4.x, pre-5.3 GPT models, or Claude models older than 4.5 in this onboarding catalog unless product intentionally expands scope.

Each Known Model record should include:

• provider;
• canonical Model Identifier;
• display name;
• aliases;
• source metadata, including sourceName: "models.dev", sourceRetrievedAt, and the model record's last_updated value;
• contextLimit from limit.context;
• maxOutputTokens from limit.output;
• flat base pricing from supported cost.* fields.

Field mapping

• models.dev.limit.context maps to contextLimit.
• models.dev.limit.output maps to the selected provider's exact max-output-tokens field when one exists, otherwise to generic config.maxOutputTokens.
• Never fill both generic and provider-specific output-token fields for the same Known Model.
• Ignore models.dev.limit.input unless the current form schema already exposes an exact matching field.
• Map only flat base pricing fields that the existing form can persist:
  • cost.input;
  • cost.output;
  • cost.cache_read;
  • cost.cache_write.
• Reuse pricingFields.ts or the existing pricing field descriptors instead of hard-coding cost form paths.
• If cache_read or cache_write is absent from a models.dev entry, leave the corresponding field at its initial value and do not include it in appliedFields.
• Ignore tiered pricing such as context_over_200k in Phase 1. Add a code comment in the adapter explaining that Coder currently persists flat pricing only.
• Do not show a UI caveat for tiered pricing in Phase 1.
• Do not set compressionThreshold from Known Models.
• Do not prefill provider-specific reasoning or thinking fields in Phase 1, including:
  • OpenAI reasoningEffort and reasoningSummary;
  • Anthropic sendReasoning, effort, and thinking.budgetTokens.

Proposed file structure

Use knownModels/ rather than modelDefaults/ because the data powers both discovery and default application.

New files:

• site/src/pages/AgentsPage/components/ChatModelAdminPanel/knownModels/types.ts
• site/src/pages/AgentsPage/components/ChatModelAdminPanel/knownModels/openai.ts
• site/src/pages/AgentsPage/components/ChatModelAdminPanel/knownModels/anthropic.ts
• site/src/pages/AgentsPage/components/ChatModelAdminPanel/knownModels/index.ts
• site/src/pages/AgentsPage/components/ChatModelAdminPanel/knownModels/applyKnownModelDefaults.ts
• site/src/pages/AgentsPage/components/ChatModelAdminPanel/ModelIdentifierField.tsx

Existing files to modify:

• site/src/pages/AgentsPage/components/ChatModelAdminPanel/ModelForm.tsx
• site/src/pages/AgentsPage/components/ChatModelAdminPanel/modelConfigFormLogic.ts
• site/src/pages/AgentsPage/components/ChatModelAdminPanel/modelConfigFormLogic.test.ts
• site/src/pages/AgentsPage/components/ChatModelAdminPanel/ChatModelAdminPanel.stories.tsx

Documentation artifacts to keep in sync if implementing from a clean workspace:

• site/src/pages/AgentsPage/components/ChatModelAdminPanel/CONTEXT.md
• site/src/pages/AgentsPage/components/ChatModelAdminPanel/docs/adr/0001-frontend-known-model-catalog.md

Implementation plan

Phase 1: Red, define pure behavior first

1. Add tests in modelConfigFormLogic.test.ts or a colocated knownModels test file for:
   • provider-scoped lookup;
   • normalized alias search;
   • canonicalization on selection;
   • unknown model leaves values unchanged;
   • exact canonical ID lookup;
   • safe initial-value patching;
   • appliedFields output that excludes Model Identifier canonicalization;
   • tiered pricing ignored;
   • missing cache pricing fields left at initial values;
   • compression threshold not populated;
   • reasoning/thinking fields not populated;
   • output-token mapping prefers provider-specific exact field and never fills both;
   • context badge formatting.
2. Add lifecycle tests where feasible:
   • provider change in add mode remounts the form and resets initialValuesRef, lastAppliedProviderModelRef, and inline default-feedback state.
3. Add edge-case tests for event and reapplication semantics:
   • selecting gpt-5.5 then blurring does not apply defaults a second time;
   • typing gpt-5.5-pro then blurring applies only pro defaults, never prefix gpt-5.5 defaults;
   • selecting one Known Model, then another, does not overwrite fields already populated by the first selection because they no longer match initial values;
   • typing an alias then blurring does not canonicalize or apply defaults;
   • an Off-catalog value for a supported provider remains valid and preserves existing required-field validation behavior.
4. Add tests for the initial OpenAI and Anthropic catalog entries to ensure IDs, source metadata, and display order remain intentional.

Quality gate: targeted unit tests fail for missing implementation.

Phase 2: Green, add Known Model catalog and pure helpers

1. Add knownModels/types.ts with readonly types for catalog records and source metadata.
2. Add knownModels/openai.ts and knownModels/anthropic.ts with the initial catalog entries and file-level refresh comments.
3. Add lookup and search helpers in knownModels/index.ts.
4. Add applyKnownModelDefaults(...) as a pure helper that accepts:
   • current form values;
   • initial form values;
   • selected provider;
   • Known Model;
   • provider field mapping helpers if needed.
5. Ensure assertions or explicit guards make impossible cases fail fast during tests, for example missing provider, missing canonical ID, or invalid source metadata.

Quality gate: targeted unit tests pass.

Phase 3: Wire Model Identifier autocomplete UX

Autocomplete integration constraints:

• Control the shared Autocomplete with inputValue for the free-text Model Identifier string and value: KnownModel | null for selected suggestions.
• Pass pre-filtered Known Model options to Autocomplete; do not rely on cmdk internal filtering once inputValue is controlled.
• Clear the selected KnownModel | null value whenever the admin types arbitrary text that no longer corresponds to the selected Known Model.
• Guard selection and blur event ordering so selecting a row does not cause the input blur handler to apply defaults a second time.
• Run exact-match blur behavior only when focus leaves the whole field/combobox, not when focus moves into the suggestion list.
• Store the last-applied provider/model pair in form-local state or a ref so add-mode provider remounts reset it naturally.
• Preserve the existing field contract: label, tooltip/help text, name, validation error rendering, aria-invalid, aria-describedby, disabled state, Formik blur/touched behavior, and submitted request shape.

1. Add ModelIdentifierField.tsx.
2. Preserve existing plain Input markup for edit mode, duplicate mode, and unsupported providers.
3. For add-mode supported providers, render Autocomplete with:
   • controlled free-text value tied to Formik's model field;
   • custom row rendering with display name, canonical ID, and context badge;
   • open-on-empty-focus behavior;
   • non-blocking no-match copy for non-empty supported-provider queries;
   • keyboard support inherited from Autocomplete.
4. On Known Model selection:
   • set the form's model field to the canonical ID;
   • apply defaults immediately;
   • show inline feedback only if fields changed.
5. On blur:
   • if the final field value exactly equals a Known Model canonical ID, apply defaults safely;
   • do not auto-apply aliases on blur.
6. Track the last applied provider/model pair in the form session to avoid repeated reapplication.

Quality gate: Storybook stories compile and the main interaction paths work locally.

Phase 4: Storybook and UX coverage

Add or extend ChatModelAdminPanel.stories.tsx with three user-visible flows:

1. OpenAI happy path:
   • open Add Model for OpenAI;
   • focus empty Model Identifier;
   • suggestions appear;
   • select GPT-5.5;
   • assert gpt-5.5 is in the input;
   • assert inline defaults note appears;
   • assert visible context limit and max output fields populate;
   • expand the pricing section before asserting pricing fields, or keep detailed pricing assertions in unit tests if the Storybook UI would become brittle.
2. Anthropic happy path:
   • open Add Model for Anthropic;
   • select Claude Opus 4.7;
   • assert canonical ID, visible context limit, and output field populate;
   • expand the pricing section before asserting pricing fields, or keep detailed pricing assertions in unit tests if the Storybook UI would become brittle;
   • assert Anthropic reasoning/thinking fields remain blank.
3. Unsupported provider fallback:
   • open Add Model for Azure or openai-compat;
   • assert Model Identifier behaves as plain free text and no suggestion popover appears.

If practical, include one keyboard selection path in Storybook or manual dogfooding:

• tab/focus Model Identifier;
• arrow to a suggestion;
• press Enter;
• verify canonicalization and defaults.

Quality gate: Storybook interaction tests pass for touched stories.

Phase 5: Refactor and documentation pass

1. Keep catalog data isolated from UI rendering code.
2. Keep provider field mapping in one helper so future Google, Bedrock, OpenRouter, or Azure support does not require editing defaulting logic everywhere.
3. Ensure comments explain why tiered pricing and reasoning defaults are excluded.
4. Update CONTEXT.md and ADR if implementation changes any design decision captured there.
5. Run formatting and linting for touched frontend files.

Quality gate: no broad refactors beyond this feature's files.

Validation commands

Use the repo's existing frontend validation commands, scoped where possible:

• pnpm -C site test <targeted ChatModelAdminPanel pattern>
• pnpm -C site test <targeted modelConfigFormLogic pattern>
• pnpm -C site test:storybook
• pnpm -C site lint:types
• pnpm -C site check

If command names differ in this workspace, inspect site/package.json and use the closest existing targeted commands. Do not claim success until the actual commands run and pass.

Dogfooding plan

Primary dogfood path is Storybook because this is a form-level UI improvement using mocked admin data.

1. Run Storybook for the Chat Model Admin Panel.
2. Record a short video showing:
   • OpenAI Add Model, focus empty Model Identifier, suggestions appear, select GPT-5.5, defaults note appears, fields populate;
   • Anthropic Add Model, select Claude Opus 4.7, fields populate, reasoning/thinking fields remain blank;
   • unsupported provider Add Model, Model Identifier stays free text with no suggestions.
3. Capture screenshots for the final state of each flow and attach them for review.
4. If implementation touches routing, ModelsSection URL state, or provider pages, also run the local UI and record /agents/settings/models?newModel=openai exercising the same OpenAI flow.

Acceptance criteria

• Add-mode native OpenAI and Anthropic Model Identifier fields provide discovery suggestions from the curated Known Model catalog.
• Suggestions appear on empty focus and filter as the admin types.
• Unsupported providers, edit mode, and duplicate mode preserve the current plain input behavior.
• Selecting a Known Model canonicalizes the field and safely applies objective defaults.
• Exact typed/pasted canonical IDs apply defaults on blur.
• Off-catalog Model Identifiers remain valid and non-blocking.
• Display name, context limit, output-token field, and flat pricing fill only when target fields still match initial values.
• Compression threshold, tiered pricing, and provider-specific reasoning/thinking fields are not populated by Phase 1 defaults.
• Inline feedback appears only when default application changed at least one field.
• Unit tests, Storybook coverage, typecheck, formatting, and lint/check commands pass.
• Dogfooding includes screenshots and video recordings.

Risks and mitigations

• Catalog staleness: models change frequently. Mitigate with source metadata and clear file-level refresh comments.
• Provider namespace mistakes: Azure, Bedrock, OpenRouter, and openai-compat use different identifier semantics. Mitigate by supporting only native OpenAI and Anthropic in Phase 1.
• Auto-fill surprise: defaults can feel magical. Mitigate with selection-first UX, blur-only exact-match behavior, initial-value safety checks, and inline feedback.
• Pricing inaccuracy for tiered models: current form persists flat prices only. Mitigate by mapping base flat prices only and documenting tiered pricing as out of scope.
• Reasoning option overreach: generic source metadata does not map cleanly to provider-specific controls. Mitigate by leaving reasoning/thinking fields blank in Phase 1.
• Overbroad UI changes: replacing an input can affect accessibility and keyboard users. Mitigate by using the shared Autocomplete primitive, preserving plain Input fallback, and dogfooding keyboard selection.