feat(tracing): integrate shared error ownership classifier

Configure Agentex-owned frames in the shared tracing classifier and forward its privacy-safe provenance without duplicating inference logic.

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

Author: jshaikScale

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

@@ -2,10 +2,16 @@
 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 (
+    ERROR_CLASSIFIER_VERSION,
+    AGENTEX_ERROR_CLASSIFIER_CONFIG,
     ErrorCategory,
     PlatformError,
     ApplicationError,
     CategorizedError,
+    ExceptionMapping,
+    ErrorClassification,
+    ErrorClassifierConfig,
+    TracebackOwnershipPolicy,
 )
 from agentex.lib.core.tracing.span_queue import (
     AsyncSpanQueue,
@@ -23,6 +29,12 @@
     "ApplicationError",
     "PlatformError",
     "ErrorCategory",
+    "ExceptionMapping",
+    "ErrorClassification",
+    "ErrorClassifierConfig",
+    "TracebackOwnershipPolicy",
+    "ERROR_CLASSIFIER_VERSION",
+    "AGENTEX_ERROR_CLASSIFIER_CONFIG",
     "AsyncSpanQueue",
     "get_default_span_queue",
     "shutdown_default_span_queue",

src/agentex/lib/core/tracing/processors/sgp_tracing_processor.py

@@ -88,6 +88,10 @@ def _build_sgp_span(span: Span, env_vars: EnvironmentVariables) -> SGPSpan:
     if error is not None:
         sgp_span.set_error(error_type=error["type"], error_message=error["message"])
         sgp_span.metadata["error_category"] = error.get("category", "unknown")
+        sgp_span.metadata["error_category_source"] = error.get("category_source", "legacy")
+        sgp_span.metadata["error_classifier_version"] = error.get("classifier_version", "legacy")
+        if "category_reason" in error:
+            sgp_span.metadata["error_category_reason"] = error["category_reason"]
     return sgp_span
 
 

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

@@ -1,11 +1,18 @@
 from __future__ import annotations
 
+import os
 from typing import Any, cast
 
 from scale_gp_beta.lib.tracing import (
+    ERROR_CLASSIFIER_VERSION as ERROR_CLASSIFIER_VERSION,
     PlatformError as PlatformError,
     ApplicationError as ApplicationError,
-    CategorizedError,
+    CategorizedError as CategorizedError,
+    ExceptionMapping as ExceptionMapping,
+    ErrorClassification as ErrorClassification,
+    ErrorClassifierConfig as ErrorClassifierConfig,
+    TracebackOwnershipPolicy,
+    classify_error,
 )
 from scale_gp_beta.lib.tracing.types import ErrorCategory
 
@@ -20,47 +27,47 @@
 # SGP and agentex-native span stores.
 SPAN_ERROR_KEY = "__error__"
 
-ERROR_CATEGORY_UNKNOWN: ErrorCategory = "unknown"
-_ERROR_CATEGORIES = frozenset({"application", "platform", "unknown"})
-
-
-def _normalize_error_category(value: object) -> ErrorCategory | None:
-    if isinstance(value, str):
-        normalized = value.strip().lower()
-        if normalized in _ERROR_CATEGORIES:
-            return cast(ErrorCategory, normalized)
-    return None
-
-
-def _error_category(
-    exc: BaseException,
-    explicit_category: ErrorCategory | str | None = None,
-) -> ErrorCategory:
-    """Return an explicit producer classification, defaulting safely to unknown."""
-    return (
-        _normalize_error_category(explicit_category)
-        or (exc.error_category if isinstance(exc, CategorizedError) else None)
-        or ERROR_CATEGORY_UNKNOWN
+_AGENTEX_PACKAGE_ROOT = os.path.normcase(os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "..", "..")))
+AGENTEX_ERROR_CLASSIFIER_CONFIG = ErrorClassifierConfig(
+    policy=TracebackOwnershipPolicy(
+        platform_module_prefixes=("agentex",),
+        platform_file_roots=(_AGENTEX_PACKAGE_ROOT,),
+        infer_application_from_unowned_absolute_paths=True,
     )
+)
 
 
 def set_span_error(
     span: Span,
     exc: BaseException,
     *,
     error_category: ErrorCategory | str | None = None,
+    boundary_category: ErrorCategory | None = None,
+    mapping_scope: str | None = None,
+    classifier_config: ErrorClassifierConfig = AGENTEX_ERROR_CLASSIFIER_CONFIG,
 ) -> None:
     """Record an exception on ``span`` under ``data[SPAN_ERROR_KEY]``.
 
-    An explicit ``error_category`` takes precedence over a ``CategorizedError``
-    classification. Invalid or absent categories become unknown.
+    The shared Scale GP classifier inspects the exception's existing traceback
+    using Agentex's ownership policy. Explicit and typed categories remain
+    authoritative; boundary hints and scoped mappings are fallback signals.
     No-op when ``span.data`` is a list (matching ``_add_source_to_span``, which
     only attaches metadata to dict-shaped data).
     """
