feat: Adopt AgentFailure/send_failure across Python adapters

.github/workflows/ci.yml

@@ -257,6 +257,7 @@ jobs:
         from band import Agent, BandLink, AgentRuntime
         from band.config import load_agent_config
         from band_sdk_core import (
+            AgentFailure,
             ClaimRegistry,
             ParticipantRoster,
             RetryTracker,
@@ -291,6 +292,13 @@ jobs:
             "room_id": "room-1",
             "message_id": "msg-1",
         }
+        failure = AgentFailure("wheel-smoke", "failure")
+        assert failure.to_dict() == {
+            "provider": "wheel-smoke",
+            "code": None,
+            "message": "failure",
+            "detail": None,
+        }
         print('Core imports successful')
         PYEOF
 

docs/adapters/codex.md

@@ -249,7 +249,6 @@ These `CodexAdapterConfig(...)` flags add more telemetry detail:
 | `emit_turn_lifecycle_events` | `bool` | `False` | Emit enriched turn lifecycle events at turn start and completion. |
 | `emit_diff_events` | `bool` | `False` | Include file diffs in event metadata, capped at 64 KB. |
 | `emit_token_usage_events` | `bool` | `False` | Track and emit token usage per session. |
-| `structured_errors` | `bool` | `True` | Emit structured error events instead of plain text errors. |
 
 Enabling both `emit_turn_task_markers` and `emit_turn_lifecycle_events` produces two task events per completed turn. Pick one; lifecycle events contain richer metadata.
 

pyproject.toml

