We now have an explicit ConversationErrorEvent in the stream (#1106)

Co-authored-by: enyst <engel.nyst@gmail.com>
Co-authored-by: openhands <openhands@all-hands.dev>

Author: 3 people

openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py

@@ -23,6 +23,7 @@
     PauseEvent,
     UserRejectObservation,
 )
+from openhands.sdk.event.conversation_error import ConversationErrorEvent
 from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.llm.llm_registry import LLMRegistry
 from openhands.sdk.logger import get_logger
@@ -312,6 +313,16 @@ def run(self) -> None:
                         break
         except Exception as e:
             self._state.execution_status = ConversationExecutionStatus.ERROR
+
+            # Add an error event
+            self._on_event(
+                ConversationErrorEvent(
+                    source="environment",
+                    code=e.__class__.__name__,
+                    detail=str(e),
+                )
+            )
+
             # Re-raise with conversation id for better UX; include original traceback
             raise ConversationRunError(self._state.id, e) from e
         finally:

openhands-sdk/openhands/sdk/event/conversation_error.py

@@ -0,0 +1,25 @@
+from pydantic import Field
+
+from openhands.sdk.event.base import Event
+
+
+class ConversationErrorEvent(Event):
+    """
+    Conversation-level failure that is NOT sent back to the LLM.
+
+    This event is emitted by the conversation runtime when an unexpected
+    exception bubbles up and prevents the run loop from continuing. It is
+    intended for client applications (e.g., UIs) to present a top-level error
+    state, and for orchestration to react. It is not an observation and it is
+    not LLM-convertible.
+
+    Differences from AgentErrorEvent:
+    - Not tied to any tool_name/tool_call_id (AgentErrorEvent is a tool
+      observation).
+    - Typically source='environment' and the run loop moves to an ERROR state,
+      while AgentErrorEvent has source='agent' and the conversation can
+      continue.
+    """
+
+    code: str = Field(description="Code for the error - typically a type")
+    detail: str = Field(description="Details about the error")