Skip to content
Python
43.7 KB
Raw Blame
"""Recorded turns as OpenTelemetry spans, with the content rules (OB-6, phase-2 design §10.4).

Pure functions, no network: the exporter (`export.py`) reads the store, calls
`build_turn_spans` for a turn's unsent steps and encodes the result with `encode_otlp`.

The mapping is the frozen 1.x one (tracing-spec §9 and §10, attributes.yaml part 2): one trace
per turn, the turn as the root span, each step a span below it, notices as events on the turn.
The Phase 1 lab exporter (`phase-1/lab/export_otel.py`) was the starting point; it was checked
against a local Langfuse. This module writes OTLP/HTTP JSON itself, so the app needs no
OpenTelemetry SDK.

Content (tracing-spec §11). Metadata is always sent. Each content attribute has its switch,
and five rules apply on top:
- R1. Tool parts inside exported messages follow the tool switches, wherever they appear.
- R2. OpenWorker's per-turn `<system-context>` block is cut out of user text unless
  `capture.context` is on.
- R3. The auto-approver's and the summary's calls need the tool switches as well.
- R4. Secrets are masked, then each text part is cut at 8 KB (`Masker`).
- R5. Never exported: reasoning text, provider-reported cost, `error.text`, `questions`,
  `decision_details`, `agents_md`, `blocked`. None of them has a name here.
"""

from __future__ import annotations

import datetime as _dt
import hashlib
import json
import os
import re
from typing import Any, Callable, Iterable, Optional

from . import calculator
from .capture import is_auxiliary, parse_events, rebuild_request, wire_of_url

ATTRIBUTES_VERSION = "1.3"
SCHEMA = f"openworker/{ATTRIBUTES_VERSION}"
SERVICE_NAME = "openworker-desktop"
SCOPE_NAME = "openworker.observability"

# Markers (tracing-spec §11).
REASONING = "[reasoning text not exported]"
TOOL_ARGS_OUT = "[tool arguments not exported]"
TOOL_RESULT_OUT = "[tool result not exported]"
CONTEXT_OUT = "[OpenWorker context not exported]"
SECRET = "[secret masked]"
CUT_BYTES = 8192
CUT_MARKER = "[cut: {n} more bytes]"

SWITCHES = ("prompts", "responses", "tool_args", "tool_results", "system_instructions",
            "context", "names")

# attributes.yaml export.value_maps.gen_ai_provider_name
PROVIDER_NAME = {"anthropic": "anthropic", "openai": "openai", "gemini": "gcp.gemini",
                 "bedrock": "aws.bedrock", "openrouter": "openrouter", "ollama": "ollama",
                 "together": "together", "openai_decisions": "openai", "typesafe_jev": "typesafe"}

SPAN_INTERNAL, SPAN_CLIENT = 1, 3  # OTLP SpanKind
STATUS_ERROR = 2


# -- R4: mask, then cut -----------------------------------------------------------------------
# attributes.yaml export.content_switches.masking
MASK_PATTERNS = [
    r"sk-[A-Za-z0-9_-]{16,}",
    r"\b(AKIA|ASIA)[A-Z0-9]{16}\b",
    r"\bgh[pousr]_[A-Za-z0-9]{30,}\b",
    r"\bgithub_pat_[A-Za-z0-9_]{30,}\b",
    r"\bxox[abp]-[A-Za-z0-9-]{10,}",
    r"\bAIza[0-9A-Za-z_-]{35}\b",
    r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----",
]
_PATTERNS = [re.compile(p) for p in MASK_PATTERNS]
MIN_SECRET_LEN = 8
_ENV_SECRET_PARTS = ("_API_KEY", "_TOKEN", "_SECRET", "PASSWORD")


def env_secret_values(environ: Optional[dict[str, str]] = None) -> list[str]:
    """Credential-looking environment variables (masking.values)."""
    env = os.environ if environ is None else environ
    return [v for k, v in env.items()
            if any(p in k.upper() for p in _ENV_SECRET_PARTS) and len(v or "") >= MIN_SECRET_LEN]


def store_secret_values(data: Any) -> list[str]:
    """Every string value in the secret store's profiles."""
    out: list[str] = []

    def walk(v: Any) -> None:
        if isinstance(v, str):
            out.append(v)
        elif isinstance(v, dict):
            for x in v.values():
                walk(x)
        elif isinstance(v, list):
            for x in v:
                walk(x)

    walk(data)
    return out


def cut(text: str, limit: int = CUT_BYTES) -> str:
    """Cut at `limit` bytes of UTF-8, on a character boundary, and say how much was left out."""
    data = text.encode("utf-8")
    if len(data) <= limit:
        return text
    n = limit
    while n > 0 and (data[n] & 0xC0) == 0x80:  # never split a character
        n -= 1
    return data[:n].decode("utf-8") + CUT_MARKER.format(n=len(data) - n)


class Masker:
    """R4: stored secret values (longest first), then the key patterns; then the cut."""

    def __init__(self, secrets: Iterable[str] = ()) -> None:
        values = {s for s in secrets if isinstance(s, str) and len(s) >= MIN_SECRET_LEN}
        self.values = sorted(values, key=len, reverse=True)

    def mask(self, text: str) -> str:
        for v in self.values:
            if v in text:
                text = text.replace(v, SECRET)
        for p in _PATTERNS:
            text = p.sub(SECRET, text)
        return text

    def clean(self, value: Any) -> str:
        """One exported text part: as text (JSON for anything else), masked, then cut."""
        text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, default=str)
        return cut(self.mask(text))


