loopview 0.1.0__py3-none-any.whl

loopview/normalize/adapters/openinference.py

@@ -0,0 +1,367 @@
+"""Adapter for OpenInference (Arize) semantic conventions.
+
+Written against the spec in Arize-ai/openinference (spec/semantic_conventions.md)
+as emitted by openinference-instrumentation-langchain 0.1.76 and
+openinference-semantic-conventions 0.1.39. The spec itself has no version number.
+
+A span is OpenInference if it has openinference.span.kind.
+
+LangGraph: the LangChain instrumentor copies LangGraph's run metadata into the
+`metadata` attribute. That is how we tell a real graph node (langgraph_node ==
+span name) from plumbing inside a node, such as a routing function or an output
+parser (langgraph_node != span name), which we keep but hide.
+"""
+
+import re
+from typing import Any
+
+from loopview.ingest.raw import RawSpan
+from loopview.normalize.adapters.base import (
+    Classification,
+    ParentHint,
+    as_int,
+    maybe_json,
+)
+from loopview.normalize.schema import Message, MessagePart, ModelCall, ToolCall, Usage
+
+TOOL_LIKE_KINDS = {
+    "TOOL": "tool",
+    "RETRIEVER": "retriever",
+    "EMBEDDING": "embedding",
+    "RERANKER": "reranker",
+}
+
+
+class OpenInferenceAdapter:
+    name = "openinference"
+
+    def matches(self, span: RawSpan) -> bool:
+        return "openinference.span.kind" in span.attributes
+
+    def classify(self, span: RawSpan) -> Classification:
+        attrs = span.attributes
+        kind = str(attrs["openinference.span.kind"]).upper()
+        io = {
+            "input": maybe_json(attrs.get("input.value")),
+            "output": maybe_json(attrs.get("output.value")),
+        }
+
+        if kind == "LLM":
+            model = attrs.get("llm.model_name") or span.name
+            return Classification("model_call", str(model), "llm", model=_model_call(attrs))
+        if kind in TOOL_LIKE_KINDS:
+            name = attrs.get("tool.name") or span.name
+            return Classification(
+                "tool_call",
+                str(name),
+                TOOL_LIKE_KINDS[kind],
+                tool=ToolCall(
+                    name=str(name),
+                    call_id=attrs.get("tool_call.id"),
+                    arguments=io["input"],
+                    result=_unwrap_tool_output(io["output"]),
+                ),
+            )
+        if kind == "PROMPT":
+            return Classification("node", span.name, "prompt", hidden=True, **io)
+        if kind in ("GUARDRAIL", "EVALUATOR"):
+            return Classification("node", span.name, kind.lower(), **io)
+
+        # CHAIN and AGENT: graphs, graph nodes, chains, agents.
+        metadata = _metadata(attrs)
+        graph_node = metadata.get("langgraph_node")
+        if graph_node is None and metadata.get("ls_integration") == "langgraph":
+            return Classification("agent", span.name, "graph", **io)  # a compiled graph
+        if graph_node is not None and graph_node != span.name:
+            return Classification("node", span.name, "internal", hidden=True, **io)
+        if graph_node == span.name:
+            # A real node. If a subgraph runs inside it, the subgraph's own span has
+            # the same name and sits directly under it: collapse the two.
+            return Classification("node", span.name, "node", collapse_into_parent=True, **io)
+        if kind == "AGENT":
+            # graph.node.id is the agent's own name where the span name is a method
+            # (CrewAI: "Weather assistant._execute_core").
+            name = attrs.get("agent.name") or attrs.get("graph.node.id") or _readable(span.name)
+            return Classification("agent", str(name), "agent", **io)
+        # A chain directly inside a span of the same name is the same step recorded
+        # twice (the OpenAI Agents SDK wraps its "Agent workflow" AGENT in a CHAIN).
+        return Classification(
+            "node", _readable(span.name), "chain", collapse_into_parent=True, **io
+        )
+
+    def infer_parent(self, span: RawSpan) -> ParentHint | None:
+        metadata = _metadata(span.attributes)
+        graph_node = metadata.get("langgraph_node")
+        if graph_node is None:
+            return None
+        if graph_node != span.name:
+            return ParentHint(str(graph_node), "node", "node")  # plumbing inside a node
+        # A node inside a subgraph: the namespace is "outer:<id>|inner:<id>".
+        namespace = str(metadata.get("langgraph_checkpoint_ns", "")).split("|")
+        if len(namespace) > 1:
+            return ParentHint(namespace[-2].split(":")[0], "agent", "graph")
+        return None
+
+
+_UUID_IN_NAME = re.compile(
+    r"[_-]?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
+)
+
+
+def _readable(name: str) -> str:
+    """A span name without the run's UUID in it (CrewAI: "Crew_<uuid>.kickoff")."""
+    return _UUID_IN_NAME.sub("", name) or name
+
+
+def _metadata(attrs: dict[str, Any]) -> dict[str, Any]:
+    value = maybe_json(attrs.get("metadata"))
+    return value if isinstance(value, dict) else {}
+
+
+def _unwrap_tool_output(value: Any) -> Any:
+    """LangChain serialises a tool result as a ToolMessage; show just its content."""
+    if (
+        isinstance(value, dict)
+        and value.get("type") == "tool"
+        and isinstance(value.get("data"), dict)
+    ):
+        return maybe_json(value["data"].get("content"))
+    return value
+
+
+def _model_call(attrs: dict[str, Any]) -> ModelCall:
+    output = _messages(attrs, "llm.output_messages.")
+    reasoning = _reasoning_from_raw_output(attrs.get("output.value"))
+    if reasoning:
+        if not output:
+            output = [Message(role="assistant", parts=[])]
+        output[0].parts[:0] = [MessagePart(type="reasoning", text=r) for r in reasoning]
+    inputs = _messages(attrs, "llm.input_messages.")
+    _add_raw_tool_results(inputs, attrs.get("input.value"))
+    return ModelCall(
+        provider=attrs.get("llm.provider") or attrs.get("llm.system"),
+        model=attrs.get("llm.model_name"),
+        input=inputs,
+        output=output,
+        tool_definitions=_tool_definitions(attrs),
+        usage=_usage(attrs),
+    )
+
+
+def _tool_definitions(attrs: dict[str, Any]) -> list[Any]:
+    """llm.tools.N.tool.json_schema, in order."""
+    return [
+        maybe_json(t.get("tool.json_schema"))
+        for t in _group_by_index(attrs, "llm.tools.")
+        if t.get("tool.json_schema") is not None
+    ]
+
+
+def _usage(attrs: dict[str, Any]) -> Usage | None:
+    """Token counts from the spec's attributes, completed from the raw output.
+
+    The instrumentor leaves out cache attributes that are zero, and doesn't copy
+    reasoning (thinking) tokens into an attribute at all. Both are in the raw
+    output it also records, as LangChain's usage_metadata."""
+    raw = _raw_usage(attrs.get("output.value"))
+    usage = Usage(
+        input_tokens=as_int(attrs.get("llm.token_count.prompt")),
+        output_tokens=as_int(attrs.get("llm.token_count.completion")),
+        cache_read_tokens=_first(
+            attrs.get("llm.token_count.prompt_details.cache_read"), raw.get("cache_read")
+        ),
+        cache_write_tokens=_first(
+            attrs.get("llm.token_count.prompt_details.cache_write"), raw.get("cache_write")
+        ),
+        reasoning_tokens=_first(
+            attrs.get("llm.token_count.completion_details.reasoning"), raw.get("reasoning")
+        ),
+    )
+    return usage if usage.model_dump(exclude_none=True) else None
+
+
+def _first(*values: Any) -> int | None:
+    for value in values:
+        if as_int(value) is not None:
+            return as_int(value)
+    return None
+
+
+def _raw_usage(raw: Any) -> dict[str, int]:
+    """Cache and reasoning counts from LangChain's usage_metadata in the raw output:
+    {"input_token_details": {"cache_read", "cache_creation", "ephemeral_5m_input_tokens",
+    "ephemeral_1h_input_tokens"}, "output_token_details": {"reasoning"}}.
+
+    LangChain's cache_creation can read 0 while the per-lifetime counts
+    (ephemeral_5m / ephemeral_1h) hold the cache writes, so the larger wins."""
+    found: dict[str, int] = {}
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            meta = node.get("usage_metadata")
+            if isinstance(meta, dict):
+                inputs = meta.get("input_token_details") or {}
+                outputs = meta.get("output_token_details") or {}
+                if "cache_read" in inputs:
+                    found["cache_read"] = as_int(inputs["cache_read"]) or 0
+                writes = [
+                    as_int(inputs.get(k))
+                    for k in (
+                        "cache_creation",
+                        "ephemeral_5m_input_tokens",
+                        "ephemeral_1h_input_tokens",
+                    )
+                ]
+                if any(w is not None for w in writes):
+                    found["cache_write"] = max(writes[0] or 0, (writes[1] or 0) + (writes[2] or 0))
+                if "reasoning" in outputs:
+                    found["reasoning"] = as_int(outputs["reasoning"]) or 0
+                return
+            for value in node.values():
+                walk(value)
+        elif isinstance(node, list):
+            for value in node:
+                walk(value)
+
+    walk(maybe_json(raw))
+    return found
+
+
+def _reasoning_from_raw_output(raw: Any) -> list[str]:
+    """Thinking text from the raw model output.
+
+    The flattened llm.output_messages attributes drop thinking blocks, but the
+    instrumentor also records the raw output (output.value), where the model's
+    content blocks are kept, e.g. LangChain's {"type": "thinking", "thinking": ...}.
+    We look for such blocks anywhere in it rather than depend on one exact layout.
+    """
+    found: list[str] = []
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            kind = node.get("type")
+            if kind in ("thinking", "reasoning"):
+                text = node.get("thinking") or node.get("reasoning") or node.get("text")
+                if isinstance(text, str) and text.strip():
+                    found.append(text)
+                    return
+            for value in node.values():
+                walk(value)
+        elif isinstance(node, list):
+            for value in node:
+                walk(value)
+
+    walk(maybe_json(raw))
+    # A generation can repeat the same message in several places; keep each once.
+    return list(dict.fromkeys(found))
+
+
+# --- flattened messages ------------------------------------------------------------
+# OpenInference flattens lists into indexed keys, for example:
+#   llm.input_messages.2.message.role = assistant
+#   llm.input_messages.2.message.contents.0.message_content.text = ...
+#   llm.input_messages.2.message.tool_calls.0.tool_call.function.name = weekday
+#   llm.input_messages.3.message.tool_call_id = toolu_...
+
+_INDEXED = re.compile(r"^(\d+)\.(.+)$")
+
+
+def _group_by_index(flat: dict[str, Any], prefix: str) -> list[dict[str, Any]]:
+    """{prefix}N.rest = v  ->  [ {rest: v}, ... ] ordered by N."""
+    groups: dict[int, dict[str, Any]] = {}
+    for key, value in flat.items():
+        if not key.startswith(prefix):
+            continue
+        match = _INDEXED.match(key[len(prefix) :])
+        if match:
+            groups.setdefault(int(match.group(1)), {})[match.group(2)] = value
+    return [groups[i] for i in sorted(groups)]
+
+
+def _messages(attrs: dict[str, Any], prefix: str) -> list[Message]:
+    messages = []
+    for m in _group_by_index(attrs, prefix):
+        parts: list[MessagePart] = []
+        if m.get("message.content"):
+            text = str(m["message.content"])
+            # A tool result: role "tool" (OpenAI), or any message answering a tool
+            # call (Anthropic sends results in a "user" message).
+            if m.get("message.role") == "tool" or m.get("message.tool_call_id"):
+                parts.append(
+                    MessagePart(
+                        type="tool_result",
+                        id=m.get("message.tool_call_id"),
+                        result=maybe_json(text),
+                    )
+                )
+            else:
+                parts.append(MessagePart(type="text", text=text))
+        for c in _group_by_index(m, "message.contents."):
+            kind = c.get("message_content.type", "text")
+            if kind == "text":
+                parts.append(MessagePart(type="text", text=str(c.get("message_content.text", ""))))
+            elif kind == "tool_use":
+                continue  # the same call is also under message.tool_calls
+            else:
+                parts.append(MessagePart(type="other", name=c.get("message_content.type")))
+        for tc in _group_by_index(m, "message.tool_calls."):
+            parts.append(
+                MessagePart(
+                    type="tool_call",
+                    id=tc.get("tool_call.id"),
+                    name=tc.get("tool_call.function.name"),
+                    arguments=maybe_json(tc.get("tool_call.function.arguments")),
+                )
+            )
+        messages.append(Message(role=str(m.get("message.role", "unknown")), parts=parts))
+    return messages
+
+
+def _add_raw_tool_results(inputs: list[Message], raw: Any) -> None:
+    """Tool results from the raw request (input.value), which the flattened messages
+    can lose: OpenInference's Anthropic instrumentation keeps only one tool result per
+    message, and drops Anthropic's is_error flag. Results already present get the
+    flag; missing ones are added to the message holding the other results."""
+    found: dict[str, tuple[Any, bool | None]] = {}
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            if node.get("type") == "tool_result" and node.get("tool_use_id"):
+                flag = node.get("is_error")
+                found[str(node["tool_use_id"])] = (
+                    _tool_result_content(node.get("content")),
+                    flag if isinstance(flag, bool) else None,
+                )
+                return
+            for value in node.values():
+                walk(value)
+        elif isinstance(node, list):
+            for value in node:
+                walk(value)
+
+    walk(maybe_json(raw))
+    if not found:
+        return
+    present = {p.id: p for m in inputs for p in m.parts if p.type == "tool_result" and p.id}
+    for call_id, (content, flag) in found.items():
+        if call_id in present:
+            present[call_id].is_error = flag
+            continue
+        # The message answering the previous calls, or a new one at the end.
+        holder = next(
+            (m for m in reversed(inputs) if any(p.type == "tool_result" for p in m.parts)), None
+        )
+        if holder is None:
+            holder = Message(role="user", parts=[])
+            inputs.append(holder)
+        holder.parts.append(
+            MessagePart(type="tool_result", id=call_id, result=content, is_error=flag)
+        )
+
+
+def _tool_result_content(content: Any) -> Any:
+    """Anthropic's tool_result content: a string, or text blocks."""
+    if isinstance(content, list):
+        texts = [c.get("text") for c in content if isinstance(c, dict) and c.get("text")]
+        content = "\n".join(texts) if texts else content
+    return maybe_json(content)

