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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.2.15
+Version: 0.2.22
 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
@@ -28,6 +28,7 @@ Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
 Provides-Extra: claude-agent-sdk
 Requires-Dist: claude-agent-sdk>=0.1.59; extra == 'claude-agent-sdk'
+Requires-Dist: mcp>=1.28.1; extra == 'claude-agent-sdk'
 Provides-Extra: demo
 Requires-Dist: langchain-anthropic>=1.4.6; extra == 'demo'
 Requires-Dist: langchain-core>=1.3.3; extra == 'demo'
@@ -380,7 +381,7 @@ backlink still renders.
 Emits attributes per the OTel GenAI semantic conventions:
 
 - `gen_ai.operation.name` — `chat`, `execute_tool`, `invoke_agent`, `retrieval`
-- `gen_ai.provider.name` — `anthropic`, `openai`, `langchain`, `struct`, …
+- `gen_ai.provider.name` — the GenAI provider on inference spans (`anthropic`, `openai`, …); platform-routed calls report the platform value (`aws.bedrock`, `gcp.vertex_ai`, `azure.ai.openai`) when detectable from the client. `invoke_agent` spans inherit the provider from their first child inference call (omitted when no model is reached); `execute_tool`/`retrieval` spans carry no provider.
 - `gen_ai.request.{model, max_tokens, temperature, top_p, top_k, stop_sequences}`
 - `gen_ai.response.{model, id, finish_reasons}`
 - `gen_ai.usage.{input_tokens, output_tokens, cache_read.input_tokens, cache_creation.input_tokens}`

{struct_sdk-0.2.15 → struct_sdk-0.2.22}/README.md

@@ -332,7 +332,7 @@ backlink still renders.
 Emits attributes per the OTel GenAI semantic conventions:
 
 - `gen_ai.operation.name` — `chat`, `execute_tool`, `invoke_agent`, `retrieval`
-- `gen_ai.provider.name` — `anthropic`, `openai`, `langchain`, `struct`, …
+- `gen_ai.provider.name` — the GenAI provider on inference spans (`anthropic`, `openai`, …); platform-routed calls report the platform value (`aws.bedrock`, `gcp.vertex_ai`, `azure.ai.openai`) when detectable from the client. `invoke_agent` spans inherit the provider from their first child inference call (omitted when no model is reached); `execute_tool`/`retrieval` spans carry no provider.
 - `gen_ai.request.{model, max_tokens, temperature, top_p, top_k, stop_sequences}`
 - `gen_ai.response.{model, id, finish_reasons}`
 - `gen_ai.usage.{input_tokens, output_tokens, cache_read.input_tokens, cache_creation.input_tokens}`

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.2.15"
+version = "0.2.22"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,7 +37,11 @@ Issues = "https://struct.ai/support"
 
 [project.optional-dependencies]
 anthropic = ["anthropic>=0.30.0"]
-claude-agent-sdk = ["claude-agent-sdk>=0.1.59"]
+# mcp>=1.28.1 pinned directly (not just in override-dependencies below) so it
+# ships in this extra's published wheel metadata — CVE-2026-52870,
+# CVE-2026-52869, CVE-2026-59950 (GHSA-hvrp-rf83-w775, GHSA-jpw9-pfvf-9f58,
+# GHSA-vj7q-gjh5-988w).
+claude-agent-sdk = ["claude-agent-sdk>=0.1.59", "mcp>=1.28.1"]
 langchain = ["langchain-core>=1.3.3"]
 # Responses API (openai.resources.responses) exists from 1.66.0 onward.
 openai = ["openai>=1.66.0"]
@@ -80,6 +84,8 @@ override-dependencies = [
     "starlette>=1.3.1",
     "langsmith>=0.8.18",
     "pydantic-settings>=2.14.2",
+    # CVE-2026-52870, CVE-2026-52869, CVE-2026-59950 (GHSA-hvrp-rf83-w775, GHSA-jpw9-pfvf-9f58, GHSA-vj7q-gjh5-988w)
+    "mcp>=1.28.1",
 ]
 
 [tool.pytest.ini_options]