# -- content: the exact request and reply, in the GenAI message shape -------------------------
def _text_parts(content: Any) -> list[dict[str, Any]]:
    if content is None:
        return []
    if isinstance(content, str):
        return [{"type": "text", "content": content}] if content else []
    parts: list[dict[str, Any]] = []
    for b in content if isinstance(content, list) else [content]:
        if not isinstance(b, dict):
            parts.append({"type": "text", "content": str(b)})
            continue
        t = b.get("type")
        if t in ("text", "input_text", "output_text"):
            parts.append({"type": "text", "content": b.get("text", "")})
        elif t == "tool_use":
            parts.append({"type": "tool_call", "id": b.get("id"), "name": b.get("name"), "arguments": b.get("input")})
        elif t == "tool_result":
            parts.append({"type": "tool_call_response", "id": b.get("tool_use_id"), "response": b.get("content")})
        elif t in ("thinking", "redacted_thinking", "reasoning"):
            parts.append({"type": "reasoning", "content": REASONING})
        else:
            parts.append({"type": t or "unknown"})  # images and the like: the kind only
    return parts


def _gemini_parts(parts: Any) -> list[dict[str, Any]]:
    out: list[dict[str, Any]] = []
    for p in parts or []:
        if not isinstance(p, dict):
            continue
        if p.get("thought"):
            out.append({"type": "reasoning", "content": REASONING})
        elif "text" in p:
            out.append({"type": "text", "content": p.get("text") or ""})
        elif "functionCall" in p:
            fc = p["functionCall"] or {}
            out.append({"type": "tool_call", "id": fc.get("id"), "name": fc.get("name"), "arguments": fc.get("args")})
        elif "functionResponse" in p:
            fr = p["functionResponse"] or {}
            out.append({"type": "tool_call_response", "id": fr.get("id") or fr.get("name"), "response": fr.get("response")})
        else:
            out.append({"type": next(iter(p), "unknown")})
    return out


def request_messages(wire: str, req: dict[str, Any]) -> tuple[list, list, list]:
    """(system instructions, input messages, tool definitions) from a rebuilt request."""
    system: list[dict[str, Any]] = []
    msgs: list[dict[str, Any]] = []
    tools = req.get("tools") or []
    if wire == "anthropic":
        system = _text_parts(req.get("system"))
        for m in req.get("messages") or []:
            msgs.append({"role": m.get("role"), "parts": _text_parts(m.get("content"))})
    elif wire == "openai_responses":
        if req.get("instructions"):
            system = [{"type": "text", "content": req["instructions"]}]
        items = req.get("input") or []
        for it in [{"role": "user", "content": items}] if isinstance(items, str) else items:
            t = it.get("type")
            if t == "function_call":
                msgs.append({"role": "assistant", "parts": [{"type": "tool_call", "id": it.get("call_id"),
                                                              "name": it.get("name"), "arguments": it.get("arguments")}]})
            elif t == "function_call_output":
                msgs.append({"role": "tool", "parts": [{"type": "tool_call_response", "id": it.get("call_id"),
                                                         "response": it.get("output")}]})
            elif t == "reasoning":
                msgs.append({"role": "assistant", "parts": [{"type": "reasoning", "content": REASONING}]})
            elif it.get("role") in ("system", "developer"):
                system += _text_parts(it.get("content"))
            else:
                msgs.append({"role": it.get("role", "user"), "parts": _text_parts(it.get("content"))})
    elif wire == "gemini":
        system = _gemini_parts((req.get("systemInstruction") or {}).get("parts"))
        for c in req.get("contents") or []:
            msgs.append({"role": c.get("role", "user"), "parts": _gemini_parts(c.get("parts"))})
    else:  # openai_chat and ollama: a messages list, system first
        for m in req.get("messages") or []:
            if m.get("role") in ("system", "developer"):
                system += _text_parts(m.get("content"))
                continue
            parts = _text_parts(m.get("content"))
            if m.get("reasoning_content") or m.get("reasoning") or m.get("thinking"):
                parts.insert(0, {"type": "reasoning", "content": REASONING})
            for tc in m.get("tool_calls") or []:
                fn = tc.get("function") or {}
                parts.append({"type": "tool_call", "id": tc.get("id"), "name": fn.get("name"),
                              "arguments": fn.get("arguments")})
            if m.get("role") == "tool":
                parts = [{"type": "tool_call_response", "id": m.get("tool_call_id") or m.get("tool_name"),
                          "response": m.get("content")}]
            msgs.append({"role": m.get("role"), "parts": parts})
    return system, msgs, tools


