fix(builder): resolve the agent builder's model against what's installed

Build Custom Agent hardcoded model_id="Qwen3.5-35B-A3B-GGUF" and fell back to
it even when nothing upstream resolved a real one — so the 35B requirement
came back by default on every machine that doesn't have it installed (no
`gaia init` profile installs it).

- BuilderAgent's registry entry now carries a real preference list
  (BUILDER_PREFERRED_MODELS: 35B, then the two models actual init profiles
  install) instead of models=[], so AgentRegistry.resolve_model picks up an
  installed model before construction.
- Added a construction-time safety net (_select_builder_model) so the
  hardcoded-35B fallback can never resurface even when a caller omits
  model_id outright (CLI, tests, or the "nothing preferred is installed"
  path) — it checks Lemonade's live model list and fails loudly, naming what
  to install, instead of silently defaulting.
- Distinguishes "Lemonade unreachable" from "reachable but nothing usable
  installed" — conflating the two was flagged as a real risk since both
  previously collapsed to an empty list with no way to tell them apart.
- No "model quality may be reduced" messaging: the repo's own eval baselines
  show the smaller model outperforming the 35B on tool selection, so no such
  claim is substantiated.

Builds on the model-not-found (404) surfacing already on this branch.

Author: itomek

src/gaia/agents/builder/agent.py

@@ -20,6 +20,12 @@
 from gaia.agents.base.agent import Agent, default_max_steps
 from gaia.agents.base.console import AgentConsole
 from gaia.agents.base.tools import tool
+from gaia.agents.registry import (
+    BUILDER_PREFERRED_MODELS,
+    get_lemonade_models,
+    resolve_preferred_model,
+)
+from gaia.llm.providers.lemonade import LemonadeError, LemonadeNetworkError
 from gaia.logger import get_logger
 
 logger = get_logger(__name__)
@@ -112,6 +118,47 @@ def _normalize_display_name(name: str) -> str:
     return " ".join(words)
 
 
+def _select_builder_model(base_url: str) -> str:
+    """Pick an installed model for the builder, or fail loudly.
+
+    Runs only when the caller didn't already pin an explicit ``model_id`` —
+    the normal Agent UI path resolves one upstream via
+    ``AgentRegistry.resolve_model`` before construction. This is the
+    construction-time safety net: it must not trust that an omitted
+    ``model_id`` means "the 35B default is fine" (that trust is exactly what
+    caused #2243 — the omission is deliberate per #841, not an endorsement of
+    the hardcoded fallback).
+
+    Distinguishes "Lemonade unreachable" (retryable, connectivity problem)
+    from "reachable but nothing usable is installed" (not retryable, needs a
+    model install) — the two need different remediation.
+    """
+    available = get_lemonade_models(base_url)
+    if available is None:
+        raise LemonadeNetworkError()
+
+    selected = resolve_preferred_model(BUILDER_PREFERRED_MODELS, available)
+    if selected is None:
+        candidates = ", ".join(BUILDER_PREFERRED_MODELS)
+        err = LemonadeError(
+            user_message=(
+                "No usable model is installed for the agent builder. Install "
+                f"one of: {candidates} — for example "
+                f"`gaia download {BUILDER_PREFERRED_MODELS[-1]}` — or run "
+                "`gaia init` to set up a profile, then try again."
+            )
+        )
+        logger.warning(
+            "builder: no preferred model installed (checked %s against %s)",
+            BUILDER_PREFERRED_MODELS,
+            available,
+        )
+        raise err
+
+    logger.info("builder: selected model %s", selected)
+    return selected
+
+
 @dataclass
 class BuilderAgentConfig:
     """Configuration for BuilderAgent."""
@@ -146,12 +193,19 @@ def __init__(self, config: Optional[BuilderAgentConfig] = None):
         config = config or BuilderAgentConfig()
         self.config = config
 
-        effective_model_id = config.model_id or "Qwen3.5-35B-A3B-GGUF"
         effective_base_url = (
             config.base_url
             if config.base_url is not None
             else os.getenv("LEMONADE_BASE_URL", "http://localhost:13305/api/v1")
         )
+        # An explicit model_id (session-resolved upstream, or pinned by a
+        # caller) is never second-guessed by a live check. Only an omitted
+        # model_id triggers the construction-time safety net (#2243) — see
+        # _select_builder_model's docstring for why this can't just default
+        # to a hardcoded model.
+        effective_model_id = config.model_id or _select_builder_model(
+            effective_base_url
+        )
 
         self.response_mode = "conversational"
         super().__init__(

src/gaia/agents/registry.py

@@ -73,6 +73,55 @@
 )
 
 