struct_sdk-0.2.22/src/struct_sdk/_genai_content.py

@@ -0,0 +1,580 @@
+"""Provider-agnostic GenAI content primitives — shared by the anthropic and
+openai integrations.
+
+This module is the single home for the pieces that are genuinely the same
+across providers once a message/response has been mapped to the spec's
+``{"role", "parts"}`` shape:
+
+- Truncation constants + helpers (``truncate_field`` / ``truncate_parts`` /
+  ``truncate_and_serialize`` / ``safe_json``).
+- The low-level per-message and choice LogRecord emitters
+  (``emit_message_event`` / ``emit_choice_event``) — they take already-built
+  ``parts`` and a ``provider`` string, so the OTel logs data-model wiring
+  (``body`` = event tag, ``attributes['body']`` = JSON payload, span-context
+  from the EXPLICIT span) lives in exactly one place.
+- ``propagate_user_prompt_to_parent`` — write-once parent ``gen_ai.input.messages``
+  from the last user message's parts.
+
+The per-provider MAPPER (Anthropic message blocks vs OpenAI Responses items ->
+``parts``) is the only content code that stays provider-specific; it lives in
+``anthropic.py`` / ``openai.py`` and calls into this module.
+
+Both this bug (OpenAI emitting zero content) and the earlier reset bug came from
+``openai.py`` diverging from ``anthropic.py``; sharing these primitives is the
+structural fix. Everything here is written to NEVER fault the customer call —
+each public emitter is wrapped in try/except -> ``logger.debug``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import sys
+import time
+from typing import Any, Callable, Iterator, Optional
+from urllib.parse import urlparse
+
+from opentelemetry import trace
+from opentelemetry.trace import StatusCode
+
+logger = logging.getLogger("struct_sdk._genai_content")
+
+# Max size for content attributes (JSON strings on spans).
+_MAX_CONTENT_SIZE = 128 * 1024  # 128KB — generous limit for full message capture
+_TRUNCATION_MARKER = "… [truncated]"
+# Per-field cap: individual text/content fields longer than this get truncated.
+_MAX_FIELD_SIZE = 16384  # 16KB per field
+
+
+# ---------------------------------------------------------------------------
+# Truncation / serialization
+# ---------------------------------------------------------------------------
+
+def truncate_field(value: "str | Any", max_len: int = _MAX_FIELD_SIZE) -> "str | Any":
+    """Truncate a single string field if it exceeds ``max_len``."""
+    if isinstance(value, str) and len(value) > max_len:
+        return value[:max_len] + _TRUNCATION_MARKER
+    return value
+
+
+def truncate_parts(parts: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Truncate content fields within message parts (content/arguments/response)."""
+    result = []
+    for part in parts:
+        part = dict(part)  # shallow copy
+        if "content" in part and isinstance(part["content"], str):
+            part["content"] = truncate_field(part["content"])
+        if "arguments" in part:
+            arg = part["arguments"]
+            if isinstance(arg, str):
+                part["arguments"] = truncate_field(arg)
+            elif isinstance(arg, dict):
+                serialized = json.dumps(arg, default=str)
+                if len(serialized) > _MAX_FIELD_SIZE:
+                    part["arguments"] = serialized[:_MAX_FIELD_SIZE] + _TRUNCATION_MARKER
+        if "response" in part:
+            resp = part["response"]
+            if isinstance(resp, str):
+                part["response"] = truncate_field(resp)
+            elif isinstance(resp, (dict, list)):
+                serialized = json.dumps(resp, default=str)
+                if len(serialized) > _MAX_FIELD_SIZE:
+                    part["response"] = serialized[:_MAX_FIELD_SIZE] + _TRUNCATION_MARKER
+        result.append(part)
+    return result
+
+
+def truncate_and_serialize(obj: Any, max_size: int = _MAX_CONTENT_SIZE) -> str:
+    """Truncate individual fields in message structures, then serialize.
+
+    Unlike a blind string slice, this preserves valid JSON by truncating
+    content/arguments/response fields within parts before serialization.
+    If the result still exceeds ``max_size`` after field truncation, applies
+    a final hard cap that tries to keep the JSON array parseable.
+    """
+    if isinstance(obj, list):
+        truncated = []
+        for item in obj:
+            if isinstance(item, dict):
+                item = dict(item)  # shallow copy
+                if "parts" in item and isinstance(item["parts"], list):
+                    item["parts"] = truncate_parts(item["parts"])
+                elif "content" in item and isinstance(item["content"], str):
+                    # Top-level content (e.g. system_instructions format)
+                    item["content"] = truncate_field(item["content"])
+            truncated.append(item)
+        result = json.dumps(truncated, default=str)
+    else:
+        result = json.dumps(obj, default=str)
+
+    # If still too large after field-level truncation, do a final hard cap
+    # but try to close the JSON array to keep it parseable.
+    if len(result) > max_size:
+        cut = result[:max_size - 50]  # leave room for closing
+        last_brace = cut.rfind("}")
+        if last_brace > 0:
+            result = cut[:last_brace + 1] + "]"
+        else:
+            result = "[]"
+
+    return result
+
+
+def safe_json(obj: Any) -> str:
+    """Safely serialize to JSON string with field-level truncation."""
+    try:
+        return truncate_and_serialize(obj)
+    except Exception:
+        return "[]"
+
+
+# ---------------------------------------------------------------------------
+# LogRecord emission — OTel logs data model
+# ---------------------------------------------------------------------------
+
+def emit_message_event(
+    otel_logger: Any,
+    *,
+    role: str,
+    parts: list[dict[str, Any]],
+    event_name: str,
+    provider: str,
+    message_index: int,
+    span: Optional[trace.Span] = None,
+) -> None:
+    """Emit ONE per-message LogRecord linked to ``span``.
+
+    OTel logs data-model convention:
+    - ``body`` (log record body): the event tag (``gen_ai.user.message`` etc.).
+    - ``attributes['body']``: the JSON payload ``{"role": ..., "parts": [...]}``.
+    - Other attributes: ``event.name``, ``gen_ai.provider.name``,
+      ``gen_ai.message.index``, and ``gen_ai.conversation.id`` when a session is
+      active.
+
+    Span-context is taken from the EXPLICIT ``span`` when given —
+    ``trace.get_current_span()`` can drop the active span across the generator
+    wrapper's async awaits. All work is best-effort: a failure here NEVER
+    reaches the customer's call (it becomes a ``logger.debug``).
+    """
+    try:
+        from opentelemetry._logs import LogRecord, SeverityNumber
+
+        span_ctx = (span or trace.get_current_span()).get_span_context()
+        from struct_sdk.core import _current_session_id
+        session_id = _current_session_id.get(None)
+
+        payload = json.dumps({"role": role, "parts": truncate_parts(parts)}, default=str)
+        attrs: dict[str, Any] = {
+            "event.name": event_name,
+            "body": payload,
+            "gen_ai.provider.name": provider,
+            "gen_ai.message.index": message_index,
+        }
+        if session_id:
+            attrs["gen_ai.conversation.id"] = session_id
+
+        otel_logger.emit(LogRecord(
+            timestamp=int(time.time_ns()),
+            trace_id=span_ctx.trace_id,
+            span_id=span_ctx.span_id,
+            trace_flags=span_ctx.trace_flags,
+            severity_number=SeverityNumber.INFO,
+            body=event_name,
+            attributes=attrs,
+        ))
+    except Exception:
+        logger.debug("Failed to emit message event", exc_info=True)
+
+
+def emit_choice_event(
+    otel_logger: Any,
+    *,
+    parts: list[dict[str, Any]],
+    finish_reason: str,
+    provider: str,
+    span: Optional[trace.Span] = None,
+) -> None:
+    """Emit a ``gen_ai.choice`` LogRecord for the assistant's response.
+
+    ``parts`` are already spec-shaped assistant parts and ``finish_reason`` is
+    already mapped to the spec name by the caller (mapping is provider-specific).
+    The ``choice`` event omits ``gen_ai.message.index``.
+    """
+    try:
+        from opentelemetry._logs import LogRecord, SeverityNumber
+
+        span_ctx = (span or trace.get_current_span()).get_span_context()
+        from struct_sdk.core import _current_session_id
+        session_id = _current_session_id.get(None)
+
+        choice_body = {
+            "index": 0,
+            "finish_reason": finish_reason or "stop",
+            "message": {"role": "assistant", "parts": truncate_parts(parts)},
+        }
+        payload = json.dumps(choice_body, default=str)
+        event_name = "gen_ai.choice"
+        attrs: dict[str, Any] = {
+            "event.name": event_name,
+            "body": payload,
+            "gen_ai.provider.name": provider,
+        }
+        if session_id:
+            attrs["gen_ai.conversation.id"] = session_id
+
+        otel_logger.emit(LogRecord(
+            timestamp=int(time.time_ns()),
+            trace_id=span_ctx.trace_id,
+            span_id=span_ctx.span_id,
+            trace_flags=span_ctx.trace_flags,
+            severity_number=SeverityNumber.INFO,
+            body=event_name,
+            attributes=attrs,
+        ))
+    except Exception:
+        logger.debug("Failed to emit choice event", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# Host-boundary span lifecycle
+# ---------------------------------------------------------------------------
+
+def _contain(fn: Any, site: str) -> None:
+    """``_safe`` with BASE-exception containment, for satellites that run
+    directly ON THE HOST CALL PATH only: guarded_client_span's start/attach/
+    finalize/end, and the create-path error satellites that stringify the
+    host's exception inside ``gen.throw``. There, a host-installed
+    SpanProcessor (or a host exception's ``__str__``) raising
+    KeyboardInterrupt/SystemExit would otherwise replace the provider's
+    successful result or in-flight exception — the one thing the harness
+    guarantees cannot happen. Deliberately NOT the global ``_safe``
+    semantics: everywhere else, delaying a genuine Ctrl-C matters more than
+    a hostile input.
+    """
+    try:
+        fn()
+    except BaseException:  # noqa: BLE001 — containment is the contract here
+        try:
+            logger.debug("telemetry self-fault contained at %s", site, exc_info=True)
+        except BaseException:  # noqa: BLE001
+            pass
+
+
+@contextlib.contextmanager
+def guarded_client_span(tracer: Any, span_name: str) -> Iterator[Any]:
+    """Explicit CLIENT span with ``_safe``-guarded start and end.
+
+    Deliberately NOT ``start_as_current_span``: ``use_span``'s exit runs
+    ``span.end()`` — and with it every customer-added ``SpanProcessor.on_end``
+    — plus its own ``record_exception``/``set_status`` (which stringify the
+    host's exception) UNGUARDED, and in the create-path generator sandwich
+    that exit executes on the ``gen.send``/``gen.throw`` HOST path. A broken
+    processor or a host exception with a raising ``__str__`` would replace
+    the customer's result/exception (host-crash-on-success).
+
+    This CM starts the span under ``_safe`` (yields ``None`` on failure — the
+    caller's ``_safe`` satellites degrade to no-telemetry) and ends it under
+    ``_safe`` on every exit. Ambient propagation is GUARDED, not removed: the
+    span is attached to the current context via a ``_safe`` satellite so a
+    customer's own downstream instrumentation (their HTTP-layer spans fired
+    during the provider call) still nests under ``chat`` — removing
+    propagation outright was struct-sdk-typescript's round-2 regression
+    (#3280, 343de609d). A hostile runtime context degrades to no-ambient
+    (span still emitted; event linkage rides the explicit span); OTel's
+    ``context.detach`` swallows internally and is ``_safe``-wrapped besides.
+    Nothing host-controllable wraps the caller's block unguarded. Mirrors
+    struct-sdk-typescript's ``instrumentCall``.
+    """
+    from opentelemetry import trace as _trace
+
+    from struct_sdk.core import (
+        _attach_current_span,
+        _detach_current_span,
+    )
+
+    span: Any = None
+    token: Any = None
+    enter_task: Any = None
+
+    def start() -> None:
+        nonlocal span
+        span = tracer.start_span(span_name, kind=_trace.SpanKind.CLIENT)
+
+    # DOCUMENTED DEGRADE: if a host-installed SpanProcessor raises from
+    # on_start, the OTel SDK lets it propagate out of start_span WITHOUT
+    # guarding (SynchronousMultiSpanProcessor.on_start is a bare loop) and
+    # the just-created span's reference never escapes the SDK frame — it is
+    # unrecoverable at this layer, and earlier processors see an on_start
+    # with no on_end. Host survival takes precedence (the OTel spec requires
+    # processors not to throw); recovering would need a global span registry,
+    # which AGENTS.md §7 forbids for exactly this kind of unreachable-in-
+    # practice input. The same degrade existed for plain Exception under
+    # ``_safe`` since this CM's inception.
+    _contain(start, "genai.client_span.start")
+
+    if span is not None:
+        def attach_ambient() -> None:
+            # Reuse the SDK's ONE ambient-context lifecycle (task-aware pair
+            # from core): a cross-task exit must SKIP the detach — OTel logs
+            # "Failed to detach context" at ERROR internally, before _safe
+            # could suppress it. No second lifecycle to drift.
+            nonlocal token, enter_task
+            token, enter_task = _attach_current_span(span)
+
+        _contain(attach_ambient, "genai.client_span.attach")
+    try:
+        yield span
+    finally:
+        if span is not None:
+            def finalize_base_exception() -> None:
+                # The caller's except-blocks record ordinary Exceptions; a
+                # BaseException (CancelledError, KeyboardInterrupt) bypasses
+                # them, so record it here — status + error.type only, message
+                # is the type name (never str(exc): hostile __str__).
+                # GeneratorExit is normal generator teardown, not a failure.
+                exc = sys.exc_info()[1]
+                if (
+                    exc is not None
+                    and not isinstance(exc, Exception)
+                    and not isinstance(exc, GeneratorExit)
+                ):
+                    span.set_attribute("error.type", type(exc).__name__)
+                    span.set_status(StatusCode.ERROR, type(exc).__name__)
+
+            _contain(finalize_base_exception, "genai.client_span.finalize_base")
+        _contain(lambda: _detach_current_span(token, enter_task), "genai.client_span.detach")
+        if span is not None:
+            _contain(span.end, "genai.client_span.end")
+
+
+# ---------------------------------------------------------------------------
+# Generator-sandwich drivers — the host-boundary CHOKE POINT
+# ---------------------------------------------------------------------------
+#
+# Provider modules express telemetry as a generator that yields exactly once:
+# ``f, call_args, call_kwargs = yield`` marks the host call; code before the
+# yield is setup, the except-block is error telemetry, code after is success
+# telemetry. These two drivers own EVERY interaction with such a generator
+# (prime / error-forward / complete) under BaseException containment, so the
+# host-crash-on-success invariant holds structurally: a telemetry fault at
+# ANY point degrades telemetry, never the host call. Per-site ``_safe`` /
+# ``_contain`` calls inside the generators improve degradation quality (a
+# broken satellite loses one attribute, not the span); they are no longer
+# what stands between a hostile input and the customer's result. Mirrors
+# struct-sdk-typescript's single ``instrumentCall`` combinator (and OTel
+# contrib's ``safeExecuteInTheMiddle``).
+
+
+def _log_contained(site: str) -> None:
+    try:
+        logger.debug("telemetry self-fault contained at %s", site, exc_info=True)
+    except BaseException:  # noqa: BLE001 — containment is the contract here
+        pass
+
+
+def _prime_sandwich(make_gen: Any, site: str) -> Any:
+    """Create + advance the telemetry generator to its yield, contained.
+
+    Returns ``(gen, f, call_args, call_kwargs)`` or ``None`` on any fault —
+    including a hostile yielded shape — so the caller can degrade to an
+    uninstrumented host call.
+    """
+    try:
+        gen = make_gen()
+        f, call_args, call_kwargs = next(gen)
+        return gen, f, call_args, call_kwargs
+    except BaseException:  # noqa: BLE001
+        _log_contained(site + ".prime")
+        return None
+
+
+def _forward_error(gen: Any, exc: BaseException, site: str) -> Any:
+    """Drive the generator's error path, contained. The host's original
+    exception must keep propagating AS ITSELF even if the generator's error
+    telemetry raises something else. Returns a ``StopIteration`` value only
+    if the generator swallowed the error and returned one."""
+    try:
+        gen.throw(exc)
+    except StopIteration as e:
+        return e.value
+    except BaseException as out:
+        if out is exc:
+            raise
+        _log_contained(site + ".error_telemetry")
+        raise exc from None
+    # Generator yielded again instead of re-raising — out of contract;
+    # surface the host's error regardless.
+    raise exc
+
+
+def _complete_sandwich(gen: Any, result: Any, site: str) -> Any:
+    """Drive the generator's success path, contained. After the host call
+    SUCCEEDS, nothing raised during telemetry completion may replace the
+    result (a lazy response property can raise even ``KeyboardInterrupt``
+    during extraction)."""
+    try:
+        return gen.send(result)
+    except StopIteration as e:
+        return e.value
+    except BaseException:  # noqa: BLE001 — telemetry-only from here
+        _log_contained(site + ".completion")
+        return result
+
+
+def drive_instrumented_call(
+    make_gen: Any, original: Any, args: Any, kwargs: Any, site: str
+) -> Any:
+    """SYNC choke point: telemetry generator sandwich around ``original``."""
+    primed = _prime_sandwich(make_gen, site)
+    if primed is None:
+        return original(*args, **kwargs)
+    gen, f, call_args, call_kwargs = primed
+    try:
+        result = f(*call_args, **call_kwargs)
+    except BaseException as exc:  # host error — forward into the generator
+        return _forward_error(gen, exc, site)
+    return _complete_sandwich(gen, result, site)
+
+
+async def drive_instrumented_call_async(
+    make_gen: Any, original: Any, args: Any, kwargs: Any, site: str
+) -> Any:
+    """ASYNC choke point — identical semantics; only the host call awaits."""
+    primed = _prime_sandwich(make_gen, site)
+    if primed is None:
+        return await original(*args, **kwargs)
+    gen, f, call_args, call_kwargs = primed
+    try:
+        result = await f(*call_args, **call_kwargs)
+    except BaseException as exc:  # host error — forward into the generator
+        return _forward_error(gen, exc, site)
+    return _complete_sandwich(gen, result, site)
+
+
+# ---------------------------------------------------------------------------
+# Platform detection — shared by the anthropic/openai emitters
+# ---------------------------------------------------------------------------
+
+def detect_provider_from_resource(
+    resource: Any,
+    class_name_rules: tuple[tuple[frozenset[str], str], ...],
+    host_rules: tuple[tuple[Callable[[str], bool], str], ...],
+    default: str,
+) -> str:
+    """Best-knowledge ``gen_ai.provider.name`` from a bound resource.
+
+    The platform client flavors (Bedrock/Vertex/Azure) reuse the exact same
+    resource classes as the first-party clients, so the platform can only be
+    read at call time from the resource's owning client: EXACT class names in
+    the MRO first (exact, not substring — a customer class named
+    ``NotAzureOpenAI`` must not match; real subclasses still match via their
+    inherited base class in the MRO), then per-platform ``base_url`` host
+    predicates matching only official endpoint shapes.
+
+    Takes the RESOURCE, not the client: the ``_client`` attribute access is a
+    host-boundary read (a proxied resource can raise from its descriptor —
+    ``getattr(..., default)`` only swallows AttributeError), so it must happen
+    inside this function's guard. Falls back to ``default`` whenever routing
+    is not positively detectable; never raises.
+    """
+    try:
+        client = getattr(resource, "_client", None)
+        if client is None:
+            return default
+        mro_names = {cls.__name__ for cls in type(client).__mro__}
+        for names, provider in class_name_rules:
+            if mro_names & names:
+                return provider
+        host = urlparse(str(getattr(client, "base_url", "") or "")).hostname or ""
+        for matches_host, provider in host_rules:
+            if matches_host(host):
+                return provider
+    except Exception:  # noqa: BLE001 — detection must never fault the user's call
+        pass
+    return default
+
+
+# ---------------------------------------------------------------------------
+# Parent-span propagation
+# ---------------------------------------------------------------------------
+
+def propagate_user_prompt_to_parent(last_user_parts: Optional[list[dict[str, Any]]]) -> None:
+    """Set the last user message on the parent invoke_agent span (write-once).
+
+    This lets the waterfall UI show what the user asked without drilling into
+    the child chat span. Provider-agnostic: the caller extracts the last user
+    message's spec parts (Anthropic message blocks vs Responses items differ);
+    this just stamps them once on the ambient ``_current_agent_span``.
+    """
+    try:
+        if not last_user_parts:
+            return
+        from struct_sdk.core import _current_agent_span
+        agent_span = _current_agent_span.get(None)
+        if agent_span is None:
+            return
+        # Only set once — the first chat call within an invoke_agent scope wins.
+        existing = None
+        if hasattr(agent_span, "attributes"):
+            existing = agent_span.attributes.get("gen_ai.input.messages")  # type: ignore[union-attr]
+        if existing:
+            return
+        agent_span.set_attribute(
+            "gen_ai.input.messages",
+            truncate_and_serialize([{"role": "user", "parts": last_user_parts}]),
+        )
+    except Exception:
+        pass  # Never break the application for telemetry
+
+
+def stamp_provider_once(agent_span: Any, provider: Optional[str]) -> None:
+    """Write-once ``gen_ai.provider.name`` on an invoke_agent span.
+
+    The GenAI spec puts ``gen_ai.provider.name`` on invoke_agent spans, but
+    the layer that CREATES those spans (``struct.agent()``, the LangChain
+    handler) is provider-agnostic — only a child inference call knows the
+    value. The first child call stamps it; an agent that never reaches a
+    model omits the attribute rather than carrying a framework name.
+
+    CONTRACT: ``agent_span`` is always an SDK-OWNED span — created by our own
+    tracer in ``struct.agent()`` or the LangChain handler, and delivered here
+    via ``_current_agent_span`` / the handler's run map, which nothing else
+    writes. It is never a host-supplied object. That is why the industry-
+    standard owned-object pattern applies (state lives ON the object, like
+    Sentry/dd-trace private span fields): a private sentinel attribute set
+    after a successful write. No global registries, locks, or weakref
+    lifecycles — those are for FOREIGN objects (see AGENTS.md: prefer
+    industry-standard telemetry patterns; don't defend interfaces no call
+    path can violate).
+
+    Semantics: "a real child provider" — if two child calls with DIFFERENT
+    providers race in the same instant, either may win; both are real
+    providers, and the semconv does not privilege one for a multi-provider
+    agent. The sentinel is set only after a successful write, so a transient
+    ``set_attribute`` failure can be retried by the next child call.
+    """
+    try:
+        if not provider or agent_span is None:
+            return
+        if getattr(agent_span, "_struct_provider_stamped", False):
+            return
+        agent_span.set_attribute("gen_ai.provider.name", provider)
+        try:
+            agent_span._struct_provider_stamped = True
+        except Exception:
+            # Frozen/slotted span: sentinel unavailable. Worst case a later
+            # child re-stamps another REAL provider — acceptable per the
+            # semantics above.
+            pass
+    except Exception:
+        pass  # Never break the application for telemetry
+
+
+def propagate_provider_to_parent(provider: Optional[str]) -> None:
+    """Stamp the ambient ``_current_agent_span`` with the child call's provider."""
+    try:
+        from struct_sdk.core import _current_agent_span
+        stamp_provider_once(_current_agent_span.get(None), provider)
+    except Exception:
+        pass  # Never break the application for telemetry