def response_message(wire: str, body: str) -> dict[str, Any]:
    """The assistant's reply, put together from the body exactly as received."""
    evs = [e for e in parse_events(body) if isinstance(e, dict)]
    parts: list[dict[str, Any]] = []
    finish = None
    if wire == "anthropic":
        blocks: dict[int, dict[str, Any]] = {}
        for e in evs:
            t = e.get("type")
            if t == "message" and isinstance(e.get("content"), list):  # not streamed
                for i, b in enumerate(e["content"]):
                    blocks[i] = dict(b, _json="")
                finish = e.get("stop_reason")
            elif t == "content_block_start":
                blocks[e.get("index", 0)] = dict(e.get("content_block") or {}, _json="")
            elif t == "content_block_delta":
                b = blocks.setdefault(e.get("index", 0), {"type": "text", "text": "", "_json": ""})
                d = e.get("delta") or {}
                if d.get("type") == "text_delta":
                    b["text"] = b.get("text", "") + d.get("text", "")
                elif d.get("type") == "input_json_delta":
                    b["_json"] += d.get("partial_json", "")
            elif t == "message_delta":
                finish = (e.get("delta") or {}).get("stop_reason")
        for i in sorted(blocks):
            b = blocks[i]
            if b.get("type") == "tool_use":
                try:
                    args = json.loads(b["_json"]) if b["_json"] else b.get("input")
                except ValueError:
                    args = b["_json"]
                parts.append({"type": "tool_call", "id": b.get("id"), "name": b.get("name"), "arguments": args})
            elif b.get("type") == "text":
                parts.append({"type": "text", "content": b.get("text", "")})
            else:
                parts.append({"type": "reasoning", "content": REASONING})
    elif wire == "openai_responses":
        done = [e for e in evs if e.get("type") == "response.completed"]
        resp = done[-1].get("response") if done else (evs[-1] if evs and "output" in evs[-1] else {})
        finish = (resp or {}).get("status")
        for it in (resp or {}).get("output") or []:
            if it.get("type") == "function_call":
                parts.append({"type": "tool_call", "id": it.get("call_id"), "name": it.get("name"),
                              "arguments": it.get("arguments")})
            elif it.get("type") == "message":
                parts += _text_parts(it.get("content"))
            elif it.get("type") == "reasoning":
                parts.append({"type": "reasoning", "content": REASONING})
    elif wire == "gemini":
        for e in evs:
            for c in e.get("candidates") or []:
                parts += _gemini_parts((c.get("content") or {}).get("parts"))
                finish = c.get("finishReason") or finish
    elif wire == "ollama":
        text, reasoning = "", False
        for e in evs:
            m = e.get("message") or {}
            text += m.get("content") or ""
            reasoning = reasoning or bool(m.get("thinking"))
            for tc in m.get("tool_calls") or []:
                fn = tc.get("function") or {}
                parts.append({"type": "tool_call", "id": tc.get("id"), "name": fn.get("name"),
                              "arguments": fn.get("arguments")})
            if e.get("done"):
                finish = e.get("done_reason")
        if text:
            parts.insert(0, {"type": "text", "content": text})
        if reasoning:
            parts.insert(0, {"type": "reasoning", "content": REASONING})
    else:  # openai_chat, streamed or not
        text, calls, reasoning = "", {}, False
        for e in evs:
            for ch in e.get("choices") or []:
                d = ch.get("delta") or ch.get("message") or {}
                text += d.get("content") or ""
                reasoning = reasoning or bool(d.get("reasoning") or d.get("reasoning_content"))
                for n, tc in enumerate(d.get("tool_calls") or []):
                    c = calls.setdefault(tc.get("index", n), {"id": None, "name": None, "arguments": ""})
                    c["id"] = tc.get("id") or c["id"]
                    fn = tc.get("function") or {}
                    c["name"] = fn.get("name") or c["name"]
                    c["arguments"] += fn.get("arguments") or ""
                finish = ch.get("finish_reason") or finish
        if reasoning:
            parts.append({"type": "reasoning", "content": REASONING})
        if text:
            parts.append({"type": "text", "content": text})
        parts += [dict(type="tool_call", **calls[i]) for i in sorted(calls)]
    return {"role": "assistant", "parts": parts, "finish_reason": finish}


def step_exchange(step: dict[str, Any], get_piece: Callable[[str], Optional[bytes]]) -> Optional[tuple[str, dict, str]]:
    """(wire, rebuilt request, response body) of a model step's last real request."""
    for ex in reversed((step.get("content") or {}).get("exchange") or []):
        url = (ex.get("request") or {}).get("url") or ""
        if ex.get("auxiliary") or is_auxiliary(url):
            continue  # a helper lookup (Ollama's /api/show), not the call
        try:
            req = rebuild_request(ex, get_piece)
            if isinstance(req, (bytes, bytearray)):
                req = json.loads(req)
        except Exception:  # noqa: BLE001 - a piece already swept: nothing to rebuild
            return None
        if not isinstance(req, dict):
            return None
        body = get_piece((ex.get("response") or {}).get("body_blob") or "") or b""
        return wire_of_url(url), req, body.decode("utf-8", "replace")
    return None


# -- the content rules -------------------------------------------------------------------------
_CONTEXT_BLOCK = re.compile(r"<system-context>.*?(</system-context>|\Z)", re.S)


def cut_context(text: str) -> str:
    """R2: OpenWorker's per-turn block, replaced by its marker."""
    return _CONTEXT_BLOCK.sub(CONTEXT_OUT, text)


def apply_rules(messages: list[dict[str, Any]], sw: dict[str, bool], masker: Masker) -> list[dict[str, Any]]:
    """R1, R2 and R4 over a list of exported messages (a copy)."""
    out = []
    for m in messages:
        parts = []
        for p in m.get("parts") or []:
            p = dict(p)
            t = p.get("type")
            if t == "text":
                text = p.get("content") or ""
                if m.get("role") == "user" and not sw.get("context"):
                    text = cut_context(text)
                p["content"] = masker.clean(text)
            elif t == "tool_call":
                p["arguments"] = masker.clean(p.get("arguments")) if sw.get("tool_args") else TOOL_ARGS_OUT
            elif t == "tool_call_response":
                p["response"] = masker.clean(p.get("response")) if sw.get("tool_results") else TOOL_RESULT_OUT
            parts.append(p)
        out.append({k: v for k, v in m.items() if k != "parts"} | {"parts": parts})
    return out