+    classification = classify_error(
+        exc,
+        explicit_category=cast(ErrorCategory | None, error_category),
+        boundary_category=boundary_category,
+        mapping_scope=mapping_scope,
+        config=classifier_config,
+    )
     error = {
         "type": type(exc).__name__,
         "message": str(exc),
-        "category": _error_category(exc, error_category),
+        "category": classification.category,
+        "category_source": classification.source,
+        "classifier_version": classification.classifier_version,
+        "category_reason": classification.reason,
     }
     if span.data is None:
         span.data = {}

tests/lib/adk/test_tracing_module.py

@@ -10,7 +10,7 @@
 from agentex.types.span import Span
 from agentex.lib.core.harness.types import TurnUsage
 from agentex.lib.adk._modules.tracing import TurnSpan, TracingModule
-from agentex.lib.core.tracing.span_error import get_span_error
+from agentex.lib.core.tracing.span_error import ERROR_CLASSIFIER_VERSION, get_span_error
 from agentex.lib.core.services.adk.tracing import TracingService
 
 
@@ -264,7 +264,10 @@ async def test_span_context_manager_records_and_reraises_body_error(self):
         assert get_span_error(started) == {
             "type": "RuntimeError",
             "message": "boom",
-            "category": "unknown",
+            "category": "application",
+            "category_source": "stack_trace",
+            "classifier_version": ERROR_CLASSIFIER_VERSION,
+            "category_reason": "stack_rule:unowned_absolute_source",
         }
         mock_service.end_span.assert_called_once_with(trace_id="trace-123", span=started)
 

tests/lib/core/tracing/test_span_error.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import uuid
 from typing import Any
 from datetime import UTC, datetime
@@ -16,6 +17,7 @@
 from agentex.lib.core.tracing.trace import Trace, AsyncTrace
 from agentex.lib.core.tracing.span_error import (
     SPAN_ERROR_KEY,
+    ERROR_CLASSIFIER_VERSION,
     PlatformError,
     ApplicationError,
     CategorizedError,
@@ -36,6 +38,12 @@ def _make_span(data=None) -> Span:
     )
 
 
+def _synthetic_function(module_name: str, filename: str, body: str, **values: Any) -> Any:
+    namespace = {"__name__": module_name, **values}
+    exec(compile(f"def run():\n    {body}\n", filename, "exec"), namespace)
+    return namespace["run"]
+
+
 # ---------------------------------------------------------------------------
 # Helpers: set_span_error / get_span_error
 # ---------------------------------------------------------------------------
@@ -54,13 +62,12 @@ def test_set_then_get_on_none_data(self):
             "type": "ValueError",
             "message": "boom",
             "category": "unknown",
+            "category_source": "fallback",
+            "classifier_version": ERROR_CLASSIFIER_VERSION,
+            "category_reason": "stack_no_traceback",
         }
         assert isinstance(span.data, dict)
-        assert span.data[SPAN_ERROR_KEY] == {
-            "type": "ValueError",
-            "message": "boom",
-            "category": "unknown",
-        }
+        assert span.data[SPAN_ERROR_KEY] == get_span_error(span)
 
     def test_set_uses_explicit_exception_category(self):
         span = _make_span(data=None)
@@ -69,12 +76,18 @@ def test_set_uses_explicit_exception_category(self):
             "type": "PlatformError",
             "message": "unavailable",
             "category": "platform",
+            "category_source": "categorized_error",
+            "classifier_version": ERROR_CLASSIFIER_VERSION,
+            "category_reason": "canonical_categorized_error",
         }
 
     def test_explicit_category_takes_precedence(self):
         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]
+        error = get_span_error(span)
+        assert error is not None
+        assert error["category"] == "application"
+        assert error["category_source"] == "explicit"
 
     def test_set_uses_application_error_category(self):
         span = _make_span(data=None)
@@ -89,6 +102,54 @@ class ImplicitlyCategorizedError(RuntimeError):
         set_span_error(span, ImplicitlyCategorizedError("boom"))
         assert get_span_error(span)["category"] == "unknown"  # type: ignore[index]
 
