Merge pull request #351 from Lexus2016/evolution/issue-348-model-404-suffix-selfcorrect

fix(provider): self-correct bare model 404 via suffix variants (Closes #348)

Author: Lexus2016

agent/conversation_loop.py

@@ -29,7 +29,11 @@
 
 from agent.codex_responses_adapter import _summarize_user_message_for_log
 from agent.display import KawaiiSpinner
-from agent.error_classifier import FailoverReason, classify_api_error
+from agent.error_classifier import (
+    FailoverReason,
+    classify_api_error,
+    next_untried_model_variant,
+)
 from agent.iteration_budget import IterationBudget
 from agent.turn_context import build_turn_context
 from agent.turn_retry_state import TurnRetryState
@@ -3253,6 +3257,41 @@ def _perform_api_call(next_api_kwargs):
                 ) and not is_context_length_error
 
                 if is_client_error:
+                    # ── Model 404 self-correct (#348) — try suffix variants of
+                    #    the SAME model before switching providers. A bare model
+                    #    id (no ``:suffix``) that 404s often resolves once
+                    #    suffixed (``glm-4`` → ``glm-4:cloud``). Try each untried
+                    #    variant once; only on exhaustion do we fall through to
+                    #    the provider fallback / abort below. Variants are derived
+                    #    from the ORIGINAL id so a mutated ``agent.model`` from a
+                    #    prior attempt doesn't shrink the candidate set.
+                    if classified.reason == FailoverReason.model_not_found:
+                        _mnf_base = getattr(agent, "_model_404_base", None)
+                        _mnf_tried = getattr(agent, "_model_404_tried", None)
+                        # Fresh model (first 404, or the user switched models
+                        # mid-session) → restart the variant search from it so a
+                        # stale base never narrows the candidates.
+                        if _mnf_tried is None or (agent.model or "") not in _mnf_tried:
+                            _mnf_base = agent.model or ""
+                            _mnf_tried = {_mnf_base}
+                        _variant = next_untried_model_variant(_mnf_base, _mnf_tried)
+                        if _variant is not None:
+                            _mnf_tried.add(_variant)
+                            agent._model_404_base = _mnf_base
+                            agent._model_404_tried = _mnf_tried
+                            agent._buffer_status(
+                                f"⚠️ Model '{agent.model}' not found — trying '{_variant}'..."
+                            )
+                            agent._vprint(
+                                f"{agent.log_prefix}   💡 Model not found; self-correcting "
+                                f"to suffixed variant '{_variant}'.",
+                                force=True,
+                            )
+                            agent.model = _variant
+                            retry_count = 0
+                            compression_attempts = 0
+                            _retry.primary_recovery_attempted = False
+                            continue
                     # Try fallback before aborting — a different provider may
                     # not have the same issue (rate limit, auth, etc.). Only
                     # announce the attempt when a fallback chain actually

agent/error_classifier.py

@@ -252,6 +252,35 @@ def is_auth(self) -> bool:
     "unsupported model",
 ]
 
+
+def model_id_suffix_variants(model: str) -> list[str]:
+    """Candidate suffixed variants of a *bare* model id, in priority order (#348).
+
+    A bare model id (no provider ``:suffix``) that 404s with "model not found"
+    frequently resolves once suffixed — e.g. ``glm-4`` → ``glm-4:cloud`` — because
+    the catalog only exposes the suffixed form (Ollama Cloud, vLLM tiers, etc.).
+    Returns ``[]`` when the id already carries a ``:suffix`` (we never second-guess
+    an explicit choice) or is empty/blank.
+    """
+    model = (model or "").strip()
+    if not model or ":" in model:
+        return []
+    return [f"{model}:cloud", f"{model}:local"]
+
+
+def next_untried_model_variant(base_model: str, tried: "set[str] | frozenset[str]") -> str | None:
+    """Next ``model:suffix`` variant of ``base_model`` not present in ``tried``.
+
+    Drives the bounded 404 self-correction loop (#348): callers pass the original
+    bare id and the set of ids already attempted; ``None`` means "no variant left,
+    fall through to provider fallback / abort".
+    """
+    for candidate in model_id_suffix_variants(base_model):
+        if candidate not in tried:
+            return candidate
+    return None
+
+
 # Request-validation patterns — the request is malformed and will fail
 # identically on every retry. Some OpenAI-compatible gateways (notably
 # codex.nekos.me) return these as 5xx instead of the standard 4xx, which

tests/agent/test_error_classifier.py

@@ -9,6 +9,8 @@
     _extract_error_body,
     _extract_error_code,
     _classify_402,
+    model_id_suffix_variants,
+    next_untried_model_variant,
 )
 
 
@@ -1654,3 +1656,48 @@ def test_unrelated_400_is_not_misclassified(self):
         e = MockAPIError("bad request: missing field 'model'", status_code=400)
         result = classify_api_error(e, provider="openrouter", model="anthropic/claude-sonnet-4")
         assert result.reason != FailoverReason.multimodal_tool_content_unsupported
+
+
+# ── Model 404 suffix-variant self-correction (#348) ────────────────────
+
+class TestModelSuffixVariants:
+    def test_bare_id_yields_cloud_then_local(self):
+        assert model_id_suffix_variants("glm-4") == ["glm-4:cloud", "glm-4:local"]
+
+    def test_already_suffixed_yields_nothing(self):
+        # An explicit ``:suffix`` is the user's choice — never second-guess it.
+        assert model_id_suffix_variants("glm-4:cloud") == []
+        assert model_id_suffix_variants("openrouter:anthropic/claude") == []
+
+    def test_blank_or_empty_yields_nothing(self):
+        assert model_id_suffix_variants("") == []
+        assert model_id_suffix_variants("   ") == []
+
+    def test_whitespace_is_trimmed(self):
+        assert model_id_suffix_variants("  kimi-k2  ") == ["kimi-k2:cloud", "kimi-k2:local"]
+
+
+class TestNextUntriedModelVariant:
+    def test_first_call_returns_cloud(self):
+        assert next_untried_model_variant("glm-4", {"glm-4"}) == "glm-4:cloud"
+
+    def test_skips_already_tried(self):
+        assert next_untried_model_variant("glm-4", {"glm-4", "glm-4:cloud"}) == "glm-4:local"
+
+    def test_exhausted_returns_none(self):
+        tried = {"glm-4", "glm-4:cloud", "glm-4:local"}
+        assert next_untried_model_variant("glm-4", tried) is None
+
+    def test_suffixed_base_has_no_variants(self):
+        assert next_untried_model_variant("glm-4:cloud", {"glm-4:cloud"}) is None
+
+    def test_bounded_two_step_progression(self):
+        # The exact loop the conversation handler runs: base 404 → :cloud 404 →
+        # :local 404 → give up (fall through to provider fallback / abort).
+        base, tried = "qwen3", {"qwen3"}
+        seq = []
+        while (v := next_untried_model_variant(base, tried)) is not None:
+            seq.append(v)
+            tried.add(v)
+        assert seq == ["qwen3:cloud", "qwen3:local"]
+