def content_allowed(purpose: str, sw: dict[str, bool]) -> tuple[bool, bool]:
    """(input, output) of a model call may go out (R3)."""
    if purpose == "auto_approver":
        return sw["prompts"] and sw["tool_args"], sw["responses"] and sw["tool_args"]
    if purpose == "summary":
        tools = sw["tool_args"] and sw["tool_results"]
        return sw["prompts"] and tools, sw["responses"] and tools
    return sw["prompts"], sw["responses"]


# -- tokens -------------------------------------------------------------------------------------
def _usage(step: dict[str, Any]) -> Optional[dict[str, Any]]:
    u = (step.get("attrs") or {}).get("usage") or {}
    if not u.get("reported"):
        return None
    return {k: u.get(k) for k in ("input_fresh", "cache_read", "cache_write", "output", "reasoning")}


def _semconv_usage(u: dict[str, Any]) -> dict[str, int]:
    a = {"gen_ai.usage.input_tokens": calculator.input_total(u), "gen_ai.usage.output_tokens": u.get("output") or 0}
    for part, name in (("cache_read", "gen_ai.usage.cache_read.input_tokens"),
                       ("cache_write", "gen_ai.usage.cache_creation.input_tokens"),
                       ("reasoning", "gen_ai.usage.reasoning.output_tokens")):
        if u.get(part) is not None:  # a part not reported is left out, never 0
            a[name] = u[part]
    return a


def _langfuse_usage(u: dict[str, Any]) -> dict[str, int]:
    """Buckets that do not overlap: they add up to the call's total."""
    d = {"input": u.get("input_fresh") or 0}
    if u.get("cache_read") is not None:
        d["input_cache_read"] = u["cache_read"]
    if u.get("cache_write") is not None:
        d["input_cache_creation"] = u["cache_write"]
    out = u.get("output") or 0
    if u.get("reasoning") is not None:
        d["output"] = max(out - u["reasoning"], 0)
        d["output_reasoning"] = u["reasoning"]
    else:
        d["output"] = out
    return d


# -- ids -----------------------------------------------------------------------------------------
def _hex(text: str, n: int) -> str:
    h = hashlib.sha256(text.encode("utf-8")).hexdigest()[:n]
    return h if int(h, 16) else "1".rjust(n, "0")  # an all-zero id is invalid in OTLP


def trace_id(turn_id: str) -> str:
    return _hex(f"trace|{turn_id}", 32)


def root_span_id(turn_id: str) -> str:
    return _hex(f"turn|{turn_id}", 16)


def step_span_id(step_id: str) -> str:
    return _hex(f"step|{step_id}", 16)


def _iso(ms: int) -> str:
    return (_dt.datetime.fromtimestamp(ms / 1000, _dt.timezone.utc)
            .isoformat(timespec="milliseconds").replace("+00:00", "Z"))


def _js(v: Any) -> str:
    return json.dumps(v, ensure_ascii=False, default=str)


# -- one turn -> spans -----------------------------------------------------------------------------
def switches_from(include: dict[str, bool]) -> dict[str, bool]:
    """The page's switches to the shared `capture.*` ones (design §10.4)."""
    return {
        "prompts": bool(include.get("messages")), "responses": bool(include.get("messages")),
        "tool_args": bool(include.get("tool_io")), "tool_results": bool(include.get("tool_io")),
        "system_instructions": bool(include.get("context")), "context": bool(include.get("context")),
        "names": bool(include.get("names")),
    }


def turn_end_ms(turn: dict[str, Any], steps: list[dict[str, Any]]) -> int:
    if turn.get("duration_ms") is not None:
        return turn["started_at"] + turn["duration_ms"]
    ends = [s["started_at"] + (s.get("duration_ms") or 0) for s in steps if s.get("started_at") is not None]
    return max([turn.get("started_at") or 0] + ends)


def _is_gap(step: dict[str, Any]) -> bool:
    """A gap notice with a duration: its own span, not an event on the turn (1.2)."""
    from .gaps import GAP_NOTICES

    return step.get("kind") == "notice" and step.get("name") in GAP_NOTICES and bool(step.get("duration_ms"))


