Pick a provider first, then a model

The picker was one flat list of every provider-account-model
combination — 30+ rows, the same models repeated once per account,
providers interleaved. Group it: the top level now shows one row per
provider (each account is already its own catalog entry, e.g.
codex/abk-labs vs codex/dirtroad, so no extra grouping key is needed),
selecting one descends into that provider's models, and Escape at the
model level steps back to the provider level instead of closing the
picker.

Recent and favorite picks stay flat at the top so the default model
is reachable without descending, same as before. The active model's
row (and its provider group, when the row itself is not already
surfaced via Recent) reads "(current)" so the pick is identifiable at
a glance. Both levels reuse the same scrolling list overlay the picker
already used, so a short terminal scrolls within the picker rather
than overflowing it.

Escape only stepped back for permissions/operator overlays before —
extended to model_picker so the provider level can be restored via the
same dismiss path, harmless no-op for a caller that sets no onCancel.

The description-zone fallback for a provider row shows its model count
so the zone is never blank before descending.

Author: TheGreatAxios

src/tui-opentui/overlays.ts

@@ -170,6 +170,8 @@ export type OpenModelPickerOpts = {
   readonly describe?: (itemId: string) => ItemDescription | null
   /** Bare-key claim on the focused row (e.g. `f` to toggle favorite). */
   readonly onAction?: (itemId: string, key: KeyEvent) => boolean
+  /** Per-open Esc/dismiss — the provider-first picker steps back to the provider level instead of closing outright. */
+  readonly onCancel?: () => void
 }
 
 export function openModelPickerOverlay(
@@ -186,5 +188,6 @@ export function openModelPickerOverlay(
     ...(opts?.onAccept !== undefined ? { onAccept: opts.onAccept } : {}),
     ...(opts?.describe !== undefined ? { describe: opts.describe } : {}),
     ...(opts?.onAction !== undefined ? { onAction: opts.onAction } : {}),
+    ...(opts?.onCancel !== undefined ? { onCancel: opts.onCancel } : {}),
   })
 }

src/tui-opentui/product-host.test.ts

@@ -6,13 +6,14 @@ import { EventEmitter } from "node:events"
 import { describe, expect, test } from "bun:test"
 import type { PermissionRequest } from "../permission/types.js"
 import { createHarness } from "./harness.js"
-import { acceptOverlaySelection } from "./shell.js"
+import { acceptOverlaySelection, closeInsetOverlay, moveOverlaySelection } from "./shell.js"
 import {
   mountProductHost,
   operatorResultFromSelection,
   permissionChoices,
   type ProductHostConfig,
 } from "./product-host.js"
+import { buildModelsFirstCatalog } from "./model-catalog.js"
 
 function makeFakeSessionPort(): {
   readonly sends: string[]
@@ -271,6 +272,162 @@ describe("mountProductHost", () => {
   })
 })
 
