fix(repo-explorer): recover from a blank survey turn instead of aborting

An empty/malformed completion raises LLMResponseError in every adapter
(anthropic/google/openai-responses, and openai-chat once its empty-content
guard lands). The exploration loop called complete() unguarded, so a single
blank turn aborted a survey that may already have read useful context --
turning a transient into a total failure of application-context / threat-model
generation.

Catch it and retry the same messages (appending nothing keeps the user/
assistant roles alternating), bounded by MAX_CONSECUTIVE_EMPTY_TURNS so a
persistently-empty model still fails loudly and well short of the MAX_TURNS
budget. A refusal (LLMRefusalError, a subclass) is caught first and re-raised
so a safety signal is never churned past.

Tests: recover-on-transient, fail-loud-and-bounded-on-persistent, and
refusal-propagates. The tests raise repo_explorer's own bound exception class
so they stay stable when another test purges utilities.* from sys.modules.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: gadievron

libs/openant-core/context/repo_explorer.py

@@ -38,6 +38,8 @@
 
 from utilities.file_io import UnsafeRepoFile, read_repo_file
 from utilities.llm.adapter import (
+    LLMRefusalError,
+    LLMResponseError,
     Message,
     TextBlock,
     ToolDef,
@@ -48,6 +50,12 @@
 # Bounds. Chosen so a survey of a mid-sized repository completes in a few dollars
 # rather than tens, and so a pathological tree cannot run away.
 MAX_TURNS = 24
+# A blank/malformed turn (an adapter raises LLMResponseError -- e.g. an empty
+# completion, which every adapter guards) is treated as a transient: the survey
+# retries rather than aborting work already done. This many CONSECUTIVE blanks
+# are tolerated; the NEXT one re-raises, so a persistently-empty model fails
+# loudly after MAX_CONSECUTIVE_EMPTY_TURNS + 1 calls -- well short of MAX_TURNS.
+MAX_CONSECUTIVE_EMPTY_TURNS = 2
 MAX_FILE_BYTES = 40_000
 MAX_TOTAL_BYTES = 400_000
 MAX_LIST_ENTRIES = 300
@@ -267,15 +275,35 @@ def explore_repository(
     tools = [*EXPLORATION_TOOLS, finish_tool]
     messages = [Message(role="user", content=(TextBlock(text=task_prompt),))]
 
+    consecutive_empty = 0
     while budget.turns < MAX_TURNS:
         budget.turns += 1
-        response = binding.adapter.complete(
-            model=binding.model,
-            system=system_prompt,
-            messages=messages,
-            max_tokens=MAX_TOKENS_PER_TURN,
-            tools=tools,
-        )
+        try:
+            response = binding.adapter.complete(
+                model=binding.model,
+                system=system_prompt,
+                messages=messages,
+                max_tokens=MAX_TOKENS_PER_TURN,
+                tools=tools,
+            )
+        except LLMRefusalError:
+            # A deliberate refusal / content-filter is NOT transient: propagate it
+            # so a safety signal is never silently churned past. (Caught before the
+            # broader LLMResponseError below since it is a subclass.)
+            raise
+        except LLMResponseError:
+            # A structurally-bad turn -- most often an empty completion, also a
+            # missing usage block or malformed tool_use -- must not abort a survey
+            # that may already have read useful context. Retry the SAME messages
+            # (appending nothing keeps the user/assistant roles alternating). This
+            # helps a transient blank; a deterministic malformation just re-raises
+            # once the consecutive count exceeds the cap (bounded, well short of
+            # MAX_TURNS). A refusal is caught above and never reaches here.
+            consecutive_empty += 1
+            if consecutive_empty > MAX_CONSECUTIVE_EMPTY_TURNS:
+                raise
+            continue
+        consecutive_empty = 0
         assistant_content = tuple(response.content)
         results: list[ToolResultBlock] = []
 

libs/openant-core/tests/test_repo_explorer_loop.py

@@ -141,3 +141,58 @@ def test_never_finishing_raises_after_max_turns(tmp_path):
     adapter = _FakeAdapter([_Resp((TextBlock(text="thinking"),)) for _ in range(MAX_TURNS)])
     with pytest.raises(RuntimeError):
         explore_repository(_repo(tmp_path), _FakeBinding(adapter), "sys", "task", _FINISH)
+
+
+class _ScriptedRaisingAdapter(_FakeAdapter):
+    """Scripted entries may be exceptions: a completion that RAISES (an empty/
+    malformed turn -- every adapter raises LLMResponseError on empty content).
+    """
+    def complete(self, *, model, system, messages, max_tokens, tools):
+        self.seen_messages.append(list(messages))
+        item = self._scripted.pop(0)
+        if isinstance(item, BaseException):
+            raise item
+        return item
+
+
+def test_empty_turn_is_recovered_not_fatal(tmp_path):
+    # An empty/malformed turn (adapter raises LLMResponseError) mid-survey must NOT
+    # abort a survey that may already have read useful context. The loop consumes
+    # the turn and retries; a later valid finish still succeeds.
+    # Raise the exact class repo_explorer's `except` is bound to (its own module
+    # binding) so the test is stable even if another test purged utilities.* from
+    # sys.modules and re-minted a second LLMResponseError identity.
+    from context.repo_explorer import LLMResponseError
+    adapter = _ScriptedRaisingAdapter([
+        LLMResponseError("OpenAI returned an empty completion"),
+        _Resp((ToolUseBlock(id="tu-fin", name="finish", input={"ok": 1}),)),
+    ])
+    payload, budget = explore_repository(_repo(tmp_path), _FakeBinding(adapter),
+                                         "sys", "task", _FINISH)
+    assert payload == {"ok": 1}
+    assert budget.turns == 2  # the empty turn was consumed, then finish
+
+
+def test_persistent_empty_turns_fail_loud_and_bounded(tmp_path):
+    # A model that returns nothing on EVERY turn must still fail loudly (never a
+    # silent partial) and bounded (not burn the entire MAX_TURNS budget).
+    from context.repo_explorer import LLMResponseError
+    adapter = _ScriptedRaisingAdapter(
+        [LLMResponseError("empty") for _ in range(MAX_TURNS + 2)])
+    with pytest.raises(LLMResponseError):
+        explore_repository(_repo(tmp_path), _FakeBinding(adapter), "sys", "task", _FINISH)
+    # Bailed early on consecutive empties -- did NOT consume the whole budget.
+    assert len(adapter.seen_messages) < MAX_TURNS
+
+
+def test_refusal_is_not_retried_propagates(tmp_path):
+    # A refusal/content-filter (LLMRefusalError, subclass of LLMResponseError) is
+    # NOT a transient blank: it must propagate immediately, never be churned past.
+    from context.repo_explorer import LLMRefusalError
+    adapter = _ScriptedRaisingAdapter([
+        LLMRefusalError("model refused"),
+        _Resp((ToolUseBlock(id="tu-fin", name="finish", input={"ok": 1}),)),
+    ])
+    with pytest.raises(LLMRefusalError):
+        explore_repository(_repo(tmp_path), _FakeBinding(adapter), "sys", "task", _FINISH)
+    assert len(adapter.seen_messages) == 1  # bailed on the refusal, did not retry