def build_turn_spans(
    turn: dict[str, Any],
    steps: list[dict[str, Any]],
    *,
    sw: dict[str, bool],
    dialect: str,
    get_piece: Callable[[str], Optional[bytes]],
    masker: Masker,
    include_root: bool = True,
    only: Optional[set[str]] = None,
    session_title: Optional[str] = None,
) -> list[dict[str, Any]]:
    """The spans of one turn, as plain dicts (`encode_otlp` turns them into OTLP JSON).

    `steps` is every step of the turn (parents and content are looked up among them);
    `only` limits the spans built to these step ids (a late `after_turn` step), and
    `include_root` says whether the turn's own span is built. Each span dict carries
    `_mark`: the id the exporter marks as sent (the step id, or the turn id for the root).
    """
    lf = dialect == "langfuse"
    tid = turn["turn_id"]
    by_id = {s["step_id"]: s for s in steps}
    end_ms = turn_end_ms(turn, steps)
    common = {"session.id": turn["session_id"], "gen_ai.conversation.id": turn["session_id"],
              "openworker.turn.id": tid}
    any_content = any(sw.get(k) for k in SWITCHES if k != "names")

    # Content for tool spans comes from the exchanges around them: the arguments from the
    # reply that asked for the call, the result from the next request that carried it back.
    exchanges: dict[str, tuple[str, dict, str]] = {}
    tool_args: dict[str, Any] = {}
    tool_results: dict[str, Any] = {}
    if any_content:
        for s in steps:
            if s.get("kind") != "model":
                continue
            x = step_exchange(s, get_piece)
            if x is None:
                continue
            exchanges[s["step_id"]] = x
            wire, req, body = x
            for m in request_messages(wire, req)[1]:
                for p in m["parts"]:
                    if p.get("type") == "tool_call_response" and p.get("id"):
                        tool_results[p["id"]] = p.get("response")
            for p in response_message(wire, body)["parts"]:
                if p.get("type") == "tool_call" and p.get("id"):
                    tool_args[p["id"]] = p.get("arguments")

    spans: list[dict[str, Any]] = []
    trace = trace_id(tid)
    root_id = root_span_id(tid)

    def depth(s: dict[str, Any]) -> int:
        d, p, seen = 0, s.get("parent_step_id"), set()
        while p and p in by_id and p not in seen:
            seen.add(p)
            d, p = d + 1, by_id[p].get("parent_step_id")
        return d

    first_user_text = last_reply_text = None
    for s in sorted(steps, key=lambda s: (depth(s), s.get("seq") or 0)):
        if (s.get("kind") == "notice" and not _is_gap(s)) or (only is not None and s["step_id"] not in only):
            continue
        a = s.get("attrs") or {}
        attrs: dict[str, Any] = dict(common, **{
            "openworker.step.id": s["step_id"], "openworker.step.kind": s["kind"],
            "openworker.step.status": s.get("status") or "unknown", "openworker.step.seq": s.get("seq") or 0})
        if s.get("after_turn"):
            attrs["openworker.after_turn"] = True
        if s.get("shadow"):
            attrs["openworker.shadow"] = True
        call_id = s.get("call_id") or (a.get("for_call_id") if s["kind"] == "wait" else None)
        if call_id:
            # Only a tool's own span carries gen_ai.tool.call.id: viewers type any span with it
            # as a tool (V-22). Waits, checks and the reviewer's model call use our own name.
            attrs["gen_ai.tool.call.id" if s["kind"] == "tool" else "openworker.tool.call_id"] = call_id
        kind = SPAN_INTERNAL
        events: list[dict[str, Any]] = []
        lf_type = "span"
        usage = None
        if s["kind"] == "model":
            model = a.get("model") or ""
            prov, _, short = model.partition(":")
            short = short or model
            prov = a.get("provider") or prov
            facts = a.get("provider_facts") or {}
            name = f"chat {short}"
            kind, lf_type = SPAN_CLIENT, "generation"
            attrs.update({"gen_ai.operation.name": "chat", "gen_ai.provider.name": PROVIDER_NAME.get(prov, prov),
                          "gen_ai.request.model": short, "openworker.model": model,
                          "openworker.llm.purpose": a.get("purpose") or "unattributed",
                          "openworker.stream": bool(a.get("stream"))})
            if facts.get("served_model"):
                attrs["gen_ai.response.model"] = facts["served_model"]
            if facts.get("provider_response_id"):
                attrs["gen_ai.response.id"] = facts["provider_response_id"]
            if facts.get("provider_request_id"):
                attrs["openworker.provider.request_id"] = facts["provider_request_id"]
            if facts.get("served_by") or a.get("served_by"):
                attrs["openworker.provider.served_by"] = facts.get("served_by") or a.get("served_by")
            if a.get("finish_reason"):
                attrs["gen_ai.response.finish_reasons"] = [a["finish_reason"]]
            if a.get("tools_offered") is not None:
                attrs["openworker.tools_offered"] = a["tools_offered"]
            usage = _usage(s)
            attrs["openworker.usage.reported"] = usage is not None
            if usage:
                attrs.update(_semconv_usage(usage))
                if lf:
                    attrs["langfuse.observation.usage_details"] = _js(_langfuse_usage(usage))
            if a.get("ttft_ms") is not None and s.get("started_at") is not None:
                first = s["started_at"] + a["ttft_ms"]
                attrs["gen_ai.client.operation.time_to_first_chunk"] = a["ttft_ms"] / 1000
                events.append({"name": "gen_ai.first_chunk", "at": first, "attrs": {}})
                if lf:
                    attrs["langfuse.observation.completion_start_time"] = _iso(first)
            err = a.get("error")
            if err:
                attrs["error.type"] = err.get("type") or "error"  # never error.text (R5)
            x = exchanges.get(s["step_id"])
            if x is not None:
                wire, req, body = x
                system, msgs, tools = request_messages(wire, req)
                out = response_message(wire, body)
                purpose = a.get("purpose") or ""
                in_ok, out_ok = content_allowed(purpose, sw)
                if sw.get("system_instructions"):
                    attrs["gen_ai.system_instructions"] = _js(apply_rules([{"role": "system", "parts": system}],
                                                                          {**sw, "context": True}, masker)[0]["parts"])
                    attrs["gen_ai.tool.definitions"] = masker.clean(tools)
                if in_ok:
                    attrs["gen_ai.input.messages"] = _js(apply_rules(msgs, sw, masker))
                if out_ok:
                    attrs["gen_ai.output.messages"] = _js(apply_rules([out], sw, masker))
                if purpose == "main":
                    users = [p["content"] for m in msgs if m.get("role") == "user"
                             for p in m["parts"] if p.get("type") == "text"]
                    first_user_text = first_user_text or (users[-1] if users else None)
                    texts = [p["content"] for p in out["parts"] if p.get("type") == "text"]
                    last_reply_text = texts[-1] if texts else last_reply_text
        elif s["kind"] == "tool":
            name = f"execute_tool {s.get('name')}"
            lf_type = "tool"
            attrs.update({"gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": s.get("name") or "",
                          "gen_ai.tool.type": "function"})
            dec = a.get("decision") or {}
            if dec.get("origin"):
                attrs["openworker.decision.origin"] = dec["origin"]
            if dec.get("path"):
                attrs["openworker.decision.path"] = [f"{p.get('stage')}:{p.get('outcome')}" for p in dec["path"]]
            if dec.get("helper"):
                attrs["openworker.decision.helper"] = True
            for k in ("risk_class", "exit_code", "result_bytes"):
                if a.get(k) is not None:
                    attrs[f"openworker.tool.{k}"] = a[k]
            cid = s.get("call_id")
            if sw.get("tool_args") and cid in tool_args:
                attrs["gen_ai.tool.call.arguments"] = masker.clean(tool_args[cid])
            if sw.get("tool_results") and cid in tool_results:
                attrs["gen_ai.tool.call.result"] = masker.clean(tool_results[cid])
        elif s["kind"] == "wait":
            wk = a.get("kind") or "approval"
            name = f"openworker.{wk}.wait"
            for k in ("kind", "where", "outcome", "attended"):
                if a.get(k) is not None:
                    attrs[f"openworker.wait.{k}"] = a[k]
            resolved = (s.get("content") or {}).get("resolved_by")
            if sw.get("names") and resolved:
                attrs["openworker.wait.resolved_by"] = masker.clean(resolved)
        elif s["kind"] == "auto_approver":
            name = f"openworker.policy.review {s.get('name')}"
            lf_type = "guardrail"
            rv = a.get("reviewer") or {}
            attrs.update({"openworker.reviewer.kind": rv.get("kind") or "",
                          "openworker.reviewer.external": bool(rv.get("external")),
                          "openworker.reviewer.mode": a.get("mode") or "",
                          "openworker.reviewer.result": a.get("result") or ""})
            if rv.get("model"):
                attrs["openworker.reviewer.model"] = rv["model"]
            for k in ("score", "cutoff"):
                if a.get(k) is not None:
                    attrs[f"openworker.reviewer.{k}"] = a[k]
            reason = (s.get("content") or {}).get("reason")
            if reason and sw.get("responses") and sw.get("tool_args"):  # R3: it quotes the action
                attrs["openworker.reviewer.reason"] = masker.clean(reason)
        elif s["kind"] == "summary":
            name = "openworker.compaction" if s.get("name") == "summary" else "openworker.compaction.trim"
            for k in ("reason", "tokens_before", "tokens_after"):
                if a.get(k) is not None:
                    attrs[f"openworker.compaction.{k}"] = a[k]
        elif s["kind"] == "context":
            name = "openworker.context.build"
            for k in ("size_chars", "session_prompt_hash", "block_hash"):
                if a.get(k) is not None:
                    attrs[f"openworker.context.{k}"] = a[k]
        elif s["kind"] == "notice":  # a gap with a duration (1.2, tracing-spec §9)
            name = f"openworker.gap.{s.get('name')}"
            for k in ("reason", "skipped_ms"):
                if a.get(k) is not None:
                    attrs[f"openworker.gap.{k}"] = a[k]
        elif s["kind"] == "sandbox":
            name = "openworker.sandbox.setup"
            for k in ("provider", "trigger", "failed_stage"):
                if a.get(k) is not None:
                    attrs[f"openworker.sandbox.{k}"] = a[k]
            # One event per stage (tracing-spec §9); the error's text stays on this machine.
            for st in a.get("stages") or []:
                ev_attrs = {"openworker.sandbox.stage.status": st.get("status") or "ok"}
                if st.get("duration_ms") is not None:
                    ev_attrs["openworker.sandbox.stage.duration_ms"] = st["duration_ms"]
                if st.get("uncertain"):
                    ev_attrs["openworker.sandbox.stage.uncertain"] = True
                events.append({"name": f"openworker.sandbox.stage.{st.get('name')}",
                               "at": st.get("started_at") or s.get("started_at") or turn["started_at"], "attrs": ev_attrs})
        else:
            name = f"openworker.{s['kind']}"

        status = s.get("status") or "unknown"
        has_end = s.get("duration_ms") is not None
        level = message = None
        if status == "error":
            level = "ERROR"
            message = (a.get("error") or {}).get("type") or "error"
            if s["kind"] == "model":
                message += "; usage unknown"
        elif status in ("denied", "interrupted", "unknown") or not has_end:
            level, message = "WARNING", status if has_end else "unknown"
        elif s["kind"] == "model" and usage is None:
            level, message = "WARNING", "usage not reported"
        if lf:
            attrs["langfuse.observation.type"] = lf_type
            if level:
                attrs["langfuse.observation.level"] = level
                attrs["langfuse.observation.status_message"] = message
        parent = s.get("parent_step_id")
        start = s.get("started_at") if s.get("started_at") is not None else turn["started_at"]
        spans.append({
            "_mark": s["step_id"], "trace_id": trace,
            "span_id": step_span_id(s["step_id"]),
            "parent_span_id": step_span_id(parent) if parent and parent in by_id else root_id,
            "name": name, "kind": kind, "start_ms": start,
            "end_ms": start + s["duration_ms"] if has_end else max(end_ms, start),
            "attrs": attrs, "events": events,
            "error": ((a.get("error") or {}).get("type") or "error") if status == "error" else None,
        })

    if include_root:
        usage = calculator.usage({"steps": steps}, turn_id=tid)
        root_attrs = dict(common, **{
            "gen_ai.operation.name": "invoke_agent", "gen_ai.agent.name": "coworker",
            "openworker.turn.seq": turn.get("seq") or 0, "openworker.turn.kind": turn.get("kind") or "",
            "openworker.turn.trigger": turn.get("trigger") or "", "openworker.turn.status": turn.get("status") or "",
            "openworker.approval_mode": turn.get("approval_mode") or "",
            "openworker.attended": bool(turn.get("attended")),
            # Never a gen_ai.usage.* name on a parent span: viewers would count it twice.
            "openworker.usage.total_tokens": usage["pill"],
            "openworker.usage.at_least": usage["at_least"],
            "openworker.usage.unreported_calls": usage["unreported_calls"],
            "openworker.usage.failed_calls": usage["failed_calls"],
            "openworker.usage.context_limit_calls": usage["overflow_calls"]})
        # 1.3 (E25b, TD3-25): the coworker and its version, why the turn started, and the
        # automation run. gen_ai.agent.name keeps its 1.0 value (FO-149).
        stamp = turn.get("stamp") or {}
        wake = turn.get("wake") or {}
        auto = turn.get("automation") or {}
        team = stamp.get("team") or {}
        for key, value in (("openworker.persona.id", stamp.get("persona_id")),
                           ("openworker.persona.fp", stamp.get("persona_fp")),
                           ("openworker.team.role", team.get("role")),
                           ("openworker.wake.reason", wake.get("reason")),
                           ("openworker.automation.task_id", auto.get("task_id")),
                           ("openworker.automation.run_id", auto.get("run_id")),
                           ("openworker.automation.trigger", auto.get("trigger"))):
            if value:
                root_attrs[key] = value
        if team.get("team_id"):
            root_attrs.setdefault("openworker.team.id", team["team_id"])
        woken = turn.get("woken_by") or {}
        if isinstance(woken, dict):
            if woken.get("team_id"):
                root_attrs["openworker.team.id"] = woken["team_id"]
            if woken.get("lead_session_id"):
                root_attrs["openworker.lead.session.id"] = woken["lead_session_id"]
        if sw.get("names") and session_title:
            root_attrs["openworker.session.title"] = masker.clean(session_title)
        if lf:
            root_attrs.update({"langfuse.observation.type": "agent", "langfuse.trace.name": "invoke_agent coworker"})
            if usage["unreported_calls"] or usage["failed_calls"]:
                root_attrs["langfuse.trace.tags"] = ["usage-incomplete"]
            if sw.get("prompts") and first_user_text:
                text = first_user_text if sw.get("context") else cut_context(first_user_text)
                root_attrs["langfuse.trace.input"] = root_attrs["langfuse.observation.input"] = masker.clean(text)
            if sw.get("responses") and last_reply_text:
                root_attrs["langfuse.trace.output"] = root_attrs["langfuse.observation.output"] = masker.clean(last_reply_text)
        events = [{"name": f"openworker.notice.{s.get('name')}", "at": s.get("started_at") or turn["started_at"],
                   "attrs": {"openworker.step.id": s["step_id"]}}
                  for s in sorted(steps, key=lambda s: s.get("seq") or 0) if s.get("kind") == "notice" and not _is_gap(s)]
        spans.insert(0, {
            "_mark": tid, "_notices": [s["step_id"] for s in steps if s.get("kind") == "notice" and not _is_gap(s)],
            "trace_id": trace, "span_id": root_id, "parent_span_id": None,
            "name": "invoke_agent coworker", "kind": SPAN_INTERNAL, "start_ms": turn["started_at"],
            "end_ms": end_ms, "attrs": root_attrs, "events": events,
            "error": turn.get("status") if turn.get("status") == "error" else None,
        })
    return spans


