fix: report model failures returned as data and use single-token E2E markers

Agno, Google ADK and Gemini return a failed model run as a value instead of
raising. A shared ProviderRunError and generic_provider_failure fail the turn
with the coarse code (SAFETY, PROHIBITED_CONTENT, ...) even after the turn did
real work; provider text stays in the agent log.

E2E markers become one uppercase alphanumeric token, since models dropped the
word-like "note-" prefix. The add-participant smoke now reports the agent's
tool calls and failed results when the add is missing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017jhEdA7VR9ng3nZpKW2Z2X

Author: AlexanderZ-Band

docs/turn-outcome.md

@@ -228,6 +228,18 @@ returns record nothing; self-hosted tools record their own effects.
 file with the reason it carries the model's words, so a new one fails until it
 is justified.
 
+## Failed runs returned as data: `ProviderRunError`
+
+Some frameworks return a failed model run as a value instead of raising: Agno
+sets an error status, Google ADK yields an event with `error_code`, and a Gemini
+response carries a safety `finish_reason` or a blocked prompt. The judge cannot
+see such a failure when the turn already did work or replied, so the adapter
+raises `ProviderRunError(code, detail)` from `band.core.exceptions` inside its
+turn. Its failure path reports `generic_provider_failure(provider, error)` from
+`band.core.protocols`: the generic message plus the coarse `code` (such as
+`SAFETY`). The provider's `detail` can echo the prompt, so it goes only to the
+agent log. Agno, Google ADK and Gemini follow this rule.
+
 ## Detached turns
 
 An adapter whose turn outlives `on_message` (one parked on a human approval)

src/band/adapters/agno.py

@@ -12,12 +12,12 @@
 
 from agno.media import Image
 from agno.tools.function import ToolResult
-from band_sdk_core import AgentFailure
 from typing_extensions import Unpack
 
 from band.converters.agno import AgnoHistoryConverter, AgnoMessages
 from band.core.adapterconfig import BaseAdapterConfig
-from band.core.protocols import GENERIC_PROVIDER_FAILURE_MESSAGE, AgentToolsProtocol
+from band.core.exceptions import ProviderRunError
+from band.core.protocols import AgentToolsProtocol, generic_provider_failure
 from band.core.simple_adapter import SimpleAdapter
 from band.core.tool_filter import filter_tool_schemas
 from band.core.types import (
@@ -73,7 +73,7 @@
 )
 
 
-class AgnoRunError(RuntimeError):
+class AgnoRunError(ProviderRunError):
     """An Agno run finished in an error state instead of raising.
 
     Agno catches exceptions inside ``Agent.arun`` (model/API failures included)
@@ -84,6 +84,9 @@ class AgnoRunError(RuntimeError):
     that produced no output.
     """
 
+    def __init__(self, detail: str) -> None:
+        super().__init__(RunStatus.error.value, detail)
+
 
 def _error_summary(detail: str | None) -> str:
     """A bounded, log-safe summary of Agno's swallowed error text."""