+    def test_agentex_internal_origin_is_platform(self):
+        platform = _synthetic_function(
+            "agentex.lib.synthetic_runtime",
+            "/synthetic/agentex/runtime.py",
+            "raise RuntimeError('boom')",
+        )
+        span = _make_span()
+        try:
+            platform()
+        except Exception as exc:
+            set_span_error(span, exc)
+
+        error = get_span_error(span)
+        assert error is not None
+        assert error["category"] == "platform"
+        assert error["category_source"] == "stack_trace"
+        assert error["category_reason"] == "stack_rule:platform_module"
+
+    def test_stdlib_dependency_under_application_is_application(self):
+        application = _synthetic_function(
+            "customer_agent.main",
+            "/synthetic/application/main.py",
+            "parse('{')",
+            parse=json.loads,
+        )
+        span = _make_span()
+        try:
+            application()
+        except Exception as exc:
+            set_span_error(span, exc)
+
+        assert get_span_error(span)["category"] == "application"  # type: ignore[index]
+
+    def test_stdlib_dependency_under_agentex_is_platform(self):
+        platform = _synthetic_function(
+            "agentex.lib.synthetic_runtime",
+            "/synthetic/agentex/runtime.py",
+            "parse('{')",
+            parse=json.loads,
+        )
+        span = _make_span()
+        try:
+            platform()
+        except Exception as exc:
+            set_span_error(span, exc)
+
+        assert get_span_error(span)["category"] == "platform"  # type: ignore[index]
+
     def test_set_preserves_existing_dict_keys(self):
         span = _make_span(data={"__span_type__": "LLM"})
         set_span_error(span, RuntimeError("nope"))
@@ -127,7 +188,10 @@ def test_sync_span_records_error_and_reraises(self):
         assert err == {
             "type": "ValueError",
             "message": "boom",
-            "category": "unknown",
+            "category": "application",
+            "category_source": "stack_trace",
+            "classifier_version": ERROR_CLASSIFIER_VERSION,
+            "category_reason": "stack_rule:unowned_absolute_source",
         }
 
     def test_sync_span_success_has_no_error(self):
@@ -148,7 +212,10 @@ async def test_async_span_records_error_and_reraises(self):
         assert err == {
             "type": "RuntimeError",
             "message": "kaboom",
-            "category": "unknown",
+            "category": "application",
+            "category_source": "stack_trace",
+            "classifier_version": ERROR_CLASSIFIER_VERSION,
+            "category_reason": "stack_rule:unowned_absolute_source",
         }
 
 
@@ -193,6 +260,9 @@ def test_error_maps_to_status_error(self):
                     "type": "ValueError",
                     "message": "boom",
                     "category": "application",
+                    "category_source": "stack_trace",
+                    "classifier_version": ERROR_CLASSIFIER_VERSION,
+                    "category_reason": "stack_rule:application_module",
                 }
             }
         )
@@ -204,6 +274,9 @@ def test_error_maps_to_status_error(self):
         assert sgp_span.metadata["error_type"] == "ValueError"
         assert sgp_span.metadata["error_message"] == "boom"
         assert sgp_span.metadata["error_category"] == "application"
+        assert sgp_span.metadata["error_category_source"] == "stack_trace"
+        assert sgp_span.metadata["error_classifier_version"] == ERROR_CLASSIFIER_VERSION
+        assert sgp_span.metadata["error_category_reason"] == "stack_rule:application_module"
 
     def test_no_error_leaves_status_success(self):
         from agentex.lib.core.tracing.processors.sgp_tracing_processor import _build_sgp_span

tests/test_adk_tracing_span_error.py

@@ -23,7 +23,7 @@
 
 from agentex.types.span import Span
 from agentex.lib.adk._modules.tracing import TracingModule
-from agentex.lib.core.tracing.span_error import get_span_error
+from agentex.lib.core.tracing.span_error import ERROR_CLASSIFIER_VERSION, get_span_error
 
 
 def _make_module() -> tuple[TracingModule, Span, AsyncMock]:
@@ -51,7 +51,10 @@ async def test_span_records_error_and_reraises() -> None:
     assert error == {
         "type": "ValueError",
         "message": "boom",
-        "category": "unknown",
+        "category": "application",
+        "category_source": "stack_trace",
+        "classifier_version": ERROR_CLASSIFIER_VERSION,
+        "category_reason": "stack_rule:unowned_absolute_source",
     }
 
     # end_span still ran (finally) and saw the span with the error already set,
@@ -61,7 +64,10 @@ async def test_span_records_error_and_reraises() -> None:
     assert get_span_error(persisted_span) == {
         "type": "ValueError",
         "message": "boom",
-        "category": "unknown",
+        "category": "application",
+        "category_source": "stack_trace",
+        "classifier_version": ERROR_CLASSIFIER_VERSION,
+        "category_reason": "stack_rule:unowned_absolute_source",
     }
 
 
@@ -115,6 +121,9 @@ async def test_turn_span_records_error_and_reraises() -> None:
     assert get_span_error(span) == {
         "type": "ValueError",
         "message": "boom",
-        "category": "unknown",
+        "category": "application",
+        "category_source": "stack_trace",
+        "classifier_version": ERROR_CLASSIFIER_VERSION,
+        "category_reason": "stack_rule:unowned_absolute_source",
     }
     end_span.assert_awaited_once()