# -- feedback (1.3, E27b, TD3-10) ---------------------------------------------------------------
FEEDBACK_SCORE = "user_feedback"


def feedback_id(turn_id: str) -> str:
    """The fixed id of a turn's rating, so a changed rating replaces the score (or span)."""
    return _hex(f"feedback|{turn_id}", 32)


def feedback_span(fb: dict[str, Any], *, sw: dict[str, bool], masker: Masker) -> dict[str, Any]:
    """OTLP: one small span `openworker.feedback` in the turn's trace, under its root span,
    with the fixed id. The note only with "Your messages and the AI's answers" on (TD3-11),
    masked and cut (rule R4)."""
    at = fb.get("changed_at") or fb["rated_at"]
    attrs: dict[str, Any] = {"openworker.feedback.rating": fb["rating"],
                             "openworker.turn.id": fb["turn_id"], "openworker.session.id": fb["session_id"]}
    if fb.get("reasons"):
        attrs["openworker.feedback.reasons"] = list(fb["reasons"])
    note = (fb.get("content") or {}).get("note")
    if note and sw.get("prompts"):
        attrs["openworker.feedback.note"] = cut(masker.clean(note))
    return {"trace_id": trace_id(fb["turn_id"]), "span_id": feedback_id(fb["turn_id"])[:16],
            "parent_span_id": root_span_id(fb["turn_id"]), "name": "openworker.feedback",
            "kind": SPAN_INTERNAL, "start_ms": at, "end_ms": at, "attrs": attrs, "events": [], "error": None}


