fix(agent-runner): loop-breaker for stuck repeat-loops + web_fetch raw-HTML bug (#229)

AVADSA25 · Mikarina13 · claude · web-flow · commit 0addf7e20ab4 · 2026-07-09T14:50:39.000+02:00
* fix(agent-runner): loop-breaker for stuck repeat-loops + web_fetch returns raw HTML

Live incident: a Project (research 5 AI startups, draft outreach emails) burned
its ENTIRE 80-step budget on checkpoint 1 without ever finishing it. Root cause
was two compounding bugs, both fixed:

1. web_fetch returned response.text verbatim for ANY html content-type — raw
   markup ("&lt;!DOCTYPE html&gt;&lt;html lang=...") is unusable for an LLM trying to
   extract facts from a page. The agent kept re-fetching the same URLs hoping
   for different content and got identical garbage every time. Fixed with a
   stdlib-only HTML-to-text extractor (no new dependency — bs4 is installed in
   this venv but not a pinned requirement, so depending on it would be a CI
   risk): strips script/style/head/comments, converts block tags to newlines,
   unescapes entities, and caps output at 12k chars so a single fetch can't
   blow a step's context budget. Verified against the actual URL from the
   incident (legible text instead of raw markup).

2. Even with readable results, nothing detected that the agent was making the
   same call over and over. Qwen's own "return checkpoint_done when satisfied"
   self-check never caught it — after 80 identical-ish steps it was still
   issuing near-duplicate web_search/web_fetch calls. Added a deterministic
   loop-breaker: NoProgressDetected fires when the same (skill, result)
   signature repeats _REPEAT_THRESHOLD=3 times within a checkpoint, pausing
   early with an honest, specific reason ("'web_fetch' returned the same
   result 3x... without new information") instead of grinding through the
   rest of the budget. Doesn't depend on the model noticing its own loop —
   this is deterministic, seeded from prior history on resume too so a
   crash-restart can't reset the counter and re-earn 3 more free repeats.

Two existing tests (test_execute_checkpoint_step_budget_exhausted,
test_run_agent_step_budget_exhausted_pauses_not_blocks) were mocking a
"repeat the same result forever" scenario to test pure budget exhaustion —
now correctly caught earlier by the loop-breaker instead. Fixed both to use
distinct per-step results so they test what they say they test; added two new
tests proving the loop-breaker fires within ~3 repeats (not 60) and does NOT
false-positive on genuine step-by-step progress.

Verified: full test suite (2469 passed, 0 failed, 79 skipped/env-gated), ruff
clean, ran the fixed web_fetch against the real incident URL.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;

* chore: regenerate D-1 skill manifest for web_fetch.py change

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Mickael Farina &lt;farina.mickael@gmail.com&gt;
Co-authored-by: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/codec_agent_runner.py b/codec_agent_runner.py
@@ -727,6 +727,36 @@ class StepBudgetExhausted(Exception):
     """Per-checkpoint step budget cap reached without checkpoint_done."""
 
 
+class NoProgressDetected(Exception):
+    """The last several actions returned near-identical results — the agent is
+    stuck in a repeat loop, not making progress. Raised well before the step
+    budget exhausts so the human sees an early, honest pause instead of the
+    agent silently grinding through its whole budget on the same dead end.
+
+    2026-07: a live Project run (research 5 AI startups) re-fetched the same
+    URL 15+ times and re-issued the same search 10+ times, burning all 80
+    steps of checkpoint 1 without ever finishing it — Qwen's own
+    "return checkpoint_done" self-check never caught it. This is a
+    deterministic backstop that doesn't depend on the model noticing its own
+    loop."""
+
+
+_REPEAT_THRESHOLD = 3  # this many near-identical results anywhere in the
+                       # checkpoint so far => treat as a stuck loop, not luck
+
+
+def _result_signature(skill: str, result: str) -> str:
+    """Cheap normalized signature for repeat-detection: same skill + a
+    whitespace-collapsed prefix of the result. Two fetches of the same URL (or
+    two searches surfacing the same top result) collapse to the same
+    signature even when the LLM phrases the task text slightly differently
+    each time — task-text similarity is NOT a reliable signal (the model
+    reliably varies its phrasing while making the exact same call), but
+    getting back the same information twice is unambiguous."""
+    norm = re.sub(r"\s+", " ", (result or "")).strip()[:300]
+    return f"{skill}::{norm}"
+
+
 def _build_correction_nudge(pv: "PermissionViolation",
                             action: Action,
                             agent_grants: Dict[str, Any],
@@ -872,6 +902,15 @@ def _execute_checkpoint(plan_dict: Dict[str, Any],
     # (seeded from state.json on resume by _run_agent). Mutated in place + persisted.
     if executed_destructive is None:
         executed_destructive = []
+    # Loop-breaker: seed the repeat-signature counter from any PRE-EXISTING
+    # history (resume-after-crash case) so a checkpoint that was ALREADY
+    # looping before a restart doesn't get a fresh 3-strike allowance.
+    _sig_counts: Dict[str, int] = {}
+    for h in history:
+        if h.get("_skill_correction_nudge") or h.get("_resume_skipped"):
+            continue
+        sig = _result_signature(h.get("skill", ""), h.get("result", ""))
+        _sig_counts[sig] = _sig_counts.get(sig, 0) + 1
     cp_id = str(checkpoint.get("id", ""))
     # Floor to DEFAULT so plans with tiny LLM-generated budgets (e.g. 5 or 10)
     # don't exhaust before Qwen can finish real work.
@@ -985,6 +1024,19 @@ def _next_action():
         })
         _persist_checkpoint_progress(agent_id, cp_id, history, executed_destructive)
 
+        # Loop-breaker: this exact (skill, result) pair has now come back
+        # _REPEAT_THRESHOLD times in this checkpoint — repeating it isn't
+        # teaching the agent anything new. Stop here instead of grinding
+        # through the rest of the step budget on the same dead end.
+        sig = _result_signature(action.skill, result)
+        _sig_counts[sig] = _sig_counts.get(sig, 0) + 1
+        if _sig_counts[sig] >= _REPEAT_THRESHOLD:
+            raise NoProgressDetected(
+                f"'{action.skill}' returned the same result {_sig_counts[sig]}x in "
+                f"checkpoint {cp_id!r} without new information (last task: "
+                f"{action.task[:120]!r})"
+            )
+
     raise StepBudgetExhausted(f"step_budget {budget} exhausted in checkpoint {checkpoint.get('id')}")
 
 
@@ -1296,6 +1348,29 @@ def _run_agent(agent_id: str, cid: Optional[str] = None) -> None:
                     else:
                         log.info("[%s] pause not announced — status superseded externally", agent_id)
                 return
+            except NoProgressDetected as e:
+                # Deterministic loop-breaker fired before the step budget was
+                # anywhere near exhausted — the agent is stuck, not still
+                # working. Pause early with an honest, specific reason instead
+                # of grinding through the rest of the budget for nothing.
+                if _atomic_set_status(agent_id, "paused", reason=f"no_progress_detected:{e}"):
+                    _audit(AGENT_PAUSED,
+                           message=f"paused: no progress ({e})",
+                           correlation_id=cid, outcome="warning", level="warning",
+                           extra={"agent_id": agent_id, "checkpoint_id": cp.id,
+                                  "reason": "no_progress_detected"})
+                    post_message(agent_id=agent_id, type="agent_blocked",
+                                 title="Paused: not making progress",
+                                 body=f"{e}. Resume to let me try a different approach, "
+                                      f"or abort if this isn't worth pursuing further.",
+                                 actions=[
+                                     {"label": "Resume", "endpoint": f"/api/agents/{agent_id}/resume"},
+                                     {"label": "Abort", "endpoint": f"/api/agents/{agent_id}/abort"},
+                                 ],
+                                 correlation_id=cid)
+                else:
+                    log.info("[%s] no-progress pause not announced — status superseded externally", agent_id)
+                return
 
             # Checkpoint complete: atomic state save (resume guarantee).
             # B-5: load-modify-save (not overwrite) — advance the cursor and CLEAR the
diff --git a/skills/.manifest.json b/skills/.manifest.json
@@ -86,7 +86,7 @@
     "tts_say.py": "bbc8828d73f0fa4ebb935919ffd0e64f706362bf715fe86851046e4527f62c92",
     "volume.py": "cbd20b36ee7d4010a4a4d13829b2d7e96e5123bd112ccd5a17fe18ab85c18429",
     "weather.py": "d33a479119a23a26a485df230440a7e4e1beb04bb0bb68bd2a7444e3504a6b2e",
-    "web_fetch.py": "cd6e2b7565bc3f486faeabdf6d338f5fd052d6cde0e5c8d7625b3b630f987859",
+    "web_fetch.py": "3a07aed6b21ddfae096ae9e94c4a27048b653167cad3102781ea2cc44954ae38",
     "web_search.py": "49023eef091cbedb7e099ad7a545e02eed68676f5c0de0e168625d51914d6462"
   }
 }
