struct-sdk 0.2.13__tar.gz → 0.2.15__tar.gz

{struct_sdk-0.2.13 → struct_sdk-0.2.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.2.13
+Version: 0.2.15
 Summary: Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry
 Project-URL: Homepage, https://struct.ai
 Project-URL: Documentation, https://struct.ai/docs

{struct_sdk-0.2.13 → struct_sdk-0.2.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.2.13"
+version = "0.2.15"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"

{struct_sdk-0.2.13 → struct_sdk-0.2.15}/src/struct_sdk/core.py

@@ -161,7 +161,8 @@ def _attach_current_span(
     """Make ``span`` the current OTel span so children — customer-created raw spans
     AND nested SDK spans — nest under it (ambient-context honoring, good-citizen
     behavior). Returns ``(token, enter_task)`` for a later task-safe detach."""
-    token = _otel_context.attach(trace.set_span_in_context(span))
+    ctx = trace.set_span_in_context(span)
+    token = _otel_context.attach(ctx)
     return token, _current_task_or_none()
 
 
@@ -657,51 +658,34 @@ class _AgentContext:
                 and enclosing_agent_span is not None
             )
 
-            # ── Foreign-context guard (top-level agent run) ──────────────────
-            # A top-level agent run (no enclosing STRUCT agent) must NOT inherit
-            # whatever OTel span happens to be active. That active span may be a
-            # FOREIGN span leaked across an async boundary — e.g. a tool span from
-            # a PRIOR turn that a Temporal/queue context propagator carried into
-            # this later wake-up. Inheriting it would mis-parent this brand-new
-            # turn UNDER unrelated, long-finished work (it would show up nested in
-            # that old tool call instead of as its own turn).
+            # ── Parentage: PURE NEST (Option D) ──────────────────────────────
+            # A non-break-out agent nests under whatever OTel span is active — the
+            # host's ambient context — exactly like every peer LLM/agent SDK
+            # (Vercel, Pydantic AI, OpenLLMetry, OpenInference, Langfuse). We do NOT
+            # second-guess the active span or unilaterally re-root: the old
+            # `foreign_root` heuristic detached from ANY active span and so ripped
+            # agents out of legitimate host request traces. Cross-conversation
+            # grouping is carried by gen_ai.conversation.id, never by trace
+            # parentage.
             #
-            # So: when there is no enclosing Struct agent but some other span is
-            # active, start a FRESH ROOT trace and record that active span as a
-            # causal OTel Link (preserving "this turn was triggered by that") —
-            # never as the parent.
-            #
-            # Genuine in-run sub-agents are unaffected: they always run with an
-            # enclosing Struct agent in scope (``enclosing_session_id`` set, because
-            # the contextvar is live in the same task), so they fall through to the
-            # inherit path below and stay nested in the same trace.
-            active_span_context = trace.get_current_span().get_span_context()
-            foreign_root = (
-                not break_out
-                and enclosing_session_id is None
-                and active_span_context.is_valid
-            )
-
+            # If a runtime propagates a stale/unwanted span across a boundary — e.g.
+            # our own persistent_agent's long-lived Temporal workflow span — it is
+            # cleared at the SOURCE (edgedive-server resets the OTel context at the
+            # Temporal activity boundary so no foreign span is active here), never
+            # defended against in the SDK. (A provenance-gated detach — re-root only
+            # a leaked Struct-OWNED span, nest under host spans — is a documented
+            # follow-up, deferred until a real customer needs it.)
             if break_out:
-                # Start a fresh root span: pass context=trace.Context() to create
-                # a span with no parent (new TraceId) while keeping the current
-                # context vars readable for the span's children.
+                # Explicit different session while nested under another Struct agent:
+                # start a fresh root trace and carry a spawned-by Link to the
+                # enclosing agent. This is the one deliberate re-root, and it is
+                # opt-in (the caller passed an explicit, differing session_id).
                 assert enclosing_agent_span is not None  # narrowing for mypy
-                links = [trace.Link(enclosing_agent_span.get_span_context())]
-                self._span = tracer.start_span(
-                    f"invoke_agent {agent_name}",
-                    kind=trace.SpanKind.INTERNAL,
-                    context=_OtelContext(),  # empty context → new root trace
-                    links=links,
-                )
-            elif foreign_root:
-                # New root trace; the leaked/foreign active span becomes a Link
-                # (causal origin), NOT this turn's parent.
                 self._span = tracer.start_span(
                     f"invoke_agent {agent_name}",
                     kind=trace.SpanKind.INTERNAL,
                     context=_OtelContext(),  # empty context → new root trace
-                    links=[trace.Link(active_span_context)],
+                    links=[trace.Link(enclosing_agent_span.get_span_context())],
                 )
             else:
                 self._span = tracer.start_span(

{struct_sdk-0.2.13 → struct_sdk-0.2.15}/src/struct_sdk/langchain.py

@@ -104,10 +104,25 @@ def patch(sdk: StructSDK) -> None:
                 *args: Any,
                 **kwargs: Any,
             ) -> Any:
-                inheritable_callbacks = _inject_handler(
-                    inheritable_callbacks, _active_handler
-                )
-                local_callbacks = _strip_struct(local_callbacks)
+                # Our handler injection/stripping must NEVER break the host's
+                # configure(). It runs on the invoke/stream/batch path and,
+                # unlike the on_* callbacks, has no ``raise_error=False`` net.
+                # _inject_handler / _strip_struct read ``h.name`` / ``.handlers``
+                # on host-owned callback objects via ``getattr(..., default)``,
+                # which swallows only AttributeError — a getter raising anything
+                # else (hostile/lazy/proxy handler) would abort a host call that
+                # LangChain's own configure (which never reads ``.name``) would
+                # have completed. Degrade ATOMICALLY: on any failure fall through
+                # with the ORIGINAL args (both rebind only if both succeed).
+                # Mirrors langchain.ts's resolveConfigureHandlerArgs guard.
+                try:
+                    new_inheritable = _inject_handler(
+                        inheritable_callbacks, _active_handler
+                    )
+                    new_local = _strip_struct(local_callbacks)
+                    inheritable_callbacks, local_callbacks = new_inheritable, new_local
+                except Exception:  # noqa: BLE001 — never break the host's configure()
+                    pass
                 return orig_func(
                     cls,
                     inheritable_callbacks,