def langfuse_score(fb: dict[str, Any], *, sw: dict[str, bool], masker: Masker) -> dict[str, Any]:
    """Langfuse: a score through its scores API, `user_feedback` = 1 or -1 on the turn's
    trace, with a fixed id so a changed rating replaces it. Reasons in metadata; the note as
    the comment, only with capture.prompts on (TD3-11)."""
    body: dict[str, Any] = {"id": feedback_id(fb["turn_id"]), "traceId": trace_id(fb["turn_id"]),
                            "name": FEEDBACK_SCORE, "value": 1 if fb["rating"] == "up" else -1,
                            "dataType": "NUMERIC", "metadata": {"reasons": list(fb.get("reasons") or [])}}
    note = (fb.get("content") or {}).get("note")
    # Always sent, empty when there is no note to send: Langfuse merges a score sent again
    # under the same id, so a left-out comment would keep an earlier rating's note there.
    body["comment"] = cut(masker.clean(note)) if note and sw.get("prompts") else ""
    return body


# -- the made-up test recording (E9c) ------------------------------------------------------------
TEST_SESSION = "openworker-test"


def sample_spans(now_ms: int, dialect: str) -> list[dict[str, Any]]:
    """One trace with one model span and one tool span, fixed made-up values, tagged
    `openworker-test`. Nothing in it comes from a session."""
    turn_id = f"openworker-test-{now_ms}"
    turn = {"turn_id": turn_id, "session_id": TEST_SESSION, "seq": 1, "kind": "run", "trigger": "user",
            "status": "completed", "approval_mode": "ask", "attended": True,
            "started_at": now_ms - 1500, "duration_ms": 1500}
    steps = [
        {"step_id": f"{turn_id}-model", "turn_id": turn_id, "session_id": TEST_SESSION, "seq": 1,
         "kind": "model", "name": "model", "started_at": now_ms - 1400, "duration_ms": 900, "status": "ok",
         "attrs": {"model": "openworker:test-model", "provider": "openworker", "purpose": "main",
                   "stream": False, "finish_reason": "tool_calls",
                   "usage": {"reported": True, "input_fresh": 100, "cache_read": None, "cache_write": None,
                             "output": 10, "reasoning": None}}},
        {"step_id": f"{turn_id}-tool", "turn_id": turn_id, "session_id": TEST_SESSION, "seq": 2,
         "kind": "tool", "name": "test_tool", "call_id": "test-call", "started_at": now_ms - 400,
         "duration_ms": 200, "status": "ok", "attrs": {"result_bytes": 2}},
    ]
    sw = {k: False for k in SWITCHES}
    spans = build_turn_spans(turn, steps, sw=sw, dialect=dialect, get_piece=lambda _k: None, masker=Masker())
    if dialect == "langfuse":
        spans[0]["attrs"]["langfuse.trace.tags"] = [TEST_SESSION]
    return spans