loopview/normalize/derived_tools.py

@@ -0,0 +1,90 @@
+"""Tool calls rebuilt from the conversation, when no span records them.
+
+Instrumenting a model SDK (OpenAI, Anthropic, through OpenInference, OpenLLMetry or
+OpenTelemetry's own packages) records model calls only: the tools are the user's
+own functions, and nothing traces them. The conversation still says what happened.
+A model call's output asks for tools (`tool_call` parts: id, name, arguments), and
+the next model call's input carries their results (`tool_result` parts, same id).
+
+So when a run has no tool call spans at all, each requested tool becomes a tool
+call step, marked `synthetic`:
+- name and arguments: from the request;
+- result: from the next model call in the same scope that answers it;
+- start: when the requesting call ended; end: when the answering call started (the
+  tool ran somewhere in between; the exact time isn't known). With no answer in
+  the run, it lasts no time and has no result;
+- failed: only when the result is flagged as an error (Anthropic's `is_error`).
+  The OpenAI API has no such flag, and errors are never guessed from text
+  (DECISIONS D44), so there it stays "ok".
+
+Runs with any tool call span are left alone: their tools are recorded for real
+(by a framework, or loopview_sdk.tool). A request with no span there is deliberate,
+not lost: structured output, for instance, is a tool call that is never run (the
+flagship's `Plan`). So decorate all of a loop's tools with loopview_sdk.tool, or none.
+"""
+
+from loopview.normalize.schema import MessagePart, Step, ToolCall
+
+
+def derive_tool_calls(steps: list[Step]) -> list[Step]:
+    if any(s.kind == "tool_call" and not s.synthetic for s in steps):
+        return steps
+    by_scope: dict[str | None, list[Step]] = {}
+    for s in steps:
+        if s.kind == "model_call" and not s.hidden and s.model is not None:
+            by_scope.setdefault(s.scope_id, []).append(s)
+
+    derived: list[Step] = []
+    for calls in by_scope.values():
+        calls.sort(key=lambda s: (s.start_ns, s.id))
+        for i, call in enumerate(calls):
+            requests = [p for m in call.model.output for p in m.parts if p.type == "tool_call"]  # type: ignore[union-attr]
+            if not requests or call.end_ns is None:
+                continue
+            later = calls[i + 1 :]
+            for n, request in enumerate(requests):
+                answer, result = _answer(request, later)
+                end = answer.start_ns if answer is not None else call.end_ns
+                derived.append(
+                    Step(
+                        id=f"{call.id}~tool{n}",
+                        run_id=call.run_id,
+                        parent_id=call.scope_id,
+                        scope_id=call.scope_id,
+                        kind="tool_call",
+                        type_label="tool",
+                        name=request.name or "tool",
+                        key="",  # set when keys are built (loop_nodes._rekey)
+                        status="error" if result is not None and result.is_error else "ok",
+                        start_ns=call.end_ns,
+                        end_ns=max(end, call.end_ns),
+                        error=_error_text(result),
+                        tool=ToolCall(
+                            name=request.name or "tool",
+                            call_id=request.id,
+                            arguments=request.arguments,
+                            result=result.result if result is not None else None,
+                        ),
+                        convention=call.convention,
+                        synthetic=True,
+                    )
+                )
+    if not derived:
+        return steps
+    return sorted(steps + derived, key=lambda s: (s.start_ns, s.id))
+
+
+def _answer(request: MessagePart, later: list[Step]) -> tuple[Step | None, MessagePart | None]:
+    """The first later model call whose input carries this request's result."""
+    for call in later:
+        for message in call.model.input:  # type: ignore[union-attr]
+            for part in message.parts:
+                if part.type == "tool_result" and request.id and part.id == request.id:
+                    return call, part
+    return None, None
+
+
+def _error_text(result: MessagePart | None) -> str | None:
+    if result is None or not result.is_error:
+        return None
+    return result.result if isinstance(result.result, str) else "tool error"