+describe("provider-first model picker", () => {
+  // Mirrors the bug-report shape: several providers, one (codex) with three
+  // accounts, plus a favorite so the top level has a reachable-without-descending pick.
+  const providers = {
+    "codex/abk-labs": { models: ["gpt-5.5", "gpt-5.6-sol"] },
+    "codex/dirtroad": { models: ["gpt-5.5", "gpt-5.6-sol"] },
+    "codex/fleur": { models: ["gpt-5.5", "gpt-5.6-sol"] },
+    "xai/thegreataxios": { models: ["grok-4.5"] },
+    "Z.AI": { models: ["glm-5", "glm-5-turbo", "glm-5.2"] },
+  }
+
+  async function mountPicker(overrides: Partial<ProductHostConfig> = {}) {
+    const harness = await createHarness({ width: 80, height: 24 })
+    const port = makeFakeSessionPort()
+    const catalog = buildModelsFirstCatalog({
+      providers,
+      favorites: [{ provider: "codex/abk-labs", model: "gpt-5.5" }],
+    })
+    const selected: string[] = []
+    const host = await mountProductHost({
+      title: "test-session",
+      eventEmitter: new EventEmitter(),
+      send: port.send,
+      interrupt: port.interrupt,
+      createRenderer: async () => harness.renderer,
+      models: catalog,
+      onModelSelect: (id) => selected.push(id),
+      ...overrides,
+    })
+    return { harness, host, selected }
+  }
+
+  test("top level lists providers (one row per account), not one row per model", async () => {
+    const { harness, host } = await mountPicker()
+    try {
+      host.openModels?.()
+      await harness.renderOnce()
+      const frame = harness.captureCharFrame()
+      // Each codex account is its own row; the account name appears once,
+      // not once per model it exposes.
+      expect(frame).toContain("codex/abk-labs")
+      expect(frame).toContain("codex/dirtroad")
+      expect(frame).toContain("codex/fleur")
+      expect(frame).toContain("xai/thegreataxios")
+      // The favorite is a leaf row, reachable without descending — it, not
+      // its provider group, carries the model name at the top level.
+      expect(frame).toContain("gpt-5.5")
+    } finally {
+      host.dispose()
+      harness.destroy()
+    }
+  })
+
+  test("selecting a provider descends into its models; Escape returns to the provider level", async () => {
+    const { harness, host } = await mountPicker()
+    try {
+      host.openModels?.()
+      await harness.renderOnce()
+
+      const items = host.shell.overlayItems
+      const xaiIndex = items.findIndex((label) => label.includes("xai/thegreataxios"))
+      expect(xaiIndex).toBeGreaterThanOrEqual(0)
+      moveOverlaySelection(host.shell, xaiIndex)
+      acceptOverlaySelection(host.shell)
+      await harness.renderOnce()
+
+      const modelFrame = harness.captureCharFrame()
+      expect(modelFrame).toContain("grok-4.5")
+      expect(modelFrame).not.toContain("codex/abk-labs")
+
+      closeInsetOverlay(host.shell)
+      await harness.renderOnce()
+      const backFrame = harness.captureCharFrame()
+      expect(backFrame).toContain("codex/abk-labs")
+      expect(host.shell.overlayList).not.toBeNull()
+    } finally {
+      host.dispose()
+      harness.destroy()
+    }
+  })
+
+  test("selecting a model at the model level applies the pick", async () => {
+    const { harness, host, selected } = await mountPicker()
+    try {
+      host.openModels?.()
+      await harness.renderOnce()
+      const items = host.shell.overlayItems
+      const xaiIndex = items.findIndex((label) => label.includes("xai/thegreataxios"))
+      moveOverlaySelection(host.shell, xaiIndex)
+      acceptOverlaySelection(host.shell)
+      await harness.renderOnce()
+
+      acceptOverlaySelection(host.shell)
+      expect(selected).toEqual(["xai/thegreataxios:grok-4.5"])
+    } finally {
+      host.dispose()
+      harness.destroy()
+    }
+  })
+
+  test("the current model's row reads \"(current)\" at a glance", async () => {
+    const harness = await createHarness({ width: 80, height: 24 })
+    const port = makeFakeSessionPort()
+    const catalog = buildModelsFirstCatalog({ providers, recent: [{ provider: "xai/thegreataxios", model: "grok-4.5" }] })
+    const host = await mountProductHost({
+      title: "test-session",
+      eventEmitter: new EventEmitter(),
+      send: port.send,
+      interrupt: port.interrupt,
+      createRenderer: async () => harness.renderer,
+      models: catalog,
+      onModelSelect: () => {},
+    })
+    try {
+      host.openModels?.()
+      await harness.renderOnce()
+      const frame = harness.captureCharFrame()
+      expect(frame).toContain("xai/thegreataxios / grok-4.5 (current)")
+    } finally {
+      host.dispose()
+      harness.destroy()
+    }
+  })
+
+  test("fits and scrolls within a short terminal instead of overflowing it", async () => {
+    const port = makeFakeSessionPort()
+    const harness = await createHarness({ width: 80, height: 10 })
+    try {
+      const catalog = buildModelsFirstCatalog({ providers })
+      const host = await mountProductHost({
+        title: "test-session",
+        eventEmitter: new EventEmitter(),
+        send: port.send,
+        interrupt: port.interrupt,
+        createRenderer: async () => harness.renderer,
+        models: catalog,
+        onModelSelect: () => {},
+      })
+      try {
+        host.openModels?.()
+        await harness.renderOnce()
+        const frame = harness.captureCharFrame()
+        // Five provider rows do not all fit a 10-row terminal alongside the
+        // overlay chrome; the picker renders without throwing and the frame
+        // stays within the terminal's own line count.
+        expect(frame.replace(/\n$/, "").split("\n").length).toBeLessThanOrEqual(10)
+        expect(host.shell.overlayList).not.toBeNull()
+      } finally {
+        host.dispose()
+      }
+    } finally {
+      harness.destroy()
+    }
+  })
+})
+
 describe("mount failure", () => {
   test("destroys the renderer when gate wiring throws", async () => {
     const harness = await createHarness({ width: 80, height: 24 })

src/tui-opentui/product-host.ts

@@ -58,6 +58,72 @@ import type { StreamRow } from "./stream.js"
 
 import type { PendingImageAttachment } from "../tui/image-attachments.js"
 
+const PROVIDER_GROUP_PREFIX = "providerGroup:"
+
+function providerGroupRowId(provider: string): string {
+  return `${PROVIDER_GROUP_PREFIX}${provider}`
+}
+
+function providerFromGroupRowId(id: string): string | null {
+  return id.startsWith(PROVIDER_GROUP_PREFIX) ? id.slice(PROVIDER_GROUP_PREFIX.length) : null
+}
+
+/** Provider (account) segment of a `provider:model` row id. */
+function providerOfRowId(id: string): string {
+  const i = id.indexOf(":")
+  return i === -1 ? id : id.slice(0, i)
+}
+
+/** Provider label segment of a `Provider Label / model` row label. */
+function providerLabelOfRow(label: string): string {
+  const i = label.indexOf(" / ")
+  return i === -1 ? label : label.slice(0, i)
+}
+
+type ModelGroup = {
+  readonly label: string
+  readonly rows: ProductHostModelOption[]
+}
+
+/**
+ * Split a flat, section-tagged models list into the provider-first picker's
+ * top level (recent/favorites/unconnected pass through flat; each distinct
+ * provider collapses into one group row, in first-seen order) plus the
+ * per-provider model rows reached by descending into a group. Rows with no
+ * `section` (a caller not using buildModelsFirstCatalog) pass through
+ * ungrouped, preserving today's single-level picker for that caller.
+ */
+function groupModelsForPicker(
+  models: readonly ProductHostModelOption[],
+): { readonly top: ProductHostModelOption[]; readonly groups: ReadonlyMap<string, ModelGroup> } {
+  const top: ProductHostModelOption[] = []
+  const groups = new Map<string, ModelGroup>()
+  for (const row of models) {
+    if (row.section !== "provider") {
+      top.push(row)
+      continue
+    }
+    const provider = providerOfRowId(row.id)
+    let group = groups.get(provider)
+    if (group === undefined) {
+      group = { label: providerLabelOfRow(row.label), rows: [] }
+      groups.set(provider, group)
+      top.push({ id: providerGroupRowId(provider), label: group.label, section: "provider" })
+    }
+    group.rows.push(row)
+  }
+  return { top, groups }
+}
+
+/** Suffix the row matching `activeId` (if any) so it reads as the current pick. */
+function annotateCurrent(
+  rows: readonly ProductHostModelOption[],
+  activeId: string | undefined,
+): ProductHostModelOption[] {
+  if (activeId === undefined) return [...rows]
+  return rows.map((r) => (r.id === activeId ? { ...r, label: `${r.label} (current)` } : r))
+}
+
 export type ProductHostSend = (
   text: string,
   attachments?: readonly PendingImageAttachment[],
@@ -69,9 +135,19 @@ export type ProductHostDeliver = (
   attachments?: readonly PendingImageAttachment[],
 ) => void
 
+/**
+ * `section` groups rows for the provider-first picker: "recent" and
+ * "favorites" stay flat at the top (already single models, reachable without
+ * descending); "provider" rows are grouped into one top-level entry per
+ * provider (or per account, since each configured provider entry is already
+ * account-scoped — `codex/abk-labs`, `codex/dirtroad`); "unconnected" stays
+ * flat as a "connect →" row. Omitted (from a caller not using
+ * buildModelsFirstCatalog) falls back to one flat list, unwrapped.
+ */
 export type ProductHostModelOption = {
   readonly id: string
   readonly label: string
+  readonly section?: "recent" | "favorites" | "provider" | "unconnected"
 }
 
 export type ProductHostConfig = {
@@ -433,36 +509,86 @@ export async function mountProductHost(
     const onSelect = config.onModelSelect
     const onConnect = config.onConnectProvider
     const onFavoriteToggle = config.onFavoriteToggle
-    openModels = (): void => {
+
+    // Provider rows have no catalog entry of their own to describe; fall back
+    // to a plain model count so the description zone is never blank.
+    const describe = (itemId: string): ItemDescription | null => {
+      const groupProvider = providerFromGroupRowId(itemId)
+      if (groupProvider !== null) {
+        const { groups } = groupModelsForPicker(currentModels)
+        const count = groups.get(groupProvider)?.rows.length ?? 0
+        return {
+          what: `${count} model${count === 1 ? "" : "s"} available.`,
+          impact: "Press Enter to see them.",
+          tone: "plain",
+        }
+      }
+      return currentDescribeModel?.(itemId) ?? null
+    }
+
+    const openLevel = (items: readonly ProductHostModelOption[], onCancel?: () => void): void => {
       openModelPickerOverlay(shell, {
-        items: currentModels.map((m) => m.label),
-        itemIds: currentModels.map((m) => m.id),
+        items: items.map((m) => m.label),
+        itemIds: items.map((m) => m.id),
         onAccept: (sel) => {
-          const id = sel.id ?? currentModels[sel.index]?.id
+          const id = sel.id ?? items[sel.index]?.id
           if (!id) return
           const providerName = id.startsWith("connect:") ? id.slice("connect:".length) : null
           if (providerName !== null) {
             onConnect?.(providerName)
             return
           }
+          const groupProvider = providerFromGroupRowId(id)
+          if (groupProvider !== null) {
+            const { groups } = groupModelsForPicker(currentModels)
+            const group = groups.get(groupProvider)
+            if (group !== undefined) {
+              openLevel(annotateCurrent(group.rows, activeModelId()), openModels)
+            }
+            return
+          }
           onSelect(id)
         },
-        ...(currentDescribeModel !== undefined ? { describe: currentDescribeModel } : {}),
+        describe,
         ...(onFavoriteToggle !== undefined
           ? {
               onAction: (itemId, key) => {
                 // Alt+F, never bare f — the palette filters as you type, so a
                 // bare letter narrows the list instead of toggling a favorite.
                 const name = typeof key.name === "string" ? key.name.toLowerCase() : ""
                 if (name !== "f" || key.ctrl || !(key.meta || key.option)) return false
-                if (itemId.startsWith("connect:")) return false
+                if (itemId.startsWith("connect:") || providerFromGroupRowId(itemId) !== null) return false
                 onFavoriteToggle(itemId)
                 return true
               },
             }
           : {}),
+        ...(onCancel !== undefined ? { onCancel } : {}),
       })
     }
+
+    // Recent's first row (if any) is the model just switched to — the closest
+    // thing to a live "current model" id without threading one through from
+    // the runner. Used only to mark that row "(current)" wherever it appears.
+    const activeModelId = (): string | undefined =>
+      currentModels.find((r) => r.section === "recent")?.id
+
+    openModels = (): void => {
+      const { top, groups } = groupModelsForPicker(currentModels)
+      const activeId = activeModelId()
+      // The active model's own row already reads "(current)" via annotateCurrent
+      // below; when it lives inside a provider group, mark the group row too
+      // so the pick is visible without descending into it.
+      const activeGroupId = [...groups.entries()].find(([, g]) =>
+        g.rows.some((r) => r.id === activeId),
+      )?.[0]
+      const withGroupMark = activeGroupId === undefined
+        ? top
+        : top.map((r) =>
+            r.id === providerGroupRowId(activeGroupId) ? { ...r, label: `${r.label} (current)` } : r,
+          )
+      openLevel(annotateCurrent(withGroupMark, activeId))
+    }
     ;(shell as AppShell & { __openModels?: () => void }).__openModels =
       openModels
   }