+# BuilderAgent's model preference, best-to-worst. The first two entries match
+# what `gaia init` profiles actually install (`Gemma-4-E4B-it-GGUF` is the
+# default-profile model; `gemma4-it-e2b-FLM` is the npu-profile one — see
+# `INIT_PROFILES` in `gaia.installer.init_command`); no profile installs the
+# 35B, so it must not be the only entry (#2243).
+BUILDER_PREFERRED_MODELS: List[str] = [
+    "Qwen3.5-35B-A3B-GGUF",
+    "Gemma-4-E4B-it-GGUF",
+    "gemma4-it-e2b-FLM",
+]
+
+
+def resolve_preferred_model(
+    preferred_models: List[str], available_models: List[str]
+) -> Optional[str]:
+    """Return the first of *preferred_models* present in *available_models*.
+
+    Pure ordering primitive shared by ``AgentRegistry.resolve_model`` and any
+    caller (e.g. ``BuilderAgent``) that needs to pick a model from a live
+    Lemonade catalog without going through a full registry instance.
+    """
+    for model in preferred_models:
+        if model in available_models:
+            return model
+    return None
+
+
+def get_lemonade_models(base_url: str, timeout: float = 2.0) -> Optional[List[str]]:
+    """Query Lemonade's ``/models`` endpoint directly (no cache, no backoff).
+
+    Returns the list of installed model ids on a 2xx response — an empty list
+    means Lemonade is reachable but nothing is loaded/installed. Returns
+    ``None`` when the request could not be completed at all (connection
+    error, timeout, non-2xx, malformed response). Callers must not conflate
+    the two: "unreachable" and "reachable but nothing installed" call for
+    different messages and different remediation.
+    """
+    try:
+        import requests
+
+        resp = requests.get(f"{base_url}/models", timeout=timeout)
+        if resp.status_code == 200:
+            data = resp.json()
+            return [m["id"] for m in data.get("data", [])]
+    except Exception:
+        pass
+    return None
+
+
 # Session-level kwargs that constrain the agent's effective sandbox. If
 # python_factory drops one of these for a class that doesn't declare it, the
 # session-intended constraint silently relaxes to the agent's default — log
@@ -628,7 +677,7 @@ def builder_factory(**kwargs):
                         builder_factory, "builtin:builder"
                     ),
                     agent_dir=None,
-                    models=[],
+                    models=BUILDER_PREFERRED_MODELS,
                     hidden=True,
                     required_connections=[],
                     namespaced_agent_id="builtin:builder",
@@ -1220,23 +1269,19 @@ def resolve_model(
         if available_models is None:
             available_models = self._get_available_models()
 
-        for model in preferred_models:
-            if model in available_models:
-                logger.info(
-                    "registry: Agent %s: preferred model %s available",
-                    agent_id,
-                    model,
-                )
-                return model
+        resolved = resolve_preferred_model(preferred_models, available_models)
+        if resolved is not None:
             logger.info(
-                "registry: Agent %s: preferred model %s not available, trying next",
+                "registry: Agent %s: preferred model %s available",
                 agent_id,
-                model,
+                resolved,
             )
+            return resolved
 
         logger.warning(
-            "registry: Agent %s: no preferred models available, using server default",
+            "registry: Agent %s: no preferred models available (%s), using server default",
             agent_id,
+            preferred_models,
         )
         return None
 
@@ -1258,17 +1303,11 @@ def _get_available_models(self) -> List[str]:
         ):
             return []
 
-        try:
-            import requests
-
-            base_url = os.getenv("LEMONADE_BASE_URL", "http://localhost:13305/api/v1")
-            resp = requests.get(f"{base_url}/models", timeout=2)
-            if resp.ok:
-                data = resp.json()
-                self._lemonade_models = [m["id"] for m in data.get("data", [])]
-                return self._lemonade_models
-        except Exception:
-            pass
+        base_url = os.getenv("LEMONADE_BASE_URL", "http://localhost:13305/api/v1")
+        models = get_lemonade_models(base_url)
+        if models is not None:
+            self._lemonade_models = models
+            return self._lemonade_models
 
         # Record failure timestamp; do NOT cache models so we retry after the interval.
         self._lemonade_models_last_fail = time.monotonic()

tests/unit/agents/test_builder_model_selection.py

@@ -89,9 +89,9 @@ def test_no_usable_model_installed_raises_actionable_error(self):
                 _select_builder_model(_BASE_URL)
         message = excinfo.value.user_message
         # Must name a concrete candidate model so the user knows what to install.
-        assert any(model in message for model in BUILDER_PREFERRED_MODELS), (
-            f"expected a concrete candidate model name in the error, got: {message!r}"
-        )
+        assert any(
+            model in message for model in BUILDER_PREFERRED_MODELS
+        ), f"expected a concrete candidate model name in the error, got: {message!r}"
         # Must give a remediation command.
         assert (
             "gaia download" in message or "gaia init" in message
@@ -213,9 +213,7 @@ def test_get_lemonade_models_returns_none_on_connection_error(self):
 
         from gaia.agents.registry import get_lemonade_models
 
-        with patch(
-            "requests.get", side_effect=requests.exceptions.ConnectionError()
-        ):
+        with patch("requests.get", side_effect=requests.exceptions.ConnectionError()):
             result = get_lemonade_models(_BASE_URL)
         assert result is None
 

tests/unit/agents/test_registry.py

@@ -879,9 +879,7 @@ def test_get_lemonade_models_none_means_unreachable_not_empty(self):
         callers must be able to tell them apart."""
         from gaia.agents.registry import get_lemonade_models
 
-        mock_response = SimpleNamespace(
-            status_code=200, json=lambda: {"data": []}
-        )
+        mock_response = SimpleNamespace(status_code=200, json=lambda: {"data": []})
         with patch("requests.get", return_value=mock_response):
             reachable_empty = get_lemonade_models("http://localhost:13305/api/v1")