loopview/normalize/loop_nodes.py

@@ -0,0 +1,193 @@
+"""Give a flat agent loop the shape of a graph: a `model` node and a `tools` node.
+
+LangGraph records a span per graph node, so its agents arrive as `model` and
+`tools` nodes with the calls inside them, and the graph shows the loop. The GenAI
+conventions (Pydantic AI, the Anthropic and OpenAI SDKs, hand instrumented code)
+record only `invoke_agent` with `chat` and `execute_tool` spans directly under it:
+no span says "this is the model step" or "this is the tools step". Drawn as is,
+such an agent is one card holding every call.
+
+For an agent with tool calls directly inside it, this pass adds the steps the
+convention leaves out, marked `synthetic`:
+- one `model` step per model call, wrapping it;
+- one `tools` step per turn, wrapping the tool calls that model call asked for.
+  A tool call belongs to the agent's latest model call that had ended when the
+  tool started (compared with ends, so tied timestamps work, DECISIONS D17).
+
+The usual transition rule then draws model -> tools -> model, with a loop counter.
+A flow step started by a tool (a sub-agent run by `gather_facts`) moves inside
+that turn's `tools` step, which then becomes a group. Agents without direct tool
+calls are left alone: with only model calls there is no loop to show.
+
+Two more cases from hand-written loops:
+- calls with no flow step around them at all (a model SDK instrumented, nothing
+  wrapping the loop) get a synthetic agent, named after the service, so the run
+  has something to draw;
+- a plain step that isn't an agent (a generic span such as `main`, or a chain)
+  holding both model and tool calls directly is treated as the agent of its loop.
+"""
+
+from loopview.normalize.schema import FLOW_KINDS, Step, StepStatus
+
+CALL_KINDS = ("model_call", "tool_call")
+
+
+def add_loop_nodes(steps: list[Step], root_name: str = "agent") -> list[Step]:
+    steps = _wrap_unowned_calls(steps, root_name)
+    by_id = {s.id: s for s in steps}
+    direct: dict[str, list[Step]] = {}  # owner id -> its visible direct calls
+    for s in steps:
+        owner = by_id.get(s.scope_id) if s.scope_id else None
+        if owner and not s.hidden and s.kind in CALL_KINDS:
+            direct.setdefault(owner.id, []).append(s)
+    for owner_id in list(direct):
+        owner = by_id[owner_id]
+        models = sum(1 for c in direct[owner_id] if c.kind == "model_call")
+        tools = len(direct[owner_id]) - models
+        # An agent's loop, or another step running a whole loop by itself: several
+        # model calls and tools. One model call and its tools is a single turn
+        # (the OpenAI Agents SDK's `turn` nodes), already drawn as a step.
+        if owner.kind != "agent" and not (models >= 2 and tools >= 1):
+            del direct[owner_id]
+
+    added: list[Step] = []
+    new_scope: dict[str, str] = {}  # call id -> the synthetic step that now holds it
+    for agent_id, calls in direct.items():
+        if not any(c.kind == "tool_call" for c in calls):
+            continue
+        agent = by_id[agent_id]
+        if agent.kind != "agent":
+            agent.kind = "agent"  # it holds its loop's nodes now: a group
+        models = sorted((c for c in calls if c.kind == "model_call"), key=_order)
+        for m in models:
+            step = _synthetic(agent, f"{m.id}~model", "model", [m])
+            added.append(step)
+            new_scope[m.id] = step.id
+        turns: dict[int, list[Step]] = {}
+        for t in sorted((c for c in calls if c.kind == "tool_call"), key=_order):
+            turns.setdefault(_turn_of(t, models), []).append(t)
+        for index, tools in turns.items():
+            step_id = f"{models[index].id}~tools" if index >= 0 else f"{agent.id}~tools"
+            step = _synthetic(agent, step_id, "tools", tools)
+            added.append(step)
+            for t in tools:
+                new_scope[t.id] = step.id
+
+    if not added:
+        if any(not s.key for s in steps):
+            _rekey(steps, by_id)  # tool calls rebuilt from messages have no key yet
+        return steps
+    all_steps = steps + added
+    by_id.update({s.id: s for s in added})
+
+    # Move the calls, and everything that happened inside them, into their new step.
+    for s in steps:
+        if s.id in new_scope:
+            s.parent_id = s.scope_id = new_scope[s.id]
+            continue
+        inside = _enclosing_call(s, by_id, new_scope)
+        if inside is not None:
+            s.scope_id = new_scope[inside]
+
+    # A tools step that now holds flow steps (sub-agents) is a group.
+    for s in all_steps:
+        if s.kind in FLOW_KINDS and not s.hidden and s.scope_id:
+            holder = by_id[s.scope_id]
+            if holder.synthetic and holder.kind == "node":
+                holder.kind = "agent"
+
+    _rekey(all_steps, by_id)
+    all_steps.sort(key=_order)
+    return all_steps
+
+
+def _wrap_unowned_calls(steps: list[Step], root_name: str) -> list[Step]:
+    """Model and tool calls with no flow step around them get a synthetic agent."""
+    unowned = [s for s in steps if s.kind in CALL_KINDS and not s.hidden and s.scope_id is None]
+    if not unowned:
+        return steps
+    first = min(unowned, key=_order)
+    running = any(s.end_ns is None for s in unowned)
+    root = Step(
+        id=f"{first.run_id}~agent",
+        run_id=first.run_id,
+        parent_id=None,
+        scope_id=None,
+        kind="agent",
+        type_label="agent",
+        name=root_name,
+        key="",
+        status="running" if running else "ok",
+        start_ns=first.start_ns,
+        end_ns=None if running else max(s.end_ns or 0 for s in unowned),
+        convention=first.convention,
+        synthetic=True,
+    )
+    for s in unowned:
+        s.scope_id = root.id
+        if s.parent_id is None:
+            s.parent_id = root.id
+    return [root, *steps]
+
+
+def _order(s: Step) -> tuple[int, str]:
+    return (s.start_ns, s.id)
+
+
+def _turn_of(call: Step, models: list[Step]) -> int:
+    turn = -1
+    for i, m in enumerate(models):
+        if m.end_ns is not None and m.end_ns <= call.start_ns:
+            turn = i
+    return turn
+
+
+def _synthetic(agent: Step, step_id: str, name: str, inside: list[Step]) -> Step:
+    running = any(c.end_ns is None for c in inside)
+    status: StepStatus = "running" if running else "ok"
+    if name == "model" and not running:
+        status = inside[0].status
+    return Step(
+        id=step_id,
+        run_id=agent.run_id,
+        parent_id=agent.id,
+        scope_id=agent.id,
+        kind="node",
+        type_label=name,
+        name=name,
+        key="",  # set by _rekey
+        status=status,
+        start_ns=min(c.start_ns for c in inside),
+        end_ns=None if running else max(c.end_ns or 0 for c in inside),
+        convention=agent.convention,
+        synthetic=True,
+    )
+
+
+def _enclosing_call(s: Step, by_id: dict[str, Step], moved: dict[str, str]) -> str | None:
+    """The moved call that `s` happened inside, if any (walking visible parents)."""
+    parent_id = s.parent_id
+    while parent_id is not None and parent_id in by_id:
+        if parent_id in moved:
+            return parent_id
+        parent = by_id[parent_id]
+        if parent.kind in FLOW_KINDS:
+            return None  # another flow step owns it
+        parent_id = parent.parent_id
+    return None
+
+
+def _rekey(steps: list[Step], by_id: dict[str, Step]) -> None:
+    """Keys are the scope path plus the name, as the normalizer builds them; scopes
+    changed, so build them again."""
+    keys: dict[str, str] = {}
+
+    def key_of(step: Step) -> str:
+        if step.id not in keys:
+            name = step.name if step.kind in FLOW_KINDS else f"{step.kind}:{step.name}"
+            scope = by_id.get(step.scope_id) if step.scope_id else None
+            keys[step.id] = f"{key_of(scope)}/{name}" if scope else name
+        return keys[step.id]
+
+    for s in steps:
+        s.key = key_of(s)