otelzero 0.2.0__py3-none-any.whl

otelzero/hooks/_content.py

@@ -0,0 +1,865 @@
+"""Prompt/response capture shared by all framework hooks.
+
+The GenAI conventions record a run's prompt and response as
+``gen_ai.input.messages`` / ``gen_ai.output.messages``: arrays of
+``{"role": ..., "parts": [...]}`` messages (see :mod:`otelzero.semconv` for the
+part shapes). Every framework spells its messages differently -- Anthropic
+content blocks, Bedrock ``{"text": ...}`` blocks, OpenAI Responses items,
+LangChain ``BaseMessage`` objects, ADK ``Content``/``Part`` objects -- and
+:func:`messages_from` folds any of them into that one shape, the way
+:mod:`otelzero.hooks._usage` does for token counts.
+
+Two rules hold throughout:
+
+* **Everything is Opt-In.** Each public function returns ``None`` immediately
+  unless ``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` is set, so a
+  hook can call them unconditionally and pay nothing by default.
+* **Nothing raises.** All reads are dict-or-attr based and any failure degrades
+  to "no content" -- never a crash in the wrapper around a user's agent.
+
+Size is bounded on the client: each text / arguments / response part is cut at
+``OTELZERO_CONTENT_MAX_CHARS`` characters (default 4000; ``0`` disables) with a
+trailing marker, and only the last ``OTELZERO_CONTENT_MAX_MESSAGES`` messages
+of a prompt or a streamed response are kept (default 20; ``0`` disables) so a
+chat history replayed on every turn doesn't grow every event.
+"""
+
+import json
+import os
+from typing import Any, List, Optional, Tuple
+
+from otelzero import semconv
+from otelzero.hooks._usage import _field
+
+MAX_CHARS_ENV = "OTELZERO_CONTENT_MAX_CHARS"
+MAX_MESSAGES_ENV = "OTELZERO_CONTENT_MAX_MESSAGES"
+DEFAULT_MAX_CHARS = 4000
+DEFAULT_MAX_MESSAGES = 20
+
+
+def enabled() -> bool:
+    """True when the user opted in to recording message content."""
+    return semconv.capture_content_enabled()
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return default
+
+
+def max_chars() -> int:
+    return _env_int(MAX_CHARS_ENV, DEFAULT_MAX_CHARS)
+
+
+def max_messages() -> int:
+    return _env_int(MAX_MESSAGES_ENV, DEFAULT_MAX_MESSAGES)
+
+
+def truncate(text: str) -> str:
+    """Cut ``text`` at the configured cap, marking how much was dropped."""
+    limit = max_chars()
+    if limit and len(text) > limit:
+        return text[:limit] + f"…[truncated, {len(text) - limit} more chars]"
+    return text
+
+
+# --- Coercions ---------------------------------------------------------------
+
+_TEXT_KEYS = ("text", "content", "output", "output_text", "result", "raw", "input", "answer")
+_TEXT_ATTRS = ("raw", "text", "content", "output", "result")
+
+
+def _first_field(obj: Any, *keys: str) -> Any:
+    for key in keys:
+        value = _field(obj, key)
+        if value is not None:
+            return value
+    return None
+
+
+def _plain(value: Any) -> Any:
+    """Unwrap enum-like values (``Role.USER`` -> ``"user"``)."""
+    return getattr(value, "value", value)
+
+
+def _text(obj: Any) -> Optional[str]:
+    """Best-effort plain text of a framework value (untruncated)."""
+    if obj is None:
+        return None
+    if isinstance(obj, str):
+        return obj
+    if isinstance(obj, dict):
+        for key in _TEXT_KEYS:
+            value = obj.get(key)
+            if isinstance(value, str):
+                return value
+        return json.dumps(obj, default=str)
+    if isinstance(obj, (list, tuple)):
+        texts = [_text(item) for item in obj]
+        return "\n".join(t for t in texts if t)
+    for attr in _TEXT_ATTRS:
+        value = getattr(obj, attr, None)
+        if isinstance(value, str):
+            return value
+    return str(obj)
+
+
+def text_of(obj: Any) -> Optional[str]:
+    """Plain text of a framework result, for a one-message response.
+
+    ``CrewOutput.raw``, an ``AIMessage.content``, a ``{"output": ...}`` dict, a
+    bare string -- whichever the framework returns. ``None`` when not opted in
+    or when there is no text.
+    """
+    if not enabled():
+        return None
+    try:
+        text = _text(obj)
+    except Exception:
+        return None
+    return text or None
+
+
+def _bounded(value: Any) -> Any:
+    """Structured tool arguments/results, kept structured while small."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return truncate(value)
+    if isinstance(value, (dict, list, tuple)):
+        dumped = json.dumps(value, default=str)
+        limit = max_chars()
+        if limit and len(dumped) > limit:
+            return truncate(dumped)
+        return json.loads(dumped)
+    return truncate(str(value))
+
+
+# --- Parts and messages ------------------------------------------------------
+
+
+def _strip(part: dict) -> dict:
+    return {k: v for k, v in part.items() if v is not None}
+
+
+def text_part(text: Any) -> Optional[dict]:
+    text = _text(text)
+    return {"type": "text", "content": truncate(text)} if text else None
+
+
+def reasoning_part(text: Any) -> Optional[dict]:
+    """A model's thinking, as the conventions' ``reasoning`` part.
+
+    Only the readable thinking text is recorded. A provider's opaque companion
+    payload -- Anthropic's ``signature``, a redacted block's ciphertext -- is
+    deliberately dropped: it is unreadable downstream and would spend the size
+    cap on bytes no one can use. A block that carries *only* such a payload
+    therefore yields no part at all.
+    """
+    text = _text(text)
+    return {"type": "reasoning", "content": truncate(text)} if text else None
+
+
+def tool_call_part(call_id: Any, name: Any, arguments: Any) -> dict:
+    return _strip(
+        {
+            "type": "tool_call",
+            "id": str(call_id) if call_id is not None else None,
+            "name": str(name) if name is not None else None,
+            "arguments": _bounded(arguments),
+        }
+    )
+
+
+def tool_call_response_part(call_id: Any, response: Any) -> dict:
+    return _strip(
+        {
+            "type": "tool_call_response",
+            "id": str(call_id) if call_id is not None else None,
+            "response": _bounded(response),
+        }
+    )
+
+
+_ROLES = {
+    "human": "user",
+    "ai": "assistant",
+    "model": "assistant",
+    "function": "tool",
+    "developer": "system",
+}
+
+
+def _role(raw: Any, default: str) -> str:
+    raw = _plain(raw)
+    if not isinstance(raw, str) or not raw:
+        return default
+    raw = raw.strip().lower()
+    return _ROLES.get(raw, raw)
+
+
+def message(role: str, parts, **extra) -> Optional[dict]:
+    """One semconv message; ``None`` when it would carry no parts."""
+    parts = [p for p in (parts or []) if p]
+    if not parts:
+        return None
+    # Tool results arrive under the *user* role in Anthropic- and
+    # OpenAI-shaped histories; the conventions file them under ``tool``.
+    if role == "user" and all(p.get("type") == "tool_call_response" for p in parts):
+        role = "tool"
+    return {"role": role, "parts": parts, **extra}
+
+
+def user_text(text: Any) -> Optional[dict]:
+    return message("user", [text_part(text)])
+
+
+def assistant_text(text: Any) -> Optional[dict]:
+    return message("assistant", [text_part(text)])
+
+
+# Block ``type`` spellings (underscores removed, lower-cased) for the two tool
+# part kinds. Class names double as types for typed SDK blocks (``ToolUseBlock``,
+# ``FunctionCallContent``) whose instances carry no ``type`` field.
+_TOOL_CALL_KINDS = {
+    "tooluse",
+    "tooluseblock",
+    "toolcall",
+    "functioncall",
+    "functioncallcontent",
+}
+_REASONING_KINDS = {
+    "thinking",
+    "thinkingblock",
+    "redactedthinking",
+    "redactedthinkingblock",
+    "reasoning",
+    "reasoningcontent",
+    "reasoningcontentblock",
+    "reasoningtext",
+}
+_TOOL_RESPONSE_KINDS = {
+    "toolresult",
+    "toolresultblock",
+    "toolcallresponse",
+    "toolresponse",
+    "functioncalloutput",
+    "functionresponse",
+    # Microsoft Agent Framework discriminates one ``Content`` class by a
+    # ``type`` field ("function_result"); older releases used a class per kind
+    # ("FunctionResultContent"), which carried no ``type`` at all.
+    "functionresult",
+    "functionresultcontent",
+}
+
+
+def _kind(block: Any) -> str:
+    btype = _plain(_field(block, "type"))
+    if not isinstance(btype, str) or not btype:
+        btype = type(block).__name__
+    return btype.replace("_", "").strip().lower()
+
+
+def _part_from(block: Any) -> Optional[dict]:
+    """Map one framework content block to a semconv part."""
+    if block is None:
+        return None
+    if isinstance(block, str):
+        return text_part(block)
+    kind = _kind(block)
+    if kind in _REASONING_KINDS:
+        # ``thinking`` (Anthropic ``ThinkingBlock``), ``summary`` (OpenAI
+        # Responses reasoning items, a list of summary_text blocks),
+        # ``reasoningText`` (Bedrock). Never ``signature``/``data``.
+        return reasoning_part(
+            _first_field(block, "thinking", "reasoningText", "summary", "text", "content")
+        )
+    if kind in _TOOL_CALL_KINDS:
+        return tool_call_part(
+            # Responses items have an item id as well as the call id their
+            # function_call_output refers to. Prefer the latter for pairing.
+            _first_field(block, "call_id", "tool_call_id", "id"),
+            _field(block, "name"),
+            _first_field(block, "input", "arguments", "args"),
+        )
+    if kind in _TOOL_RESPONSE_KINDS:
+        return tool_call_response_part(
+            _first_field(block, "tool_use_id", "call_id", "tool_call_id", "id"),
+            _first_field(block, "content", "output", "response", "result"),
+        )
+    # Bedrock / Strands blocks identify their kind with an outer key instead
+    # of a type field. Arguments and results still use the shared size bounds.
+    reasoning = _field(block, "reasoningContent")
+    if reasoning is not None:
+        return reasoning_part(_first_field(reasoning, "reasoningText", "text"))
+    call = _field(block, "toolUse")
+    if call is not None:
+        return tool_call_part(
+            _field(call, "toolUseId"), _field(call, "name"), _field(call, "input")
+        )
+    response = _field(block, "toolResult")
+    if response is not None:
+        return tool_call_response_part(
+            _field(response, "toolUseId"), _field(response, "content")
+        )
+    # Google GenAI / ADK ``Part``: text, function_call or function_response
+    # live side by side as optional fields.
+    call = _field(block, "function_call")
+    if call is not None:
+        return tool_call_part(
+            _field(call, "id"), _field(call, "name"), _first_field(call, "args", "arguments")
+        )
+    response = _field(block, "function_response")
+    if response is not None:
+        return tool_call_response_part(_field(response, "id"), _field(response, "response"))
+    text = _first_field(block, "text", "content")
+    if isinstance(text, str):
+        # Gemini/ADK mark a thinking part with ``thought`` beside its text.
+        if _field(block, "thought") is True:
+            return reasoning_part(text)
+        return text_part(text)
+    return text_part(_text(block))
+
+
+def _parts_from(content: Any) -> List[dict]:
+    if content is None:
+        return []
+    if isinstance(content, str):
+        part = text_part(content)
+        return [part] if part else []
+    if isinstance(content, (list, tuple)):
+        parts = [_part_from(block) for block in content]
+        return [p for p in parts if p]
+    part = _part_from(content)
+    return [part] if part else []
+
+
+_LANGCHAIN_TYPES = {"human", "ai", "system", "tool", "function", "chat"}
+
+
+def _langchain_type(obj: Any) -> Optional[str]:
+    """``BaseMessage.type`` -- LangChain's messages have no ``role`` attribute."""
+    kind = getattr(obj, "type", None)
+    if isinstance(kind, str) and kind in _LANGCHAIN_TYPES and hasattr(obj, "content"):
+        return kind
+    return None
+
+
+def _is_message(obj: Any) -> bool:
+    if isinstance(obj, dict):
+        return "role" in obj
+    if isinstance(obj, (str, bytes, list, tuple)) or obj is None:
+        return False
+    return getattr(obj, "role", None) is not None or _langchain_type(obj) is not None
+
+
+def _message_from(obj: Any, default_role: str) -> Optional[dict]:
+    role = _role(_field(obj, "role") or _langchain_type(obj), default_role)
+    content = _first_field(obj, "content", "parts", "contents", "text")
+    # ChatAgent/OpenAI and LangChain tool messages put the association on the
+    # message itself, not inside a content block. Preserve empty results too.
+    call_id = _field(obj, "tool_call_id")
+    if role == "tool" and call_id is not None:
+        return message(role, [tool_call_response_part(call_id, content)])
+    parts = _parts_from(content)
+    # LangChain tool calls carry name/args directly; OpenAI Chat and MLflow
+    # ChatAgent put name/arguments under function, keeping id on the outer call.
+    tool_calls = _field(obj, "tool_calls")
+    if isinstance(tool_calls, (list, tuple)):
+        # An Anthropic-backed AIMessage reports each call *twice*: once as a
+        # ``tool_use`` content block and again in ``tool_calls``. Skip a call
+        # whose id (or, unidentified, whose whole part) is already recorded.
+        seen = {p.get("id") for p in parts if p.get("type") == "tool_call"}
+        for call in tool_calls:
+            function = _field(call, "function")
+            payload = function if function is not None else call
+            part = tool_call_part(
+                _first_field(call, "id", "call_id"),
+                _field(payload, "name"),
+                _first_field(payload, "args", "arguments", "input"),
+            )
+            call_id = part.get("id")
+            if call_id is not None and call_id in seen:
+                continue
+            if call_id is None and part in parts:
+                continue
+            seen.add(call_id)
+            parts.append(part)
+    return message(role, parts)
+
+
+def _item_to_message(item: Any, default_role: str) -> Optional[dict]:
+    """A list item that is either a whole message or a bare block."""
+    if _is_message(item):
+        return _message_from(item, default_role)
+    part = _part_from(item)
+    if not part:
+        return None
+    role = {"tool_call": "assistant", "tool_call_response": "tool"}.get(
+        part["type"], default_role
+    )
+    return message(role, [part])
+
+
+def _messages(obj: Any, default_role: str) -> List[dict]:
+    if isinstance(obj, str):
+        return [message(default_role, [text_part(obj)])]
+    if isinstance(obj, (list, tuple)):
+        if any(_is_message(item) for item in obj):
+            # A history, possibly interleaved with bare tool items (OpenAI
+            # Responses ``function_call`` / ``function_call_output``).
+            return [_item_to_message(item, default_role) for item in obj]
+        # A list of content blocks (or strings) forming one message.
+        return [message(default_role, _parts_from(obj))]
+    if _is_message(obj):
+        return [_message_from(obj, default_role)]
+    return [message(default_role, [text_part(_text(obj))])]
+
+
+def coalesce_turns(messages: List[dict]) -> List[dict]:
+    """Merge consecutive same-role messages into one message per turn.
+
+    A provider reports one model turn as several blocks or streamed items -- a
+    thinking block, then text, then a tool call -- while the conventions model
+    that turn as a *single* message holding several parts. Without this, a
+    consumer counting assistant messages sees three turns where there was one.
+
+    Only plain ``{"role", "parts"}`` messages merge: one that already carries a
+    field of its own (``name``) marks a boundary the framework was explicit
+    about, so it is left standing. Roles never merge
+    across, so a real history (``assistant`` -> ``tool`` -> ``assistant``)
+    keeps its turns.
+    """
+    merged: List[dict] = []
+    for msg in messages:
+        previous = merged[-1] if merged else None
+        if (
+            previous is not None
+            and previous["role"] == msg["role"]
+            and set(previous) == {"role", "parts"}
+            and set(msg) == {"role", "parts"}
+        ):
+            previous["parts"] = previous["parts"] + msg["parts"]
+        else:
+            merged.append(dict(msg))
+    return merged
+
+
+def cap_messages(messages: List[dict]) -> List[dict]:
+    """Keep only the most recent ``OTELZERO_CONTENT_MAX_MESSAGES`` messages."""
+    limit = max_messages()
+    if limit and len(messages) > limit:
+        return messages[-limit:]
+    return messages
+
+
+def messages_from(obj: Any, default_role: str = "user") -> Optional[List[dict]]:
+    """Fold a framework prompt or response into semconv messages.
+
+    Accepts a bare string, a list of content blocks, a single message, or a
+    list of messages (dicts with ``role``/``content``, LangChain
+    ``BaseMessage`` objects, Anthropic/OpenAI/Bedrock/Gemini shapes, ...).
+    ``default_role`` labels content that carries no role of its own -- ``user``
+    for prompts, ``assistant`` for responses. ``None`` when not opted in or
+    when nothing recognisable was found.
+
+    A response (``default_role="assistant"``) additionally has its consecutive
+    same-role messages folded into one message per turn, see
+    :func:`coalesce_turns`. A prompt is left alone: two ``user`` messages in a
+    row there are two real turns of a history, not one turn's blocks.
+    """
+    if not enabled() or obj is None:
+        return None
+    try:
+        messages = [m for m in _messages(obj, default_role) if m]
+        if default_role == "assistant":
+            messages = coalesce_turns(messages)
+    except Exception:
+        return None
+    return cap_messages(messages) or None
+
+
+# --- Agent SDK prompts -------------------------------------------------------
+#
+# The Claude and Cortex agent SDKs take a prompt in two forms: a string, or an
+# *async iterable* of message dicts (their streaming input mode) that the SDK
+# reads itself. The helpers below record either without getting in the way.
+
+
+def _unwrap_envelope(item: Any) -> Any:
+    """The message inside an SDK wire envelope, ``{"type": "user", "message": {...}}``.
+
+    A streamed prompt's items come in the shape the SDK writes to its CLI --
+    the same envelope a string prompt is wrapped in -- and only the ``message``
+    inside is what the model sees. A typed item carrying no message (a control
+    request, say) is not a prompt at all and yields ``None``; anything else
+    passes through untouched.
+    """
+    if isinstance(item, dict) and "role" not in item:
+        inner = item.get("message")
+        if isinstance(inner, dict):
+            return inner
+        if "type" in item:
+            return None
+    return item
+
+
+def prompt_messages(prompt: Any) -> Optional[List[dict]]:
+    """A materialised agent SDK prompt (a string or message list) as input messages.
+
+    An async iterable is deliberately left unread: consuming it here would
+    swallow the very messages the SDK is about to send. Recording nothing beats
+    breaking the run -- :class:`PromptTee` is how a streamed prompt is captured.
+    """
+    if isinstance(prompt, str):
+        return messages_from(prompt)
+    if isinstance(prompt, (list, tuple)):
+        items = [_unwrap_envelope(item) for item in prompt]
+        return messages_from([item for item in items if item is not None])
+    return None
+
+
+class PromptTee:
+    """Observe a streamed prompt on its way to an SDK, without consuming it.
+
+    The SDK iterates the tee in place of the caller's async iterable; the tee
+    yields every item through untouched and keeps a shaped copy of each, so
+    :meth:`result` holds the input messages once the run is over.
+
+    Three things keep this safe to put in the SDK's path:
+
+    * items are shaped as they pass, never kept by reference -- the SDK mutates
+      the dicts it is handed (it stamps a ``session_id`` on each);
+    * the record is capped while it grows (``OTELZERO_CONTENT_MAX_MESSAGES``),
+      so a long stream never accumulates unbounded;
+    * recording never raises, and closing the tee closes the source, so an SDK
+      that stops reading early leaves nothing suspended.
+
+    :meth:`wrap` returns ``None`` -- leave the prompt alone -- unless content
+    capture is opted in and the prompt is an async iterable.
+    """
+
+    def __init__(self, source: Any):
+        self._source = source
+        self._messages: List[dict] = []
+
+    @classmethod
+    def wrap(cls, prompt: Any) -> Optional["PromptTee"]:
+        if not enabled() or not hasattr(prompt, "__aiter__"):
+            return None
+        return cls(prompt)
+
+    def __aiter__(self):
+        return self._relay()
+
+    async def _relay(self):
+        iterator = self._source.__aiter__()
+        try:
+            async for item in iterator:
+                self._record(item)
+                yield item
+        finally:
+            # ``async for`` does not close the iterator it leaves early; when
+            # the SDK drops the tee, the caller's generator must not outlive it.
+            aclose = getattr(iterator, "aclose", None)
+            if aclose is not None:
+                try:
+                    await aclose()
+                except Exception:
+                    pass
+
+    def _record(self, item: Any) -> None:
+        try:
+            item = _unwrap_envelope(item)
+            shaped = [m for m in _messages(item, "user") if m] if item is not None else []
+        except Exception:
+            return
+        self._messages.extend(shaped)
+        limit = max_messages()
+        if limit and len(self._messages) > limit:
+            del self._messages[:-limit]
+
+    def result(self) -> Optional[List[dict]]:
+        if not enabled():
+            return None
+        return cap_messages(list(self._messages)) or None
+
+
+def replace_prompt(args: tuple, kwargs: dict, prompt: Any) -> Tuple[tuple, dict]:
+    """The ``args``/``kwargs`` of a ``query(prompt, ...)`` call with ``prompt`` swapped in."""
+    if "prompt" in kwargs:
+        return args, {**kwargs, "prompt": prompt}
+    if args:
+        return (prompt, *args[1:]), kwargs
+    return args, kwargs
+
+
+_PENDING_PROMPTS = "_otelzero_pending_prompts"
+
+
+def queue_prompt(client: Any, messages: Optional[List[dict]]) -> None:
+    """Remember what an SDK client's ``query()`` sent, for the responses that follow.
+
+    An interactive client takes prompts and responses through two different
+    calls, so a prompt has to be carried from one to the other. Prompts queue
+    up in the order they were sent and :func:`take_prompt` hands them out one
+    response at a time. Past ``OTELZERO_CONTENT_MAX_MESSAGES`` unanswered
+    prompts the newest are dropped, not the oldest: the queue's order is what
+    pairs a prompt with its response, and a hole at the end costs only the
+    last few pairings.
+    """
+    if not messages:
+        return
+    try:
+        pending = getattr(client, _PENDING_PROMPTS, None)
+        if pending is None:
+            pending = []
+            setattr(client, _PENDING_PROMPTS, pending)
+        pending.extend(messages)
+        limit = max_messages()
+        if limit and len(pending) > limit:
+            del pending[limit:]
+    except Exception:
+        pass
+
+
+def take_prompt(client: Any) -> Optional[List[dict]]:
+    """The oldest prompt :func:`queue_prompt` stored: the response being read's input.
+
+    One prompt per response, oldest first. The SDK's CLI runs one turn per
+    user message it is sent, however many were sent before a reply was read,
+    and ``receive_response()`` yields one turn -- so the reply being read now
+    answers the oldest message still unanswered. (Seen live with the Claude
+    Agent SDK: two ``query()`` calls before one ``receive_response()`` gave
+    two results, one per prompt, the second turn carrying the first's history.)
+    """
+    try:
+        pending = getattr(client, _PENDING_PROMPTS, None)
+        if not pending:
+            return None
+        return [pending.pop(0)]
+    except Exception:
+        return None
+
+
+def as_messages(value: Any, role: str) -> Optional[List[dict]]:
+    """What ``RunContext.set_input`` / ``set_output`` accept: a shaped list or text."""
+    if not enabled() or not value:
+        return None
+    if isinstance(value, str):
+        return messages_from(value, role)
+    return list(value)
+
+
+def as_parts(value: Any) -> Optional[List[dict]]:
+    """What ``RunContext.set_system`` accepts: a shaped part list or text."""
+    if not enabled() or not value:
+        return None
+    if isinstance(value, str):
+        part = text_part(value)
+        return [part] if part else None
+    return list(value)
+
+
+# --- Finish reasons ----------------------------------------------------------
+
+_FINISH_REASONS = {
+    "end_turn": "stop",
+    "stop_sequence": "stop",
+    "stop": "stop",
+    "completed": "stop",
+    "complete": "stop",
+    "end": "stop",
+    "max_tokens": "length",
+    "max_output_tokens": "length",
+    "length": "length",
+    "tool_use": "tool_call",
+    "tool_calls": "tool_call",
+    "tool_call": "tool_call",
+    "function_call": "tool_call",
+    "content_filter": "content_filter",
+    "guardrail_intervened": "content_filter",
+    "safety": "content_filter",
+    "recitation": "content_filter",
+}
+
+
+def finish_reason(raw: Any) -> Optional[str]:
+    """Normalise a provider's stop reason to the conventions' spelling."""
+    raw = _plain(raw)
+    if raw is None:
+        return None
+    if not isinstance(raw, str):
+        raw = getattr(raw, "name", None) or str(raw)
+    key = raw.strip().lower()
+    return _FINISH_REASONS.get(key, key) or None
+
+
+# --- Streams -----------------------------------------------------------------
+
+
+class OutputAccumulator:
+    """Collect a streamed run's response into output messages, one per turn.
+
+    Mirrors :class:`otelzero.hooks._usage.UsageAccumulator`: a hook feeds it each
+    streamed item and reads :meth:`result` once. Three kinds of item are
+    understood, covering the SDKs this repo instruments:
+
+    * a message with list content (Claude SDK ``AssistantMessage`` /
+      ``UserMessage``, an ADK event's ``Content``) -- its blocks join the
+      message being built, or start the next one;
+    * a result carrying the final text (Claude SDK ``ResultMessage.result``)
+      -- ends the turn; its text stands in only when no messages were seen;
+    * a text chunk (:meth:`add_text`, Agent Framework stream updates) --
+      concatenated into one assistant message.
+
+    Messages are folded as they arrive, so the record never holds more than one
+    message per turn, nor more than ``OTELZERO_CONTENT_MAX_MESSAGES`` of them.
+    Blocks join the open message while the role holds and the generation is the
+    same: an SDK that stamps a ``message_id`` on each block (the Claude SDK) is
+    followed by it, and elsewhere a block carrying a stop reason, or a result
+    item, closes the message. Two turns that touch in the stream -- a streamed
+    prompt's second message answered right after the first -- therefore stay
+    two messages.
+
+    Every stop reason the stream reports goes into :attr:`finish_reasons` in
+    order, once per generation, as ``gen_ai.response.finish_reasons`` wants one
+    reason per generation received. What a framework reports is what is
+    recorded: the Claude SDK's CLI names one per turn, on its result item; ADK
+    names one per model response; a chunked stream names one on the last chunk
+    of each generation (Agent Framework: ``tool_calls``, then ``stop``). The
+    reasons are not content, so they are collected whether or not content
+    capture is opted in; the messages only when it is.
+    """
+
+    def __init__(self):
+        self._messages: List[dict] = []
+        self._open = False  # the last message still takes blocks
+        self._generation: Optional[str] = None  # its message_id, when stamped
+        self._reported: set = set()  # generations whose reason is recorded
+        self.finish_reasons: List[str] = []
+        self._chunks: List[str] = []
+        self._final: Optional[str] = None
+
+    def add(self, item: Any) -> None:
+        if item is None:
+            return
+        try:
+            self._add(item)
+        except Exception:  # pragma: no cover - defensive
+            pass
+
+    def _add(self, item: Any) -> None:
+        name = type(item).__name__.lower()
+        if name.startswith("system"):
+            return  # SDK init/session info, not model output
+        generation = _field(item, "message_id")
+        generation = str(generation) if generation else None
+        msg = self._message_of(item, name) if enabled() else None
+        if msg:
+            self._append(msg, generation)
+        reason = self._note_reason(item, generation)
+        if msg is None or (reason and generation is None):
+            # A result item ends the turn; a stop reason on a block no
+            # generation id places ends the generation. A generation the SDK
+            # does identify is ended by the next id instead, so a reason
+            # repeated on each of its blocks cannot split it.
+            self._open = False
+
+    def _message_of(self, item: Any, name: str) -> Optional[dict]:
+        if _is_message(item):
+            return _message_from(item, "assistant")
+        content = _first_field(item, "content", "parts")
+        if isinstance(content, (list, tuple)):
+            role = "user" if name.startswith("user") else "assistant"
+            return message(role, _parts_from(content))
+        if _is_message(content):
+            return _message_from(content, "assistant")
+        final = _field(item, "result")
+        if isinstance(final, str) and final:
+            self._final = final
+        return None
+
+    def _append(self, msg: dict, generation: Optional[str]) -> None:
+        last = self._messages[-1] if self._messages else None
+        joins = (
+            last is not None
+            and last["role"] == msg["role"]
+            and set(last) == {"role", "parts"} == set(msg)
+            and (
+                generation == self._generation
+                if generation is not None
+                else self._open and self._generation is None
+            )
+        )
+        if joins:
+            last["parts"] = last["parts"] + msg["parts"]
+        else:
+            self._messages.append(dict(msg))
+            self._generation = generation
+            limit = max_messages()
+            if limit and len(self._messages) > limit:
+                del self._messages[:-limit]
+        self._open = True
+
+    @staticmethod
+    def _reason_of(item: Any) -> Optional[str]:
+        raw = _first_field(item, "stop_reason", "finish_reason")
+        if raw is None or isinstance(raw, (list, tuple, dict)):
+            return None
+        return finish_reason(raw)
+
+    def _note_reason(self, item: Any, generation: Optional[str]) -> Optional[str]:
+        reason = self._reason_of(item)
+        if not reason:
+            return None
+        if generation is not None:
+            if generation in self._reported:
+                return None
+            self._reported.add(generation)
+        self.finish_reasons.append(reason)
+        return reason
+
+    def add_text(self, chunk: Any) -> None:
+        if chunk is None:
+            return
+        text = chunk if isinstance(chunk, str) else _first_field(chunk, "text", "content")
+        reason = None
+        if type(chunk) is not str:  # an update object, or a str subclass with fields
+            try:
+                reason = self._reason_of(chunk)
+            except Exception:  # pragma: no cover - defensive
+                pass
+        if enabled() and isinstance(text, str) and text:
+            self._chunks.append(text)
+        if reason:
+            # The chunk that names a reason is a generation's last: the text
+            # so far is that generation's message, and what follows is the
+            # next generation's.
+            self._flush_chunks()
+            self.finish_reasons.append(reason)
+
+    def _flush_chunks(self) -> None:
+        text = "".join(self._chunks)
+        self._chunks = []
+        msg = assistant_text(text) if text else None
+        if msg:
+            self._append(msg, None)
+        self._open = False
+
+    def result(self) -> Optional[List[dict]]:
+        if not enabled():
+            return None
+        messages = list(self._messages)
+        remaining = assistant_text("".join(self._chunks)) if self._chunks else None
+        if remaining:
+            messages.append(remaining)
+        if messages:
+            return messages
+        final = assistant_text(self._final) if self._final else None
+        return [final] if final else None