UX: Redesign model selector to scale with large model catalogs

[heiwen]

Context

The current ModelSelector in the Model Configuration page renders all available models as a flat <Select> list. As hebo-gateway model presets grow, this becomes unusable — no search, no grouping, no filtering.

Each model has the following attributes available for grouping/filtering: modality (text, embedding, …), free, requiresByok, and providers (provider family slugs).

---

Options

A — Grouped Select with section headers

Add visual section headers to the existing <Select>, grouping by modality or provider family.

• Pros: minimal change, no new dependencies
• Cons: no search; still breaks beyond ~30–40 items; native select rendering limits label customization

B — Searchable Combobox (recommended)

Replace <Select> with a Command-palette-style combobox (popover + search input + grouped list). shadcn ships this pattern out of the box.

• Pros: scales to any number of models; fits existing form field layout with no structural changes; zero UX paradigm shift
• Cons: slightly more implementation work than A

Sketch:

[ Search models...           ▼ ]
────────────────────────────────
 Text Generation
   ○ claude-4-opus         [BYOK]
   ○ gpt-4o            [Free Tier]
 Embeddings
   ○ text-embedding-3      [BYOK]

C — Two-step selector: provider → model

First pick a provider family, then pick a model within it.

• Pros: keeps each individual list small
• Cons: extra click; couples the selection UX to provider as a first-class concept; awkward when a model supports multiple providers

D — Model picker dialog / sheet

Full-screen modal with search, filter chips (by modality, tier), and a grid or grouped list layout. Similar to a font picker.

• Pros: best experience for very large catalogs (50+ models); room for richer metadata display
• Cons: most engineering work; introduces context-switching for what is currently an inline form field

---

Recommendation

Option B. It's a direct swap of one component (<Select> → <Combobox>) with grouping by modality as the primary key. All existing form wiring, badges, and field layout remain unchanged. Can be extended toward D later if the catalog grows further.

---

Acceptance criteria