diff --git a/skills/web_fetch.py b/skills/web_fetch.py
@@ -4,11 +4,39 @@
 SKILL_TRIGGERS = ["fetch", "get url"]
 SKILL_MCP_EXPOSE = True
 
+import html as _html
 import re
 from urllib.parse import urljoin
 
 import requests
 
+_MAX_CHARS = 12_000  # keep a fetch from blowing an agent step's context budget
+
+
+def _html_to_text(raw: str) -> str:
+    """Strip an HTML document down to its readable text. Stdlib-only (no bs4
+    dependency risk) — good enough to make a page's actual content legible to
+    the LLM instead of raw markup, which is unusable for extracting facts.
+
+    2026-07: web_fetch previously returned response.text verbatim for ANY
+    HTML page — a Project agent researching AI startup launches re-fetched
+    the same page 15+ times because it kept receiving
+    '<!DOCTYPE html><html lang="en">...' and could never extract a founder
+    name from it, burning its entire step budget (80 steps) in the loop
+    before ever finishing checkpoint 1."""
+    # Drop non-content blocks entirely — their text isn't page content.
+    text = re.sub(r"(?is)<(script|style|noscript|svg|head)\b.*?</\1>", " ", raw)
+    text = re.sub(r"(?is)<!--.*?-->", " ", text)
+    # Block-level tags become newlines so paragraphs/list items stay separable.
+    text = re.sub(r"(?i)<(br|/p|/div|/li|/h[1-6]|/tr)\s*/?>", "\n", text)
+    text = re.sub(r"(?s)<[^>]+>", " ", text)          # strip remaining tags
+    text = _html.unescape(text)
+    text = re.sub(r"[ \t]+", " ", text)
+    text = re.sub(r"\n\s*\n+", "\n", text).strip()
+    if len(text) > _MAX_CHARS:
+        text = text[:_MAX_CHARS] + f"\n...[truncated, {len(raw)} raw chars]"
+    return text
+
 
 def _get_validating_redirects(url: str, max_redirects: int = 5):
     """SSRF-safe GET (Fix #7 H1 + re-audit N3). Validates the URL, then follows
@@ -46,8 +74,11 @@ def run(task: str, context: str = "") -> str:
         response.raise_for_status()
         
         content_type = response.headers.get("content-type", "")
+        if "html" in content_type:
+            return _html_to_text(response.text)
         if "text" in content_type or "json" in content_type:
-            return response.text
+            body = response.text
+            return body[:_MAX_CHARS] + (f"\n...[truncated, {len(body)} raw chars]" if len(body) > _MAX_CHARS else "")
         else:
             return f"web_fetch failed: unsupported content type {content_type}"
             
diff --git a/tests/test_agent_runner.py b/tests/test_agent_runner.py
@@ -492,14 +492,23 @@ def test_execute_checkpoint_destructive_rejection_raises(monkeypatch, temp_codec
 
 
 def test_execute_checkpoint_step_budget_exhausted(monkeypatch, temp_codec_dir):
-    """Step budget cap reached → StepBudgetExhausted."""
+    """Step budget cap reached → StepBudgetExhausted.
+
+    Each step must return GENUINELY DISTINCT results (a counter, not a fixed
+    "r") — otherwise this exercises the 2026-07 loop-breaker (NoProgressDetected,
+    tested separately in test_runner_loop.py) instead of real budget exhaustion,
+    since identical results repeated 3x now correctly pause early."""
     import codec_agent_runner as car
 
     # Always return a skill call (never checkpoint_done)
     monkeypatch.setattr(car, "_qwen_next_action", lambda *a, **k:
         car.Action(skill="weather", task="loop",
                    is_destructive=False, network_call=False, touches_path=False))
-    monkeypatch.setattr(car, "_run_skill", MagicMock(return_value="r"))
+    _n = {"i": 0}
+    def _distinct_result(*a, **k):
+        _n["i"] += 1
+        return f"result #{_n['i']}"
+    monkeypatch.setattr(car, "_run_skill", _distinct_result)
 
     grants = {"skills": ["weather"], "read_paths": [], "write_paths": [],
               "network_domains": []}
@@ -941,7 +950,10 @@ def test_post_api_agents_404_for_unknown_id(temp_codec_dir):
 
 def test_run_agent_step_budget_exhausted_pauses_not_blocks(monkeypatch, temp_codec_dir):
     """Real budget hit (not destructive_consent_timeout) → status=paused