@@ -23,7 +23,7 @@ classifiers = [
 
 dependencies = [
     "band-client-rest==0.0.27",
-    "band-sdk-core==2.2.0",
+    "band-sdk-core==2.3.0",
     "phoenix-channels-python-client>=0.2.4",
     "python-dotenv>=1.2.2",
     "pydantic>=2.0",

src/band/adapters/agno.py

@@ -12,9 +12,10 @@
 
 from agno.media import Image
 from agno.tools.function import ToolResult
+from band_sdk_core import AgentFailure
 from typing_extensions import Unpack
 
-from band.core.protocols import AgentToolsProtocol
+from band.core.protocols import GENERIC_PROVIDER_FAILURE_MESSAGE, AgentToolsProtocol
 from band.core.simple_adapter import SimpleAdapter
 from band.core.tool_filter import filter_tool_schemas
 from band.core.types import (
@@ -465,18 +466,18 @@ async def _run_agent(
         :meth:`_run_streamed`), matching the other adapters' live reporting.
         Otherwise it runs non-streaming, exactly as before.
         """
-        agent = self._agent
-        if agent is None:
-            raise RuntimeError("AgnoAdapter was used before on_started()")
-        session_id = self._session_id_factory(room_id)
-        logger.debug(
-            "Room %s msg %s: running Agno agent (%d input messages, session_id=%s)",
-            room_id,
-            msg_id,
-            len(messages),
-            session_id,
-        )
         try:
+            agent = self._agent
+            if agent is None:
+                raise RuntimeError("AgnoAdapter was used before on_started()")
+            session_id = self._session_id_factory(room_id)
+            logger.debug(
+                "Room %s msg %s: running Agno agent (%d input messages, session_id=%s)",
+                room_id,
+                msg_id,
+                len(messages),
+                session_id,
+            )
             with _bind_room_tools(tools):
                 if Emit.TOOL_CALLS in self.features.emit:
                     response = await self._run_streamed(
@@ -494,22 +495,19 @@ async def _run_agent(
             # the turn as failed rather than as a silent empty reply.
             if response is not None and response.status == RunStatus.error:
                 raise AgnoRunError(_error_summary(response.content))
-        except Exception:
+        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.
+            # 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
             )
-            try:
-                await tools.send_event(
-                    content="Internal error while processing message; see agent logs.",
-                    message_type="error",
-                )
-            except Exception:
-                logger.exception(
-                    "Room %s msg %s: failed to report error event", 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)
+            )
             raise
 
         if response is None:

src/band/adapters/anthropic.py

@@ -11,12 +11,13 @@
 import warnings
 from typing import Any, ClassVar, cast
 
-from anthropic import AsyncAnthropic
+from anthropic import APIStatusError, AsyncAnthropic
 from anthropic.types import Message, MessageParam, TextBlock, ToolParam, ToolUseBlock
+from band_sdk_core import AgentFailure
 from typing_extensions import Unpack
 
 from band.core.exceptions import BandConfigError
-from band.core.protocols import AgentToolsProtocol
+from band.core.protocols import GENERIC_PROVIDER_FAILURE_MESSAGE, AgentToolsProtocol
 from band.core.simple_adapter import SimpleAdapter
 from band.core.types import (
     Capability,
@@ -62,6 +63,17 @@ def _image_tool_result_content(result: dict[str, Any]) -> list[dict[str, Any]]:
     ]
 
 
+def _to_agent_failure(e: Exception) -> AgentFailure:
+    """Parse a turn-ending exception into the shared provider-failure shape.
+
+    ``APIStatusError`` carries an HTTP status and response body that a plain
+    exception's message alone does not.
+    """
+    if isinstance(e, APIStatusError):
+        return AgentFailure("anthropic", str(e), str(e.status_code), e.body)
+    return AgentFailure("anthropic", GENERIC_PROVIDER_FAILURE_MESSAGE)
+
+
 class AnthropicAdapter(SimpleAdapter[AnthropicMessages]):
     """
     Anthropic SDK adapter using SimpleAdapter pattern.
@@ -279,7 +291,7 @@ async def on_message(
                     )
                 except Exception as e:
                     logger.error("Error calling Anthropic: %s", e, exc_info=True)
-                    await self._report_error(tools, str(e))
+                    await tools.send_failure(_to_agent_failure(e))
                     raise  # Re-raise so message is marked as failed
 
                 turn_usage = turn_usage + self._usage_from_response(response)
@@ -512,11 +524,3 @@ async def _process_tool_calls(
             )
 
         return tool_results
-
-    # --- Copied from BaseFrameworkAgent._report_error ---
-    async def _report_error(self, tools: AgentToolsProtocol, error: str) -> None:
-        """Send error event (best effort)."""
-        try:
-            await tools.send_event(content=f"Error: {error}", message_type="error")
-        except Exception as e:
-            logger.warning("Failed to send error event: %s", e)

src/band/adapters/claude_sdk.py

@@ -49,9 +49,14 @@
 except ImportError:
     _CLAUDE_SDK_AVAILABLE = False
 
+from band_sdk_core import AgentFailure
 from typing_extensions import Unpack
 
-from band.core.protocols import AgentToolsProtocol
+from band.core.protocols import (
+    GENERIC_PROVIDER_FAILURE_MESSAGE,
+    AgentToolsProtocol,
+    TurnResultAlreadyReported,
+)
 from band.core.simple_adapter import SimpleAdapter
 from band.core.types import (
     Capability,
@@ -128,6 +133,8 @@
 # same constant instead of a second, driftable number.
 _CLAUDE_SDK_MAX_BUFFER_BYTES = MAX_INLINE_IMAGE_BYTES * 2
 
+_PROVIDER = "claude_sdk"
+
 # Approval flow types (mirrors Codex adapter patterns)
 ApprovalMode = Literal["auto_accept", "auto_decline", "manual"]
 ApprovalDecision = Literal["accept", "decline"]
@@ -611,10 +618,27 @@ async def on_message(
                     stored_session_id,
                     resume_exc,
                 )
-                client = await self._session_manager.get_or_create_session(
-                    room_id, resume_session_id=None
-                )
+                try:
+                    client = await self._session_manager.get_or_create_session(
+                        room_id, resume_session_id=None
+                    )
+                except Exception as fresh_exc:
+                    logger.exception(
+                        "Room %s: Fresh session creation also failed: %s",
+                        room_id,
+                        fresh_exc,
+                    )
+                    await tools.send_failure(
+                        AgentFailure(_PROVIDER, GENERIC_PROVIDER_FAILURE_MESSAGE)
+                    )
+                    raise
             else:
+                logger.exception(
+                    "Room %s: Session creation failed: %s", room_id, resume_exc
+                )
+                await tools.send_failure(
+                    AgentFailure(_PROVIDER, GENERIC_PROVIDER_FAILURE_MESSAGE)
+                )
                 raise
 
         # Add chat_id context (Claude needs this for tool calls) -- the label
@@ -685,6 +709,11 @@ async def on_message(
             # Process streaming response (MCP tools handle execution)
             await self._process_response(client, room_id, tools)
 
+        except TurnResultAlreadyReported:
+            # _on_turn_complete already reported this failure via
+            # send_failure; propagate without reporting it a second time.
+            raise
+
         except CLIConnectionError as e:
             # CLI process is dead — evict the cached session so the next
             # message creates a fresh one instead of reusing the corpse.
@@ -695,12 +724,16 @@ async def on_message(
             )
             await self._invalidate_session(room_id)
 
-            await self._report_error(tools, str(e))
+            await tools.send_failure(
+                AgentFailure(_PROVIDER, GENERIC_PROVIDER_FAILURE_MESSAGE)
+            )
             raise
 
         except Exception as e:
             logger.exception("Error processing message: %s", e)
-            await self._report_error(tools, str(e))
+            await tools.send_failure(
+                AgentFailure(_PROVIDER, GENERIC_PROVIDER_FAILURE_MESSAGE)
+            )
             raise
 
         logger.debug("Message %s processed successfully", msg.id)
@@ -933,11 +966,22 @@ async def _on_turn_complete(
         # outright) doesn't linger and grow this room's entry unbounded.
         notified = self._notified_declines.pop(room_id, None)
         if sdk_message.is_error:
-            await self._report_error(tools, self._result_error_detail(sdk_message))
+            code = (
+                str(sdk_message.api_error_status)
+                if sdk_message.api_error_status is not None
+                else None
+            )
+            detail = self._result_error_detail(sdk_message)
+            await tools.send_failure(
+                AgentFailure(_PROVIDER, detail, code, sdk_message.errors)
+            )
+            raise TurnResultAlreadyReported(detail)
         elif not replied_this_turn and not self._declined_the_reply(
             sdk_message.permission_denials, notified
         ):
-            await self._report_error(tools, missing_reply_error("Claude SDK"))
+            detail = missing_reply_error("Claude SDK")
+            await tools.send_failure(AgentFailure(_PROVIDER, detail))
+            raise TurnResultAlreadyReported(detail)
 
     def _declined_the_reply(
         self, permission_denials: list[Any] | None, notified: set[str] | None
@@ -1127,14 +1171,6 @@ async def on_cleanup(self, room_id: str) -> None:
         self._pending_tool_names.pop(room_id, None)
         logger.debug("Room %s: Cleaned up Claude SDK session", room_id)
 
-    # --- Copied from BaseFrameworkAgent._report_error ---
-    async def _report_error(self, tools: AgentToolsProtocol, error: str) -> None:
-        """Send error event (best effort)."""
-        try:
-            await tools.send_event(content=f"Error: {error}", message_type="error")
-        except Exception:
-            logger.debug("Failed to send error event", exc_info=True)
-
     async def cleanup_all(self) -> None:
         """Cleanup all sessions (call on stop)."""
         # Decline all pending approvals across rooms