# -- OTLP/HTTP JSON ------------------------------------------------------------------------------
def _value(v: Any) -> dict[str, Any]:
    if isinstance(v, bool):
        return {"boolValue": v}
    if isinstance(v, int):
        return {"intValue": str(v)}
    if isinstance(v, float):
        return {"doubleValue": v}
    if isinstance(v, (list, tuple)):
        return {"arrayValue": {"values": [_value(x) for x in v]}}
    return {"stringValue": str(v)}


def _attrs(d: dict[str, Any]) -> list[dict[str, Any]]:
    return [{"key": k, "value": _value(v)} for k, v in d.items() if v is not None]


def _ns(ms: int) -> str:
    return str(int(ms) * 1_000_000)


def resource_attrs(*, app_version: str, machine_name: Optional[str] = None) -> dict[str, Any]:
    out = {"service.name": SERVICE_NAME, "service.version": app_version or "unknown",
           "openworker.export.schema": SCHEMA}
    if machine_name:  # only with capture.names
        out["host.name"] = machine_name
    return out


def encode_otlp(groups: list[tuple[dict[str, Any], list[dict[str, Any]]]]) -> dict[str, Any]:
    """`[(resource attributes, spans)]` -> the OTLP/HTTP JSON body."""
    out = []
    for resource, spans in groups:
        enc = []
        for s in spans:
            span = {
                "traceId": s["trace_id"], "spanId": s["span_id"], "name": s["name"], "kind": s["kind"],
                "startTimeUnixNano": _ns(s["start_ms"]), "endTimeUnixNano": _ns(s["end_ms"]),
                "attributes": _attrs(s["attrs"]),
                "events": [{"timeUnixNano": _ns(e["at"]), "name": e["name"], "attributes": _attrs(e["attrs"])}
                           for e in s.get("events") or []],
            }
            if s.get("parent_span_id"):
                span["parentSpanId"] = s["parent_span_id"]
            if s.get("error"):
                span["status"] = {"code": STATUS_ERROR, "message": s["error"]}
            enc.append(span)
        out.append({"resource": {"attributes": _attrs(resource)},
                    "scopeSpans": [{"scope": {"name": SCOPE_NAME, "version": ATTRIBUTES_VERSION}, "spans": enc}]})
    return {"resourceSpans": out}