-    with reason=step_budget_exhausted (was: blocked_on_permission)."""
+    with reason=step_budget_exhausted (was: blocked_on_permission).
+
+    Distinct per-step results (see test_execute_checkpoint_step_budget_exhausted
+    above) so this tests real exhaustion, not the loop-breaker."""
     import codec_agent_runner as car
     import codec_agent_plan as cap
     _setup_approved_agent(temp_codec_dir, monkeypatch, num_checkpoints=1)
@@ -950,7 +962,11 @@ def test_run_agent_step_budget_exhausted_pauses_not_blocks(monkeypatch, temp_cod
     monkeypatch.setattr(car, "_qwen_next_action", lambda *a, **k:
         car.Action(skill="weather", task="loop", kind="skill_call",
                    is_destructive=False, network_call=False, touches_path=False))
-    monkeypatch.setattr(car, "_run_skill", MagicMock(return_value="r"))
+    _n = {"i": 0}
+    def _distinct_result(*a, **k):
+        _n["i"] += 1
+        return f"result #{_n['i']}"
+    monkeypatch.setattr(car, "_run_skill", _distinct_result)
 
     car._run_agent("test_agent")
 
diff --git a/tests/test_runner_loop.py b/tests/test_runner_loop.py
@@ -109,6 +109,70 @@ def fake_next(plan_dict, checkpoint, history, *a, **k):
         f"qwen calls must be capped at ~budget (4)+1, counting corrections; got {calls['n']} (B-14)"
 
 
+# ── Loop-breaker (2026-07): detect a stuck repeat-loop well before budget ──────
+def test_no_progress_detected_on_repeated_identical_results(monkeypatch, temp_codec_dir):
+    """Reproduces the live failure: a research checkpoint kept re-fetching the
+    same URL and re-issuing the same search, getting back identical results,
+    and burned its ENTIRE 80-step budget without ever finishing. The
+    loop-breaker must raise NoProgressDetected after _REPEAT_THRESHOLD
+    identical results — long before a large budget would exhaust — so the
+    agent pauses early with an honest reason instead of grinding pointlessly."""
+    grants = {"skills": ["web_fetch"], "read_paths": [], "write_paths": [],
+              "network_domains": ["*"]}
+    gg = {"schema": 1, "version": 0, "skills": [], "read_paths": [],
+          "write_paths": [], "network_domains": []}
+    # A large budget — if the loop-breaker didn't exist, this would grind for
+    # 60 steps before StepBudgetExhausted, exactly like the real incident.
+    cp = {"id": "cp0", "title": "research", "description": "d",
+          "expected_output": "o", "step_budget": 60}
+
+    call_n = {"n": 0}
+    def fake_next(plan_dict, checkpoint, history, *a, **k):
+        call_n["n"] += 1
+        # The model keeps varying its phrasing (as it did live) but keeps
+        # calling the same skill against the same effective target.
+        return car.Action(skill="web_fetch", task=f"Fetch attempt #{call_n['n']} of the page",
+                          kind="skill_call")
+    monkeypatch.setattr(car, "_qwen_next_action", fake_next)
+    # Every fetch returns the EXACT same raw content — no new information.
+    monkeypatch.setattr(car, "_run_skill",
+                        MagicMock(return_value="<!DOCTYPE html>...same page every time..."))
+
+    with pytest.raises(car.NoProgressDetected):
+        car._execute_checkpoint(plan_dict={"goals": ["g"]}, checkpoint=cp,
+                                agent_grants=grants, global_grants=gg, agent_id="test_agent")
+    assert call_n["n"] <= car._REPEAT_THRESHOLD + 1, (
+        f"loop-breaker must fire within ~{car._REPEAT_THRESHOLD} repeats, not grind "
+        f"toward the 60-step budget; got {call_n['n']} calls"
+    )
+
+
+def test_no_progress_not_triggered_by_genuinely_different_results(monkeypatch, temp_codec_dir):
+    """Sanity check: normal progress (each step yields new information) must
+    NOT trip the loop-breaker — only true repeats should."""
+    grants = {"skills": ["web_fetch"], "read_paths": [], "write_paths": [],
+              "network_domains": ["*"]}
+    gg = {"schema": 1, "version": 0, "skills": [], "read_paths": [],
+          "write_paths": [], "network_domains": []}
+    cp = {"id": "cp0", "title": "research", "description": "d",
+          "expected_output": "o", "step_budget": 5}
+
+    step = {"n": 0}
+    def fake_next(plan_dict, checkpoint, history, *a, **k):
+        step["n"] += 1
+        if step["n"] > 4:
+            return car.Action(skill="", task="", kind="checkpoint_done")
+        return car.Action(skill="web_fetch", task=f"Fetch source #{step['n']}", kind="skill_call")
+    monkeypatch.setattr(car, "_qwen_next_action", fake_next)
+    # Each call returns DIFFERENT content — genuine progress, not a loop.
+    monkeypatch.setattr(car, "_run_skill",
+                        lambda skill, task, agent_id: f"unique content for step {step['n']}")
+
+    history = car._execute_checkpoint(plan_dict={"goals": ["g"]}, checkpoint=cp,
+                                      agent_grants=grants, global_grants=gg, agent_id="test_agent")
+    assert len(history) == 4  # all 4 distinct fetches ran, then checkpoint_done
+
+
 def test_extend_budget_caps_cumulative(monkeypatch, temp_codec_dir):
     """extend_budget cannot push a checkpoint's override above MAX_CHECKPOINT_STEP_BUDGET."""
     import routes.agents as ra

Original file line number	Diff line number	Diff line change
`@@ -86,7 +86,7 @@`
`86`	`86`	`"tts_say.py": "bbc8828d73f0fa4ebb935919ffd0e64f706362bf715fe86851046e4527f62c92",`
`87`	`87`	`"volume.py": "cbd20b36ee7d4010a4a4d13829b2d7e96e5123bd112ccd5a17fe18ab85c18429",`
`88`	`88`	`"weather.py": "d33a479119a23a26a485df230440a7e4e1beb04bb0bb68bd2a7444e3504a6b2e",`
`89`		`- "web_fetch.py": "cd6e2b7565bc3f486faeabdf6d338f5fd052d6cde0e5c8d7625b3b630f987859",`
	`89`	`+ "web_fetch.py": "3a07aed6b21ddfae096ae9e94c4a27048b653167cad3102781ea2cc44954ae38",`
`90`	`90`	`"web_search.py": "49023eef091cbedb7e099ad7a545e02eed68676f5c0de0e168625d51914d6462"`
`91`	`91`	`}`
`92`	`92`	`}`