feat(core): carry structured exception detail on ExecutionResult

docs/src/sdk-reference/misc/executionresult.mdx

@@ -28,6 +28,9 @@ description: ""
 <ParamField path="exception" type="UnionType[NotteBaseError, Exception, None]">
 </ParamField>
 
+<ParamField path="exception_detail" type="UnionType[SerializedError, None]">
+</ParamField>
+
 
 ## Module
 

docs/src/sdk-reference/misc/serializederror.mdx

@@ -0,0 +1,37 @@
+---
+title: "SerializedError"
+description: "Lossless wire representation of an execution result's exception"
+---
+
+
+
+The legacy `exception` field is serialized as `str(e)`, which collapses the error
+to whichever single message the server's `ErrorConfig` mode baked in and drops the
+concrete type and the retry/notify flags. This model carries all of it so clients
+can rehydrate the exception the server actually raised. The field is additive for
+wire compatibility: old servers never send it, old clients ignore it
+
+## Fields
+
+<ParamField path="error_type" type="str" required>
+</ParamField>
+
+<ParamField path="dev_message" type="str" required>
+</ParamField>
+
+<ParamField path="user_message" type="str" required>
+</ParamField>
+
+<ParamField path="agent_message" type="str" required>
+</ParamField>
+
+<ParamField path="should_retry_later" type="bool" default="False">
+</ParamField>
+
+<ParamField path="should_notify_team" type="bool" default="False">
+</ParamField>
+
+
+## Module
+
+`notte_core.browser.observation`

packages/notte-core/src/notte_core/browser/observation.py

@@ -316,13 +316,99 @@ def generate_empty_picture(width: int = 1280, height: int = 1080) -> bytes:
         return _empty_observation_instance
 
 
+class SerializedError(BaseModel):
+    """Lossless wire representation of an execution result's exception.
+
+    The legacy `exception` field is serialized as `str(e)`, which collapses the error
+    to whichever single message the server's `ErrorConfig` mode baked in and drops the
+    concrete type and the retry/notify flags. This model carries all of it so clients
+    can rehydrate the exception the server actually raised. The field is additive for
+    wire compatibility: old servers never send it, old clients ignore it.
+    """
+
+    error_type: str
+    dev_message: str
+    user_message: str
+    agent_message: str
+    should_retry_later: bool = False
+    should_notify_team: bool = False
+
+    @staticmethod
+    def from_exception(e: Exception) -> "SerializedError":
+        if isinstance(e, NotteBaseError):
+            return SerializedError(
+                error_type=type(e).__name__,
+                dev_message=e.dev_message,
+                user_message=e.user_message,
+                agent_message=e.agent_message,
+                should_retry_later=e.should_retry_later,
+                should_notify_team=e.should_notify_team,
+            )
+        message = str(e)
+        return SerializedError(
+            error_type=type(e).__name__,
+            dev_message=message,
+            user_message=message,
+            agent_message=message,
+        )
+
+    def to_exception(self) -> NotteBaseError:
+        error_cls = self._resolve_error_class()
+        error = error_cls.__new__(error_cls)
+        # Subclass __init__ signatures differ (e.g. ActionExecutionError takes
+        # action_id/url/reason), so rebuild through the uniform base initializer.
+        NotteBaseError.__init__(
+            error,
+            dev_message=self.dev_message,
+            user_message=self.user_message,
+            agent_message=self.agent_message,
+            should_retry_later=self.should_retry_later,
+            should_notify_team=self.should_notify_team,
+        )
+        return error
+
+    def _resolve_error_class(self) -> type[NotteBaseError]:
+        # Imported lazily so every first-party error subclass is registered in
+        # `__subclasses__` before the walk, without import cycles at module load.
+        # Modules outside notte-core are optional: an SDK-only install (or one
+        # without playwright) does not ship them.
+        import importlib
+
+        for module in (
+            "notte_core.errors.actions",
+            "notte_core.errors.llm",
+            "notte_core.errors.processing",
+            "notte_core.errors.provider",
+            "notte_core.errors.validation",
+            "notte_browser.errors",
+            "notte_agent.errors",
+            "notte_sdk.errors",
+        ):
+            try:
+                _ = importlib.import_module(module)
+            except ImportError:
+                continue
+
+        # Error types not found in the tree (third-party, or from a module that
+        # is not installed) rehydrate as the base class: the type is
+        # best-effort, the messages and flags are not.
+        candidates: list[type[NotteBaseError]] = [NotteBaseError]
+        while candidates:
+            cls = candidates.pop()
+            if cls.__name__ == self.error_type:
+                return cls
+            candidates.extend(cls.__subclasses__())
+        return NotteBaseError
+
+
 class ExecutionResult(FilledTimedSpan):
     # action: BaseAction
     action: ActionUnion
     success: bool
     message: str
     data: DataSpace | None = None
     exception: NotteBaseError | Exception | None = Field(default=None)
