novacode-cli 1.2.0__py3-none-any.whl

novacode_cli/config/model_create.py

@@ -0,0 +1,1325 @@
+import os
+import re
+
+from langchain_core.language_models import BaseChatModel
+
+from novacode_cli.config.config import console, settings
+from novacode_cli.config.provider_registry import CATALOG_PROVIDERS
+
+# Env var that must be set before a provider is usable. Ollama needs no key.
+PROVIDER_KEY_ENV: dict[str, str] = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "google": "GOOGLE_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+    "opencode": "OPENCODE_API_KEY",
+    "opencode_zen": "OPENCODE_ZEN_API_KEY",
+    "commandcode": "COMMANDCODE_API_KEY",
+    "nvidia": "NVIDIA_API_KEY",
+    "azure": "AZURE_OPENAI_API_KEY",
+    "mistral": "MISTRAL_API_KEY",
+    "groq": "GROQ_API_KEY",
+    "cerebras": "CEREBRAS_API_KEY",
+    "xai": "XAI_API_KEY",
+    "huggingface": "HF_TOKEN",
+    "kimi_coding": "KIMI_API_KEY",
+    "minimax": "MINIMAX_API_KEY",
+    # Bedrock is absent on purpose: an AWS profile or role authenticates it with
+    # no key in the environment, so a key gate would wrongly turn it away.
+}
+
+PROVIDER_KEY_ENV.update({
+    provider: preset["api_key_var"]
+    for provider, preset in CATALOG_PROVIDERS.items()
+    if preset.get("api_key_var")
+})
+
+
+def azure_base_url() -> str:
+    """The Azure v1 OpenAI-compatible URL for the configured resource.
+
+    From ``AZURE_OPENAI_ENDPOINT``, the endpoint saved with the key in /auth, or
+    ``AZURE_RESOURCE_NAME``. Accepts the endpoint with or without ``/openai/v1``.
+    """
+    from novacode_cli.config.credentials import credential_meta
+
+    meta = credential_meta("AZURE_OPENAI_API_KEY")
+    endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT") or (meta.base_url if meta else None)
+    if not endpoint and (resource := os.environ.get("AZURE_RESOURCE_NAME")):
+        endpoint = f"https://{resource}.openai.azure.com"
+    if not endpoint:
+        raise ValueError(
+            "Azure needs your resource endpoint: add it with the key in /auth, or set "
+            "AZURE_OPENAI_ENDPOINT (https://<resource>.openai.azure.com) or AZURE_RESOURCE_NAME."
+        )
+    endpoint = endpoint.strip().rstrip("/").removesuffix("/v1").removesuffix("/openai")
+    return f"{endpoint}/openai/v1"
+
+
+def _has_openai_chatgpt_auth() -> bool:
+    """Whether OpenAI is available through a stored ChatGPT-plan sign-in."""
+    try:
+        from novacode_cli.config.openai_chatgpt_auth import has_credentials
+
+        return has_credentials()
+    except Exception:  # noqa: BLE001 — provider discovery must not abort startup
+        return False
+
+
+def _openai_auth_available() -> bool:
+    """Honor the selected OpenAI auth mode when gating model construction."""
+    from novacode_cli.config.openai_chatgpt_auth import has_credentials, selected_auth_mode
+
+    mode = selected_auth_mode()
+    has_key = bool(settings.openai_api_key or os.environ.get("OPENAI_API_KEY"))
+    if mode == "api_key":
+        return has_key
+    if mode == "chatgpt":
+        return has_credentials()
+    return has_key or has_credentials()
+
+
+def _opencode_chat_class() -> type:
+    """A ChatOpenAI that drops message fields OpenCode Go's upstreams reject.
+
+    OpenCode Go is a gateway: it routes each model to a different upstream, and
+    some of those refuse a ``name`` on a message with
+
+        400 invalid_request_error — messages[2]: "name" is not supported by
+        this endpoint
+
+    which kills the turn outright. Nova never sets ``name`` itself; LangChain
+    puts it there from the agent/subagent name, where it is traceability
+    metadata rather than anything the model needs. Dropping it costs nothing
+    and removes a whole class of hard failures.
+
+    Scoped to this client, via the one hook that sees the finished payload, so
+    no other provider's requests change — the strictness is OpenCode's, and
+    ``name`` is perfectly legal for OpenAI itself.
+    """
+    from langchain_openai import ChatOpenAI
+
+    class _OpenCodeChat(ChatOpenAI):  # type: ignore[misc]
+        def _get_request_payload(self, input_, *, stop=None, **kwargs):  # noqa: ANN001, ANN202
+            payload = super()._get_request_payload(input_, stop=stop, **kwargs)
+            for message in payload.get("messages", []):
+                if isinstance(message, dict):
+                    message.pop("name", None)
+            return payload
+
+    return _OpenCodeChat
+
+
+def _chatgpt_plan_chat_class() -> type:
+    """Adapt Nova system prompts to the ChatGPT-plan Responses contract."""
+    from langchain_core.messages import ChatMessage, SystemMessage
+    from langchain_openai import ChatOpenAI
+
+    class _ChatGPTPlanChat(ChatOpenAI):  # type: ignore[misc]
+        def _get_request_payload(self, input_, *, stop=None, **kwargs):  # noqa: ANN001, ANN202
+            messages = self._convert_input(input_).to_messages()
+            # The SIWC preview rejects input items with role="system". OpenAI
+            # documents developer messages as the supported equivalent.
+            normalized = [
+                ChatMessage(
+                    role="developer",
+                    content=message.content,
+                    additional_kwargs=message.additional_kwargs,
+                    response_metadata=message.response_metadata,
+                    name=message.name,
+                    id=message.id,
+                )
+                if isinstance(message, SystemMessage)
+                else message
+                for message in messages
+            ]
+            return super()._get_request_payload(normalized, stop=stop, **kwargs)
+
+    return _ChatGPTPlanChat
+
+
+#: Stable for the life of the process — see :func:`opencode_session_id`.
+_OPENCODE_SESSION_ID: str | None = None
+
+
+def opencode_session_id() -> str:
+    """The ``x-opencode-session`` value for the OpenCode Go gateway.
+
+    The gateway rejects requests that omit this header (400 ``MissingSessionID``,
+    "cannot be routed efficiently"), and uses it to route and to key prompt
+    caching. It must therefore stay *stable across a conversation* rather than
+    change per request — a fresh id per call would defeat the cache it exists to
+    enable, which is presumably why the gateway refuses to serve without one.
+
+    One id per Nova process. That is the honest granularity available here: the
+    chat client is constructed once with fixed headers, well before any session
+    is chosen, and it outlives session switches. A Nova run is close enough to
+    one conversation for routing and caching to work.
+
+    Set ``OPENCODE_SESSION_ID`` to pin it — across restarts (so a resumed
+    session keeps its cache) or per pane if you run parallel sessions and want
+    them cached separately.
+    """
+    global _OPENCODE_SESSION_ID
+    pinned = os.environ.get("OPENCODE_SESSION_ID", "").strip()
+    if pinned:
+        return pinned
+    if _OPENCODE_SESSION_ID is None:
+        import uuid
+
+        _OPENCODE_SESSION_ID = f"nova-{uuid.uuid4().hex}"
+    return _OPENCODE_SESSION_ID
+
+
+#: Claude model IDs: family, major, minor (``claude-sonnet-5-5``, ``claude-opus-4-8``).
+#: A dated suffix (``claude-sonnet-4-20250514``) is not a minor version.
+_CLAUDE_VERSION = re.compile(r"claude-(opus|sonnet|haiku|fable|mythos)-(\d+)(?:-(\d{1,2}))?(?=-|@|$)")
+
+
+def _claude_takes_adaptive_thinking(model_name: str) -> bool:
+    """Claude 4.6+ and Fable/Mythos think adaptively; ``budget_tokens`` is a 400
+    on Sonnet 5.5, Sonnet 5, Opus 4.7+, Fable and Haiku 5.5. Older IDs
+    (Haiku 4.5, Sonnet 4.5, ``claude-3-*``) still use a token budget."""
+    match = _CLAUDE_VERSION.search(model_name.lower())
+    if match is None:
+        return False
+    family, major, minor = match.group(1), int(match.group(2)), int(match.group(3) or 0)
+    return family in ("fable", "mythos") or (major, minor) >= (4, 6)
+
+
+def anthropic_thinking_kwargs(model_name: str, effort: str | None, budget: int = 0) -> dict:
+    """ChatAnthropic thinking settings for Nova's ``/effort`` (off/low/medium/high).
+
+    Adaptive models get ``effort`` (``output_config.effort``) with adaptive
+    thinking shown as a summary, so Nova's reasoning stream has text. "off" is
+    the lowest effort rather than disabled thinking, which Opus 5.5, Sonnet 5.5
+    and Fable reject. Older models keep ``budget_tokens``, from the configured
+    ``thinking_budget`` or a per-effort default.
+    """
+    level = effort if effort in ("low", "medium", "high") else None
+    if _claude_takes_adaptive_thinking(model_name):
+        if effort == "off":
+            return {"effort": "low"}
+        if level is None:  # "default": the model's own defaults
+            return {}
+        # Opus/Sonnet 4.6 summarize by default; `display` arrived with 4.7.
+        display = {} if re.search(r"-4-6(?!\d)", model_name) else {"display": "summarized"}
+        return {"effort": level, "thinking": {"type": "adaptive", **display}}
+    if not budget and effort and effort != "off":
+        budget = {"low": 2048, "medium": 4096, "high": 16384}.get(effort, 4096)
+    if budget > 0:
+        return {"thinking": {"type": "enabled", "budget_tokens": budget}}
+    return {}
+
+
+def openai_reasoning_kwargs(model_name: str, effort: str | None, *, summary: bool = False) -> dict:
+    """``reasoning_effort`` for OpenAI reasoning models (o-series, GPT-5 and later).
+
+    langchain-openai sends it as ``reasoning.effort`` on the Responses API.
+    Models without reasoning (gpt-4o, gpt-4.1, ``*-chat``) and o1-mini/o1-preview
+    reject it. "none" and "minimal" are not accepted everywhere (GPT-6 Astra,
+    GPT-6.1 Sol), so "off" is "low", which every reasoning model takes.
+    Summary-capable Responses routes opt in with ``summary=True``.
+    """
+    name = model_name.lower().rsplit("/", 1)[-1]
+    reasoning = re.match(r"(o\d|gpt-([5-9]|\d{2}))", name) and "chat" not in name
+    if not reasoning or name.startswith(("o1-mini", "o1-preview")):
+        return {}
+    if effort == "off":
+        return {"reasoning_effort": "low"}
+    if summary and effort in {"low", "medium", "high"} and not name.startswith("o1"):
+        return {
+            "use_responses_api": True,
+            "store": False,
+            "include": ["reasoning.encrypted_content"],
+            "reasoning": {"effort": effort, "summary": "auto"},
+        }
+    return {"reasoning_effort": effort} if effort in ("low", "medium", "high") else {}
+
+
+def google_thinking_kwargs(model_name: str, effort: str | None) -> dict:
+    """Gemini thinking: ``thinking_level`` on 3.x and later, ``thinking_budget`` on 2.5.
+
+    Sending the other one is an error, and 2.0 has no thinking. Gemini 3 Pro
+    takes only low/high; "off" is "low" on 3.x (3 Pro and 3.1 Pro cannot turn
+    thinking off), a budget of 0 on 2.5 Flash and the 128 minimum on 2.5 Pro.
+    2.5 budgets top out at 24,576 (Flash) and 32,768 (Pro).
+    """
+    name = model_name.lower().rsplit("/", 1)[-1]
+    match = re.search(r"gemini-(\d+)(?:\.(\d+))?", name)
+    if match is None or effort not in ("off", "low", "medium", "high"):
+        return {}
+    version = (int(match.group(1)), int(match.group(2) or 0))
+    if version >= (3, 0):
+        level = "low" if effort == "off" else effort
+        if level == "medium" and "gemini-3-pro" in name:
+            level = "high"
+        return {"thinking_level": level, "include_thoughts": True}
+    if version == (2, 5):
+        pro = "pro" in name
+        if effort == "off":
+            return {"thinking_budget": 128 if pro else 0}
+        budget = {"low": 1024, "medium": 8192, "high": 32768 if pro else 24576}[effort]
+        return {"thinking_budget": budget, "include_thoughts": True}
+    return {}
+
+
+def gateway_reasoning_kwargs(provider: str, model_name: str, effort: str | None) -> dict:
+    """Map verified gateway controls without assuming all models accept effort.
+
+    OpenRouter translates its unified reasoning field across upstream families.
+    Command Code and OpenCode use OpenAI-shaped effort for GPT and DeepSeek V4.
+    On those gateways ``off`` requests minimum effort, not disabled thinking.
+    Unknown families keep provider defaults rather than receiving guessed fields.
+    """
+    if effort not in {"off", "low", "medium", "high"}:
+        return {}
+    if provider == "openrouter":
+        return {"extra_body": {"reasoning": {"effort": "low" if effort == "off" else effort}}}
+    kwargs = openai_reasoning_kwargs(model_name, effort)
+    name = model_name.lower().rsplit("/", 1)[-1]
+    if not kwargs and name.startswith("deepseek-v4"):
+        return {"reasoning_effort": "low" if effort in {"off", "low"} else "high"}
+    return kwargs
+
+
+def reasoning_setting_note(  # noqa: PLR0911 — each provider has a different control
+    provider: str | None, model_name: str, effort: str | None
+) -> str:
+    """Describe the configured control honestly, including model limitations."""
+    if not effort or effort == "default":
+        return "Using the provider's default reasoning settings."
+    name = model_name.lower().rsplit("/", 1)[-1]
+    if provider == "nvidia":
+        return "NVIDIA uses a model-specific thinking toggle; low/medium/high all enable it."
+    if provider == "ollama":
+        return (
+            "Ollama receives reasoning_effort (off → none); support depends on the installed model."
+        )
+    if provider == "google" and google_thinking_kwargs(model_name, effort):
+        return (
+            "Gemini receives its version-specific thinking level or budget; "
+            "some models cannot disable thinking."
+        )
+    if name.startswith("claude-") and provider in {
+        "anthropic",
+        "commandcode",
+        "opencode",
+        "opencode_zen",
+    }:
+        return (
+            "Claude receives adaptive effort or a thinking budget; "
+            "off uses minimum effort on adaptive models."
+        )
+    if provider == "openrouter":
+        return (
+            "OpenRouter receives unified reasoning effort; off requests low. "
+            "Upstream model support varies."
+        )
+    if openai_reasoning_kwargs(model_name, effort):
+        return (
+            "The model receives reasoning effort; off requests low "
+            "because some models cannot disable thinking."
+        )
+    if provider in {"commandcode", "opencode", "opencode_zen"} and name.startswith("deepseek-v4"):
+        return "DeepSeek V4 receives low/high effort (medium → high, off → low)."
+    return (
+        "No verified configurable effort control for this model/route; "
+        "provider defaults remain in effect."
+    )
+
+
+def build_chat_model(
+    provider: str, model_name: str, *, reasoning_effort: str | None = None,
+    max_retries: int | None = None,
+) -> BaseChatModel:
+    """Build a provider model, with an optional per-route effort override.
+
+    The override uses the same capability mappings as the session setting and
+    never saves a new global preference.
+    """
+    if max_retries is not None:
+        # Factory calls must reserve capacity separately for every retry.
+        model = _build_chat_model(
+            provider, model_name, reasoning_effort=reasoning_effort, max_retries=max_retries
+        )
+    else:
+        model = (
+            _build_chat_model(provider, model_name, reasoning_effort=reasoning_effort)
+            if reasoning_effort is not None else _build_chat_model(provider, model_name)
+        )
+    # Lossless model identity for new worker processes; never infer a gateway
+    # provider from its OpenAI-compatible model class or change its defaults.
+    model.metadata = {**(model.metadata or {}), "nova_provider": provider, "nova_model": model_name}
+    from novacode_cli.tracking.usage_tree import attach_usage_callback
+
+    attach_usage_callback(model)
+    if os.environ.get("NOVA_LOCAL_METRICS") == "1":
+        from novacode_cli.tracking.local_metrics import callbacks
+
+        model.callbacks = [*(getattr(model, "callbacks", None) or []), *callbacks()]
+    return model
+
+
+def ollama_openai_base_url() -> str:
+    """Ollama's OpenAI-compatible endpoint, from ``OLLAMA_HOST`` (default local).
+
+    ``OLLAMA_HOST`` is the variable the ``ollama`` CLI itself reads, and it is
+    often written without a scheme (``127.0.0.1:11434``) or as the bind address
+    ``0.0.0.0``, which is not somewhere a client can connect to.
+    """
+    host = (os.environ.get("OLLAMA_HOST") or "").strip().rstrip("/") or "http://localhost:11434"
+    if "://" not in host:
+        host = f"http://{host}"
+    host = host.replace("://0.0.0.0", "://localhost")
+    if host.endswith("/v1"):
+        return host
+    return f"{host}/v1"
+
+
+def _build_chat_model(
+    provider: str, model_name: str, *, reasoning_effort: str | None = None,
+    max_retries: int = 5,
+) -> BaseChatModel:
+    """THE model constructor — every ChatX(...) in Nova is built here.
+
+    One deep module for provider construction: reasoning-effort / thinking
+    budgets, retries, Ollama num_ctx + content-block patch, OpenRouter base
+    URL. Key-presence *policy* stays with the callers (return None / warn and
+    fall back / raise) — this function only constructs.
+
+    Args:
+        provider: "ollama" | "openai" | "anthropic" | "google" | "openrouter" | "opencode".
+        model_name: The model identifier for that provider.
+
+    Raises:
+        ValueError: Unknown provider.
+    """
+    from novacode_cli.config.nova_config import NovaConfig
+
+    nova_config = NovaConfig()
+    effort = reasoning_effort if reasoning_effort is not None else nova_config.get("reasoning_effort")
+
+    if provider in CATALOG_PROVIDERS:
+        from novacode_cli.config.catalog_models import build_catalog_model
+
+        return build_catalog_model(provider, model_name, max_retries=max_retries)
+
+    if provider == "ollama":
+        # Ollama is driven through its OpenAI-compatible endpoint (`/v1`) with
+        # the OpenAI client — the same path as every other OpenAI-compatible
+        # provider here, and how OpenCode talks to Ollama.
+        #
+        # What that changes, all checked against a live server (2026-10-11):
+        # - Thinking is switched off with `reasoning_effort="none"`; the native
+        #   `think: false` is ignored on this endpoint.
+        # - A reply is capped with `max_tokens` (a cut-off reply reports
+        #   finish_reason "length"). Uncapped, a thinking model can run away:
+        #   ~394k tokens in one reply, then an empty turn.
+        # - `num_ctx` cannot be sent. Ollama's cloud ignored it anyway. For a
+        #   LOCAL model the server's own setting now applies, so that has to be
+        #   large enough: start the server with OLLAMA_CONTEXT_LENGTH set, or
+        #   bake `num_ctx` into the model with a Modelfile. Nova still reads the
+        #   context Ollama actually allocated (`ollama ps`) to size its window.
+        # - `keep_alive` cannot be sent either; the server's default applies.
+        from langchain_openai import ChatOpenAI
+
+        from novacode_cli.utils.backend_patches import (
+            apply_openai_reasoning_content_patch,
+        )
+
+        apply_openai_reasoning_content_patch()
+
+        ollama_kwargs: dict = {}
+        if effort:
+            ollama_kwargs["reasoning_effort"] = "none" if effort == "off" else effort
+
+        return ChatOpenAI(
+            model=model_name,
+            base_url=ollama_openai_base_url(),
+            # The local server needs no key; the client refuses to start without
+            # one. A real key is only used when pointing straight at a hosted API.
+            api_key=os.environ.get("OLLAMA_API_KEY") or "ollama",
+            temperature=0,
+            # Sent as a raw `max_tokens`, NOT through the client's own field: the
+            # client renames that to `max_completion_tokens`, which Ollama
+            # accepts and ignores — a limit of 25 produced an 800-token reply.
+            extra_body={"max_tokens": nova_config.get("max_tokens", 16384)},
+            max_retries=max_retries,
+            # Token usage is only streamed back when asked for, and the client
+            # does not ask by default for a custom base URL.
+            stream_usage=True,
+            **ollama_kwargs,
+        )
+
+    if provider == "commandcode":
+        # Command Code's Provider API: Claude models are served only on the
+        # Anthropic Messages route (400 elsewhere), every other model on Chat
+        # Completions. The public /models list confirms the split by prefix.
+        from novacode_cli.config.model_manager import COMMANDCODE_BASE_URL
+
+        from novacode_cli.config.nova_config import _config_bool
+
+        api_key = settings.commandcode_api_key or os.environ.get("COMMANDCODE_API_KEY")
+        # Zero data retention, switched in /auth: only ZDR-capable upstreams
+        # serve the request, and a model with none fails with 422 instead.
+        zdr = {"x-cmd-zdr": "1"} if _config_bool(nova_config.get("commandcode_zdr", False)) else {}
+        if model_name.lower().startswith("claude-"):
+            from langchain_anthropic import ChatAnthropic
+
+            budget = nova_config.get("thinking_budget", 0) or 0
+            return ChatAnthropic(
+                model_name=model_name,
+                api_key=api_key,
+                # The SDK appends /v1/messages itself.
+                base_url=COMMANDCODE_BASE_URL.removesuffix("/v1"),
+                default_headers=zdr,
+                max_tokens=20_000,  # type: ignore[arg-type]
+                max_retries=max_retries,
+                **anthropic_thinking_kwargs(model_name, effort, int(budget)),
+            )
+        from novacode_cli.utils.backend_patches import apply_openai_reasoning_content_patch
+
+        apply_openai_reasoning_content_patch()
+        # A gateway to many upstreams, like OpenCode: drop `name` on messages.
+        return _opencode_chat_class()(
+            model=model_name,
+            api_key=api_key,
+            base_url=COMMANDCODE_BASE_URL,
+            default_headers=zdr,
+            max_retries=max_retries,
+            stream_usage=True,
+            **gateway_reasoning_kwargs(provider, model_name, effort),
+        )
+
+    from novacode_cli.config.model_manager import OPENAI_COMPATIBLE_PROVIDERS
+
+    if provider in OPENAI_COMPATIBLE_PROVIDERS or provider == "azure":
+        # Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi For Coding and Azure's
+        # v1 API all take OpenAI Chat Completions at their own URL. `name` on a
+        # message is dropped, as for the gateways: Groq and Hugging Face's
+        # upstreams refuse it, and it is metadata the model never needs.
+        from novacode_cli.config.model_manager import provider_api_key, provider_base_url
+        from novacode_cli.utils.backend_patches import apply_openai_reasoning_content_patch
+
+        apply_openai_reasoning_content_patch()
+        if provider == "azure":
+            base_url = azure_base_url()
+            reasoning = openai_reasoning_kwargs(model_name, effort, summary=True)
+        else:
+            base_url = provider_base_url(provider)
+            reasoning = {}
+        return _opencode_chat_class()(
+            model=model_name,
+            api_key=provider_api_key(provider),
+            base_url=base_url,
+            max_retries=max_retries,
+            stream_usage=True,
+            **reasoning,
+        )
+
+    if provider == "minimax":
+        # MiniMax serves its models on an Anthropic-compatible Messages API.
+        from langchain_anthropic import ChatAnthropic
+
+        from novacode_cli.config.model_manager import provider_api_key, provider_base_url
+
+        return ChatAnthropic(
+            model_name=model_name,
+            api_key=provider_api_key(provider),
+            base_url=provider_base_url(provider),
+            max_tokens=20_000,  # type: ignore[arg-type]
+            max_retries=max_retries,
+        )
+
+    if provider == "bedrock":
+        # Credentials come from boto3's usual chain: AWS_BEARER_TOKEN_BEDROCK (a
+        # Bedrock API key, which /auth stores), AWS_ACCESS_KEY_ID, a profile or a role.
+        try:
+            from langchain_aws import ChatBedrockConverse
+        except ImportError as exc:  # pragma: no cover - install-time path
+            from novacode_cli.install_commands import install_command
+
+            command = install_command(["langchain-aws"], "bedrock")
+            raise RuntimeError(
+                "The Bedrock provider needs the langchain-aws package, which is not "
+                f"installed in this environment. Install it with:\n\n    {command}\n\n"
+                "then restart Nova and run /model again."
+            ) from exc
+
+        region = os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION") or "us-east-1"
+        bedrock_options = {}
+        if max_retries != 5:
+            from botocore.config import Config
+
+            bedrock_options["config"] = Config(retries={"total_max_attempts": max_retries + 1})
+        return ChatBedrockConverse(
+            model=model_name,
+            region_name=region,
+            max_tokens=nova_config.get("max_tokens", 16384),
+            **bedrock_options,
+        )
+
+    if provider in ("openai", "openrouter", "opencode", "opencode_zen"):
+        from langchain_openai import ChatOpenAI
+
+        from novacode_cli.utils.backend_patches import (
+            apply_openai_reasoning_content_patch,
+        )
+
+        # Thinking models (DeepSeek, GLM) require their reasoning_content to be
+        # sent back on the next turn; LangChain drops it. Applied for every
+        # OpenAI-compatible provider because the patch only acts on messages
+        # that actually carry the field.
+        apply_openai_reasoning_content_patch()
+
+        openai_kwargs: dict = (
+            openai_reasoning_kwargs(model_name, effort) if provider == "openai"
+            else gateway_reasoning_kwargs(provider, model_name, effort)
+        )
+        if provider == "openrouter":
+            # OpenRouter is OpenAI-compatible: same client, custom base URL + key.
+            from novacode_cli.config.model_manager import OPENROUTER_BASE_URL
+
+            openai_kwargs["base_url"] = OPENROUTER_BASE_URL
+            # Resolve via settings (keyring-or-env) then env — a key saved to the
+            # system keychain is NOT in os.environ on a fresh session, so reading
+            # os.environ alone left the model with api_key=None on every restart.
+            openai_kwargs["api_key"] = settings.openrouter_api_key or os.environ.get(
+                "OPENROUTER_API_KEY"
+            )
+        elif provider in {"opencode", "opencode_zen"}:
+            # OpenCode Go is OpenAI-compatible: same client, custom base URL + key.
+            from novacode_cli.config.model_manager import MODEL_PRESETS
+            from novacode_cli.config.opencode_gateway import headers, protocol
+
+            openai_kwargs["base_url"] = MODEL_PRESETS[provider]["base_url"]
+            # Keyring-aware (see openrouter note): os.environ alone was empty on a
+            # restart even with the key saved, so OpenCode silently 401'd.
+            openai_kwargs["api_key"] = getattr(settings, f"{provider}_api_key", None) or os.environ.get(
+                PROVIDER_KEY_ENV[provider]
+            )
+            # The gateway REJECTS requests without this header — every call
+            # fails with 400 MissingSessionID — so it is not optional.
+            openai_kwargs["default_headers"] = headers(opencode_session_id())
+            api = protocol(provider, model_name)
+            if api == "unsupported":
+                raise ValueError("This OpenCode model uses an API not supported by the chat provider.")
+            if api == "messages":
+                from langchain_anthropic import ChatAnthropic
+                thinking_kwargs = (
+                    anthropic_thinking_kwargs(
+                        model_name, effort, int(nova_config.get("thinking_budget", 0) or 0)
+                    ) if model_name.lower().startswith("claude-") else {}
+                )
+                return ChatAnthropic(
+                    model=model_name, api_key=openai_kwargs["api_key"],
+                    base_url=openai_kwargs["base_url"],
+                    default_headers=openai_kwargs["default_headers"],
+                    max_tokens=20_000, max_retries=max_retries,
+                    **thinking_kwargs,
+                )
+            if api == "responses":
+                openai_kwargs.update(use_responses_api=True, store=False)
+        else:
+            # Plain OpenAI: same keyring-or-env resolution as the gateways above.
+            # Without this, a key held only in the system keychain passed the
+            # caller's has-key gate but never reached the client, so ChatOpenAI
+            # raised "api_key must be set" instead of working.
+            openai_key = settings.openai_api_key or os.environ.get("OPENAI_API_KEY")
+            from novacode_cli.config.openai_chatgpt_auth import (
+                has_credentials,
+                selected_auth_mode,
+            )
+
+            auth_mode = selected_auth_mode()
+            if auth_mode == "chatgpt":
+                if not has_credentials():
+                    raise ValueError("ChatGPT sign-in is selected for OpenAI. Connect it in /auth.")
+                openai_key = None
+            if openai_key:
+                openai_kwargs["api_key"] = openai_key
+            # Custom OpenAI-compatible endpoint (Azure, LM Studio, vLLM, a
+            # LiteLLM proxy…). Saved by /model, overridable per-shell via
+            # OPENAI_BASE_URL. Without this, ChatOpenAI always went to
+            # api.openai.com and a self-hosted endpoint was unreachable.
+            base_url = None
+            try:
+                base_url = nova_config.get_model_base_url()
+            except Exception:  # noqa: BLE001 — config is best-effort here
+                base_url = None
+            base_url = base_url or os.environ.get("OPENAI_BASE_URL")
+            if auth_mode == "chatgpt":
+                # ChatGPT-plan tokens are valid only for OpenAI's public
+                # Responses endpoint, regardless of a saved custom API URL.
+                base_url = None
+            if auth_mode == "api_key" and not openai_key and not base_url:
+                raise ValueError("OpenAI API-key auth is selected, but no API key is configured.")
+            if base_url:
+                openai_kwargs["base_url"] = base_url
+                # A local endpoint usually ignores the key but the client still
+                # demands one; send a placeholder so it doesn't refuse to start.
+                openai_kwargs.setdefault("api_key", "not-needed")
+            elif not openai_key and auth_mode in {"auto", "chatgpt"}:
+                # ChatGPT plan credentials are separate from API keys and are
+                # accepted only on the public Responses API route.
+                from novacode_cli.config.openai_chatgpt_auth import (
+                    has_credentials,
+                    http_clients,
+                )
+
+                if has_credentials():
+                    sync_client, async_client = http_clients()
+
+                    openai_kwargs.update(
+                        api_key="chatgpt-plan-token-managed-per-request",
+                        use_responses_api=True,
+                        streaming=True,
+                        store=False,
+                        http_client=sync_client,
+                        http_async_client=async_client,
+                    )
+
+        # Public OpenAI exposes reasoning summaries only through Responses.
+        # Preserve Chat Completions on custom endpoints and gateways unless
+        # their model route already explicitly selected Responses.
+        summary_kwargs = openai_reasoning_kwargs(model_name, effort, summary=True)
+        public_openai = provider == "openai" and openai_kwargs.get("base_url") in {
+            None,
+            "https://api.openai.com/v1",
+            "https://api.openai.com/v1/",
+        }
+        if (
+            "reasoning" in summary_kwargs
+            and "reasoning_effort" in openai_kwargs
+            and (public_openai or openai_kwargs.get("use_responses_api"))
+        ):
+            openai_kwargs.pop("reasoning_effort", None)
+            openai_kwargs.update(summary_kwargs)
+
+        if provider in {"opencode", "opencode_zen"}:
+            return _opencode_chat_class()(
+                model=model_name, max_retries=max_retries, **openai_kwargs
+            )
+        if openai_kwargs.get("use_responses_api"):
+            return _chatgpt_plan_chat_class()(model=model_name, max_retries=max_retries, **openai_kwargs)
+        return ChatOpenAI(model=model_name, max_retries=max_retries, **openai_kwargs)
+
+    if provider == "nvidia":
+        # NVIDIA NIM (build.nvidia.com). Its own client rather than ChatOpenAI:
+        # ChatNVIDIA handles NIM's model-listing and payload quirks, and takes
+        # NIM-specific options (chat_template_kwargs) that ChatOpenAI drops.
+        try:
+            from langchain_nvidia_ai_endpoints import ChatNVIDIA
+        except ImportError as exc:  # pragma: no cover - install-time path
+            # A bare ModuleNotFoundError here reads as a Nova bug rather
+            # than a missing package, and leaves the user with no next
+            # step. Nova installs pull this in; a pre-existing
+            # environment upgraded in place will not have it.
+            from novacode_cli.install_commands import install_command
+
+            command = install_command(["langchain-nvidia-ai-endpoints"])
+            raise RuntimeError(
+                "The NVIDIA provider needs the langchain-nvidia-ai-endpoints "
+                "package, which is not installed in this environment. "
+                f"Install it with:\n\n    {command}\n\n"
+                "then restart Nova and run /model again."
+            ) from exc
+
+        # Keyring-or-env, never a literal: same resolution as every other
+        # provider here, so a key stored in the system keychain still reaches
+        # the client on a fresh session (os.environ alone is empty there).
+        nvidia_key = settings.nvidia_api_key or os.environ.get("NVIDIA_API_KEY")
+
+        nvidia_kwargs: dict = {}
+        if nvidia_key:
+            nvidia_kwargs["api_key"] = nvidia_key
+        # A self-hosted NIM container speaks the same API on a different host.
+        nvidia_base = os.environ.get("NVIDIA_BASE_URL")
+        if nvidia_base:
+            nvidia_kwargs["base_url"] = nvidia_base
+
+        # Reasoning models on NIM gate their chain-of-thought behind a
+        # per-request template flag. Nova surfaces reasoning as its own event
+        # stream, so follow the session's /effort setting: off -> no thinking.
+        #
+        # Passed inside model_kwargs, not as a top-level argument. ChatNVIDIA
+        # does not declare chat_template_kwargs as a field, so a top-level one
+        # is relocated here anyway — with a warning on every model build telling
+        # the user to "confirm that chat_template_kwargs is what you intended".
+        # Both routes produce a byte-identical request payload; this one is
+        # simply the declared way to say it.
+        if effort:
+            nvidia_kwargs["model_kwargs"] = {
+                "chat_template_kwargs": {"thinking": effort != "off"}
+            }
+
+        return ChatNVIDIA(
+            model=model_name,
+            temperature=nova_config.get("temperature", 1.0),
+            top_p=nova_config.get("top_p", 0.95),
+            max_tokens=nova_config.get("max_tokens", 16384),
+            **nvidia_kwargs,
+        )
+
+    if provider == "anthropic":
+        from langchain_anthropic import ChatAnthropic
+
+        thinking_budget = nova_config.get("thinking_budget", 0) or int(
+            os.environ.get("Nova_THINKING_BUDGET", "0")
+        )
+        thinking_kwargs = anthropic_thinking_kwargs(model_name, effort, int(thinking_budget or 0))
+
+        return ChatAnthropic(
+            model_name=model_name,
+            max_tokens=20_000,  # type: ignore[arg-type]
+            max_retries=max_retries,
+            **thinking_kwargs,
+        )
+
+    if provider == "google":
+        from langchain_google_genai import ChatGoogleGenerativeAI
+
+        from novacode_cli.config.google_oauth_auth import (
+            GoogleOAuthAuth,
+            has_credentials,
+            use_oauth,
+        )
+
+        google_kwargs: dict = {}
+        google_key = (os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY")
+                      or settings.google_api_key)
+        oauth_selected = use_oauth(has_key=bool(google_key))
+        if oauth_selected:
+            if not has_credentials():
+                raise ValueError("Google sign-in is selected but missing. Reconnect through /auth.")
+            # The SDK currently requires an API-key constructor argument for
+            # Developer API. HTTPX replaces this non-secret placeholder with
+            # real OAuth bearer auth on every sync/async/streaming request.
+            google_kwargs.update(
+                google_api_key="nova-oauth-managed",
+                vertexai=False,
+                base_url="https://generativelanguage.googleapis.com/",
+            )
+        google_kwargs.update(google_thinking_kwargs(model_name, effort))
+
+        model = ChatGoogleGenerativeAI(
+            model=model_name,
+            temperature=0,
+            max_tokens=None,
+            max_retries=max_retries,
+            **google_kwargs,
+        )
+        if oauth_selected:
+            import httpx
+            from google import genai
+            from google.genai.types import HttpOptions
+            # Explicit HTTPX clients prevent the SDK's optional aiohttp path
+            # bypassing OAuth. Both streaming and non-streaming use these.
+            model.client.close()
+            model.client = genai.Client(
+                vertexai=False, api_key="nova-oauth-managed",
+                http_options=HttpOptions(
+                    base_url="https://generativelanguage.googleapis.com/",
+                    api_version=model.api_version,
+                    httpx_client=httpx.Client(auth=GoogleOAuthAuth(), timeout=300),
+                    httpx_async_client=httpx.AsyncClient(auth=GoogleOAuthAuth(), timeout=300),
+                ),
+            )
+        return model
+
+    raise ValueError(f"Unknown provider: {provider}")
+
+
+def create_model_from_config(provider: str, model_name: str) -> BaseChatModel | None:
+    """Create a model instance from a provider and model name (no fallback).
+
+    Unlike :func:`create_model`, this function only tries the exact provider/model
+    requested and returns ``None`` if the required API key is missing — it never
+    falls back to another provider. This is used for the on-demand vision model.
+
+    Args:
+        provider: An Ollama, OpenAI, Anthropic, Google, OpenRouter or OpenCode provider.
+        model_name: The model name/identifier.
+
+    Returns:
+        A ``BaseChatModel`` instance, or ``None`` if the provider cannot be used.
+    """
+    key_var = PROVIDER_KEY_ENV.get(provider)
+    if provider in CATALOG_PROVIDERS:
+        from novacode_cli.config.provider_auth import get_provider_auth_status
+
+        if not get_provider_auth_status(provider).is_usable:
+            return None
+        try:
+            return build_chat_model(provider, model_name)
+        except ValueError:
+            return None
+    if key_var:
+        # Keyring-aware: a key saved to the system keychain is absent from
+        # os.environ on a fresh session, so an env-only check wrongly returned
+        # None on restart (settings.<provider>_api_key resolves keychain-or-env).
+        has_key = os.environ.get(key_var) or getattr(settings, f"{provider}_api_key", None)
+        if provider == "openai":
+            has_key = _openai_auth_available()
+        elif provider == "google":
+            from novacode_cli.config.provider_auth import get_provider_auth_status
+            has_key = get_provider_auth_status("google").is_usable
+        if not has_key:
+            return None
+    try:
+        return build_chat_model(provider, model_name)
+    except ValueError:
+        return None  # unknown provider
+
+
+def create_model_for_session(
+    provider: str | None,
+    model_name: str | None,
+) -> tuple[BaseChatModel | None, str | None]:
+    """Rebuild the model a resumed session was using.
+
+    A session records the provider and model it ran on, so resuming should
+    restore that model rather than silently adopting whatever the global config
+    says now. This tries the exact recorded pair and reports why it could not be
+    rebuilt, so the caller can warn and fall back instead of failing to resume.
+
+    Args:
+        provider: Provider recorded on the session, or None for sessions saved
+            before the provider was recorded.
+        model_name: Model recorded on the session.
+
+    Returns:
+        ``(model, warning)``:
+        - ``(None, None)`` — nothing to restore (a legacy session, or no model
+          recorded). The caller should use :func:`create_model` silently.
+        - ``(model, None)`` — the session's model was rebuilt.
+        - ``(None, warning)`` — the session's model could not be rebuilt; the
+          caller should surface ``warning`` and fall back to :func:`create_model`.
+    """
+    if not provider or not model_name:
+        # Legacy session: the provider was not recorded, so the exact model
+        # cannot be rebuilt. Not an error — fall back without warning.
+        return None, None
+
+    model = create_model_from_config(provider, model_name)
+    if model is not None:
+        return model, None
+
+    key_var = PROVIDER_KEY_ENV.get(provider)
+    if provider in CATALOG_PROVIDERS:
+        from novacode_cli.config.provider_auth import get_provider_auth_status
+
+        status = get_provider_auth_status(provider)
+        reason = (
+            status.detail if not status.is_usable
+            else f"provider '{provider}' or model is unavailable"
+        )
+    elif key_var and not (
+        os.environ.get(key_var) or getattr(settings, f"{provider}_api_key", None)
+    ):
+        has_chatgpt_login = _openai_auth_available() if provider == "openai" else False
+        reason = (
+            "OpenAI ChatGPT sign-in is missing"
+            if provider == "openai" and not has_chatgpt_login
+            else f"{key_var} is not set"
+        )
+    else:
+        reason = f"provider '{provider}' is unavailable"
+    return None, (
+        f"This session used {provider}:{model_name}, but it could not be restored "
+        f"({reason}). Falling back to the configured default model."
+    )
+
+
+def create_model() -> BaseChatModel:
+    """Create the appropriate model based on available API keys.
+
+    Priority order:
+    1. Saved configuration from Nova.config.json (highest priority)
+    2. Environment variables from .env file
+    3. Default to Ollama (fallback)
+
+    Returns:
+        ChatModel instance (OpenAI, Anthropic, Google, OpenRouter, or Ollama)
+    """
+    # Load saved configuration - this takes precedence over .env
+    from novacode_cli.config.nova_config import NovaConfig
+    from novacode_cli.config.provider_auth import get_provider_auth_status
+
+    nova_config = NovaConfig()
+    saved_model_config = nova_config.get_model_config()
+
+    # If we have a saved config, use it directly (bypasses .env settings).
+    # Missing key for the saved provider → warn and fall through to the
+    # env-priority chain below (same as the pre-consolidation behavior).
+    if saved_model_config:
+        provider = saved_model_config["provider"]
+        model_name = saved_model_config["model"]
+        key_var = PROVIDER_KEY_ENV.get(provider)
+        available = (
+            _openai_auth_available()
+            if provider == "openai"
+            else bool(key_var and os.environ.get(key_var))
+        )
+        if provider == "google":
+            from novacode_cli.config.provider_auth import get_provider_auth_status
+            available = get_provider_auth_status("google").is_usable
+        elif provider in CATALOG_PROVIDERS:
+            available = get_provider_auth_status(provider).is_usable
+        if (key_var or provider in CATALOG_PROVIDERS) and not available:
+            if provider in CATALOG_PROVIDERS:
+                detail = get_provider_auth_status(provider).detail or "provider unavailable"
+                console.print(
+                    f"[yellow]Warning: {provider}: {detail}; falling back to Ollama[/yellow]"
+                )
+            else:
+                console.print(
+                    f"[yellow]Warning: {key_var} not set, falling back to Ollama[/yellow]"
+                )
+        else:
+            return build_chat_model(provider, model_name)
+
+    # No usable saved config — pick the first provider with a key configured.
+    _ENV_PRIORITY = [
+        (
+            settings.has_openai or _openai_auth_available(),
+            "openai",
+            "OPENAI_MODEL",
+            "gpt-5-mini",
+            "OpenAI",
+        ),
+        (
+            settings.has_anthropic,
+            "anthropic",
+            "ANTHROPIC_MODEL",
+            "claude-sonnet-4-5-20250929",
+            "Anthropic",
+        ),
+        (get_provider_auth_status("google").is_usable,
+         "google", "GOOGLE_MODEL", "gemini-3-pro-preview", "Google Gemini"),
+        (
+            settings.has_openrouter,
+            "openrouter",
+            "OPENROUTER_MODEL",
+            "anthropic/claude-3.5-sonnet",
+            "OpenRouter",
+        ),
+        (
+            settings.has_opencode,
+            "opencode",
+            "OPENCODE_MODEL",
+            "glm-5.3",
+            "OpenCode Go",
+        ),
+        (settings.has_opencode_zen, "opencode_zen", "OPENCODE_ZEN_MODEL", "big-pickle", "OpenCode Zen"),
+        (
+            settings.has_commandcode,
+            "commandcode",
+            "COMMANDCODE_MODEL",
+            "deepseek/deepseek-v4-flash",
+            "Command Code",
+        ),
+        (
+            settings.has_nvidia,
+            "nvidia",
+            "NVIDIA_MODEL",
+            "deepseek-ai/deepseek-v4-pro-0813",
+            "NVIDIA NIM",
+        ),
+    ]
+    for available, provider, model_env, default_model, label in _ENV_PRIORITY:
+        if available:
+            model_name = os.environ.get(model_env, default_model)
+            console.print(f"[dim]Using {label} model: {model_name}[/dim]")
+            return build_chat_model(provider, model_name)
+
+    # Then the providers that only need a key. Azure also needs an endpoint and
+    # Bedrock may have no key at all, so both wait for an explicit /model pick.
+    from novacode_cli.config.model_manager import MODEL_PRESETS, OPENAI_COMPATIBLE_PROVIDERS
+
+    for provider in sorted(OPENAI_COMPATIBLE_PROVIDERS | {"minimax"}):
+        # New gateways and regional variants need an explicit /model choice;
+        # sharing a credential name never authorizes selecting a new origin.
+        if provider in CATALOG_PROVIDERS:
+            continue
+        preset = MODEL_PRESETS[provider]
+        if os.environ.get(preset["api_key_var"]):
+            model_name = os.environ.get(preset["env_var"], preset["default_model"])
+            console.print(f"[dim]Using {preset['name']} model: {model_name}[/dim]")
+            return build_chat_model(provider, model_name)
+
+    # Default to Ollama if no API keys are configured
+    from novacode_cli.config.model_manager import DEFAULT_OLLAMA_MODEL
+
+    model_name = os.environ.get("OLLAMA_MODEL", DEFAULT_OLLAMA_MODEL)
+    console.print(f"[dim]No API keys configured. Defaulting to Ollama model: {model_name}[/dim]")
+    return build_chat_model("ollama", model_name)
+
+
+# =============================================================================
+# Vision Model Registry
+# =============================================================================
+
+# Models known to support vision/multimodal capabilities
+VISION_CAPABLE_MODELS: dict[str, bool] = {
+    # Anthropic - Claude 3+ models support vision
+    "claude-sonnet-4-5-20250929": True,
+    "claude-opus-4-5-20251001": True,
+    "claude-3-5-sonnet-20241022": True,
+    "claude-3-5-sonnet-20240620": True,
+    "claude-3-5-haiku-20241022": True,
+    "claude-3-opus-20240229": True,
+    "claude-3-sonnet-20240229": True,
+    "claude-3-haiku-20240307": True,
+    # OpenAI - GPT-4 Vision models
+    "gpt-4o": True,
+    "gpt-4o-mini": True,
+    "gpt-4-turbo": True,
+    "gpt-4-vision-preview": True,
+    "gpt-4-turbo-2024-04-09": True,
+    # Google - Gemini 1.5+ models
+    "gemini-1.5-pro": True,
+    "gemini-1.5-flash": True,
+    "gemini-2.0-flash-exp": True,
+    "gemini-3-pro-preview": True,
+    # Ollama vision models (common ones)
+    "llava": True,
+    "llava:7b": True,
+    "llava:13b": True,
+    "llava:34b": True,
+    "bakllava": True,
+    "moondream": True,
+    "moondream2": True,
+    "llava-llama3": True,
+    "llava-phi3": True,
+    "minicpm-v": True,
+    # User's preferred model
+    "qwen3-vl:235b-cloud": True,
+    "qwen2-vl": True,
+    "qwen2-vl:7b": True,
+    "qwen2-vl:72b": True,
+}
+
+# Keywords that indicate vision capability in model names
+VISION_KEYWORDS = [
+    "vision",
+    "multimodal",
+    "mm",
+    "llava",
+    "bakllava",
+    "moondream",
+    "-vl",
+    "-v",
+    "minicpm-v",
+    "qwen-vl",
+    "qwen2-vl",
+    "qwen3-vl",
+]
+
+
+def model_supports_vision(model_name: str) -> bool:
+    """Check if a model supports vision/multimodal capabilities.
+
+    Args:
+        model_name: Name of the model
+
+    Returns:
+        True if model supports vision, False otherwise
+    """
+    # Normalize model name for comparison
+    model_lower = model_name.lower()
+
+    # Check registry first (exact match)
+    if model_name in VISION_CAPABLE_MODELS:
+        return VISION_CAPABLE_MODELS[model_name]
+
+    # Check registry with lowercase
+    if model_lower in VISION_CAPABLE_MODELS:
+        return VISION_CAPABLE_MODELS[model_lower]
+
+    # For unknown models, check if name contains vision keywords
+    return any(keyword in model_lower for keyword in VISION_KEYWORDS)
+
+
+def get_vision_model_suggestion(current_model: str) -> str | None:
+    """Suggest a vision-capable model if current model doesn't support vision.
+
+    Args:
+        current_model: Current model name
+
+    Returns:
+        Suggested model name or None if current model supports vision
+    """
+    if model_supports_vision(current_model):
+        return None  # Current model already supports vision
+
+    # Suggest best available model based on configured providers
+    if settings.has_anthropic:
+        return "claude-sonnet-4-5-20250929"
+    if settings.has_openai:
+        return "gpt-4o"
+    if settings.has_google:
+        return "gemini-1.5-pro"
+    # Default to Ollama vision model
+    return "qwen3-vl:235b-cloud"
+
+
+def get_current_model_name() -> str:
+    """Get the name of the currently configured model.
+
+    Returns:
+        Model name string
+    """
+    from novacode_cli.config.nova_config import NovaConfig
+
+    nova_config = NovaConfig()
+    saved_config = nova_config.get_model_config()
+
+    if saved_config:
+        return saved_config["model"]
+
+    # Check environment variables
+    if settings.has_openai:
+        return os.environ.get("OPENAI_MODEL", "gpt-5-mini")
+    if settings.has_anthropic:
+        return os.environ.get("ANTHROPIC_MODEL", "claude-sonnet-4-5-20250929")
+    if settings.has_google:
+        return os.environ.get("GOOGLE_MODEL", "gemini-3-pro-preview")
+    from novacode_cli.config.model_manager import DEFAULT_OLLAMA_MODEL
+
+    return os.environ.get("OLLAMA_MODEL", DEFAULT_OLLAMA_MODEL)
+
+
+# ── async-agent graphs ────────────────────────────────────────────────────────
+#
+# The six remote graphs (agents/async_agents/*.py, hosted by the LangGraph server) used to
+# build ``ChatOllama`` themselves, in six near-identical copies, so the model behind
+# background work was an Ollama decision. They now delegate here, which is also how
+# they inherit every provider quirk this module already handles.
+
+#: Which provider the async-agent graphs build their model with.
+ASYNC_AGENT_PROVIDER_ENV = "ASYNC_AGENT_PROVIDER"
+
+#: Model id for those graphs, falling back to the older DOC_AGENT_MODEL.
+ASYNC_AGENT_MODEL_ENV = "ASYNC_AGENT_MODEL"
+
+#: Providers an async graph may run on: Ollama plus everything with a key variable.
+VALID_ASYNC_PROVIDERS: tuple[str, ...] = tuple(
+    dict.fromkeys(("ollama", *PROVIDER_KEY_ENV, *CATALOG_PROVIDERS))
+)
+
+#: Model used when nothing overrides it. Only providers whose default Nova can stand
+#: behind are listed; for the rest, asking for ASYNC_AGENT_MODEL beats guessing an id
+#: that may not exist at the provider.
+PROVIDER_DEFAULT_MODEL: dict[str, str] = {
+    "ollama": "gemma4:31b-cloud",  # the historical default, deliberately unchanged
+    "openai": "gpt-4o-mini",
+    "anthropic": "claude-sonnet-4-5-20250929",
+    "google": "gemini-3-pro-preview",
+    "openrouter": "z-ai/glm-5.2",
+}
+PROVIDER_DEFAULT_MODEL.update({
+    provider: preset["default_model"] for provider, preset in CATALOG_PROVIDERS.items()
+    if preset.get("default_model")
+})
+
+
+def build_role_model(role: str) -> BaseChatModel | None:
+    """The model a role runs on, or None when the role inherits the main agent's.
+
+    Returns a model **object**, never the ``provider:model`` spec string. deepagents
+    turns a spec string into a client with langchain's ``init_chat_model``, which
+    only knows langchain's own provider names -- so a spec naming one of Nova's
+    (``opencode``, ``nvidia``) dies at agent-construction time with
+
+        ValueError: Unable to infer model provider for model='opencode:...'
+
+    even though Nova builds that provider perfectly well right here. ``resolve_model``
+    returns a ``BaseChatModel`` unchanged, so an object sidesteps the lookup entirely
+    and every provider Nova supports works for a role, not just langchain's.
+
+    A role that cannot be built -- a missing key, an unknown provider -- warns and
+    inherits the main agent's model instead of raising. That matches what the main
+    model does, and it matters more than enforcing the choice: raising here would
+    leave the CLI unusable over one setting, which is the very failure this function
+    exists to remove.
+    """
+    from novacode_cli.config.nova_config import NovaConfig
+
+    entry = NovaConfig().get_role_model(role)
+    if not entry:
+        return None
+    provider = str(entry.get("provider") or "").strip()
+    model_name = str(entry.get("model") or "").strip()
+    if not provider or not model_name:
+        return None
+    try:
+        return build_chat_model(provider, model_name)
+    except Exception as exc:  # noqa: BLE001 - a bad role must never brick the CLI
+        console.print(
+            f"[yellow]Role '{role}' could not use {provider}:{model_name} "
+            f"({type(exc).__name__}: {exc}); inheriting the main agent's model.[/yellow]"
+        )
+        return None
+
+
+def build_dynamic_role_model() -> BaseChatModel | None:
+    """The model for discovered agents that name none of their own.
+
+    ``dynamic`` falls back to ``subagent`` rather than to None, because a discovered
+    agent *is* a subagent; see :func:`novacode_cli.config.role_models.dynamic_spec`.
+    """
+    return build_role_model("dynamic") or build_role_model("subagent")
+
+
+def build_async_agent_model(*, per_agent_model_var: str | None = None) -> BaseChatModel:
+    """The chat model one async-agent graph runs on.
+
+    Resolution, highest priority first:
+
+    1. ``per_agent_model_var`` if given and set (e.g. ``PLAN_SCOUT_MODEL``)
+    2. ``ASYNC_AGENT_MODEL``
+    3. ``DOC_AGENT_MODEL``, what these graphs read before the move
+    4. the provider's entry in :data:`PROVIDER_DEFAULT_MODEL`
+
+    The provider comes from ``ASYNC_AGENT_PROVIDER`` and defaults to ``ollama``, so an
+    existing deployment is unaffected. Failures are raised rather than worked around:
+    a background agent that quietly ran on the wrong provider would be worse than one
+    that refuses to start, because its results would still look plausible.
+    """
+    provider = (os.environ.get(ASYNC_AGENT_PROVIDER_ENV) or "").strip().lower() or "ollama"
+    if provider not in VALID_ASYNC_PROVIDERS:
+        message = (
+            f"Unknown {ASYNC_AGENT_PROVIDER_ENV}={provider!r}. Valid providers: "
+            + ", ".join(VALID_ASYNC_PROVIDERS)
+        )
+        raise ValueError(message)
+
+    model_name = ""
+    for var in (per_agent_model_var, ASYNC_AGENT_MODEL_ENV, "DOC_AGENT_MODEL"):
+        if var:
+            model_name = (os.environ.get(var) or "").strip()
+            if model_name:
+                break
+    if not model_name:
+        model_name = PROVIDER_DEFAULT_MODEL.get(provider, "")
+    if not model_name:
+        message = (
+            f"No model set for provider {provider!r}: set {ASYNC_AGENT_MODEL_ENV} "
+            "(there is no default model for this provider)."
+        )
+        raise ValueError(message)
+
+    key_var = PROVIDER_KEY_ENV.get(provider)
+    if (
+        key_var and provider not in CATALOG_PROVIDERS
+        and not (os.environ.get(key_var) or "").strip()
+    ):
+        message = (
+            f"Provider {provider!r} needs an API key: set {key_var} (in .env for the "
+            "container, or in the environment for a server Nova launches itself)."
+        )
+        raise ValueError(message)
+
+    return build_chat_model(provider, model_name)