zjcode 0.0.1__py3-none-any.whl

deepagents_code/tui/widgets/model_selector.py

@@ -0,0 +1,2343 @@
+"""Interactive model selector screen for `/model` command."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple
+
+from textual.binding import Binding, BindingType
+from textual.containers import Container, Vertical, VerticalScroll
+from textual.content import Content
+from textual.css.query import NoMatches
+from textual.events import (
+    Click,  # noqa: TC002 - needed at runtime for Textual event dispatch
+)
+from textual.fuzzy import Matcher
+from textual.message import Message
+from textual.screen import ModalScreen
+from textual.widgets import Button, Input, Static
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from textual.app import ComposeResult
+
+from deepagents_code import theme
+from deepagents_code.auth_display import format_auth_indicator
+from deepagents_code.config import Glyphs, get_glyphs, is_ascii_mode
+from deepagents_code.model_config import (
+    CODEX_PROVIDER,
+    ModelConfig,
+    ModelProfileEntry,
+    ModelSpec,
+    ProviderAuthState,
+    ProviderAuthStatus,
+    clear_default_model,
+    get_available_models,
+    get_credential_env_var,
+    get_model_profiles,
+    get_provider_auth_status,
+    load_recent_models,
+    save_default_model,
+)
+
+logger = logging.getLogger(__name__)
+
+_MODEL_LIST_MAX_HEIGHT = 16
+"""Upper bound (in cells) for the model selector list.
+
+Keep in sync with the `max-height: 16` in the `.model-list` CSS below; Textual
+CSS cannot reference Python constants, so the static cap and the runtime
+`_fit_model_list` clamp must agree.
+"""
+
+_MODEL_LIST_MIN_HEIGHT = 1
+"""Floor (in cells) so the model selector list never collapses to zero."""
+
+_MAX_MODEL_ID_LEN = 255
+"""Maximum length allowed for a custom provider's default model ID."""
+
+_RECENT_SECTION_LABEL = "Recent"
+"""Header label for the MRU pseudo-provider section pinned at the top of `/model`.
+
+Recent picks are surfaced regardless of the recommended-only toggle —
+they're a personal signal that outweighs curation — and de-duplicated
+from the per-provider sections below.
+"""
+
+
+_RECOMMENDED_MODELS: dict[str, str] = {
+    "anthropic:claude-opus-4-7": "Claude Opus 4.7",
+    "anthropic:claude-opus-4-8": "Claude Opus 4.8",
+    "anthropic:claude-sonnet-5": "Claude Sonnet 5",
+    "baseten:deepseek-ai/DeepSeek-V4-Pro": "DeepSeek V4 Pro",
+    "baseten:moonshotai/Kimi-K2.7-Code": "Kimi K2.7 Code",
+    "baseten:nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B": "Nemotron 3 Ultra 550B A55B",
+    "baseten:zai-org/GLM-5.2": "GLM 5.2",
+    "fireworks:accounts/fireworks/models/deepseek-v4-pro": "DeepSeek V4 Pro",
+    "fireworks:accounts/fireworks/models/glm-5p2": "GLM 5.2",
+    "fireworks:accounts/fireworks/models/kimi-k2p7-code": "Kimi K2.7 Code",
+    "fireworks:accounts/fireworks/models/minimax-m3": "MiniMax-M3",
+    "fireworks:accounts/fireworks/models/qwen3p7-plus": "Qwen 3.7 Plus",
+    "google_genai:gemini-3.5-flash": "Gemini 3.5 Flash",
+    "google_genai:gemini-3.1-pro-preview": "Gemini 3.1 Pro Preview",
+    "meta:muse-spark-1.1": "Muse Spark 1.1",
+    "ollama:deepseek-v4-flash:cloud": "DeepSeek V4 Flash",
+    "ollama:deepseek-v4-pro:cloud": "DeepSeek V4 Pro",
+    "ollama:glm-5.2:cloud": "GLM 5.2",
+    "ollama:kimi-k2.7-code:cloud": "Kimi K2.7 Code",
+    "ollama:minimax-m3:cloud": "MiniMax-M3",
+    "openai:gpt-5.4": "GPT-5.4",
+    "openai:gpt-5.4-mini": "GPT-5.4 mini",
+    "openai:gpt-5.4-pro": "GPT-5.4 Pro",
+    "openai:gpt-5.5": "GPT-5.5",
+    "openai:gpt-5.5-pro": "GPT-5.5 Pro",
+    "openai:gpt-5.6-luna": "GPT-5.6 Luna",
+    "openai:gpt-5.6-sol": "GPT-5.6 Sol",
+    "openai:gpt-5.6-terra": "GPT-5.6 Terra",
+    "openai_codex:gpt-5.2": "GPT-5.2",
+    "openai_codex:gpt-5.3-codex": "GPT-5.3 Codex",
+    "openai_codex:gpt-5.4": "GPT-5.4",
+    "openai_codex:gpt-5.4-mini": "GPT-5.4 mini",
+    "openai_codex:gpt-5.5": "GPT-5.5",
+    "openai_codex:gpt-5.6-luna": "GPT-5.6 Luna",
+    "openai_codex:gpt-5.6-sol": "GPT-5.6 Sol",
+    "openai_codex:gpt-5.6-terra": "GPT-5.6 Terra",
+    "openrouter:anthropic/claude-opus-4.6": "Claude Opus 4.6",
+    "openrouter:anthropic/claude-opus-4.7": "Claude Opus 4.7",
+    "openrouter:anthropic/claude-opus-4.7-fast": "Claude Opus 4.7 Fast",
+    "openrouter:anthropic/claude-opus-4.8": "Claude Opus 4.8",
+    "openrouter:anthropic/claude-sonnet-5": "Claude Sonnet 5",
+    "openrouter:deepseek/deepseek-v4-flash": "DeepSeek V4 Flash",
+    "openrouter:deepseek/deepseek-v4-flash:free": "DeepSeek V4 Flash (free)",
+    "openrouter:deepseek/deepseek-v4-pro": "DeepSeek V4 Pro",
+    "openrouter:google/gemini-3.5-flash": "Gemini 3.5 Flash",
+    "openrouter:google/gemini-3.1-pro-preview": "Gemini 3.1 Pro Preview",
+    "openrouter:moonshotai/kimi-k2.7-code": "Kimi K2.7 Code",
+    "openrouter:nvidia/nemotron-3-ultra-550b-a55b": "Nemotron 3 Ultra 550B A55B",
+    "openrouter:openai/gpt-5.4": "GPT-5.4",
+    "openrouter:openai/gpt-5.4-mini": "GPT-5.4 mini",
+    "openrouter:openai/gpt-5.4-pro": "GPT-5.4 Pro",
+    "openrouter:openai/gpt-5.5": "GPT-5.5",
+    "openrouter:openai/gpt-5.5-pro": "GPT-5.5 Pro",
+    "openrouter:openrouter/fusion": "OpenRouter Fusion",
+    "openrouter:qwen/qwen3.7-plus": "Qwen 3.7 Plus",
+    "openrouter:z-ai/glm-5.2": "GLM 5.2",
+    "xai:grok-4.5": "Grok 4.5",
+}
+"""Hand-curated frontier-tier models promoted across the UI, mapped to a
+human-readable display name.
+
+Used by the onboarding picker (`curated=True`) and by the in-`/model`
+"Recommended only" toggle (Ctrl+R). Membership tests and iteration operate on
+the spec keys; the names are a display fallback for `_get_model_display_name`
+when a provider package (and thus its profile `name`) is not installed — the
+common case for uninstalled recommendations and onboarding, where the raw
+model id (e.g. `accounts/fireworks/models/kimi-k2p7-code`) would otherwise
+show. When a profile is available its upstream `name` wins, so these stay a
+safety net rather than a second source of truth.
+
+Same model IDs may appear under multiple providers (e.g. Kimi K2.7 Code via
+`baseten`, `fireworks`, `ollama`, and `openrouter`) and are listed under each
+provider intentionally so the user can pick whichever provider they have
+credentials for.
+"""
+
+
+class _ModelData(NamedTuple):
+    """Model discovery data returned by `ModelSelectorScreen._load_model_data`.
+
+    Attributes:
+        all_models: `(provider:model spec, provider)` pairs for every model to
+            surface, including install-required recommended models.
+        default_spec: The configured default model spec, or `None`.
+        profiles: Spec string to profile entry mapping.
+        recent_specs: Most-recent-first `provider:model` specs read from
+            `~/.deepagents/.state/recent_models.json`.
+        install_extras: Each surfaced-but-uninstalled provider mapped to the
+            extra that installs it.
+    """
+
+    all_models: list[tuple[str, str]]
+    default_spec: str | None
+    profiles: Mapping[str, ModelProfileEntry]
+    recent_specs: list[str]
+    install_extras: dict[str, str]
+
+
+class ModelOption(Static):
+    """A clickable model option in the selector."""
+
+    def __init__(
+        self,
+        label: str | Content,
+        model_spec: str,
+        provider: str,
+        index: int,
+        *,
+        auth_status: ProviderAuthStatus | None = None,
+        classes: str = "",
+        show_provider: bool = True,
+    ) -> None:
+        """Initialize a model option.
+
+        Args:
+            label: Display content — a `Content` object (preferred) or a
+                plain string that `Static` will parse as markup.
+            model_spec: The model specification (provider:model format).
+            provider: The provider name.
+            index: The index of this option in the filtered list.
+            auth_status: Provider auth/readiness status.
+            classes: CSS classes for styling.
+            show_provider: Whether the row appends a dim `(provider)` tag after
+                the model name. `True` for the cross-provider "Recent" section,
+                which has no provider header to disambiguate the same model
+                offered by multiple providers; `False` for provider-grouped
+                rows where the header already names the provider. Persisted on
+                the widget so incremental relabels in `_move_selection`
+                reproduce the same display.
+        """
+        super().__init__(label, classes=classes)
+        self.model_spec = model_spec
+        self.index = index
+        self.show_provider = show_provider
+        self.auth_status = auth_status or ProviderAuthStatus(
+            state=ProviderAuthState.UNKNOWN,
+            provider=provider,
+            detail="credentials unknown",
+        )
+
+    @property
+    def provider(self) -> str:
+        """Provider name, derived from the embedded auth status."""
+        return self.auth_status.provider
+
+    class Clicked(Message):
+        """Message sent when a model option is clicked."""
+
+        def __init__(self, model_spec: str, provider: str, index: int) -> None:
+            """Initialize the Clicked message.
+
+            Args:
+                model_spec: The model specification.
+                provider: The provider name.
+                index: The index of the clicked option.
+            """
+            super().__init__()
+            self.model_spec = model_spec
+            self.provider = provider
+            self.index = index
+
+    def on_click(self, event: Click) -> None:
+        """Handle click on this option.
+
+        Args:
+            event: The click event.
+        """
+        event.stop()
+        self.post_message(self.Clicked(self.model_spec, self.provider, self.index))
+
+
+class ModelSelectorScreen(ModalScreen[tuple[str, str] | None]):
+    """Full-screen modal for model selection.
+
+    Displays available models grouped by provider with keyboard navigation
+    and search filtering. Current model is highlighted.
+
+    Returns (model_spec, provider) tuple on selection, or None on cancel.
+    """
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("up", "move_up", "Up", show=False, priority=True),
+        Binding("down", "move_down", "Down", show=False, priority=True),
+        Binding("tab", "tab_complete", "Tab complete", show=False, priority=True),
+        Binding("pageup", "page_up", "Page up", show=False, priority=True),
+        Binding("pagedown", "page_down", "Page down", show=False, priority=True),
+        Binding("enter", "select", "Select", show=False, priority=True),
+        Binding("ctrl+s", "set_default", "Set default", show=False, priority=True),
+        Binding(
+            "ctrl+r",
+            "toggle_recommended",
+            "Recommended only",
+            show=False,
+            priority=True,
+        ),
+        Binding(
+            "ctrl+a",
+            "add_custom_provider",
+            "Add custom provider",
+            show=False,
+            priority=True,
+        ),
+        Binding("ctrl+n", "toggle_names", "Model IDs", show=False, priority=True),
+        Binding("escape", "cancel", "Cancel", show=False, priority=True),
+    ]
+    """Key bindings for model navigation, selection, defaulting, and cancel.
+
+    Arrows move the cursor, Page Up/Down jump by a visual page, Tab copies
+    the highlighted spec into the filter input, Enter selects, Ctrl+S
+    toggles the default model, Ctrl+R toggles between showing all installed
+    models and the hand-curated "recommended" subset, Ctrl+N toggles rows
+    between friendly display names and raw `provider:model` specs (the analog
+    of the `/theme` picker's `n` key), and Esc dismisses. All bindings use
+    `priority=True` so they take precedence over the embedded `Input`;
+    vim-style `j`/`k` bindings — and a bare `n` mirroring the `/theme`
+    picker — are deliberately omitted because they would prevent typing those
+    letters into the always-focused filter input, which is why the names
+    toggle is bound to `ctrl+n` instead.
+    """
+
+    CSS = """
+    ModelSelectorScreen {
+        align: center middle;
+    }
+
+    ModelSelectorScreen > Vertical {
+        width: 76;
+        max-width: 90%;
+        height: auto;
+        background: $surface;
+        border: solid $primary;
+        padding: 1 2;
+    }
+
+    ModelSelectorScreen .model-selector-title {
+        text-style: bold;
+        color: $primary;
+        text-align: center;
+        margin-bottom: 1;
+    }
+
+    ModelSelectorScreen .model-selector-description {
+        height: auto;
+        color: $text-muted;
+        margin-bottom: 1;
+    }
+
+    ModelSelectorScreen .model-selector-info {
+        height: auto;
+        color: $text-muted;
+        margin-bottom: 1;
+    }
+
+    ModelSelectorScreen #model-filter {
+        margin-bottom: 1;
+        border: solid $primary-lighten-2;
+    }
+
+    ModelSelectorScreen #model-filter:focus {
+        border: solid $primary;
+    }
+
+    ModelSelectorScreen .model-list {
+        height: auto;
+        min-height: 1;
+        max-height: 16;  /* keep in sync with `_MODEL_LIST_MAX_HEIGHT` */
+        scrollbar-gutter: stable;
+        background: $background;
+    }
+
+    ModelSelectorScreen #model-options {
+        height: auto;
+    }
+
+    ModelSelectorScreen .model-provider-header {
+        color: $primary;
+        margin-top: 1;
+    }
+
+    ModelSelectorScreen #model-options > .model-provider-header:first-child {
+        margin-top: 0;
+    }
+
+    ModelSelectorScreen .model-option {
+        height: 1;
+        padding: 0 1;
+    }
+
+    ModelSelectorScreen .model-option:hover {
+        background: $surface-lighten-1;
+    }
+
+    ModelSelectorScreen .model-option-selected {
+        background: $primary;
+        color: $background;
+        text-style: bold;
+    }
+
+    ModelSelectorScreen .model-option-selected:hover {
+        background: $primary-lighten-1;
+    }
+
+    ModelSelectorScreen .model-option-current {
+        text-style: italic;
+    }
+
+    ModelSelectorScreen .model-selector-help {
+        height: auto;  /* keep auto so the standard footer wraps; see _help_text */
+        color: $text-muted;
+        text-style: italic;
+        margin-top: 1;
+        text-align: center;
+    }
+
+    ModelSelectorScreen .model-detail-footer {
+        height: 4;
+        padding: 0 2;
+        margin-top: 1;
+    }
+    """
+    """Styling for the modal shell, filter input, provider-grouped list, detail
+    footer, and help text."""
+
+    def __init__(
+        self,
+        current_model: str | None = None,
+        current_provider: str | None = None,
+        cli_profile_override: dict[str, Any] | None = None,
+        *,
+        curated: bool = False,
+        title: str | None = None,
+        description: str | Content | None = None,
+        result_callback: Callable[[tuple[str, str] | None], None] | None = None,
+    ) -> None:
+        """Initialize the ModelSelectorScreen.
+
+        Data loading (model discovery, profiles) is deferred to `on_mount`
+        so the screen pushes instantly and populates asynchronously.
+
+        Args:
+            current_model: The currently active model name (to highlight).
+            current_provider: The provider of the current model.
+            cli_profile_override: Extra profile fields from `--profile-override`.
+
+                Merged on top of upstream + config.toml profiles so that app
+                overrides appear with `*` markers in the detail footer.
+            curated: Whether to show a short, profile-ranked model subset.
+            title: Optional title override for the selector.
+            description: Optional description shown below the title.
+            result_callback: Optional callback for selector results when the
+                screen is displayed without a `push_screen` result callback.
+        """
+        super().__init__()
+        self._current_model = current_model
+        self._current_provider = current_provider
+        self._cli_profile_override = cli_profile_override
+        self._curated = curated
+        self._title = title
+        self._description = description
+        self._result_callback = result_callback
+        # Standard /model defaults to the curated recommended subset so users
+        # face less decision fatigue; onboarding (`curated=True`) already
+        # constrains the list via `_curated`, so leaving this False there
+        # avoids double-flagging in `_apply_subset`.
+        self._recommended_only = not curated
+        # Rows show friendly display names by default; Ctrl+N flips every row
+        # to its raw `provider:model` spec (mirrors the `/theme` picker's
+        # label/key toggle) so a user can read or copy the canonical id.
+        self._show_specs = False
+
+        self._unfiltered_models: list[tuple[str, str]] = []
+        self._recent_specs: list[str] = []
+        # Providers surfaced in the list whose integration package is not
+        # installed, mapped to the extra that installs them. Selecting one
+        # routes through the install-confirm modal instead of an auth prompt.
+        self._install_extras: dict[str, str] = {}
+        self._reload_task: asyncio.Task[None] | None = None
+        # Set when the user confirms installing a provider's extra; the app
+        # reads this off the screen after dismissal to install then switch.
+        self.pending_install_extra: str | None = None
+
+        self._all_models: list[tuple[str, str]] = []
+        self._filtered_models: list[tuple[str, str]] = []
+        self._selected_index = 0
+        self._options_container: Container | None = None
+        self._option_widgets: list[ModelOption] = []
+        self._filter_text = ""
+        self._current_spec: str | None = None
+        if current_model and current_provider:
+            self._current_spec = f"{current_provider}:{current_model}"
+        self._default_spec: str | None = None
+        self._profiles: Mapping[str, ModelProfileEntry] = {}
+        self._loaded = False
+
+    def _info_line_content(self) -> Content:
+        """Build the info line shown above the filter input.
+
+        Reflects whether the screen is filtered to the recommended subset.
+
+        Returns:
+            Styled `Content` for the info line.
+        """
+        if self._filter_text.strip():
+            return Content.styled("Searching all models from installed providers")
+        if self._recommended_only:
+            return Content.styled(
+                "Showing recommended models — Ctrl+R for all",
+            )
+        return Content.styled(
+            "Showing all models from installed providers — Ctrl+R for recommended",
+        )
+
+    def _update_info_line(self) -> None:
+        """Refresh the standard selector info line."""
+        if self._curated:
+            return
+        info = self.query_one("#model-selector-info", Static)
+        info.update(self._info_line_content())
+
+    def _help_text(self) -> str:
+        """Build the footer help text.
+
+        Curated/onboarding mode omits the Ctrl+S, Ctrl+R, and Ctrl+N hints.
+        Escape stays bound but is left off the hint line — modal dismissal via
+        Escape is conventional, and advertising it would only lengthen an
+        already-wrapping line. In standard mode the full line exceeds the modal
+        width, so the help `Static` is sized to grow (auto height) and wraps to
+        two rows rather than clipping the trailing hints.
+
+        Returns:
+            The bullet-separated help line.
+        """
+        glyphs = get_glyphs()
+        parts = [
+            f"{glyphs.arrow_up}/{glyphs.arrow_down} navigate",
+            "Tab autocomplete",
+            "Enter select",
+        ]
+        if not self._curated:
+            parts.extend((
+                "Ctrl+S set default",
+                "Ctrl+R recommended",
+                "Ctrl+A add provider",
+                "Ctrl+N IDs",
+            ))
+        sep = f" {glyphs.bullet} "
+        return sep.join(parts)
+
+    def _find_current_model_index(self) -> int:
+        """Find the index of the current model in the filtered list.
+
+        Returns:
+            Index of the current model, or 0 if not found.
+        """
+        if not self._current_model or not self._current_provider:
+            return 0
+
+        current_spec = f"{self._current_provider}:{self._current_model}"
+        for i, (model_spec, _) in enumerate(self._filtered_models):
+            if model_spec == current_spec:
+                return i
+        return 0
+
+    def _initial_selected_index(self) -> int:
+        """Return the default highlighted row for the current selector mode."""
+        if self._curated:
+            return 0
+        return self._find_current_model_index()
+
+    def compose(self) -> ComposeResult:
+        """Compose the screen layout.
+
+        Yields:
+            Widgets for the model selector UI.
+        """
+        with Vertical():
+            # Title with current model in provider:model format
+            if self._title:
+                title = self._title
+            elif self._current_model and self._current_provider:
+                current_spec = f"{self._current_provider}:{self._current_model}"
+                title = f"Select Model (current: {current_spec})"
+            elif self._current_model:
+                title = f"Select Model (current: {self._current_model})"
+            else:
+                title = "Select Model"
+            yield Static(title, classes="model-selector-title")
+            if self._description:
+                yield Static(
+                    self._description,
+                    classes="model-selector-description",
+                )
+
+            if not self._curated:
+                yield Static(
+                    self._info_line_content(),
+                    classes="model-selector-info",
+                    id="model-selector-info",
+                )
+
+            # Search input
+            yield Input(
+                placeholder="Type to filter or enter provider:model...",
+                id="model-filter",
+            )
+
+            # Scrollable model list
+            with VerticalScroll(classes="model-list"):
+                self._options_container = Container(id="model-options")
+                yield self._options_container
+
+            # Model detail footer
+            yield Static("", classes="model-detail-footer", id="model-detail-footer")
+
+            # Add custom provider button (only in non-curated mode)
+            if not self._curated:
+                yield Button(
+                    "Add Custom Provider (Ctrl+A)",
+                    id="add-custom-provider-btn",
+                    variant="primary",
+                )
+
+            yield Static(self._help_text(), classes="model-selector-help")
+
+    @staticmethod
+    def _load_model_data(
+        cli_override: dict[str, Any] | None,
+        *,
+        include_uninstalled: bool = True,
+        include_recent: bool = True,
+    ) -> _ModelData:
+        """Gather model discovery data synchronously.
+
+        Intended to be called via `asyncio.to_thread` so filesystem I/O in
+        `get_available_models` does not block the event loop.
+
+        Args:
+            cli_override: Extra profile fields from `--profile-override`.
+            include_uninstalled: When `True`, append recommended models that
+                aren't already surfaced, in two cases: (1) the provider
+                integration isn't installed, added as greyed-out
+                install-required rows; (2) the provider is installed but its
+                upstream profiles omit the model, added as normal selectable
+                rows.
+            include_recent: When `True`, load the recent-models MRU so the
+                pinned "Recent" section can render. Onboarding sets this
+                `False`: first-run users have never picked a model, and the
+                startup default-fallback resolution writes its auto-detected
+                pick into the MRU, which would otherwise surface as a bogus
+                "Recent" entry the user never chose.
+
+        Returns:
+            A `_ModelData` bundle of the discovered models, default spec,
+                profiles, recent specs, and install-required provider extras.
+        """
+        available = get_available_models()
+        config = ModelConfig.load()
+        all_models: list[tuple[str, str]] = [
+            (f"{provider}:{model}", provider)
+            for provider, models in available.items()
+            for model in models
+        ]
+
+        install_extras: dict[str, str] = {}
+        if include_uninstalled:
+            from deepagents_code.config_manifest import (
+                is_provider_package_installed,
+                provider_install_extra,
+            )
+
+            # Seeded from the discovered models; a recommended spec already
+            # surfaced here is skipped below. Recommended specs are unique (dict
+            # keys iterated once), so this entry guard is the only dedup needed
+            # and the set never has to grow inside the loop.
+            existing_specs = {spec for spec, _ in all_models}
+            installed_recommended: list[tuple[str, str]] = []
+            uninstalled_recommended: list[tuple[str, str]] = []
+            for spec in sorted(_RECOMMENDED_MODELS):
+                if spec in existing_specs:
+                    continue
+                provider = spec.split(":", 1)[0]
+                try:
+                    if not config.is_provider_enabled(provider):
+                        continue
+                    extra = provider_install_extra(provider)
+                    provider_installed = is_provider_package_installed(provider)
+                except Exception:
+                    # Isolate per-provider probe failures so one bad recommended
+                    # provider can't take down the entire model list (the caller
+                    # degrades any raise here to an empty selector). The append
+                    # bookkeeping below stays outside this guard so genuine logic
+                    # bugs surface instead of being silently swallowed.
+                    logger.warning(
+                        "Skipping recommended model %r while merging "
+                        "recommendations into the model list",
+                        spec,
+                        exc_info=True,
+                    )
+                    continue
+                if provider in available and provider_installed:
+                    # Provider is installed and discoverable, but its upstream
+                    # profiles don't surface this curated model (missing entry
+                    # or filtered out). Add it as a normal selectable row so the
+                    # hardcoded recommendation isn't silently dropped when the
+                    # profile list lags.
+                    installed_recommended.append((spec, provider))
+                    continue
+                if extra is None or provider_installed:
+                    continue
+                install_extras[provider] = extra
+                uninstalled_recommended.append((spec, provider))
+            all_models.extend(installed_recommended)
+            all_models.extend(uninstalled_recommended)
+
+        profiles = get_model_profiles(cli_override=cli_override)
+        recent_specs = load_recent_models() if include_recent else []
+        return _ModelData(
+            all_models,
+            config.default_model,
+            profiles,
+            recent_specs,
+            install_extras,
+        )
+
+    def _apply_subset(
+        self,
+        all_models: list[tuple[str, str]],
+    ) -> list[tuple[str, str]]:
+        """Apply the active subset filter (onboarding or recommended-only).
+
+        Recently-used specs are unioned in even when the recommended-only
+        toggle is on, so personal usage always wins over curation. Onboarding
+        intentionally keeps a tight curated subset and skips this union.
+
+        Args:
+            all_models: Full list of `(provider:model, provider)` pairs.
+
+        Returns:
+            The list reduced to the recommended subset when either
+                `_curated` (onboarding) or `_recommended_only` (Ctrl+R) is
+                active. Falls back to the full list when no recommended
+                models are installed so the screen is never empty.
+        """
+        if self._curated:
+            return self._curate_models(all_models)
+        if self._recommended_only:
+            curated = self._curate_models(all_models)
+            curated_specs = {spec for spec, _ in curated}
+            # Order follows all_models (insertion), not MRU; _update_display
+            # rebuilds visual order by iterating self._recent_specs directly.
+            recent_extra = [
+                (spec, provider)
+                for spec, provider in all_models
+                if spec in self._recent_specs and spec not in curated_specs
+            ]
+            return [*recent_extra, *curated]
+        return list(all_models)
+
+    @staticmethod
+    def _curate_models(
+        all_models: list[tuple[str, str]],
+    ) -> list[tuple[str, str]]:
+        """Return the curated onboarding list in the model switcher's order.
+
+        Returns the eval-backed frontier subset when any of those models are
+        available. When none are, returns the full switcher list so onboarding
+        still surfaces every installed provider rather than a truncated slice.
+
+        Args:
+            all_models: Full list of `(provider:model, provider)` pairs.
+
+        Returns:
+            Curated model list for onboarding setup.
+        """
+        frontier = [
+            (spec, provider)
+            for spec, provider in all_models
+            if spec in _RECOMMENDED_MODELS
+        ]
+        return frontier or all_models
+
+    async def on_mount(self) -> None:
+        """Set up the screen on mount.
+
+        Loads model data in a background thread so the screen frame renders
+        immediately, then populates the model list.
+        """
+        if is_ascii_mode():
+            colors = theme.get_theme_colors(self)
+            container = self.query_one(Vertical)
+            container.styles.border = ("ascii", colors.success)
+        self.call_after_refresh(self._fit_model_list)
+
+        # Focus the filter input immediately so the user can start typing
+        # while model data loads.
+        filter_input = self.query_one("#model-filter", Input)
+        filter_input.focus()
+
+        # Offload to thread because get_available_models does filesystem I/O
+        try:
+            data = await asyncio.to_thread(
+                self._load_model_data,
+                self._cli_profile_override,
+                include_uninstalled=True,
+                include_recent=not self._curated,
+            )
+        except Exception:
+            logger.exception("Failed to load model data for /model selector")
+            self._loaded = True
+            if self.is_running:
+                self.notify(
+                    "Could not load model list. "
+                    "Check provider packages and config.toml.",
+                    severity="error",
+                    timeout=10,
+                    markup=False,
+                )
+                await self._update_display()
+                self._update_footer()
+            return
+
+        # Screen may have been dismissed while the thread was running
+        if not self.is_running:
+            return
+
+        self._unfiltered_models = data.all_models
+        self._default_spec = data.default_spec
+        self._profiles = data.profiles
+        self._recent_specs = data.recent_specs
+        self._install_extras = data.install_extras
+        self._all_models = self._apply_subset(self._unfiltered_models)
+        self._filtered_models = list(self._all_models)
+        self._selected_index = self._initial_selected_index()
+        self._loaded = True
+
+        # Re-apply any filter text the user typed while data was loading
+        if self._filter_text:
+            self._update_filtered_list()
+
+        await self._update_display()
+        self._update_footer()
+
+    def on_resize(self) -> None:
+        """Refit the model list when terminal dimensions change."""
+        self.call_after_refresh(self._fit_model_list)
+
+    def _fit_model_list(self) -> None:
+        """Cap the model list so modal controls stay visible."""
+        try:
+            container = self.query_one(Vertical)
+        except NoMatches:
+            # This runs deferred via `call_after_refresh`/`on_resize`; the
+            # screen may have been popped before it fires (e.g. a resize racing
+            # dismissal). Sizing is cosmetic, so skip quietly but leave a
+            # breadcrumb rather than letting it surface in the event loop.
+            logger.debug(
+                "Skipping model-list refit; screen not mounted",
+                exc_info=True,
+            )
+            return
+        # The screen is still mounted, so `.model-list` (always composed) must
+        # exist; a missing body here is a structural regression, not the
+        # teardown race, so let `NoMatches` surface rather than silently
+        # rendering an uncapped list.
+        body = self.query_one(".model-list", VerticalScroll)
+        non_body_height = max(0, container.region.height - body.region.height)
+        available_height = self.size.height - non_body_height
+        max_height = max(
+            _MODEL_LIST_MIN_HEIGHT,
+            min(_MODEL_LIST_MAX_HEIGHT, available_height),
+        )
+        current = body.styles.max_height
+        if current is not None and current.cells == max_height:
+            return
+        body.styles.max_height = max_height
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        """Filter models as user types.
+
+        Args:
+            event: The input changed event.
+        """
+        self._filter_text = event.value
+        self._update_info_line()
+        if not self._loaded:
+            return  # on_mount will re-apply filter after data loads
+        self._update_filtered_list()
+        self.call_after_refresh(self._update_display)
+
+    async def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle button presses."""
+        if event.button.id == "add-custom-provider-btn":
+            await self.action_add_custom_provider()
+        self.call_after_refresh(self._update_display)
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Handle Enter key when filter input is focused.
+
+        Args:
+            event: The input submitted event.
+        """
+        event.stop()
+        self.action_select()
+
+    def on_model_option_clicked(self, event: ModelOption.Clicked) -> None:
+        """Handle click on a model option.
+
+        Args:
+            event: The click event with model info.
+        """
+        self._selected_index = event.index
+        self._select_with_auth_check(event.model_spec, event.provider)
+
+    def _update_filtered_list(self) -> None:
+        """Update the filtered models based on search text using fuzzy matching.
+
+        Results are sorted by match score (best first), with installed
+        providers ranked above not-yet-installed ones so the common case of
+        picking an available model is never displaced by an install-required
+        suggestion. In standard `/model` mode, non-empty searches span the
+        full installed model list even when the default view is currently
+        constrained to recommended models.
+        """
+        query = self._filter_text.strip()
+        if not query:
+            self._filtered_models = list(self._all_models)
+            self._selected_index = self._initial_selected_index()
+            return
+
+        tokens = query.split()
+        search_models = self._all_models if self._curated else self._unfiltered_models
+
+        # Match against what the user actually sees, not just the raw spec: the
+        # friendly model name and provider label are folded into the search
+        # haystack so e.g. "Opus 4.8" finds `anthropic:claude-opus-4-8` (whose
+        # spec, with hyphens, the "4.8" token can't subsequence-match) and
+        # "OpenAI Codex" finds the codex rows. The spec stays in the haystack so
+        # existing muscle-memory queries keep working.
+        from deepagents_code.tui.widgets.auth import provider_display_name
+
+        config = ModelConfig.load()
+        provider_labels: dict[str, str] = {}
+
+        # Resolve the display labels up front, *outside* the try below. That
+        # fallback exists for `Matcher` choking on edge-case input; folding
+        # label resolution into it would misattribute an error from
+        # `_get_model_display_name`/`provider_display_name` to the matcher and
+        # silently drop the user's filter. Any failure here should surface, not
+        # masquerade as "no matches".
+        haystacks: list[tuple[str, str, str]] = []
+        for spec, provider in search_models:
+            label = provider_labels.get(provider)
+            if label is None:
+                label = provider_display_name(provider, config)
+                provider_labels[provider] = label
+            haystacks.append(
+                (spec, provider, f"{spec} {self._get_model_display_name(spec)} {label}")
+            )
+
+        try:
+            matchers = [Matcher(token, case_sensitive=False) for token in tokens]
+            scored: list[tuple[float, str, str]] = []
+            for spec, provider, haystack in haystacks:
+                scores = [m.match(haystack) for m in matchers]
+                if all(s > 0 for s in scores):
+                    scored.append((min(scores), spec, provider))
+        except Exception:
+            # graceful fallback if Matcher fails on edge-case input
+            logger.warning(
+                "Fuzzy matcher failed for query %r, falling back to full list",
+                query,
+                exc_info=True,
+            )
+            self._filtered_models = list(search_models)
+            self._selected_index = self._initial_selected_index()
+            return
+
+        self._filtered_models = [
+            (spec, provider)
+            for _installed, _score, spec, provider in sorted(
+                (
+                    (provider not in self._install_extras, score, spec, provider)
+                    for score, spec, provider in scored
+                ),
+                reverse=True,
+            )
+        ]
+        self._selected_index = 0
+
+    @staticmethod
+    def _unique_model_entries(
+        models: list[tuple[str, str]],
+    ) -> list[tuple[str, str]]:
+        """Return unique model/provider pairs while preserving first-seen order."""
+        seen: set[tuple[str, str]] = set()
+        unique: list[tuple[str, str]] = []
+        for entry in models:
+            if entry in seen:
+                continue
+            seen.add(entry)
+            unique.append(entry)
+        return unique
+
+    @staticmethod
+    def _find_same_occurrence_index(
+        models: list[tuple[str, str]],
+        entry: tuple[str, str],
+        occurrence: int,
+    ) -> int:
+        """Find the `occurrence`th matching model/provider tuple in `models`.
+
+        Args:
+            models: Render-ordered model/provider pairs to search.
+            entry: Exact `(model_spec, provider)` tuple to match.
+            occurrence: One-based occurrence count to find.
+
+        Returns:
+            Matching index, or `0` if no matching occurrence exists.
+        """
+        matches = 0
+        first_match: int | None = None
+        for i, candidate in enumerate(models):
+            if candidate != entry:
+                continue
+            if first_match is None:
+                first_match = i
+            matches += 1
+            if matches == occurrence:
+                return i
+        return first_match or 0
+
+    # Lower ranks render first: providers the user can use right now lead,
+    # then providers whose readiness is unknown, then providers needing a
+    # missing credential, then ones that aren't even installed. A missing
+    # credential sits above not-installed since fixing it is just an auth
+    # prompt away.
+    _PROVIDER_AVAILABLE_RANK = 0
+    _PROVIDER_UNKNOWN_RANK = 1
+    _PROVIDER_MISSING_RANK = 2
+    _PROVIDER_UNINSTALLED_RANK = 3
+
+    def _provider_availability_rank(
+        self,
+        provider: str,
+        auth_status: ProviderAuthStatus,
+    ) -> int:
+        """Return a sort rank that floats usable providers to the top.
+
+        Args:
+            provider: Provider name being ranked.
+            auth_status: The provider's resolved auth/readiness status.
+
+        Returns:
+            A rank where lower values sort earlier: ready-to-use providers
+                first, then unknown, then missing-credential, then
+                not-installed providers.
+        """
+        if provider in self._install_extras:
+            return self._PROVIDER_UNINSTALLED_RANK
+        state = auth_status.state
+        if state in {
+            ProviderAuthState.CONFIGURED,
+            ProviderAuthState.NOT_REQUIRED,
+            ProviderAuthState.IMPLICIT,
+            ProviderAuthState.MANAGED,
+        }:
+            return self._PROVIDER_AVAILABLE_RANK
+        if state is ProviderAuthState.UNKNOWN:
+            return self._PROVIDER_UNKNOWN_RANK
+        return self._PROVIDER_MISSING_RANK
+
+    async def _update_display(self) -> None:
+        """Render the model list grouped by provider.
+
+        Performs a full DOM rebuild (removes all children, re-mounts).
+        Arrow-key navigation uses `_move_selection` instead to avoid
+        the cost of a full rebuild.
+        """
+        if not self._options_container:
+            return
+
+        await self._options_container.remove_children()
+        self._option_widgets = []
+
+        if not self._filtered_models:
+            if not self._loaded:
+                empty_content: Content = Content.styled("Loading models…", "dim")
+            else:
+                typed = self._filter_text.strip()
+                if typed and ":" in typed:
+                    empty_content = Content.assemble(
+                        ("No matching models — press ", "dim"),
+                        ("Enter", "bold"),
+                        (" to use ", "dim"),
+                        (typed, "bold"),
+                        (" as a custom provider:model spec", "dim"),
+                    )
+                elif typed:
+                    empty_content = Content.assemble(
+                        ("No matching models — press ", "dim"),
+                        ("Enter", "bold"),
+                        (" to use ", "dim"),
+                        (typed, "bold"),
+                        (" as a custom model spec (no provider prefix)", "dim"),
+                    )
+                else:
+                    empty_content = Content.styled("No matching models", "dim")
+            await self._options_container.mount(Static(empty_content))
+            self._update_footer()
+            self.call_after_refresh(self._fit_model_list)
+            return
+
+        has_filter = bool(self._filter_text.strip())
+        source = self._filtered_models if has_filter else self._all_models
+        source_models = self._unique_model_entries(source)
+
+        # Resolve which recent specs are present in the current filtered set.
+        # Recent rendering only happens at the top of an unfiltered view; once
+        # the user starts fuzzy-filtering, recents are surfaced through the
+        # match logic like any other model so the search remains predictable.
+        if has_filter:
+            recent_entries: list[tuple[str, str]] = []
+        else:
+            spec_to_provider = dict(source_models)
+            recent_entries = [
+                (spec, spec_to_provider[spec])
+                for spec in self._recent_specs
+                if spec in spec_to_provider
+            ]
+        # Group models by provider, preserving insertion order so models
+        # from the same provider cluster together in the visual list. Specs
+        # also in the Recent section are intentionally kept here so a user
+        # who opens `/model` always finds their model at its provider's
+        # familiar position in addition to the MRU shortcut at the top.
+        by_provider: dict[str, list[tuple[str, str]]] = {}
+        for model_spec, provider in source_models:
+            by_provider.setdefault(provider, []).append((model_spec, provider))
+
+        # Resolve provider auth upfront so it can both drive the
+        # availability-first ordering below and feed the widget-building loop.
+        auth_statuses = {p: get_provider_auth_status(p) for p in by_provider}
+
+        # In the default (unfiltered) view, float providers the user can
+        # actually use to the top so a usable model is reachable without
+        # scrolling or searching. Providers needing missing credentials or a
+        # package install sink to the bottom. A search already orders by match
+        # score (installed providers first), so leave that ordering untouched.
+        if not has_filter:
+            ordered_providers = sorted(
+                by_provider,
+                key=lambda p: self._provider_availability_rank(p, auth_statuses[p]),
+            )
+            by_provider = {p: by_provider[p] for p in ordered_providers}
+
+        # Rebuild _filtered_models to match the rendered order (recents first,
+        # then provider-grouped). Without this, _filtered_models stays in
+        # score-sorted order while _option_widgets follow rendered order,
+        # causing _update_footer to look up the wrong model for the
+        # highlighted index.
+        grouped_order: list[tuple[str, str]] = list(recent_entries)
+        for entries in by_provider.values():
+            grouped_order.extend(entries)
+
+        # Remap selected_index so the same visual occurrence stays highlighted.
+        old_entry = self._filtered_models[self._selected_index]
+        old_occurrence = self._filtered_models[: self._selected_index + 1].count(
+            old_entry
+        )
+        self._filtered_models = grouped_order
+        self._selected_index = self._find_same_occurrence_index(
+            grouped_order,
+            old_entry,
+            old_occurrence,
+        )
+
+        glyphs = get_glyphs()
+        flat_index = 0
+        selected_widget: ModelOption | None = None
+
+        # Build current model spec for comparison
+        current_spec = None
+        if self._current_model and self._current_provider:
+            current_spec = f"{self._current_provider}:{self._current_model}"
+
+        # Collect all widgets first, then batch-mount once to avoid
+        # individual DOM mutations per widget
+        all_widgets: list[Static] = []
+
+        # Pinned "Recent" section — pseudo-provider header with no auth badge
+        # because each entry already carries its real provider's auth state
+        # via `ModelOption.auth_status`.
+        if recent_entries:
+            all_widgets.append(
+                Static(
+                    Content.from_markup(
+                        "[bold]$label[/bold]", label=_RECENT_SECTION_LABEL
+                    ),
+                    classes="model-provider-header",
+                )
+            )
+            for model_spec, real_provider in recent_entries:
+                auth_status = auth_statuses[real_provider]
+                is_current = model_spec == current_spec
+                is_selected = flat_index == self._selected_index
+
+                classes = "model-option"
+                if is_selected:
+                    classes += " model-option-selected"
+                if is_current:
+                    classes += " model-option-current"
+
+                label = self._build_option_label(
+                    model_spec, real_provider, auth_status, selected=is_selected
+                )
+                widget = ModelOption(
+                    label=label,
+                    model_spec=model_spec,
+                    provider=real_provider,
+                    index=flat_index,
+                    auth_status=auth_status,
+                    classes=classes,
+                )
+                all_widgets.append(widget)
+                self._option_widgets.append(widget)
+                if is_selected:
+                    selected_widget = widget
+                flat_index += 1
+
+        # Resolve friendly provider labels via the shared helper so headers
+        # match the `/auth` and install UIs (e.g. `openai_codex` renders as
+        # "OpenAI Codex (ChatGPT login)"). Load config once; the helper reads a
+        # user-configured `display_name` before the built-in map.
+        from deepagents_code.tui.widgets.auth import provider_display_name
+
+        config = ModelConfig.load()
+
+        for provider, model_entries in by_provider.items():
+            # Provider header; auth/readiness indicator appended only when non-empty.
+            auth_status = auth_statuses[provider]
+            provider_label = provider_display_name(provider, config)
+            if provider in self._install_extras:
+                auth_indicator = self._install_indicator()
+            else:
+                auth_indicator = self._format_auth_indicator(auth_status, glyphs)
+            if auth_indicator:
+                header_content = Content.from_markup(
+                    "[bold]$provider[/bold] [dim]$auth[/dim]",
+                    provider=provider_label,
+                    auth=auth_indicator,
+                )
+            else:
+                header_content = Content.from_markup(
+                    "[bold]$provider[/bold]",
+                    provider=provider_label,
+                )
+            all_widgets.append(Static(header_content, classes="model-provider-header"))
+
+            for model_spec, _prov in model_entries:
+                is_current = model_spec == current_spec
+                is_selected = flat_index == self._selected_index
+
+                classes = "model-option"
+                if is_selected:
+                    classes += " model-option-selected"
+                if is_current:
+                    classes += " model-option-current"
+
+                label = self._build_option_label(
+                    model_spec,
+                    provider,
+                    auth_status,
+                    selected=is_selected,
+                    show_provider=False,
+                )
+                widget = ModelOption(
+                    label=label,
+                    model_spec=model_spec,
+                    provider=provider,
+                    index=flat_index,
+                    auth_status=auth_status,
+                    classes=classes,
+                    show_provider=False,
+                )
+                all_widgets.append(widget)
+                self._option_widgets.append(widget)
+
+                if is_selected:
+                    selected_widget = widget
+
+                flat_index += 1
+
+        await self._options_container.mount(*all_widgets)
+
+        # Scroll the selected item into view without animation so the list
+        # appears already scrolled to the current model on first paint.
+        if selected_widget:
+            if self._selected_index == 0:
+                # First item: scroll to top so header is visible
+                scroll_container = self.query_one(".model-list", VerticalScroll)
+                scroll_container.scroll_home(animate=False)
+            else:
+                selected_widget.scroll_visible(animate=False)
+
+        self._update_footer()
+        self.call_after_refresh(self._fit_model_list)
+
+    @staticmethod
+    def _format_auth_indicator(
+        auth_status: ProviderAuthStatus,
+        glyphs: Glyphs,
+    ) -> str:
+        """Build the provider header auth indicator.
+
+        Args:
+            auth_status: Provider auth/readiness status.
+            glyphs: Glyph table for the active terminal mode.
+
+        Returns:
+            Text shown next to the provider name, or an empty string when no
+                indicator should be rendered (e.g., `CONFIGURED`).
+        """
+        return format_auth_indicator(auth_status, glyphs)
+
+    @staticmethod
+    def _install_indicator() -> str:
+        """Return the provider-header text for an uninstalled provider."""
+        return "not installed"
+
+    def _build_option_label(
+        self,
+        model_spec: str,
+        provider: str,
+        auth_status: ProviderAuthStatus,
+        *,
+        selected: bool,
+        show_provider: bool = True,
+    ) -> Content:
+        """Build a model-option label from the current screen state.
+
+        Every row shows the model's human-readable name (via
+        `_get_model_display_name`). The cross-provider "Recent" section
+        (`show_provider=True`) additionally appends a dim `(provider)` tag,
+        since it has no provider header to disambiguate the same model offered
+        by multiple providers.
+
+        Centralizes the per-row flag derivation (current/default/status/
+        `install_required`) shared by the full rebuild in `_update_display`
+        and the incremental relabel in `_move_selection`, so the two paths
+        cannot drift. The original `/model` dim-persistence bug came from
+        exactly such drift: `_move_selection` omitted `install_required`,
+        so uninstalled rows stopped rendering dimmed after navigation.
+
+        Args:
+            model_spec: The `provider:model` string for the row.
+            provider: The row's provider key, tested against the
+                install-required set.
+            auth_status: Provider auth/readiness status for the row.
+            selected: Whether this row is the highlighted one.
+            show_provider: Whether to append the dim `(provider)` tag — `True`
+                for Recent rows, `False` for provider-grouped rows. The tag
+                uses the compact brand label (`provider_short_name`).
+
+        Returns:
+            Styled `Content` label.
+        """
+        provider_label: str | None = None
+        if show_provider:
+            from deepagents_code.tui.widgets.auth import provider_short_name
+
+            provider_label = provider_short_name(provider)
+        # `_show_specs` (Ctrl+N) renders the raw `provider:model` spec instead
+        # of the friendly name; `display_name=None` makes `_format_option_label`
+        # fall back to the spec and drop the redundant `(provider)` tag, which
+        # the spec already embeds.
+        display_name = (
+            None if self._show_specs else self._get_model_display_name(model_spec)
+        )
+        return self._format_option_label(
+            model_spec,
+            selected=selected,
+            current=model_spec == self._current_spec,
+            auth_status=auth_status,
+            is_default=model_spec == self._default_spec,
+            status=self._get_model_status(model_spec),
+            install_required=provider in self._install_extras,
+            display_name=display_name,
+            provider_label=provider_label,
+        )
+
+    @staticmethod
+    def _format_option_label(
+        model_spec: str,
+        *,
+        selected: bool,
+        current: bool,
+        auth_status: ProviderAuthStatus,
+        is_default: bool = False,
+        status: str | None = None,
+        install_required: bool = False,
+        display_name: str | None = None,
+        provider_label: str | None = None,
+    ) -> Content:
+        """Build the display label for a model option.
+
+        Args:
+            model_spec: The `provider:model` string.
+            selected: Whether this option is currently highlighted.
+            current: Whether this is the active model.
+            auth_status: Provider auth/readiness status.
+            is_default: Whether this is the configured default model.
+            status: Model status from profile (e.g., `'deprecated'`,
+                `'beta'`, `'alpha'`). `'deprecated'` renders in red;
+                other non-None values render in yellow.
+            install_required: Whether the provider's integration package is not
+                installed; renders the spec dimmed since selecting it prompts
+                an install rather than switching immediately.
+            display_name: Text to show in place of the full `model_spec`. When
+                `None`, the full spec is shown. Both the Recent and
+                provider-grouped rows pass the model's human-readable name (see
+                `_get_model_display_name`).
+            provider_label: When set (and `display_name` is given), appends a
+                dim ` (provider)` tag after the name — used by the
+                cross-provider Recent section, which has no provider header to
+                disambiguate the same model across providers. `None` for
+                provider-grouped rows. Ignored when `display_name` is `None`,
+                since the raw spec already embeds the provider.
+
+        Returns:
+            Styled Content label.
+        """
+        colors = theme.get_theme_colors()
+        glyphs = get_glyphs()
+        cursor = f"{glyphs.cursor} " if selected else "  "
+        display = model_spec if display_name is None else display_name
+        # When selected, skip the inline primary color — CSS already flips the
+        # row to ($primary bg, $background fg). Keep `bold` so the default
+        # emphasis survives both states.
+        if install_required and not selected:
+            spec = Content.styled(display, "dim")
+        elif auth_status.blocks_start:
+            spec = Content.styled(display, colors.warning)
+        elif is_default and selected:
+            spec = Content.styled(display, "bold")
+        elif is_default:
+            spec = Content.styled(display, f"bold {colors.primary}")
+        else:
+            spec = Content(display)
+        # Dim provider tag disambiguates Recent rows (no provider header).
+        # Styled like `(current)` — always dim, so it survives row selection.
+        # Requires a friendly `display_name`: tagging the raw spec (which
+        # already embeds the provider) would print the provider twice.
+        if provider_label and display_name is not None:
+            provider_tag = Content.styled(f" ({provider_label})", "dim")
+        else:
+            provider_tag = Content("")
+        suffix = Content.styled(" (current)", "dim") if current else Content("")
+        if is_default and selected:
+            default_suffix = Content.styled(" (default)", "bold")
+        elif is_default:
+            default_suffix = Content.styled(" (default)", f"bold {colors.primary}")
+        else:
+            default_suffix = Content("")
+        if status == "deprecated":
+            status_suffix = Content.styled(" (deprecated)", colors.error)
+        elif status:
+            status_suffix = Content.styled(f" ({status})", colors.warning)
+        else:
+            status_suffix = Content("")
+        return Content.assemble(
+            cursor, spec, provider_tag, suffix, default_suffix, status_suffix
+        )
+
+    @staticmethod
+    def _format_footer(
+        profile_entry: ModelProfileEntry | None,
+        glyphs: Glyphs,
+    ) -> Content:
+        """Build the detail footer text for the highlighted model.
+
+        Args:
+            profile_entry: Profile data with override tracking, or None.
+            glyphs: Glyph set for display characters.
+
+        Returns:
+            Styled `Content` for the 4-line footer.
+        """
+        from deepagents_code._session_stats import format_token_count
+
+        if profile_entry is None or not profile_entry["profile"]:
+            return Content.styled("Model profile not available :(\n\n\n", "dim")
+
+        profile = profile_entry["profile"]
+        overridden = profile_entry["overridden_keys"]
+
+        colors = theme.get_theme_colors()
+
+        def _mark(key: str, text: str) -> Content:
+            if key in overridden:
+                return Content.styled(f"*{text}", colors.warning)
+            return Content(text)
+
+        def _format_token(key: str, suffix: str) -> Content | None:
+            """Format a token-count profile key, falling back to the raw value.
+
+            Returns:
+                Styled `Content` with override marker, or None if key absent.
+            """
+            val = profile.get(key)
+            if val is None:
+                return None
+            try:
+                text = f"{format_token_count(int(val))} {suffix}"
+            except (ValueError, TypeError, OverflowError):
+                text = f"{val} {suffix}"
+            return _mark(key, text)
+
+        def _format_flags(keys: list[tuple[str, str]]) -> list[Content]:
+            """Render boolean profile keys as green (on) or dim (off) labels.
+
+            Returns:
+                List of styled `Content` objects for present keys.
+            """
+            parts: list[Content] = []
+            for key, label in keys:
+                if key in profile:
+                    base = (
+                        Content.styled(label, colors.success)
+                        if profile[key]
+                        else Content.styled(label, "dim")
+                    )
+                    if key in overridden:
+                        base = Content.assemble(
+                            Content.styled("*", colors.warning), base
+                        )
+                    parts.append(base)
+            return parts
+
+        # Line 1: Context window
+        token_keys = [("max_input_tokens", "in"), ("max_output_tokens", "out")]
+        ctx_parts = [p for k, s in token_keys if (p := _format_token(k, s)) is not None]
+        bullet_sep = Content(f" {glyphs.bullet} ")
+        line1 = (
+            Content.assemble("Context: ", bullet_sep.join(ctx_parts))
+            if ctx_parts
+            else Content("")
+        )
+
+        # Line 2: Input modalities
+        modality_keys = [
+            ("text_inputs", "text"),
+            ("image_inputs", "image"),
+            ("audio_inputs", "audio"),
+            ("pdf_inputs", "pdf"),
+            ("video_inputs", "video"),
+        ]
+        modality_parts = _format_flags(modality_keys)
+        space = Content(" ")
+        line2 = (
+            Content.assemble("Input: ", space.join(modality_parts))
+            if modality_parts
+            else Content("")
+        )
+
+        # Line 3: Capabilities
+        capability_keys = [
+            ("reasoning_output", "reasoning"),
+            ("tool_calling", "tool calling"),
+            ("structured_output", "structured output"),
+        ]
+        cap_parts = _format_flags(capability_keys)
+        line3 = (
+            Content.assemble("Capabilities: ", space.join(cap_parts))
+            if cap_parts
+            else Content("")
+        )
+
+        # Line 4: Override notice
+        displayed_keys = {k for k, _ in token_keys + modality_keys + capability_keys}
+        has_visible_override = bool(overridden & displayed_keys)
+        line4 = (
+            Content.from_markup("[dim][yellow]*[/yellow] = override[/dim]")
+            if has_visible_override
+            else Content("")
+        )
+
+        return Content.assemble(line1, "\n", line2, "\n", line3, "\n", line4)
+
+    def _get_model_status(self, model_spec: str) -> str | None:
+        """Look up the status field for a model from its profile.
+
+        Args:
+            model_spec: The `provider:model` string.
+
+        Returns:
+            Status string (e.g., `'deprecated'`) if the model has a profile
+            with a `status` key, otherwise None.
+        """
+        entry = self._profiles.get(model_spec)
+        if entry is None:
+            return None
+        profile = entry.get("profile")
+        if not profile:
+            return None
+        return profile.get("status")
+
+    def _get_model_display_name(self, model_spec: str) -> str:
+        """Resolve the friendly display name for a model spec.
+
+        Used by every row (provider-grouped and the cross-provider Recent
+        section) and folded into the search haystack. Prefers the profile's
+        human-readable `name` (e.g. `'Claude Sonnet 5'`), which reads better
+        than the raw model id. When no profile is loaded — the case for
+        uninstalled recommendations and onboarding — falls back to the
+        hardcoded name in `_RECOMMENDED_MODELS`, then the model portion of the
+        spec, then the spec itself.
+
+        Args:
+            model_spec: The `provider:model` string.
+
+        Returns:
+            The display name for the row.
+        """
+        entry = self._profiles.get(model_spec)
+        if entry:
+            profile = entry.get("profile")
+            # `profile` originates from provider packages, so guard its type
+            # rather than trusting the schema before `.get`.
+            if isinstance(profile, dict):
+                name = profile.get("name")
+                if isinstance(name, str) and name:
+                    return name
+        recommended = _RECOMMENDED_MODELS.get(model_spec)
+        if recommended:
+            return recommended
+        parsed = ModelSpec.try_parse(model_spec)
+        # `parsed.model` can be empty for a malformed spec like `provider:`;
+        # fall back to the raw spec rather than rendering a blank row.
+        return parsed.model if parsed and parsed.model else model_spec
+
+    def _update_footer(self) -> None:
+        """Update the detail footer for the currently highlighted model."""
+        footer = self.query_one("#model-detail-footer", Static)
+        if not self._filtered_models:
+            footer.update(Content.styled("No model selected", "dim"))
+            return
+        index = min(self._selected_index, len(self._filtered_models) - 1)
+        spec, _ = self._filtered_models[index]
+        entry = self._profiles.get(spec)
+        try:
+            text = self._format_footer(entry, get_glyphs())
+        except (KeyError, ValueError, TypeError):  # Resilient footer rendering
+            logger.warning("Failed to format footer for %s", spec, exc_info=True)
+            text = Content.styled("Could not load profile details\n\n\n", "dim")
+        footer.update(text)
+
+    def _move_selection(self, delta: int) -> None:
+        """Move selection by delta, updating only the affected widgets.
+
+        Args:
+            delta: Number of positions to move (-1 for up, +1 for down).
+        """
+        if not self._filtered_models or not self._option_widgets:
+            return
+
+        count = len(self._filtered_models)
+        old_index = self._selected_index
+        new_index = (old_index + delta) % count
+        self._selected_index = new_index
+
+        # Update the previously selected widget
+        old_widget = self._option_widgets[old_index]
+        old_widget.remove_class("model-option-selected")
+        old_widget.update(
+            self._build_option_label(
+                old_widget.model_spec,
+                old_widget.provider,
+                old_widget.auth_status,
+                selected=False,
+                show_provider=old_widget.show_provider,
+            )
+        )
+
+        # Update the newly selected widget
+        new_widget = self._option_widgets[new_index]
+        new_widget.add_class("model-option-selected")
+        new_widget.update(
+            self._build_option_label(
+                new_widget.model_spec,
+                new_widget.provider,
+                new_widget.auth_status,
+                selected=True,
+                show_provider=new_widget.show_provider,
+            )
+        )
+
+        # Scroll the selected item into view
+        if new_index == 0:
+            scroll_container = self.query_one(".model-list", VerticalScroll)
+            scroll_container.scroll_home(animate=False)
+        else:
+            new_widget.scroll_visible()
+
+        self._update_footer()
+
+    def action_move_up(self) -> None:
+        """Move selection up."""
+        self._move_selection(-1)
+
+    def action_move_down(self) -> None:
+        """Move selection down."""
+        self._move_selection(1)
+
+    def action_tab_complete(self) -> None:
+        """Replace search text with the currently selected model spec."""
+        if not self._filtered_models:
+            return
+        model_spec, _ = self._filtered_models[self._selected_index]
+        filter_input = self.query_one("#model-filter", Input)
+        filter_input.value = model_spec
+        filter_input.cursor_position = len(model_spec)
+
+    def _visible_page_size(self) -> int:
+        """Return the number of model options that fit in one visual page.
+
+        Returns:
+            Number of model options per page, at least 1.
+        """
+        default_page_size = 10
+        try:
+            scroll = self.query_one(".model-list", VerticalScroll)
+            height = scroll.size.height
+        except Exception:  # noqa: BLE001  # Fallback to default page size on any widget query error
+            return default_page_size
+        if height <= 0:
+            return default_page_size
+
+        total_models = len(self._filtered_models)
+        if total_models == 0:
+            return default_page_size
+
+        # Each provider header = 1 row + margin-top: 1 (first has margin 0)
+        num_headers = len(self.query(".model-provider-header"))
+        header_rows = max(0, num_headers * 2 - 1) if num_headers else 0
+        total_rows = total_models + header_rows
+        return max(1, int(height * total_models / total_rows))
+
+    def action_page_up(self) -> None:
+        """Move selection up by one visible page."""
+        if not self._filtered_models:
+            return
+        page = self._visible_page_size()
+        target = max(0, self._selected_index - page)
+        delta = target - self._selected_index
+        if delta != 0:
+            self._move_selection(delta)
+
+    def action_page_down(self) -> None:
+        """Move selection down by one visible page."""
+        if not self._filtered_models:
+            return
+        count = len(self._filtered_models)
+        page = self._visible_page_size()
+        target = min(count - 1, self._selected_index + page)
+        delta = target - self._selected_index
+        if delta != 0:
+            self._move_selection(delta)
+
+    def action_select(self) -> None:
+        """Select the current model."""
+        # If there are filtered results, always select the highlighted model
+        if self._filtered_models:
+            model_spec, provider = self._filtered_models[self._selected_index]
+            self._select_with_auth_check(model_spec, provider)
+            return
+
+        # No matches - check if user typed a custom provider:model spec
+        filter_input = self.query_one("#model-filter", Input)
+        custom_input = filter_input.value.strip()
+
+        if custom_input and ":" in custom_input:
+            provider = custom_input.split(":", 1)[0]
+            self._select_with_auth_check(custom_input, provider)
+        elif custom_input:
+            self._dismiss_with_result((custom_input, ""))
+
+    def _select_with_auth_check(self, model_spec: str, provider: str) -> None:
+        """Either dismiss with the selection, or prompt for credentials first.
+
+        When the highlighted provider has `blocks_start` auth (typically a
+        missing API key), open the in-TUI auth prompt instead of dismissing.
+        On save, dismiss with the originally-selected model. On cancel, stay
+        on the selector and refresh the credential indicator so the user can
+        try again or pick a different provider.
+        """
+        if not provider:
+            self._dismiss_with_result((model_spec, provider))
+            return
+
+        from deepagents_code.config_manifest import (
+            is_provider_package_installed,
+            provider_install_extra,
+        )
+
+        extra = provider_install_extra(provider)
+        if extra is not None and not is_provider_package_installed(provider):
+            if self._curated:
+                # Onboarding installs first, then prompts for credentials from the
+                # launch flow, matching the dependency screen's auto-install copy.
+                self._dismiss_with_result((model_spec, provider))
+                return
+            self._prompt_install_provider(model_spec, provider, extra)
+            return
+
+        status = get_provider_auth_status(provider)
+        if not status.blocks_start:
+            self._dismiss_with_result((model_spec, provider))
+            return
+
+        if provider == CODEX_PROVIDER:
+            # ChatGPT auth is an OAuth browser flow, not an API key, so the
+            # generic key/base-url prompt doesn't apply. Route to the
+            # dedicated sign-in modal (the same one the auth manager uses).
+            self._prompt_codex_sign_in(model_spec, provider)
+            return
+
+        env_var = status.env_var or get_credential_env_var(provider)
+
+        from deepagents_code.tui.widgets.auth import AuthPromptScreen, AuthResult
+
+        def _on_auth_done(result: AuthResult | None) -> None:
+            if result is AuthResult.SAVED:
+                self._dismiss_with_result((model_spec, provider))
+                return
+            # On DELETED or CANCELLED the user explicitly chose not to
+            # provide a key; refresh the credential indicator and stay on
+            # the selector so they can pick a different provider.
+            self.call_after_refresh(self._update_display)
+
+        self.app.push_screen(
+            AuthPromptScreen(
+                provider,
+                env_var,
+                reason=f"Required to use {model_spec}",
+            ),
+            _on_auth_done,
+        )
+
+    def _prompt_install_provider(
+        self, model_spec: str, provider: str, extra: str
+    ) -> None:
+        """Confirm installing a provider's extra before selecting its model.
+
+        On confirm, record the extra on `pending_install_extra` and dismiss
+        with the selected model so the app can install the extra and then
+        switch. On cancel, refresh the credential indicator and stay on the
+        selector so the user can pick a different provider.
+        """
+        from deepagents_code.tui.widgets.install_confirm import (
+            InstallProviderConfirmScreen,
+        )
+
+        def _on_confirm(proceed: bool | None) -> None:
+            if proceed:
+                self.pending_install_extra = extra
+                self._dismiss_with_result((model_spec, provider))
+                return
+            self.call_after_refresh(self._update_display)
+
+        self.app.push_screen(
+            InstallProviderConfirmScreen(provider, extra, model_spec),
+            _on_confirm,
+        )
+
+    def _prompt_codex_sign_in(self, model_spec: str, provider: str) -> None:
+        """Confirm, then run the ChatGPT OAuth flow for the selected model.
+
+        Signing in launches a browser and a multi-minute loopback wait, so a
+        confirmation modal is shown first. If the user declines, refresh the
+        credential indicator and stay on the selector so they can retry or
+        pick a different provider.
+        """
+        from deepagents_code.tui.widgets.auth import AuthConfirmScreen
+
+        def _on_confirm(proceed: bool | None) -> None:
+            if proceed:
+                self._run_codex_oauth(model_spec, provider)
+                return
+            self.call_after_refresh(self._update_display)
+
+        confirm = AuthConfirmScreen(
+            title="No ChatGPT sign-in detected",
+            body=Content.from_markup(
+                "[bold]$model[/bold] authenticates with ChatGPT, but no "
+                "sign-in was detected. Sign in now, or return to the model "
+                "list.",
+                model=model_spec,
+            ),
+            help_text="Enter to sign in, Esc to return to model list",
+        )
+        self.app.push_screen(confirm, _on_confirm)
+
+    def _run_codex_oauth(self, model_spec: str, provider: str) -> None:
+        """Run the ChatGPT OAuth sign-in flow for the selected codex model.
+
+        On a successful sign-in, dismiss with the originally-selected model.
+        On cancel or error, refresh the credential indicator and stay on the
+        selector so the user can retry or pick a different provider.
+        """
+        from deepagents_code.model_config import clear_caches
+        from deepagents_code.tui.widgets.codex_auth import CodexAuthScreen
+
+        def _on_codex_done(signed_in: bool | None) -> None:
+            clear_caches()
+            if signed_in:
+                self._dismiss_with_result((model_spec, provider))
+                return
+            self.call_after_refresh(self._update_display)
+
+        self.app.push_screen(CodexAuthScreen(), _on_codex_done)
+
+    async def action_set_default(self) -> None:
+        """Toggle the highlighted model as the default.
+
+        If the highlighted model is already the default, clears it.
+        Otherwise sets it as the new default.
+        """
+        if not self._filtered_models or not self._option_widgets:
+            return
+
+        model_spec, _provider = self._filtered_models[self._selected_index]
+        help_widget = self.query_one(".model-selector-help", Static)
+
+        if model_spec == self._default_spec:
+            # Already default — clear it
+            if await asyncio.to_thread(clear_default_model):
+                self._default_spec = None
+                self.call_after_refresh(self._update_display)
+                help_widget.update(Content.styled("Default cleared", "bold"))
+                self.set_timer(3.0, self._restore_help_text)
+            else:
+                help_widget.update(
+                    Content.styled(
+                        "Failed to clear default",
+                        f"bold {theme.get_theme_colors(self).error}",
+                    )
+                )
+                self.set_timer(3.0, self._restore_help_text)
+        elif await asyncio.to_thread(save_default_model, model_spec):
+            self._default_spec = model_spec
+            self.call_after_refresh(self._update_display)
+            help_widget.update(
+                Content.from_markup(
+                    "[bold]Default set to $spec[/bold]", spec=model_spec
+                )
+            )
+            self.set_timer(3.0, self._restore_help_text)
+        else:
+            help_widget.update(
+                Content.styled(
+                    "Failed to save default",
+                    f"bold {theme.get_theme_colors(self).error}",
+                )
+            )
+            self.set_timer(3.0, self._restore_help_text)
+
+    def _restore_help_text(self) -> None:
+        """Restore the default help text after a temporary message."""
+        help_widget = self.query_one(".model-selector-help", Static)
+        help_widget.update(self._help_text())
+
+    async def action_toggle_recommended(self) -> None:
+        """Toggle between the full model list and the recommended subset.
+
+        Disabled while in `_curated` (onboarding) mode — that screen is
+        already constrained to the recommended subset and the user should
+        finish or skip onboarding rather than browse the full list.
+        Preserves the highlighted model when it survives the toggle and
+        falls back to the current/default/first model otherwise.
+        """
+        if self._curated or not self._loaded:
+            return
+
+        prev_spec: str | None = None
+        if self._filtered_models and 0 <= self._selected_index < len(
+            self._filtered_models
+        ):
+            prev_spec = self._filtered_models[self._selected_index][0]
+
+        self._recommended_only = not self._recommended_only
+        self._all_models = self._apply_subset(self._unfiltered_models)
+
+        if self._filter_text.strip():
+            self._update_filtered_list()
+        else:
+            self._filtered_models = list(self._all_models)
+            self._selected_index = self._find_current_model_index()
+
+        if prev_spec is not None:
+            for i, (spec, _) in enumerate(self._filtered_models):
+                if spec == prev_spec:
+                    self._selected_index = i
+                    break
+
+        info = self.query_one("#model-selector-info", Static)
+        info.update(self._info_line_content())
+
+        await self._update_display()
+
+    def action_toggle_names(self) -> None:
+        """Toggle rows between friendly display names and raw model specs.
+
+        Mirrors the `/theme` picker's label/key toggle: pressing Ctrl+N flips
+        every visible row between its human-readable name (e.g.
+        `Claude Sonnet 5`) and the canonical `provider:model` spec (e.g.
+        `anthropic:claude-sonnet-5`) so the user can read or copy the exact id
+        without leaving the picker. Relabels the mounted rows in place — the
+        toggle changes neither ordering nor selection, so a full rebuild is
+        unnecessary — and stays available in curated/onboarding mode since it
+        only affects presentation.
+        """
+        if not self._loaded:
+            return
+        self._show_specs = not self._show_specs
+        self._relabel_options()
+
+    def _relabel_options(self) -> None:
+        """Rebuild each mounted row's label for the current display mode.
+
+        Used by `action_toggle_names` after flipping `_show_specs`. Each entry
+        in `_option_widgets` lines up with its `_filtered_models` index, so the
+        highlighted row is re-derived from `_selected_index` to preserve the
+        selected styling.
+        """
+        for index, widget in enumerate(self._option_widgets):
+            widget.update(
+                self._build_option_label(
+                    widget.model_spec,
+                    widget.provider,
+                    widget.auth_status,
+                    selected=index == self._selected_index,
+                    show_provider=widget.show_provider,
+                )
+            )
+
+    def action_cancel(self) -> None:
+        """Cancel the selection."""
+        self._dismiss_with_result(None)
+
+    def _dismiss_with_result(self, result: tuple[str, str] | None) -> None:
+        """Dismiss the selector and notify an optional direct result callback."""
+        if self._result_callback is not None:
+            self._result_callback(result)
+        self.dismiss(result)
+
+    async def action_add_custom_provider(self) -> None:
+        """Open the custom provider add modal."""
+        def _on_provider_saved(success: bool) -> None:
+            help_widget = self.query_one(".model-selector-help", Static)
+            if success:
+                # Reload model list to show new provider
+                self._reload_task = asyncio.create_task(self._reload_model_list())
+                help_widget.update(
+                    Content.styled(
+                        "Custom provider added successfully!", "bold green"
+                    )
+                )
+                self.set_timer(3.0, self._restore_help_text)
+            else:
+                help_widget.update(
+                    Content.styled("Failed to add custom provider", "bold red")
+                )
+                self.set_timer(3.0, self._restore_help_text)
+
+        self.app.push_screen(CustomProviderModalScreen(), _on_provider_saved)
+
+    async def _reload_model_list(self) -> None:
+        """Reload the model list after adding a custom provider."""
+        # Offload to thread because get_available_models does filesystem I/O
+        try:
+            data = await asyncio.to_thread(
+                self._load_model_data,
+                self._cli_profile_override,
+                include_uninstalled=True,
+                include_recent=not self._curated,
+            )
+        except Exception:
+            logger.exception("Failed to reload model data")
+            self.notify(
+                "Could not reload model list.",
+                severity="error",
+                timeout=3.0,
+                markup=False,
+            )
+            return
+
+        # Screen may have been dismissed while the thread was running
+        if not self.is_running:
+            return
+
+        self._unfiltered_models = data.all_models
+        self._default_spec = data.default_spec
+        self._profiles = data.profiles
+        self._recent_specs = data.recent_specs
+        self._install_extras = data.install_extras
+        self._all_models = self._apply_subset(self._unfiltered_models)
+        self._filtered_models = list(self._all_models)
+        self._selected_index = self._initial_selected_index()
+
+        # Re-apply any filter text
+        if self._filter_text:
+            self._update_filtered_list()
+
+        await self._update_display()
+        self._update_footer()
+
+
+class CustomProviderModalScreen(ModalScreen[bool]):
+    """Modal screen for adding/editing a custom OpenAI-compatible provider."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("enter", "submit", "Save provider", priority=True),
+        Binding("escape", "cancel", "Cancel", priority=True),
+    ]
+
+    def __init__(
+        self, provider_id: str | None = None, **kwargs: Any,
+    ) -> None:
+        """Initialize the custom provider modal.
+
+        Args:
+            provider_id: The provider ID to edit, or ``None`` to add a new one.
+            **kwargs: Extra keyword arguments forwarded to `ModalScreen`.
+        """
+        super().__init__(**kwargs)
+        self.provider_id = provider_id
+        self.existing_providers: dict[str, dict[str, Any]] = {}
+
+    CSS = """
+    CustomProviderModalScreen {
+        align: center middle;
+    }
+
+    CustomProviderModalScreen > Vertical {
+        background: $surface;
+        border: thick $primary;
+        width: 60;
+        height: auto;
+        padding: 1 2;
+    }
+
+    CustomProviderModalScreen .form-title {
+        text-align: center;
+        width: 100%;
+        height: 1;
+        margin-bottom: 1;
+    }
+
+    CustomProviderModalScreen .form-label {
+        width: 100%;
+        height: 1;
+        margin-top: 1;
+    }
+
+    CustomProviderModalScreen Input {
+        width: 100%;
+        height: 3;
+    }
+
+    CustomProviderModalScreen .form-buttons {
+        layout: horizontal;
+        width: 100%;
+        height: 3;
+        margin-top: 1;
+    }
+
+    CustomProviderModalScreen .form-buttons-left {
+        width: 1fr;
+        height: 100%;
+        align: left middle;
+    }
+
+    CustomProviderModalScreen .form-buttons-right {
+        width: 1fr;
+        height: 100%;
+        align: right middle;
+    }
+
+    CustomProviderModalScreen Button {
+        margin-left: 1;
+    }
+
+    CustomProviderModalScreen .error-message {
+        color: $error;
+        height: 1;
+        margin-top: 1;
+        text-align: center;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        """Compose the modal's form widgets.
+
+        Yields:
+            Textual widgets that render the form.
+        """
+        with Vertical():
+            title = (
+                "Edit Custom Provider" if self.provider_id else "Add Custom Provider"
+            )
+            yield Static(title, classes="form-title")
+            yield Static(
+                "Provider ID (lowercase, numbers, hyphens, underscores):",
+                classes="form-label",
+            )
+            yield Input(id="provider-id", placeholder="e.g. my-provider")
+            yield Static("Display Name:", classes="form-label")
+            yield Input(id="display-name", placeholder="e.g. My Custom Provider")
+            yield Static("Base URL:", classes="form-label")
+            yield Input(
+                id="base-url", placeholder="e.g. https://api.example.com/v1"
+            )
+            yield Static("API Key (optional):", classes="form-label")
+            yield Input(id="api-key", placeholder="sk-...", password=True)
+            yield Static("Default Model (optional):", classes="form-label")
+            yield Input(id="default-model", placeholder="e.g. gpt-4o")
+            yield Static("", id="error-message", classes="error-message")
+            with Container(classes="form-buttons"):
+                with Container(classes="form-buttons-left"):
+                    yield Button("Cancel", id="cancel-btn", variant="default")
+                with Container(classes="form-buttons-right"):
+                    yield Button("Confirm", id="save-btn", variant="primary")
+
+    def on_mount(self) -> None:
+        """Focus first input on mount; pre-fill if editing an existing provider."""
+        import tomllib
+
+        from deepagents_code.model_config import DEFAULT_CONFIG_PATH
+
+        # Load all existing custom providers from config
+        self.existing_providers = {}
+        try:
+            if DEFAULT_CONFIG_PATH.exists():
+                with DEFAULT_CONFIG_PATH.open("rb") as f:
+                    data = tomllib.load(f)
+                self.existing_providers = data.get("models", {}).get("providers", {})
+        except Exception:
+            logger.exception("Failed to load existing custom providers from config")
+
+        if self.provider_id:
+            # Load existing provider config for editing
+            provider_config = self.existing_providers.get(self.provider_id, {})
+            if provider_config:
+                self.query_one("#provider-id", Input).value = self.provider_id
+                # Can't edit ID for existing providers
+                self.query_one("#provider-id", Input).disabled = True
+                self.query_one("#display-name", Input).value = provider_config.get(
+                    "display_name", ""
+                )
+                self.query_one("#base-url", Input).value = provider_config.get(
+                    "base_url", ""
+                )
+                self.query_one("#default-model", Input).value = provider_config.get(
+                    "default_model", ""
+                )
+                # API key is not stored in config, it's in env var, so leave empty
+
+        if not self.provider_id:
+            self.query_one("#provider-id", Input).focus()
+        else:
+            self.query_one("#display-name", Input).focus()
+
+    def on_input(self, event: Input.Changed) -> None:
+        """Handle input changes, auto-fill existing provider data when ID matches."""
+        if event.input.id == "provider-id" and not self.provider_id:
+            provider_id = event.value.strip()
+            if not provider_id:
+                # If input is cleared, re-enable and clear other fields
+                event.input.disabled = False
+                self.query_one("#display-name", Input).value = ""
+                self.query_one("#base-url", Input).value = ""
+            elif (
+                provider_id in self.existing_providers
+                and not event.input.disabled
+            ):
+                # Auto-fill data for existing provider
+                provider_config = self.existing_providers[provider_id]
+                self.query_one("#display-name", Input).value = provider_config.get(
+                    "display_name", ""
+                )
+                self.query_one("#base-url", Input).value = provider_config.get(
+                    "base_url", ""
+                )
+                self.query_one("#default-model", Input).value = provider_config.get(
+                    "default_model", ""
+                )
+                # Disable provider ID input to prevent modification
+                event.input.disabled = True
+                # Move focus to next field
+                self.query_one("#display-name", Input).focus()
+
+    async def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle button presses."""
+        if event.button.id == "cancel-btn":
+            self.action_cancel()
+        elif event.button.id == "save-btn":
+            await self.action_submit()
+
+    async def action_submit(self) -> None:
+        """Validate and submit the form."""
+        provider_id = self.query_one("#provider-id", Input).value.strip()
+        display_name = self.query_one("#display-name", Input).value.strip()
+        base_url = self.query_one("#base-url", Input).value.strip()
+        api_key = self.query_one("#api-key", Input).value.strip() or None
+        default_model = self.query_one("#default-model", Input).value.strip() or None
+        error_widget = self.query_one("#error-message", Static)
+        # Clear any prior validation message so a successful submit doesn't
+        # leave a stale error visible in the modal (or reported by tests).
+        error_widget.update("")
+
+        # Validate inputs
+        if not provider_id:
+            error_widget.update("Provider ID is required")
+            return
+        if not all(c.islower() or c.isdigit() or c in "-_" for c in provider_id):
+            error_widget.update(
+                "Provider ID can only contain lowercase letters, numbers, "
+                "hyphens, and underscores"
+            )
+            return
+        if not display_name:
+            error_widget.update("Display name is required")
+            return
+        if not base_url:
+            error_widget.update("Base URL is required")
+            return
+        if not base_url.startswith(("http://", "https://")):
+            error_widget.update("Base URL must start with http:// or https://")
+            return
+        # Validate model ID if provided
+        if default_model:
+            if len(default_model) > _MAX_MODEL_ID_LEN:
+                error_widget.update("Model ID cannot exceed 255 characters")
+                return
+            # Allow alphanumeric, hyphens, underscores, dots, colons, slashes
+            # (common model ID characters)
+            if not all(c.isalnum() or c in "-_.:/" for c in default_model):
+                error_widget.update(
+                    "Model ID can only contain letters, numbers, hyphens, "
+                    "underscores, dots, colons, and slashes"
+                )
+                return
+
+        # Save the provider
+        from deepagents_code.model_config import save_custom_provider
+        success = await asyncio.to_thread(
+            save_custom_provider,
+            provider_id=provider_id,
+            display_name=display_name,
+            base_url=base_url,
+            api_key=api_key,
+            default_model=default_model,
+        )
+
+        if success:
+            self.dismiss(success)
+        else:
+            error_widget.update(
+                "Failed to save custom provider. Check permissions and try again."
+            )
+
+    def action_cancel(self) -> None:
+        """Cancel the form."""
+        self.dismiss(False)