+    exception_detail: SerializedError | None = None
 
     @field_validator("exception", mode="before")
     @classmethod
@@ -331,6 +417,22 @@ def validate_exception(cls, v: Any) -> NotteBaseError | Exception | None:
             return NotteBaseError(dev_message=v, user_message=v, agent_message=v)
         return v
 
+    @model_validator(mode="after")
+    def sync_exception_detail(self) -> "ExecutionResult":
+        if self.success:
+            return self
+        if self.exception is None:
+            if self.exception_detail is not None:
+                # Wire payload from a server that only sets the structured field.
+                self.exception = self.exception_detail.to_exception()
+        elif self.exception_detail is None:
+            self.exception_detail = SerializedError.from_exception(self.exception)
+        elif type(self.exception) is NotteBaseError:
+            # The legacy string field was rehydrated as a bare NotteBaseError by
+            # `validate_exception`; the detail knows the real type, messages and flags.
+            self.exception = self.exception_detail.to_exception()
+        return self
+
     model_config: ConfigDict = ConfigDict(  # pyright: ignore [reportIncompatibleVariableOverride]
         arbitrary_types_allowed=True,
         json_encoders={

tests/test_execution_result_serialization.py

@@ -0,0 +1,152 @@
+"""ExecutionResult exception round-trips.
+
+The legacy wire format serialized `exception` as `str(e)`, so the concrete error
+type, the per-audience messages and the retry/notify flags were destroyed in
+transit and every remote failure rehydrated as a bare `NotteBaseError`. The
+additive `exception_detail` field carries the full error; these tests pin the
+round-trip, the fallbacks, and compatibility with payloads from older servers.
+"""
+
+import json
+
+import pytest
+from notte_core.actions import ClickAction
+from notte_core.browser.observation import ExecutionResult, SerializedError, TimedSpan
+from notte_core.errors.actions import ActionExecutionError
+from notte_core.errors.base import NotteBaseError
+
+
+def _failed_result(exception: Exception) -> ExecutionResult:
+    span = TimedSpan.start().close()
+    return ExecutionResult(
+        action=ClickAction(id="B1"),
+        success=False,
+        message="click failed",
+        started_at=span.started_at,
+        ended_at=span.ended_at,
+        exception=exception,
+    )
+
+
+def test_notte_error_round_trips_with_type_messages_and_flags() -> None:
+    original = ActionExecutionError(action_id="click", url="https://example.com", reason="element is disabled")
+    dumped = _failed_result(original).model_dump_json()
+
+    restored = ExecutionResult.model_validate_json(dumped)
+
+    assert isinstance(restored.exception, ActionExecutionError)
+    assert restored.exception.dev_message == original.dev_message
+    assert restored.exception.user_message == original.user_message
+    assert restored.exception.agent_message == original.agent_message
+    assert restored.exception.should_retry_later is True
+    assert restored.exception.should_notify_team is True
+    assert "element is disabled" in restored.exception.dev_message
+
+
+def test_legacy_payload_without_detail_keeps_old_behavior() -> None:
+    original = ActionExecutionError(action_id="click", url="https://example.com", reason="element is disabled")
+    payload = json.loads(_failed_result(original).model_dump_json())
+    # An older server serializes only the stringified exception.
+    del payload["exception_detail"]
+
+    restored = ExecutionResult.model_validate(payload)
+
+    assert type(restored.exception) is NotteBaseError
+    assert restored.exception.dev_message == str(original)
+
+
+def test_unknown_error_type_falls_back_to_base_class() -> None:
+    detail = SerializedError(
+        error_type="ServerOnlyError",
+        dev_message="dev",
+        user_message="user",
+        agent_message="agent",
+        should_retry_later=True,
+    )
+    payload = json.loads(_failed_result(ValueError("boom")).model_dump_json())
+    payload["exception"] = "dev"
+    payload["exception_detail"] = detail.model_dump()
+
+    restored = ExecutionResult.model_validate(payload)
+
+    assert type(restored.exception) is NotteBaseError
+    assert restored.exception.dev_message == "dev"
+    assert restored.exception.user_message == "user"
+    assert restored.exception.should_retry_later is True
+
+
+def test_first_party_error_outside_core_rehydrates_concrete_type() -> None:
+    """Errors defined in notte-browser/notte-agent resolve without the caller importing them."""
+    for error_type in ("InvalidLocatorRuntimeError", "MaxStepsReachedError", "PageLoadingError"):
+        detail = SerializedError(
+            error_type=error_type,
+            dev_message="dev",
+            user_message="user",
+            agent_message="agent",
+        )
+
+        error = detail.to_exception()
+
+        assert type(error).__name__ == error_type
+
+    from notte_browser.errors import BrowserError
+
+    # hierarchy matters: `except BrowserError` on the client must catch a
+    # rehydrated PageLoadingError
+    assert isinstance(
+        SerializedError(
+            error_type="PageLoadingError", dev_message="dev", user_message="user", agent_message="agent"
+        ).to_exception(),
+        BrowserError,
+    )
+
+
+def test_plain_exception_round_trips_messages() -> None:
+    restored = ExecutionResult.model_validate_json(_failed_result(TimeoutError("boom")).model_dump_json())
+
+    assert isinstance(restored.exception, NotteBaseError)
+    assert restored.exception.dev_message == "boom"
+    assert restored.exception.user_message == "boom"
+
+
+def test_detail_only_payload_rehydrates_exception() -> None:
+    payload = json.loads(
+        _failed_result(ActionExecutionError(action_id="click", url="https://example.com")).model_dump_json()
+    )
+    # A future server may stop sending the lossy legacy field altogether.
+    payload["exception"] = None
+
+    restored = ExecutionResult.model_validate(payload)
+
+    assert isinstance(restored.exception, ActionExecutionError)
+
+
+def test_local_construction_populates_detail() -> None:
+    result = _failed_result(ActionExecutionError(action_id="click", url="https://example.com", reason="nope"))
+
+    assert result.exception_detail is not None
+    assert result.exception_detail.error_type == "ActionExecutionError"
+    assert "nope" in result.exception_detail.dev_message
+
+
+def test_success_keeps_exception_invariant() -> None:
+    span = TimedSpan.start().close()
+    result = ExecutionResult(
+        action=ClickAction(id="B1"),
+        success=True,
+        message="clicked",
+        started_at=span.started_at,
+        ended_at=span.ended_at,
+    )
+    assert result.exception is None
+    assert result.exception_detail is None
+
+    with pytest.raises(ValueError, match="Exception should be None"):
+        ExecutionResult(
+            action=ClickAction(id="B1"),
+            success=True,
+            message="clicked",
+            started_at=span.started_at,
+            ended_at=span.ended_at,
+            exception=ValueError("boom"),
+        )