• Model type field in the Model Configuration form uses a searchable combobox
• Models are grouped by modality
• Free Tier / BYOK / Embeddings badges are preserved
• Keyboard navigation and form submission work as before
• Empty/error state (couldn't load models) is preserved

[heiwen]

@claude where can we find some inspiration for this?

[hebo-agent]

Claude finished @heiwen's task in 1m 38s —— View job

---

Inspiration sources for the model selector redesign

• Gather context on current implementation
• Research inspiration sources
• Compile response

Great news — the codebase already has most of the building blocks in place. Here's where to look for inspiration:

---

Direct references (Option B — Combobox)

Source	Why it's relevant
shadcn/ui Combobox	The canonical Popover + Command pattern. The "Combobox" and "Popover" examples show exactly the grouped, searchable select the issue describes. Your repo already has cmdk-base installed and a full Command component in packages/aikit-ui/src/_shadcn/ui/command.tsx.
Vercel AI SDK model selector	Real-world model picker with search, grouping by provider, and badges — very close to the sketch in the issue.
OpenRouter model picker	Large model catalog with search + filter chips (modality, pricing tier). Good reference for how to scale beyond 50+ models (Option D territory if you ever need it).
Hugging Face model hub filters	Filter-heavy catalog with modality/task grouping. More of an Option D reference, but the tag/badge system is worth studying.

In-repo building blocks already available

You're closer than you might think:

• Command component — packages/aikit-ui/src/_shadcn/ui/command.tsx — full cmdk-base wrapper with CommandInput, CommandGroup, CommandItem, CommandEmpty, etc.
• Popover component — packages/shared-ui/src/_shadcn/ui/popover.tsx — @base-ui/react/popover wrapper ready to host the command list.
• InputGroup — packages/aikit-ui/src/_shadcn/ui/input-group.tsx — already has a data-[slot=combobox-content] styling hook (line 17), suggesting this pattern was anticipated.
• Badge — already used in ModelSelector.tsx for Free Tier / BYOK / Embeddings labels.

Pattern sketch using existing components

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" role="combobox">
      {selectedModel ?? "Select model..."}
    </Button>
  </PopoverTrigger>
  <PopoverContent>
    <Command>
      <CommandInput />
      <CommandList>
        <CommandEmpty>No models found.</CommandEmpty>
        <CommandGroup heading="Text Generation">
          <CommandItem>claude-4-opus <Badge>BYOK</Badge></CommandItem>
          <CommandItem>gpt-4o <Badge>Free Tier</Badge></CommandItem>
        </CommandGroup>
        <CommandGroup heading="Embeddings">
          <CommandItem>text-embedding-3 <Badge>BYOK</Badge></CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  </PopoverContent>
</Popover>

Other UIs worth a glance

• Linear's label/assignee pickers — command palette combobox with grouping, keyboard nav, and inline badges. Polished UX for the exact same pattern.
• Raycast's extension store search — grouped command list with metadata chips; great keyboard-first design.
• GitHub's branch/tag switcher — Popover + search + grouped list, very similar interaction model.

---

The shadcn combobox docs are the most direct starting point since the primitives are already wired up in the repo. The main implementation work is composing Popover + Command into a ModelCombobox, grouping the model entries by modality, and preserving the existing badge rendering and form integration from ModelSelector.tsx.

[heiwen]

OpenRouter Model Picker

T3 Chat Model Picker

[heiwen]

OpenCode

[heiwen]

@claude I think we need a combobox grouped by provider, similar to opencode and openrouter. can you plan that out for me?

[hebo-agent]

Claude finished @heiwen's task in 3m 21s —— View job

---

Planning: Provider-grouped model combobox

• Gather context on current implementation
• Review inspiration images (OpenRouter, T3 Chat, OpenCode)
• Analyze existing component primitives
• Write implementation plan

---

Implementation Plan

Here's the full plan for replacing the ModelSelector <Select> with a provider-grouped searchable combobox, inspired by OpenCode and OpenRouter.

---

1. Add owner to the Models type

The model IDs already encode the provider as a prefix (anthropic/claude-sonnet-4.6, openai/gpt-oss-120b), and the API returns owned_by. We need to surface this for grouping.

apps/console/app/lib/shell.ts — add owner: string to the Models value type:

 export type Models = Record<
   string,
   {
     name: string;
+    owner: string;
     modality: string;
     providers: readonly string[];
     free: boolean;
     requiresByok: boolean;
   }
 >;

apps/console/app/routes/_shell/route.tsx — map owned_by from the API response (line ~54):

 {
   name: m.name ?? "n/a",
+  owner: m.owned_by ?? m.id.split("/")[0] ?? "unknown",
   modality: m.architecture?.output_modalities?.[0] ?? "n/a",
   ...
 }

---

2. Create ModelCombobox component

New file: apps/console/app/components/ui/model-combobox.tsx

Compose the existing Command (from @hebo/aikit-ui) + Popover (from @hebo/shared-ui) primitives into a form-compatible combobox. This is the core of the change.

Structure:

┌─────────────────────────────────────┐
│ ▸ Claude Sonnet 4.6           [▼]  │  ← PopoverTrigger (Button)
├─────────────────────────────────────┤
│ 🔍 Search models...                │  ← CommandInput
├─────────────────────────────────────┤
│ Anthropic                           │  ← CommandGroup heading
│   Claude Sonnet 4.6        [BYOK]  │  ← CommandItem
│   Claude Haiku 4.5         [BYOK]  │
│ OpenAI                              │
│   GPT OSS 120B         [Free Tier] │
│ Amazon                              │
│   Nova 2 Embeddings   [Embeddings] │
│ Voyage                              │
│   Voyage 3.5               [BYOK]  │
└─────────────────────────────────────┘

Props (preserve the existing contract, swap Select items for Models):

type ModelComboboxProps = {
  models: Models | undefined;
  value?: string;               // controlled value (model ID)
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  name?: string;                // hidden input name for Conform
  disabled?: boolean;
  placeholder?: string;
};

Key implementation details:

• Grouping logic: Extract unique owner values from models, title-case them (e.g. anthropic → Anthropic), and render each as a CommandGroup with a heading prop.
• Search: cmdk handles fuzzy filtering out of the box via CommandInput. Model name and owner are both searchable by setting keywords on each CommandItem.
• Badges: Preserve existing badge rendering — Free Tier (green), BYOK (amber), Embeddings (blue) — inside each CommandItem.
• Form integration: Render a hidden <input name={name} value={selectedId} /> so Conform picks up the value without any adapter changes.
• Empty/error state: CommandEmpty shows "No models found." when search yields nothing. When models is undefined or empty, disable the trigger and show "Error: Couldn't load models" placeholder.
• Selected state: cmdk supports data-checked — the existing CommandItem already renders a CheckIcon on data-[checked=true].
• Popover width: Match trigger width using style={{ width: "var(--radix-popover-trigger-width)" }} or the Base UI equivalent.

Skeleton:

import { useState } from "react";
import { ChevronsUpDown } from "lucide-react";

import { Badge } from "@hebo/shared-ui/components/Badge";
import { Button } from "@hebo/shared-ui/components/Button";
import { Popover, PopoverContent, PopoverTrigger } from "@hebo/shared-ui/components/Popover";
import {
  Command, CommandEmpty, CommandGroup,
  CommandInput, CommandItem, CommandList,
} from "@hebo/aikit-ui/components/Command";

import type { Models } from "~console/lib/shell";

function groupByOwner(models: Models) {
  const groups: Record<string, Array<{ id: string; /* ... */ }>> = {};
  for (const [id, m] of Object.entries(models)) {
    (groups[m.owner] ??= []).push({ id, ...m });
  }
  return Object.entries(groups).sort(([a], [b]) => a.localeCompare(b));
}

function ModelCombobox({ models, value, onValueChange, name, ... }: ModelComboboxProps) {
  const [open, setOpen] = useState(false);
  const selected = value && models?.[value];
  const groups = groupByOwner(models ?? {});

  return (
    <>
      {name && <input type="hidden" name={name} value={value ?? ""} />}
      <Popover open={open} onOpenChange={setOpen}>
        <PopoverTrigger asChild>
          <Button variant="outline" role="combobox" aria-expanded={open}>
            {selected ? selected.name : placeholder}
            <ChevronsUpDown className="ml-auto opacity-50" />
          </Button>
        </PopoverTrigger>
        <PopoverContent>
          <Command>
            <CommandInput />
            <CommandList>
              <CommandEmpty>No models found.</CommandEmpty>
              {groups.map(([owner, items]) => (
                <CommandGroup key={owner} heading={titleCase(owner)}>
                  {items.map((m) => (
                    <CommandItem
                      key={m.id}
                      value={m.id}
                      keywords={[m.name, owner]}
                      onSelect={() => { onValueChange?.(m.id); setOpen(false); }}
                    >
                      {m.name}
                      {/* badges */}
                    </CommandItem>
                  ))}
                </CommandGroup>
              ))}
            </CommandList>
          </Command>
        </PopoverContent>
      </Popover>
    </>
  );
}

---

3. Replace ModelSelector usages

There are two consumers to update:

Consumer	File	Notes
Agent Create form	apps/console/app/routes/_shell.agent.create/form.tsx (line ~83)	Single model picker, sets defaultModel
Models Config form	apps/console/app/routes/_shell.agent.$agentSlug.branch.$branchSlug.models/form.tsx (line ~226)	Multiple model pickers in a field list

Both currently use <ModelSelector> which wraps <Select>. The swap is:

- <ModelSelector models={models} {...getSelectProps(fields.type)} />
+ <ModelCombobox models={models} {...getSelectProps(fields.type)} />

The hidden <input> inside ModelCombobox ensures Conform integration works without changes to schemas or actions.

---

4. Update mock data (optional but helpful)

apps/console/app/mocks/routes/models.ts — add a few more models to stress-test grouping:

Currently 5 models across 4 owners (openai, anthropic, amazon, voyage). Consider adding 2–3 more (e.g., google/gemini-2.5-pro, mistral/mistral-large) to validate the grouped UI during development.

---

5. Keyboard navigation & accessibility

cmdk provides this out of the box:

• Arrow keys navigate items across groups
• Enter selects the focused item
• Escape closes the popover
• Type-ahead filters the list

Verify that:

• Focus returns to the trigger button after selection
• The hidden input updates before form submission
• Screen readers announce the group headings

---

6. Delete old ModelSelector

Once both consumers are migrated, delete:

• apps/console/app/components/ui/ModelSelector.tsx

---

File change summary

Action	File
Edit	apps/console/app/lib/shell.ts — add owner field
Edit	apps/console/app/routes/_shell/route.tsx — map owned_by
Create	apps/console/app/components/ui/model-combobox.tsx — new combobox
Edit	apps/console/app/routes/_shell.agent.create/form.tsx — swap selector
Edit	apps/console/app/routes/_shell.agent.$agentSlug.branch.$branchSlug.models/form.tsx — swap selector
Delete	apps/console/app/components/ui/ModelSelector.tsx
Edit (optional)	apps/console/app/mocks/routes/models.ts — add test models

Open questions

1. Owner display names — Should we title-case the raw owned_by slug (e.g., anthropic → Anthropic), or should the API return a display name? Title-casing works for now but may look odd for multi-word owners.
2. Sort order within groups — Alphabetical by model name, or free-tier first (current behavior in agent create)?
3. Popover component source — The Command component lives in @hebo/aikit-ui but Popover lives in @hebo/shared-ui. The combobox composes both. Should ModelCombobox live in the console app (current plan) or be promoted to a shared package?

---

View job

[heiwen]

@claude a few refinements:
1/ instead of owner let's call it lab, we can start with title-casing (existing labelize function)
2/ sort order should be free tier first, then alphabetical
3/ we can use ShadCN / BaseUI Grouped Comboxbox
https://ui.shadcn.com/docs/components/base/combobox
https://base-ui.com/react/components/combobox

[hebo-agent]

Claude finished @heiwen's task in 8m 46s —— View job • claude-issue-307-20260422-0314 • Create PR ➔

---

Implementing provider-grouped model combobox with refinements

• Gather context on current implementation
• Read CLAUDE.md and AGENTS.md for repo guidelines
• Add lab field to Models type and shell route
• Create ModelCombobox component (ShadCN/BaseUI combobox, grouped by lab)
• Replace ModelSelector usages in both consumer forms
• Delete old ModelSelector component
• Update mock data with additional models for testing
• Verify build passes (build, lint, tests all green)
• Commit and push

Summary

Replaced the flat <Select> model picker with a searchable Base UI combobox grouped by provider lab, incorporating all three refinements:

1. lab instead of owner — added lab field to the Models type, mapped from API owned_by, displayed via existing labelize() function
2. Sort order: free tier first, then alphabetical — within each provider group, free tier models sort to the top
3. ShadCN / Base UI Combobox — added the shadcn combobox primitive (from @base-ui/react) to shared-ui, composed into a ModelCombobox with provider grouping, search, and badge preservation

Files changed

Action	File
Edit	apps/console/app/lib/shell.ts — add lab field to Models type
Edit	apps/console/app/routes/_shell/route.tsx — map owned_by → lab
Create	packages/shared-ui/src/_shadcn/ui/combobox.tsx — Base UI combobox primitive
Create	packages/shared-ui/src/_shadcn/ui/input-group.tsx — input-group dependency
Create	packages/shared-ui/src/components/Combobox.tsx — public re-export
Create	apps/console/app/components/ui/model-combobox.tsx — ModelCombobox component
Edit	apps/console/app/routes/_shell.agent.create/form.tsx — swap to combobox
Edit	apps/console/app/routes/_shell.agent.$agentSlug.branch.$branchSlug.models/form.tsx — swap to combobox
Delete	apps/console/app/components/ui/ModelSelector.tsx
Edit	apps/console/app/mocks/routes/models.ts — add Google, Mistral, OpenAI GPT-4o Mini

|