@@ -485,18 +488,10 @@ async def _run_agent(
             if response is not None and response.status == RunStatus.error:
                 raise AgnoRunError(_error_summary(response.content))
         except Exception as e:
-            # Keep the user-facing payload generic; the full traceback is in the
-            # agent log via logger.exception. Exception text can include DB
-            # strings, paths, and tokens that must not surface in chat. Only
-            # the coarse RunStatus.error code -- never response.content -- is
-            # safe to attach.
             logger.exception(
                 "Room %s msg %s: error running Agno agent", room_id, msg_id
             )
-            code = RunStatus.error.value if isinstance(e, AgnoRunError) else None
-            await tools.send_failure(
-                AgentFailure("agno", GENERIC_PROVIDER_FAILURE_MESSAGE, code)
-            )
+            await tools.send_failure(generic_provider_failure("agno", e))
             raise
 
         if response is None:

src/band/adapters/gemini.py

@@ -31,7 +31,8 @@
 
 from band.converters.gemini import GeminiHistoryConverter, GeminiMessages
 from band.core.adapterconfig import BaseAdapterConfig
-from band.core.protocols import GENERIC_PROVIDER_FAILURE_MESSAGE, AgentToolsProtocol
+from band.core.exceptions import ProviderRunError
+from band.core.protocols import AgentToolsProtocol, generic_provider_failure
 from band.core.simple_adapter import SimpleAdapter
 from band.core.tool_filter import sanitize_tool_schema
 from band.core.types import (
@@ -88,7 +89,26 @@ def _to_agent_failure(e: Exception) -> AgentFailure:
     if isinstance(e, ServerError):
         status = e.status if e.status is None else str(e.status)
         return AgentFailure(_PROVIDER, str(e), status, e.message)
-    return AgentFailure(_PROVIDER, GENERIC_PROVIDER_FAILURE_MESSAGE)
+    return generic_provider_failure(_PROVIDER, e)
+
+
+def _model_failure(response: types.GenerateContentResponse) -> ProviderRunError | None:
+    """The failure a response carries as data (a blocked prompt, a safety stop),
+    read the way google-adk's ``LlmResponse.create`` reads it. A reply with
+    content, even one cut off at MAX_TOKENS, and an empty normal finish are
+    not failures."""
+    if response.candidates:
+        candidate = response.candidates[0]
+        if candidate.content and candidate.content.parts:
+            return None
+        reason = candidate.finish_reason
+        if reason is None or reason == types.FinishReason.STOP:
+            return None
+        return ProviderRunError(reason.value, candidate.finish_message)
+    feedback = response.prompt_feedback
+    if feedback is None or feedback.block_reason is None:
+        return None
+    return ProviderRunError(feedback.block_reason.value, feedback.block_reason_message)
 
 
 class GeminiAdapterConfig(BaseAdapterConfig):
@@ -258,13 +278,14 @@ async def on_message(
                     response = await self._call_gemini(
                         contents=self._message_history[room_id], tools=gemini_tools
                     )
+                    turn_usage = turn_usage + self._usage_from_response(response)
+                    if failure := _model_failure(response):
+                        raise failure
                 except Exception as e:
                     logger.exception("Error calling Gemini")
                     await tools.send_failure(_to_agent_failure(e))
                     raise
 
-                turn_usage = turn_usage + self._usage_from_response(response)
-
                 candidate_content = self._extract_candidate_content(response)
                 if candidate_content is not None:
                     self._message_history[room_id].append(candidate_content)

src/band/adapters/google_adk.py

@@ -15,13 +15,13 @@
 import uuid
 from typing import TYPE_CHECKING, Any, ClassVar, cast
 
-from band_sdk_core import AgentFailure
 from pydantic import PositiveInt, ValidationError
 from typing_extensions import Unpack
 
 from band.converters.google_adk import GoogleADKHistoryConverter, GoogleADKMessages
 from band.core.adapterconfig import BaseAdapterConfig
-from band.core.protocols import GENERIC_PROVIDER_FAILURE_MESSAGE, AgentToolsProtocol
+from band.core.exceptions import ProviderRunError
+from band.core.protocols import AgentToolsProtocol, generic_provider_failure
 from band.core.simple_adapter import SimpleAdapter
 from band.core.tool_filter import sanitize_tool_schema
 from band.core.types import (
@@ -589,6 +589,7 @@ async def on_message(
             # reported per model response on the event stream, so sum across
             # the loop into one per-turn TurnUsage.
             final_response_text = ""
+            model_failure: ProviderRunError | None = None
             async for event in runner.run_async(
                 user_id=room_id,
                 session_id=session_id,
@@ -597,6 +598,15 @@ async def on_message(
                 if Emit.USAGE in self.features.emit:
                     turn_usage = turn_usage + self._usage_from_event(event)
 
+                # ADK returns a model failure as an event. Its flow ends the
+                # run after one, so drain rather than break: breaking leaves
+                # ADK's nested generators open inside their tracing spans.
+                # ADK <= 1.10 reports an empty normal finish as "STOP".
+                if event.error_code and event.error_code != types.FinishReason.STOP:
+                    model_failure = ProviderRunError(
+                        event.error_code, event.error_message
+                    )
+
                 # Report tool calls/results if enabled
                 if Emit.TOOL_CALLS in self.features.emit:
                     try:
@@ -611,11 +621,11 @@ async def on_message(
                         "Room %s: ADK agent completed with final response",
                         room_id,
                     )
-        except Exception:
+            if model_failure is not None:
+                raise model_failure
+        except Exception as e:
             logger.exception("Error running ADK agent in room %s", room_id)
-            await tools.send_failure(
-                AgentFailure("google_adk", GENERIC_PROVIDER_FAILURE_MESSAGE)
-            )
+            await tools.send_failure(generic_provider_failure("google_adk", e))
             raise
         finally:
             # Emit before close so a close() failure can't drop the usage, but

src/band/core/exceptions.py

@@ -54,6 +54,21 @@ class BandToolError(BandError):
     """Tool execution failures. Actionable by adapter/LLM."""
 
 
+class ProviderRunError(BandError):
+    """A provider or framework returned a failed run as data instead of raising.
+    Actionable by the adapter: raise it inside the turn so the turn is reported
+    failed.
+
+    ``code`` is coarse and safe to post; ``detail`` is provider text, which can
+    echo the prompt, so it belongs only in logs.
+    """
+
+    def __init__(self, code: str, detail: str | None = None) -> None:
+        super().__init__(f"{code}: {detail}" if detail else code)
+        self.code = code
+        self.detail = detail
+
+
 def _levenshtein(a: str, b: str) -> int:
     """Iterative Levenshtein distance. Pure Python, no dependencies."""
     if a == b:

src/band/core/protocols.py

@@ -9,6 +9,7 @@
 from band_sdk_core import AgentFailure
 
 from band.core.content import has_visible_content
+from band.core.exceptions import ProviderRunError
 
 logger = logging.getLogger(__name__)
 
@@ -54,6 +55,13 @@
 )
 
 
+def generic_provider_failure(provider: str, error: BaseException) -> AgentFailure:
+    """The room-safe failure for a caught provider error: the generic message,
+    plus the coarse code when the provider returned the failure as data."""
+    code = error.code if isinstance(error, ProviderRunError) else None
+    return AgentFailure(provider, GENERIC_PROVIDER_FAILURE_MESSAGE, code)
+
+
 # ``AgentFailure.provider`` for a turn failure the runtime reports on the
 # adapter's behalf.
 TURN_FAILURE_PROVIDER = "band-runtime"

tests/adapters/genaikit.py

@@ -0,0 +1,84 @@
+"""Real google-genai responses for scripting the Google adapters' turns.
+
+Gemini reads a ``GenerateContentResponse`` directly and Google ADK reads the
+same object through ``LlmResponse.create``, so both adapters' tests script
+turns from these builders. Every response carries ``SCRIPTED_USAGE``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import MagicMock
+
+from google.genai import types
+
+from band.runtime.tools import AgentTools
+from band.testing import FakeAgentTools
+
+SCRIPTED_USAGE = types.GenerateContentResponseUsageMetadata(
+    prompt_token_count=11, candidates_token_count=3
+)
+
+# Provider text that must reach only the agent log, never the room.
+PROVIDER_DETAIL = "blocked: the prompt asked for the secret"
+
+
+class PlatformSchemaFakeTools(FakeAgentTools):
+    """A ``FakeAgentTools`` advertising the real platform tool schemas, so a
+    scripted function call goes through the adapter's own tool bridge."""
+
+    def get_openai_tool_schemas(self, **kwargs: Any) -> list[dict[str, Any]]:
+        # Schema building reads the tool registry, never the REST link.
+        return AgentTools("room-123", MagicMock()).get_openai_tool_schemas(**kwargs)
+
+
+def tool_call(name: str, args: dict[str, Any]) -> types.GenerateContentResponse:
+    return _candidate(
+        types.Content(
+            role="model", parts=[types.Part.from_function_call(name=name, args=args)]
+        ),
+        types.FinishReason.STOP,
+    )
+
+
+def text_reply(
+    text: str, finish: types.FinishReason = types.FinishReason.STOP
+) -> types.GenerateContentResponse:
+    return _candidate(
+        types.Content(role="model", parts=[types.Part.from_text(text=text)]), finish
+    )
+
+
+def stopped(reason: types.FinishReason) -> types.GenerateContentResponse:
+    """A candidate with no content, ended for ``reason``."""
+    return _candidate(None, reason, finish_message=PROVIDER_DETAIL)
+
+
+def prompt_blocked(reason: types.BlockedReason) -> types.GenerateContentResponse:
+    """No candidates: the prompt itself was refused."""
+    return types.GenerateContentResponse(
+        prompt_feedback=types.GenerateContentResponsePromptFeedback(
+            block_reason=reason, block_reason_message=PROVIDER_DETAIL
+        ),
+        usage_metadata=SCRIPTED_USAGE,
+    )
+
+
+def no_candidates() -> types.GenerateContentResponse:
+    return types.GenerateContentResponse(usage_metadata=SCRIPTED_USAGE)
+
+
+def _candidate(
+    content: types.Content | None,
+    finish: types.FinishReason,
+    *,
+    finish_message: str | None = None,
+) -> types.GenerateContentResponse:
+    return types.GenerateContentResponse(
+        candidates=[
+            types.Candidate(
+                content=content, finish_reason=finish, finish_message=finish_message
+            )
+        ],
+        usage_metadata=SCRIPTED_USAGE,
+    )