fix: make error ownership classification explicit

Provide typed application and platform error classes with documented ownership boundaries instead of relying on arbitrary exception attributes.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jshaikScale

src/agentex/lib/core/tracing/__init__.py

@@ -1,6 +1,11 @@
 from agentex.types.span import Span
 from agentex.lib.core.tracing.trace import Trace, AsyncTrace
 from agentex.lib.core.tracing.tracer import Tracer, AsyncTracer
+from agentex.lib.core.tracing.span_error import (
+    PlatformError,
+    ApplicationError,
+    CategorizedError,
+)
 from agentex.lib.core.tracing.span_queue import (
     AsyncSpanQueue,
     get_default_span_queue,
@@ -13,6 +18,9 @@
     "Span",
     "Tracer",
     "AsyncTracer",
+    "CategorizedError",
+    "ApplicationError",
+    "PlatformError",
     "AsyncSpanQueue",
     "get_default_span_queue",
     "shutdown_default_span_queue",

src/agentex/lib/core/tracing/span_error.py

@@ -18,6 +18,31 @@
 _ERROR_CATEGORIES = frozenset({"application", "platform", "unknown"})
 
 
+class CategorizedError(Exception):
+    """Base class for failures with known operational ownership.
+
+    Use ``ApplicationError`` for failures owned by agent or caller code, such
+    as business logic, user input, tools, or application configuration. Use
+    ``PlatformError`` only at a known Agentex/SGP-owned boundary, such as
+    managed runtime, tracing, persistence, or platform networking. Leave
+    unclassified failures as ordinary exceptions so they remain ``unknown``.
+    """
+
+    error_category: ErrorCategory = ERROR_CATEGORY_UNKNOWN
+
+
+class ApplicationError(CategorizedError):
+    """Failure owned by the agent application or its caller."""
+
+    error_category: ErrorCategory = "application"
+
+
+class PlatformError(CategorizedError):
+    """Failure owned by Agentex/SGP or a platform-managed dependency."""
+
+    error_category: ErrorCategory = "platform"
+
+
 def _normalize_error_category(value: object) -> ErrorCategory | None:
     if isinstance(value, str):
         normalized = value.strip().lower()
@@ -33,7 +58,7 @@ def _error_category(
     """Return an explicit producer classification, defaulting safely to unknown."""
     return (
         _normalize_error_category(explicit_category)
-        or _normalize_error_category(getattr(exc, "error_category", None))
+        or (exc.error_category if isinstance(exc, CategorizedError) else None)
         or ERROR_CATEGORY_UNKNOWN
     )
 
@@ -46,8 +71,8 @@ def set_span_error(
 ) -> None:
     """Record an exception on ``span`` under ``data[SPAN_ERROR_KEY]``.
 
-    An explicit ``error_category`` takes precedence over an exception's
-    ``error_category`` attribute. Invalid or absent categories become unknown.
+    An explicit ``error_category`` takes precedence over a ``CategorizedError``
+    classification. Invalid or absent categories become unknown.
     No-op when ``span.data`` is a list (matching ``_add_source_to_span``, which
     only attaches metadata to dict-shaped data).
     """

tests/lib/core/tracing/test_span_error.py

@@ -11,6 +11,8 @@
 from agentex.lib.core.tracing.trace import Trace, AsyncTrace
 from agentex.lib.core.tracing.span_error import (
     SPAN_ERROR_KEY,
+    PlatformError,
+    ApplicationError,
     get_span_error,
     set_span_error,
 )
@@ -50,30 +52,30 @@ def test_set_then_get_on_none_data(self):
         }
 
     def test_set_uses_explicit_exception_category(self):
-        class PlatformFailure(RuntimeError):
-            error_category = " PLATFORM "
-
         span = _make_span(data=None)
-        set_span_error(span, PlatformFailure("unavailable"))
+        set_span_error(span, PlatformError("unavailable"))
         assert get_span_error(span) == {
-            "type": "PlatformFailure",
+            "type": "PlatformError",
             "message": "unavailable",
             "category": "platform",
         }
 
     def test_explicit_category_takes_precedence(self):
-        class PlatformFailure(RuntimeError):
-            error_category = "platform"
+        span = _make_span(data=None)
+        set_span_error(span, PlatformError("bad input"), error_category="application")
+        assert get_span_error(span)["category"] == "application"  # type: ignore[index]
 
+    def test_set_uses_application_error_category(self):
         span = _make_span(data=None)
-        set_span_error(span, PlatformFailure("bad input"), error_category="application")
+        set_span_error(span, ApplicationError("bad input"))
         assert get_span_error(span)["category"] == "application"  # type: ignore[index]
 
-    def test_set_rejects_invalid_exception_category(self):
-        exc = RuntimeError("boom")
-        exc.error_category = "infrastructure"  # type: ignore[attr-defined]
+    def test_bare_exception_attribute_does_not_opt_in(self):
+        class ImplicitlyCategorizedError(RuntimeError):
+            error_category = "platform"
+
         span = _make_span(data=None)
-        set_span_error(span, exc)
+        set_span_error(span, ImplicitlyCategorizedError("boom"))
         assert get_span_error(span)["category"] == "unknown"  # type: ignore[index]
 
     def test_set_preserves_existing_dict_keys(self):